Post-Installation Checklist

The Bugzilla Guide
Prev | Chapter 4. Administering Bugzilla | Next

# 4.1. Post-Installation Checklist

After installation, follow the checklist below to help ensure that you have a successful installation. If you do not see a recommended setting for a parameter, consider leaving it at the default while you perform your initial tests on your Bugzilla setup.

1. Bring up `editparams.cgi` in your web browser. This should be available as the "edit parameters" link from any Bugzilla screen once you have logged in.

2. The "maintainer" is the email address of the person responsible for maintaining this Bugzilla installation. The maintainer need not be a valid Bugzilla user. Error pages, error emails, and administrative mail will be sent with the maintainer as the return email address.

   Set "maintainer" to your email address. This allows Bugzilla's error messages to display your email address and allow people to contact you for help.

3. The "urlbase" parameter defines the fully qualified domain name and web server path to your Bugzilla installation.

   For example, if your bugzilla query page is http://www.foo.com/bugzilla/query.cgi, set your "urlbase" is http://www.foo.com/bugzilla/.

4. "usebuggroups" dictates whether or not to implement group-based security for Bugzilla. If set, Bugzilla bugs can have an associated groupmask defining which groups of users are allowed to see and edit the bug.

   Set "usebuggroups" to "on" only if you may wish to restrict access to products. I suggest leaving this parameter off while initially testing your Bugzilla.

5. "usebuggroupsentry", when set to "on", requires that all bugs have an associated groupmask when submitted. This parameter is made for those installations where product isolation is a necessity.

   Set "usebuggroupsentry" to "on" if you absolutely need to restrict access to bugs from the moment they are submitted through resolution. Once again, if you are simply testing your installation, I suggest against turning this parameter on; the strict security checking may stop you from being able to modify your new entries.

6. You run into an interesting problem when Bugzilla reaches a high level of continuous activity. MySQL supports only table-level write locking. What this means is that if someone needs to make a change to a bug, they will lock the entire table until the operation is complete. Locking for write also blocks reads until the write is complete. The "shadowdb" parameter was designed to get around this limitation. While only a single user is allowed to write to a table at a time, reads can continue unimpeded on a read-only shadow copy of the database. Although your database size will double, a shadow database can cause an enormous performance improvement when implemented on extremely high-traffic Bugzilla databases.

   Set "shadowdb" to "bug_shadowdb" if you will be running a *very* large installation of Bugzilla. The shadow database enables many simultaneous users to read and write to the database without interfering with one another.

   | Enabling "shadowdb" can adversely affect the stability of your installation of Bugzilla. You should regularly check that your database is in sync. It is often advisable to force a shadow database sync nightly via "cron".

   Once again, in testing you should avoid this option -- use it if or when you need to use it, and have repeatedly run into the problem it was designed to solve -- very long wait times while attempting to commit a change to the database. Mozilla.org began needing "shadowdb" when they reached around 40,000 Bugzilla users with several hundred Bugzilla bug changes and comments per day.

   If you use the "shadowdb" option, it is only natural that you should turn the "queryagainstshadowdb" option "On" as well. Otherwise you are replicating data into a shadow database for no reason!

7. "headerhtml", "footerhtml", "errorhtml", "bannerhtml", and "blurbhtml" are all templates which control display of headers, footers, errors, banners, and additional data. We could go into some detail regarding the usage of these, but it is really best just to monkey around with them a bit to see what they do. I strongly recommend you copy your `data/params` file somewhere safe before playing with these values, though. If they are changed dramatically, it may make it impossible for you to display Bugzilla pages to fix the problem until you have restored your `data/params` file.

   If you have custom logos or HTML you must put in place to fit within your site design guidelines, place the code in the "headerhtml", "footerhtml", "errorhtml", "bannerhtml", or "blurbhtml" text boxes.

   | The "headerhtml" text box is the HTML printed out before any other code on the page, except the CONTENT-TYPE header sent by the Bugzilla engine. If you have a special banner, put the code for it in "bannerhtml". You may want to leave these settings at the defaults initially.

8. "passwordmail" is rather simple. Every time a user creates an account, the text of this parameter is read as the text to send to the new user along with their password message.

   Add any text you wish to the "passwordmail" parameter box. For instance, many people choose to use this box to give a quick training blurb about how to use Bugzilla at your site.

9. "useqacontact" allows you to define an email address for each component, in addition to that of the default owner, who will be sent carbon copies of incoming bugs. The critical difference between a QA Contact and an Owner is that the QA Contact follows the component. If you reassign a bug from component A to component B, the QA Contact for that bug will change with the reassignment, regardless of owner.

   "usestatuswhiteboard" defines whether you wish to have a free-form, overwritable field associated with each bug. The advantage of the Status Whiteboard is that it can be deleted or modified with ease, and provides an easily-searchable field for indexing some bugs that have some trait in common. Many people will put "help wanted", "stalled", or "waiting on reply from somebody" messages into the Status Whiteboard field so those who peruse the bugs are aware of their status even more than that which can be indicated by the Resolution fields.

   Do you want to use the QA Contact ("useqacontact") and status whiteboard ("usestatuswhiteboard") fields? These fields are useful because they allow for more flexibility, particularly when you have an existing Quality Assurance and/or Release Engineering team, but they may not be needed for many smaller installations.

10. Set "whinedays" to the amount of days you want to let bugs go in the "New" or "Reopened" state before notifying people they have untouched new bugs. If you do not plan to use this feature, simply do not set up the whining cron job described in the installation instructions, or set this value to "0" (never whine).

11. "commenton" fields allow you to dictate what changes can pass without comment, and which must have a comment from the person who changed them. Often, administrators will allow users to add themselves to the CC list, accept bugs, or change the Status Whiteboard without adding a comment as to their reasons for the change, yet require that most other changes come with an explanation.

    Set the "commenton" options according to your site policy. It is a wise idea to require comments when users resolve, reassign, or reopen bugs at the very least.

    | It is generally far better to require a developer comment when resolving bugs than not. Few things are more annoying to bug database users than having a developer mark a bug "fixed" without any comment as to what the fix was (or even that it was truly fixed!)

12. The "supportwatchers" option can be an exceptionally powerful tool in the hands of a power Bugzilla user. By enabling this option, you allow users to receive email updates whenever other users receive email updates. This is, of course, subject to the groupset restrictions on the bug; if the "watcher" would not normally be allowed to view a bug, the watcher cannot get around the system by setting herself up to watch the bugs of someone with bugs outside her privileges. She would still only receive email updates for those bugs she could normally view.

    For Bugzilla sites which require strong inter-Product security to prevent snooping, watchers are not a good idea.

    However, for most sites you should set "supportwatchers" to "On". This feature is helpful for team leads to monitor progress in their respective areas, and can offer many other benefits, such as allowing a developer to pick up a former engineer's bugs without requiring her to change all the information in the bug.

Prev | Home | Next
Administering Bugzilla | Up | User Administration