ArsDigita Community System Installation

by Philip Greenspun

Prerequisites

It is helpful if you have Oracle interMedia Text for full-text searches. We're also trying to make our system work with the PLS System, available free from http://www.pls.com.

Your Oracle installation

The ACS requires that Oracle's NLS_DATE_FORMAT parameter be set to 'YYYY-MM-DD', as God intended it to be. See http://photo.net/wtr/oracle-tips for more details on how to bring Oracle into the ANSI age...

The "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 in the same Oracle init file.

Creating a chroot'ed environment

As of the arrival of AOLserver 3.0, we recommend running AOLserver and the ACS in a chroot "jail." This enhances security, limiting the likelihood of a rogue intruder damaging your system. For more details, see the security document.

This will require that all binaries you may need to access and all libraries those binaries may linked against be found under the jail's perimeter. We recommend this be located in the directory /webroot.

Your AOLserver installation

All ArsDigita software packages, including the ACS, rely on a basket of utility procedures that are generally part of the AOLserver installation. This used to be distributed separately and put in the shared Tcl directory (/home/nsadmin/modules/tcl), but is now a part of the ACS and exists in [acsdir]/tcl/ad-utilities.preload. Note that many other files in the tcl directory depend on utility functions defined in this file, which is why it is named as it is, so that it will be loaded before any of the other files.

All of our services are set up in accordance with the ArsDigita Server Architecture.

We place our entire AOLserver directory structure in /webroot/aol30.

Getting Ready to Untar

We recommend rooting webserver content in /webroot/web. Since most servers these days are expected to run multiple services from multiple IP addresses, each server gets a subdirectory from /webroot/web. For example, http://scorecard.org would be rooted at /webroot/web/scorecard on one of our machines and if http://jobdirect.com were on the same box then it would be at /webroot/web/jobdirect.

For the sake of argument, we're going to assume that your service is called "yourdomain", is going to be at http://yourdomain.com and is rooted at /webroot/web/yourdomain in the Unix file system. Note that you'll find our definitions files starting out with "yourdomain.com".

You'll now find that /webroot/web/yourdomain/www contains the document root and /webroot/web/yourdomain/tcl contains Tcl scripts that are loaded when the AOLserver starts up.

Feeding Oracle the Data Model

The entire server will behave in an unhappy manner if it connects to Oracle and finds that, for example, the users table does not exist. Thus you need to connect to Oracle as whatever user the AOLserver will connect as, and feed Oracle the table definitions.

Configuring AOLServer

Note: Because we're chroot'ing the webserver, its view of the filesystem begins at /webroot. So, it will actually see its content at /web.

Configuring ACS itself

If you want a system that works, you have to copy /web/yourdomain/parameters/ad.ini to /web/yourdomain/parameters/yourdomain.ini (or any other name different from ad.ini). You don't actually have to delete the ad.ini file. Each section has a hardcoded "yourservername" in the name. This means that the ad_parameter will ignore everything in ad.ini unless your AOLserver name happens to be "yourservername".

Once you've got a private copy of the aux .ini file, make sure to change "yourservername" to whatever you're calling this particular AOLserver (look at the server name in the main .ini file for a reference).

Unless you want pages that advertise a community called "Yourdomain Network" owned by "webmaster@yourdomain.com", you'll probably want to edit the text of /web/yourdomain/parameters/yourdomain.ini file to change system-wide parameters. If you want to change how some of these are used, a good place to look is /web/yourdomain/tcl/ad-defs.

Configuring Permissions

Now, you need to protect the proper administration directories of the ACS. You decide the policy. Here are the directories to consider protecting:

Adding Yourself as a User and Making Yourself a Sysadmin

The ArsDigita Community System will define two users: system and anonymous. It will also define a user group of system administrators. You'll want to add yourself as a user (at /register/ ) and then add yourself as as member of the site-wide administration group. Start by logging out as yourself and logging in as the system user (email of "system", password "changeme"). Change the system user's password. Visit the the https://yourservername.com/admin/ug/ directory and add your personal user as a site-wide administrator. Now you're bootstrapped!

Closing Down Access

The ACS ships with a user named "anonymous" (email "anonymous", password "changeme") to serve as a content owner. If you're operating a restricted-access site, make sure to change the anonymous user's password or ban the anonymous user from the system in addition to changing the system user's password.

Where to Find What

A few pointers:

Making sure that it works

Run the acceptance tests in /doc/acceptance-test

Reversing the whole process!

If you want to take an operating ArsDigita Community System and use it as the basis of a new toolkit release, then what you want is the script at /admin/conversion/make-acs-dist (only works if you have zsh installed). It plays some neat tricks such as
philg@mit.edu