Index: openacs-4/packages/acs-core-docs/www/xml/openacs.xsl =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/openacs.xsl,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/xml/openacs.xsl 20 Aug 2003 16:20:18 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/xml/openacs.xsl 14 Oct 2003 10:03:22 -0000 1.11 @@ -35,7 +35,7 @@
- + Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml 20 Aug 2003 16:20:18 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml 14 Oct 2003 10:03:23 -0000 1.5 @@ -22,27 +22,23 @@ Daemontools must already be installed. If not, install it. - Each service controlled by daemontools must have a directory in /service. That directory must have a file called run. Daemontools then creates additional files and directories to track status and log. Create the appropriate directory as /web/service0/etc/daemontools, copy the prepared run file, and set permissions. If your server is not called service0, edit /web/service0/etc/run accordingly. - [service0@yourserver log]$ cd /web/service0/etc -[service0@yourserver etc]$ mkdir daemontools -[service0@yourserver etc]$ cp /web/service0/packages/acs-core-docs/www/files/run.txt daemontools/run -[service0@yourserver etc]$ chmod 700 daemontools/run -cd /web/service0/etc -mkdir daemontools -cp /web/service0/packages/acs-core-docs/www/files/run.txt daemontools/run -chmod 700 daemontools/run - - - 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. + Each service controlled by daemontools must have a + directory in /service. That + directory must have a file called + run. Daemontools then + creates additional files and directories to track status and + log. A daemontools directory is included in the OpenACS + tarball at + /var/lib/aolserver/service0/etc/daemontools. To use it, first ill 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. [service0@yourserver etc]$ killall nsd nsd: no process killed [service0@yourserver etc]$ exit -[root@yourserver root]# ln -s /web/service0/etc/daemontools/ /service/service0 +[root@yourserver root]# ln -s /var/lib/aolserver/service0/etc/daemontools/ /service/service0 Verify that AOLserver is running. [root@yourserver root]# ps -auxw | grep nsd -service0 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /web/service0/etc/config.tcl -u serve +service0 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/service0/etc/config.tcl -u serve root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd [root@yourserver root]# @@ -91,7 +87,7 @@ Install a script to automate the stopping and starting of aolserver services via daemontools. You can then restart a service via restart-aolserver service0 - [root@yourserver root]# cp /web/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver + [root@yourserver root]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver [root@yourserver root]# chmod 755 /usr/local/bin/restart-aolserver [root@yourserver root]# @@ -103,7 +99,7 @@ [root@yourserver root]# - Verify that the controls work. You may want to tail -f /web/service0/log/service0-error.log in another window, so you can see what happens when you type these commands. + Verify that the controls work. You may want to tail -f /var/lib/aolserver/service0/log/service0-error.log in another window, so you can see what happens when you type these commands. @@ -192,7 +188,7 @@ joeuser:~$ killall nsd nsd: no process killed -joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.tcl +joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/birdnotes/nsd.tcl joeuser:~$ restart-aolserver birdnotes Killing 23727 joeuser:~$ killall nsd @@ -223,7 +219,7 @@ nss1 is unique. -nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/web/birdnotes/nsd.tcl +nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl @@ -328,16 +324,16 @@ Prepare a certificate directory for the service. - [service0@yourserver etc]$ mkdir /web/service0/etc/certs -[service0@yourserver etc]$ chmod 700 /web/service0/etc/certs + [service0@yourserver etc]$ mkdir /var/lib/aolserver/service0/etc/certs +[service0@yourserver etc]$ chmod 700 /var/lib/aolserver/service0/etc/certs [service0@yourserver etc]$ -mkdir /web/service0/etc/certs -chmod 700 /web/service0/etc/certs +mkdir /var/lib/aolserver/service0/etc/certs +chmod 700 /var/lib/aolserver/service0/etc/certs It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages. Use an OpenSSL perl script to generate a certificate and key. - [service0@yourserver service0]$ cd /web/service0/etc/certs + [service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc/certs [service0@yourserver certs]$ perl /usr/share/ssl/misc/CA -newcert Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key @@ -380,26 +376,26 @@ [root@yourserver src]# su - service0 -[service0@yourserver service0]$ cd /web/service0 -[service0@yourserver service0]$ cp /web/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg +[service0@yourserver service0]$ cd /var/lib/aolserver/service0 +[service0@yourserver service0]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg [service0@yourserver service0]$ mkdir www/log [service0@yourserver service0]$ cp -r /usr/share/analog-5.31/images www/log/ [service0@yourserver service0]$ su - service0 -cd /web/service0 -cp /web/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg +cd /var/lib/aolserver/service0 +cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg mkdir www/log cp -r /usr/share/analog-5.31/images www/log/ Edit -/web/service0/etc/analog.cfg and change the variable in HOSTNAME "[my +/var/lib/aolserver/service0/etc/analog.cfg and change the variable in HOSTNAME "[my organisation]" to reflect your website title. If you don't want the traffic log to be publicly visible, change -OUTFILE /web/service0/www/log/traffic.html to use a private +OUTFILE /var/lib/aolserver/service0/www/log/traffic.html to use a private directory. Run it. - [service0@yourserver service0]$ /usr/share/analog-5.31/analog -G -g/web/service0/etc/analog.cfg + [service0@yourserver service0]$ /usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg /usr/share/analog-5.31/analog: analog version 5.31/Unix /usr/share/analog-5.31/analog: Warning F: Failed to open DNS input file /home/service0/dnscache: ignoring it @@ -418,7 +414,7 @@ Put this into the file: #!/bin/sh -/usr/share/analog-5.31/analog -G -g/web/service0/etc/analog.cfg +/usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg [root@yourserver root]# chmod 755 /etc/cron.daily/analog Test it by running the script. [root@yourserver root]# sh /etc/cron.daily/analog Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 20 Aug 2003 16:20:18 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 14 Oct 2003 10:03:23 -0000 1.11 @@ -17,16 +17,15 @@ The reference install stores all OpenACS services in - /web, with one subdirectory per - service. The first time you install a service, you must create + /var/lib/aolserver, with one subdirectory per service. The first time you install a service, you must create that directory and set its permissions: - [root@yourserver root]# mkdir /web -[root@yourserver root]# chgrp web /web -[root@yourserver root]# chmod 770 /web + [root@yourserver root]# mkdir /var/lib/aolserver +[root@yourserver root]# chgrp web /var/lib/aolserver +[root@yourserver root]# chmod 770 /var/lib/aolserver [root@yourserver root]# -mkdir /web -chgrp web /web -chmod 770 /web +mkdir /var/lib/aolserver +chgrp web /var/lib/aolserver +chmod 770 /var/lib/aolserver @@ -126,21 +125,21 @@ Unpack the OpenACS tarball and rename it to service0. Secure the directory so that only the owner can access it. Check the permissions by listing the directory. [root@yourserver root]# su - service0 -[service0@yourserver service0]$ cd /web -[service0@yourserver web]$ tar xzf /tmp/&tarballpath;.tgz -[service0@yourserver web]$ mv &tarballpath; service0 -[service0@yourserver web]$ chmod -R 700 service0 -[service0@yourserver web]$ ls -al +[service0@yourserver service0]$ cd /var/lib/aolserver +[service0@yourserver aolserver]$ tar xzf /tmp/&tarballpath;.tgz +[service0@yourserver aolserver]$ mv &tarballpath; service0 +[service0@yourserver aolserver]$ chmod -R 700 service0 +[service0@yourserver 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 service0 web 1024 Jan 6 14:36 service0 -[service0@yourserver web]$ exit +[service0@yourserver aolserver]$ exit logout [root@yourserver root]# su - service0 -cd /web +cd /var/lib/aolserver tar xzf /tmp/&tarballpath;.tgz mv &tarballpath; service0 chmod -R 700 service0/ @@ -155,13 +154,13 @@ these directories will be included in the tarball)Set up several additional directories in the service root: etc is for configuration and control files, log is for error and request (web page hit) log files, and database-backup is for database backup files. If you did the CVS step, note that these new directories are excluded from that step so that you can decide whether or not you want your logs and config files in source control. [root@yourserver root]# su - service0 -[service0@yourserver service0]$ mkdir /web/service0/etc /web/service0/log /web/service0/database-backup -[service0@yourserver web]$ exit +[service0@yourserver service0]$ mkdir /var/lib/aolserver/service0/etc /var/lib/aolserver/service0/log /var/lib/aolserver/service0/database-backup +[service0@yourserver aolserver]$ exit logout -[root@yourserver web]# +[root@yourserver aolserver]# su - service0 -mkdir /web/service0/etc /web/service0/log /web/service0/database-backup +mkdir /var/lib/aolserver/service0/etc /var/lib/aolserver/service0/log /var/lib/aolserver/service0/database-backup exit @@ -401,15 +400,15 @@ 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, - /web/service0/etc/config.tcl. + /var/lib/aolserver/service0/etc/config.tcl. Open it in an editor to adjust the parameters. AOLserver configuration [root@yourserver root]# su - service0 -[service0@yourserver service0]$ cd /web/service0/etc +[service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc [service0@yourserver etc]# emacs config.tcl @@ -499,7 +498,7 @@ nsd and selectively kill by job number. [service0@yourserver etc]$ killall nsd nsd: no process killed -[service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /web/service0/etc/config.tcl +[service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/service0/etc/config.tcl [service0@yourserver service0]$ [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. @@ -513,13 +512,13 @@ url="files/openacs-start.html">this. If you imported your files into cvs, now that you know it worked you can erase the temp - directory with rm -rf /web/service0.orig. + directory with rm -rf /var/lib/aolserver/service0.orig. If you don't see the login page, view your error log - (/web/service0/log/service0-error.log) + (/var/lib/aolserver/service0/log/service0-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 @@ -612,7 +611,7 @@ AOLServer to restart itself (ie. inittab or daemontools), you'll need to manually restart your service. - [service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /web/service0/config.tcl + [service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/service0/config.tcl Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 20 Aug 2003 16:20:18 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 14 Oct 2003 10:05:44 -0000 1.5 @@ -366,8 +366,23 @@ See also + + Install nspam + + +nspam is documented in acs-authentication. This html + version of acs-core-docs was compiled without + acs-authentication. To view nspam installation instructions, + install acs-authentication and read /docs/acs-authentication. + + + + + - + Install Full Text Search Install OpenFTS module @@ -466,7 +481,7 @@ - + Install OpenFTS prerequisites in PostGreSQL instance @@ -597,7 +612,6 @@ - Install nsopenssl This AOLserver module is required if you want people to connect to your site via Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml 11 Sep 2003 04:27:54 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/software.xml 14 Oct 2003 10:05:44 -0000 1.6 @@ -21,27 +21,27 @@ Bundled Software All of these materials are available bundled: - - - - Reference Platform &version;-P (<ulink>tarball</ulink>, <ulink>ISO image</ulink>) - Reference Platform A: OpenACS &version;, AOLserver - 3.3oacs1, PostGreSQL 7.2.4, and all supporting - files. Also requires Red Hat 8.0. - - - - - Reference Platform &version;-O (<ulink>tarball</ulink>, <ulink>ISO image</ulink>) - Reference Platform B: OpenACS &version;, AOLserver -3.3oacs1, Oracle 8.1.7, and all supporting - files. Also requires Red Hat 8.0. Also - requires Oracle - see for information on how to get Oracle. - - + + + + Reference Platform &version;-P (<ulink>tarball</ulink>, <ulink>ISO image</ulink>) + Reference Platform A: OpenACS &version;, AOLserver + 3.3oacs1, PostGreSQL 7.2.4, and all supporting + files. Also requires Red Hat 8.0. + + + + + Reference Platform &version;-O (<ulink>tarball</ulink>, <ulink>ISO image</ulink>) + Reference Platform B: OpenACS &version;, AOLserver + 3.3oacs1, Oracle 8.1.7, and all supporting + files. Also requires Red Hat 8.0. Also + requires Oracle - see for information on how to get Oracle. + + - ---> + + --> Compatibility Matrix @@ -234,7 +234,7 @@ tDOM, REQUIRED - OpenACS &version; stores + OpenACS &version; stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which was used prior to 4.6.4.) tDOM is available from - Web Server - The web server handles incoming HTTP requests, provides + Web Server + The web server handles incoming HTTP requests, provides a runtime environment for OpenACS's tcl code, connects to the database, sends out HTTP responses, and logs requests and errors. OpenACS uses AOLserver; some people have had success running Apache with mod_nsd - see this post. - - - + - - - <ulink + <itemizedlist> + + <listitem id="source-aolserver"> + <formalpara> + <title><ulink url="http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz">AOLserver 3.3oacs1</ulink>, REQUIRED - Mat Kovach's source distribution of AOLserver, including all of the patches listed below. - + Mat Kovach's source distribution of AOLserver, including all of the patches listed below. + - + Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS &version;. These instructions will describe how to install using his source @@ -299,7 +299,7 @@ - + The patch that makes exec work on BSD is available at sourceforge.net @@ -319,42 +319,78 @@ - - - - - - <ulink + </listitem> + <listitem id="nsopenssl-download"> + <formalpara> + <title><ulink url="http://www.scottg.net/download/nsopenssl-2.1.tar.gz">nsopenssl 2.1</ulink>, OPTIONAL - Provides SSL capabilities for AOLserver. It requires + Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make secure (https) connections to your webserver. - - - - - <ulink - url="http://unc.dl.sourceforge.net/sourceforge/openfts/Search-OpenFTS-tcl-0.3.2.tar.gz">OpenFTS TCL 0.3.2</ulink>, OPTIONAL - 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. - - - - - <ulink + </formalpara> + </listitem> + + <listitem id="nspam-download"> + <formalpara> + <title><ulink + url="http://braindamage.alal.com/software/ns_pam-0.1.tar.gz">ns_pam + 0.1</ulink>, OPTIONAL + Provides PAM capabilities for AOLserver. You + need this if you want OpenACS users to authenticate + through a PAM module (such as RADIUS). (home + page) + + + + + + + <ulink + url="ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar">pam_radius 1.3.16</ulink>, OPTIONAL + Provides RADIUS capabilities for PAM. You need + this if you want to use RADIUS authentication via PAM in OpenACS. + + + + + + <ulink + url="http://sourceforge.net/project/showfiles.php?group_id=3152">ns_ldap 0.r8 + </ulink>, OPTIONAL + Provides LDAP capabilities for AOLserver. You need + this if you want to use LDAP authentication in OpenACS. + + + + + + + + <ulink + url="http://unc.dl.sourceforge.net/sourceforge/openfts/Search-OpenFTS-tcl-0.3.2.tar.gz">OpenFTS TCL 0.3.2</ulink>, OPTIONAL + 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. + + + + + + + <ulink url="http://www.analog.cx/analog-5.31.tar.gz">Analog 5.31</ulink>, OPTIONAL - This program examines web server request logs, looks up + This program 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. - - - - + + + + - - Database - The data on your site (for example, user names and passwords, + + Database + The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS seperates the database with an abstraction layer, which means that several different databases all function @@ -378,48 +414,48 @@ <ulink url="http://www.ca.postgresql.org/ftpsite/source/v7.2.4/postgresql-7.2.4.tar.gz">PostGreSQL 7.2.4</ulink> (Either this or Oracle is REQUIRED) - You need this if you want to use a PostGreSQL database. + You need this if you want to use a PostGreSQL database. PostGreSQL 7.3 is not backwards-compatible, and OpenACS support for 7.3 has not been fully tested. If you are not in the United States, select a closer mirror - + Process Controller - This is software that initiates other software, and + This is software that initiates other software, and restarts that software if it fails. On Linux, we recommend using Daemontools to control AOLserver and qmail. - - - - - <ulink + </formalpara> + <itemizedlist> + <listitem id="daemontools-download"> + <formalpara> + <title><ulink url="http://cr.yp.to/daemontools/daemontools-0.76.tar.gz">Daemontools 0.76</ulink>, OPTIONAL - You need this if you want AOLserver and qmail to run + You need this if you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. - - + + - - - Mail Transport Agent - A Mail Transport Agent is a program that handles all + + + Mail Transport Agent + A Mail Transport Agent is 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. - - - - - <ulink + </formalpara> + <itemizedlist> + <listitem> + <formalpara id="qmail-download"> + <title><ulink url="http://cr.yp.to/software/qmail-1.03.tar.gz">Qmail 1.03</ulink>, OPTIONAL - You need this (or a different Mail Transport + You need this (or a different Mail Transport Agent) if you want your webserver to send and receive email.
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml,v diff -u -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml 20 Aug 2003 16:20:18 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml 14 Oct 2003 10:03:22 -0000 1.4 @@ -16,36 +16,42 @@ Debugging + Developer Support + The Developer Support package adds several goodies: debug + information for every page; the ability to log comments to the + page instead of the error log, and fast user switching so that you + can test pages as anonymous and as dummy users without logging + in and out. + + PostgreSQL You can work directly with the database to do debugging steps like looking directly at tables and testing stored - procedures. Start emacs. Type + procedures. Start emacs. Type M-x sql-postgres. Press enter for server name and use openacs-dev for database name. You can use C-(up arrow) and C-(down arrow) - for command history. + for command history. + - - Hint: "Parse error near *" usually means that an xql file + 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. Watching the server log - -NOTE: explain how to add tcl to directly write your own log output - To set up real-time monitoring of the Aolserver error - log, type less /usr/local/aolserver/log/openacs-dev-error.log + NOTE: explain how to add tcl to directly write your own + log output + + To set up real-time monitoring of the Aolserver error + log, type less /usr/local/aolserver/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. - - - Manual testing Make a list of basic tests to make sure it works @@ -72,16 +78,133 @@ Other things to test: try to delete someone else's note. Try to delete your own note. Edit your own note. Search for a note. - + + + + + by Simon Carstensen + + Write automated tests + + Create the automated tests for the package. + It seems to me that a lot of +people have been asking for some guidelines on how to write automated +tests. I've done several tests by now and have found the process to be +extremely easy and useful. It's a joy to work with automated testing +once you get the hang of it. + + I just wrote a test script for the acs-service-contract package and +thought I'd might as well post a step-by-step run-through, since some +people have been asking for this. Here goes. + + + + Create the directory that will contain the test + script(s): + +$ cd /web/simon/packages/acs-service-contract/tcl +$ mkdir test + + + + Create the .tcl library that holds the test + procs: + +$ cd test +$ emacs acs-service-contract-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. +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: - - Write automated tests - - Create the automated tests for the package. - (Forthcoming.) - +aa_register_case acs_sc_impl_new_from_spec { + aa_run_with_teardown \ + -rollback \ + -testcode { + ... logic ... + } +} + +Now let's look at the actual test code. That's the code that +goes inside -testcode {}. +In my case I had added a new column to acs_sc_impls (pretty_name), +which meant that I had to change the datamodel and the Tcl API to +support this new change. To make sure I didn't screw up, I wrote a test +that created a new service contract, then a new implementation of that +contract, and called acs_sc::impl::get to check that the data in the +new column had been added correctly and then finally verified that the +pretty_name was actually what I had tried to insert. It looked +something like this: +set spec { + name "foo_contract" + description "Blah blah" + ... +} +# Create service contract +acs_sc::contract::new_from_spec -spec $spec +set spec { + name "foo_impl" + description "Blah blah blah" + pretty_name "Foo Implementation" + ... +} + +# Create implementation +set impl_id [acs_sc::impl::new_from_spec -spec $spec] + +# Get the values of the implementation we just created +acs_sc::impl::get -impl_id $impl_id -array impl + +#Verify that the pretty_name column has the correct value +aa_equals "did column pretty_name get set correctly?" $impl(pretty_name) "Foo Implementation" + +Now you might not know how acs-service-contract works, but that +doesn't matter. I'm basically inserting data into the database, then +querying for the database to check that it got inserted and then +finally, using aa_equals, I compare the result with what I inserted to +verify that everything is correct. + +There are number of other useful procs for determening whether a test case was successful or not, namely: + + aa_true "is this true?" [expr ![empty_string $foo]] +aa_false "is this true?" [empty_string $foo] + + There a number of other useful procs and I will encourage you to +look at the few packages for which tests have already been implemented. +That is perhaps the best documentation we have so far. + + + + + Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 20 Aug 2003 16:20:18 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 14 Oct 2003 10:05:44 -0000 1.13 @@ -185,7 +185,9 @@ Install Full Text Search with OpenFTS (OPTIONAL) - + + Install nspam (OPTIONAL) + Test AOLserver Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/Attic/compatibility.xml,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml 20 Aug 2003 16:20:18 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/compatibility.xml 14 Oct 2003 10:03:23 -0000 1.6 @@ -71,7 +71,8 @@ 7.3.2 Incompatible - Untested + Mostly compatible (news is broken)