First-time installation

AdvoKit runs on a web server with PHP and a MySQL database server. Before you can install or upgrade AdvoKit, you must have information for accessing the MySQL database; where the application files will go; and where the web root is found.

There are three steps that must be accomplished, in no particular order, before starting up the AdvoKit installer: Setting up a database; Figuring out where files will go; and installing the installer!

Database setup:

You will need to work with your hosting service or local system administrator to create a MySQL database that you have access to. To set up AdvoKit, you will need to know:

• the web address for the MySQL server
• the database name
• a valid user name and password on that MySQL server with privileges to create tables in that database.

 

File system setup:

Take a minute or two to understand the directory structure on your host machine. If you are installing on a remote server, use your FTP client to take a look at how the hosting service has organized your directories. Typically, in your top level directory or perhaps one level down, there is a folder called "public_html" or "htdocs" or some such, which is where your publicly accessible web pages are served from. This folder is known as the "web root". The advokit-installer will need to put some files under that directory. You can decide if you want AdvoKit to run directly from the web root, or from a folder somewhere under the web root, e.g. "../public_html/advokit".

Most of the AdvoKit files will be placed in a location that is NOT under the web root, so that prying eyes or mischief-makers cannot get into them. The most typical approach is to create a folder called "advokit" at the top level of your directory structure (above that web root) for the advokit-installer to use to place all the application files and private data files.

 

Getting ready to run the installer:  

The advokit-installer compressed archive will need to be decompressed and uploaded to your web server. Most efficient is to upload the archive to your server and then decompress it from the command line. If you do not have shell access, then decompress the archive on your PC (using e.g. WinZip), and then drag the advokit-installer folder to your web server using your FTP client. Make sure you place it under your web root, where it can be accessed by a web browser.

 

After you have decompressed and placed the advokit-installer folder under your web root, point your web browser to <your.domain>/advokit-installer.

Assuming this is a new installation, click on the button labeled "Install advokit, deleting any existing installation >"

 

Step 1: Entering database connection information

• Database Host: either localhost, if the database server is on the local machine, or the url to a MySQL server somewhere on the internet.
• Database Port: Usually 3306. If you don't know what to change it to, then probably it should be left alone.
• Database Name: this is the name of the database on the MySQL server where AdvoKit data will be stored. You must have an account (username and password) for this database. If you are using a web hosting service, this information would have been provided to you when you signed up for the database service.
• Database User: enter the username that you have been assigned to access this database. Note that this probably will not be the same as your other web host account usernames.
• Database Password: enter the password for access to this database account. Again, this usually will not be the same as you would use to access other parts of your internet service.

It doesn't hurt to select "transaction safe tables", though most MySQL servers do not support them.

• Table prefix: Since a given MySQL database may be holding data for a number of applications, it is generally best to give your AdvoKit tables a readily distinguished identifier. A typical strategy for someone just trying out AdvoKit is to create a test instance, and then when they have messed around and are comfortable, create a real production instance. Using a different table prefix for the test instance will ensure that you do not inadvertantly damage good data when you are learning to use AdvoKit.

At this point you can click "continue". If the database connection information was valid, then you will see a screen like this

Step 2: Database setup continued

If the database connection is successful, click "continue". If it was not successful, click "go back one step" and carefully check the information as entered.

 

Step 3: Database setup continued

Now a long list appears, showing what database tables the AdvoKit installer plans to create. If any of these tables already exist, they will be dropped, and any data in them will be lost permanently. If you are installing over a pre-existing AdvoKit database, that data will be lost.

If you are installing AdvoKit for the first time, you might want to choose to have some sample voter data installed. This loads a small voterfile that you can use while exploring your way around AdvoKit. If you do not have any voterfile data, this is a great way to learn about AdvoKit. Do not choose to install this sample data if you intend to upload real voterfile data and begin to run a real campaign, however you can get rid of the sample data at any time just by re-running the AdvoKit-installer. Note that the option to load sample data is off by default, and appears at the bottom of this long page, requiring scrolling down to see it.

 

Step 4: Database setup concluded:

If you now choose to continue, the installer will proceed to install the more than fifty database tables needed to run AdvoKit. This should only take a minute. A lengthy log of results for each SQL insert statement should scroll rapidly past as each table is created. If there are any errors, the installer will usually stop and display an error message. However it is a good idea to to quickly scan the results display for any highlighted text that may indicate a warning or error message. Most warnings can be safely ignored. An error message stops installation, and should be resolved and the import run again.

 

Step 5: Application files installation:

Once the database installation is successful, the installer turns to setting up the application files and configuring the advokit.ini file that binds everything together. To do so, you must provide the installer with information about where your installation will be found on the world wide web, and where its files will be found on the machine that will be serving your site..

• Installation URL: This is the address that people will be able to type into their browsers to use your site. For example: "http://www.mydomain.org/advokit". The installer fills this field in for you, but you can change it if desired.
• Filesystem path: This is the path to the directory on the host machine that corresponds to the URL above. The installer will likewise fill this field in for you, but you can edit it if necessary.

The following five items expect you to provide an absolute path for locations to place AdvoKit application files - folder locations on the host machine. In a remote hosted environment, the complete path may not be apparent to you, since you can usually only see the file structure below your private home directory. However, the advokit-installer does provide some help for you. If you look at the filesystem path above that was filled out by the installer, it shows the complete filesystem path to where the web-accessible portion of AdvoKit is found in your web directory. Since your web directory is normally located below your private home directory, you can pull out the portion of the path that shows where your private home directory is. For example, if

Filesystem path is "/home/.zachheater/janedoe/public_html/advokit", then it's easy to figure out that the private home directory is "/home/.zachheater/janedoe". Now if you created a folder called "advokit" under your private home directory (see "File system setup above), then you would just need to substitute "/home/.zachheater/janedoe" for "\NON-WEB\PATH\TO" in the following paths.

• Uploads: This directory is where some uploaded files are stored (not used much, if at all).
• Voterfiles: This is where you will want to put voter data that you have uploaded in preparation for importing into AdvoKit.
• Application files: This is where all the executable code for AdvoKit is located. Several folders are created under this directory.
• Templates: The Smarty templates that actually create the AdvoKit pages go here.
• Log directory: Log files are generated and saved here.

Carefully double-check all the entries in this page before clicking "Continue >". You will next see a scrolling list of the files that are being copied to your application folders. Watch for error messages, usually shown in bold red type. If there are errors, try to resolve them and then reload this page, or go back one step.

Upgrading an existing AdvoKit installation

Until something better is written, see this FAQ entry.