Installation Instructions

This section contains step-by-step instructions for installing The Manhattan Virtual Classroom on a Linux server. Also see Installation Commentary for detailed commentary on each step.

While logged in as root:

1. Create a new user named manhat with a good password. This user will have full read/write access to all files and programs created by the system.

2. Add a group named www to your system, and make manhat a member of that group. If that makes sense to you, skip to Step 3 once you've done it, otherwise maybe this will help:

   Each user account on a Linux system can be associated with one or more groups. When an account is first created, a user might be put into a group called users, for example. For our purposes, we want the user manhat to also be a member of a group called www. (A user can be a member of several groups. For example, manhat can be a member of both users and www.)

   Your Linux distribution might already have a pre-defined group named www. (This is the case for SuSE 9.0, for example, and is also true for the FreeBSD 4.8 I've installed.) If this is the case, then you just need to make manhat a member of that group. For other Linux distributions, you'll have to create a new group named www, then add manhat as a member.

   How to create users and groups varies between Linux distributions, but it is likely that your distribution has a graphical utility for managing groups and users. Consult your system's documentation. (For FreeBSD, login as root and edit the file /etc/group to add manhat to the end of the line that starts with www.)

   Once you think you have the manhat account created and have made manhat a member of the group www, you can try typing the command:

   groups

   while logged in as manhat. This command lists the groups that manhat belongs to. Make sure the list includes www.

   You may have to logout and then login again for the manhat user's group change to take effect.

NOW LOGIN AS THE NEW USER manhat and do the following:

3. From manhat's home directory, enter the command:

   chmod 711 .

   This command gives limited access to manhat's home directory.

   Note the 'dot' at the end of the preceding command. A 'dot' means 'this directory'.

4. Copy the Manhattan distribution's gzipped tar file to manhat's home directory. cd to that directory and uncompress and unpack the tar file with:

   tar -xvzf manhat-x.x.x.tar.gz

   You'll notice that as the file unpacks, it creates a new directory. That's the installation directory you'll use in place of manhat-x.x.x in the remainder of these instructions.

5. cd to the src subdirectory of the manhat-x.x.x directory that was just created

   cd manhat-x.x.x/src

6. Enter the following command:

   cp default_custom.h custom.h

   This copies the default configuration file into a file named custom.h, which is required to install Manhattan.

   Use your favorite text editor to view and probably modify the file named custom.h Extensive comments within that file explain each option. If you don't understand what an option does, you can generally leave it alone.

   Don't skip the step of reviewing the custom.h file. In particular, you will want to change the first entry, which is: #define EXIT_URL "http://manhattan.sf.net If you don't, you'll find that users will be directed to Manhattan's home page when they logout of the classroom. Change this entry to point to one of your own websites.

7. Type the commands

   make clean make english (or make spanish, or ...) make install

   to compile the source files. (FreeBSD: remember to use 'gmake' instead of 'make' throughout these instructions.) Other translations besides english and spanish might be available, although they might be in an incomplete state at this time. Try the command 'make' for a list of available languages.

   The build process involves converting a number of 'C' source files into binary executable files. You should see dozens of lines scroll by on your screen as the process completes. This can take a few minutes, especially on slower computers. If any errors occur, you might want to break the compilation down into smaller steps to isolate the problem - see Separate Compilation of Manhattan Components below.

   If you immediately get errors like:

   make: command not found or gcc: command not found

   
   
   

   it means that you don't have either the GNU 'make' program or the GNU gcc compiler installed on your system. At one time, it was unthinkable to have a Linux distribution without these basic tools, since they can be considered an integral part of any Unix based system. These days, however, some distributions make the installation of these tools optional, particularly if you've performed a 'desktop' or 'workstation' type installation. Read your system documentation to learn how to add the gcc compiler and GNU make to your system. Look for something similar to 'developer tools'. The packages you need are on probably on the CDs that came with your distribution (or are otherwise freely available on the Internet).

   If you get an error like:

   custom.h: file not found

   it means you skipped Step 6 above.

   The executables are installed in the directories:

   /home/manhat/manhat-x.x.x/bin and /home/manhat/manhat-x.x.x/sbin and /home/manhat/manhat-x.x.x/chat

   You'll also find that the installation has created directories named:

   /home/manhat/manhat-x.x.x/courses ........................./surveys ........................./clipboards ........................./templates ........................./tmp ........................./templates ........................./users ........................./images

   MANHATTAN NEVER WRITES ANY FILES OUTSIDE OF ITS OWN INSTALLATION DIRECTORY.

WHILE LOGGED IN AS root do:

8. Manhattan is a web-based application that requires the Apache web server. (If it's not installed, you'll have to read your distribution's documentation to find out how to do that.)

   Apache's configuration is controlled by a file named httpd.conf. Find the file. Unfortunately, where this file is located depends on your Linux distribution, and how Apache was installed. You might find it as:

   /usr/local/apache/conf/httpd.conf or /etc/httpd/conf/httpd.conf or /etc/httpd/httpd.conf or ...

   The commands locate httpd.conf or whereis httpd.conf can help you find the file.

   Open the file in a text editor (you must be logged in as 'root') and look for the lines:

   User <something> Group <something>

   and change the Group setting to:

   Group www

   Some installations already use the Group www setting, so you won't have to make any changes.

9. Add the following lines to the appropriate place within the httpd.conf file.

   The appropriate place is usually at the end of the file. (If you are using virtual hosts, you might have to put the lines within the proper <Virtual Host> container.)

   If you are not using virtual hosts, try placing the lines at the end of the httpd.conf file. That's worked for me. Another approach is to search the file for the text "ScriptAlias" and put the lines below any existing entries.

   Again, be sure to replace all FOUR occurrences of manhat-x.x.x with the appropriate name of the Manhattan distribution:

   ScriptAlias /manhat2-bin/ /home/manhat/manhat-x.x.x/bin/ ScriptAlias /manhat2-sbin/ /home/manhat/manhat-x.x.x/sbin/ Alias /manhat2-images/ /home/manhat/manhat-x.x.x/images/ <Directory /home/manhat/manhat-x.x.x/images> Options FollowSymLinks AllowOverride None </Directory>

   Now check your ServerName setting in httpd.conf

   Your Apache httpd.conf file contains a ServerName entry. Find it, and make sure it is correct. The ServerName setting is used by Manhattan to redirect users back to certain Manhattan programs. Often this setting is filled in with some default value that won't work for Manhattan.

   The correct value for your ServerName setting is the complete name someone would type into a web browser to visit a page on your server. An example is:

   ServerName www.myschool.edu

10. Save the httpd.conf file and restart the Apache web service.

    The command apachectl restart is typically used to restart the Apache server. Like the httpd.conf file, the location of the apachectl program varies between distributions. Some typical locations include:

    /usr/local/apache/bin/apachectl restart /usr/sbin/apachectl restart /sbin/apachctl restart

    Try typing locate apachectl if you can't find the program

11. Test the installation by pointing a web browser at:

    http://YOURSERVER.edu/manhat2-bin/doorstep

    
    
    

    You should get a login screen with a Manhattan Virtual Classroom logo. Of course, you won't be able to login, since there are no accounts on the system yet! If the above URL gets you to a login screen with the logo, you're in pretty good shape. If you're in a hurry, and want to get started immediately you can skip ahead to Creating the super-user account, otherwise read on to understand a bit about the steps you just took to install Manhattan.