OpenACS may sound extremely complex, but it actually consists of only four parts: 1) an installed PostgreSQL or Oracle server; 2) AOLserver, compiled with nsxml (the XML-parsing module for AOLserver), the PostgreSQL and/or Oracle driver and an appropriate configuration file; 3) the OpenACS data model; and 4) OpenACS Tcl libraries, Tcl pages and ADP pages.

Until version 4.x, installing OpenACS was straightforward. You installed PostgreSQL and AOLserver, loaded the OpenACS data model using the psql command-line client, copied the OpenACS libraries, Tcl pages and ADP pages into the appropriate directory and began to use the system.

But this approach led to a number of problems, most of which stemmed from the installation's inflexibility. What if I want forums under two different URLs, rather than the default /bboard? What if I want to install only two or three packages, rather than all 40? What if I want to upgrade the e-commerce solution, without also upgrading the FAQ system?

The solution to this problem is the ArsDigita Package Manager, introduced in ArsDigita's ACS 4.x and adopted by OpenACS 4.x. Each application has been renamed a “package” and consists of a data model, .xql files, Tcl libraries, Tcl pages and ADP pages, as well as documentation. Each package can be installed at any number of URLs on the system and can have arbitrary permissions associated with it (using the system of users and groups that are central to OpenACS). Each package also may define one or more parameters, giving custom information each time it is instantiated.

If you install OpenACS in /web/openacs4, then the www directory contains all of the top-level Tcl and ADP pages, the tcl directory contains the top-level Tcl libraries, and the packages directory contains each of the packages loaded onto the system.

Once a package is in the filesystem, you can use the OpenACS web-based installer program to create the package-specific data model in the database. Finally, the site administrator makes the package available by mounting it (one or more times) via the administrative site map. Once mounted, an application is available via the named URL.

Installing OpenACS

Now that I've explained much of the theory behind OpenACS, we're ready to install it. Note that installation is relatively complex, because it involves a number of packages that must be installed with particular ownerships and permissions. The OpenACS 4.5 installation process is smoother and easier than previous versions, but it is still surprisingly easy to make a mistake along the way.

Before beginning, make sure that PostgreSQL 7.1.3 is installed, including the server, client and development libraries. The newest version of PostgreSQL (7.2) has a few subtle incompatibilities with older versions that can make it difficult to install OpenACS. While there are certainly a number of improvements in 7.2, you should be fine using 7.1.3.

Also, make sure you have installed libxml 2.x; on Red Hat systems, you should make sure the libxml2 and libxml2-devel RPMs are both installed. Without these, OpenACS won't be able to open the .info package associated with each file, as well as the .xql files used by the query dispatcher.

Next, install AOLserver, ensuring that /usr/local/aolserver is owned by the nsadmin user:

# mkdir /usr/local/aolserver
# useradd nsadmin
# chown -R nsadmin /usr/local/aolserver

Rather than installing the stock version of AOLserver, applying the patches that ArsDigita and the OpenACS crew have written over the years and separately downloading the PostgreSQL and XML-parsing modules, you should download the all-in-one version known as “Matt's AOLserver distribution” (see Resources).

Next, create a PostgreSQL user named openacs4, giving it full privileges. (PostgreSQL has its own list of users that is independent of the UNIX list.) In general, such activities must be performed as the postgres user, rather than as root:

# su postgres
# createuser openacs4
  Shall the new user be allowed to create
    databases? (y/n) y
  Shall the new user be allowed to create
    more new users? (y/n) y

Now, use this new PostgreSQL user to create a new database, which we will call openacs4:

# createdb -U openacs4 openacs4
Following this, install the OpenACS package itself while logged in as the root user. You can download the latest release (openacs-4-5-release.tgz) from Traditionally, this package is unpacked under the /web hierarchy:
# mkdir /web
# cd /web
# tar -zxvf /tmp/openacs-4-5-release.tgz
# mv /web/openacs-4 /web/openacs4
# chown -R nsadmin.nsadmin /web
With the completion of this step, all of the major pieces are in place. What remains is to tie all of these pieces together in the AOLserver configuration file. The easiest starting point for this is to download the file openacs4.tcl.txt from, rename it openacs4.tcl, place it in /usr/local/aolserver and edit it in the following ways:
  • Modify the httpport to reflect the port on which you want the server to run. By default, HTTP servers run on port 80; in the sample configuration, it is set to 8000.

  • Modify the hostname and address settings (lines 14 and 15) to the actual hostname and IP address of the computer on which you want to run your system. In theory, the Tcl code in openacs4.tcl will find your hostname and IP address automatically. But if your computer has more than one name or IP address, or if you want to use localhost as the hostname for testing, then you will have to set this manually.

  • Change line 17 to the name of the server and database you wish to use, which should be the name of the directory within /web where the OpenACS software is installed. Thus, if you put the OpenACS software under /web/foo, you should also name your database foo. The server variable on line 17 also should be set to foo.

  • Change line 18 to reflect the human-readable name of the on-line community you wish to create.

  • On each of the lines where you see ns_param user nsadmin change the value (nsadmin) to openacs4, the name of the PostgreSQL user that created the database. You must do this for all three of the database connection pools AOLserver opens to PostgreSQL, known as main, log and subquery.

Once you have made these changes, you should be ready to start the system. As root, start the server in foreground mode:

# cd /usr/local/aolserver
# ./bin/nsd -f -u nsadmin -g nsadmin \
  -t openacs4.tcl

You should see a lot of debugging information on your screen, scrolling by faster than you can possibly read. When the scrolling stops, you should see something toward the end that looks like this:

  Notice: nssock: listening on
  Notice: nssock: starting
  Notice: nssock: accepting connections
If you do, point your web browser to http://localhost:8000/. If all is well, you should see a welcome message from the OpenACS installer. Now, follow the directions to create the system, clicking the next button at the bottom as it appears. Note that the installation process may take awhile, because the installer creates a large number of database tables. Toward the end of the installation process, you will be asked for the e-mail address of the OpenACS administrator, as well as other system parameters.

The final page welcomes you to OpenACS and informs you that AOLserver has been terminated. (This is necessary, so as to load all of the newly installed Tcl library files into AOLserver's memory.) Restart the server, point your browser at http://localhost:8000/ once again, and OpenACS will be ready and waiting for you.

At this point, OpenACS is fully functional, but given that none of the packages have been installed, it won't do very much for you. In next month's At the Forge, we'll take a look at how to install and manage OpenACS packages.