The Toolkit for Online Communities
18433 Community Members, 0 members online, 1794 visitors today
Log In Register
OpenACS Home : xowiki : Weblog
Search · Index
Previous Month May 2015
Sun Mon Tue Wed Thu Fri Sat
26 27 28 29 30 (7) 1 2
3 4 5 6 7 8 9
10 11 12 13 14 15 16
17 18 19 20 (1) 21 (2) 22 23
(1) 24 25 26 27 28 29 30
31 1 2 3 4 5 6

Popular tags

ad_form , ADP , ajax , aolserver , asynchronous , bgdelivery , bugtracker , COMET , cvs , debian , emacs , fedora , FreeBSD , hstore , includelets , install , installation , installers , javascript , libthread , linux , monitoring , munin , NaviServer , nginx , nx , OmniOS , oracle , osx , patches

No registered users in community xowiki
in last 30 minutes




Filtered by category Subsystems Documentation, 1 - 76 of 76 Postings (all, summary)

Installing OpenACS

Created by OpenACS community, last modified by Gustaf Neumann 01 May 2015, at 10:00 AM

There are many ways to get OpenACS working for you quickly and/or easily. See Try OpenACS for demonstrations and hosting solutions.

Packaged installations

For platforms like Linux/Ubuntu, Linux/Debian, FreeBSD or Windows, one can use the packaged solutions:

Generic installation scripts

For many Linux platforms (e.g. Ubuntu, Debian, Fedora), one can use the generic installer that compiles all base components (using Naviserver) and creates users/groups as needed; which works with Postgres 9.2 or newer. These install scripts can be as well used on Mac OS X, when MacPorts  are installed. These installer scripts are regularly updated.

The following alternative script installs aolserver and the contained modules from sources. It assumes, that PostgreSQL is already installed:

  1. Install AOLserver: http://openacs.org/storage/view/aolserver/install.tgz 
  2. Install OpenACS: en:openacs-subsystem-install

Manually installing OpenACS:

These are the steps involved in setting up OpenACS. Before beginning, read about ways of getting help (en:docs-admin-help) during installation. Also, read the documentation completely before beginning, to minimize the chance of any surprises during installation.

  1. Prerequisites to installing OpenACS
  2. OpenACS reference platform
  3. Install a *nix based operating system
  4. Get the code
  5. Install Oracle
  6. Install PostgreSQL
  7. Install Tcl
  8. Install AOLserver
  9. Install OpenACS distribution

These pages contain notes where installing OpenACS on a specific OS different from the *nix standard installation instructions (above).  These notes also refer to helper scripts and automated installers that can really simplify installation:


Created by OpenACS community, last modified by Gustaf Neumann 01 May 2015, at 09:37 AM

Tcl is a Turing Complete, open-source, embeddable interpreted language. OpenACS additionally, uses these modules:

What others say about Tcl

  • Tcl (tcl.tk)
  • testimonials on tcl.tk
  • Tcl the misunderstood
  • Tcl/Tk is perhaps the most mature of the dynamic languages, dating back to 1988. The evolution of the language over the last 20 years has been marked by passionate preservation of the balance between maintaining simplicity and utility with the adoption of new ideas and new techniques based on accumulated experience.

    Tcl/Tk is used in a number of prominent software systems including DejaGnu (e.g. used for testing the gcc compiler), Expect and AOLserver. The language is used by many scientific organizations including NASA as well as being used extensively in the commerical and financial sectors. ( http://wiki.tcl.tk/20832 )

Using Tcl

Install OpenACS with NaviServer from Scratch

Created by Gustaf Neumann, last modified by Gustaf Neumann 01 May 2015, at 09:24 AM

This page describes how to install OpenACS with NaviServer on Unix-like systems (e.g. Linux, Mac OS X, Solaris, OmniOS) by compiling all but PostgreSQL from scratch, guided by script that collects the components from various sources, compiles it, etc.

The installation is done in two steps:

  • install-ns.sh : Install NaviServer and its components for a PostgreSQL installation from scratch by obtaining the relevant sources and compiling it. The script assumes PostgreSQL to be installed (or obtainable via package managers), but installs all other components by obtaining it from the source repositories and compiling it from scratch (e.g. Tcl, tcllib, tDOM, libthread, nsf/XOTcl 2).

  • install-oacs.sh : Install OpenACS from CVS/git. This script configures a (pre-installed) PostgreSQL installation for
    OpenACS, adds hstore, installs OpenACS core, basic OpenACS packages, xowiki, xowf and optionally dotlrn from CVS/git and generates a config file and startup files (for Ubuntu and Fedora Core). The script assumes a pre-existing NaviServer installation, installed e.g. via install-ns.sh

 These install scripts are frequently updated when now components are released or problems are detected (commit log ).

If you open the links above, use save-as in the browser to save the files. Alternatively, download the files as .zip file or clone the repository via GitHub .

   cd /usr/local/src
   git clone https://github.com/gustafn/install-ns
   cd install-ns
The scripts work under a typical Linux installation (e.g. Ubuntu, Fedora Core) as well as on Mac OS X or on OmniOS. The scripts are tested with PostgreSQL 9.1, 9.2 and 9.3 on Ubuntu 12.04, 13.04, 14.04 and Fedora Core 18.

On a a fresh Ubuntu installation, you should be able to download the two scripts from this page and install OpenACS with NaviServer in the following steps:

   sudo bash

   bash install-ns.sh
   bash install-ns.sh build

   bash install-oacs.sh
   bash install-oacs.sh build

After running both scripts in the default configuration you will see e.g. on Ubuntu 14.04

Congratulations, you have installed OpenACS with NaviServer on your machine.
You might start the server manually with
    sudo /usr/local/ns/bin/nsd -t /usr/local/ns/config-oacs-5-8.tcl -u nsadmin -g nsadmin
or you can manage your installation with upstart (Ubuntu/Debian). In this case, you might use the following commands
    initctl status oacs-5-8
    initctl start oacs-5-8
    initctl stop oacs-5-8
To use OpenACS, point your browser to http://localhost:8000/ The configuration file is /usr/local/ns/config-oacs-5-8.tcl and might be tailored to your needs. The generated startup file is in /etc/init/oacs-5-8.conf. The access.log and error.log of this instance are in /var/www/oacs-5-8/log

On Fedora, the startup commands for systemd are

    systemctl status oacs-5-8
    systemctl start oacs-5-8
    systemctl stop oacs-5-8

The generated startup file for RedHat/Fedora is in /lib/systemd/system/oacs-5-8.service


Created by OpenACS community, last modified by Maurizio Martignano 15 Apr 2015, at 12:38 AM

OpenACS and .LRN can be installed as native Win64 applications for Windows 8, Windows 8.1, Windows Server 2012 and Windows Server 2012 R2 using the Windows-OpenACS distribution.

The current release is Windows-OpenACS version 2.6 (released April 2015).

For more details, http://www.spazioit.com/pages_en/sol_inf_en/windows-openacs_en/ .

Monitoring Naviserver

Created by Gustaf Neumann, last modified by Gustaf Neumann 17 Feb 2015, at 11:11 AM

Munin  is a popular web-based tool to monitor several website. Munin provides a simple plugin mechanism for adding new kinds of sources, such as e.g. the NaviServer plugins  for monitoring NaviServer.

The monitoring information collected by munin can be placed at different web servers, one finds usually information about apache and friends. In general older versions of munin (before 2.0) supported only static pages, whereas newer version support as well dynamic information (with additional features such as zooming).

For static munin pages, it is the easiest to place in OpenACS sites the output directory either under the main www directory, or under the subsite admin directory (packages/acs-subsite/www/admin/).

For the cgi-setup, one has to make sure to load nscgi in the statup files of NaviServer and to point the urls to the appropriate directories. The sample setup below uses the directories of munin as provided by a standard munin setup on an Ubuntu system.

ns_section ns/server/${server}/modules
   ns_param   nscgi        nscgi.so

ns_section "ns/server/${server}/module/nscgi"
   ns_param map  "GET /munin-cgi/munin-cgi-graph /var/www/cgi-bin/munin-cgi-graph"
   ns_param map  "GET /munin-cgi/static /etc/munin/static/"
   ns_param map  "GET /munin-cgi /var/www/cgi-bin/munin-cgi-html"

OpenACS compatibility matrix

Created by Joel Aufrecht, last modified by Gustaf Neumann 13 Jan 2015, at 09:23 AM

OpenACS requires, at a minimum, an operating system, database, and web server to work. Many additional programs, such as a build environment, Mail Transport Agent, and source control system, are also needed for a fully effective installation.

Table 2.2. Version Compatibility Matrix

OpenACS Version 3.2.5 4.5 4.6 4.6.1 4.6.2 4.6.3 5.0 5.1 5.2 (core)
5.3 (core)
5.4 (core)
5.5 (core)
5.6 (core)
5.7 (core)
5.8 (core)
AOLserver 3 Yes No
3.3+ad13 Maybe Yes No
3.3oacs1 Maybe Yes No
3.4.4 No
3.4.4oacs1 Maybe Yes No
3.5.5 Maybe Yes No
4.0 Maybe Yes No
4.5 No Yes
NaviServer 4.99.4 - No Maybe Yes
Tcl 8.4 Yes No
8.5.4 - Maybe Yes
PostgreSQL 7.0 Yes No
7.2 Maybe Yes No
7.3.2 - 7.3.x No Yes No
7.4 No Yes No
8.0 No Maybe Yes Maybe
8.1 No Yes Maybe
8.2 No tar: no, CVS: Yes Yes Maybe
8.3 No Yes Maybe
8.4 No Yes
9.0 - 9.4 No Yes
Oracle 8.1.6 Maybe Yes Maybe
8.1.7 Maybe Yes Maybe
9i No Yes Maybe
10g No Yes Maybe
11g No Maybe

The value in the cells correspond to the last version of that release, and not necessarily to all minor releases. Empty cells denote an unknown status.

Installing OpenACS on FreeBSD with ports

Created by Gustaf Neumann, last modified by Gustaf Neumann 04 Sep 2014, at 07:47 PM

NEW:  For the impatient users there is a quick-and-dirty install guide for FreeBSD

OpenACS and .LRN are included in the current FreeBSD ports tree.
The ports are tested with FreeBSD production version 6.2-RELEASE, old stable 5.5-RELEASE and the development branch 7-CURRENT.

Installation requirements:

  1. FreeBSD operating system with root access rights.
  2. Installed and updated FreeBSD Ports Collection (for updating see Appendix A below)
    (alternative: installing from packages, see Appendix B)

To install OpenACS or .LRN from the FreeBSD ports tree, follow the instructions below.

1. Installing and configuring PostgreSQL

NOTICE: If you have a PostgreSQL server installed and running, skip to Section 2.

If you desire to use a local PostgreSQL server (most users do), install the server first.
We recommend using PostgreSQL version 8.2 from the databases/postgresql82-server port

# cd /usr/ports/databases/postgresql82-server # make install clean

NOTICE: As an alternative, you may install PostgreSQL server from a binary package. See Appendix B below

The plperl language is required for OpenACS/.LRN. This can be installed from the ports with the following commands:

# cd /usr/ports/databases/p5-postgresql-plperl # make install clean

To install the OpenACS/.LRN database, your PostgreSQL server must be running.
You need to enable it in your /etc/rc.conf (or /etc/rc.conf.local) by adding the following line:


After installing the PostgreSQL server, you have to initialize your data store:

# /usr/local/etc/rc.d/postgresql initdb

To start the PostgreSQL server, issue the following command:

# /usr/local/etc/rc.d/postgresql start

You can check if the server is up and running with:

# /usr/local/etc/rc.d/postgresql status

2. Installing OpenACS / .LRN

2.1 Installing the OpenACS or .LRN port 

OpenACS can be installed directly from the FreeBSD ports tree, www/openacs:

# cd /usr/ports/www/openacs
# make install clean

.LRN installation, www/openacs-dotlrn:

# cd /usr/ports/www/openacs-dotlrn
# make install clean

NOTICE: If you want to make changes to the default configuration, the AOLserver configuration files for OpenACS/.LRN files are located at:

NOTICE: If you installed both OpenACS and .LRN ports, you have to change the default port of one of the installations. See the configuration files in the previous notice.

2.2 Creating the OpenACS/.LRN database 

For this step, you require an installed and running PostgreSQL server (see Section 1) and installed OpenACS/.LRN (see Section 2.1)

First we need to adjust the PostgreSQL configuration (this applies for server versions 8.1.x and higher):

# /usr/local/share/doc/openacs/adjust_pgsql_conf.sh

or if .LRN was installed: 

# /usr/local/share/doc/dotlrn/adjust_pgsql_conf.sh

NOTICE: You can adjust the configuration manually (standard location: /usr/local/pgsql/data/postgresql.conf)
Please see en:How_to_install_in_Postgres_8.x.

The PostgreSQL server needs to be restarted after changing the configuration:

# /usr/local/etc/rc.d/postgresql restart

Next, we can create a default OpenACS database by running the following script:

# /usr/local/share/doc/openacs/create_sampledb.sh

To create a default .LRN database, run the following script:

# /usr/local/share/doc/dotlrn/create_sampledb.sh

2.3 Starting OpenACS/.LRN and finalizing installation 

To make use of the automatic startup script OpenACS/.LRN has to be enabled in /etc/rc.conf (or /etc/rc.conf.local):


or for .LRN:


To start OpenACS, use the following command:

# /usr/local/etc/rc.d/openacs start

To start .LRN, use the following command:

# /usr/local/etc/rc.d/dotlrn start

Now you can login to your OpenACS/.LRN system and finalize the installation.
The default port is 8000. URL:


After filling your e-mail address, password and other important information OpenACS/.LRN gets installed, but the server stops.
You have to start it again (see above).

 A. Updating the FreeBSD ports tree

To get the latest versions of the OpenACS, .LRN and other FreeBSD ports, it is recommended to update the FreeBSD ports tree on a regular basis. The easiest way to to perform this task is using the portsnap(8) command.

For documentation, refer to the following FreeBSD Handbook chapters:
Using the Ports Collection
Using Portsnap

B. Installing from binary packages

PostgreSQL, OpenACS, .LRN and all dependent ports may be installed from binary packages, too.
This installation can be performed from a submenu of FreeBSD's sysinstall(8) command: Configure/Packages

OpenACS and .LRN are located in subcategory www, PostgreSQL is in subcategory databases.

C. Contact information and bug reporting

Please send bug reports and feature suggestions to the port maintainer of OpenACS/.LRN FreeBSD ports:
Martin Matuska

Installing OpenACS on FreeBSD

Created by OpenACS community, last modified by Gustaf Neumann 04 Sep 2014, at 07:33 PM

OpenACS and .LRN are available via FreeBSD ports. See en:openacs-system-install-freebsd-ports.

The following notes are useful if you decide to follow the OpenACS manual installation process using FreeBSD. These notes include points where a manual FreeBSD install differes from the slow, manual en:openacs-system-install.

The following information is pulled from: http://openacs.org/forums/message-view?message_id=312823 and http://openacs.org/forums/message-view?message_id=136910 and http://openacs.org/forums/message-view?message_id=312823

The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different shell, you will need to substitute your shell's conventions for setting environment variables when appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use wget to download software.

Note that on most linux distributions, GNU Make is simply named make and there is no gmake, whereas on BSD distributions, make and gmake are different --use gmake.

Change the period separating user.group in chown commands to use a colon ":" instead. For example,




Should you decide to install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

Installing tdom

FreeBSD can use the standard tdom from ports when installing manually, without going the extra step of installing tdom within the aolserver src tree.

Installing en:postgresql

Creating postgres user

To set defaults for new users or special service users you may create, edit the file /etc/share/skel/dot.profile instead of /etc/profile

To create the user, we need to add more parameters to match what is expected from creating a user in linux.

[root src]# mkdir -p /usr/local/pgsql
[root src]# pw groupadd -n web
[root src]# pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
[root src]# chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
[root src]# chmod -R 750 /usr/local/pgsql
[root src]#
mkdir -p /usr/local/pgsql
pw groupadd -n web
pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash
chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
chmod -R 750 /usr/local/pgsql

Set PostgreSQL to start on boot

[root ~]# cp /tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
[root ~]# chown root:wheel /usr/local/etc/rc.d/postgresql.sh
[root ~]# chmod 755 /usr/local/etc/rc.d/postgresql.sh
[root ~]# 
cp /tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh
chown root:wheel /usr/local/etc/rc.d/postgresql.sh
chmod 755 /usr/local/etc/rc.d/postgresql.sh

Test the script

[root ~]# /usr/local/etc/rc.d/postgresql.sh stop
Stopping PostgreSQL: ok
[root ~]# 

If PostgreSQL successfully stopped, then turn it back on because we'll use it later.

[root root]# /usr/local/etc/rc.d/postgresql.sh start
Starting PostgreSQL: ok
[root root]#
/usr/local/etc/rc.d/postgresql.sh start

PostgreSQL performance tuning

See man syctl, man 5 sysctl and man 5 loader.conf.

Installing Libthreads 2.6.5

cd /usr/local/src/aolserver/
fetch http://mesh.dl.sourceforge.net/sourceforge/tcl/thread2.6.5.tar.gz
tar xzpf thread2.6.5.tar.gz
cd thread2.6.5/unix
less ../README
../configure --help
../configure --enable-threads --prefix=/usr/local/aolserver --exec-prefix=/usr/local/aolserver --with-aolserver=/usr/local/aolserver --with-tcl=/usr/local/lib/tcl8.4-threads
gmake install

Creating users

We need to add more parameters to have user environments match the linux ones expected by the en:openacs-reference-platform.

Create users this way:

[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME
[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash
[root root]#
mkdir -p /home/$OPENACS_SERVICE_NAME
pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash

OpenACS/dotLRN Windows Installer Instructions

Created by Byron Linares, last modified by Gustaf Neumann 12 Nov 2013, at 11:22 AM

NOTE: Currently (05/2009), the best option to get OpenACS 5.5.* running on Windows is to use the native windows installation Win32-OpenACS by Spazio IT (Maurizio Martignano).

This page describes the installation of:

  • OpenACS 5.2.3
  • DotLRN 2.2.0
Included Software
  • AOLServer 4.0.beta10_2003
  • PostgresSQL 7.4.3
  • OpenACS 5.2.3
  • DotLrn 2.2.0
  • Cygwin
Installer Download :

The installer is available in openacs community page.
Available versions:

  • OpenACS/dotLRN installer
  • OpenACS 5.2.0 installer

Installation Instructions:

Run the "OpenACS/DotLRN Installer" called setup.exe, read the license document before continuing, the installer will ask for some information, this will be used to make the automatic installation.

There are to ways to install the components; manually or automatic


  • dotLRN Manual and openACS Manual:
  • In this modality the entered personal data in the installer will be omitted and will be necessary to retake the installation from a browser window and enter the necessary data to continue the creation of the data modeling.
  • dotLRN Automatic and openACS Automatic
  • In this modality the installer its in charge of all the work, when finishing creating the data model the following step would be to reinitiate the service and continue with the use of the platform.
  • Source Code:
  • The installer will put in the installation folder the source code of the same one.

Select what you want to install and click next. After the installer places all the files, a browser window will be opened and the installation have to be continued from here, if the automatic mode has been selected wait to the installation finishes. When the installation finishes restart the server and type in a web browser "http://localhost"

 Access Icons:

  • OpenACS on the web: access to http://localhost/
  • Start Server: Bach file to initiate the server (aolserver, postgresql, cygwim)
  • Stop Server: Bach file to stop the server (aolserver, postgresql, cygwin)
  • Unistall OpenACS: Uninstall all

  • Check if CygWin: Please execute the file server/cygwin/cygwin.bat.  You should get a black screen with some green text saying: "yourusername@yourcomputer" and the "$".
  • Check PostgreSQL: in the cygwin window typy psql -l , You should get the names of all data base.
  • Check AOLServer: ps -alW | grep nsd , You should get some thing like this
  • 2312 0 0 2312 ? 0 07:52:20 C:\OpenACS\nsd4\bin\nsd.exe

Full guide

developed at the Galileo University (www.galileo.edu) by Byron Haroldo Linares Roman bhlr@galileo.edu as part of the E-LANE project (www.e-lane.org)

related forum threads

OpenACS/dotLRN installer for MSWindows

Installing *nix

Created by OpenACS community, last modified by Gustaf Neumann 23 Sep 2013, at 08:16 PM

Install a *nix-based operating system (OS)

Follow the installation directions that come with the distribution.

There are generally 2 strategies at this point:

  1. Install an OS with minimum programs, or
  2. Install a suite of programs, for example choose between a developer set or desktop set.

We recommend installing only the OS to minimize the chances of conflicts resulting from installing 2 or more copies of one of the OpenACS system components openacs-system.

The impatient reader might want to check out the two scripts at naviserver-openacs which can be used to install OpenACS from scratch on a variety if systems (including Debian/RHEL Linux or Mac OS X), and which lists the detailed dependencies during the build process. Below, we describe in detail the steps.

Many additional programs, such as a build environment (gcc), Mail Transport Agent (MTA), and source control system, are also needed for a fully operational installation. Most of these are included with a basic OS installation.

Install some helper software

You might want to install some of these after a minimum OS install, since OpenACS administration usually assumes you have these (or alternates) installed:

  • wget
  • emacs or vi/vim
  • bash shell (usually automatically installed with Linux distributions)
  • gcc or equivalent (along with standard distribution source libraries) - if you plan to install software from source.
  • ImageMagick - used by some packages for server side image processing
  • aspell - used to offer spell checking in forms

*nix install guides

some helpful documentation for installing *nix flavors

*nix-based systems without installing *nix

These DEMOs install a temporary *nix OS on your system:

Or, lease a hosted system with a *nix OS and OpenACS installed on it.

See companies that host OpenACS websites.

Securing your system

Once you get your OS installed, it's imperative that you secure your installation. As Jon Griffin repeatedly warns us, "No distribution is secure out of the box." The Reference Platform implements some basic precautions, but security is a process, not a condition. If you are responsible for a computer hooked to the internet, you are responsible for learning some rudiments of security, such as monitoring the state of a computer, maintaining patch levels, and keeping backups. We recommend these resources:

for everyone

Created by OpenACS community, last modified by Benjamin Brink 09 Sep 2013, at 07:44 PM

OpenACS for everyone

OpenACS (Open Architecture Community System) is:

  • an advanced toolkit for building scalable, community-oriented web applications.
  • a robust, scalable framework (see: en:openacs-system) for building dynamic content driven sites and enterprise-level web applications.
  • a collection of pre-built applications and services that you can build on to create a custom web-site or application.
  • derived from the ArsDigita Community System (ACS). ArsDigita (now part of Red Hat, Inc.) kindly made their work available under the GPL, making all of this possible.

Through a modular architecture, OpenACS has packages for user/groups management, content management, e-commerce, news, FAQs, calendar, forums, bug tracking, wiki (XoWiki ), full-text searching etc. See OpenACS repository.


Use the OpenACS fourms to contact the OpenACS community. We welcome your feedback and can help with your OpenACS endeavors. Commercial support is also available.

What others say about OpenACS

Testimonials posted to forums on OpenACS

Try OpenACS

History of OpenACS

See: History of OpenACS en:docs-history

Bibliography and Credits

See: Documentation Credits en:doc-credits

Install Tcl

Created by OpenACS community, last modified by Jim Lynch 06 Sep 2013, at 12:21 AM

Check suitability of a previously installed TCL.

Start tcl (type tclsh or find it using which tclsh).

[root root]% info exists tcl_platform(threaded)
[root root]% info patchlevel
[root root]%

If the first command returns anything other than 1, then tcl is not threaded. If tcl is threaded and the version is 8.5 or higher, then installing tcl from source is optional.

 (jiml) Note that you will also need compiletime stuff so you can build things against that tcl; how to get it varies according to what OS and flavor thereof you run. Personally, I don't like to permit the operating system to dictate any versions of anything or have any influence over installing/removing, so I build the whole stack (these days, not including postgres) myself.

Install Tcl

Get TCL 8.5 (or higher). Download and install TCL 8.5 from source.

If you have not installed TCL already, download the latest TCL version from Sourceforge or http://www.tcl.tk/software/tcltk/downloadnow85.html 

We are installing tcl in context with aolserver to use a consistent set of libraries when more than one version may be present. Use the same directory for aolserver here, that you will be using when installing aolserver from the en:aolserver-install page.

Remember that you have to be logged in as root to issue the following commands.

[root root]# mkdir -p /usr/local/src/aolserver40r10
[root root]# cd /usr/local/src/aolserver40r10
[root src]# wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.5.14-src.tar.gz
[root src]# tar xfz tcl8.5.14-src.tar.gz
[root src]# cd tcl8.5.14/unix
[root unix]# ./configure --enable-threads --prefix=/usr/local/aolserver40r10
[root unix]# make install
[root root]# 

ref: http://openacs.org/doc/aolserver4.html 

Pull info from: http://www.tcl.tk/software/tcltk/downloadnow85.html 

Installing OpenACS on debian

Created by OpenACS community, last modified by Gustaf Neumann 31 Aug 2013, at 11:37 AM

The quicksheet versions:

You should know what you're doing when you use them.


Tcl development headers are required for compiling Tcl packages yourself.

apt-get install tcl8.4-dev

Should you decide to Install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

Installing Postgresql

Debian stable user should install PostGreSQL from source as detailed below, or they should use the www.backports.org backport for Postgres to get a more current version. Debian unstable users: the following process has been known to work (but you should double-check that the version of PostGreSQL is 7.3 or above):

For Debian stable users, you can use backports, by adding this line to the /etc/apt/sources.list

deb http://www.backports.org/debian stable bison postgresql openssl openssh tcl8.4 courier debconf spamassassin tla diff patch neon chkrootki

and perform this actions:

apt-get update
apt-get install postgresql postgresql-dev postgresql-doc
ln -s /usr/include/postgresql/ /usr/include/pgsql
ln -s /var/lib/postgres /usr/local/pgsql
ln -s /usr/include/pgsql /usr/local/pgsql/include
su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1"

..and proceed to the next section.

Installing PostgreSQL's Tsearch2

apt-get install postgresql-contrib

Creating the Postgres user.

Use adduser instead of useradd. Type man adduser for more info.

Compiling PostgreSQL

On debian woody (stable, 3.0), do:

./configure --without-readline --without-zlib 

Set PostgreSQL to start on boot

[root ~]# cp /var/tmp/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
[root ~]# chown root.root /etc/init.d/postgresql
[root ~]# chmod 755 /etc/init.d/postgresql
[root ~]# 
cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
chown root.root /etc/init.d/postgresql
chmod 755 /etc/init.d/postgresql

Test the script

[root ~]# /etc/init.d/postgresql stop
Stopping PostgreSQL: ok
[root ~]# 

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown.

[root ~]# update-rc.d postgresql defaults
 Adding system startup for /etc/init.d/postgresql ...
   /etc/rc0.d/K20postgresql -> ../init.d/postgresql
   /etc/rc1.d/K20postgresql -> ../init.d/postgresql
   /etc/rc6.d/K20postgresql -> ../init.d/postgresql
   /etc/rc2.d/S20postgresql -> ../init.d/postgresql
   /etc/rc3.d/S20postgresql -> ../init.d/postgresql
   /etc/rc4.d/S20postgresql -> ../init.d/postgresql
   /etc/rc5.d/S20postgresql -> ../init.d/postgresql
[root ~]# /etc/init.d/postgresql start
Starting PostgreSQL: ok
[root ~]#

Debian defaults to starting all services on runlevels 2-5.

Installing Tcl

You can apt-get install tcl8.4-dev if you have the right version (stable users will need to add tcl8.4 to their sources.list file as described in the "Install Postgresql" section above. You will have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you try to find the tcl libraries, however.

apt-get install tcl8.4 tcl8.4-dev

and proceed to installing aolserver.

When installing aolserver, replace --with-tcl=/usr/local/lib/ with --with-tcl=/usr/lib/tcl8.4.

Installing AOLserver

To install AOLserver you can use apt command:

apt-get install aolserver4 aolserver4-nscache aolserver4-nspostgres aolserver4-nssha1 tdom

After installing AOLserver, You need to make the following symbolic link:

ln -s /usr/lib/aolserver4 /usr/local/aolserver


Created by OpenACS community, last modified by Gustaf Neumann 31 Aug 2013, at 11:17 AM

the free, open-source, multithreaded, scalable, Tcl-enabled, web/application server used by some of the world's busiest websites, such as AOL.com, Mapquest.com, Netscape.com, and Moviefone.com. Other sites that run on AOLserver: http://panoptic.com/wiki/aolserver/Sites_That_Run_On_AOLserver

What others say about AOLserver

Using AOLserver with OpenACS

Notes on upgrading AOLserver 4.5.1 ( or greather )

  • All the ns_cache* API is from AOLServer 4.5.1 on, part of the core, therefore loading nscache.so in your config file is not longer required. Doing otherwise could lead to syntax errors while doing some calls to the API.


Postgres 9.1 and later versions

Created by Gustaf Neumann, last modified by Gustaf Neumann 31 Aug 2013, at 10:53 AM

The head version of OpenACS (5.8) works with PostgreSQL 9.1 or newer out of the box, no special configurations in postgresql.conf are needed.

To work with PostgreSQL 9, one has to use an actual postgres driver:

OpenACS core + commonly used packages (search, forums, xowiki, ...) have been tested with PostgreSQL 9.2.4

For new installs, OpenACS 5.8 works without further considerations. When upgrading to PostgresSQL 9.*, one has to keep in mind, that not only the sql-install scripts have to be SQL 9.* compatible, but as well the update scripts (migration scripts). During the work for making OpenACS compatible with PostgreSQL 9.*, we did not update (all) of the migration scripts (e.g. kernel upgrades) of earlier versions.

Therefore, the following upgrade steps are recommended: 

  • For users of PostgreSQL versions earlier than 8.4:  In case you run a version of OpenACS earlier than 5.5 then upgrade first your code to OpenACS 5.5 (oacs-5-5 branch from the CVS Repository), then dump your database and reload it into pg 8.4 (e.g. into pg 8.4.17, which is the oldest still supported version from postgres, end-of-life July 2014). Then continue with the next step below.

  • For users of PostgreSQL version 8.4 (or newer before 9): Make sure, you are running Tcl 8.5, then get OpenACS 5.8.0 (or newer) and upgrade OpenACS and your used packages (e.g. via acs-admin/apm + "install packages"). Then dump the database and restore it in pg 9.*.

Installing OpenACS on Redhat

Created by OpenACS community, last modified by Gustaf Neumann 20 Aug 2013, at 01:32 PM

Redhat publishes 2 versions of their OS, Fedora (FC) and Redhat Enterprise...

The quicksheet versions:

You should know what you're doing when you use them.

Should you decide to Install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes.

Some of these notes below are probably outdated by now, but might still give some useful hints for certain installations.

Notes for Installing Postgresql en:postgresql-install

If you install PostgreSQL 7.3.2 from the Red Hat 9 RPM, you can skip a few steps. These shell commands add some links for compatibility with the directories from a source-based install; start the service; create a new group for web service users, and modify the postgres user's environment (more information):

[root root]# ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
[root root]# ln -s /var/lib/pgsql /usr/local/pgsql
[root root]# ln -s /etc/init.d/postgresql /etc/init.d/postgres
[root root]# ln -s /usr/bin /usr/local/pgsql/bin
[root root]# service postgresql start
Initializing database:
                                                           [  OK  ]
Starting postgresql service:                               [  OK  ]
[root root]# echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
[root root]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
[root root]# groupadd web
[root root]# su - postgres

ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
ln -s /var/lib/pgsql /usr/local/pgsql
ln -s /usr/bin /usr/local/pgsql/bin
service postgresql start
echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
groupadd web
su - postgres

... and then skip to the section in en:postgresql-install that deals with installing plpgsql.

Set PostgreSQL to start on boot

Red Hat RPM:

The init script is already installed; just turn it on for the appropriate run levels.

[root root]# chkconfig --level 345 postgresql on
[root root]# 

Red Hat from source:

[root src]# cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
[root src]# chown root.root /etc/rc.d/init.d/postgresql
[root src]# chmod 755 /etc/rc.d/init.d/postgresql
[root src]# 
cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
chown root.root /etc/rc.d/init.d/postgresql
chmod 755 /etc/rc.d/init.d/postgresql

Test the script.

[root root]# service postgresql stop
Stopping PostgreSQL: ok
[root root]# 

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. And turn it back on because we'll use it later.

[root root]# chkconfig --add postgresql
[root root]# chkconfig --level 345 postgresql on
[root root]# chkconfig --list postgresql
postgresql      0:off   1:off   2:on    3:on    4:on    5:on    6:off
[root root]# service postgresql start
Starting PostgreSQL: ok
[root root]#
chkconfig --add postgresql
chkconfig --level 345 postgresql on
chkconfig --list postgresql
service postgresql start

Red Hat defaults to starting services on 3-5. So, on Red Hat, PostgreSQL won't start on runlevel 2 unless you alter the above commands a little. This usually isn't a problem as Red Hat defaults to runlevel 3)


Created by Michael Aram, last modified by Gustaf Neumann 16 Aug 2013, at 10:19 PM

hstore  is a postgresql module, which is used optionally by newer versions of xowiki and xowf (xowiki content flow ) to provide quick access to the "instance_attributes" (the per-form or per-workflow attributes not part of the native content repository data model). The supporting functions (creating indices, etc) are currently mostly part of the xowf sources, but will be moved eventually into xowiki.

Under Ubuntu, you can install hstore by locating the appropriate sql file on your system (you may need to install the postgres-contrib first), and then install it as postgresql user via:

psql -d <yourdb> -f /usr/share/postgresql/8.3/contrib/hstore.sql

...or issueing the command "create extension hstore" in psql. You can then verify the successful installation on the shell using:


Get the Code!

Created by roc@, last modified by Gustaf Neumann 25 Jul 2013, at 08:52 PM

This are instructions to obtain OpenACS, either as a released distribution (a .tar.gz file) or from CVS.

Obtain a released version of OpenACS via .tar file:

Download from OpenACS.org: http://openacs.org/projects/openacs/download/

Unpack the OpenACS tarball. Usually something like this works:

tar zxvf openacs-5.7.0.tgz

Obtain OpenACS from CVS (a certain release with potential patches, or the HEAD version):

If you want to track fresh code developments between releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to downloading a distribution, except that you get the files from CVS instead of the tarball. The following commands are used to obtain OpenACS 5.6 from CVS:

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot login
# press enter for password
cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-6 acs-core 

The command above checks out the core packages of OpenACS in a directory named openacs-4. For  the entire OpenACS version 5.6 branch you can use the following commands (adjust as required going forward):

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-6 openacs-4

If the the branch name (like oacs-5-6) is omitted, the the leading edge developer version (the HEAD release) is obtained

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout openacs-4

In order to check out a single package (e.g. the package cronjob) from  e.g. the leading edge developer version (HEAD), use 

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout openacs-4/packages/cronjob

For most OpenACS packages, CVS aliases are defined. In order to checkout e.g. the forums package from OpenACS 5.5, just use:

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-5 forums

 More info here: http://www.openacs.org/test-doc/using-cvs-with-openacs

Looking for README instructions or installers? View the OpenACS Installation instructions: en:openacs-system-install, otherwise continue by setting up the OpenACS distribution:

Set up the file system for one or more OpenACS sites

For Linux Standard Base compliance and ease of backup, all of the files in each OpenACS site are stored in a subdirectory of /var/lib/aolserver, one subdirectory (SERVERROOT) per site (see: en:openacs-reference-platform). The first time you install an OpenACS site on a server, you must create the parent directory and set its permissions:

While logged in as root:

mkdir -p /var/lib/aolserver
chgrp web /var/lib/aolserver
chmod 770 /var/lib/aolserver

Move the uncompressed code to SERVERROOT and rename the directory to $OPENACS_SERVICE_NAME:

mv openacs-4 /var/lib/aolserver/$OPENACS_SERVICE_NAME

Postgres 8.1.x and later versions

Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 24 May 2013, at 05:06 PM

Postgres 8.x (e.g. 8.1.* and later) require a few changes in the configuration file for backward compatibility:

1. Configure postgres8 with all compatibility ON in postgresql.conf:

add_missing_from = on
regex_flavor = extended
default_with_oids = on

2. If you are upgrading an OpenACS site between versions 4.5.2 to 5.2 and not continuing to 5.3, then: After the createdb step to create the OpenACS database, generate the next function before you import the pre-existing OpenACS database.

 From your shell prompt enter:

psql <dbname>

From the psql prompt enter the follow plpgsql code to create the bitfromint4 function:

create or replace function bitfromint4 (integer)
returns bit varying as '
return $1::bit(32);
end;' language 'plpgsql' immutable strict;

Exit psql:


This is the original thread  

For a full script on how to install PG 8.2 with ltree and tsearch2 look at Malte's install script  

Emacs as an OpenACS IDE

Created by OpenACS community, last modified by Prem Thomas 18 Jan 2013, at 09:54 PM

emacs integrated development environment for OpenACS

emacs documentation: http://www.gnu.org/software/emacs/manual/html_node/

Emacs uses major and minor modes that provide a UI context for editing various file types. Here are some useful ones for working with OpenACS:

CVS Mode Emacs with OpenACS

I use M-x cvs-examine to update and check in code when I am working with OpenACS. One thing that is a pain with CVS is that cvs diff does not tell you what you are going to get if you update, it only tells you what is changed in your local copy.

You can use M-x cvs-examine and then type "d e" next to any of the files in your checkout in the *cvs* buffer to open ediff mode and then interactively merge what's in CVS with your local changes. In ediff mode you use n/p to got to the next/previous difference. You can copy changes from the CVS buffer to your local copy using a/b to copy the the buffer marked A to B or B to A. Type ? on the ediff window to get a list of other commands.

OpenACS Mode for Emacs

See historical page describing oacs.el http://web.archive.org/web/20040621200046/www.thecodemill.biz/services/oacs/

Download: oacs.el.tar updated 2006-08-15 . The lastest version includes nXML mode support in addition to PSGML support. There are good installation instructions in the INSTALL.txt file. A quick install guide for Debian

sudo su -
cd /usr/share/emacs/site-lisp
wget http://www.emacswiki.org/elisp/color-occur.el
wget http://openacs.org/storage/view/xowiki-resources%5C/oacs.el.tar
tar xf oacs.el.tar
apt-get install psgml mmm-mode

# Alternatively compile manually
wget http://www.lysator.liu.se/~lenst/about_psgml/psgml-1.2.5.tar.gz
tar xfz psgml-1.2.5.tar.gz
cd psgml-1.2.5
make install
cd ..
wget http://switch.dl.sourceforge.net/sourceforge/mmm-mode/mmm-mode-0.4.8.tar.gz
tar xfz mmm-mode-0.4.8.tar.gz
cd mmm-mode-0.4.8
make install

After this login as the user who is doing the development and edit you .emacs file.

(add-to-list 'load-path "/usr/share/emacs/site-lisp/oacs")
(require 'oacs)
(setq user-full-name "<yourname>")
(setq user-mail-address "<your email>")
(add-to-list 'auto-mode-alist '("\\.vuh" . tcl-mode))
(add-to-list 'auto-mode-alist '("\\.adp" . html-mode))

For recent Emacs versions (> 2008), modify oacs-nxml.el in the downloaded tarball:

line 30: (load "nxml-mode.el")  instead of (load "rng-auto.el")

See http://lists.gnu.org/archive/html/emacs-devel/2008-01/msg00947.html

Also, you may need to modify adp.rnc to the correct path to the xhtml.rnc schema on your installation. On OS X, for example, line 5 should read:

include "/Applications/Emacs.app/Contents/Resources/etc/schema/xhtml.rnc" 

The following was written by Bart the author of oacs.el

OpenACS lacked a good Integrated Development Environment and as I use Emacs for almost everything it was only natural to fill the void. The Emacs OACS module is an extension to GNU Emacs, the extensible, customizable, self-documenting real-time display editor.

Development status

Emacs OACS's development is driven by the needs I encounter in my OpenACS projects. Development takes place in my spare time. At this stage the code is the documentation. I lack the time to write a proper article. However, as Emacs OACS addresses the issues described in articles XQL Document Type Definition and Replacing SQL bind vars in Emacs some background information can be found in those articles.

Forum thread: Beta Emacs OACS module available

Useful commands

Formating TCL

  • M-o ft to re-format Tcl code. See code for details.
  • M-o fh to reformat Html or Adp code.
  • M-o fs to reformat Sql code.
  • M-x oacs-format-separate-tags to separate adjacent tags. E.g. <tr><td>
  • M-x oacs-format-includes to place all include attribubtes on a separate line.

Code navigation

  • M-o oo to search for any custom regular expression.
  • M-o on to search the log for Notice oacs-dbg messages. That is a Notice level message created with the macro 'oddbg'.
  • M-o od to search the log for Debug oacs-dbg messages.
  • M-o oe to search the log for Error oacs-dbg messages. Etc for all other ns_log levels.
  • M-o op to browse Tcl libraries for procedure definitions. This is by far my favorite way of navigating a library!
  • M-o fp (find-file-at-point) to NSD error log mode.
  • M-o rl to revert the logfile
  • M-o ml to to open an error log file and monitor the changes to the log. 

Editing docbook xml

editing via Muse mode

editing via nXML mode

See http://openacs.org/doc/nxml-mode.html

psgml mode


Developing with emacs

To make emacs display .vuh files similar to .tcl files, add to .emacs file:

(add-to-list 'auto-mode-alist '("\\.vuh" . tcl-mode))

To make emacs display .adp files similar to .html files, add to .emacs file:

(add-to-list 'auto-mode-alist '("\\.adp" . html-mode))

Common command shortcuts

Minor Modes

 M-x global-font-lock-mode highlights syntax using colors
 M-x transient-mark-mode   shows a highlighted text region
 M-x show-paren-mode       shows matching parentheses (and when the do not)

Move, Search and Replace

 M-x goto-line             go to a specific line in a file
 M-x goto-char             go to a specific character number in a file
 M-C-f                     search forward for matching brace
 M-C-b                     search backward for matching brace
 M-x replace-regexp        search/replace using regular expressions
 M-x query-replace-regexp  query/search/replace using regular expressions
   note \\( and \\) for start and end subgroups
 M-x grep                  grep creates new buffer with results
                           for fast loading/editing search hits

Useful "sleepers" (not found in many shortcut sheets)

 fg<cr>                    restart a suspended emacs session from commandline
 C-q <key press>           add a key without emacs interpreting the key binding

You can configure emacs to create 4 spaces when you press the tab key--important for meeting coding standards. Add this to your .emacs file:

(setq-default tab-width 4 indent-tabs-mode nil)

other useful quicksheets

Install AOLserver

Created by OpenACS community, last modified by Gustaf Neumann 22 Jun 2012, at 05:07 PM

Get AOLserver and modules Download AOLserver and modules from CVS. Install Tcl if it is not installed yet.

  • one should base the documentation on releases, not on head versions. So, just relying on the head version of github is not recommended for beginners.
  • newer versions of aolserver have ns_cache included (4.5.1 or newer). no need for the extra module listed below.
  • using "aolserver40r10" as name for the install directory is strange, especially, when the release is not 4.0.10
[root root]# mkdir -p /usr/local/src/aolserver40r10/
[root root]# git clone git://github.com/aolserver/aolserver.git /usr/local/src/aolserver40r10/aolserver/
[root root]# git clone git://github.com/aolserver/nssha1.git /usr/local/src/aolserver40r10/nssha1/
[root root]# git clone git://github.com/aolserver/nspostgres.git /usr/local/src/aolserver40r10/nspostgres/
[root root]# git clone git://github.com/aolserver/nsoracle.git /usr/local/src/aolserver40r10/nsoracle/
[root root]# cd /usr/local/src/aolserver40r10
[root root]# cvs -z3 -d:pserver:anonymous@aolserver.cvs.sourceforge.net:/cvsroot/aolserver co nscache

Download en:tdom, tcllib, and XOTcl.

[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.tdom.org:/usr/local/pubcvs co tdom
[root aolserver]# wget http://heanet.dl.sourceforge.net/sourceforge/tcllib/tcllib-1.10.tar.bz2
[root aolserver]# wget http://media.wu-wien.ac.at/download/xotcl-1.6.7.tar.gz

Configure, compile and install AOLserver. Many people need to run more than one version of AOLserver in parallel. This section accomodates future upgrades by installing AOLserver 4 in /usr/local/aolserver40r10.

[root aolserver]# cd /usr/local/src/aolserver40r10/aolserver
[root aolserver]# ./configure --prefix=/usr/local/aolserver40r10 \
				--with-tcl=/usr/local/lib/ \
[root aolserver]# make
[root aolserver]# make install

If this is the only version of AOLserver in use, or is the default version, create a symlink. If not, then be sure to use /usr/local/aolserver40r10 instead of /usr/local/aolserver in future steps and check any scripts and makefiles you run to ensure they use the correct path.

[root aolserver]# ln -s /usr/local/aolserver40r10 /usr/local/aolserver

Configure, compile and install the modules.

OpenACS looks for the Oracle driver at /usr/local/aolserver/bin/ora8.so, but some versions of nsoracle may create nsoracle.so instead. In that case, you can symlink (ln -s nsoracle.so ora8.so) to fix it.

  1. Install nscache

    [root aolserver]# cd /usr/local/src/aolserver40r10/nscache
    [root nscache]# make install AOLSERVER=/usr/local/aolserver40r10
  2. Install nsoracle (if you want to use Oracle)

    [root nscache]# cd ../nsoracle
    [root nsoracle]# make install AOLSERVER=/usr/local/aolserver40r10
  3. Install nspostgres (if you want to use Postgres)

    [root nscache]# cd ../nspostgres
    [root nspostgres]# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
    [root nspostgres]# make install POSTGRES=LSB \
    				ACS=1 \
    				INST=/usr/local/aolserver40r10 \

     You might try POSTGRES=PG_CONFIG if that does not work.

    If you get errors like:

    nspostgres.c: In function `Ns_PgTableList':
    nspostgres.c:679: warning: passing arg 3 of `Tcl_DStringAppend' as signed due to prototype

    then PostGreSQL is probably not in the standard location.

    [jiml at cvs openacs here.] There are -new- (as of within 2nd quarter 2007) changes to nspostgres, there have been expansions of the ways to locate postgres, and changes to some error reporting. Please read the README and the Makefile. The nspostgres build can now use postgres's pg_config to locate a particular postgres installation. [jiml out]

    The location of PostGreSQL is very dependent on which method was used to install it. To correct the problem, replace LSB with the path to the path to your PostGreSQL installation. Often this is /usr/local/pgsql.

    Another possibility is that you may need to set the LD_LIBRARY_PATH environmental variable. You may still get warnings, but sometimes this will fix things enough to work.

    [root nspostgres]# export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib

    You can use the ldd command to verify that all libraries are linked in: ldd /usr/local/src/aolserver40r10/nspostgres/nspostgres.so

    If you run into problems with libpq.a do the following (and repeat the step above)

    [root nspostgres]# ranlib /usr/local/pgsql/lib/libpq.a

    If you run into problems with the linker, edit the Makefile. Add -lnsdb to the MODLIBS var.

    MODLIBS = -L$(PGLIB) -lpq -lnsdb
  4. Install nssha1

    [root nspostgres]# cd ../nssha1

    Now install nssha1:

    [root nssha1]# make install NSHOME=/usr/local/aolserver40r10

    If the make fails you will have to edit nssha1.c. Comment out the following 2 lines (lines 139-140):

    // typedef unsigned int u_int32_t;
    // typedef unsigned char u_int8_t;
  5. Install tDOM Note, if you use bash31 you need to apply a patch, see http://openacs.org/forums/message-view?message_id=369867 for details.

    [root nssha1]# cd ../tDOM-0.8.0/unix

    Edit the CONFIG file. Uncomment the instructions meant for AOLserver 4, but edit it to look like this:

    ../configure --enable-threads --disable-tdomalloc --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/src/aolserver40r10/tcl-8.4.14/unix

    Now you can compile and configure tDOM

    [root unix]# sh CONFIG
    [root unix]# make install
  6. Install tcllib

    [root aolserver]# cd /usr/local/src/aolserver40r10
    [root aolserver]# tar xvfj tcllib-1.10.tar.bz2
    [root aolserver]# cd tcllib-1.10
    [root aolserver]# ./configure --prefix=/usr/local/aolserver40r10
    [root aolserver]# make install
  7. Install XOTcl

    [root aolserver]# cd /usr/local/src/aolserver40r10
    [root aolserver]# tar xvfz xotcl-1.6.7.tar.gz
    [root aolserver]# cd xotcl-1.6.7/
    [root aolserver]# export CC=gcc
    [root aolserver]# ./configure --enable-threads --enable-symbols \
    				--prefix=/usr/local/aolserver40r10 \
    				--exec-prefix=/usr/local/aolserver40r10 \
    [root aolserver]# make
    [root aolserver]# make install-aol

Add a database-specific wrapper script. This script sets database environment variables before starting AOLserver; this allows the AOLserver instance can communicate with the database. There is one script each for Oracle and PostgreSQL. They don't conflict, so if you plan to use both databases, install both. Note that this section requires you to have the OpenACS, which you can get through CVS, through a tarball, or by other means. You can come back to this section after you acquire the OpenACS code, but don't forget to come back. (Note to maintainers: this should be moved to the next page and integrated into the text there)

  • Oracle

    [root aolserver]# cd /usr/local/aolserver40r10/bin
    [root bin]# cp /tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
    [root bin]# chmod 750 nsd-oracle
    [root bin]#
  • PostgreSQL

    [root aolserver]# cd /usr/local/aolserver40r10/bin
    [root bin]# cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
    [root bin]# chmod 755 nsd-postgres
    [root bin]#

You may need to edit these scripts if you are not using /usr/local/aolserver as the directory of Aolserver4.

Test AOLserver. We will use the sample-config.tcl file provided in the AOLserver distribution to test AOLserver. This test will use the nobody user and web group. The sample-config.tcl configuration writes to the default log locations, so we need to give it permission to do so or it will fail. Grant the web group permission to write to /usr/local/aolserver/log and /usr/local/aolserver/servers.

[root root]# cd /usr/local/aolserver
[root aolserver]# chown -R root.web log servers
[root aolserver]# chmod -R g+w log servers
[root aolserver]# ls -l
total 32
drwxr-sr-x    2 root     root         4096 Mar  8 12:57 bin
drwxr-xr-x    3 root     root         4096 Mar  8 10:34 include
drwxr-sr-x    3 root     root         4096 Mar  8 10:34 lib
drwxrwsr-x    2 root     web          4096 Mar  8 10:31 log
drwxr-sr-x    3 root     root         4096 Mar  8 10:31 modules
-rw-r--r--    1 root     root         7320 Mar 31  2001 sample-config.tcl
drwxrwsr-x    3 root     web          4096 Mar  8 10:31 servers
[root aolserver]#

Note: AOLserver4.x does not include a default start page, so we create one for this test. Type echo "Welcome to AOLserver" > /usr/local/aolserver40r10/servers/server1/pages/index.html

Now, run AOLserver using the sample configuration to verify it runs without errors. This configuration attempts to automatically get the machine's IP address and hostname. It will then start up the server at port 8000 of that IP address.

[root aolserver]# ./bin/nsd -t sample-config.tcl -u nobody -g web
[root aolserver]# [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: starting to read config file...
[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nsssl not loaded -- key/cert files do not exist.
[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nscp not loaded
-- user/password is not set.
[08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading
config file.

The first warning, about nsssl, can be ignored. We will not be using nsssl; we will be using nsopenssl instead. The nssl error happens because we have not fully configured secure connections to use nsopenssl. The nscp warning means that without a user and password in the sample-config.tcl file, the administrative panel of AOLserver will not load. We do not plan to use it and can ignore that error as well. Any other warning or error is unexpected and probably indicates a problem.

Test to see if AOLserver is working by starting Mozilla or Lynx on the same computer and surfing over to your web page. If you browse from another computer and the sample config file didn't guess your hostname or ip correctly, you will get a false negative test.

[root aolserver]# lynx localhost:8000

You should see a "Welcome to AOLserver" page. If this does not work, try browsing to If this still does not work, read the en:aolserver-admin section on "Troubleshooting AOLserver". Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address.

Shutdown the test server:

[root aolserver]# killall nsd
[root aolserver]#

The killall command will kill all processes with the name nsd, but clearly this is not a good tool to use for managing your services in general. We cover this topic in en:aolserver-admin section.

Set up the file system for one or more OpenACS Sites

This should already have been done, according to the instructions at the bottom of this page: en:Get_the_Code

Set up a user account for each site.

AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the command line. This user should have as few privileges as possible, because if an intruder somehow breaks in through AOLserver, you do not want the intruder to have any ability to do damage to the rest of your server.

At the same time, AOLserver needs to have write access to some files on your system in order for OpenACS to function properly. So, we run AOLserver with a different user account for each different service. Create the username as $OPENACS_SERVICE_NAME.

The password should be blank, to prevent login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that group. (If you don't know how to do this, type man usermod. You can type groups to find out which groups a user is a part of)

[root root]# useradd $OPENACS_SERVICE_NAME

You also need to set up a group called web.

[root root]# groupadd web

Then change the user to be a part of this group:

[root root]# usermod -g web $OPENACS_SERVICE_NAME

ref: http://openacs.org/doc/aolserver4.html

Install OpenACS on debian unstable / Ubuntu 7.10

Created by David Arroyo Menéndez, last modified by Gustaf Neumann 09 Nov 2011, at 02:07 PM

There are now debian packages for all OpenACS requirements, and OpenACS (.LRN) itself.

See The debian wiki page

The rest of this page is superseded by the debian wiki page.

You can also use the en:OpenACSDebianInstallGuide quicksheet.

Install tcl 8.4

apt-get install tcl8.4 tcl8.4-dev tcl8.4-doc

Install PostgreSQL 8.2

(from ubuntu repository or debian etch) for PG 8.2 I had to add this line to the /etc/apt/sources.list (under debian etch) 

deb http://www.backports.org/debian etch-backports main contrib non-free

Install with apt

apt-get install postgresql-8.2 postgresql-client postgresql-dev postgresql-doc
under debian-etch I did this to avoid downloading some 7.4-packages
apt-get install postgresql-8.2 postgresql-client-8.2 postgresql-dev postgresql-doc-8.2

Config the postgresql 8.x

from http://openacs.org/xowiki/How_to_install_in_Postgres_8.x
add_missing_from = on
regex_flavor = extended
default_with_oids = on
On debian you could need to change the postgresql port number to 5432, see /etc/postgresql/8.2/main/postgresql.conf

Create the database

su postgres -c "/usr/lib/postgresql/8.2/bin/createlang plpgsql template1"
su postgres -c "createuser service"

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
su postgres -c "createdb -E UNICODE service"

Install AOLserver

(AOLserver 4.5 for now only from debian unstable)
# Note: on ubuntu maybe more better install AOLserver 4.0 and you can download it from debian stable
  1. Add the next lines to /etc/apt/sources.list
    deb http://http.us.debian.org/debian stable main contrib non-free
    deb http://non-us.debian.org/debian-non-US stable/non-US main contrib non-free
    deb http://security.debian.org stable/updates main contrib non-free
  2. Update
    apt-get update
    # If you have any trouble with gpg keys, then you must read: http://www.davidam.com/debian/debian-gpg

  3. Install wit apt

    apt-get install -t unstable aolserver4 aolserver4-nscache aolserver4-nsopenssl aolserver4-nspostgres aolserver4-nssha1 aolserver4-dev aolserver4-doc daemontools-installer cvs

    *note: unpack the https.gz from aolserver4-nsopenssl and copy it over to the tcl directory of aolserver4, if not the api with https such as ns_httpspost will not be available.

    https.gz is normally found at /usr/share/doc/aolserver4-nsopenssl/examples/

    The tcl directory for aolserver4 is normally found at /usr/lib/aolserver4/modules/tcl/

  4. Install tdom from cvs
    # Sometimes cvs.tdom.org is down, if you have problems you can download with
    wget http://cognovis.de/file-storage/view/aolserver45.tar.bz2
    cd /usr/lib/aolserver4
    sudo ln -s /usr/include/aolserver4 include
    mkdir /usr/local/src/aolserver4
    cd /usr/local/src/aolserver4
    sudo cvs -z3 -d:pserver:anonymous@cvs.tdom.org:/usr/local/pubcvs co tdom
    cd tdom/unix
    ../configure --enable-threads --disable-tdomalloc --with-aolserver=/usr/lib/aolserver4 --prefix=/usr/lib/aolserver4 --with-tcl=/usr/lib/tcl8.4
    sudo make install
  5. Install XOTcl
    cd /usr/local/src
    sudo wget http://media.wu-wien.ac.at/download/xotcl-1.6.7.tar.gz
    sudo tar xvfz xotcl-1.6.7.tar.gz
    cd xotcl-1.6.7/
    export CC=gcc
    sudo ./configure --enable-threads --enable-symbols --prefix=/usr/lib/aolserver4 --exec-prefix=/usr/lib/aolserver4 --with-tcl=/usr/lib/tcl8.4
    sudo make
    sudo make install-aol
  6. Install TclLib
    cd /usr/local/src
    sudo wget http://kent.dl.sourceforge.net/sourceforge/tcllib/tcllib-1.10.tar.gz
    sudo tar xvzf tcllib-1.10.tar.gz
    cd tcllib-1.10
    sudo ./configure --prefix=/usr/lib/aolserver4
    sudo make install

Download and config OpenACS 5.4

  1. Create the directory where we can install OpenACS
    adduser service
    su - service
    mkdir aolserver
    cd aolserver
  2. Copy the two config files aolserver.nsadmin and nsadmin.tcl there:
    wget http://www.davidam.com/debian/aolserver.nsadmin
    wget http://www.davidam.com/debian/nsadmin.tcl
  3. Change nsadmin to service
    mv aolserver.nsadmin aolserver.service
    mv nsadmin.tcl service.tcl

    sed -i "s/nsadmin/service/g" aolserver.service service.tcl
  4. Download OpenACS from cvs
    cvs -z3 -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -r oacs-5-4 openacs-4
    mv openacs-4 service
    chmod 774 aolserver.service

     # create log directory (if needed)

    mkdir service/log
  5. Start AOLserver
    ./aolserver.service start
    Some minutes after that, it must be runing on http://localhost:8000

Install OpenACS on Mac OS X 10.5 / 10.6 (Snow Leopard) Using Macports

Created by Malte Sussdorff, last modified by Gustaf Neumann 03 Nov 2011, at 02:26 PM

I worked off the work of Dave Bauer and used Macports.

Unfortunately, the default configuration of Mac OS X does not allow suitable amounts of shared memory to be created to run the database server. 

Therefore you should edit your /etc/sysctl.conf

On a MacBook Pro with 2GB of RAM, the author's sysctl.conf contains:








Download and install MacPorts from http://www.macports.org/install.php and get the latest version (1.7.1 as of 2009-04-18)

Install PostgreSQL 8.4

sudo port -k install postgresql84
cd `port work postgresql84`/postgresql-8.4.7/contrib/ltree
make all
sudo make install
sudo port install postgresql84-server
This installs expat, gperf, libiconv, ncursesw, ncurses, gettext, m4, bison, zlib, libxml2, libxslt1, openssl, readline, postgresql82. The macports install then says
To create a database instance, after install do
sudo mkdir -p /opt/local/var/db/postgresql84/defaultdb
sudo chown postgres:postgres /opt/local/var/db/postgresql84/defaultdb
sudo su postgres -c '/opt/local/lib/postgresql84/bin/initdb -D /opt/local/var/db/postgresql84/defaultdb'

Then after initdb postgres says to start postgresql. Before that edit the config file to make it compatible with ACS

sudo emacs -nw /opt/local/var/db/postgresql84/defaultdb/postgresql.conf
Once you have emacs open, change the following config items:
autovacuum = on
add_missing_from = on
default_with_oids = on
regex_flavor = extended

Now start the PostgreSQL Server 

sudo su postgres -c  '/opt/local/lib/postgresql84/bin/postgres -D /opt/local/var/db/postgresql84/defaultdb' &

Install plpgsql as a language

/opt/local/lib/postgresql84/bin/createlang plpgsql template1 -U postgres

Last but not least, put postgresql under launchctl so you can start and stop it: 

sudo launchctl load -w /Library/LaunchDaemons/org.macports.postgresql84-server.plist 

To start it from then on just call

sudo launchctl start org.macports.postgresql84-server

To stop it:

sudo launchctl stop org.macports.postgresql84-server

Install AOLserver 4.5

sudo port install tcl +threads +headers

This will install Tcl with threads enabled, which is needed for AOLserver.

sudo port install aolserver
Now we have AOLserver installed into /opt/local/aolserver. You now need to configure the server to your needs. You might want to create another user (e.g. aolserver) to run the server. First get all the files:
    cd /usr/local/src
    mkdir aolserver 
    cd aolserver 
    # Path for the AOLserver installation 
    cvs -z3 -d:pserver:anonymous@aolserver.cvs.sourceforge.net:/cvsroot/aolserver co nssha1 
    cvs -z3 -d:pserver:anonymous@aolserver.cvs.sourceforge.net:/cvsroot/aolserver co nspostgres
    echo "Getting TDOM ..." 
    git clone git://github.com/tDOM/tdom.git
    echo "Getting TCL modules ..." 
    curl -L -O http://downloads.sourceforge.net/tcllib/tcllib-${TCLLIB}.tar.bz2 
    curl -L -O http://downloads.sourceforge.net/tcl/thread2.6.5.tar.gz 
    curl -L -O http://media.wu-wien.ac.at/download/xotcl-${XOTCL}.tar.gz

Now install nssha1

    cd nssha1
    sudo make install NSHOME=${NS} 
    cd ..

Now go for nspostgres

    cd nspostgres/

    # Edit the Makefile so it reads (adding the "-lnsdb")
    MODLIBS = -L$(PGLIB) -lpq -lnsdb
    sudo make install AOLSERVER=/opt/local/aolserver/ PGCONFIG=/opt/local/lib/postgresql84/bin/pg_config POSTGRES=/opt/local PGINC=/opt/local/include/postgresql84/ PGLIB=/opt/local/lib/postgresql84/ ACS=1
    cd ..


    cd tDOM-0.8.2/unix
    ../configure    --mandir=/usr/local/share/man    --libdir=/opt/local/aolserver/lib    --with-tcl=/opt/local/lib   --with-aolserver=/opt/local/aolserver
    sudo make install 
    cd ../..


    tar xvfz thread2.6.5.tar.gz 
    cd thread2.6.5/unix 
    ../configure    --mandir=/usr/local/share/man    --libdir=/Library/Tcl    --with-tcl=/System/Library/Frameworks/Tcl.framework    --with-tclinclude=/System/Library/Frameworks/Tcl.framework/Headers    --with-aolserver=/opt/local/aolserver 
    sudo make install
    cd ../..


The private header files of Tcl are missing, therefore I got the source and recompiled Tcl:

  curl -L -O http://downloads.sourceforge.net/tcl/tcl8.5.9-src.tar.gz
  tar xfz tcl8.5.9-src.tar.gz
  cd tcl8.5.9/unix
  ./configure --enable-threads --prefix=/opt/local --disable-corefoundation 
  sudo make install
  cd ../..

  tar xvfz xotcl-1.6.7.tar.gz 
  cd xotcl-1.6.7
  ./configure --enable-threads --enable-symbols --prefix=${NS} --exec-prefix=${NS} --with-tcl=/opt/local/lib
  sudo make install-aol
  cd .. 

Now we finish off with tcllib

  tar xvfj tcllib-1.13.tar.bz2 
  cd tcllib-1.13
  ./configure --prefix=/opt/local/aolserver/ 
  sudo make install
Type in terminal before starting nsd
  ulimit -n 256
I would recommend to install the server in ~/Sites/yourserver if you don't intend to run multiple different servers with access rights on your machine. Checkout the OpenACS code and Edit ~/Sites/yourserver/etc/config.tcl and make the following changes
# Change the server root
set serverroot                "~/Sites/${server}"

# Make sure that OpenACS finds PostgreSQL. Add two lines to the $database if statement

if { $database eq "oracle" } {
    set db_password           "mysitepassword"
} else {
    set db_host               localhost
    set db_port               ""
    set db_user               $server
    ns_section "ns/db/driver/postgres"
    ns_param   pgbin              /opt/local/lib/postgresql84/bin/

# Change the AOLserver location
set homedir                   /opt/local/aolserver

Now you can start up your server. First try ist with /opt/local/aolserver/bin/nsd -t ~/Sites/yourserver/etc/config.tcl. If this works you might want to create a launchctl entry as you did above for postgresql

Edit /Library/LaunchDaemons/org.openacs.YOURSERVER.plist and enter the following

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
        <string>OpenACS Service</string>

Now put yourserver under launchctl so you can start and stop it: 

sudo launchctl load -w /Library/LaunchDaemons/org.openacs.yourserver.plist 

To start it from then on just call

sudo launchctl start org.openacs.yourserver

To stop it:

sudo launchctl stop org.openacs.yourserver 

It is a good idea to schedule regular backups for your server(s). To do this create a shell script, e.g. backup.sh which executes your backups and then create a launchdaemon plist to run your backups nightly

Edit /Library/LaunchDaemons/org.openacs.backup.plist and enter the following

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

If you intend to run AOLserver on a continous basis remember that it is a great idea to make sure it responds properly. To do this you can run a keepalive service.

Edit /Library/LaunchDaemons/org.openacs.keepalive.plist and enter the following

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

Your keepalive.sh could look like this

HEAD="/usr/bin/head -1"


[ -z "$1" ] && exit
[ -z "$2" ] && exit

[ -f ${WGET_FILE} ] && rm -f ${WGET_FILE}  

_restartwebserver ()

/bin/launchctl start org.openacs.$INSTANCE
sleep 3
/bin/launchctl start org.openacs.$INSTANCE

_sendmail ()
echo "${1}" |mailx -s AolWebserver ${MAIL_ADDR}

while [ 1 -eq 1 ];
        [ -f ${WGET_FILE} ] && /bin/rm -f ${WGET_FILE}
        /usr/bin/curl -s -o $WGET_FILE --connect-timeout 3 --retry 3 "${URL_TEST}"

        if [ -f ${WGET_FILE} ] 
                FIRST_LINE=`${HEAD} ${WGET_FILE} | ${GREP} -i "success"`
                [ -z "${FIRST_LINE}" ] && _restartwebserver && _sendmail "I just restarted the $INSTANCE webserver on `uname -n`" && echo "`date +'%D-%H:%M'` :: FAILURE" || echo "`date +'%D-%H:%M'` :: success $INSTANCE" >>/Users/malte/Sites/keepalive.log 
                _restartwebserver && _sendmail "I just restarted the $INSTANCE webserver on `uname -n`"
#               _restartwebserver
                echo "`date +'%D-%H:%M'` :: FAILURE"

If you intend to run AOLserver on a continous basis remember that it is a great idea to restart your server once per night, otherwise the memory footprint will grow and grow and grow.

Edit /Library/LaunchDaemons/org.openacs.restart.plist and enter the following

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">

Now put scripts under launchctl so they will run in the night: 

sudo launchctl load -w /Library/LaunchDaemons/org.openacs.backup.plist

sudo launchctl load -w /Library/LaunchDaemons/org.openacs.restart.plist

sudo launchctl load -w /Library/LaunchDaemons/org.openacs.keepalive.plist

Your restart.sh could look like this

  echo "cognovis"
  sudo launchctl stop org.openacs.yourserver
  sleep 10
  sudo launchctl start org.openacs.yourserver 


Created by Gustaf Neumann, last modified by Gustaf Neumann 03 Nov 2011, at 02:25 PM

XOTcl is an object oriented extension for Tcl and required part of OpenACS installations since  TIP #87. The OpenACS package xotcl-core provides base functionality and integration with the OpenACS framework.

The current version of XOTcl is 1.6.7. Read about XOTcl motivations and  feature from http://media.wu-wien.ac.at/whatIsXOTcl.html . For more details about XOTcl, see XOTcl Homepage .


One can get XOTcl e.g. in binary form from debian or it can be complied from source. The following instructions describe, how to compile XOTcl from source.
  1. Get, compile and install XOTcl

    Get xotcl-1.6.7:

    cd /usr/local/src
    wget http://media.wu-wien.ac.at/download/xotcl-1.6.7.tar.gz
    tar zxvf xotcl-1.6.7.tar.gz

    The following commands can be used to compile XOTcl and install it into the appropriate places of the specified aolserver. We assume that the aolserver is installed under /usr/local/aolserver:

    cd xotcl-1.6.7
    CC=gcc;export CC
    ./configure --enable-threads --enable-symbols --prefix=/usr/local/aolserver --exec-prefix=/usr/local/aolserver --with-tcl=/usr/src/tcl8.4.16/unix

    Use appropriate paths for aolserver4 and your tcl version.

    make install-aol

    After the "make install-aol" from the XOTcl sources, a file xotcl.tcl is installed in the directory /usr/local/aolserver/modules/tcl/ that handles .xotcl files and XOTcl serialization in the aolserver.

  2. Restart your aolserver to load xotcl.


Created by OpenACS community, last modified by Gustaf Neumann 04 May 2011, at 05:41 PM

A tcl-based package, tDOM combines high performance XML data processing with easy and powerful Tcl scripting functionality. tDOM is one of the fastest ways to manipulate XML with a scripting language and uses very little memory.

More info at tdom.github.com (mailing list )

What others say about tDOM

Using tDOM with OpenACS


for beginning developers

Created by OpenACS community, last modified by Gustaf Neumann 12 Mar 2011, at 11:40 PM

Tutorials for OpenACS development

Other related tutorials

See also: OpenACS Mentorship Program

Other useful resources

Web Sites


OpenACS/.LRN for Debian

Created by Héctor Romojaro, Stefan Sobernig, last modified by Héctor Romojaro 22 Feb 2011, at 12:07 PM


Packages of OpenACS  and .LRN  are now available for Debian GNU/Linux . We hope to facilitate the adoption by novices and the infrastructure deployment by professional users, both running Debian GNU/Linux  and its derivates. Our packaging activity explicitly targets Debian GNU/Linux  stable , testing and unstable . Important dependencies are co-maintained with the Debian Tcl/Tk Maintainers .

See also OpenACS for Ubuntu.

Getting started

Please, review the section on supported distributions first.  Currently, the core packages (openacs, dotlrn) and their dependencies are included into the official Debian GNU/Linux  repositories.


  1. Run:

    apt-get update

  2. (optional) Provide for a PostgreSQL environment: If you don't have a PostgreSQL installation at hand, provide one. You do not need to care about setting up a concrete data base. This is automatically done by the openacs and dotlrn post-install instructions. For further PostgreSQL-related set-up issue, see ...

    apt-get install postgresql
    If you run a remote PostgreSQL instance, remember to allow for access of the PostgreSQL Administrator (postgres) and the openacs/dotlrn user from machine hosting your OpenACS/.LRN installation.

  3. Install the core packages and follow the on-screen instructions:

    # OpenACS
    apt-get install openacs
    ... or ...

    # .LRN
    apt-get install dotlrn

After Install

  1. (optional) To change IP address and port of the instance, please edit the file:

    # OpenACS

    # dotLRN

  2. (optional) To control the instance using daemontools, please install the daemontools debian packages and follow the instructions on the file:

    # OpenACS

    # dotLRN


Next Steps, After Basic Installation (above)


Active contributors

  • Héctor Romojaro 
  • Stefan Sobernig
  • Avni M. Khatri
  • Carl R. Blesius

Packages status

Packages maintained by Debian Tcl/Tk Maintainers 
Packages co-maintained by OCT & Debian Tcl/Tk Maintainers 


    Please, for getting in contact and reporting issues, consider ...

    OpenACS/.LRN for Ubuntu

    Created by Héctor Romojaro, last modified by Héctor Romojaro 22 Feb 2011, at 12:00 PM

    Packages of OpenACS  and .LRN  are now available for Ubuntu Linux . We hope to facilitate the adoption by novices and the infrastructure deployment by professional users, both running Debian GNU/Linux  and its derivates. This is an on-going effort. Beware, our packaging activity explicitly targets Ubuntu Linux  10.04 LTS (Lucid Lynx) and further versions. Important dependencies are co-maintained with the Debian Tcl/Tk Maintainers .

    See also OpenACS for Debian.

    Getting started

    Please, review the section on supported distributions first. Currently, the core packages (openacs, dotlrn) are included into the Universe Ubuntu repository.

    Release packages for Ubuntu 10.04 and Further

    1. Run:

      apt-get update
    2. (optional) Provide for a PostgreSQL environment: If you don't have a PostgreSQL installation at hand, provide one. You do not need to care about setting up a concrete data base. This is automatically done by the openacs and dotlrn post-install instructions.

      apt-get install postgresql
      If you run a remote PostgreSQL instance, remember to allow for access of the PostgreSQL Administrator (postgres) and the openacs/dotlrn user from the machine hosting your OpenACS/.LRN installation.

    3. Install the core packages and follow the on-screen instructions:

      # OpenACS
      apt-get install openacs
      ... or ...

      # .LRN
      apt-get install dotlrn

    After Install

    1. (optional) To change IP address and port of the instance, please edit the file:

      # OpenACS

      # dotLRN

    2. (optional) To control the instance using daemontools, please install the daemontools ubuntu packages and follow the instructions on the file:

      # OpenACS

      # dotLRN


    Active contributors

    • Héctor Romojaro 
    • Stefan Sobernig
    • Avni M. Khatri
    • Carl R. Blesius

    Packages status

    Packages maintained by Debian Tcl/Tk Maintainers 
    Packages co-maintained by OCT & Debian Tcl/Tk Maintainers 

    Community packages maintained by OCT


    Please, for getting in contact and reporting issues, consider ...

    Install OpenACS distribution

    Created by OpenACS community, last modified by Michael Aram 22 Dec 2010, at 06:19 PM

    You should have an OpenACS distribution downloaded and available at /var/lib/aolserver/$OPENACS_SERVICE_NAME, otherwise en:Get_the_Code.

    Option 1: Use an automated script

    A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation.

    Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target location.

    [root root]# su - $OPENACS_SERVICE_NAME
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install
    cvs server: Updating install
    U install/README
    U install/TODO
      ... many lines omitted ...
    U install/tcl/twt-procs.tcl
    U install/tcl/user-procs.tcl
    [$OPENACS_SERVICE_NAME install]$ emacs install.tcl

    Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at

    Run the install script install.sh as root:

    [root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh
    /home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file 
    /home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/
    $OPENACS_SERVICE_NAME, server_url=, do_checkout=yes, do_install=yes, 
    dotlrn=no, and database=postgres., use_daemontools=true
      ... many lines omitted ...
    Tue Jan 27 11:50:59 CET 2004: Finished (re)installing /var/lib/aolserver/$OPENACS_SERVICE_NAME.
      New site URL:
    admin email   : admin@yourserver.net
    admin password: xxxx
    [root root]#

    If there are no errors, you can browse to the "Welcome" page of your server. Be sure to visit en:docs-admin for administration help and en:docs-dev-tutorial for tutorials.

    Option 2: Install available distribution

    Secure the directory so that only the owner can access it. Check the permissions by listing the directory.

    [root root]# su - $OPENACS_SERVICE_NAME
    [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver
    [$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/openacs-5.2.0d1.tgz
    [$OPENACS_SERVICE_NAME aolserver]$ mv openacs-5.2.0d1 $OPENACS_SERVICE_NAME
    [$OPENACS_SERVICE_NAME aolserver]$ ls -al
    total 3
    drwxrwx---    3 root     web          1024 Mar 29 16:41 .
    drwxr-xr-x   25 root     root         1024 Mar 29 16:24 ..
    drwx------    7 $OPENACS_SERVICE_NAME web          1024 Jan  6 14:36 $OPENACS_SERVICE_NAME
    [$OPENACS_SERVICE_NAME aolserver]$ exit
    [root root]#
    cd /var/lib/aolserver
    tar xzf /var/tmp/openacs-5.2.0d1.tgz
    mv openacs-5.2.0d1 $OPENACS_SERVICE_NAME
    chmod -R 755 $OPENACS_SERVICE_NAME

    Prepare the database

    Prepare Oracle for OpenACS. If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service

    You should be sure that your user account (e.g. $OPENACS_SERVICE_NAME) is in the dba group.

    1. Verify membership by typing groups when you login:

      [$OPENACS_SERVICE_NAME ~]$ groups
      dba web

      If you do not see these groups, take the following action:

      [$OPENACS_SERVICE_NAME ~]$ su -
      Password: ************
      [root ~]# adduser $OPENACS_SERVICE_NAME dba

      If you get an error about an undefined group, then add that group manually:

      [root ~]# groupadd dba
      [root ~]# groupadd web

      Make sure to logout as root when you are finished with this step and log back in as your regular user.

    2. Connect to Oracle using svrmgrl and login:

      [$OPENACS_SERVICE_NAME ~]$ svrmgrl
      SVRMGR> connect internal

    3. Determine where the system tablespaces are stored:

      SVRMGR> select file_name from dba_data_files;

      Example results:


    4. Using the above output, you should determine where to store your tablespace. As a general rule, you'll want to store your tablespace on a mount point under the /ora8 directory that is separate from the Oracle system data files. By default, the Oracle system is on m01, so we will use m02. This enables your Oracle system and database files to be on separate disks for optimized performance. For more information on such a configuration, see Chapter 12 of Philip's book. For this example, we'll use /ora8/m02/oradata/ora8/.

    5. Create the directory for the datafile; to do this, exit from svrmgrl and login as root for this step:

      SVRMGR> exit
      [$OPENACS_SERVICE_NAME ~]$ su -
      Password: ************
      [root ~]# mkdir -p /ora8/m02/oradata/ora8/
      [root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8
      [root ~]# chmod 775 /ora8/m02/oradata/ora8
      [root ~]# exit
    6. Create a tablespace for the service. It is important that the tablespace can autoextend. This allows the tablespace's storage capacity to grow as the size of the data grows. We set the pctincrease to be a very low value so that our extents won't grow geometrically. We do not set it to 0 at the tablespace level because this would affect Oracle's ability to automatically coalesce free space in the tablespace.

      [$OPENACS_SERVICE_NAME ~]$ svrmgrl
      SVRMGR> connect internal;
      SVRMGR> create tablespace $OPENACS_SERVICE_NAME
            datafile '/ora8/m02/oradata/ora8/$OPENACS_SERVICE_NAME01.dbf' 
            size 50M 
            autoextend on 
            next 10M
            maxsize 300M
            extent management local
            uniform size 32K;
    7. Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use $OPENACS_SERVICE_NAMEpassword as our password.

      Write down what you specify as service_name (i.e. $OPENACS_SERVICE_NAME) and database_password (i.e. $OPENACS_SERVICE_NAMEpassword). You will need this information for configuring exports and AOLserver.

      SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME
          temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME;
      SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite, create view, create synonym to $OPENACS_SERVICE_NAME;
      SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME;
      SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME;
      SVRMGR> exit;

      Your table space is now ready. In case you are trying to delete a previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below.

    8. Make sure that you can login to Oracle using your service_name account:

      SQL> select sysdate from dual;
      SQL> exit;

      You should see today's date in a format 'YYYY-MM-DD.' If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in the section called “Troubleshooting Oracle Dates”

    Prepare PostgreSQL for an OpenACS Service.

    • PostgreSQL:

      Create a user in the database matching the service name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.

      [root root]# su - postgres
      [postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME
      [postgres pgsql]$ exit
      [root root]#
    • Create a database with the same name as our service name, $OPENACS_SERVICE_NAME.

      [root root]# su - $OPENACS_SERVICE_NAME
    • Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.


      Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information.

      0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME
      0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME

      Depending on your distribution, you may receive email when the crontab items are executed. If you don't want to receive email for those crontab items, you can add > /dev/null 2>&1 to the end of each crontab line

      At this point the database should be ready for installing OpenACS.

    Configure an AOLserver Service for OpenACS.

    1. The AOLserver architecture lets you run an arbitrary number of virtual servers. A virtual server is an HTTP service running on a specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl. Open it in an editor to adjust the parameters.

      [root root]# su - $OPENACS_SERVICE_NAME
      [$OPENACS_SERVICE_NAME etc]$ emacs config.tcl

      You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines. See en:aolserver-admin for an explanation of some other values you might want to change in the config.tcl file.

    Verify AOLserver startup.

    1. Kill any current running AOLserver processes and start a new one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run.

      If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the $OPENACS_SERVICE_NAME user via grep $OPENACS_SERVICE_NAME /etc/passwd and then put those numbers into the command line via -u 501 -g 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.

      If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep nsd and selectively kill by job number.

      [$OPENACS_SERVICE_NAME etc]$ killall nsd
      nsd: no process killed
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file...
      [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.
    2. Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000

      You should see a page that looks like this, otherwise check the en:aolserver-admin Troobleshooting secton.

    Configure a Service with the OpenACS Installer. Now that you've got AOLserver up and running, let's install OpenACS 5.2.0d1.

    • You should see a page from the webserver titled OpenACS Installation: Welcome. You will be warned if your version of the database driver is out of date, if AOLserver cannot connect to the database, if any modules are missing or out-of-date, or if there are any problems with filesystem permissions on the server side. But if everything is fine, you can click Next to proceed to load the OpenACS Kernel data model.

    • The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You should see a string of output messages from the database as the datamodel is created. You'll see the line:

      Loading package .info files ... this will take a few minutes

      This will really take a few minutes. Have faith! Finally, another Next button will appear at the bottom - click it.

    • The following page shows the results of loading the core package data models. You should see positive results for each of the previously selected packages, but watch out for any errors. Eventually, the page will display "Generating secret tokens" and then "Done"- click Next.

    • You should see a page, "OpenACS Installation: Create Administrator" with form fields to define the OpenACS site administrator. Fill out the fields as appropriate, and click Create User.

    • You should see a page, "OpenACS Installation: Set System Information" allowing you to name your service. Fill out the fields as appropriate, and click Set System Information

    • You'll see the final Installer page, "OpenACS Installation: Complete." It will tell you that the server is being restarted; note that unless you already set up a way for AOLserver to restart itself (ie. inittab or daemontools), you'll need to manually restart your service.

      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl
    • Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS <version> is now up and running!

    ref: http://openacs.org/doc/openacs.html

    Nagios Monitoring

    Created by Malte Sussdorff, last modified by Malte Sussdorff 22 Jul 2010, at 06:08 PM

    To monitor your server with Nagios you can use the check_http command.


    check_http -h <yourip> -u /SYSTEM/dbtest -s "success"

    To obtain the HTTP critical status if OpenACS can't return success, which can be either because the server isn't running or the database connection has failed.

    Installing OpenACS on win2k

    Created by OpenACS community, last modified by Maurizio Martignano 14 Jul 2010, at 09:59 AM

    by Matthew Burke and Curtis Galloway and others

    NOTE: These instructions were valid for ACS v4, but have not been tested with OpenACS and the ArsDigita binary distributions are no longer available. Currently (Summer 2010), the best option to get OpenACS 5.6.* and .LRN 2.5.* running on Windows is to use the native windows installation [Win32-OpenACS] by Spazio IT (Maurizio Martignano).

    Another option, for OpenACS 5.2.* is to use VMware and John Sequeira's Oasis VM distribution.



    With the recent release of a win32 version of AOLserver, it is now possible to run the OpenACS on Windows2000 and Windows98. This document explains the steps necessary to get the OpenACS installed and running on your machine.


    We do not recommend running a production server on Windows98. But the platform is more than sufficient for working the problem sets and for getting a feel for the OpenACS.

    You'll need to use the ArsDigita binary distribution of AOLserver for the Win32 platform, which contains patches for several problems we have come across in the default AOLserver binary distribution. See the ArsDigita AOLserver 3 distribution page (from archive.org) for details.

    You can download the binary distribution from the ArsDigita download page (compliments of Eve Andersson) under "ArsDigita AOLserver 3 Binary Distribution for Win32." Please read the release notes in the distribution for configuration notes specific to the version you are downloading.


    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.

    Although the zsh shell is the only command-line tool required to install the OpenACS, if you are a UNIX person used to typing ls instead of dir you'll get along much better with the Cygwin toolkit from RedHat (available at http://sourceware.cygnus.com/cygwin). This is a development library and set of tools that gives you a very UNIX-like environment under Windows. In particular, it includes bash, gzip and tar, which you can use to perform the OpenACS installation instead of WinZip and zsh.

    Your Oracle installation

    When you install Oracle, a good rule of thumb is "every default setting is wrong." We will not discuss Oracle configuration here except to mention that the OpenACS requires Oracle's NLS_DATE_FORMAT parameter be set to 'YYYY-MM-DD'. Fixing this depends on whether Oracle Administration Assistant for Windows NT (yes, that's Windows NT) will run on your machine or not (in some cases, it will complain about Microsoft Managment Console not being installed).

    If it runs on your machine, proceed as follows:

    1. Run Oracle Administration Assistant for Windows NT

    2. Navigate using the Explorer-style control in the left panel and select the Oracle Home for the database you wish to use.

    3. Bring up its properties dialog and add a parameter NLS_DATE_FORMAT with value 'YYYY-MM-DD' (without the quotes)

    4. Verify the date format by logging into the database using SQL Plus and run the following query: select sysdate from dual;

    Otherwise you will need to perform a little registry surgery as follows:

    1. Run regedit and navigate down the registry keys to HKEY_LOCAL_MACHINE\Software\ORACLE.

    2. Choose the appropriate subtree; this will be HOME0 if you only have on einstallation of Oracle.

      If you are an Oracle achiever and have more than one Oracle installation on your machine, you will see HOME0, HOME1, HOME2, etc. Choose the subtree that corresponds to the Oracle installtion you wish to use with the OpenACS.


    3. If the NLS_DATE_FORMAT key is already present, double-click on its value and change it to 'YYYY-MM-DD' (without the quotes). If the key does not exist, choose Edit->New->String Value from the menu and type NLS_DATE_FORMAT for the name of the new value to create it. Then double-click on the empty value to change it.

    4. Verify the date format by logging into the database using SQL Plus and run the following query: select sysdate from dual;

    For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips or search the OpenACS forums. One other note: the "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 for your database.

    The ArsDigita binary installation

    Extract the ArsDigita AOLserver distribution onto the C: drive into the default aol30 directory. You can install it on any drive, but it will make your life easier if you keep the AOLserver binary and your OpenACS instance on the same drive. For the rest of these instructions, we'll assume that you used drive C:.

    Untar the OpenACS

    We recommend rooting webserver content in c:\web. Since most servers these days are expected to run multiple services from multiple IP addresses, each server gets a subdirectory from c:\web. For example, http://scorecard.org would be rooted at c:\web\scorecard on one of our machines and if http://jobdirect.com were on the same box then it would be at c:\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 c:\web\yourdomain in the Windows 2000 file system. Note that you'll find our definitions files starting out with "yourdomain.com".

    • download the OpenACS (see above) into c:\temp\acs.tar.gz

    • use WinZip (or equivalent) to extract the files to c:\web\yourdomain

    You'll now find that c:\web\yourdomain\www contains the document root and c:\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 c:\web\yourdomain\www\install directory. You will need to open a console window and run

      zsh load-geo-tables foo/foopassword

      You most likely will see a slew of "Commit point reached . . . " messages. This does not indicate a problem.

    • cd to c:\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, open a console window and run

      sqlplus foo/foopassword < load-data-model.sql
    • If you have interMedia installed, while still in c:\web\yourdomain\www\doc\sql, run

      zsh 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 the password for interMedia Text's special ctxsys user.

    Configuring AOLserver

    You will need two configuration files. The first is a Tcl file with configuration information for AOLserver. This should be called yourdomain and should be located in c:\aolserve3_0. The second is an .ini file that configures the OpenACS and is discussed below. Note that pathnames in yourdomain must use forward slashes rather than the Windows back slashes. This is also true for the .ini file.

    The following items must be defined in yourdomain:

    • three database pools: main, subquery, and log. They must be named as such. The default pool will be "main".

    • the auxconfig directory which contains the .ini file: c:\web\yourdomain\parameters

    • the pageroot: c:\web\yourdomain\www

    • the directory containing the TclLibrary: c:\web\yourdomain\tcl

    You can use our template file as a starting point (you'll need to save this file with a rather than .txt extension).

    Configuring OpenACS itself

    If you want a system that works, go to c:\web\yourdomain\parameters and copy ad.ini to yourdomain.ini (or any other name different from ad.ini). You don't actually have to delete ad.ini.

    Each section of yourdomain.ini has a hardcoded "yourservername" in the name (e.g. [ns/server/yourservername/acs]). This means that the OpenACS will ignore your configuration settings unless your AOLserver name happens to be "yourservername". Therefore you must go through yourdomain.ini and change "yourservername" to whatever you're calling this particular AOLserver (look at the server name in the nsd 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 yourdomain.ini to change system-wide parameters. If you want to see how some of these are used, a good place to look is c:\web\yourdomain\tcl\ad-defs. The Tcl function, ad_parameter, is used to grab parameter values from the .ini file.

    Starting the Service

    Now you're ready to start things up. Before installing as a Windows service, you might want to test the setup for configuration errors. Open up a console window and go to c:\aol30. Then run

    bin\nsd -ft yourdomain.tcl

    This will print all the AOLserver messages to the console so you can see them.

    Try to connect to your new server with a web browser. If you see the message "Error in serving group pages", you probably forgot to copy the ad.ini file in c:\web\yourdomain\parameters If everything seems ok, you can kill the server with Control-c and then issue the following command to install as a Windows service:

    bin\nsd -I -s yourdomain -t yourdomain.tcl

    You can now configure error recovery and other Windows aspects of the service from the Services control panel. If you make further changes to yourdomain or yourdomain.ini you should stop and start the service from the Services control panel.

    Configuring Permissions

    Now, you need to protect the proper administration directories of the OpenACS. You decide the policy although we recommend requiring the admin directories be accessible only via an SSL connection. 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

    OpenACS 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"). Change the system user's password. Visit the https://yourservername.com/admin/ug/ directory and add your personal user as a site-wide administrator. Now you're bootstrapped!

    If you do not know what the system user's password is connect to Oracle using SQL Plus and run the following query:

    select password from users where last_name = 'system';

    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

    Running Multiple Instances of the OpenACS

    You can run multiple instances of the OpenACS on a physical machine but they must each be set up as a separate Windows service. Each instance of the OpenACS must have its own:

    • Oracle tablespace and a user account with the appropriate permissions on that tablespace. Each of these tablespaces must have the OpenACS data model loaded.

    • file with the appropriate settings including server name, auxconfig, ipaddress, and port.

    • Copy of the acs files in an appropriate directory under c:\web.

    Suppose you wish to run two services: lintcollectors.com and iguanasdirect.com. You would need the following:

    • an Oracle tablespace, lintcollectors with a user lintcollectors and password secretlint

    • an Oracle tablespace, iguanasdirect with a user iguanasdirect and password secretiguanas

    For each of these tablespaces/users you would load the OpenACS data model as described above. Then in c:\aolserver3_0 create files for each service, i.e. lintcollectors and iguanasdirect. These files would point to their respective pageroots, c:\web\lintcollectors\www and c:\web\iguanasdirect\www; their respective auxconfigdirs, c:\web\lintcollectors\parameters and c:\web\iguanasdirect\parameters; etc. In the respective auxconfigdirs would be the files lintcollectors.ini and iguanasdirect.ini.

    Now open a console window and go to c:\aol30. You'll start up the two services as follows:

    bin\nsd -I -s lintcollectors -t lintcollectors.tcl
    bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl

    In the services control panel you should see two services: AOLserver-lintcollectors and AOLserver-iguanasdirect.

    ref: http://openacs.org/doc/win2k-installation.html

    Vi as an OpenACS IDE

    Created by OpenACS community, last modified by Gustaf Neumann 19 May 2010, at 12:26 PM

    In vim add the following in your .vimrc will help convert tabs to 4 spaces to meet part of the OpenACS coding standard.

    set tabstop=4
    set expandtab
    set list
    set listchars=tab:>.

    It's also nice to have syntax highlighting by adding the following line

    syntax on 

    Also useful to use tagging features. In brief - run ctags -R in the root of the install or source tree.

    At that point you can edit using vim -t procname or ::package::procname and go to the corresponding place in the code. From within the code, you can lookup functions by having the term highlighted and hit CTL-] - use CTL-T to go back.

    Only works if you edit from the top directory, all tags are relative to there.

    Testing with TCLWebtest

    Created by OpenACS community, last modified by Ryan Gallimore 10 Apr 2010, at 06:49 PM

    Testing with TCLWebtest

    by Simon Carstensen and Joel Aufrecht

    Tclwebtest is primarily for testing user interface and acceptance testing.

    API testing is only part of testing your package - it doesn't test the code in our adp/tcl pairs. For this, we can use TCLWebtest (see sourceforge ). TCLWebtest provides a library of functions (see command reference ) that make it easy to call a page through HTTP, examine the results, and drive forms. TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.

    TCLWebtest must be installed for to work. Since automated testing uses it, it should be part of every OpenACS installation. Note that TCLwebtest is installed automatically by Malte's install script .

    Forum Posts:

    Command Reference:

    • http://tclwebtest.sourceforge.net/doc/api_public.html 


    • Automated Testing Best Practices see: http://openacs.org/doc/automated-testing-best-practices.html
    • testing packages for release en:Package_Testing_Process_


    • Webtest-Recorder Firefox extension (TwtR) see http://www.km.co.at/km/twtr This module is a plugin for Firefox. It is used to generate/edit a tclwebtest script which can be used later for regression testing without the need of a browser. There is a certain overlap of the application range between selenium and TwtR. This plugin was developed by Åsmund Realfsen for regression/load testing of the assessment module.

    Here are some guidelines on how to write automated tests with TCLWebtest. It is a joy to work with automated testing once you get the hang of it. We will use the "myfirstpackage" as an example.

    Create the directory that will contain the test script and edit the script file. The directory location and file name are standards which are recognized by the automated testing package:

    [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
    [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
    [$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl

    Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file:

    ad_library {

    To create a test case you call aa_register_case test_case_name.. Once you've created the test case you start writing the needed logic. We'll use the tutorial package, "myfirstpackage," as an example. Let's say you just wrote an API for adding and deleting notes in the notes packages and wanted to test that. You'd probably want to write a test that first creates a note, then verifies that it was inserted, then perhaps deletes it again, and finally verifies that it is gone.

    Naturally this means you'll be adding a lot of bogus data to the database, which you're not really interested in having there. To avoid this I usually do two things. I always put all my test code inside a call to aa_run_with_teardown which basically means that all the inserts, deletes, and updates will be rolled back once the test has been executed. A very useful feature. Instead of inserting bogus data like: set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:

    set name [ad_generate_random_string]

    Here's how the test case looks so far:

    aa_register_case mfp_basic_test {
        My test
    } {
        aa_run_with_teardown \
           -rollback \
           -test_code  {

    Now look at the actual test code. That's the code that goes inside -test_code {}. We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title."

          set name [ad_generate_random_string]
          set new_id [mfp::note::add -title $name]
          aa_true "Note add succeeded" [exists_and_not_null new_id]

    To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.) To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage". Since we'll be changing it frequently, select "watch this file" on the next page. This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing. We can also add some aa_register_case flags to make it easier to run the test. The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all. The -cats flag, setting categories, makes it easier to control which tests to run. The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")

    Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage. You should see your test case. Run it and examine the results.


    Now we can add the rest of the API tests, including a test with deliberately bad data. The complete test looks like:

    ad_library {
        Test cases for my first package.
    aa_register_case \
        -cats {smoke api} \
        -procs {mfp::note::add mfp::note::get mfp::note::delete} \
        mfp_basic_test \
            A simple test that adds, retrieves, and deletes a record.
        } {
            aa_run_with_teardown \
                -rollback \
                -test_code  {
                    set name [ad_generate_random_string]
                    set new_id [mfp::note::add -title $name]
                    aa_true "Note add succeeded" [exists_and_not_null new_id]
                    mfp::note::get -item_id $new_id -array note_array
                    aa_true "Note contains correct title" [string equal $note_array(title) $name]
                    mfp::note::delete -item_id $new_id
                    set get_again [catch {mfp::note::get -item_id $new_id -array note_array}]
                    aa_false "After deleting a note, retrieving it fails" [expr $get_again == 0]
    aa_register_case \
        -cats {api} \
        -procs {mfp::note::add mfp::note::get mfp::note::delete} \
        mfp_bad_data_test \
            A simple test that adds, retrieves, and deletes a record, using some tricky data.
        } {
            aa_run_with_teardown \
                -rollback \
                -test_code  {
                    set name {-Bad [BAD] \077 { $Bad}} 
                    append name [ad_generate_random_string]
                    set new_id [mfp::note::add -title $name]
                    aa_true "Note add succeeded" [exists_and_not_null new_id]
                    mfp::note::get -item_id $new_id -array note_array
                    aa_true "Note contains correct title" [string equal $note_array(title) $name]
                    aa_log "Title is $name"
                    mfp::note::delete -item_id $new_id
                    set get_again [catch {mfp::note::get -item_id $new_id -array note_array}]
                    aa_false "After deleting a note, retrieving it fails" [expr $get_again == 0]
    aa_register_case \
        -cats {web smoke} \
        -libraries tclwebtest \
        mfp_web_basic_test \
            A simple tclwebtest test case for the tutorial demo package.
            @author Peter Marklund
        } {
            # we need to get a user_id here so that it's available throughout
            # this proc
            set user_id [db_nextval acs_object_id_seq]
            set note_title [ad_generate_random_string]
            # NOTE: Never use the aa_run_with_teardown with the rollback switch
            # when running Tclwebtest tests since this will put the test code in
            # a transaction and changes won't be visible across HTTP requests.
            aa_run_with_teardown -test_code {
                # Login
                # Make a site-wide admin user for this test
                # We use an admin to avoid permission issues
                array set user_info [twt::user::create -admin -user_id $user_id]
                # Login the user
                twt::user::login $user_info(email) $user_info(password)
                # New Note
                # Request note-edit page
                set package_uri [apm_package_url_from_key myfirstpackage]
                set edit_uri "${package_uri}note-edit"
                aa_log "[twt::server_url]$edit_uri"
                twt::do_request "[twt::server_url]$edit_uri"
                # Submit a new note
                tclwebtest::form find ~n note
                tclwebtest::field find ~n title
                tclwebtest::field fill $note_title
                tclwebtest::form submit
                # Retrieve note
                # Request index page and verify that note is in listing
                tclwebtest::do_request $package_uri                 
                aa_true "New note with title \"$note_title\" is found in index page" \
                    [string match "*${note_title}*" [tclwebtest::response body]]
                # Delete Note
                # Delete all notes
                # Three options to delete the note
                # 1) go directly to the database to get the id
                # 2) require an API function that takes name and returns ID
                # 3) screen-scrape for the ID
                # all options are problematic.  We'll do #1 in this example:
                set note_id [db_string get_note_id_from_name " 
                    select item_id 
                      from cr_items 
                     where name = :note_title  
                       and content_type = 'mfp_note'
                " -default 0]
                aa_log "Deleting note with id $note_id"
                set delete_uri "${package_uri}note-delete?item_id=${note_id}"
                twt::do_request $delete_uri
                # Request index page and verify that note is in listing
                tclwebtest::do_request $package_uri                 
                aa_true "Note with title \"$note_title\" is not found in index page after deletion." \
                    ![string match "*${note_title}*" [tclwebtest::response body]]
            } -teardown_code {
                twt::user::delete -user_id $user_id

    Tcl Thread Library

    Created by Gustaf Neumann, last modified by Gustaf Neumann 14 Jan 2010, at 08:15 PM

    Libthread is the standard Tcl thread library developed by Zoran Vasiljevic and provides optional functionality for OpenACS. Threads created by the Tcl thread library are executed in an event loop, which makes it easy to send commands to such threads. xotcl-core provides support for the the thread library and uses it for example for background delivery of large files. Also the chat package uses libthread when it is installed. The xotcl-request-monitor depends on libthread.


    1. Get and install libthread:

        download thread2.6.5 from


     untar it and go to you platform specific directory (eg. thread2.6.5/unix)

    # cd unix
    # ../configure --enable-threads \
    --prefix=/usr/local/aolserver \
    --exec-prefix=/usr/local/aolserver \

    use --prefix --exec-prefix --with-aolserver with the path pointing to the directory, where aolserver4 is installed. The flag --with-aolserver is essential. When multiple Tcls are installed on the system, it is recommended to use the flag pointing to it, like e.g. in --with-tclinclude=/usr/local/src/tcl8.4.16/unix/ --with-tcl=/usr/lib/

    # check in output if there is following definition: -DNS_AOLSERVER=1
    make install

    You should now have installed libthread2.6.5.so (check for /usr/local/aolserver/lib/thread2.6.5/libthread2.6.5.so

    2) Adjusting config.tcl for libthread service

        I would recommed to load libthread 2.6.5 as a "module" from the aolserver config file to avoid a mixup with the plain tcl libthread extension (which is most likely compiled without --with-aolserver)

    • open config.tcl (/var/lib/aolserver/${yourservice}/etc/config.tcl)
    • look for modules section: ns_section ns/server/${server}/modules
    • add libthread to modules section:

      ns_param libthread ${homedir}/lib/thread2.6.5/libthread2.6.5.so

    restart the aolserver and check the error log, whether libthread2.6.5 was loaded successfully.

    svc -t /service/${yourservice}

    Installing OpenACS on FreeBSD (quick)

    Created by Martin Matuska, last modified by Gustaf Neumann 18 Nov 2009, at 08:47 AM

    This quick-and-dirty guide is intended for more experienced (or very impatient) users.
    More detailed instructions can be found here.

    1. Installation requirements

    FreeBSD (7.x, or 6.x) with updated ports tree
    and NOT yet installed ports databases/postgresql82-server, www/openacs or www/openacs-dotlrn

    2. Installing OpenACS

     Enter the following shell commands:

    # cd /usr/ports/databases/postgresql82-server # make install clean # cd /usr/ports/databases/p5-postgresql-plperl # make install clean # echo 'postgresql_enable="YES"' >> /etc/rc.conf # cd /usr/ports/www/openacs # make install clean # echo 'openacs_enable="YES"' >> /etc/rc.conf # /usr/local/etc/rc.d/postgresql initdb # /usr/local/share/doc/openacs/adjust_pgsql_conf.sh # /usr/local/etc/rc.d/postgresql start # /usr/local/share/doc/openacs/create_sampledb.sh # /usr/local/etc/rc.d/openacs start

    Now open  in your browser http://localhost:8000 and fill in all neccesary data, finalize installation. The openacs server goes down afterwards.

    # /usr/local/etc/rc.d/openacs start

    That's all! You local OpenACS installation is accesible under http://localhost:8000

    3. Installing .LRN 

     Enter the following shell commands:

    # cd /usr/ports/databases/postgresql82-server # make install clean # cd /usr/ports/databases/p5-postgresql-plperl # make install clean # echo 'postgresql_enable="YES"' >> /etc/rc.conf.local # cd /usr/ports/www/openacs-dotlrn # make install clean # echo 'dotlrn_enable="YES"' >> /etc/rc.conf.local # /usr/local/etc/rc.d/postgresql initdb # /usr/local/share/doc/dotlrn/adjust_pgsql_conf.sh # /usr/local/etc/rc.d/postgresql start # /usr/local/share/doc/dotlrn/create_sampledb.sh # /usr/local/etc/rc.d/dotlrn start

    Now open  in your browser http://localhost:8000 and fill in all neccesary data, finalize installation. The .LRN server goes down afterwards.

    # /usr/local/etc/rc.d/dotlrn start

    That's all! You local .LRN installation is accesible under http://localhost:8000

    A. Contact information and bug reporting

    Please send bug reports and feature suggestions to the port maintainer of OpenACS/.LRN FreeBSD ports:
    Martin Matuska

    OpenACS Performance Tuning

    Created by OpenACS community, last modified by Torben Brosten 09 Nov 2009, at 07:54 PM

    OpenACS Performance Tuning

    Here is some documentation on general OpenACS performance tuning:

    Much performance tuning is targeted at the subsystems level, and so you will find some specific tuning information in these pages:

    A broad scope of causes can be attributed to OpenACS performance issues. These forum threads help identify useful diagnostic techniques and accurate testing to help narrow the scope of problem areas etc.

    Installing OpenACS on Mac OS X

    Created by OpenACS community, last modified by Torben Brosten 19 Oct 2009, at 10:34 AM

    Installing OpenACS on Apple Mac OS X

    See one of these:

    Should you decide to Install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

    Installing en:postgresql

    OS X conventions

    On Mac OS X type sudo su - to become root.

    Use curl -L -O instead of wget

    If you are running Mac OS X prior to 10.3, you should be able to install and use PostGreSQL 7.3.x. Mac OS X 10.3 requires PostGreSQL 7.4. Note: if you're installing PG on an Intel Mac, you'll need to install 8.x; 7.4.x won't compile because of a lack of "native spinlock support" -- and this is something that the PG maintainers aren't inclined to fix. See this. PG 8.0.x installs fine, as does PG 8.1 or 8.2.

    Creating postgres user

    Do this instead:

    First make sure the gids and uids below are available (change them if they are not). To list taken uids and gids:

    nireport / /groups name gid | grep "[0-9][0-9][0-9]" nireport / /users name uid | grep "[0-9][0-9][0-9]"

    Now you can install the users

    sudo niutil -create / /groups/web sudo niutil -createprop / /groups/web gid 201 sudo niutil -create / /users/postgres sudo niutil -createprop / /users/postgres gid 201 sudo niutil -createprop / /users/postgres uid 502 sudo niutil -createprop / /users/postgres home /usr/local/pgsql sudo niutil -create / /users/$OPENACS_SERVICE_NAME sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME gid 201 sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME uid 201 mkdir -p /usr/local/pgsql chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 chmod 750 /usr/local/pgsql

    Compile and install PostgreSQL

    If you're using Fink:

    Append --with-includes=/sw/include/ --with-libraries=/sw/lib flags to ./configure.

    ./configure --with-includes=/sw/include/ --with-libraries=/sw/lib

    Set PostgreSQL to start on boot

    cd /Library/StartupItems/ tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz

    Alternatively, one can use an XML file like the following to start postgres via launchd (specifying the postgres binary directory and database directory)

    For Mac OS X Tiger (10.4.*), use:

    <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>GroupName</key> <string>nsadmin</string> <key>Label</key> <string>org.postgresql.PostgreSQL</string> <key>OnDemand</key> <false/> <key>ProgramArguments</key> <array> <string>/usr/local/pg820/bin/pg_ctl</string> <string>-D</string> <string>/usr/local/pg820/data</string> <string>-l</string> <string>/usr/local/pg820/data/server.log</string> <string>start</string> </array> <key>ServiceDescription</key> <string>PostgreSQL Server</string> <key>UserName</key> <string>postgres</string> </dict> </plist>

    For Mac OS X Leopard (10.5.*), use:

    <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>Label</key> <string>org.postgresql.PostgreSQL</string> <key>UserName</key> <string>postgres</string> <key>GroupName</key> <string>nsadmin</string> <key>OnDemand</key> <false/> <key>ProgramArguments</key> <array> <string>/usr/local/pg820/bin/postmaster</string> <string>-D</string> <string>/usr/local/pg820/data</string> <string>-c</string> <string>log_connections=YES</string> </array> </dict> </plist>

    Save the above files as /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist and postgres will be started automatically on the next boot of the system. One can use launchctl to start the service for testing;

    launchctl % load /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist % start org.postgresql.PostgreSQL % ^D

    To get Tcl to build on Leopard or newer

    for compiling under Mac OS X Leopard or newer, use the following flags to compile Tcl:

    ./configure --prefix=/opt/aolserver --enable-threads --disable-corefoundation --enable-symbols

    To get tDOM to build on tiger

    1. Download and install/update to the latest version of xcode tools (version2.2) from http://developer.apple.com/tools/xcode which updates the gcc compiler.

    2. Then make some additional changes to the unix/CONFIG file (after modifying the unix/CONFIG file according to instructions at en:aolserver-install, uncomment:
      'CC=gcc; export CC'
    3. add a new line, somewhere after the first line:

      export CPP="/usr/bin/cpp"

    When versions of aolservers different to aolserver 4.5 (head, including changes from Mar 22, 2008) are used, aolserver is likely to segfault on startup due to recent changes in the Mac OS X System libraries. To avoid this, use
    ulimit -n 256
    in the startup script (don't use unlimited).

    Testing with Selenium

    Created by Hamilton Chua, last modified by Dave Bauer 17 Sep 2009, at 07:56 PM

    Testing with Selenium

    Selenium is primarily for feature testing, user interface and acceptance testing.

    Recently OpenACS got support for Selenium RC   on CVS HEAD to be released in OpenACS 5.6 sometime in the future.

    Forum Posts :


    Command Reference :


    Interesting Articles :

    Tools :

    Selenium Recorder Firefox Extension

    Quickstart to Writing Tests:

      This quickstart shows you how to start writing selenium tests with selenium and the selenium recorder (aka selenium-ide).

    1. You need to have the Firefox Browser version 1.5 or higher
    2. Proceed to http://www.openqa.org/selenium-ide/ and click on the link (Firefox Extension) to install the Selenium IDE firefox extension
    3. Restart firefox
    4. Click Tools -> Selenium IDE
    5. The selenium ide window will open
    6. It will start recording your actions in the browser.
    7. You can go ahead and go to a url and click on the links to see how the recorder records your actions.
    8. To disable recording while the recorder window is open, click the "red" button.
    9. Selenium verifies that a test or action is successful by checking the title or text in a webpage
    10. You can verify the title of the current page  by right clicking on the webpage you are currently in and click Append Selenium -> verifyTitle
    11. You can verify the presence of text in a page by highlighting some text and then right click -> Append Selenium Command -> verifyTextPresent

    Click here for a video of how to use Selenium IDE.

    Selenium IDE allows you to create, save, load and run tests right from firefox without having to install Selenium on the server.

    Selenium on the Server

    Aside from using the Selenium IDE to test webpages, selenium itself can be installed on the server. This provides a central location for testers and developers to view and execute tests. "Server" here refers to the OpenACS instance where your application is running. If your OpenACS instance is in http://your_openacs_instance, then selenium should be installed in http://your_openacs_instance/selenium

    WARNING: We do not recommend installing selenium on the server of a production instance. Only install selenium on a staging or test server. This is because

    • When tests fail, they leave a mess of test data that you will not want on production
    • Selenium is mostly javascript that can run on any browser. While there are currently no reports of exploits on servers running selenium, we do not want and (you should not too) take the risk of having it on a production box where it is possible for a clever hacker to utilize a browser vulnerability to break into your server.

    To instal selenium on the server :

    1. Download selenium from http://www.openqa.org/selenium-core/download.action
    2. Choose to download the "Full Release"
    3. After downloading, decompress the file.
    4. You will see a folder selenium-x.x where "x.x" is the version of selenium you downloaded.
    5. Go inside this folder and look for the "selenium" folder.
    6. Copy this "selenium" folder to the openacsroot/www/ directory
    7. Launch a browser and go to http://your_openacs_instance/selenium

    At this point, selenium is installed. The page that you see when you visit /selenium is the default selenium page. It lists the tests that come with selenium.

    To start using selenium on the server :

    1. Customize the landing page /selenium/index.html
    2. Create Test Suites for each package. A test suite is just a file in selenium/tests that lists a number of tests for a particular feature or section of an application. For instance, TestSuite-News.html would be a file that lists the tests for the News Package.
    3. Upload tests to the /selenium/tests folder.
    Guidelines for Creating and Running Tests for OpenACS Packages

    Coming Soon .....

    Some Limitations :

    • Minor Issue with SSL  : Selenium can't switch properly between http and https pages.
    • File Input type not supported : You can't tell selenium to upload a file. But there is a work around with firefox. Read it here
    • WYSIWYG Editors  : Selenium can't write to some WYSIWYG editors like htmlarea but it seems to work with xinha, you just need to get the textearea element name that xinha uses.

    Tips :

    Use xpath to find specific html elements

    I have  scenario where I want to click ona image field with no id or name attribute so there's no easy way to tell selenium to click it. We can either ask the designer to put an id or name attribute or use xpath. Let's say the image button in question looks like this

     <input type="image" src="images/long-login-btn.gif" width=166 height=15 />

    the xpath syntax will be


    and you can use this in conjunction with clickAndWait

    Use javascript to create dummy values

    You can use javascript to generate values like so

      javascript{'test' + (new Date()).getTime()}

    and use store to store them to a value for use later in the selenium script.

    Next Steps After Installation, Debian Specific

    Created by Kenneth Wyrick, last modified by Kenneth Wyrick 14 Jul 2009, at 04:30 PM


    After following:

    Debian Installation Instructions

    A. Installing Daemontools

    nano /usr/share/doc/openacs|dotlrn/README.daemontools on openacs package.

    apt-get install daemontools daemontools-run

    B. Configuring Daemontools and Using SVC

    1) Change the "StartDaemon" value to "no" in /etc/default/:
    # OpenACS
    nano /etc/default/openacs
    ... or ...

    # .LRN
    nano /etc/default/dotlrn

    2) Stop the daemon:

    # OpenACS
    /etc/init.d/openacs stop
       ... or ...

    # .LRN
    /etc/init.d/dotlrn stop

    3) Link daemontools dotlrn|openacs script:

    # OpenACS
    ln -s /usr/share/openacs/etc/daemontools /etc/service/openacs
    ... or ...

    # .LRN

    ln -s /usr/share/dotlrn/etc/daemontools /etc/service/dotlrn

    Now you can control the dotlrn service using the svc command:
    * To start the service: svc -u /etc/service/
    /openacs or dotlrn
    * To stop the service: svc -d /etc/service/
    /openacs or dotlrn
    * To restart the service: svc -t /etc/service/openacs or dotlrn

    C. If There's Problems Purge and Reinstall

    apt-get remove --purge openacs or dotlrn

    apt-get install openacs or dotlrn

    D. To configure the instance to listen on a different IP than


    Edit the config.tcl file:
    nano /etc/openacs|dotlrn/config.tcl

    Change the following parameters to fit your needs:
    set hostname Your hostname
    set address to Your public IP

    E. Backup and Restore (to be filled in)

    I first went to: backup and restore docs

    and found that I had to figure out how to:

    pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp openacs-dev
    ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp

    which I thought would be "dotlrn"
    turned out to be "www-data"

    Next I found there was no /var/lib/aolserver but there are /var/lib/dotlrn and /var/lib/postgresql

    The default paths show the locations that were decided upon (in early 2004) so below we will try to document were things are in a standard dotlrn installation, now.

    a work in progress

    OpenACS service dotlrn
    OpenACS service account www-data
    OpenACS database name dotlrn
    SERVERROOT /usr/share/dotlrn/www
    Database backup directory /var/backups/
    Service config files /usr/share/dotlrn/etc/config.tcl
    Service log files /usr/share/dotlrn/log/
    PostgreSQL directory /usr/lib/postgresql/8.3/main
    AOLserver directory /usr/lib/aolserver4
    Backup Script

    F. Installing Packages (to be filled in)

    1. From .LRN CVS

    a) Create a local repository

    b) Download to your local repository

    G. View the Log File

    nano /var/log/aolserver4/dotlrn/error.log

    H. Mail Server (to be filled in)

    1. Installation
    2. configuration

    Install OpenACS - prereqs

    Created by OpenACS community, last modified by Torben Brosten 15 Dec 2008, at 08:39 PM

    Prerequisites to installing OpenACS

    You will need a computer with at least these minimum specifications:

    • 256MB RAM (much more if you will be running Oracle)
    • 1GB free space on the computer's hard disk (much more if you will be running Oracle)
    • a compatible, Unix-like operating system en:os-nix installed.

    All of the software mentioned is open-source and available without direct costs, except for Oracle. You can obtain a free copy of Oracle for development purposes (see: en:oracle-install).

    Each version of OpenACS only works with certain versions of the component software. Determine which versions you will be using by reviewing the en:openacs-compatibility-matrix.

    These components in-turn depend on other software and parts of the OS. Here is a list of minimum required versions. For production systems, use the lastest stable release:

    • GNU/Linux. The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
    • glibc 2.2 or newer. You need recent versions of these libraries for Oracle to build and work properly. For Unicode support, you need glibc 2.2 or newer. glibc should be included in your operating system distribution.
    • GNU Make 3.76.1 or newer and gcc. PostgreSQL and AOLserver require gmake/gcc to compile.

    OpenACS has a variety of packages that may require other software to be installed. Review the individual package documentation for other requirements. Also, OpenACS is commonly deployed with other related applications. For your convenience, here is a short list of some of these:

    • tclwebtest - a tool for testing web interfaces via tcl scripts.
    • ns_pam - provides PAM capabilities for AOLserver. You need this if you want OpenACS users to authenticate through a PAM module (such as RADIUS).
    • pam_radius - provides RADIUS capabilities for PAM. You need this if you want to use RADIUS authentication via PAM in OpenACS.
    • ns_ldap - provides LDAP capabilities for AOLserver. You need this if you want to use LDAP authentication in OpenACS.
    • OpenFTS - Adds full-text-search to PostgreSQL and includes a driver for AOLserver. You need this if you want users to be able to search for any text on your site. For postgres 7.4.x and higher, full text search is also available via tsearch2.
    • Analog - examines web server request logs, looks up DNS values, and produces a report. You need this if you want to see how much traffic your site is getting.
    • Balance - "a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system.
    • Daemontools -You need this if you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. An alternative would be to run the services from inittab.
    • en:mta
    • Netqmail - You need this (or a different Mail Transport Agent) if you want your webserver to send and receive email.
    • ucspi-tcp - listens for incoming TCP connections and hands them to a program. We use it instead of inetd, which is insecure. You need this if you are running qmail.
    • DocBook (docbook-xml, docbook-xsl, libxslt, xsltproc) - for writing or editing docbook style documentation.
    • en:source-control
    • search uses these utilities to index file contents: http://wagner.pp.ru/~vitus/software/catdoc/ and  http://poppler.freedesktop.org/ based on xpdf.

    next: en:openacs-system-install

    Install OpenACS on Linux

    Created by Gustaf Neumann, last modified by Gustaf Neumann 06 Dec 2008, at 10:36 AM

    The following pre-packaged installations for OpenACS and .LRN under Linux are available:

    OpenACS and .LRN can be installed certainly as well from scratch using the guidelines for stepwise installation of all necessary components.

    In general, OpenACS and its components works very well under Linux. It is used in many large installation with up to 10 million hits per day. For most applications, the systems runs nicely with a wide range of versions of Linux and its components. Due to some library changes in some Linux versions (especially in the native Linux thread installations), some precautions might be necessary. In case of problems on sites with high loads (e.g. server hangs) we recommend the following versions

    • Linux Kernel <2.6.9 or better,  >2.6.25
    • NTPL >= 2.7
    • gcc >= 4.2
    • Tcl libthread should be > 2.6.5 (including changes from 2008-05-22)

    Boost your application performance to serve large files!

    Created by Rocael Hernández Rizzardini, last modified by Gustaf Neumann 24 Nov 2008, at 03:23 PM

    In order to speed up file-deliveries, one can use the background delivery methods provided by xotcl-core. The main advantage is that with background delivery the costly connection threads are just used for permission checking and locating the file, and the time-consuming spooling of the file to the client is implemented in an asynchronous background delivery thread. Therefore, connection thread are not blocked, it is possible to spool simultaneously several hundred (thousand?) files with only a few connection threads configured.

    We use this in production since several years. For example today (no semester yet) we had so far 150.000 file deliveries by background delivery.

    The asynchrounous background delivery requires a small patch (2 changes, one is a backport from naviserver) and the tcl thread library (by zoran). The application code is in XOTcl is only a few lines of code and is included in xotcl-core (bgdelivery-procs.tcl).

    One needs the following patch to

    The patch is already included in the current head version of aolserver 4.5 and in naviserver.

    With this patch and xotcl-core, one can replace

    ns_returnfile 200 $mime_type $filename

    ad_returnfile_background 200 $mime_type $filename
    e.g. in cr_write_content in acs-content-repository/tcl/revision-procs.tcl to activate it and to deliver files from the content-repository (file-store) in the background.

    The connection thread is only used for permission management, localization of the file and writing the the reply header, the actual delivery of the file is performed via asychronous io without using up many resources. This can handle probably a couple of thousand concurrent file deliveries without running out of resources.

    Check the files that has been served since the last reboot of your aolserver using this method from the developer support shell:

    bgdelivery do set delivery_count

    Original thread:

    Installing OpenACS on RPM-based systems

    Created by Ryan Gallimore, last modified by Ryan Gallimore 09 Nov 2008, at 09:16 PM

    As root:

    OPENACS_SERVICE_NAME=service1 # Name your service


    groupadd web

    useradd -g web $OPENACS_SERVICE_NAME

    mkdir /var/lib/aolserver

    cd /var/lib/aolserver

    # Download latest tarball:

    >> wget [URL to latest tarball] 

    >> tar xzvf [tarball.tar.gz]

    >> mv [tarball_dir] $OPENACS_SERVICE_NAME 

    # OR, checkout from CVS. Replace oacs-5-4 with the branch of your choice.

    >> cvs -d:pserver:anonymous@cvs.openacs.org/cvsroot checkout -r oacs-5-4 acs-core

    >> mv openacs-4 $OPENACS_SERVICE_NAME

    chown -R $OPENACS_SERVICE_NAME.web /var/lib/aolserver/$OPENACS_SERVICE_NAME

    chmod -R 770 /var/lib/aolserver/$OPENACS_SERVICE_NAME


    # PostgreSQL 8.x

    service postgresql stop

    yum -y remove postgresql

    # Download the PG rpm 

    # Initialize the Cluster

    service postgresql initdb

    # Start the service

    service postgresql start

    # Start pg on boot

    chkconfig postgresql on

    # Change postgresql.conf

    # AOLServer

    Try the AOLServer 4.5 page. The archive download works well

    (but uses sources from 2006).

    # Daemontools should now be installed, so let's set it up to start, stop and restart AOLServer

    cd /service

    ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools $OPENACS_SERVICE_NAME 

    # Daemontools will no scan the etc/daemontools directory and find the run script.

    Read this for more information on Daemontools commands 

    # Modify the etc/daemontools/run script for your ip, user and group. Note the -b IP:PORT flag that
    # must be added for privileged ports.

    # Modify etc/config.tcl to match your hostname and IP. aolserver director should be /usr/local/aolserver 

    # avoid pid not found errors in the log

    chown -R $OPENACS_SERVICE_NAME.web /usr/local/aolserver/log

    chmod -R 775 /usr/local/aolserver/log 

     # Start the server!

    svc -u /service/$OPENACS_SERVICE_NAME

    # Watch the log for errors:

    tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log

    If successful, call up the site URL and install the data model. 


    # Done!

    Install Postgresql

    Created by OpenACS community, last modified by Ryan Gallimore 03 Oct 2008, at 06:27 PM

    A quick install guide for Postgres 8.2 which takes everything into account can be found at http://cognovis.de/developer/en/pg82 

    For RPMs, see http://yum.pgsqlrpms.org/

    These instructions should work for 7.4 to 8.2.

    Get the source code


    Install from source

    Unpack PostgreSQL 7.4.7. If you have downloaded the postgresql tarball to /var/tmp/postgresql-7.4.7.tar.gz

    [root root]# cd /usr/local/src
    [root src]# tar xzf /var/tmp/postgresql-7.4.7.tar.gz
    [root src]# 
    cd /usr/local/src
    tar xzf /var/tmp/postgresql-7.4.7.tar.gz

    If you have downloaded the postgresql tarball to /var/tmp/postgresql-7.4.7.tar.bz2

    [root root]# cd /usr/local/src
    [root src]# tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
    [root src]# 
    cd /usr/local/src
    tar xfj /var/tmp/postgresql-7.4.7.tar.bz2

    Create the Postgres user. Create a user and group (if you haven't done so before) for PostgreSQL. This is the account that PostgreSQL will run as since it will not run as root. Since nobody will log in directly as that user, we'll leave the password blank.

    [root src]# groupadd web
    [root src]# useradd -g web -d /usr/local/pgsql postgres
    [root src]# mkdir -p /usr/local/pgsql
    [root src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
    [root src]# chmod 750 /usr/local/pgsql
    [root src]#
    groupadd web
    useradd -g web -d /usr/local/pgsql postgres
    mkdir -p /usr/local/pgsql
    chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7
    chmod 750 /usr/local/pgsql

    Set up postgres's environment variables. They are necessary for the executable to find its supporting libraries. Put the following lines into the postgres user's environment.

    [root src]# su - postgres
    [postgres ~] emacs ~postgres/.bashrc

    Paste this line into .bash_profile:

    source $HOME/.bashrc

    Paste these lines into .bashrc:

    export PATH=/usr/local/bin/:$PATH:/usr/local/pgsql/bin
    export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib

    Test this by logging in as postgres and checking the paths; you should see /usr/local/pgsql/bin

    [root src]# su - postgres
    [postgres pgsql]$ env | grep PATH
    [postgres pgsql]$ exit

    Don't continue unless you see correct output from env | grep PATH

    Compile and install PostgreSQL. Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can configure PostgreSQL in various ways. To see what the possibilities, run ./configure --help.

    [root src]# su - postgres
    [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.7
    [postgres postgresql-7.4.7]$ ./configure
    creating cache ./config.cache
    checking host system type... i686-pc-linux-gnu
    (many lines omitted>
    linking ./src/makefiles/Makefile.linux to src/Makefile.port
    linking ./src/backend/port/tas/dummy.s to src/backend/port/tas.s
    [postgres postgresql-7.4.7]$ make all
    make -C doc all
    make[1]: Entering directory `/usr/local/src/postgresql-7.4.7/doc'
    (many lines omitted)
    make[1]: Leaving directory `/usr/local/src/postgresql-7.4.7/src'
    All of PostgreSQL successfully made. Ready to install.
    [postgres postgresql-7.4.7]$ make install
    make -C doc install
    make[1]: Entering directory `/usr/local/src/postgresql-7.4.7/doc'
    (many lines omitted)
    Thank you for choosing PostgreSQL, the most advanced open source database
    su - postgres
    cd /usr/local/src/postgresql-7.4.7
    make all
    make install

    Start PostgreSQL. The initdb command initializes the database. pg_ctl is used to start up PostgreSQL.

    [postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
    The files belonging to this database system will be owned by user "postgres".
    This user must also own the server process.
    (17 lines omitted)
        /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start
    [postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
    postmaster successfully started
    [postgres postgresql-7.4.7]$
    /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
    /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start

    PostgreSQL errors will be logged in /usr/local/pgsql/data/server.log

    Install Pl/pgSQL.Set up plpgsq and allow your user to have access. Plpgsql is a PL/SQL-like language. We add it to template1, which is the template from which all new databases are created. We can verify that it was created with the createlang command in list mode.

    [postgres postgresql-7.4.7]$ createlang plpgsql template1
    [postgres pgsql]$ createlang -l template1
    Procedural languages
      Name   | Trusted?
     plpgsql | t
    (1 row)
    [postgres pgsql-7.4.7]$
    createlang plpgsql template1
    createlang -l template1

    If you are installing Postgres 8.x, follow additional instructions at en:How_to_install_in_Postgres_8.x

    If you are installing tsearch2, follow additional instructions at en:postgresql-tsearch2

    Test PostgreSQL (OPTIONAL). Create a database and try some simple commands. The output should be as shown.

    [postgres pgsql]$ createdb mytestdb
    [postgres pgsql]$ psql mytestdb
    Welcome to psql, the PostgreSQL interactive terminal.
    Type:  \copyright for distribution terms
           \h for help with SQL commands
           \? for help on internal slash commands
           \g or terminate with semicolon to execute query
           \q to quit
    mytestdb=# select current_timestamp;
     2003-03-07 22:18:29.185413-08
    (1 row)
    mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql';
    mytestdb=# select test1();
    (1 row)
    mytestdb=# \q
    [postgres pgsql]$ dropdb mytestdb
    [postgres pgsql]$ exit
    [root src]#

    Set PostgreSQL to start on boot. First, we copy the SERVERROOT/packages/acs-core-docs/www/files/postgresql.txt init script, which automates startup and shutdown, to the distribution-specific init.d directory. Then we verify that it works. Then we automate it by setting up a bunch of symlinks that ensure that, when the operating system changes runlevels, postgresql goes to the appropriate state. Red Hat and Debian and SuSE each work a little differently. Be sure to check OS distribution notes for specifics (and examples)

    Once installed, PostgreSQL should start automatically each time you boot up and it should shutdown gracefully each time you shut down.

    AOLserver administration

    Created by OpenACS community, last modified by Torben Brosten 22 Aug 2008, at 08:46 AM

    AOLserver administration

    automating AOLserver startup and stop

    The simplest way to start and stop and OpenACS site is to run the startup shell script provided in the OpenACS distribution, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.

    A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.

    The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is next.

    Configuring Daemontools

    1. Daemontools must already be installed. If not, install it.

    2. Each service controlled by daemontools must have a directory in /service. That directory must have a file called run. It works like this:

      • The init program starts every time the computer is booted.

      • A line in init's configuration file, /etc/inittab, tells init to run, and to restart if necessary, svscanboot.

      • svscanboot checks the directory /service every few seconds.

      • If it sees a subdirectory there, it looks for a file in the subdirectory called run. If it finds a run file, it creates a supervise process

      • supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.

      Hence, the AOLserver instance for your development server is started by the file /service/$OPENACS_SERVICE_NAME/run. But we use a symlink to make it easier to add and remove stuff from the /service, so the actual location is /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run.

      Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS tarball at /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first kill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.

      [$OPENACS_SERVICE_NAME etc]$ killall nsd
      nsd: no process killed
      [$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run
      [$OPENACS_SERVICE_NAME etc]$ exit
      [root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run /service/$OPENACS_SERVICE_NAME/run

      Verify that AOLserver is running.

      [root root]# ps -auxw | grep nsd
      $OPENACS_SERVICE_NAME   5562 14.2  6.2 22436 15952 ?       S    11:55   0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl -u serve
      root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd
      [root root]#
    3. The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:

      • svc -d /service/$OPENACS_SERVICE_NAME - Bring the server down

      • svc -u /service/$OPENACS_SERVICE_NAME - Start the server up and leave it in keepalive mode.

      • svc -o /service/$OPENACS_SERVICE_NAME - Start the server up once. Do not restart it if it stops.

      • svc -t /service/$OPENACS_SERVICE_NAME - Stop and immediately restart the server.

      • svc -k /service/$OPENACS_SERVICE_NAME - Sends the server a KILL signal. This is like KILL -9. AOLserver exits immediately. If svc -t fails to fully kill AOLserver, use this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately.

    4. Install a script to automate the stopping and starting of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME

      [root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver
      [root root]# chmod 755 /usr/local/bin/restart-aolserver
      [root root]#
    5. At this point, these commands will work only for the root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server.

      [root root]# /usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME
      [root root]#
    6. Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands.

      Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO.

    Table 6.1. How it Works

    Program Invoked by this program ... ... using this file Where to find errors Log goes to Use these commands to control it
    svscanboot init /etc/inittab ps -auxw | grep readproctitle n/a
    aolserver supervise (a child of svscanboot) /service/$OPENACS_SERVICE_NAME/run /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log svc -k /service/$OPENACS_SERVICE_NAME
    postgresql Redhat init scripts during boot /etc/init.d/postgresql /usr/local/pgsql/data/server.log
    service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)

    init - keeping AOLserver alive

    This is an alternative method for keeping the AOLserver process running. The recommended method is to run AOLserver supervised.

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

    • There are 2 general steps to getting this working.

      1. Install a script called restart-aolserver. This script doesn't actually restart AOLserver - it just kills it.

      2. Ask the OS to restart our service whenever it's not running. We do this by adding a line to /etc/inittab.

      Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling restart-aolserver effectively restarts our service.

    • 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 executable by 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.

      [joeuser ~]$ su - 
      Password: ***********
      [root ~]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver.txt /usr/local/bin/restart-aolserver
      [root ~]# chown root.web /usr/local/bin/restart-aolserver
      [root ~]# chmod 4750 /usr/local/bin/restart-aolserver
      [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl
      [root ~]# exit
    • Test the restart-aolserver script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines.

      [joeuser ~]$ killall nsd
      nsd: no process killed
      [joeuser ~]$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/service0/nsd.tcl
      [joeuser ~]$ restart-aolserver service0 Killing 23727 [joeuser ~]$ killall nsd nsd: no process killed

      The number 23727 indicates the process id(s) (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.

      [joeuser ~]$ su -
      Password: ************
      [root ~]# emacs -nw /etc/inittab
    • Copy this line into the bottom of the file as a template, making sure that the first field nss1 is unique.

      nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/service0/nsd.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.

      [root ~]# killall nsd    
      nsd: no process killed
      [root ~]# /sbin/init q
    • See if it worked by running the restart-aolserver script again.

      [root ~]# restart-aolserver service0
      Killing 23750

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

    external monitoring of server uptime


    starting aolserver before postgresql

    Add a pause to the aolserver "run" script, for example:

        sleep 15

    Alternately, John Sequeira suggests adding this code to the run script:

    pid=`pidof -s postmaster`
    while !([ $pid ] && /etc/init.d/postgresql status > /dev/null 2>&1)
    pid=`pidof -s postmaster`
    echo "checking...not yet"
    sleep 1

    run AOLserver on port 80 (or <1024) To run AOLserver on a port below 1024 (normally, for a webserver use port 80), edit the run script. /var/lib/aolserver/service0/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch)

    Troubleshooting AOLserver

    Check the serverlog 

    To set up real-time monitoring of the AOLserver error log, from the shell, type

    less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log

    F to show new log entries in real time (like tail -f)
    C-c to stop and F to start it up again. 
    G goes to the end.
    ? searches backward 
    / searches forward.  

    Cannot view sample AOLserver welcome page There may be a problem with the server configuration. Start by viewing the AOLserver log, which is in /usr/local/aolserver/log/server.log. You should also try to find lines of the form:

    [01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (
    [01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections

    If you can find these lines, try entering the URL the server is listening on into your browser. If you cannot find these lines, there must be an error somewhere in the file. Search for lines beginning with the word Error instead of Notice.

    The sample-config.tcl file grabs your address and hostname from your OS settings.

    set hostname        [ns_info hostname]
    set address [ns_info address]

    If you get an error that nssock can't get the requested address, you can set these manually. If you type, AOLserver will try to listen on all available addresses. Note: ns_info address doesn't appear to be supported in current versions of AOLserver.

    set hostname        [ns_info hostname]
    #set address [ns_info address]
    set address

    NsTclInitObjs: sizeof(int) < sizeof(long) This is a 64-bit compile problem that keeps Aolserver from starting. An error detection check in file nsd/tclobj.c is causing the error, and needs to be commented out. Wrap the following code with the C style /* */ comments (as shown), then rebuild. See http://openacs.org/forums/message-view?message_id=309887 for more info.

    if (sizeof(int) < sizeof(long)) {
    Tcl_Panic("NsTclInitObjs: sizeof(int) < sizeof(long)");

    Cannot view the OpenACS login or OpenACS Installation: Welcome page. View your error log (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and aolserver failing to start due to permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with killall nsd.

    Modifying AOLserver configuration config.tcl

    • httpport - If you want your server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.

    • httpsport - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 143 to match the standard.

    • address - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.

    • server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses $OPENACS_SERVICE_NAME.

    • db_name - In almost all cases, this can be kept as a reference to $server. If for some reason, the tablespace you are using is different than your servername, then you can set it here. You should have a good reason for doing this.

    • servername - This is just a *pretty* name for your server.

    • user_account - The account that will both own OpenACS files and connect to the database (for Postgresql).

    • debug - Set to true for a very verbose error log, including many lines for every page view, success or failure.

    AOLserver is very configurable. These are some of the more commonly changed settings. For more options, read the AOLserver docs.

    AOLserver command line

    See http://www.aolserver.com/docs/admin/tech.html

    for developers

    Created by OpenACS community, last modified by Torben Brosten 22 Aug 2008, at 08:32 AM

    OpenACS for developers


    Besides the quality components of Openacs (See: en:openacs-system), OpenACS has these enterprise-quality features for developers:

    will be pulling in docs from here: http://openacs.org/doc/acs-package-dev.html and http://openacs.org/doc/acs-plat-dev.html

    Integrated Development Environments (IDE)

    These text editors are commonly used when coding on OpenACS:

    Bibliography and Credits

    See en:doc-credits.

    for administrators

    Created by OpenACS community, last modified by Torben Brosten 22 Aug 2008, at 08:29 AM

    OpenACS for administrators

    will be pulling in docs from here: http://openacs.org/doc/acs-admin.html

    Getting help: en:docs-admin-help

    Install OpenACS: en:docs-install

    set up database environment variables.. see end of http://openacs.org/doc/openacs.html

    http://openacs.org/doc/backup-recovery.html and http://openacs.org/doc/snapshot-backup.html


    creating custom pages: see developer tutorials ( http://openacs.org/doc/tutorial.html )

    Administrating a system 


    Also, these OpenACS packages are your friends:

    Performance monitoring


    Bibliography and Credits

    See en:doc-credits.

    Install Oracle

    Created by OpenACS community, last modified by Ryan Gallimore 05 Jul 2008, at 12:55 AM

    Install Oracle

    Installing Oracle is optional, if you are installing Postgresql

    An excellent guide for installing Oracle 10g on Linux can be found at www.puschitz.com.

    OpenACS 5.2.x will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues.

    This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document.

    This document assumes that you are installing Oracle on the same box as AOLserver. For more details on a remote Oracle installation, see Daryl Biberdorf's document.


    We use the following defaults while installing Oracle.

    Variable Value Reason
    ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.
    ORACLE_SERVICE ora8 The service name is a domain-qualified identifier for your Oracle server.
    ORACLE_SID ora8 This is an identifier for your Oracle server.
    ORACLE_OWNER oracle The user who owns all of the oracle files.
    ORACLE_GROUP dba The special oracle group. Users in the dba group are authorized to do a connect internal within svrmgrl to gain full system access to the Oracle system.

    Get Oracle

    You can register and download Oracle (for free) from Oracle TechNet. You need this if you want to use an Oracle database.

    Production Oracle systems should run on certified platforms. Follow the metalink note 223718.1to find certified platforms. If you don't have metalink access, take a look at the Oracle on Linux FAQ: Which Linux Distributions Are Directly Supported By Oracle?. In summary, free and inexpensive Linux distributions are not certified.

    If you don't have an account at OTN get one: you can download the Oracle software from the Oracle Downloads page. It is also get the CDs shipped to you for a nominal fee from the Oracle Store.

    Each Oracle release comes with extensive and usually quite well-written documentation. Your first step should be to thoroughly read the release notes for your operating system and your Oracle version. Find the docs here:

    It is generally useful to run a particular Oracle version with its latest patchset. At the time of writing these were and, both of which are considered to be very stable.

    To be able to download a patchset, you need an account on Metalink (not free). You may find the appropriate patchset by following Andrew's suggestion.

    Things to Keep in Mind

    Oracle is very well-documented software, the online documentation comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle within in a few hours. The best starting pointing into Oracle is the Concepts book. Here's the 8i version and the 9.2 version.

    To give you an idea of how configurable Oracle is and how much thought you may need to put into buying the proper hardware and creating a sane setup, you should thoroughly read Cary Millsap's Configuring Oracle Server for VLDB and the Optimal Flexible Architecture standard.

    Throughout these instructions, we will refer to a number of configurable settings and advise certain defaults. With the exception of passwords, we advise you to follow these defaults unless you know what you are doing. Subsequent documents will expect that you used the defaults, so a change made here will necessitate further changes later. For a guide to the defaults, please see the section called “Defaults”.

    In order for OpenACS to work properly you need to set the environment appropriately.

    export ORACLE_BASE=/ora8/m01/app/oracle
    export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
    export PATH=$PATH:$ORACLE_HOME/bin
    export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
    export ORACLE_SID=ora8
    export ORACLE_TERM=vt100
    export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

    umask 022
    open_cursors = 500
    nls_date_format = "YYYY-MM-DD"

    For additional resources/documentation, please see this thread and Andrew Piskorski's mini-guide.

    Pre-Installation Tasks

    Though Oracle 8.1.7 has an automated installer, we still need to perform several manual, administrative tasks before we can launch it. You must perform all of these steps as the root user. We recommend entering the X window system as a normal user and then doing a su -. This command gives you full root access.

    • Login as a non-root user and start X by typing startx

      [joeuser ~]$ startx
    • Open a terminal window type and login as root

      [joeuser ~]$ su -
      Password: ***********
      [root ~]#
    • Create and setup the oracle group and oracle account

      We need to create a user oracle, which is used to install the product, as well as starting and stopping the database.

      [root ~]# groupadd dba
      [root ~]# groupadd oinstall
      [root ~]# groupadd oracle
      [root ~]# useradd -g dba -G oinstall,oracle -m oracle
      [root ~]# passwd oracle

      You will be prompted for the New Password and Confirmation of that password.

    • Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has adopted /ora8 as the base directory.

      Note: the Oracle install needs about 1 GB free on /ora8 to install successfully.

      [root ~]# mkdir /ora8
      root:/ora8# cd /ora8
      root:/ora8# mkdir -p m01 m02 m03/oradata/ora8
      root:/ora8# chown -R oracle.dba /ora8
      root:/ora8# exit
    • Set up the oracle user's environment

      • Log in as the user oracle by typing the following:

        [joeuser ~]$ su - oracle
        Password: ********
      • Use a text editor to edit the .bash_profile file in the oracle account home directory.

        [oracle ~]$ emacs .bash_profile

        You may get this error trying to start emacs:

        Xlib: connection to ":0.0" refused by server
        Xlib: Client is not authorized to connect to Server
        emacs: Cannot connect to X server :0.
        Check the DISPLAY environment variable or use `-d'.
        Also use the `xhost' program to verify that it is set to permit
        connections from your machine.

        If so, open a new terminal window and do the following:

        [joeuser ~]$ xhost +localhost

        Now, back in the oracle terminal:

        [oracle ~]$ export DISPLAY=localhost:0.0
        [oracle ~]$ emacs .bash_profile

        Try this procedure anytime you get an Xlib connection refused error.

      • Add the following lines (substituting your Oracle version number as needed) to .bash_profile:

        export ORACLE_BASE=/ora8/m01/app/oracle
        export ORACLE_HOME=$ORACLE_BASE/product/8.1.7
        export PATH=$PATH:$ORACLE_HOME/bin
        export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib
        export ORACLE_SID=ora8
        export ORACLE_TERM=vt100
        export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data

        umask 022

        Save the file by typing CTRL-X CTRL-S and then exit by typing CTRL-X CTRL-C. Alternatively, use the menus.

      Make sure that you do not add any lines like the following

      # NLS_LANG=american
      # export NLS_LANG

      These lines will change the Oracle date settings and will break OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD dates.

    • Log out as oracle

      [oracle ~]$ exit
    • Log back in as oracle and double check that your environment variables are as intended. The env command lists all of the variables that are set in your environment, and grep shows you just the lines you want (those with ORA in it).

      [joeuser ~]$ su - oracle
      [oracle ~]$ env | grep ORA

      If it worked, you should see:


      If not, try adding the files to ~/.bashrc instead of .bash_profile. Then logout and log back in again. Also, be certain you are doing su - oracle and not just su oracle. The - means that .bashrc and .bash_profile will be evaluated.

      Make sure that /bin, /usr/bin, and /usr/local/bin are in your path by typing:

      [oracle ~]$ echo $PATH

      If they are not, then add them to the .bash_profile by changing the PATH statement above to PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin

    Installing Oracle 8.1.7 Server

    • Log in as oracle and start X if not already running. Start a new terminal:

      [joeuser ~]$ xhost +localhost
      [joeuser ~]$ su - oracle
      Password: **********
      [oracle ~]$ export DISPLAY=localhost:0.0
    • Find the runInstaller script

      • If you are installing Oracle from a CD-ROM, it is located in the install/linux path from the cd-rom mount point

        [oracle ~]$ su - root
        [root ~]# mount -t iso9660 /dev/cdrom /mnt/cdrom
        [root ~]# exit
        [oracle ~]$ cd /mnt/cdrom
      • If you are installing from the tarball, the install script is located in the Oracle8iR2 directory that was created when you expanded the archive.

        [oracle ~]$ cd /where/oracle/Disk1

      Check to make sure the file is there.

      oracle:/where/oracle/Disk1$ ls
      doc index.htm install runInstaller stage starterdb

      If you don't see runInstaller, you are in the wrong directory.

    • Run the installer

      oracle:/where/oracle/Disk1$ ./runInstaller

      A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on "Next"


      Some people have had trouble with this step on RedHat 7.3 and 8.0. If so, try the following steps before calling ./runInstaller:

      1. Execute the following command: /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh

      2. Type export LD_ASSUME_KERNEL=2.2.5

    • The "File Locations" screen in the OUI:

      • "Source" path should have been prefilled with "(wherever you mounted the CDROM)/stage/products.jar"

      • "destination" path says "/ora8/m01/app/oracle/product/8.1.7"

        If the destination is not correct it is because your environment variables are not set properly. Make sure you logged on as oracle using su - oracle. If so, edit the ~/.bash_profile as you did in the section called “Pre-Installation Tasks”

      • Click "Next" (a pop up window will display Loading Product information).

    • The "Unix Group Name" screen in the OUI:

      • The Unix Group name needs to be set to 'oinstall' ( we made this Unix group earlier ).

      • Click "Next"

      • A popup window appears instantly, requesting you to run a script as root:

        • Debian users need to link /bin/awk to /usr/bin/awk before running the script below

          [joueser ~]$ su -
          [root ~]# ln -s /usr/bin/awk /bin/awk
      • Open a new terminal window, then type:

        [joeuser ~]$ su -
        [root ~]# cd /ora8/m01/app/oracle/product/8.1.7
        [root ~]# ./orainstRoot.sh
        ; You should see:
        Creating Oracle Inventory pointer file (/etc/oraInst.loc)
        Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
        [root ~]# mkdir -p /usr/local/java
        [root ~]# exit
        [joeuser ~]$ exit
      • Click "Retry"

    • The "Available Products" screen in the OUI:

      • Select "Oracle 8i Enterprise Edition"

      • Click "Next"

    • The "Installation Types" screen

      • Select the "Custom" installation type.

      • Click "Next"

    • The "Available Product Components" screen

      • In addition to the defaults, make sure that "Oracle SQLJ," "Oracle Protocol Support," and "Linux Documentation" are also checked.

      • Click "Next"

      • A progress bar will appear for about 1 minute.

    • The "Component Locations" screen in the OUI

      • Click on the "Java Runtime Environment 1.1.8" It should have the path "/ora8/m01/app/oracle/jre/1.1.8"

      • Click "Next"

      • A progress bar will appear for about 1 minute.

    • The "Privileged Operation System Groups" screen in the OUI

      • Enter "dba" for "Database Administrator (OSDBA) Group"

      • Enter "dba" for the "Database Operator (OSOPER) Group"

      • Click "Next"

      • A progress bar will appear for about 1 minute.

    • The "Authentication Methods" screen

      • Click "Next"

    • The next screen is "Choose JDK home directory"

      • Keep the default path: /usr/local/java

      • Click "Next"

    • The "Create a Database" screen in the OUI

      • Select "No" as we will do this later, after some important configuration changes.

      • Click "Next"

    • The next screen is "Oracle Product Support"

      • TCP should be checked with "Status" listed as Required

      • Click "Next"

    • The "Summary" screen in the OUI

      • Check the "Space Requirements" section to verify you have enough disk space for the install.

      • Check that "(144 products)" is in the "New Installations" section title.

      • Click "Install"

      • A progress bar will appear for about 20 - 30 minutes. Now is a good time to take a break.

      • A "Setup Privileges" window will popup towards the end of the installation asking you to run a script as root

      • Run the script. Switch to the oracle user first to set the environment appropriately and then do su to get root privileges, while keeping the oracle user's enviroment.

        [joeuser ~]$ su - oracle
        Password: *********
        [oracle ~]$ su
        Password: *********
        [root ~]# /ora8/m01/app/oracle/product/8.1.7/root.sh
        ; You should see the following.

        Creating Oracle Inventory pointer file (/etc/oraInst.loc)
        Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
        # /ora8/m01/app/oracle/product/8.1.7/root.sh
        Running Oracle8 root.sh script...
        The following environment variables are set as:
        ORACLE_OWNER= oracle
        ORACLE_HOME= /ora8/m01/app/oracle/product/8.1.7
        ORACLE_SID= ora8

        Enter the full pathname of the local bin directory: [/usr/local/bin]:

        Press ENTER here to accept default of /usr/local/bin Creating /etc/oratab file... Entry will be added to the /etc/oratab file by Database Configuration Assistants when a database is created Finished running generic part of root.sh script. Now product-specific root actions will be performed. IMPORTANT NOTE: Please delete any log and trace files previously created by the Oracle Enterprise Manager Intelligent Agent. These files may be found in the directories you use for storing other Net8 log and trace files. If such files exist, the OEM IA may not restart.
      • Do not follow the instructions on deleting trace and log files, it is not necessary.

      [root ~]# exit
      [joeuser ~]$ exit
    • Go back to the pop-up window and click "OK"

    • The "Configuration Tools" screen in the OUI

      • This window displays the config tools that will automatically be launched.

    • The "Welcome" screen in the "net 8 Configuration Assistant"

      • Make sure the "Perform Typical installation" is not selected.

      • Click "Next"

      • The "Directory Service Access" screen in the "Net 8 Configuration Assistant"

      • Select "No"

      • Click "Next"

    • The "Listener Configuration, Listener Name" screen in the "Net 8 Configuration Assistant"

      • Accept the default listener name of "LISTENER"

      • Click "Next"

    • The "Listener Configuration, Select Protocols" screen in the "Net 8 Configuration Assistant"

      • The only choice in "Select protocols:" should be "TCP/IP"

      • Click "Next"

    • The "Listener Configuration TCP/IP Protocol" screen in the "Net 8 Configuration Assistant"

      • Default Port should be 1521 and selected.

      • Click "Next"

    • The "Listener Configuration, More Listeners" screen in the "Net 8 Configuration Assistant"

      • Select "No"

      • Click "Next"

    • The "Listener Configuration Done" screen in the "Net 8 Configuration Assistant"

      • Click "Next"

    • The "Naming Methods Configuration" screen in the "Net 8 Configuration Assistant"

      • Select "No"

      • Click "Next"

    • The "Done" screen in the "Net 8 Configuration Assistant"

      • Click "Finish"

    • The "End of Installation" screen in the OUI

      • Click "Exit"

      • Click "Yes" on the confirmation pop up window.

      • The Oracle Universal Installer window should have disappeared!

    Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about an hour of non-interactive time, so don't quit yet.

    Creating the First Database

    This step will take you through the steps of creating a customized database. Be warned that this process takes about an hour on a Pentium II with 128 MB of RAM.


    RedHat 7.3 and 8.0 users: Before running dbassist, do the following.

    1. Download the glibc patch from Oracle Technet into /var/tmp.

    2. cd $ORACLE_HOME

    3. tar xzf /var/tmp/glibc2.1.3-stubs.tgz

    4. ./setup_stubs

    • Make sure you are running X. Open up a terminal and su to oracle and then run the dbassist program.

      [joeuser ~]$ xhost +localhost
      [joeuser ~]$ su - oracle
      Password: *********
      [oracle ~]$ export DISPLAY=localhost:0.0
      [oracle ~]$ dbassist
    • The "Welcome" screen in the Oracle Database Configuration Agent (ODCA)

      • Select "Create a database"

      • Click "Next"

    • The "Select database type" screen in the ODCA

      • Select "Custom"

      • Click "Next"

    • The "Primary Database Type" window in ODCA

      • Select "Multipurpose"

      • Click "Next"

    • The "concurrent users" screen of the ODCA

      • Select "60" concurrent users.

      • Click "Next"

    • Select "Dedicated Server Mode", click "Next"

    • Accept all of the options, and click Next Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that everything else is checked.

    • For "Global Database Name", enter "ora8"; for "SID", also enter "ora8" (it should do this automatically). Click "Change Character Set and select UTF8. Click "Next".

    • Accept the defaults for the next screen (control file location). Click "Next"

    • Go to the "temporary" and "rollback" tabs, and change the Size (upper-right text box) to 150MB. Click "Next"

    • Increase the redo log sizes to 10000K each. Click "Next"

    • Use the default checkpoint interval & timeout. Click "Next"

    • Increase "Processes" to 100; "Block Size" to 4096 (better for small Linux boxes; use 8192 for a big Solaris machine).

    • Accept the defaults for the Trace File Directory. Click "Next"

    • Finally, select "Save information to a shell script" and click "Finish" (We're going to examine the contents of this file before creating our database.)

    • Click the "Save" button. Oracle will automatically save it to the correct directory and with the correct file name. This will likely be /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh

    • It will alert you that the script has been saved successfully.

    • Now we need to customize the database configuration a bit. While still logged on as oracle, edit the database initialization script (run when the db loads). The scripts are kept in $ORACLE_HOME/dbs and the name of the script is usually initSID.ora where SID is the SID of your database. Assuming your $ORACLE_HOME matches our default of /ora8/m01/app/oracle/product/8.1.7, the following will open the file for editing.

      [oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
    • Add the following line to the end:

      nls_date_format = "YYYY-MM-DD"
    • Now find the open_cursors line in the file. If you're using emacs scroll up to the top of the buffer and do CTRL-S and type open_cursors to find the line. The default is 100. Change it to 500.

      open_cursors = 500
    • Save the file. In emacs, do CTRL-X CTRL-S to save followed by CTRL-X CTRL-C to exit or use the menu.

    • At this point, you are ready to initiate database creation. We recommend shutting down X to free up some RAM unless you have 256 MB of RAM or more. You can do this quickly by doing a CRTL-ALT-BACKSPACE, but make sure you have saved any files you were editing. You should now be returned to a text shell prompt. If you get sent to a graphical login screen instead, switch to a virtual console by doing CRTL-ALT-F1. Then login as oracle.

    • Change to the directory where the database creation script is and run it:

      [oracle ~]$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib
      oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh

      In some instances, Oracle will save the file to /ora8/m01/app/oracle/product/8.1.7/assistants/dbca Try running the script there if your first attempt does not succeed.

    • Your database will now be built. It will take > 1 hour - no fooling. You will see lots of errors scroll by (like: "ORA-01432: public synonym to be dropped does not exist") Fear not, this is normal.

      Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it.

    Acceptance Test

    For this step, open up a terminal and su to oracle as usual. You should be running X and Netscape (or other web browser) for this phase.

    • You need to download the "Oracle Acceptance Test" file. It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. Save the file to /var/tmp

    • In the oracle shell, copy the file.

      [oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql
    • Once you've got the acceptance test file all set, stay in your term and type the following:

      [oracle ~]$ sqlplus system/manager

      SQL*Plus should startup. If you get an ORA-01034: Oracle not Available error, it is because your Oracle instance is not running. You can manually start it as the oracle user.

      [oracle ~]$ svrmgrl
      SVRMGR> connect internal
      SVRMGR> startup
    • Now that you're into SQL*Plus, change the default passwords for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember):

      SQL> alter user system identified by alexisahunk;
      SQL> alter user sys identified by alexisahunk;
      SQL> alter user ctxsys identified by alexisahunk;
    • Verify that your date settings are correct.

      SQL> select sysdate from dual;

      If you don't see a date that fits the format YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”.

    • At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes.

      SQL> @ /var/tmp/acceptance.sql

      ; A bunch of lines will scroll by. You'll know if the test worked if
      ; you see this at the end:



      Many people encounter an error regarding maximum key length:

      ERROR at line 1:
      ORA-01450: maximum key length (758) exceeded

      This error occurs if your database block size is wrong and is usually suffered by people trying to load OpenACS into a pre-existing database. Unfortunately, the only solution is to create a new database with a block size of at least 4096. For instructions on how to do this, see the section called “Creating the First Database” above. You can set the parameter using the dbassist program or by setting the DB_BLOCK_SIZE parameter in your database's creation script.

      If there were no errors, then consider yourself fortunate. Your Oracle installation is working.

    Automating Startup & Shutdown

    You will want to automate the database startup and shutdown process. It's probably best to have Oracle spring to life when you boot up your machine.

    • Oracle includes a script called dbstart that can be used to automatically start the database. Unfortunately, the script shipped in the Linux distribution does not work out of the box. The fix is simple. Follow these directions to apply it. First, save dbstart to /var/tmp. Then, as oracle, do the following:

      [oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart 
      [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
    • While you're logged in as oracle, you should configure the oratab file to load your database at start. Edit the file /etc/oratab:

      • You will see this line.


        By the way, if you changed the service name or have multiple databases, the format of this file is:

        service_name:$ORACLE_HOME:Y || N (for autoload)

      • Change the last letter from "N" to "Y". This tells Oracle that you want the database to start when the machine boots. It should look like this.

      • Save the file & quit the terminal.

    • You need a script to automate startup and shutdown. Save oracle8i.txt in /var/tmp. Then login as root and install the script. (Debian users: substitute /etc/init.d for /etc/rc.d/init.d throughout this section)

      [oracle ~]$ su -
      [root ~]# cp /var/tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i
      [root ~]# chown root.root /etc/rc.d/init.d/oracle8i
      [root ~]# chmod 755 /etc/rc.d/init.d/oracle8i
    • Test the script by typing the following commands and checking the output. (Debian Users: as root, do mkdir /var/lock/subsys first)

      [root ~]# /etc/rc.d/init.d/oracle8i stop
      Oracle 8i auto start/stop
      Shutting Oracle8i:
      Oracle Server Manager Release - Production

      Copyright (c) 1997, 1999, Oracle Corporation. All
      Rights Reserved.

      Oracle8i Enterprise Edition Release -
      With the Partitioning option
      JServer Release - Production

      SVRMGR> Connected.
      SVRMGR> Database closed.
      Database dismounted.
      ORACLE instance shut down.
      Server Manager complete.
      Database "ora8" shut down.

      [root ~]# /etc/rc.d/init.d/oracle8i start
      Oracle 8i auto start/stop
      Starting Oracle8i:
      SQL*Plus: Release - Production on Wed Mar 6 17:56:02 2002

      (c) Copyright 2000 Oracle Corporation. All rights reserved.

      SQL> Connected to an idle instance.
      SQL> ORACLE instance started.

      Total System Global Area 84713632 bytes
      Fixed Size 73888 bytes
      Variable Size 76079104 bytes
      Database Buffers 8388608 bytes
      Redo Buffers 172032 bytes
      Database mounted.
      Database opened.
      SQL> Disconnected

      Database "ora8" warm started.

      Database "ora8" warm started.
    • If it worked, then run these commands to make the startup and shutdown automatic.

      • Red Hat users:

        [root ~]# cd /etc/rc.d/init.d/                      
        [root ~]# chkconfig --add oracle8i
        [root ~]# chkconfig --list oracle8i
        ; You should see:
        oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off
      • Debian users:

        [root ~]# update-rc.d oracle8i defaults
        Adding system startup for /etc/init.d/oracle8i ...
        /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i
        /etc/rc1.d/K20oracle8i -> ../init.d/oracle8i
        /etc/rc6.d/K20oracle8i -> ../init.d/oracle8i
        /etc/rc2.d/S20oracle8i -> ../init.d/oracle8i
        /etc/rc3.d/S20oracle8i -> ../init.d/oracle8i
        /etc/rc4.d/S20oracle8i -> ../init.d/oracle8i
        /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i
      • SuSE users:

        [root ~]# cd /etc/rc.d/init.d
        root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i K20oracle8i
        root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i S20oracle8i
        root:/etc/rc.d/init.d# cp K20oracle8i rc0.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc0.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc1.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc1.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc6.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc6.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc2.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc2.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc3.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc3.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc4.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc4.d
        root:/etc/rc.d/init.d# cp K20oracle8i rc5.d
        root:/etc/rc.d/init.d# cp S20oracle8i rc5.d
        root:/etc/rc.d/init.d# rm K20oracle8i
        root:/etc/rc.d/init.d# rm S20oracle8i
        root:/etc/rc.d/init.d# cd
        [root ~]# SuSEconfig
        Started the SuSE-Configuration Tool.
        Running in full featured mode.
        Reading /etc/rc.config and updating the system...
        Executing /sbin/conf.d/SuSEconfig.gdm...
        Executing /sbin/conf.d/SuSEconfig.gnprint...
        Executing /sbin/conf.d/SuSEconfig.groff...
        Executing /sbin/conf.d/SuSEconfig.java...
        Executing /sbin/conf.d/SuSEconfig.kdm...
        Executing /sbin/conf.d/SuSEconfig.pcmcia...
        Executing /sbin/conf.d/SuSEconfig.perl...
        Executing /sbin/conf.d/SuSEconfig.postfix...
        Executing /sbin/conf.d/SuSEconfig.sendmail...
        Executing /sbin/conf.d/SuSEconfig.susehilf...
        Executing /sbin/conf.d/SuSEconfig.susehilf.add...
        Executing /sbin/conf.d/SuSEconfig.susewm...
        Executing /sbin/conf.d/SuSEconfig.tetex...
        Executing /sbin/conf.d/SuSEconfig.ypclient...
        Processing index files of all manpages...
    • You also need some scripts to automate startup and shutdown of the Oracle8i listener. The listener is a name server that allows your Oracle programs to talk to local and remote databases using a standard naming convention. It is required for Intermedia Text and full site search.

      Download these three scripts into /var/tmp

      Now issue the following commands (still as root).

      [root ~]# su - oracle
      [oracle ~]$ cp /var/tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
      [oracle ~]$ cp /var/tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr
      [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
      [oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr
      [oracle ~]$ exit
      [root ~]# cp /var/tmp/listener8i.txt /etc/rc.d/init.d/listener8i
      [root ~]# cd /etc/rc.d/init.d
      root:/etc/rc.d/init.d# chmod 755 listener8i

      Test the listener automation by running the following commands and checking the output.

      root:/etc/rc.d/init.d# ./listener8i stop
      Oracle 8i listener start/stop
      Shutting down Listener for 8i:
      LSNRCTL for Linux: Version - Production on 06-MAR-2002 18:28:49

      (c) Copyright 1998, Oracle Corporation. All rights reserved.

      Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost.localdomain)(PORT=1521)))
      The command completed successfully

      root:/etc/rc.d/init.d# ./listener8i start
      Oracle 8i listener start/stop
      Starting the Listener for 8i:
      LSNRCTL for Linux: Version - Production on 06-MAR-2002 18:28:52

      (c) Copyright 1998, Oracle Corporation. All rights reserved.

      Starting /ora8/m01/app/oracle/product/8.1.7/bin/tnslsnr: please wait...

      TNSLSNR for Linux: Version - Production
      System parameter file is /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora
      Log messages written to /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log
      Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost.localdomain)(PORT=1521)))

      Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost.localdomain)(PORT=1521)))
      STATUS of the LISTENER
      Alias LISTENER
      Version TNSLSNR for Linux: Version - Production
      Start Date 06-MAR-2002 18:28:53
      Uptime 0 days 0 hr. 0 min. 0 sec
      Trace Level off
      Security OFF
      SNMP OFF
      Listener Parameter File /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora
      Listener Log File /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log
      Services Summary...
      PLSExtProc has 1 service handler(s)
      ora8 has 1 service handler(s)
      The command completed successfully

      This test will verify that the listener is operating normally. Login into the database using the listener naming convention.

      sqlplus username/password/@SID

      [root ~]# su - oracle
      [oracle ~]$ sqlplus system/alexisahunk@ora8

      SQL> select sysdate from dual;


      SQL> exit
      [oracle ~]$ exit
      [root ~]#
      • RedHat users:

        Now run chkconfig on the listener8i script.

        [root ~]# cd /etc/rc.d/init.d/
        root:/etc/rc.d/init.d# chkconfig --add listener8i
        root:/etc/rc.d/init.d# chkconfig --list listener8i
        listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off
      • Debian users:

        Now run update-rc.d on the listener8i script.

        [root ~]# update-rc.d listener8i defaults 21 19
        Adding system startup for /etc/init.d/listener8i ...
        /etc/rc0.d/K19listener8i -> ../init.d/listener8i
        /etc/rc1.d/K19listener8i -> ../init.d/listener8i
        /etc/rc6.d/K19listener8i -> ../init.d/listener8i
        /etc/rc2.d/S21listener8i -> ../init.d/listener8i
        /etc/rc3.d/S21listener8i -> ../init.d/listener8i
        /etc/rc4.d/S21listener8i -> ../init.d/listener8i
        /etc/rc5.d/S21listener8i -> ../init.d/listener8i
    • Test the automation

      As a final test, reboot your computer and make sure Oracle comes up. You can do this by typing

      [root ~]# /sbin/shutdown -r -t 0 now

      Log back in and ensure that Oracle started automatically.

      [joeuser ~]$ su - oracle
      [oracle ~]$ sqlplus system/alexisahunk@ora8

      SQL> exit

    Congratulations, your installation of Oracle 8.1.7 is complete.

    ref: http://openacs.org/doc/current/oracle.html

    Source control

    Created by OpenACS community, last modified by Dave Bauer 02 Jun 2008, at 03:38 PM

    A Source Control system keeps track of all of the old versions of your files. It lets you recover old files, compare versions of file, and identify specific versions and groupings of files such as for controlled deployment.

    the OpenACS reference platform and the OpenACS.org repository (where you can get patched and development code in between releases) use cvs.

    This is a place to add notes about other source controls and services used by the community..



    First READ the official cvs rules http://openacs.org/forums/message-view?message_id=185506 

    These rules apply whichever source control tool OpenACS is using at the time. As of this writing, we are still using CVS.


    1. Don't mix bug fixes and new work
    2. Don't commit code before it is tested in a clean environment (new working copy)
    3. If possible, have someone else test your fix
    4. Branch when necessary, don't be afraid of it (but ask OCT first)

    1. Don't mix bug fixes and

    • Be liberal with working copies. If you need to merge custom code into OpenACS, checkout a new working copy. Don't be stingy. Disk space is cheap. This prevents many problems by reducing accidental commits.
      • bottom line: don't mix bug fixes and new work! If you have a checkout of openacs you are developing some new package or feature for an existing package, and you run into a bug, fix the bug in a clean checkout of openacs. This is the only sane way to make sure you 1) actually fix the bug and 2) don't commit other changes that don't pertain to the bug fix.

    2. Don't commit code before it is tested in clean environment

    • Review your changes before committing. If possible ask someone else to look. Do a cvs -qn update to see if the commit is not changing any files you did not expect. Use cvs diff to compare your changes to the respository.
    • So for commiting code back to openacs from your local repository you should have 2 copies
      • 1) your local code
      • 2) a working copy of OpenACS HEAD
    • You should make all changes in the working copy and fully test it, running automated tests and checking to make sure you did not accidentally change something or add in client specific  code that is not reusable by OpenACS.

    3. If possible, have someone else test your fix

    • this should be self-evident, a second pair of eyes always helps to find something you missed.
    • if another person is not possible, write an automated test, in fact, write one anyway! 

    4. Branch when necessary, don't be afraid of it (but ask OCT first)

    • Large projects should be done on a branch. This is a pain with CVS, but it is the only sensible way to do this. Examples include any project that will span a major release cycle. It is the responsibility of the person doing the branch to keep up to date with HEAD and to merge and have the code tested. It is sensible to test in a working copy BEFORE commiting the code.


    Here is my heretical idea. I think we must have another branch. Here is how it would work.

    1) developer has a working copy.

    2) develop commits code to HEAD

    3) code is merged to testing branch

    4) code is tested

    5) code is moved to release branch

    Yes, this is extra work. I believe it is worth it. It is a serious pain with CVS. We started using svnmerge.py for Subversion on our private repository and I saw immediate improvements in process. In this case I think having a well defined process AND tools that facilitate the process are key. OpenACS lacks a well defined process, discipline, and tools to facilitate the process. I believe we need to work harder to define this process and I would like to collaborate with the community on this.


    Install AOLserver 4.5

    Created by Malte Sussdorff, last modified by Nima Mazloumi 28 Feb 2008, at 11:38 AM

    If you want to install AOLserver 4.5 you could follow the instructions for AOLserver en:aolserver-install and replace 40r10 with 4.5 (more or less ...).

    Alternatively follow the instructions or download it as a shell script (recommended) or download a full archive aolserver45-oacs.tar.bz2.

    If on "OS X" the install fails for nspostgres with undefined symbols, execute the following command:

    gcc -pipe -dynamiclib -install_name /usr/local/aolserver45/lib/libnspostgres.dylib  -o libnspostgres.dylib nspostgres.o -L/usr/local/aolserver45/lib -lnsd -lnsthread -L/usr/local/aolserver45/lib -ltcl8.4   -lpthread -framework CoreFoundation   -lnsdb -L/usr/local/pgsql/lib -lpq


    Conditional CREATE Index for Postgresql and Oracle

    Created by Gustaf Neumann, last modified by Dave Bauer 21 Nov 2007, at 03:03 PM

    In order to create an index conditionally (e.g. only, if it does not exist) in postgresql or in oracle, one can use the following two idioms


    create or replace function inline_0() returns integer as '

    declare v_exists integer;
    select into v_exists count(*) from pg_class where relname = ''acs_permissions_object_id_idx'';
    if v_exists = 0 then
    create index acs_permissions_object_id_idx on acs_permissions(object_id);
    end if;
    return null;
    end;' language 'plpgsql'

    select inline_0();
    drop function inline_0();


    declare v_exists integer;

    select count(*) into v_exists from user_indexes where lower(index_name)='acs_permissions_object_id_idx';
    if v_exists = 0 then
    execute immediate 'create index acs_permissions_object_id_idx on acs_permissions(object_id)';
    end if;

    show errors

    These examples were  posted by Dave Bauer OpenACS Development  forum and can be used in a similar style for conditionally creating tables, etc.

    Installing OpenACS on Solaris

    Created by OpenACS community, last modified by Torben Brosten 07 Mar 2007, at 05:18 AM

    Should you decide to Install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

    See threads:

    for everyone - Table of Contents

    Created by OpenACS community, last modified by Torben Brosten 15 Jan 2007, at 01:37 AM







    for developers - Table of Contents

    Created by OpenACS community, last modified by Torben Brosten 15 Jan 2007, at 01:36 AM









    for administrators - Table of Contents

    Created by OpenACS community, last modified by Torben Brosten 15 Jan 2007, at 01:35 AM









    Oracle notes

    Created by Jade Rubick, last modified by Torben Brosten 14 Jan 2007, at 11:02 PM

    Oracle notes

    How do I use a literal ampersand within a SQL statement for INSERT, SELECT, etc.?

    This is a sqlplus issue, I believe. See this link for a workaround: http://www.jlcomp.demon.co.uk/faq/litampersand.html
    If you're on a *nix box - yasql is a great replacement for sql*plus.

    Is there an equivalent of Postgres' vacuum analyze

    No, not really, but you can do something similar to speed up a table:
     analyze table ticket_xrefs compute statistics;
    This will look at the usage statistics, and update them. This can dramatically increase performance when the amount of data in a table has changed a lot.

    Moving one Oracle instance to another server

    Apparently, Oracle installations are fairly self-contained. In theory, at least, you should be able to move an installation from one server to another by shutting down the server, tarring up the /ora8 directory, sftping it to another server, untarring it, and possibly running the setup_stubs.sh script.

    Needless to say, this is much easier than reinstalling, exporting the database, and importing it back in. No guarantees on how well it works, however.

    Turning on autotrace

    Turning on Autotrace

    Hierarchical queries and getting around join problem with CONNECT BY


    Getting [too long] messages?

    If you're using Oracle, this thread describes how to set up Aolserver so that you receive the entire error message from the Oracle database driver. If you get an error message starting with SQL: [too long], then you need to read this. Sometimes, for long error messages, your error messages are truncated, which makes tracking down the errors more difficult.

    Efficient updates

    You can do this
    (SELECT col1, value
    FROM t1, t2
    WHERE t1.key = t2.key
    AND t2.col2 = :other_value)
    SET col1 = value

    Using lots of dynamic SQL (more than 32768 chars?)

    You cannot use a clob, so use the dbms_sql package:
    l_stmt dbms_sql.varchar2s;
    l_cursor integer default dbms_sql.open_cursor;
    l_rows number default 0;
    l_stmt(1) := 'insert';
    l_stmt(2) := 'into foo';
    l_stmt(3) := 'values';
    l_stmt(4) := '( 1 )';

    dbms_sql.parse( c => l_cursor,
    statement => l_stmt,
    lb => l_stmt.first,
    ub => l_stmt.last,
    lfflg => TRUE,
    language_flag => dbms_sql.native );

    l_rows := dbms_sql.execute(l_cursor);

    dbms_sql.close_cursor( l_cursor );
    This is from Tom Kyte, Oracle God.

    Online table updates

    DBMS Redefinition package

    PL/SQL exception handling

  • Exception handling in PL/SQL

    SPfile and Pfile startups

    $ sqlplus /nolog

    SQL*Plus: Release - Production on Tue Feb 28 19:04:30 2006

    Copyright (c) 1982, 2005, Oracle. All rights reserved.

    19:04:34 > connect / as sysdba
    19:05:21 sys@vs> startup pfile=/u01/app/oracle/admin/vs/pfile/init.ora.192006104950
    ORACLE instance started.

    Total System Global Area 285212672 bytes
    Fixed Size 1218992 bytes
    Variable Size 92276304 bytes
    Database Buffers 188743680 bytes
    Redo Buffers 2973696 bytes

    Database mounted.
    Database opened.
    19:05:37 sys@vs> 19:05:37 sys@vs>
    19:05:38 sys@vs> create spfile from pfile='/u01/app/oracle/admin/vs/pfile/init.ora.192006104950';

    File created.
  • Troubleshooting Oracle Dates

    Oracle has an internal representation for storing the data based on the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, it uses an Oracle-specific format which isn't copacetic. You want Oracle to use the ANSI-compliant date format which is of form 'YYYY-MM-DD'.

    To fix this, you should include the following line in $ORACLE_HOME/dbs/initSID.ora or for the default case, $ORACLE_HOME/dbs/initora8.ora

    nls_date_format = "YYYY-MM-DD"

    You test whether this solved the problem by firing up sqlplus and typing:

    SQL> select sysdate from dual;

    You should see back a date like 2000-06-02. If some of the date is chopped off, i.e. like 2000-06-0, everything is still fine. The problem here is that sqlplus is simply truncating the output. You can fix this by typing:

    SQL> column sysdate format a15
    SQL> select sysdate from dual;

    If the date does not conform to this format, double-check that you included the necessary line in the init scripts. If it still isn't working, make sure that you have restarted the database since adding the line:

    [joeuser ~]$ svrmgrl
    SVRMGR> connect internal
    SVRMGR> shutdown
    Database closed.
    Database dismounted.
    ORACLE instance shut down.
    SVRMGR> startup
    ORACLE instance started.

    If you're sure that you have restarted the database since adding the line, check your initialization scripts. Make sure that the following line is not included:

    export nls_lang = american

    Setting this environment variable will override the date setting. Either delete this line and login again or add the following entry to your login scripts after the nls_lang line:

    export nls_date_format = 'YYYY-MM-DD'

    Log back in again. If adding the nls_date_format line doesn't help, you can ask for advice in our OpenACS forums.

    Useful Procedures

    • Dropping a tablespace

      • Run sqlplus as the dba:

        [oracle ~]$ sqlplus system/changeme
      • To drop a user and all of the tables and data owned by that user:

        SQL> drop user oracle_user_name cascade;
      • To drop the tablespace: This will delete everything in the tablespace overriding any referential integrity constraints. Run this command only if you want to clean out your database entirely.

        SQL> drop tablespace table_space_name including contents cascade constraints;

    For more information on Oracle, please consult the documentation.

    Creating an appropriate tuning and monitoring environment

    The first task is to create an appropriate environment for finding out what is going on inside Oracle. Oracle provides Statspack, a package to monitor and save the state of the v$ performance views. These reports help finding severe problems by exposing summary data about the Oracle wait interface, executed queries. You'll find the installation instructions in $ORACLE_HOME/rdbms/admin/spdoc.txt. Follow the instructions carefully and take periodic snapshots, this way you'll be able to look at historical performance data.

    Also turn on the timed_statistics in your init.ora file, so that Statspack reports (and all other Oracle reports) are timed, which makes them a lot more meaningful. The overhead of timing data is about 1% per Oracle Support information.

    To be able to get a overview of how Oracle executes a particular query, install "autotrace". I usually follow the instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html.

    Make sure, that the Oracle CBO works with adequate statistics

    The Oracle Cost Based optimizer is a piece of software that tries to find the "optimal" execution plan for a given SQL statement. For that it estimates the costs of running a SQL query in a particular way (by default up to 80.000 permutations are being tested in a Oracle 8i). To get an adequate cost estimate, the CBO needs to have adequate statistics. For that Oracle supplies the dbms_stats package.


    Useful links

    End-users - Req.

    Created by Torben Brosten, last modified by Torben Brosten 09 Jan 2007, at 10:29 AM

    Documentation Requirements for End-users

    By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

    OpenACS end-user documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

    • End-users should not have to read docs to use the system.

    • Include how to get help. How and where to find answers, contact others, what to do if one gets an AOLserver or other error when using the system. Include types of available support (open-source, private commercial etc.) including references.

    • Explain/foster understanding of the overall structure of the system. This would be an overview of the system components, how it works, and how to find out more or dig deeper... To promote the system by presenting the history of the system, and writing about some tacit knowledge re: OpenACS.org and the opensource culture.

    • Introduce and inspire readers about the uses, benefits, and the possibilities this system brings (think customer solution, customer cost, convenience, value). A comprehensive community communications system; How this system is valuable to users; Reasons others use OpenACS (with quotes in their own words) "...the most important thing that the ACS does is manage users, i.e. provide a way to group, view and manipulate members of the web community. -- Talli Somekh, September 19, 2001" using it to communicate, cooperate, collaborate... OpenACS offers directed content functionality with the OpenACS templating system. ... OpenACS is more than a data collection and presentation tool. OpenACS has management facilities that are absent in other portals. ...The beauty of OpenACS is the simplicity (and scalability) of the platform on which it is built and the library of tried and tested community building tools that are waiting to be added. It seems that most portals just add another layer of complexity to the cake. See Slides on OACS features...a set of slides on OACS features that can be used for beginners who want to know OACS is about and what they can do with it. Screen captures that highlight features. Example shows BBoard, calendar, news, file storage, wimpy point, ticket tracking. An OpenACS tour; an abbreviated, interactive set of demo pages.

    • From a marketing perspective,

      • differentiate "product" by highlighting features, performance quality, conformance to standards, durability (handling of technological obsolescence), reliability, repairability, style of use, design (strategy in design, specifications, integrated, well-matched systems etc).

      • differentiate "service" by highlighting software availability (licensing and completeness from mature to early adopters or development versions), community incident support, project collaborative opportunities, and contractor support availability

      • differentiate price (economic considerations of opensource and features)

      • Discussion and details should rely on meeting criteria of design, completeness of implementation, and related system strengths and weaknesses. Marketing should not rely on comparing to other technologies. Competitive analysis involves mapping out strengths, weaknesses, opportunities and threats when compared to other systems for a specific purpose, and thus is inappropriate (and becomes stale quickly) for general documentation.

      • When identifying subsystems, such as tcl, include links to their marketing material if available.

      • create an example/template comparison table that shows versions of OpenACS and other systems (commonly competing against OpenACS) versus a summary feature list and how well each meets the feature criteria. Each system should be marked with a date to indicate time information was gathered, since information is likely volatile.

    • To build awareness about OpenACS, consider product differentiation: form, features, performance quality, conformance quality (to standards and requirements), durability, reliability, repairability, style, design: the deliberate planning of these product attributes.

    • Include jargon definitions, glossary, FAQs, site map/index, including where to find Instructions for using the packages. FAQ should refer like answers to the same place for consistency, brevity and maintainability.

    • Explain/tutorial on how the UI works (links do more than go to places, they are active), Page flow, descriptions of form elements; browser/interface strengths and limitations (cookies, other)

    • Discuss criteria used to decide which features are important, and the quality of the implementation from a users perspective. Each project implementation places a different emphasis on the various criteria, which is why providing a framework to help decide is probably more useful than an actual comparison.

    Package documentation requirements have additional requirements.

    • A list of all packages, their names, their purposes, what they can and cannot do (strengths, limitations), what differentiates them from similar packages, minimal description, current version, implementation status, author/maintainers, link(s) to more info. Current version available at the repository.

    • Include dependencies/requirements, known conflicts, and comments from the real world edited into a longer description to quickly learn if a package is appropriate for specific projects.

    • Create a long bulleted list of features. Feature list should go deeper than high-level feature lists and look at the quality of the implementations (from the user's perspective, not the programmer's). Example issues an end-user may have questions about: Ticket Tracker and Ticket Tracker Lite, why would I want one of them vs the other? And, before I specify to download and install it, what credit card gateways are supported by the current e-commerce module? There are some packages where the name is clear enough, but what are the limitations of the standard package?

    • End-user docs should not be duplicative. The package description information and almost everything about a package for administrators and developers is already described in the package itself through two basic development document templates: a Requirements Template and Detailed Design Document.

    PostgreSQL Administration

    Created by OpenACS community, last modified by Torben Brosten 31 Dec 2006, at 08:25 AM

    Administrating PostgreSQL

    Finding and fixing expensive queries

    Probably the most important thing you can do to improve performance is rewriting queries to run quickly. Explain analyze is your friend. OpenACS also includes tools to track down slow queries, and you can ask PostgreSQL to give you information about queries as well.

    First you should install the acs-developer-support package on a development or staging server. In general its not a good idea to keep the develop support tracking features running constantly on a production system, but you can turn it on temporarily to diagnose a problem on a production system. Once Developer Support is installed you can visit /ds/ on your site and turn on the developer support toolbar and database statistics. This will give you a total of the time for all queries for a page in the toolbar at the top of the page. If you click on the timing information you can see a page that lists every query run for that page. It should be easy to spot the slow running query in the list.

    Once you find the slow running query you can copy it to your clipboard. Next you want to open a psql session on the database server, or use M-x sql-postgres most in emacs. Type "explain analyze" and paste the query after that. This will tell postgresql to run the query and show the query plan it will use.  The first thing to look for is a "Sequential Scan" on a large table. If the table is small (hundreds instead of thousands of rows, for example)  it is probably cheaper to scan the table than to load an index, but on large tables like "acs_objects". "users", "cr_items", a sequential scan is a sign of trouble.

    PostgreSQL does not seem to generate good plans if you do a join with a view. In this case you should try to recreate the query using the tables in the view explicitly. This can speed up many queries. A comman example is the cc_users view, or the cr_revisionsx view or the (x) view automatically created for subtypes of cr_revisions.

    If you can't figure out why the query plan is slow, post it somewhere on the OpenACS forums or ask for advice in the #openacs irc channel. (http://openacs.org/irc/) 

    This will help you is you know which page is slow. If you don't know which is slow, but notice a high load on PostgreSQL on your server. You'll need to turn on the stats collector and command string collector in PostgreSQL. In the postgresql.conf file set

    stats_start_collector true


    stats_command_string true

    and then do /etc/init.d/postgreql reload or pg_ctl reload to turn it on.

    Once this is on you can execute "select * from pg_stat_activity" to see if there are any long running queries. Most queries will finish too quickly to notice in this table. The table includes the start time of the query and the process id of the backend executing the query. Sometimes you'll find a particularly bad query has been running for a very long time. Sometimes hours. If this happens you can stop the query by issuing a SIGINT signal to the process of the backend that is running that query. This will execute a cancel request to the backend and is the only safe way to stop a long running query. Do not kill the process or try to stop AOLserver. If you stop AOLserver the query will continute to run in the PostgreSQL backend process.


    Tuning PostgreSQL

    Tune postgres. (OPTIONAL). The default values for PostgreSQL are very conservative; we can safely change some of them and improve performance.

    1. Change the kernel parameter for maximum shared memory segment size to 128Mb: DAVEB: How current is this? Do modern 2.4 or 2.6 kernels have such low settings? This is highly dependent also on the amount of RAM on your server, most realy servers have gigabytes of RAM so adjust accordingly.

      [root root]# echo 134217728 >/proc/sys/kernel/shmmax
      [root root]#

      Make that change permanent by editing /etc/sysctl.conf to add these lines at the end:

      # increase shared memory limit for postgres
      kernel.shmmax = 134217728
    2. Edit the PostgreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory. These values should improve performance in most cases. (more information

      #       Shared Memory Size
      shared_buffers = 15200 # 2*max_connections, min 16

      # Non-shared Memory Sizes
      sort_mem = 32168 # min 32

      # Write-ahead log (WAL)
      checkpoint_segments = 3 # in logfile segments (16MB each), min 1

      Restart postgres (service postgresql restart) or (/etc/init.d/postgres restart) so that the changes take effect.

    Performance tuning resources:

    more information about PostgreSQL

    Vacuuming multiple databases

    If you are frequently creating and dropping various databases, using this in your crontab can help simplify setup:

    vacuumdb --all --verbose

     Debugging queries

    You can work directly with the database to do debugging steps like looking directly at tables and testing stored procedures. Start emacs. Type M-x sql-postgres. Press enter for server name and use $OPENACS_SERVICE_NAME for database name. You can use C-(up arrow) and C-(down arrow) for command history.

    Hint: "Parse error near *" usually means that an xql file wasn't recognized, because the tcl file is choking on the *SQL* placeholder that it falls back on.


    Developer Tutorial - Req.

    Created by OpenACS community, last modified by Torben Brosten 27 Oct 2006, at 09:48 AM

    Documentation Requirements for Developer Tutorials

    By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

    OpenACS developer tutorial documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

    • list learning prerequisites to customize, fix, and improve OACS modules, and create new ones. You are expected to have read and understand the information [minimum requirements similar to adept at Using OpenACS Administrating Guide] before reading this guide.

    • Refer to development documentation instead of duplicating here

    • List suggestions for installing and setting up a development environment; these can be annotated links to the installation documentation

    • Provide working examples that highlight the various subsystems, tcl environment, OpenACS protocols, aolserver template and ns_* commands, OpenACS templating, sql queries, db triggers, scheduling protocols, how to use the page contract, how to get the accessing user_id etc

    • Show how to construct basic SQL queries using the db API,

    • The life of an http request to a dynamic, templated page

    • General rules to follow for stability, scalability

    • Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package development, by referring to developer resources.

    • Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a PostgreSQL equivalent tutorial about developing a new OpenACS package including discussion of the significance of the package documentation templates

    • Include a summary of important links used by developers

    • Note any deprecated tools and methods by linking to prior versions instead of describing them in current docs

    Getting admin-level help

    Created by OpenACS community, last modified by Torben Brosten 27 Oct 2006, at 09:47 AM

    Getting admin-level help

    Keeping track of the commands you run and recording their output has important diagnostic value. I like to create a literal history of my installations in a shell inside of emacs (M-x shell) so that I can save the output if needed. An alternative would be to use the script command.

    Check the error logs. We point out the location of error logs for the various pieces of software. Output from those logs will help you, and help us help you. Do not worry if you feel overwhelmed by all the information in the error logs. Over time, you will find that they make more and more sense. At some point, you may actually look forward to errors so that you can run to the log and diagnose the problem.

    If something goes wrong, do not panic. There are plenty of ways to get help. Here are some:

    • Search the forums at openacs.org - Frequently, people who have struggled through the same issue have already posted and received help with answers immediately available to you.

    • The bottom of each page has a link to OpenACS.org, where you can post comments and read other users comments about the contents of the page.

    • Post a question on the forums. Make sure you've done a search first. When you do post, be sure to include your setup information (OS, etc) as well as the exact commands that are failing with the accompanying error. If there is a SQL error in the TCL error or in the log, post that too.

    • Ask questions at the irc channel on freenode.net (#openacs). They're knowledgeable and quite friendly if you can keep them on topic.

    • If you find errors in this document or if you have ideas about making it better, please post them in the forum or BugTracker.


    Created by OpenACS community, last modified by Torben Brosten 25 Oct 2006, at 10:37 AM


    PostgreSQL is an open-source, ACID-compliant RDBMS

    What others say about PostgreSQL

    OpenACS uses Postgresql with PL/PgSQL.

    Using PostgreSQL with OpenACS

    Install PostgreSQL en:postgresql-install

    Administrating PostgreSQL en:postgresql-admin

    OpenACS Debian Install quicksheet

    Created by Ryan Gallimore, last modified by Gustaf Neumann 24 Sep 2006, at 10:29 PM

    # PostgreSQL

    apt-get install postgresql postgresql-dev postgresql-doc
    ln -s /usr/include/postgresql/ /usr/include/pgsql
    ln -s /var/lib/postgres /usr/local/pgsql
    ln -s /usr/include/pgsql /usr/local/pgsql/include
    su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1"
    su postgres -c "createuser -a -d service1"
    su postgres -c "createdb -E UNICODE service1"

    # AOLServer
    apt-get install aolserver4 aolserver4-nspostgres aolserver4-nssha1 aolserver4-nscache tdom

    # OpenACS
    groupadd web
    useradd -g web service1
    mkdir /var/lib/aolserver
    chown -R service1 /var/lib/aolserver
    chgrp -R web /var/lib/aolserver
    chmod -R 770 /var/lib/aolserver

    su - service1
    cd /tmp
    wget http://openacs.org/projects/openacs/download/download/openacs-5.1.5.tar.gz
    cd /var/lib/aolserver
    tar xzf /tmp/openacs-5.1.5.tar.gz
    mv /tmp/openacs-5.1.5 service1

    chmod -R 755 service1
    chown -R service1.web service1


    # Copy Files (where / is root of OpenACS instance):
    # [edit hostname and address]
    config.tcl => /etc/
    set homedir                   /usr/lib/aolserver4
    set bindir                    /usr/lib/aolserver4/bin

    # init/d script:

    # Start the AOLServer HTTP server.

    NAME="OpenACS on service1"
    trap "" 1


       echo -n "Starting web server: $NAME"
       echo -e -n "\r"


        #we need to export the library stuff first
        export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
        export PATH=$PATH:/usr/local/pgsql/bin

        # give time for Postgres to come up
        sleep 1
        exec /usr/sbin/aolserver4-nsd -it $SERVICEPATH/etc/config.tcl -u service1 -g web &

        # For AOLserver 4 using privileged ports (usually < 1024), add the flag
       # -b youraddress:yourport

        echo ""

        echo -n "Stopping web server: $NAME"
        killall aolserver4-nsd
        echo ""

    case "$1" in



        sleep 2

        echo "Usage: /etc/init.d/$NAME {start|stop|restart}"
        exit 1

    echo -n -e "\c\r\n"
    exit 0

    # End of script

    # avoid pid not found errors in the log

    mkdir /usr/lib/aolserver4/log
    chown root:web /usr/lib/aolserver4/log
    chmod 775 /usr/lib/aolserver4/log

    # Set openacs to start on boot
    update-rc.d openacs-service1 defaults
    chmod u+x openacs-service1
    ln -s /var/lib/aolserver/service1

    OpenACS system

    Created by OpenACS community, last modified by Torben Brosten 25 Aug 2006, at 10:51 PM

    OpenACS is a n-tier architecture web application toolkit built on these software components:

    1. OpenACS toolkit en:openacs-subsystem
    2. an interpretive, markup language en:tcl
    3. a robust, http server en:aolserver
    4. a mature, relational database management system (RDMS) en:postgresql or en:oracle that follows the SQL standard (Why not MySQL?) and uses a procedural language (PL/SQL or PL/pgSQL).
    5. unix-like operating system en:os-nix

    And works well with minimum hardware requirements (en:docs-install).

    Chart Showing the parts of OpenACS

    OpenACS System Chart

    The blue dotted line hints at the path of a dynamic page request --from client to server and back. Each of the subsystems on the left can be directly accessed by a page request, whereas the database is only indirectly accessible. The arrows represent the pools of database connections that help manage queries --one of the key reasons that OpenACS performs well.

    tDOM with OpenACS

    Created by OpenACS community, last modified by Torben Brosten 10 Aug 2006, at 11:12 PM

    Using tDOM with OpenACS

    OpenACS Reference Platform

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:23 AM

    These are the defaults we create and use during the standard installation process, in helper scripts and other places. None of these locations are set in stone - they're simply the values that we've chosen.

    Default directories for a standard install

    Fully qualified domain name of your server yourserver.test
    name of administrative access account remadmin
    OpenACS service service0
    OpenACS service account service0
    OpenACS database name service0
    SERVERROOT - base of the OpenACS service file tree /var/lib/aolserver/service0
    Location of source code tarballs for new software /var/tmp
    The OpenACS tarball contains some files which are useful while setting up other software. Those files are located at: /var/lib/aolserver/service0/packages/acs-core-docs/www/files
    Database backup directory /var/lib/aolserver/service0/database-backup
    Service config files /var/lib/aolserver/service0/etc
    Service log files /var/lib/aolserver/service0/log
    Base compile directory /usr/local/src
    PostgreSQL directory /usr/local/pgsql
    AOLserver directory /usr/local/aolserver

    Some instructions provide cut and paste conveniences

    In order for some copy and paste instructions to work in your bash shell, you must set the environment variable $OPENACS_SERVICE_NAME. Add this line to your .bashrc or .profile_bash file to set the environment variable for a specific user:

    export OPENACS_SERVICE_NAME=service0

    To set it globally so that it works for any new users or special service users you may create, add the above line to the file /etc/profile

    $OPENACS_SERVICE_NAME is set to the value of service0 on a default install. Change service0 to a word that better represents your project. The other values we recommend you leave unchanged unless you have a reason to change them.

    A service name ($OPENACS_SERVICE_NAME) should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For example "$OPENACS_SERVICE_NAME" might be the service name for the OPENACS_SERVICE_NAME.net website.

    Some discussion that lead to these default values: http://openacs.org/forums/message-view?message_id=82934

    XoWiki User Guide

    Created by Jon Griffin, last modified by Robert Taylor 07 Aug 2006, at 03:22 AM

    Understanding xowiki

    First, this assumes you have xowiki installed.

    Next, mount up a site where you would like a wiki.

    Then go to that link and you will see your folder.

    Add a category or 2 by clicking on Site-Wide Categories.

    You can use an existing category or create your own.

    We will create a category called recipes.

    category 2

    And you can add root categories as needed, then back to the assign categories screen.

    category 3

    Here is how it looks when we pick recipes as a mapped category to our new xowiki.

    Notice I made it mandatory to choose a category, and now we have a category assigned.

    category 5 

    Now we can add a page and use it as an index if you would like. I clicked on “Add XOWiki Plain Page” so I don’t have the wysiwig widget.

    We will call this en:index. It is under category beer-recipes.


    Now lets fix the folder to automatically use the index page.

    Now you can add a page and you will see that it shows up under your category.

    Here it is indexed on the en:index page 

    PostgreSQL's Tsearch2

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:22 AM

    Install Full Text Search using Tsearch2

    By Dave Bauer, Joel Aufrecht, and Malte Sussdorff, with help from Tsearch V2 Introduction by Andrew J. Kopciuch

    Install Tsearch2 module

    This is a PostgreSQL module that the OpenACS tsearch2-driver package requires.

    If you want full text search (FTS), and you are running PostgreSQL version 7.3 or greater, install this module to support FTS. Do this step after you have installed both PostgreSQL and AOLserver. The tsearch2 module is included with the PostgreSQL full source distribution. It is also available with the PostgreSQL contrib package provided by most distribution ports.

    1. For PostgreSQL 7.3, refer to the Installation docs for details, because the Tsearch2 project has revised the installation since PostgreSQL 7.3 was deprecated.

      For PostgreSQL 7.4, download the http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz tsearch2 patch to correctly restore from a pg_dump backup. To apply this patch, download the mentioned file and place it in your postgreSQL source tree ($PGSQL_SRC). This patch makes the backup and restore procedures very simple.

                  [postgres pgsql]$ cd /tmp
                  [postgres tmp]$ wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz
                  [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/
                  [postgres postgresql-7.4.5] gunzip /tmp/regprocedure_7.4.patch.gz
                  [postgres postgresql-7.4.5] patch -b -p1 < regprocedure_7.4.patch

      If you installed tsearch2 from a ports package, you can use the http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql regprocedure script to update the database after tsearch2 is installed into it.

      If you have a working version of tsearch2 in your database, you do not need to re-install the tsearch2 module. Just apply the patch and run make. This patch only affects the tsearch2.sql file. You can run the SQL script found : [right here] This script will make the modifications found in the patch, and update the fields from the existing data. From this point on, you can dump and restore the database in a normal fashion. Without this patch, you must follow the instructions at the Tsearch2 project website for backup and restore.

      Postgresql 8.0 and above include the latest stable release with the above patch(es) applied.

    2. Install Tsearch2. These instructions assume you are using the latest point release of PostgreSQL 7.4.5.

      [root root]# su - postgres
      [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/
      [postgres tsearch2]$ make
      [postgres tsearch2]$ make install
      mkdir /usr/local/pgsql/share/contrib
      mkdir /usr/local/pgsql/doc/contrib
      (2 lines omitted)
      /bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so
      [postgres tsearch]$ exit
      [root root]#
      su - postgres
      cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2
      make install


    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:21 AM


    Oracle is an enterprise level, ACID-compliant RDBMS

    What others say about Oracle

    Oracle (Oracle.com)

    OpenACS uses Oracle with PL/SQL

    OpenACS subsystem

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:21 AM

    OpenACS subsystem

    ..consists of a collection of tcl/adp/xql files that are interpreted by the other main components of OpenACS (en:openacs-system)

    Mail Transport Agents

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:20 AM

    a program that handles all incoming and outgoing mail. The Reference Platform uses Qmail; any MTA that provides a sendmail wrapper (that is, that can be invoked by calling the sendmail program with the same variables that sendmail expects) can be used with OpenACS.

    This is a placeholder for notes implementing specific MTAs with OpenACS

    Installing OpenACS on SuSE

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:20 AM

    Should you decide to Install OpenACS from source using general en:openacs-system-install instructions, refer to these notes for changes:

    Installing [en:postgresql

    Set PostgreSQL to start on boot

    [root ~]# cp /var/tmp/openacs-5.2.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
    [root ~]# chown root.root /etc/init.d/postgresql
    [root ~]# chmod 755 /etc/init.d/postgresql

    Test the script.

    [root ~]# /etc/init.d/postgresql stop
    Stopping PostgreSQL: ok

    If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown.

    [root ~]# cd /etc/init.d
    root:/etc/init.d# ln -s /etc/init.d/postgresql K20postgresql
    root:/etc/init.d# ln -s /etc/init.d/postgresql S20postgresql  
    root:/etc/init.d# cp K20postgresql rc2.d
    root:/etc/init.d# cp S20postgresql rc2.d
    root:/etc/init.d# cp K20postgresql rc3.d
    root:/etc/init.d# cp S20postgresql rc3.d
    root:/etc/init.d# cp K20postgresql rc4.d
    root:/etc/init.d# cp S20postgresql rc4.d 
    root:/etc/init.d# cp K20postgresql rc5.d
    root:/etc/init.d# cp S20postgresql rc5.d
    root:/etc/init.d# rm K20postgresql
    root:/etc/init.d# rm S20postgresql

    Test configuration.

    root:/etc/init.d # cd
    root:~ # /etc/init.d/rc2.d/S20postgresql start
    Starting PostgreSQL: ok
    root:~ # 

    Installation - Req.

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:19 AM

    Installation Documentation Requirements

    By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

    OpenACS installation documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

    • state installation prerequisites. For example: "You should read through the installation process to familiarize yourself with the installation process, before beginning an installation."

    • list critical decisions (perhaps as questions) that need to be made before starting: which OS, which DB, which aolserver version, system name, dependencies et cetera. Maybe summarize options as tables or decision-trees. For example, "As you proceed throughout the installation, you will be acting on decisions that have an impact on how the remaining part of the system is installed. Here is a list of questions you should answer before beginning."

    • list pre-installation assumptions

    • Show chronological overview of the process of installing a system to full working status: Install operating system with supporting software, configure with preparations for OpenACS, RDBMS(s) install and configure, Webserver install and configure, OpenACS install and configure, post-install work

    Developer - Requirements

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:13 AM

    Developers - Documentation Requirements

    By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

    OpenACS developer documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

    • list documentation assumptions, such as familiarity with modifying OpenACS packages. All kernel docs are here etc.

    • This documentation should be written for ongoing use by developers, not as a tutorial.

    • List of practical development and diagnostics tools and methodologies.

    • List of OpenACS development resources, api-doc, schema-browser, developer-support package etc.

    • Identify each OpenACS subsystem, explain why it is used (instead of other choices). In the case of subsystems that are developed outside of OpenACS such as tcl, include external references to development and reference areas.

    • Show current engineering standards and indicate where changes to the standards are in the works.

    • Sections should be dedicated to DotLRN standards as well, if they are not available elsewhere.

    • Add overview diagrams showing the core parts of the datamodel including an updated summary of Greenspun's Chapter 4: Data Models and the Object System

    • package design guidelines and development process templates including planning, core functions, testing, usability, and creating case studies

    • Standard package conventions, where to see "model" code, and guidelines (or where to find them) for:

      • programming tcl/sql

      • using the acs-api

      • ad_form

      • coding permissions

      • OpenACS objects

      • scheduled protocols

      • call backs

      • directory structure

      • user interface

      • widgets

      • package_name and type_extension_table

      • adding optional services, including search, general comments, attachments, notifications, workflow, CR and the new CR Tcl API

    • Document kernel coding requirements, strategy and guidelines to help code changers make decisions that meet kernel designers' criteria

    Deployment feedback channel

    Created by Aernout Schmidt, last modified by Robert Taylor 07 Aug 2006, at 03:13 AM

    Pupose: A channel for sharing heuristics found in the installation and deployment of OpenACS and its packages.   

    1. It may be useful to remember that after successful install of packages like Lars-blogger or Xowiki any content added for testing puposes can (and soon will) be scooped by search engines and/or broadcasted by rss feeds and will thus remain available to the public (and make it avoid your service) for a long time. Parameters and permissions are (often) open by default. Check them first.
    2. In version 5.2.2 not very many packages are available. On the other hand, in version 5.1.5 some 5.2.2-packages won't work (dotFOLIO). Several 5.1.5-packages will work onder 5.2.2, if first installed on 5.1.5 and subsequently upgraded to 5.2.2. My current (admittedly Project Open is not yet very well tested) list:

       Services  Applications
      ACS Reference Data 5.2.2
      API Browser 5.2.2
      Ajax Helper 0.3d
      Attachments 0.10
      Authentication 5.2.2
      Automated Testing 5.2.2
      Bootstrap Installer 5.2.2
      Categories 1.1
      Clickthrough 0.1d
      Clipboard 0.1d
      Content Repository 5.2.2
      Date and Time Utilities 5.2.2
      Documentation 5.2.2
      Dynamic Object Type 0.1
      Events 0.5
      Feed Parser 0.3d
      Kernel 5.2.2
      Localization 5.2.2
      Mail 5.2.2
      Mail Services Lite 1.0
      Messaging 5.2.2
      New Portal 2.1.2d2
      Profile Provider 2.1.1
      RSS Support 0.3
      Reference Data - Timezone 5.2.2
      Related Items 0.1d
      Service Contracts 5.2.2
      Site-Wide Administration 5.2.2
      Subsite 5.2.2
      Tcl Library 5.2.2
      Templating 5.2.2
      Trackback 0.1
      Tsearch2 Driver 0.4d2
      User Preferences 0.5d3
      Views 0.1d
      Workflow 2.1.1
      XML-RPC Server 0.3
      XOTcl Core 0.37
      edit-this-page Portlet 2.0.3
      webDAV Support 1.1b1
      Calendar 2.1.0b4
      Edit This Page 1.8
      FAQ 4.7.4
      File Storage 5.2.2
      Forums 1.2.0d3
      GateKeeper 4.0b
      General Comments 5.2.0
      News Aggregator 1.0.2
      Notifications 5.2.0
      Project/Open Core 3.0.0
      Project/Open Cost Core 3.0.0
      Project/Open Filestorage 3.0.0
      Project/Open Forum 3.0.0
      Project/Open Freelance 3.0.0
      Project/Open HR 3.0.0
      Project/Open Invoices 3.0.0
      Project/Open Payments 3.0.0
      Project/Open Timesheet Management 3.0.0
      Project/Open Translation 3.0.0
      Project/Open Translation Invoices 3.0.0
      Robot Detection 4.0.1
      Search 5.2.2
      User Profile 2.1.1
      Weblogger 2.2.0
      Workflow Service (Petri Nets) 4.5
      dotFOLIO 0.3
      dotFOLIO UI 0.3
      xowiki 0.26

       I have an operational site now and have forgotten to install the Simulation package in the 5.1.5 stage. Correcting this will be time consuming.   

    Administrators - Req.

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:12 AM

    Site and System Administrators - Documentation Requirements

    By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003.

    OpenACS administrators' documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here.

    • For each requirement below, include links to developer tutorials and other documentation for more detail.

    • Describe a structural overview of a working system and how the components work together. "The Layered Cake view" a general network view of system; a table showing system levels versus roles to help with understanding how the subsystems are interconnected.

    • Provide a comprehensive description of typical administrative processes for operating an OpenACS system responsibly, including reading logs and command line views that describe status of various active processes.

    • Create a list of administrative tools that are useful to administrating OpenACS, including developer support, schema-browser and api browser. Link to AOLserver's config file documentation.

    • Resources on high level subjects such as web services, security guidelines

    • Describe typical skill sets (and perhaps mapped to standardized job titles) for administrating an OpenACS system (human-resources style). For a subsite admin/moderator attributes might include trustworthy, sociable, familiarity with the applications and subsystems, work/group communication skills et cetera

    • Describe how to set up typical site moderation and administration including parameters, permissions, "Hello World" page

    • Show directory structure of a typical package, explanation of the various file types in a package (tcl,adp,xql) and how those relate to the previously described subsystems, when they get refreshed etc.

    • Ways to build a "Hello World" page

    • Show examples of how the OpenACS templating system is used, including portal sections of pages. For example, create a customised auto-refreshing startpage using lars-blogger, a photo gallery, and latest posts from a forum. This should rely heavily on documentation existing elsewhere to keep current. This would essentially be a heavily annotated list of links.

    • Show ways of modifying the look and feel across pages of an OpenACS website. Refer to the skins package tutorial.

    • Describe a methodology for diagnosing problems, finding error statements and interpreting them --for OpenACS and the underlying processes.

    • FAQs: Administration tasks commonly discussed on boards: admin page flow, how to change the looks of a subsite with a new master.adp, options on "user pages" , a quick introduction to the functions and processes. info about the user variables, file locations

    *nix operating system

    Created by OpenACS community, last modified by Robert Taylor 07 Aug 2006, at 03:12 AM

    *nix operating systems

    OpenACS works on most any operating system that behaves in a manner similar to UNIX. (see "Unix-like" by Wikipedia). For example: (links to features lists of OSes)

    Next Page