What Setup Does on Windows

This document describes the complete list of steps that the FogBugz Setup program takes to install FogBugz. It is intended to help you with troubleshooting, or for advanced system administrators who need to know what changes will be made to their system, or in unusual situations where you need to install something manually. But please do not try to install FogBugz manually. FogBugz Setup is very smart and only takes a couple of minutes. Doing this all by hand would take you hours and is bound to be frustrating.

FogBugz Setup is a self-contained, single executable file that installs everything you need to run FogBugz on a Windows server. It can be used to upgrade from any old version of FogBugz, from 2.0-6.0.

Setup is completely reversible until you get to the last screen and click Finish. If you cancel at any point in time all changes that were made before then are undone.

Setup never requires a reboot. While files are being copied, it temporarily stops three services:

1. W3SVC, the web server
2. CISVC, the Content Indexing Service
3. FogBugz's own Dispatcho or Maintentance service (during an upgrade)

This is to minimize the chances that any FogBugz files are in use while you run Setup and cannot be overwritten. If a file is still in use, Setup will simply not succeed and changes will be rolled back.

If you get errors when you run Setup: To force Setup to ignore certain errors and continue anyway, there are command line options.

Check System Requirements

The operating system is checked to make sure it is one of these:

• Windows 2000
• Windows XP Professional
• Windows 2003 Server
• Windows Vista 

Internet Information Services (IIS) is checked by checking if the file iisadmin.dll has major version 4 or later. If you have Windows NT 4.0 you will have to install the Windows Option Pack to get IIS 4.0. Fog Creek Software no longer supports Windows NT 4.0, and FogBugz has not been tested on that version of the operating system.  Note: if you do not have IIS, you will still be able to choose the "Just extract FogBugz files" install option described below.

MDAC (Microsoft Data Access) is checked to make sure that you have version 2.6 or later. You can download and install MDAC from Microsoft's web site.

VBScript is checked to make sure that it is version 5.6 or later. You can install Microsoft Windows Script from their web site.

Install Files

The Setup program offers an option that only extracts files without making any other changes. If all else fails you could choose this option to get the FogBugz files out and set everything up manually. You still have to pass the "system requirements checking" phase to get this far, but no changes are made to the system except for extracting files.

Files are extracted, by default, to  c:\Program Files\FogBugz, although you can use any directory on a locally attached hard drive, which must be formatted using NTFS. Do not use FAT drives, network attached storage (NAS) devices, or Linux/UNIX SAMBA shares, because they do not support user-level permissions on files.

FogBugz Setup creates two important subdirectories, Website and Accessories. Website contains the FogBugz source code itself, and it's the one that IIS will serve out. Accessories contains everything else that ships with FogBugz.

Create an Account

The FogBugz application will need a Windows account for its operations. This account will be used for the anonymous access account in IIS, for the FogBugz Maintenance Service, and will map to a login in SQL Server (if you use SQL Server). FogBugz Setup asks you if you want to use an existing account or have Setup create an account for this purpose. If you choose the latter, it will be named "FogBugz" unless you specify another name.

On Windows 2003, the FogBugz account is added to the IIS_WPG group.

See this knowledge base article at the Fog Creek website for complete instructions on granting user permissions and configuring IIS settings.

The FogBugz account is granted the following five user rights:

Adjust memory quotas for a process
Allow log on locally
Log on as a batch job
Log on as a service
Replace a process level token

If you are on a standalone server, these settings can be found in
Local Security Policies->Local Policies->User Rights Assignment.  If the FogBugz user is a domain account, ask your domain administrator to grant these privileges.

IIS Settings

• IIS 4 and 5
• IIS 6
• IIS 7 

Component Services

In the Component Services control panel, the process associated with FogBugz is set to run under the identity of the FogBugz account.

*Not needed on Windows Vista.

Open Port 80 in the Firewall

If you are running the Microsoft Firewall, which comes with Windows XP Service Pack 2 or later, and port 80 is blocked, Setup will create an exception in the firewall configuration to allow incoming connections on port 80, the port used for web access (HTTP).

Register OCX controls

All DLLs and OCX files in FogBugz\Accessories are registered. Run register.bat in the accessories folder to do this.

* Vista users will have to disable UAC before running this command.  It can be re-enabled after you have completed setup.

Initialize Registry Settings

In HKEY_LOCAL_MACHINE\SOFTWARE\Fog Creek Software\FogBugz, we create a key with the name of the FogBugz Website directory, with all backslashes changed to forward slashes, for example, c:/Program Files/FogBugz/website. If you have multiple FogBugz installations in different directories, each can have its own registry settings. In that key, we create the following default values, which are all strings (even the ones that look like numbers are strings.)

sRegistryVersion=4
sConnectionString=a valid OLE DB connection string to the FogBugz database
sURL=your FogBugz url (e.g., http://example.com/fogbugz)

Grant Permissions For the FogBugz Account

The account is granted permissions. The following permissions are granted, and all are set up to "inherit" to child containers.

• Full control of the FogBugz directory and all subdirectories.
• Full control of the registry key HKEY_LOCAL_MACHINE\SOFTWARE\Fog Creek Software\FogBugz

Create the Database

For SQL Server, a file in the Accessories directory called all.sql contains the SQL code that you need to create a blank FogBugz database. For MySQL there is a file called mysql.sql.

For Access, a file in the Accessories directory called FogBugz.MDB contains a blank FogBugz database. Simply copy this file.

SQL Server Permissions

We set up accounts and permissions inside SQL Server using integrated Windows security, so that the FogBugz account has full control over the FogBugz database.

If you are doing this manually: create a login in SQL Server. Make it a SQL Server login, not a Windows login. It just needs to be owner of the FogBugz database, nothing more than that. Then use this login in your connection string (specified in registry settings above) like so:  uid=newlogin; pwd=newpassword

Update the Database Schema

If you are doing a manual setup, you do not need to do anything here. When you bring up FogBugz in the browser, the ASP code will handle this. To find out what the setup program does, read on.

Whether you are upgrading or installing a new database for the first time, the database schema may be out of date. FogBugz Setup connects to the FogBugz installation over http and requests that the ASP code bring the database schema up to date, adding tables, columns, and indexes that have been added since the version of FogBugz that you currently have.

On a fresh install, the database starts out empty except for a tiny "version" table which indicates that the database is version 0. On an upgrade, you may have the current database schema, or you may have a schema from an earlier version of FogBugz.

Here's what Setup does:

• Connects to the URL setupUpgradeDB.asp?action=upgrade&sUpgradeKey=random string
• This URL attempts to upgrade the database to the latest version. If anything goes wrong, it rolls the database back to its previous state and returns a page of the form -|error message . If it is successful, it returns a page containing simply +|.
• If the rest of Setup succeededs, Setup connects to the URL setupUpgradeDB.asp?action=commit&sUpgradeKey=same random string to commit the changes.
• If the rest of Setup fails, Setup connects to the URL setupUpgradeDB.asp?action=rollback&sUpgradeKey=same random string to roll back the database to the previous version.

Until the database is brought up to date, anyone logging into FogBugz will see a message that FogBugz is down while it is being upgraded.

Install the FogBugz Search Tool

In the accessories folder is located an executable called SearchTool used for the new Lucene-based search engine in FogBugz 6. Running this executable will register the search COM objects and create a COM+ application for them.

To install SearchTool manually: In a command prompt, navigate to your FogBugz/accessories folder and type this at the command line:

searchtool.exe -r -u username -p password

Username is your FogBugz Windows account, and should look like DOMAIN\FogBugz.

FogBugz Maintenance Service

In the accessories folder is a Windows service called FogBugzMaint. SETUP installs and starts this service. It runs under the FogBugz account and is always running.

FogBugzMaint is used to perform maintenance tasks which need to be run even when nobody is using FogBugz such as nightly cleanup tasks and receiving incoming email. Whenever FogBugz has something to do which might take a while, like Bayesian filter training or sending an outgoing email, instead of doing it right away, it creates a maintenance task and waits for FogBugzMaint to wake up and do it. This ensures that the FogBugz user interface always responds quickly. Read more details about the FogBugz Maintenance Service.

To install FogBugzMaint manually: In a command prompt, navigate to your FogBugz/accessories folder and type this at the command line:

FogBugzMaint.exe install username password

Username is your FogBugz Windows account, and should look like DOMAIN\FogBugz.

Install Dart Control Licenses

In HKEY_LOCAL_MACHINE\SOFTWARE\Dart\PowerTCP\License, we create license keys.  If Dart, PowerTCP, or License are missing, create those keys.  Then, go to your Site configuration page in the FogBugz web interface and click OK without changing any settings.  This will create the necessary registry values under the License key.