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".
- download acs.tar into /tmp/acs.tar
- cd /webroot/web/
- tar xvf /tmp/acs.tar (creates a directory "acs")
- mv acs yourdomain
- chmod 777 yourdomain/users (if you plan on using the homepage module)
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.
- load the
states, country_codes and counties tables
using the load-geo-tables shell script in the
/webroot/web/yourdomain/www/install
directory. This relies on the Oracle SQL*Loader utility, documented
at http://photo.net/sql/ref/utilities
- cd to /webroot/web/yourdomain/www/doc/sql/ and feed Oracle the .sql files that
you find there. There is a meta-loader file, load-data-model.sql, that includes
the other files in the proper order. To use it, run
sqlplus foo/foopassword < load-data-model.sql
- If you have interMedia installed, while still in /webroot/web/yourdomain/www/doc/sql/, run
./load-site-wide-search foo foopassword ctxsys-password
Note that there's no slash between foo and foopassword here. The third
argument, ctxsys-password, is (obviously) the password for interMedia
Text's special ctxsys user.
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.
- the community system depends on the existence of three database
pools: main, subquery, and log. They must be named as such. The
default pool will be "main".
- you can only have one ArsDigita Community System running from a
single nsd process (though you can have as many ACS servers as you like
on a physical machine; each just needs its own process). A big reason
for this is that in the [ns/parameters] section of the AOLserver .ini
file you need to say
auxconfigdir=/web/yourdomain/parameters
- Tell AOLserver that its pageroot is /web/yourdomain/www/
- Tell AOLserver that the TclLibrary is /web/yourdomain/tcl
(this will be the server's Private Tcl library)
- in the [ns/parameters] section of your AOLServer .ini file, add
the following:
StackSize=500000
This allows your to recurse a bit in Tcl and still use our Oracle
driver (which allocates 40,000 bytes on the stack when called).
- in the [ns/server/yourservername] section, if you want to use our
fancy custom error responses and such, put in
NotFoundResponse=/global/file-not-found
ServerBusyResponse=/global/busy
ServerInternalErrorResponse=/global/error
ForbiddenResponse=/global/forbidden
UnauthorizedResponse=/global/unauthorized
then go into the /www/global/ directory and edit these files to suit.
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:
- /doc (or at least /doc/sql/ since some AOLserver configurations
will allow a user to execute SQL files)
- /admin
- any private admin dirs for a module you might have written that are
not underneath the /admin directory
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:
- the /register directory contains the login and registration scripts. You
can easily redirect someone to /register/index to have them login
or register.
- the /pvt directory is for user-specific pages. They can only be accessed by people who have logged in.
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
- leaving backup files behind
- leaving random custom .ini files from the /parameters dir behind
- rerooting the files at "acs" (rather than "yourservername")
philg@mit.edu