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 or IIS. Alternative installations may be configured by experienced system administrators. These instructions assume a user who is familiar with the use of a command shell 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., C:\Inetpub\wwwroot\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: you must not have any space characters in the path to ApTest Manager (e.g. "C:\Program Files\atm\" will not work). This is because ActivePerl has trouble parsing paths with white space in them when looking up libraries, and ApTest Manager uses many local libraries.

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:

C:> cd C:\Inetpub\wwwroot\atm
C:\Inetpub\wwwroot\atm> perl INSTALL.pl

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.

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.

Note: When installing new modules, new DLLs may be added to your system. You may need to restart Windows after installation for these to register.

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. You should select CGI mode if using IIS as your web server, as mod_perl is only available for Apache.. 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 ? [C:/Inetpub/wwwroot/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.

3.6 File Access Permissions

ApTest Manager needs to be able to modify files in the folders data, mason, and suites. In order for this to happen, the Windows "user" that the web server application is running as needs modify access to these folders and everything therein. Use Windows Explorer to set the access permissions on these folders. Under IIS 7 you can also use the folder explorer view - right clicking on the ApTest Manager folder and selecting "Edit permissions". Use the "Security" tab to update the permissions. Note that these permissions must be set correctly or ApTest Manager will fail to operate.

If your server is otherwise secure (or your file access security is not a concern), it is okay to just set the permissions such that the user 'Everyone' has 'full control' access to these folders.

4 Verify your web server's configuration

4.1 Microsoft IIS

Under IIS, you need to configure the directory for ApTest Manager.

If you already see the ApTest Manager directory (i.e. you unpacked ApTest Manager into the web root directory) right click on it and select "Properties". On the "Directory" tab select the "Create" button to activate the directory. Proceed to the configure directory section.

If you unpacked ApTest Manager somewhere other than the web root directory, you will need to create and configure a new virtual directory.

Create a virtual directory

  • Go to the Internet Information Services control panel, and select the web server you will be using.
  • Right click on the web server item and select "New->Virtual Directory".
  • Enter a name for the directory (this should be directory name you specified when installing ApTest Manager) and select "Next".
  • Enter the directory location where you unzipped the ApTest Manager distribution and select "Next".
  • For access permissions, select read and execute. You do not need run scripts, since ApTest Manager does not use ASP scripts. Select "Next".

Configure (virtual) directory

  • Now that IIS knows about the directory, right click on that directory and select "Properties".
  • In the "Directory" (or "Virtual Directory") tab of the properties, select the "Configuration..." button.
  • Use the "Add" button to add a suffix mapping.
  • For the executable, select the perl.exe that you installed, followed by the cgi_handler.pl script that is in the ApTest Manager directory. For example, if Perl is installed in C:\perl, and ApTest Manager is installed in C:\Inetpub\wwwroot\atm, you would enter: 
    C:\Perl\bin\perl.exe C:\Inetpub\wwwroot\atm\cgi_handler.pl

    Note that under IIS 6, the script name portion of this needs to be in quotation marks. Under IIS 6 you would enter:

    C:\Perl\bin\perl.exe "C:\Inetpub\wwwroot\atm\cgi_handler.pl"

    Under IIS 7, scripts are connected using the "Handler Mappings" component at the directory level. Ensure there is a 'Script Map" for *.pl that maps to your Perl (e.g., c:\strawberry\perl\bin\perl.exe %s) and one for *.mpl that maps to your ATM cgi_handler.pl script (e.g., c:\strawberry\perl\bin\perl.exe "c:\atm\cgi_handler.pl").

  • In the Extension box, enter ".mpl" (omitting the quotation marks).
  • Select "OK".

Set web service permissions

Once you have activated your directory, or created your virtual directory, you need to tell IIS it is OK to run ApTest Manager. With the advent of Windows Server 2003 and IIS 6, there is a new security paradigm. In the IIS Manager Control Panel, under the Web Sites folder, there is a folder called "Web Service Extensions". Within it you can specify which web services are permitted to run. Set "All Unknown CGI Extensions" to "Allowed", and set "Perl CGI Extension" to "Allowed". Under IIS 7 this is handled through the "ISAPI and CGI Restrictions" component at the server level of the IIS Manager.

4.2 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 C:/Inetpub/wwwroot/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 C:/Inetpub/wwwroot/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" "C:/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-2018 Applied Testing and Technology, Inc. All rights reserved.