Next Page Previous Page Home Tools & Aids Search Handbook
Tools & Aids
Course Builder

        

Course Builder: Installation Instructions

Introduction
Prerequisites In order to install Course Builder, you need the following software:
  • Perl (version 5.0 or higher)
  • A web server (e.g., Apache or IIS)
  • For Windows platforms, the command line support plugin for WinZip
Perl is a freely downloadable scripting language. Most Unix/Linux platforms will already have Perl installed. Perl can be downloaded from the Active States web site.

There are a large number of web servers (both commercial and public domain). It is assumed that your local site already has a web server installed. If not, then the Apache web server can be freely downloaded for Unix/Linux and Microsoft Windows platforms.

It is also assumed that Course Builder will be installed by a web administrator (or at least by someone with basic familiarity with web servers and CGI scripts). It is simply beyond our scope to document web servers and CGI scripting.

Tested Environments Course Builder runs as a Perl-based CGI script. It has been tested in the following environments.
    Tested Environments
    Operating System Web Server Browser
    Windows 2000
    Windows XP
    Apache
    IIS
    Microsoft Internet Explorer 6.0
    Mozilla 1.4
    Opera 7.1
    Netscape 4.7, 6.0, 7.0
    Sun Solaris 5.7 Apache Netscape 4.7, 6.0, 7.0
As we are not experts on web servers, we will not formally support Course Builder in other environments. However, a local web administrator should be able to port it to other web servers, operating systems, or browsers with minimal effort.
Download the Perl Script The first step is to download the Perl script for Course Builder. You can download this to a temporary location of your choice (later instructions will document where to move it). You should save it with the name "course-builder.pl".

You can check the syntax of the script by entering the following command:

    perl -c course-builder.pl
Configure the Web Server You need to perform some configuration for the web server: If you have a different web server, you will need to perform similar configuration tasks. Consult your local web server administrator for assistance.

The basic task is to define where the e-Handbook files and CGI scripts reside on your local platform.

Configuration Details for the Apache Server (Windows Platforms)
Freely Downloadable Web Server Apache is a freely downloadable web server that is available for Windows platforms. The current version is 2.x. However, the 1.x versions is still supported. The configuration instructions below apply to both versions of Apache.
Some Relevant Directories For the Apache server, there are several relevant directories:
  • The directory where the Apache software is installed. For the purpose of the instructions below, we assume that this directory is

      c:\Program Files\Apache Group\Apache2

  • The default directory where the Apache server looks for documents to serve. For the purpose of the discussion below, we assume that this directory is

      c:\htdocs

    We also assume that the e-Handbook files are installed somewhere under this directory.

  • The directory where the Apache server looks for CGI scripts. For the purpose of the discussion below, we assume that this directory is

      c:\htdocs\cgi-bin
You are not required to use these directories. However, if you use different directories, modify the instructions below accordingly.

Configuration Steps The following steps are required:
  • Move the file "course-builder.pl" to the "c:\htdocs\cgi-bin" directory.

  • Make the following edits to the file
    "c:\Program Files\Apache Group\Apache2\conf\httpd.conf"

    1. Look for the line containing "DocumentRoot" and change it to:

        DocumentRoot "c:\htdocs"

      There should be a line starting with "<Directory" beneath the DocumentRoot line. Change the directory name on this line to match the directory given in DocumentRoot.

    2. Look for the line starting with "Option Indexes" and set it to

        Option Indexes FollowSymLinks MultiViews +Includes

    3. Look for the line starting with ScriptAlias and add the following additional line:

        ScriptAlias /cgi-bin/ "c:/htdocs/cgi-bin/"

      Note that this line uses forward slashes and that the directory name should contain an ending slash.

      There should be a line starting with "<Directory" beneath the ScriptAlias line. Change the directory name listed on this line to match the directory given in quotes on the ScriptAlias line.

Configuration Details for the Apache Server (Unix/Linux Platforms)
Freely Downloadable Web Server Apache is a freely downloadable web server that is available for Unix/Linux platforms. The current version is 2.x. However, the 1.x versions is still supported. The configuration instructions below apply to both versions of Apache.
Some Relevant Directories For the Apache server, there are several relevant directories:
  • The directory where the Apache software is installed. For the purpose of the instructions below, we assume that this directory is

      /usr/local/httpd

  • The default directory where the Apache server looks for documents to serve. For the purpose of the discussion below, we assume that this directory is

      /usr/local/httpd/htdocs

    We also assume that the e-Handbook files are installed somewhere under this directory.

  • The directory where the Apache server looks for CGI scripts. For the purpose of the discussion below, we assume that this directory is

      /usr/local/httpd/htdocs/cgi-bin
You are not required to use these directories. However, if you use different directories, modify the instructions below accordingly.
Configuration Steps The following steps are required:
  • Move the file "course-builder.pl" to the "/usr/local/httpd/htdocs/cgi-bin" directory.

  • Make the following edits to the file
    "/usr/local/httpd/conf/httpd.conf":

    1. Look for the line containing "DocumentRoot" and change it to:

        DocumentRoot "/usr/local/htdocs"

      There should be a line starting with "<Directory" beneath the DocumentRoot line. Change the directory name on this line to match the directory given in DocumentRoot.

    2. Look for the line starting with "Option Indexes" and set it to

        Option Indexes FollowSymLinks MultiViews +Includes

    3. Look for the line starting with ScriptAlias and add the following additional line:

        ScriptAlias /cgi-bin/ "/usr/local/httpd/htdocs/cgi-bin"

      Note that this line uses forward slashes and that the directory name should contain an ending slash.

      There should be a line starting with "<Directory" beneath the ScriptAlias line. Change the directory name listed on this line to match the directory given in quotes on the ScriptAlias line.

    For version 1.x of Apache, some of these settings may be in the file
    "/usr/local/httpd/conf/srm.conf":

Configuration Details for the IIS Server (Windows Platforms)
IIS Web Server The Microsoft IIS (Internet Information Services) is a popular web server on Windows platforms. It can be installed from the Windows operating systems disk (information on installing IIS is readily available elsewhere and not given here). Consult your local computer support staff for assistance (we cannot answer questions on installing IIS or any other web server).
Specify the e-Handbook Directory for IIS In order to configure IIS for the e-Handbook and Course Builder, do the following:
  1. Bring up the Control Panel menu
  2. Select the "Computer Management" menu
  3. Select "Services and Applications"
  4. Select "Internet Information Services"
  5. Select "Default Web Site"
  6. Right click on "Default Web Site" and select "Properties"
  7. Select "Home Directory"
  8. In the "Local Path" tab, enter the location of the e-Handbook directory (e.g., C:\HTDOCS\e-Handbook)
In addition, you should create the directory "cgi-bin" in the e-Handbook directory. For example, if you have installed the e-Handbook in
    C:\HTDOCS\e-Handbook
then enter the following command from a Command prompt window (or use Windows Explorer to create the directory)
    mkdir C:\HTDOCS\e-Handbook\cgi-bin
Once this directory has been created, move the "course-builder.pl" file to this directory.
Final Installation Instructions
Modifications to the Course Builder Perl Script You may need to make a few changes to the Course Builder Perl script. Specifically,
  • The first line of the "course-builder.pl" script identifies the path for Perl on your system. For Unix/Linux installtions, this is usually one of the following:

    • #!/usr/bin/perl
    • #!/usr/local/bin/perl

    For Windows platforms, it is usually the following

    • #!c:/Perl/bin/Perl.exe

    This path needs to match the location where Perl is installed on your local system. If you are not sure where this is, contact your local system administrator.

  • Check the line

      $HANDBOOK_URL = '/index.htm'

    This is the path to the e-Handbook's starting page relative to "http://server/" where "server" is the root page for your web browser.

  • Check the line

      $SCRATCH_DIRECTORY = '/tmp'

    This is the path to a working directory where the Course Builder creates temporary folders. You can set this to any convenient directory.

  • Change the line

      $UNIX = 0; # 1 = TRUE, 0 = FALSE

    Set this value to 0 for Windows platforms and to 1 for Unix/Linux platforms.

  • For Unix/Linux platforms, change the line

      $PACKAGER_EXE = 'wzzip'

    to

      $PACKAGER_EXE = 'tar -cvf'

    Leave this line as is for Windows platforms.

    This defines the command used to bundle up the files created by the Course Builder (WinZip for Windows, tar for Unix/Linux).

Note that for all path names above, the forward slash "/" is always used for both Unix and Windows platforms.
Boundary Issue for Internet Explorer (MIME Multipart/mixed) The Course Builder perl script has browser dependent code that separates "pages" from one another when printing the HTML code to the browser.

This is supported with Mozilla/Netscape browsers. However, the Microsoft Internet Explorer browser just prints the file to the screen rather than saving the file as expected. To resolve this problem, the script detects the browsers. For Mozilla/Netscape browsers, it will ask where to save the file. For Internet Explorer, it will ask to download the file using a link.

Zip and tar Issues The Course Builder perl script can use any external command application to compress the files generated by Course Builder. By default, it uses the command line version of WinZip for Windows and tar for Unix/Linux platforms. If you have a different tool available locally, modify the "$PACKAGER_EXE" variable in "course-build.pl" to define the appropriate command to use.

The script can use just one compression application. If you want to run Course Builder from both Windows and Unix desktops, one solution is to have two scripts; one for Windows (i.e., using WinZip) and one for Unix/Linux (i.e., using tar). Then let the user decide which script to run.

You need to have the WinZip plugin for command line support (windows only) installed in order to create zip files with the script.

Note that WinZIP can open tar files created by Course Builder running on Unix/Linux platforms (WinZip does not create tar files, but it can extract them).

Changing the Logo The Course Builder places a logo on all the pages that it creates. The default logo is a NIST logo. It is recommended that you replace this with a logo more appropriate for your local site. The simplest way to do this is to simply replace the image located in "cbuild\c-logo.gif" with a local logo.
Home Tools & Aids Search Handbook Previous Page Next Page