Before you begin the installation process please read the system requirements and all of these instructions carefully. If you are upgrading, please refer to the upgrading instructions.

IMPORTANT: if for any reason your installation process does not complete, your environment will be in an unknown state. After resolving whatever issue prevented the process from completing, you must run the installation to completion.

Please ensure that your web server is operational and before you begin this installation.

The following instructions are for a typical installation under a web server such as Apache. Alternative installations may be configured by experienced system administrators. These instructions assume a user who is familiar with the use of a command shell such as "csh" or "bash"in a Terminal window. All the steps here must be performed from such a shell.

Table of Contents

1 Unpack ApTest Manager

Create a directory on your server system where you want your web server software to find ApTest Manager. This will usually be beneath the document root for your web server (e.g., /Library/WebServer/Documents/atm).

IMPORTANT: ApTest Manager must not be installed in such a way that it is within any other web application. For example, if you have "bugzilla" installed on your web server, do not attempt to place the ApTest Manager folder beneath the bugzilla folder. The web application configuration settings will conflict, and both applications will break.

Unpack the ApTest Manager distribution archive into the directory you created.

IMPORTANT: under Mac OS X you can install web data in personal "Sites" or in the global server area. These instructions assume that atm is unpacked and installed in /Library/WebServer/Documents.

2 Install your license file

Download your license file from the same area of the ApTest web site where you downloaded the main ApTest Manager files. It is best to download it by selecting the license download link and choosing "Save as". Do not edit the file in any way.

Copy the LICENSE.dat file into the data directory underneath the location where you unpacked ApTest Manager.

3 Execute the installation script

In your ApTest Manager directory, execute the Perl script INSTALL.pl, for example:

MyMac:/$ cd /Library/WebServer/Documents/atm
MyMac:/Library/WebServer/Documents/atm$ perl INSTALL.pl

Note: You must run INSTALL.pl as an administrator.

The first thing this script will do is examine your system to ensure that all the required Perl modules are present. If they are not, you will be told which modules are missing and be given the option of allowing the installer to automatically install them for you. You have the option to install the modules in the general system location or locally to ApTest Manager.

Note: We strongly recommend allowing the installer to install and configure any missing modules for you.

Note: If you are asked where the "GD" libraries are located during the installation process, enter "/sw/lib".

If automatic installation of modules does not occur please refer to the documentation on configuring Perl for automated module installation and ensure your Perl environment is appropriately configured.

All of the required modules must be installed before proceeding with the installation.

Once all the required components are present you will be asked a few questions about the ApTest Manager installation. Answer these questions carefully to define the way in which ApTest Manager will operate on your system.

Note: ApTest Manager will suggest default answers to most questions. The default is enclosed in brackets after each question. If the default is correct for your system, just press enter to use that value.

Note: You can re-run the installer as many times as you like, but after the first time, you'll need to specify the "-f" option (perl INSTALL.pl -f) to force an installation, otherwise it will refuse to overwrite your existing configuration files. Also, remember that when using the -f option, any edits you might have made to the config.pl file will be lost.

3.1 Execution mode

How will this copy of ATM be connected to your web server?

0 - CGI (Any Server including IIS on Windows)
1 - mod_perl 1 (Apache 1)
2 - mod_perl 1.99 (Apache 2, beta of mod_perl 2)
3 - mod_perl 2 (Apache 2)

Choose an execution mode? [0]

This option will allow you to select if you want to use mod_perl, and which version of mod_perl you will be running. . The preferred configuration of ApTest Manager is Apache with mod_perl.

The installer will try to determine which if you have mod_perl on your system, and present the right option as the default.

Troubleshooting tip: if you select a mod_perl option, you must be using the Apache web server and have mod_perl installed. This module and associated documentation is available at perl.apache.org.

3.2 Directory

What is the directory/virtual directory that you would use in a URL
to access ApTest Manager from a browser (e.g., if ApTest Manager
was unpacked as "atm" in the HTML document root, this might be
"/atm")? [/atm]

If the URL you would use to access ATM is http://www.example.com/testing/, you would enter "/testing" for example.

The installer will offer the current directory name as the default, which is often correct.

3.3 File system path

What is the file system path to this copy of ATM ? 

Where is ApTest Manager actually unpacked in the file system?

Note: please be sure to use forward slashes, not back slashes in entering this path.

3.4 Administrator password

What password should be assigned to the administrator account? [admin]

Note: if re-running the installer using the -f option, the administrator account will already exist, in which case the administrator password will not be changed.

3.5 Encrypt passwords

Do you want passwords stored in an encrypted form? [n]

By default, ApTest Manager stores user passwords in plain text. This allows administrators to see the passwords, which may be considered a security risk. Specifying "y" here will make ApTest Manager store the passwords in an encrypted form. Administrators will be able to reset passwords, but won't see the originals.

Note: if re-running the installer using the -f option, this option will not appear if password encryption has already been selected. Password encryption is not reversible.

4 Verify your web server's configuration

4.1 Apache

Under Apache, all you need do is ensure that the directory in which ApTest Manager is installed has the AllowOverride flag set to at least "Options" (for future compatibility, however, we recommend the flag be set to "All"). For example, include at the end of your httpd.conf Apache configuration file something like:

<Directory /Library/WebServer/Documents/atm>
AllowOverride All
Order deny,allow
Allow from all
</Directory>

If you selected to run ApTest Manager under mod_perl, then you will also need a control line for that:

PerlRequire /Library/WebServer/Documents/atm/ATMHandler.pm

If you install ApTest Manager in a directory that is not under your server's normal DirectoryRoot, you will need to add instructions so Apache can find it:

Alias "/atm" "/Library/WebServer/atm"

Note: If your copy of Apache has the mod_expires module enabled, ApTest Manager will automatically use this to improve Internet Explorer's ability to cache items. This can result in a substantial performance improvement, especially over broadly distributed or slower networks. See the Apache documentation for information on installing and configuring this module.

Finally, note that some systems (e.g., recent versions of Ubuntu) have mod_actions disabled in Apache by default. ApTest Manager relies upon this module to handle dispatching requests, so it must be enabled.

5 Check your configuration

Using your web browser, navigate to the configuration checking tool "checkSetup.pl" in the ApTest Manager directory (e.g. http://www.example.com/atm/checkSetup.pl). This tool will examine your installation and ensure everything is OK. If there are any errors, you must repair them before you can use ApTest Manager. If the tool refuses to run, this indicates that your web server is mis-configured. Ensure that the web server can run ".pl" scripts as CGI scripts.

6 Configure ApTest Manager further

The installation process sets various configuration options. There are other configuration options that can be set after the installation process has completed. Please see the documentation on configuration options for ApTest Manager for further details.

7 Access ApTest Manager

Point your web browser at ApTest Manager. For example, if your machine is named www.example.com, and ApTest Manager is installed in /atm on that server, use the URI http://www.example.com/atm/.

At this point, ApTest Manager will display a message on the login page saying ApTest Manager is temporarily only available to Administrators and to try back later. Only users with administrative privilege will be able to login.

To open ApTest Manager to Normal users:

  1. Login as the special user named admin. Use the password you specified when installing ApTest Manager.
  2. Click on the username on the Suite bar.
  3. Click on Manage system configuration.
  4. Select "No" for the question "Should ApTest Manager be closed to non-administrative users?" and click Update Configuration.

You may create user accounts using the "Create an account" menu item. Logout as the admin user and login as one of the accounts you create in order to access the non-administrative areas of the product.

See the Administration chapter of the ApTest Manager User's Guide for more details.

Copyright © 2000-2015 Applied Testing and Technology, Inc. All rights reserved.