6. Configuring OpenACS itself

6.1 What is where (OpenACS directories and what is inside each of them)

• /bin - executables used by the toolkit (e.g. WatchDog)
• /parameters - OpenACS configuration file(s)
• /tcl - OpenACS Tcl scripts library. Your AOLserver config needs to point to here as its Tcl library. The definitions for the modules are here.
• /templates - where templates are stored. Templates modify how a page is displayed according the user's preference (e.g. text x graphics) and language (e.g. with language extensions .fr, .pt, etc.) Not all modules are template-enabled yet, but expect that to change in ACS 4.
• /users - user specific files. Used by the home page module for example.
• /www - Where all the pages live. Each module has a subdirectory here (e.g. www/bboard)
• The www/register directory contains the login and registration scripts. You can easily redirect someone to /register/index.tcl to have them login or register. [1]
• The www/pvt directory is for user-specific pages. They can only be accessed by people who have logged in. [1]

6.2 Configuring OpenACS

• In the parameters directory of the OpenACS tree, rename the ad.tcl file to the name of the virtual server you are running in AOLserver (server1.tcl for example)
• Each module of the ACS is configured in the sections of this file, with a heading such as ns/${server}/acs (if you are using the included ad.tcl file). If you are using .ini file, than the headers will look like [ns/server/yourservername/acs]. In this case, replace all ocurrences of yourservername with the actual name of the virtual server configured in AOLserver (such as photonet, or server1).
• Edit the parameters to fit your needs, otherwise your website will show "Yourdomain Network" and "webmaster@yourdomain.com" all over. "If you want to change how some of these are used, a good place to look is /web/yourdomain/tcl/ad-defs.tcl." [1] There are lots of comments in the file to help you out and the documentation of each individual module can be found at http://openacs.org/doc.
• READ THE CAVEAT in section 6.5 if you choose to save encrypted password in the db (EncryptPasswordsInDBP=0or ns_param EncryptPasswordsInDBP "0" in nsd.ini or nsd.tcl respectively).

6.3 Configuring Permissions [1]

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 (this directory is already protected in latter OpenACS releases).
• any private admin dirs for a module you might have written that are not underneath the /admin directory

6.4 Adding Yourself as a User and Making Yourself a Sysadmin [1]

The ArsDigita Community System will define two users: system and anonymous. It will also define a user group of system administrators.

After starting AOLserver, you'll want to:

• add yourself as a user to the system, at http://yourservername.com/register/
• add yourself as as member of the site-wide administration group. To do this, log out as yourself (there's a link at "Your Workspace" http://yourservername.com/pvt/home.tcl ) and then log in as the system user (email of "system"). Change the system user's password (the default is "changeme"). Visit the the User Groups Admin pages at http://yourservername.com/admin/ug/ and add your personal user as a site-wide administrator.

Now you're bootstrapped!

6.5 CAVEAT for those that want encrypted passwords in the DB

If you want to save encrypted passwords in the database, you'll have to do some things manually to get ACS working because the default users "system" and "anonymous" come with plain text passwords.

This is what you need to do:

1. create a login for you (as described above). Your password will be saved encrypted in the database. Go into psql and do a "select user_id,first_names,password from users;" to see all the users in your database.
2. Next, change the system user password for the password of the user you just created. Let's say the encrypted password for your user was something like "0xabcdef" (or whatever), then do a "update users set password='0xabcdef' where user_id=1;"
3. Now go back to your browser, and logout as your user (from http://yourservername.com/pvt/home.tcl), login as system with the same password you used for your user, add your user to the administration group as described above, and then change the system and anonymous passwords (from http://yoursername.com/admin/users).

6.6 Closing Down Access [1]

The ACS ships with a user named "anonymous" (email "anonymous") to serve as a content owner. If you're operating a restricted-access site, make sure to change the anonymous user's password (the default is "changeme").

6.7 Making sure that it works (and stays working)

Run the acceptance tests in http://photo.net/doc/acceptance-test.html.

Note: The first part of the above page is aimed at the original version of ACS for Oracle. You can replace that first part by going to psql (PostgreSQL interactive SQL tool) and doing some tests:

$ su - youraolserveruser

$ psql yourdb

yourdb# \d

yourdb# select * from users;

The first psql command is going to list all your tables (under PG 6.5) or all your relationships (under PG 7) and the second will show all the records in the users table.

The other sections of the acceptance-test can be used either under the Oracle or the PostgreSQL versions of the ACS.

6.8 Ensure that your service automatically starts on boot (or any other time the service dies).

This section was taken from The Hitchhiker's Guide to the ACS, written by the ArsDigita folks.

This step should be completed as root. This can break every service on your machine, so proceed with caution.

• Copy this restart-aolserver into /tmp/restart-aolserver.txt
• This script needs to be SUID-root, which means that the script will run as root. This is necessary to ensure that the aolserver processes are killed regardless of who owns them. However the script should be in the web group to ensure that the users updating the web page can use the script, but that general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in /usr/local/bin.

$ su - ; Enter root password.

# cp /tmp/restart-aolserver.txt

/usr/local/bin/restart-aolserver

# chown root.web /usr/local/bin/restart-aolserver

# chmod 4750 /usr/local/bin/restart-aolserver

# ln -s /usr/bin/perl /usr/local/bin/perl

# su - nsadmin

• Test the restart-aolserver script by making sure all servers are dead, starting a new server, and then killing it. You should see the following lines. nsadmin and typing

$ killall -9 nsd

nsd: no process killed

$ /home/aolserver/bin/nsd -u nsadmin -g web -t /home/aolserver/service_name.tcl

$ restart-aolserver service_name

Killing 23727 23728 23729 23730

$ killall -9 nsd nsd: no process killed

The numbers indicate the process ids (PIDs) of the processes being killed. It is important that no processes are killed by the second call to killall. If there are processes being killed, it means that the script is not working.

• Assuming that the restart-aolserver script worked, login as root and open /etc/inittab for editing.

$ su - ; Enter root password

# emacs -nw /etc/inittab

• Copy this line into the bottom of the file as a template, making sure that the first field nss is unique.

nss:2345:respawn:/home/aolserver/bin/nsd -u nsadmin -g web -t /home/aolserver/service_name.tcl
 

• Important: Make sure there is a newline at the end of the file. If there is not a newline at the end of the file, the system may suffer catastrophic failures.
• Still as root, enter the following command to re-initialize /etc/inittab.

# killall -9 nsd

# /sbin/init q

• Important: See if it worked by running the restart-aolserver script again.

# restart-aolserver service_name Killing 23750 23753 23754 23756

If the processes were killed, congratulations, your server is now automated for startup and shutdown.