         		Manhattan Virtual Classroom 
                               version 3.2
	  	        Installation and Testing
                 	    Steven Narmontas 
		        snarmont@users.sf.net

============
Introduction
============

The Manhattan Virtual Classroom (http://manhattan.sourceforge.net) is a
web application written in the C programming language.

Manhattan was developed under Linux, and most people run it under that
operating system. However, Manhattan should also compile cleanly under
FreeBSD.

Currently MANHATTAN WILL NOT COMPILE ON A 64 BIT OPERATING SYSTEM.
Also, there are issues moving classroom data between 64-bit and 32-bit
systems. Some have been successful compiling the system on a 32 bit
system, and then moving the binaries over to their 64-bit system, but
that's not recommended.  If you purchased a 64-bit system for the sole
purpose of running a Manhattan server, you can install a 32 bit version
of Linux on that hardware.  Support for 64 bit systems is on our to-do
list, but it is not a high priority.  Software like Manhattan will not
run faster on a 64 bit system.

Many people who would like to install Manhattan are relatively new to
Linux.  In addition, there's the problem that there's many Linux
distributions, each of which does things a little differently.  Because
of these issues, these INSTALL instructions have been recently changed
to provide more hand holding and testing than previous versions.

AFTER INSTALLING MANHATTAN FOLLOWING THESE INSTRUCTIONS, VISIT
http://manhattan.sourceforge.net AND LOOK FOR THE ADMINISTRATOR'S
MANUAL.  That manual explains in detail how to create a super-user
account, how to create classrooms, and in general how to manage a
Manhattan server. In addition, you'll also find a TEACHER'S REFERENCE
manual there, which explains Manhattan from a teacher's perspective.


=================== 
FreeBSD needs gmake
===================

Earlier releases of Manhattan were were successfully compiled and
installed on a PC running FreeBSD 6.  Unfortunately I no longer have
FreeBSD installed anywhere, so I have not yet experimented with
installing this version of Manhattan under that OS.

One thing is certain: If you are running FreeBSD, you'll have to set
things up so you use 'gmake' instead of FreeBSD's standard 'make'. 
This worked for me:

 1) Install gmake from the ports collection.
 2) Move FreeBSD's standard make out of the way:

    cd /usr/bin
    mv make make.sav

 3) Create a symbolic link make --> gmake

    ln -s /usr/local/bin/gmake make

Now the following INSTALL instructions should work fine for you, since
every reference to 'make' will actually be running 'gmake'

REMEMBER TO UNDO THIS after installing Manhattan like this:

   cd /usr/bin
   rm -i make
   mv make.sav make

There may be other (better) ways to substitute gmake for make on a
FreeBSD system.  The bottom line is that when you type:

  make --version

You should get a response that looks something like this:

   GNU Make 3.80
   Copyright (C) 2002  Free Software Foundation, Inc.

The actual version number is unimportant, as long as you have any
version of gmake installed, you'll do fine.  If the above command
results in some version information for GNU Make, you're ready to
install Manhattan.




=====================================================================
STEP  1: Select/create a user account for Manhattan 
====================================================================

Manhattan will be installed in the home directory of an ordinary user. 
You can either use an existing user account (such as your own), or you
can create an entirely new user account for this purpose.

At times you must become 'root' during the installation process.  The
user account you select should have that capability, either by using
the 'su' command together with the root password, or by having the
privilege of runnning the 'sudo' command.  In either case, know how to
execute commands as 'root' before moving on!
 
If you do create a new user account for your Manhattan installation, we
recommed you use the username 'manhat'.  THESE INSTRUCTIONS WILL ASSUME
THE USERNAME YOU'LL USE IS:

     manhat

If you use another username, adjust the following instructions
accordingly.

NOW LOGIN AS THE USER 'manhat' and from manhat's home directory, enter
the command:

                chmod 711 .

Note the 'dot' at the end of the command.  This command gives the
Apache web server limited access to manhat's home directory.



======================================================================
STEP 2:  Unpack the Manhattan distribution.
=====================================================================

Copy the Manhattan distribution file into user manhat's home directory,
and unpack it with:

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

Replace manhat-x.x.x.tar.gz with the actual name of the distribution
you downloaded.  (The 'x.x.x' part of the file name represents the
Manhattan version number.).

By user 'manhat', I mean whatever user account you have decided to use
to install Manhattan.  (This is the last time that will be mentioned!)

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.



======================================================================
STEP 3: Test for 'make' and 'gcc'.
=====================================================================

Change to the 'src' subdirectory of the manhat-x.x.x directory that was
just created:

	cd manhat-x.x.x/src

Now type the command:

	src>  make hello

Don't type the src> part! I'll use that to represent your shell prompt. 
Hopefully the 'src' will remind you that you need to be in the 'src'
directory of your Manhattan installation.

You should see something like:

	rm -f sqlite3_test.o hello.o clearsilver_test.o
	gcc -O2 -Wall -Iinclude -c hello.c
	gcc -O2 -Wall -Iinclude  hello.o  -o hello
        src>


Now run the 'hello' program by typing:

	src> ./hello

	You have 'make' and 'gcc' working! Test passed.

	src>


As shown above, the program simply prints a line of text on your
screen. If you completed the above steps without errors, move on to
Step 4 below.


Still here?

If you get any "command not found" or similar errors, you probably
don't have GNU make or the gcc compiler installed on your system.

You can test for these individually by typing:

	src> make -v
 
and 

	src> gcc -v

'make' and 'gcc' are tools used to create programs under Unix-like
operating systems.  Sometimes these tools are not automatically
installed when you install Linux. Use your version of Linux's package
management system to find and install gcc and make.  Often 'make' and
'gcc' will be found in a software category with a name that contains
the word "Development"

For some distributions, including Ubuntu, you might get the strange
message: "C compiler can't create executables", or similar. If this is
the case, you need to install the GNU C Development Libraries and
Header files.  This package will usually have a name like 'libc6-dev',
and might be found in the "Development" or "Libraries" category.

There's no point continuing until your system can pass this simple
test.  If you get stuck, consult a forum for your particular version of
Linux.  Tell them you can't get a simple "hello world" program written
in C to compile and run.



==========================================================================
Step 4:- Do you have sqlite3 installed?
=========================================================================

Starting with version 3.2, Manhattan requires a 'shared library' called
sqlite3.  MAKE SURE YOU ARE IN THE 'src' DIRECTORY OF YOUR
INSTALLATION, then type:

	src> make sqlite3_test

In a perfect world, you'll get something like:

	rm -f sqlite3_test.o hello.o clearsilver_test.o
	gcc -O2 -Wall -Iinclude -c sqlite3_test.c
	gcc -O2 -Wall -Iinclude  sqlite3_test.o   -lsqlite3 -o sqlite3_test
	src>

If this is the case (that is, you received no error messages), run the
program by typing:

	src> ./sqlite3_test

You should get something like:

	Creating a database...
	Creating a table...
	Inserting some data...
	Performing a query...
 	12345  Hello world!  1  0 
	sqlite3 tests passed!!
	src>


If the above steps completed without errors, move on to Step 5 below.


Still here? 

You need to install the "sqlite3" and/or the "sqlite3 development"
packages for your version of Linux. Use your Linux version's package
management system (whether that's RPM, YaSt, Synaptic Package Manager,
aptget, or whatever) and look for 'sqlite3' AND the 'sqlite3
development' (it may be called 'sqlite3-dev') packages, and install
them on your system. Then try the above test again.

For many Linux distributions, you'll find that sqlite3 is already
installed, but the sqlite3 development package is not.  (This seems to
be the case with Ubuntu Linux)

Note you'll probably find packages for 'sqlite' as well as 'sqlite3'.
There's no harm installing both, but Manhattan (and this test) will
work only if you have sqlite3 installed.

The website for SQLite is: http://www.sqlite.org



=====================================================================
Step 5: Type 'make clean'
=====================================================================

Be sure you are in the 'src' directory of your Manhattan installation,
then type the command:

	src> make clean

You should see many lines scroll by, as the Manhattan distribution is made
ready for installation.  There's not much that can go wrong here, since you
already checked that you have the 'make' program installed in an earlier
step.



=================================================================
Step 6: Install and test the ClearSilver library.
================================================================

Another shared library that must be installed is called 'libneo.so'. 
This provides the ClearSilver html template library that plays a
central role in Manhattan 3.x.  The website for ClearSilver is:
http://www.clearsilver.net 

ClearSilver's libneo.so library is newer and much less common than the
sqlite3 library.  Unless you've already had a previous 3.x version of
Manhattan installed on this server, it's unlikely you have this
installed.  To test, MAKE SURE YOU ARE IN THE 'src' DIRECTORY OF YOUR
INSTALLATION, then type the following:

 src> make clearsilver_test

If you have the ClearSilver library properly installed, you'll see
something like:

 rm -f sqlite3_test.o hello.o clearsilver_test.o
 gcc -O2 -Wall -Iinclude  -IClearSilver -c clearsilver_test.c
 gcc -O2 -Wall -Iinclude clearsilver_test.o  -lneo -o clearsilver_test
 src>

If there are no errors, you can try running the clearsilver_test program by
typing:

	src> ./clearsilver_test

If everything works perfectly, you'll see something like:

	ClearSilver.Test = Passed

	src>

If you can reproduce the above actions without error, move on to Step 7.

Still here?

I'm not surprised, since the ClearSilver library (named libneo.so) is much
less common than the sqlite3 library.  It's unlikely you'll have it
installed unless you've already installed an earlier edition of Manhattan
3.x on this system.

To install the ClearSilver library, follow these steps carefully. 

First, make sure you are in the 'src' directory of your Manhattan
installation, then type the command:

  	src> make clearsilver

You'll see lots of lines scroll by on your screen as the library is
created.  At the end, you'll be returned to your shell prompt.  Type
the following command to list the files in a newly created 'lib'
directory:

	src> ls lib
	libneo.so
	src>

The libneo.so file needs to be installed on your system.  TO DO THAT
YOU MUST BECOME 'root'.  (See the comments in Step 1 above.) As 'root'
do:

	src> cp lib/libneo.so   /usr/lib
	src> ldconfig

NOTES:  

If you get a 'command not found' while typing the second
command, try the command (while root) as: /sbin/ldconfig

IF YOU ARE RUNNING FreeBSD, the second command should be:

             ldconfig -m /usr/lib

            (or maybe /sbin/ldconfig -m /usr/lib )


Once you've installed the libneo library using 'ldconfig' , repeat the
test listed at the top of this step to make sure ClearSilver is
working.



===================================================================
STEP  7:  Create and edit the custom.h file
==================================================================

Be sure you are in the 'src' directory of your Manhattan distribution,
then type the command:

	src> 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 custom.h
file.  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, BUT DON'T SPEND
HOURS ON IT! Most of the options are fine just the way they are, but 
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.



======================================================================
Step 8: Compile the programs.
=====================================================================

Be sure you are in the 'src' directory of your Manhattan installation,
then type the command:

	src> make install

The compile 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. WARNINGS can generally be ignored.  If
any errors occur the process will stop before you see the word "Done!".



========================================================================
Step 9:  Configure Apache
=======================================================================

You have to become 'root' to do this step!

I assume you already have the Apache web server installed and running on
your server.  If not, get that done.

Now add the following lines to the appropriate place within your Apache
configuration files. BE SURE TO REPLACE ALL SIX OCCURRENCES OF
manhat-x.x.x WITH THE NAME OF YOUR MANHATTAN DISTRIBUTION.  The text
'/home/manhat/manhat-x.x.x' below should be the full path to the
directory where Manhattan is installed:

--- cut here -------------------------------------------------------

      ScriptAlias /manhat-bin/   /home/manhat/manhat-x.x.x/bin/

      <Directory "/home/manhat/manhat-x.x.x/bin/">
        AllowOverride None
        Options +ExecCGI -Includes
        Order allow,deny
        Allow from all
      </Directory>


      ScriptAlias /manhat-sbin/   /home/manhat/manhat-x.x.x/sbin/
      
      <Directory "/home/manhat/manhat-x.x.x/sbin/">
        AllowOverride None
        Options +ExecCGI -Includes
        Order allow,deny
        Allow from all
      </Directory>


      Alias  /manhat-images/   /home/manhat/manhat-x.x.x/images/

      <Directory /home/manhat/manhat-x.x.x/images>
          Options FollowSymLinks
          AllowOverride None
          Allow from all
      </Directory>

--- cut here ----------------------------------------------------



The "appropriate place" is wherever your installation of Apache likes
to see ScriptAlias directives. This might be in a file named httpd.conf
or could be in another file Included into your httpd.conf file.

If you don't know how to do this, maybe this explanation (ok, rant)
will help. Traditionally, Apache's configuration is controlled by a
text file that's usually named httpd.conf.  Where this file is located
seems to be at the whim of the designer of your Linux distribution,
slightly influenced by whether you are running Apache 1.3 or some 2.x
version.  You need to find the httpd.conf file. It's been known to live
in any one of these places:

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

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

Found it? Good.  You'd think that would be enough, eh?  There was a
time when all of the configuration directives were placed in this one
text file. That might still be the case for your installation. 
However, now it seems to be trendy to add other configuration files,
sometimes many other configuration files, by using Include statements
within the httpd.conf file.  So, the <ScriptAlias> directives we're
looking for could be almost anywhere.  Start looking in the httpd.conf
file.  If it's there, great, otherwise look in files that are Included
from the httpd.conf file, or maybe even in files that are stored
somewhere near the httpd.conf file.

After changing your Apache configuration file(s), restart the Apache
web service. You can often restart Apache by typing (as root)
'apache2ctl restart' for Apache 2 or 'apachectl restart' if you're
running Apache 1.3.


As a specific example, on my Ubuntu 6 installation, I was able to
create a new file called simply 'manhattan' containing nothing but the
above directives.  I placed the file in the directory:
/etc/apache2/conf/conf.d  To restart the Apache service I used:

   sudo apache2ctl restart

Ubuntu is based on Debian, which may or may not use a similar
configuration scheme.



=====================================================================
Step 10: Test your Apache configuration, and set your file permissions.
======================================================================

From any computer, use a web browser to visit:

    http://YOUR_SERVER/manhat-bin/apache_group

Replacing YOUR_SERVER  with the hostname of your server.

If everything is set up correctly so far, you'll get a page that looks
something like this:


   -------------------------------
   Apache is running as group: www

   To properly set the permissions for your Manhattan installation:

   1. cd to the 'src' directory of your Manhattan installation
   2. Become 'root' (or use sudo to execute the next command as 'root')
   3. Type the command:

   		./set_dirs www

   ------------------------------

Assuming the page displays, follow the instructions shown in your web
browser.  This involves running a 'set_dirs' script with an argument,
which will set up all of Manhattan's data directories with the proper
file permissions.  The above example shows that "Apache is running as
group: www", and therefore the command you need to run from the 'src'
directory as 'root' is

  src>  ./set_dirs www

The Apache group is often 'www', but your installation  might be
different.  Ubuntu, for example, seems to use the group 'www-data'
In all cases, follow the instructions on your web browser's screen. 

You'll see something like:

	Setting up ../sbin and ../bin
 	Setting up ../tmp
	Setting up ../templates
	Setting up ../clipboards
	chmod: cannot access clipboards': No such file or directory
	Setting up ../surveys
	chmod: cannot access surveys': No such file or directory
	Setting up ../images
	Setting up ../chat
	Setting up ../auto_update
        Setting up ../courses
	Setting up ../users


Note: the 'No such file or directory' errors are normal and can be
ignored.  However, MAKE SURE YOU RUN THE COMMAND AS ROOT', or the
permissions will not be set properly.

The whole point of visiting the 'apache_group' URL is to learn the
Group setting of Apache, so you can run ./set_dirs with the correct
argument. If you can't visit the web page, then there's probably
something wrong with the Apache configuration you did in Step 9.

You should only need to run the set_dirs script once, when you are
first installing Manhattan.  The file permissions will stay correct
forever, unless you mess around with the file system.  That said, it's
safe to run ./set_dirs whenever you think the file permissions may be
wrong, provided you include the correct argument, which is the Group
setting of your Apache installation.



=================================================================
Step 11: Perform some final tests.
=================================================================

From any computer, use a web browser to visit:

    http://YOUR_SERVER/manhat-bin/config_test

Replacing YOUR_SERVER with the hostname of your server.  This page does
a few more tests, such as making sure the spell checker for Manhattan
is installed and working.  The page includes some information on how to
set things straight if they are not already working.



===============================================================
Step 12: Configure your Super User account
==============================================================

If all of the above worked out for you, Manhattan should be ready to
go.  Visit:

  http://YOUR_SERVER/manhat-sbin/super_conf

To create a "Super User" account.  After that, you should:

   READ THE ADMINISTRATOR"S MANUAL AT:
       http://manhattan.sf.net

to learn how to begin using Manhattan.




### END OF INSTALL ###

    



