Manhattan: Simple. Smart.
Welcome > Documentation > README Files > INSTALL

INSTALL

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



(These INSTALL instructions was extracted from a Chapter
from the Manhattan Administrator's Reference. The complete Reference is
available at http://manhattan.sf.net)


*Table of Contents*

Introduction
FreeBSD needs gmake
Installing Manhattan under Fedora 8 and selinux
STEP 1: Select/create a user account
STEP 2: Unpack the Manhattan distribution.
STEP 3: Test for 'make' and 'gcc'.
STEP 4: Do you have sqlite3 installed?
STEP 5: Type "make clean"
STEP 6: Install and test the ClearSilver library
STEP 7: Compile the programs
STEP 8: Configure Apache
STEP 9: Test Apache configuration and Set file permissions
STEP 10: Initialize and test your configuration
STEP 11: Create a Super User account
STEP 12: Configure your server

This chapter provides detailed instructions for installing Manhattan 3.3
on a Linux server. I also provide some hints for FreeBSD servers. (If
you don't yet have the software, visit http://manhattan.sourceforge.net
to download a copy.)

Installing Manhattan isn't difficult. How long it takes depends largely
on how much experience you have with Linux. Complete "newbies" may
struggle with basic tasks like copying or editing a file, that more
experienced users have done thousands of times. After you've installed
Manhattan once, you can do it again if you need to within 20 minutes.








Introduction

The Manhattan Virtual Classroom 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.

[Warning]

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 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.







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.







Installing Manhattan under Fedora 8 and selinux

Bob McKay posted the following message to Manhattan's mailing list in
late February 2008, regarding installation of Manhattan on Fedora and
other distros using selinux:

Newer distros of Fedora are using fairly strict selinux settings. In
fact, there are many comments in webspace about turning selinux off in
order to get Manhattan to work - not really a good idea for a server.
The main symptom of selinux problems is that Manhattan returns a
Forbidden access even after file permissions are fixed. In fact, it
doesn't seem to be too difficult to get Manhattan to run under selinux.
Since this doesn't seem to be covered in the mailing list, I thought I'd
add my experience for anyone googling in future:

Since the manhattan installation content is to be accessed by apache, it
needs to be appropriately labeled. Similarly, the scripts need to be
labeled as scripts. I found the following worked: in the top-level
manhattan directory:

chcon -R -t httpd_sys_content_t *
chcon -R -t httpd_sys_script_exec_t bin/* sbin/*

"ls -Z" will confirm that everything got labelled as wanted (actually,
this will make your installation files read-accessible to apache; I
can't figure a reason why this would be bad, but if you're worried about
this, you might want to be more selective about what is labelled by the
first command).


--Bob McKay







STEP 1: Select/create a user account

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 running 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, I
recommend 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

[Note]

Don't type the "src>" part! I'll use that to represent your shell
prompt. Hopefully the "src>" prompt will remind you 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


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 the "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 the
next step: Compile the programs

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)
As "root" do:

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

[Tip]

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

[Tip]

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.

[Note]

The above method is the preferred way to install ClearSilver on your
system for use with Manhattan. It uses a method called dynamic linking,
which results in a smaller file size for Manhattan programs, and
requires less memory on your server.

If you have trouble getting the ClearSilver library installed, you might
want to check to see if your distribution of Linux has a "ClearSilver
Development" package you can install. Recent versions of Ubuntu have
such a package, for example.

After installing the ClearSilver development package for your Linux
distribution, open the file named "Custom.mk" found within Manhattan's
"src" directory in a text editor. Follow the instructions within that
file, which essentially tell you to change a single letter 'n' to 'y'.
After saving the "Custom.mk" file, try test again, starting from the
very beginning of this step.







STEP 7: 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 8: 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:

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>

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.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 9: Test Apache configuration and Set 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-data

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-data"


Assuming the page displays, follow the instructions shown in your web
browser. (If it doesn't display, see the note at the end of this step.)
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-data", and therefore the command you need to run from the "src" directory
as "root" is

src> ./set_dirs www-data

The Apache group is often "www-data", but your installation might be
different. 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
Setting up ../surveys
Setting up ../images
Setting up ../chat
Setting up ../auto_update
Setting up ../courses
Setting up ../users

[Caution]

MAKE SURE YOU RUN THE COMMAND AS ROOT, or the permissions will not be
set properly.

[Note]

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 may be something
wrong with the Apache configuration you did in the previous step:
Configure Apache

Another possible reason for not being able to visit the "apache_group"
URL is that the access rights for the "bin" directory are not sufficient
to allow Apache to run the "apache_group" program. We're in what's
sometimes called a "catch 22" situation - we need to run a script to set
the file permissions, but we can't run that script because the file
permissions are incorrect.

There's a few things you can do. First, try making the permissions "wide
open" on Manhattan's bin directory. (use something like "chmod 777 bin"
executed from the Manhattan installation directory. Try to access the
"apache_group" URL again.

You can also try looking in Apache's configuration files for the "Group"
setting, or in the your server's "/etc/group" file for the group used by
Apache. Or you can guess the group when you run the "./set_dirs" script.
Ubuntu (and others) use "www-data". You can also try "www", which is
also commonly used.

Even if your file permissions look correct, all bets are off if you are
running some versions of Fedora or other distributions that are based on
"selinux". See the section "Installing Manhattan under Fedora 8 and
selinux" near the top of this file.

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 10: Initialize and test your configuration

[Warning]

Do NOT skip this step! Before version 3.3, this was an optional step.
From version 3.3 forward, you MUST visit the "config_test" URL as
explained below to initialize an important configuration file.

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.

Visiting this URL serves two purposes. The first is to initialize the
configuration of your Manhattan installation. Manhattan's server
configuration is stored in the text file
"/home/manhat/manhat-x.x.x/manhat.conf" If you've worked with Manhattan
before, the "manhat.conf" file replaces the old "custom.h" file that was
previously used to configure a Manhattan installation. Visiting the
"config_test" URL runs a program that creates a default "manhat.conf"
file, if one does not already exist. (You'll examine these default
values as the last step in the installation in Configure your server.)

The second reason to visit the "config_test" URL is to perform a few
tests on your installation. For example, tests are included for your
Apache "ServerName" setting, and to make 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.

Here's a screenshot of a portion of the "config_test" web page:

The Configuration Tester







STEP 11: Create a Super User account

The next step is to create an account that will be used to enter
Manhattan's web-based administration system.

Point your web browser to:

http://YOURSERVER.edu/manhat-sbin/super_conf

Replace "YOURSERVER.edu" with the name of your server. Use the form you
see to create the super user account:


You'll need to enter a "username" and "password" for this super user. A
good username might be your first initial followed by your last name,
all in lowercase letters with no spaces. A good password is, well, a
good password.

Think a bit when you select the username. Whatever you select you'll be
using from now on. The password can be changed as often as you wish.

[Warning]

After submitting the form, you will have created the Super User account,
and the above URL will no longer work. For the best protection, you
should delete the "super_conf" CGI program, so it can never be run again
from a web browser. Login to the server using the "manhat" shell
account, then:

cd manhat-x.x.x/sbin
rm super_conf

You'll be shown a page summarizing the Super User account information.
At the bottom of the page is a link that you can click on to login to
the administrative system for the first time.



[Note]

If, when you click on the link shown above to login to the
Administrative system, your web browser cannot locate the web site, it's
likely that the "ServerName" is set improperly in Apache's "httpd.conf".
You should revisit the configuration test page as described in
Initialize and test your configuration







STEP 12: Configure your server

Log in to Manhattan's administrator's system by pointing your web
browser to:

http://YOURSERVER.edu/manhat-sbin/super_doorstep

and entering the Super User username and password you set in Create a
Super User account above.

Next, select: Server --> Configure Server from the menu:


You'll see a table of parameters that control how your Manhattan
installation will behave.


You can click on the "Edit" link to learn more about, and possibly
change, each item on the list.


[Note]

Before Manhattan version 3.3 these options were stored in a "config.h"
file, which you had to modify by hand before compiling the Manhattan
source code. If you are upgrading from Manhattan 3.2 or earlier, you
should compare these entries to the values found in your old
"src/config.h" file.

You usually don't need to spend a lot of time understanding these
options, but it's worth a few minutes of your time to get a general idea
of what your options are. The parameters and their use are listed in the
chapter Server Configuration within the Administrator's Reference.



WHAT NEXT? Follow the tutorial in the Administrators Reference available
from http://manhattan.sf.net






### END OF DOCUMENT ###