Introducing AOLserver

Compiling AOLserver is relatively straightforward. Unlike Apache, which provides support via the apxs program for compiling modules after you have installed the server, AOLserver requires that all modules be compiled and installed together.

While creating this user and group is not mandatory, AOLserver will refuse to run as root for security reasons. So before you begin to compile and install AOLserver, you should create a new user and group on your system, traditionally called nsadmin. On my Red Hat 7.2 system, I simply say:

/usr/sbin/adduser nsadmin

While still logged in as root, I now create the /usr/local/aolserver directory, into which AOLserver is installed by default. I then give ownership of this directory to nsadmin:

mkdir /usr/local/aolserver
chown nsadmin.nsadmin /usr/local/aolserver

Once we've done this, I change to the nsadmin user, open the source code that I downloaded from openacs.org and begin the compilation process:

su - nsadmin
cd /tmp
tar -zxvf aolserver3.3ad13-oacs1-beta-src.tar.gz
cd aolserver
./conf

This will automatically configure, compile and install AOLserver according to your system's parameters, placing files under the directory /usr/local/aolserver. AOLserver automatically will try to compile whichever modules it can, ignoring (and excluding) any others. On my desktop machine, which has development libraries for PostgreSQL but not for Oracle, configuring and installing AOLserver in this way results in the inclusion of the PostgreSQL driver, but ignores the Oracle driver entirely.

The build process can take awhile and doesn't produce a great deal of output to the screen. If you are concerned that the process has somehow become frozen, you can look at the log/aolserver.log file; all of the compilation output can be found there.

When the build process is done, you will have a copy of AOLserver in /usr/local/aolserver. The most important directories under /usr/local/aolserver are bin, in which the AOLserver (nsd) program is located, along with the shared libraries (.so) for each of the modules that were compiled into the server. The log directory contains access and error logs for the server, and the lib directory contains the built-in Tcl interpreter.

AOLserver's configuration file is written in Tcl; a simple configuration file is placed by default in /usr/local/aolserver/sample-config.tcl. If you examine it, you will see that each of the configuration directives is actually a Tcl variable assignment. These variable assignments are divided into sections, where each section normally represents a module that was compiled into the server.

As you can see from the sample configuration file, you can assign literal values to variables. For example, you can set the HTTP port to which AOLserver listens to 8000 with the following:

set httpport 8000

Because the configuration file is written in Tcl, you also can set the homedir variable, which is /usr/local/aolserver by default, by asking AOLserver rather than hard-coding the value:

set homedir          [file dirname [ns_info config]]

And of course, you can base variable settings on the values of other variables, using simple interpolation:

set servername             "server1"
set pageroot ${homedir}/servers/${servername}/pages

Those two lines, from the sample configuration file that comes with AOLserver, configure the root of static URLs to be in /usr/local/aolserver/servers/server1/pages.

Other configuration settings are made with the ns_param command, which typically takes two parameters: a name and a value. Each parameter must come in a section, begun by a call to ns_section. For example, we can activate server debugging by turning on the debug parameter in the (global) ns/parameters section:

ns_section "ns/parameters"
ns_param   debug           false

Unfortunately, the documentation for AOLserver's parameters is quite lacking when compared with the on-line Apache documentation. An almost complete list of parameters is at aolserver.com/docs/admin/config-reference.tcl.txt, which demonstrates a server configuration that sets nearly everything.

Once you have finished configuring your system—and the default configuration is a good start for simple sites—you can start AOLserver by invoking the nsd program and specifying the name of the configuration file you want to use:

cd /usr/local/aolserver
bin/nsd -f -t sample-config.tcl

The -f option runs AOLserver in the foreground, sending the error log to your screen. Once you feel comfortable with what's happening, you can remove the -f, looking in the log directory for your server's error log.

If you want AOLserver to listen to port 80, then you must start it as root. Otherwise, Linux will refuse to honor the request, telling you that only the superuser can start servers that listen to “privileged” ports (i.e., less than 1024). If only root can listen to port 80, but AOLserver refuses to run as root, how can you serve port 80? By starting AOLserver as root and passing it options to indicate the user and group to which it should switch:

su root
cd /usr/local/aolserver
bin/nsd -f -u nsadmin -g nsadmin -t \
  sample-config.tcl

You should now be able to point your browser at http://yourhost.yourdomain.com:8000/ and see the introductory AOLserver document, welcoming you to this new server. Note that AOLserver's configuration file looks for both your computer's name and its IP address, so if you are connected to a network, you will not be able to point your browser to localhost, but will instead need to use its full name.