FogBUGZ 3.0 Setup

By Joel Spolsky
Saturday, August 24, 2002

FogBUGZ 3.0 Setup Spec

FogBUGZ setup does not use InnoSetup.

This is because InnoSetup cannot run custom code before it starts unpacking files. We need to determine whether the user is upgrading or not, and query IIS for the location to unpack files, before we begin.

We do not use Wise or InstallShield because they are pain-in-the-ass install systems with bizarro custom scripting languages that literally do not do half of what we need to do. We do not use Windows Installer because it is even more of a pain in the ass, and it's a pain for our customers, too, and it does not do literally half of what we need to do.

Instead it uses a custom VC++ 6.0 MFC application. This will run on all our target machines. All of our files are stored in a CAB which itself is stored as a resource in SETUP.EXE. We use SETUP API functions to extract files as needed.

A lot of the code for setting up FogBUGZ already exists in MFC form in setupetc.

FogBUGZ Setup is a wizard application with a lot of screens asking the user a lot of questions and probing the system to make sure things are working and that the user's information is correct. At various pages in the wizard, we actually make changes to the user's system. Each of these changes is reversable. If you back up through the wizard, we actually reverse the changes you've made. So for example in the step where we create a new NT account for FogBUGZ, if you get past this successfully but then hit BACK, we delete the account that we just created. If you back up all the way, your system will be unchanged. If you cancel at any point, we roll back all changes that have been made to the system. When you click Finish certain rollback information is discarded.

0. Check System Requirements

This is done before the wizard comes up. If anything is missing, we display a MessageBox.

• Check the OS version matches our requirements (including service packs). NT 4.0 SP6a, NT 2000, XP Professional, or .NET Server. If not found:

FogBUGZ requires one of the following operating systems:

• Windows NT 4.0 with Service Pack 6a Installed
• Windows 2000
• Windows XP Professional
• Windows .NET Server

• Check that a reasonable version of IIS is on this machine. We'll just check the version of IISADMIN.DLL from \winnt\system32\inetsrv folder.
• Check the MDAC version. See http://www.microsoft.com/data/MDAC21info/MDACinstQ.htm for how. If the version is not high enough, show the user where to get it from Microsoft and exit.
• Check the VBScript version by checking vbscript.dll in Winnt\System32. If the version is not high enough, show the user where to get it from Microsoft and exit.
• Check that the logged-on user is an administrator, if not, warn them that things may go wrong but do allow them to continue. To check see Q118626.

NO ACTIONS

1. OK the license agreement.

Welcome to FogBUGZ. Please read the following license agreement and check "I agree" to continue.

NO ACTIONS

2. Upgrade or New Install?

Would you like to
[] Create a new FogBUGZ 3.0 installation
[] Upgrade an existing installation of FogBUGZ to version 3.0
----URL of previous FogBUGZ installation: [dropdown listing all found IIS URLs containing FogBUGZ]

To initialize this dialog:

• enumerate all IIS virtual directories, and the top level IIS web site, and any other web sites on an advanced server. Get the URL, virtual name and path of each of them.
• Look in the directories to see if there are any files that would indicate a FogBUGZ installation (any version).
• If found, default to upgrade and fill in the URL. If not found, default to Install. When install is checked, the URL dropdown is greyed out.
• If there are no IIS directories that could contain FogBUGZ, skip this screen and go into new installation mode.

NO ACTIONS

3. Choose Directory

For upgraders, we figure this out by tracking down the URL in question in IIS and finding its source directory. If it's not on this machine, that's an error.

For new installation, prompt with this dialog:

Choose a directory for the FogBUGZ files (this will contain all web pages, source code, utilities, and any file attachments which are attached to bugs).

[ edit control with BROWSE button ]

If the directory does exist, it must be empty.

ACTION: The directory in question is created if it doesn't exist. This can be rolled back.

4. Choose URL

For upgraders, we know this and just move on.

For new installation, prompt with this dialog:

Install FogBUGZ as:

[x] A top level web site (that is, http://computername/). Choose this if there are no other web sites on this server.
[ ] A virtual directory (that is, http://computername/fogbugz). Choose this if there are other web sites on this server.
[ ] A virtual directory with another name http://computername/[    ].

Check that the directory they specified isn't already pointing somewhere. If it is, pop up a message: "(url) is currently pointing to (directory). If you continue, FogBUGZ Setup will change this URL to point to FogBUGZ. Continue?"

NO ACTION.

5. Account

This screen appears for everybody, even upgraders.

FogBUGZ needs a Windows user account to run under. We highly recommend creating an account just for FogBUGZ.

( ) Create a new account named [FogBUGZ] on computer/domain: [               ] 
    Password: [*********] Retype Password: [*********]

( ) Use the following existing account: [                ] 
    Password: [*********] Computer/Domain[           ]

If the user asks us to create an account, we do so with NetUserAdd.

If user supplies an existing account, we check the password on the spot using a function I got from MSDN.

The user needs to have "Logon as a Service" permission. (It may need other permissions, too.) Code for this is in MSKB Q132958.

If you are upgrading we detect the user account that FogBUGZ is configured to use in IIS and use that as the default; we still have to prompt for the password because we're going to need it later.

ACTION: Create new account if required; this can be rolled back.

ACTION: Grant Log on As Service Permission; this can be rolled back.

6. Database

For upgraders, we know this.

1.0 version database is upgraded to 2.0 using code from old setupetc.exe
2.0 is upgraded to 3.0 using code which is currently living in the ASP pages, but should be moved into SETUP.

database does not need to be upgraded; FogBUGZ itself does this from ASP pages. (what if Dispatcho tries to use it before it has been upgraded? Maybe we should move the upgrade back into setup.)

For new installation, prompt with this dialog:

Where should FogBUGZ store its data?

[x] In a Microsoft Access/Jet file.
[ ] Using Microsoft SQL Server 7.0 or 2000.

<Help me decide>

Help me decide brings up a window listing the pros 'n' cons.

NO ACTION.

6jet. If Access, check if Jet installed. If not, provide download instructions.

6sql. If SQL Server:

Choose a SQL server installation:

Server Name: [                                 ]

FogBUGZ Setup needs to log on to the SQL Server now as an administrator to set up its database.

[ ] Connect using NT Authentication. Choose this option if COMPUTER\user is a SQL Server administrator.

[ ] Connect using the following SQL Server account:

Username: [sa           ]
Password: [*******]

At this point we immediately try to connect. If the server is not found, you get an error message saying Unable to find SQL Server "BLAH". We also check that the server is at least version 7.0.

If we can connect, we check that we have administrative privileges. If you don't have privileges, you get an error saying:

COMPUTER\user does not have administrative privileges on the SQL Server SERVER.

or

joe does not have administrative privileges on the SQL Server SERVER.

A note about database upgrade issues:

• If they said they want to upgrade, fine, we just keep using their old database. No problem.
• If they said they want a fresh install, we create a new database. No problem there, either. We never ever replace an existing MDB file or SQL Server Database. If the name FogBUGZ isn't available we install FogBUGZ2, FogBUGZ3, etc.
• We used to ask people where they wanted their SQL Server data files. No more. They will go in a subdirectory of FogBUGZ.
• We no longer use ODBC, rather, we create an OLEDB connection string. The setup.asp page will have to be enhanced to display this nicely.

7. Hard Work Page

This is the page where we extract files and create the database. It shows a progress indicator for each step. Next and Back are disabled while it's working.

When you have finished, it clicks Next for you automatically.

In order to support Rollback, when you go Back to this page and the Rollback() function is called, the page changes to show you that rollback is happening. Then it clicks "Back" for you automatically which pulls you back into the database page.

If any error occurs on this page, the page changes to show the error, everything else is rolled back, and Next is no longer available. (Should we have a Retry button at this point? Need to think about what kind of errors might occur.)

There are three kinds of installations; each does things a little bit differently.

• Fresh Install
• 1.0/2.0 upgrade
• 3.0 reinstall

Fresh Install

1. Extract files to directory
2. Set permissions on files
3. Register COM controls
4. Create Database
5. Reasonable initial defaults for our registry settings
6. Create IIS Directory
7. Configure IIS options
8. Install and start Dispatcho service

Upgrade

1. Stop W3SVC
2. Stop Dispatcho if running
3. Rename old directories website.old and accessories.old
4. Extract files to directory
5. Copy old configure.asp back in
6. Copy old fileUploads back in
7. Upgrade database
8. Restart W3SVC
9. Install and start Dispatcho service

Files We Extract:

All of Accessories and Website
Dispatcho.exe will be built into Accessories

8. Done

The rest of FogBUGZ Setup is done over the Web. When you click "Finish", we'll launch your web browser.

The URL is http://www.example.com/fogbugz.

[x] Add an icon to the Start Menu
[ ] Add an icon on my desktop

 

Next we go to the Web Based Setup phase. A setting in the registry, SetupState, is set to 0. When default.asp loads, based on the current value of SetupState, it shows the appropriate page in the web setup sequence.

Page 0

Upgrades the database.

FogBUGZ Setup is upgrading your database.
Existing Database Version: 2.00
Upgrading To: 3.14

This is flushed right away. When the upgrade is done a [Next] button appears.

Page 1 - Email

This is done for upgraders and new installations. If you are installing FogBUGZ 3.0 over FogBUGZ 3.0, it should be prepopulated from intelligent places.

FogBUGZ needs its own email account to send notifications and receive replies. Please create an account on your email server and enter the details here.

Important All email sent to this account will be sucked into FogBUGZ. Do not use your own email address!

Email address: [                     ]
Logon user name: [                       ]
Password: [                          ]
Incoming POP3 Mail Server: [                          ]
Use SSL for secure POP3: [x]
Outgoing SMTP Mail Server: [                          ]
does Dart support logon to SMTP server and SSL SMTP server? If so we should consider this.
Click < Test > to test this account; FogBUGZ will send some email to itself and check that it arrives.

[ ] Disable all email in FogBUGZ.

You cannot hit next until you test the account, or choose Disable.

Page 3 - Licenses (all users, including upgrade)

Same as current license page.

Page 4 - Admin Account (if not already set up)

Question - can we just get rid of this and send email to all administrators?

 

 

ISSUES TBD

How do we detect and handle Norton?
See http://service2.symantec.com/SUPPORT/nav.nsf/pfdocs/2001032111331506