| Prev | Next |
Table of Contents
Table of Contents
Tutorials and reference material for creating new OpenACS packages. -
Table of Contents
Tutorials and reference material for creating new OpenACS packages. +
Table of Contents
Table of Contents
Table of Contents
Download the Analog source tarball in
-/tmp. Unpack, compile, and install analog.
[root aolserver]#cd /usr/local/src-[root src]#tar xzf /tmp/analog-5.32.tar.gz-[root src]#cd analog-5.32-[root analog-5.32]#make+ +Install Analog web file analyzer Download the Analog source tarball in +/tmp. Unpack, compile, and install analog.
[root aolserver]# cd /usr/local/src +[root src]# tar xzf /tmp/analog-5.32.tar.gz +[root src]# cd analog-5.32 +[root analog-5.32]# make cd src && make make[1]: Entering directory `/usr/local/src/analog-5.32/src' (many lines omitted) ***IMPORTANT: You must read the licence before using analog *** make[1]: Leaving directory `/usr/local/src/analog-5.32/src' -[root analog-5.32]#cd ..-[root src]#mv analog-5.32 /usr/share/+[root analog-5.32]# cd .. +[root src]# mv analog-5.32 /usr/share/ [root src]# cd /usr/local/src tar xzf /tmp/analog-5.32.tar.gz cd analog-5.32 make cd .. -mv analog-5.32 /usr/share/View comments on this page at openacs.org +mv analog-5.32 /usr/share/
Analog is a program with processes webserver access logs, + +
Analog is a program with processes webserver access logs, performs DNS lookup, and outputs HTML reports. Analog should - already be + already be installed. A modified configuration file is included in - the OpenACS tarball.
[root src]#su - $OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd /var/lib/aolserver/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$mkdir www/log-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cp -r /usr/share/analog-5.32/images www/log/+ the OpenACS tarball.
[root src]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ mkdir www/log +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cp -r /usr/share/analog-5.32/images www/log/ [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver/$OPENACS_SERVICE_NAME cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg mkdir www/log cp -r /usr/share/analog-5.32/images www/log/Edit -
/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfgand change the variable inHOSTNAME "[my -organisation]"to reflect your website title. If you +/var/lib/aolserver/$OPENACS_SERVICE_NAME/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 /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.htmlto use a private -directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.Run it.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg+OUTFILE /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.html to use a private +directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.Run it.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg /usr/share/analog-5.32/analog: analog version 5.32/Unix /usr/share/analog-5.32/analog: Warning F: Failed to open DNS input file /home/$OPENACS_SERVICE_NAME/dnscache: ignoring it (For help on all errors and warnings, see docs/errors.html) /usr/share/analog-5.32/analog: Warning R: Turning off empty Search Word Report -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Verify that it works by browing to
http://yourserver.test:8000/log/traffic.htmlAutomate this by creating a file in -
/etc/cron.daily.[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$exit+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Verify that it works by browing to http://yourserver.test:8000/log/traffic.html
Automate this by creating a file in + /etc/cron.daily.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit logout -[root root]#emacs /etc/cron.daily/analogPut this into the file:
#!/bin/sh +[root root]# emacs /etc/cron.daily/analogPut this into the file:
#!/bin/sh -/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg[root root]#chmod 755 /etc/cron.daily/analogTest it by running the script.
[root root]#sh /etc/cron.daily/analogBrowse to
http://yourserver.test/log/traffic.html
[root root]# chmod 755 /etc/cron.daily/analog
Test it by running the script.
[root root]# sh /etc/cron.daily/analog
Browse to http://yourserver.test/log/traffic.html
by Vinod Kurup
+ +We recommend the use of AOLserver 4.0.1 or later. These instructions are retained as a resource.
+
We recommend the use of AOLserver 4.0.1 or later. These instructions are retained as a resource.
Debian users: we do not recommend installing Debian packages for Aolserver or Postgres. Several people have reported problems while trying to install using apt-get instead of from source. If you have the time to debug these and submit what you did, that's great, but if not, you should stick to installing from source. -
Unpack the Aolserver tarball. Download the aolserver tarball and unpack it.
[root root]#cd /usr/local/src-[root src]#wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz+
Unpack the Aolserver tarball. Download the aolserver tarball and unpack it.
[root root]# cd /usr/local/src +[root src]# wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz --15:38:08-- http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz => `aolserver3.3oacs1.tar.gz' Resolving uptime.openacs.org... done. @@ -21,41 +21,41 @@ 100%[====================================>] 3,858,074 66.56K/s ETA 00:00 15:39:05 (66.56 KB/s) - `aolserver3.3oacs1.tar.gz' saved [3858074/3858074] -[root src]#tar xzf aolserver3.3oacs1.tar.gz+[root src]# tar xzf aolserver3.3oacs1.tar.gz [root src]# cd /usr/local/src wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz -tar xzf aolserver3.3oacs1.tar.gzThis section also relies on some OpenACS files, which you can get with the section called “Unpack the OpenACS tarball”.
Compile AOLserver. Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.
root@yourserver root]#mkdir -p /usr/local/aolserver-[root root]#cd /usr/local/src/aolserver-[root aolserver]#./conf-clean+tar xzf aolserver3.3oacs1.tar.gzThis section also relies on some OpenACS files, which you can get with Section , “Unpack the OpenACS tarball”.
Compile AOLserver. Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.
root@yourserver root]# mkdir -p /usr/local/aolserver +[root root]# cd /usr/local/src/aolserver +[root aolserver]# ./conf-clean cat: BUILD-MODULES: No such file or directory Done. [root aolserver]#mkdir -p /usr/local/aolserver cd /usr/local/src/aolserver ./conf-cleanIf you are using Oracle, edit -
conf-dband change -postgresqlto -oracle, or to the word -bothif you want both drivers + conf-db and change + postgresql to + oracle, or to the word + both if you want both drivers installed. In order to get nsoracle to compile, you may need to su - oracle, and then su (without the -) root to set the environment variables properly. -
conf-instshould contain the +conf-inst should contain the location where AOLserver is to be installed. Overwrite the - tarball's default value with our default value,
/usr/local/aolserver:[root aolserver]#echo "/usr/local/aolserver" > conf-inst-[root aolserver]#
conf-makeshould contain the + tarball's default value with our default value, /usr/local/aolserver:[root aolserver]# echo "/usr/local/aolserver" > conf-inst +[root aolserver]#conf-make should contain the name of the GNU Make command on your system. It defaults to -
gmake. Debian users:.ln -s /usr/bin/make /usr/bin/gmakeSet an environment variable that the nspostgres driver + gmake. Debian users: ln -s /usr/bin/make /usr/bin/gmake.
Set an environment variable that the nspostgres driver Makefile needs to compile correctly and run -
conf, which compiles + conf, which compiles AOLserver, the default modules, and the database driver, and installs them.Debian users, see warning above, but if you do use apt-get for AOLserver 3.3+ad13 and postgresql from apt-get may need to - make these symlinks:
ln -s - /usr/include/postgresql/ /usr/include/pgsql- andln -s /usr/lib/postgresql /usr/local/pgsql)[root aolserver]#export POSTGRES=/usr/local/pgsql; ./conf+ make these symlinks: ln -s + /usr/include/postgresql/ /usr/include/pgsql + and ln -s /usr/lib/postgresql /usr/local/pgsql)[root aolserver]# export POSTGRES=/usr/local/pgsql; ./conf Building in /usr/local/aolserver with the following modules: aolserver @@ -77,27 +77,27 @@ ================================================================== Done Building Sat Mar 8 10:31:35 PST 2003 [root aolserver]#- This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in
/usr/local/src/aolserver/log. If you run into problems running AOLserver, check these files for build errors.Add a database-specific wrapper script. This script + This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in /usr/local/src/aolserver/log. If you run into problems running AOLserver, check these files for build errors.
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.
Oracle
[root aolserver]#cd /usr/local/aolserver/bin-[root bin]#cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle-[root bin]#chmod 750 nsd-oracle+ to use both databases, install both.
Oracle
[root aolserver]# cd /usr/local/aolserver/bin +[root bin]# cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle +[root bin]# chmod 750 nsd-oracle [root bin]# cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle -chmod 750 nsd-oraclePostgreSQL
[root aolserver]#cd /usr/local/aolserver/bin-[root bin]#cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres-[root bin]#chmod 755 nsd-postgres+chmod 750 nsd-oraclePostgreSQL
[root aolserver]# cd /usr/local/aolserver/bin +[root bin]# cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres +[root bin]# chmod 755 nsd-postgres [root bin]# cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres -chmod 755 nsd-postgresInstall tDOM. Download the tDOM +chmod 755 nsd-postgres
Install tDOM. Download the tDOM tarball, unpack it, adjust the configuration file to match our patched - distribution of aolserver, and compile it.
[root root]#cd /usr/local/src-[root src]#wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz+ distribution of aolserver, and compile it.[root root]# cd /usr/local/src +[root src]# wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz --16:40:58-- http://www.tdom.org/tDOM-0.7.8.tar.gz => `tDOM-0.7.8.tar.gz' Resolving www.tdom.org... done. @@ -109,54 +109,54 @@ 16:41:04 (138.06 KB/s) - `tDOM-0.7.8.tar.gz' saved [826613/826613] -[root src]#tar xzf tDOM-0.7.8.tar.gz-[root src]#cd tDOM-0.7.8/unix+[root src]# tar xzf tDOM-0.7.8.tar.gz +[root src]# cd tDOM-0.7.8/unix [root unix]# cd /usr/local/src wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz tar xzf tDOM-0.7.8.tar.gz cd tDOM-0.7.8/unixEdit the file CONFIG and change this section:
# ---------------------------------------------------- -# aolsrc="/usr/src/aolserver-3.4" +# aolsrc="/usr/src/aolserver-3.4" # ../configure --enable-threads --disable-tdomalloc \ # --with-aolserver=$aolsrc \ # --with-tcl=$aolsrc/tcl8.3.4/unixto
# ---------------------------------------------------- -aolsrc="/usr/local/src/aolserver/aolserver" +aolsrc="/usr/local/src/aolserver/aolserver" ../configure --enable-threads --disable-tdomalloc \ --with-aolserver=$aolsrc \ - --with-tcl=$aolsrc/tcl8.3.2/unixAnd configure and compile:
[root unix]#sh CONFIG+ --with-tcl=$aolsrc/tcl8.3.2/unixAnd configure and compile:
[root unix]# sh CONFIG creating cache ./config.cache checking for memmove... yes (many lines omitted) creating Makefile creating tdomConfig.sh -[root unix]#make+[root unix]# make gcc -pipe -DHAVE_UNISTD_H=1 -DHAVE_LIMITS_H=1 -DTCL_THREADS=1 -DHAVE_GETCWD=1 -DHAVE_OPENDIR=1 -DHAVE_STRSTR=1 -DHAVE_STRTOL=1 (many lines omitted) -Wl,-rpath,/usr/local/lib -o tcldomsh;\ fi -[root unix]#cp libtdom0.7.8.so /usr/local/aolserver/bin/-[root unix]#cd /usr/local/aolserver/bin/-[root bin]#ln -s libtdom0.7.8.so libtdom.so+[root unix]# cp libtdom0.7.8.so /usr/local/aolserver/bin/ +[root unix]# cd /usr/local/aolserver/bin/ +[root bin]# ln -s libtdom0.7.8.so libtdom.so [root bin]# sh CONFIG make cp libtdom0.7.8.so /usr/local/aolserver/bin/ cd /usr/local/aolserver/bin -ln -s libtdom0.7.8.so libtdom.soInstall nsopenssl - (OPTIONAL)
Install Full Text Search with OpenFTS (OPTIONAL)
Install nspam (OPTIONAL)
Test AOLserver. In order to test AOLserver, we'll run it using the +ln -s libtdom0.7.8.so libtdom.so
Install nsopenssl + (OPTIONAL)
Install Full Text Search with OpenFTS (OPTIONAL)
Install nspam (OPTIONAL)
Test AOLserver. In order to test AOLserver, we'll run it using the sample-config.tcl file provided in the AOLserver distribution, - under the nobody user and
web+ under 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 theweb+ or it will fail. Grant the web group permission to write to -/usr/local/aolserver/logand -/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+ /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 @@ -171,12 +171,12 @@ chown -R root.web log servers chmod -R g+w log servers ls -lNote: AOLserver4.x does not include a default start page, so we create one for this test. Type -
echo "Welcome to AOLserver" > /usr/local/aolserver40r8/servers/server1/pages/index.html+ echo "Welcome to AOLserver" > /usr/local/aolserver40r8/servers/server1/pages/index.htmlNow, we'll run a quick test to ensure AOLserver is running correctly. We'll use the sample config file provided with AOLserver. This file will attempt to guess your 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+ 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 @@ -185,32 +185,32 @@ config file.The first warning, about nsssl, can be ignored. We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet. The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load. We don't plan to use it and can ignore that error as well. Any other warning or error is unexpected and probably a problem.
Test to see if AOLserver is working by starting -
Mozillaor -Lynxon the same + 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'll get a false negative test. -[root aolserver]#lynx localhost:8000+
[root aolserver]# lynx localhost:8000- You should see a "Welcome to AOLserver" page. If this + You should see a "Welcome to AOLserver" page. If this doesn't work, try going to -
http://127.0.0.1:8000/. If this - still doesn't work, check out the Troubleshooting AOLserver section below. 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. + http://127.0.0.1:8000/. If this + still doesn't work, check out the Troubleshooting AOLserver section below. 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+Shutdown the test server:
[root aolserver]# killall nsd [root aolserver]#- The
killallcommand will kill - all processes with the namensd, + 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 the Keep AOLserver alive section. + services in general. We cover this topic in the Keep AOLserver alive section. -Troubleshooting. If you can't view the welcome page, it's likely there's a +
Troubleshooting. If you can't view the welcome page, it's likely there's a problem with your server configuration. Start by viewing your AOLserver log, which is in -
/usr/local/aolserver/log/server.log. + /usr/local/aolserver/log/server.log. You should also try to find lines of the form:[01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) @@ -219,12 +219,12 @@ If you can find these lines, try entering the URL the server is listening on. If you cannot find these lines, there must be an error somewhere in the file. Search for lines beginning with the word -Errorinstead of -Notice. + Error instead of + Notice.- The
sample-config.tclfile grabs + The sample-config.tcl file grabs your address and hostname from your OS settings.@@ -234,11 +234,11 @@ If you get an error that nssock can't get the requested address, you can set these manually. If you type 0.0.0.0, AOLserver will try to listen on all available addresses. Note: -ns_info addressdoesn't appear + 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 0.0.0.0Install Analog web file analyzer. (OPTIONAL)
($Id$)
Check suitability of previously installed TCL. Start tcl (type tclsh or find it using which tclsh).
-
[root root]% info exists tcl_platform(threaded)
+ Check suitability of previously installed TCL. Start tcl (type tclsh or find it using which tclsh). +
[root root]% info exists tcl_platform(threaded)
1
-[root root]% info patchlevel
+[root root]% info patchlevel
8.4.7
[root root]%
tclsh
info exists tcl_platform(threaded)
info patchlevel
-If the first command returns anything other than 1,
+
If the first command returns anything other than 1, then tcl is not threaded. If tcl is threaded and the version is 8.4 or higher, then installing tcl from source is optional. -
Retrieve TCL 8.4 (or higher). Download and install TCL 8.4 from source
Note for Debian users: you can apt-get install +
Retrieve TCL 8.4 (or higher). Download and install TCL 8.4 from source
Note for Debian users: 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 on the - Install Postgres page). You'll + Install Postgres page). You'll have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you - try to find the tcl libraries, however.
If you have not installed TCL already, download the latest TCL version from Sourceforge
Debian:
- apt-get install
- tcl8.4 tcl8.4-dev and proceed to
+ try to find the tcl libraries, however.
If you have not installed TCL already, download the latest TCL version from Sourceforge
Debian:
+ apt-get install
+ tcl8.4 tcl8.4-dev and proceed to
the next step. In that step, replace
- --with-tcl=/usr/local/lib/ with
- --with-tcl=/usr/lib/tcl8.4.
Remember that you have to be root if you want to follow these instructions. On Mac OS X type sudo su - to become root.
Alternatively use curl -L -O instead of wget (especially on Mac OS X).
[root root]#cd /usr/local/src-[root src]#wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz-[root src]#tar xfz tcl8.4.9-src.tar.gz-[root src]#cd tcl8.4.9/unix-[root unix]#./configure --enable-threads-[root unix]#make install+ --with-tcl=/usr/local/lib/ with + --with-tcl=/usr/lib/tcl8.4.Remember that you have to be root if you want to follow these instructions. On Mac OS X type sudo su - to become root.
Alternatively use curl -L -O instead of wget (especially on Mac OS X).
[root root]# cd /usr/local/src +[root src]# wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz +[root src]# tar xfz tcl8.4.9-src.tar.gz +[root src]# cd tcl8.4.9/unix +[root unix]# ./configure --enable-threads +[root unix]# make install [root root]# cd /usr/local/src wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz tar xfz tcl8.4.9-src.tar.gz cd tcl8.4.9/unix ./configure --enable-threads make install -
Retrieve AOLserver. Download the aolserver from CVS.
[root root]#cd /usr/local/src-[root src]#mkdir aolserver40r10-[root src]#cd aolserver40r10-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r aolserver_v40_r10 aolserver-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nscache-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nspostgres-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nssha1-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle-[root aolserver]#wget http://www.tdom.org/tDOM-0.7.8.tar.gz-[root aolserver]#tar xvfz tDOM-0.7.8.tar.gz-[root aolserver]#cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib+
Retrieve AOLserver. Download the aolserver from CVS.
[root root]# cd /usr/local/src
+[root src]# mkdir aolserver40r10
+[root src]# cd aolserver40r10
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r aolserver_v40_r10 aolserver
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nscache
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nspostgres
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nssha1
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle
+[root aolserver]# wget http://www.tdom.org/tDOM-0.7.8.tar.gz
+[root aolserver]# tar xvfz tDOM-0.7.8.tar.gz
+[root aolserver]# cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib
[root root]#
cd /usr/local/src
mkdir aolserver40r10
@@ -60,32 +60,32 @@
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle
wget http://www.tdom.org/files/tDOM-0.8.0.tar.gz
tar xvfz tDOM-0.8.0.tar.gz
-cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllibConfigure, 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/aolserver40r9.
[root aolserver]#cd /usr/local/src/aolserver40r10/aolserver-[root aolserver]#./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/-[root aolserver]#make install+cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib
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/aolserver40r9.
[root aolserver]# cd /usr/local/src/aolserver40r10/aolserver
+[root aolserver]# ./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/
+[root aolserver]# make install
cd /usr/local/src/aolserver40r10/aolserver
./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/
make install
-If you are using gcc 4 or later, see http://openacs.org/forums/message-view?message_id=309814
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 the steps below and check both scripts and makefiles to ensure they use the correct path.
[root aolserver]# ln -s /usr/local/aolserver40r10 /usr/local/aolserverConfigure, compile and install the modules. -
[root aolserver]#cd /usr/local/src/aolserver40r10/nscache-[root nscache]#make install AOLSERVER=/usr/local/aolserver
Install nsoracle (if you want to use Oracle)
[root nscache]#cd ../nsoracle-[root nsoracle]#make install AOLSERVER=/usr/local/aolserver
OpenACS looks for the Oracle driver at +
If you are using gcc 4 or later, see http://openacs.org/forums/message-view?message_id=309814
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 the steps below and check both scripts and makefiles to ensure they use the correct path.
[root aolserver]# ln -s /usr/local/aolserver40r10 /usr/local/aolserver
Configure, compile and install the modules. +
[root aolserver]# cd /usr/local/src/aolserver40r10/nscache +[root nscache]# make install AOLSERVER=/usr/local/aolserver
Install nsoracle (if you want to use Oracle)
[root nscache]# cd ../nsoracle +[root nsoracle]# make install AOLSERVER=/usr/local/aolserver
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.
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:/usr/local/aolserver/lib-[root nspostgres]#make install POSTGRES=LSB ACS=1 INST=/usr/local/aolserver AOLSERVER=/usr/local/aolserver+ can symlink (ln -s nsoracle.so ora8.so) to fix it.
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:/usr/local/aolserver/lib
+[root nspostgres]# make install POSTGRES=LSB ACS=1 INST=/usr/local/aolserver AOLSERVER=/usr/local/aolserver
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. 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.
You can use the
- ldd command to verify
+nspostgres.c:679: warning: passing arg 3 of `Tcl_DStringAppend' as signed due to prototype
then PostGreSQL is probably not in the standard location. 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.
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.aIf you run into problems with the linker, edit the Makefile. Add -lnsdb to the MODLIBS var.
MODLIBS = -L$(PGLIB) -lpq -lnsdb[root nspostgres]# cd ../nssha1Now install nssha1:
[root nssha1]# make install AOLSERVER=/usr/local/aolserverIf 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;
[root nssha1]# cd ../tDOM-0.8.0/unixEdit 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/aolserver --with-tcl=/usr/local/lib
Note that the location of the Tcl library may vary on differnt platforms (e.g. for Debian 3.0: --with-tcl=/usr/lib/tcl8.4)
Now you can compile and configure tDOM
[root unix]#sh CONFIG-[root unix]#make install
[root nssha1]# cd ../tcllibConfigure and compile TCLLIB
[root unix]#./configure -prefix=/usr/local/aolserver40r10-[root unix]#make install
-
Add a database-specific wrapper script. This script + 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[root nspostgres]# cd ../nssha1
Now install nssha1:
[root nssha1]# make install AOLSERVER=/usr/local/aolserver
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;
[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/aolserver --with-tcl=/usr/local/lib
Note that the location of the Tcl library may vary on differnt platforms (e.g. for Debian 3.0: --with-tcl=/usr/lib/tcl8.4)
Now you can compile and configure tDOM
[root unix]# sh CONFIG +[root unix]# make install
[root nssha1]# cd ../tcllib
Configure and compile TCLLIB
[root unix]# ./configure -prefix=/usr/local/aolserver40r10 +[root unix]# make install
+
Add a database-specific wrapper script. This script sets database environment variables before starting AOLserver; this allows the AOLserver instance to communicate with the database. There is one script for @@ -99,17 +99,17 @@ 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/aolserver/bin-[root bin]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle-[root bin]#chmod 750 nsd-oracle+
Oracle
[root aolserver]# cd /usr/local/aolserver/bin +[root bin]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle +[root bin]# chmod 750 nsd-oracle [root bin]# cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle -chmod 750 nsd-oraclePostgreSQL
[root aolserver]#cd /usr/local/aolserver/bin-[root bin]#cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres-[root bin]#chmod 755 nsd-postgres+chmod 750 nsd-oraclePostgreSQL
[root aolserver]# cd /usr/local/aolserver/bin +[root bin]# cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres +[root bin]# chmod 755 nsd-postgres [root bin]# cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.5.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres chmod 755 nsd-postgresYou may need to edit these scripts if you are not using - /usr/local/aolserver as the directory of Aolserver4.
Change startup script (optional). If you want to run AOLserver on a port below 1024 (normally, for a webserver you will use 80), you will have to change the /var/lib/aolserver/service0/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch)
Change startup script (optional). If you want to run AOLserver on a port below 1024 (normally, for a webserver you will use 80), you will have to change the /var/lib/aolserver/service0/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch)
By Bryan Quinn
+ +Tcl API
-apm-install-procs.tcl (Supports installation of packages)
-20-apm-load-procs.tcl (Bootstraps APM for server startup)
-apm-admin-procs.tcl (Supports APM UI)
PL/SQL file
Tcl API
+apm-install-procs.tcl (Supports installation of packages)
+20-apm-load-procs.tcl (Bootstraps APM for server startup)
+apm-admin-procs.tcl (Supports APM UI)
PL/SQL file
+In general terms, a package is a unit of software that serves a single well-defined purpose. That purpose may be to provide a service directly to one or more classes of end-user, (e.g., discussion forums and file storage for community members, user profiling tools for the site publisher), or it may be to act as a building block for other packages (e.g., an application programming interface (API) for storing and querying access control rules, or an API for scheduling email alerts). Thus, packages fall into one of two categories: -
OpenACS Applications: a "program or group of programs -designed for end users" (the Webopedia +
OpenACS Applications: a "program or group of programs +designed for end users" (the Webopedia definition); also known as modules, for historical reasons. -Examples of applications include Forums and News. +Examples of applications include Forums and News. -
OpenACS Services: the aforementioned building blocks. -Examples of services include the OpenACS -Content Repository, the OpenACS Templating -System, and the OpenACS Kernel, which includes +
OpenACS Services: the aforementioned building blocks. +Examples of services include the OpenACS +Content Repository, the OpenACS Templating +System, and the OpenACS Kernel, which includes APM.
An installation of the OpenACS includes the OpenACS Kernel, some services that extend the kernel's functionality, and some applications intended for -end-users. Packages function as individual pieces of subsites. A subsite can contain multiple +end-users. Packages function as individual pieces of subsites. A subsite can contain multiple application and service instances that provide the end-user with capabilities and content customized to the particular subsite.
This architecture supports the growth of collaborative commerce. For example, Jane User starts a forum focusing on the merits of View Cameras by @@ -36,48 +36,48 @@ it in his subsite. As interest in Jane's forum grows, she creates a subsite specializing in providing information about View cameras. This subsite now includes several package instances beyond Forum; it could -potentially include its own Ecommerce capabilities (ala Yahoo! Shopping). This could include a +potentially include its own Ecommerce capabilities (ala Yahoo! Shopping). This could include a knowledge management application that allows users to spread expertise about view cameras and a portal application that links to reliable camera models and resellers. Any subsite enabled package that is added to the OpenACS installation through APM is another potential package instance that can become part of Jane's View Camera subsite.
The APM provides an architecture for packaging software, making instances of that software available to subsites, specifying configuration parameters -for each instance, and managing the creation and release of new packages.
+for each instance, and managing the creation and release of new packages.
Prior to ACS 3.3, all packages were lumped together into one monolithic distribution without explicit boundaries; the only way to ascertain what comprised a given package was to look at the top of the corresponding documentation page, where, by convention, the package developer would specify where to find: -
the data model
the Tcl procedures
the user-accessible pages
the administration pages
Experience has shown us that this lack of explicit boundaries causes a -number of maintainability problems for pre-3.3 installations:
Package interfaces were not guaranteed to be stable in any formal way, so +
the data model
the Tcl procedures
the user-accessible pages
the administration pages
Experience has shown us that this lack of explicit boundaries causes a +number of maintainability problems for pre-3.3 installations:
Package interfaces were not guaranteed to be stable in any formal way, so a change in the interface of one package would often break dependent packages (which we would only discover through manual regression testing). In this context, any of the following could constitute an interface change: -
renaming a file or directory that appears in a URL
changing what form variables are expected as input by a page
changing a procedural abstraction, e.g., a PL/SQL or Java stored -procedure or a Tcl procedure
changing a functional abstraction, e.g., a database view or a PL/SQL or -Java stored function
changing the data model
This last point is especially important. In most cases, changing the data +
renaming a file or directory that appears in a URL
changing what form variables are expected as input by a page
changing a procedural abstraction, e.g., a PL/SQL or Java stored +procedure or a Tcl procedure
changing a functional abstraction, e.g., a database view or a PL/SQL or +Java stored function
changing the data model
This last point is especially important. In most cases, changing the data model should not affect dependent packages. Rather, the package interface should provide a level of abstraction above the data model (as well as the rest of the package implementation). Then, users of the package can take advantage of implementation improvements that don't affect the interface (e.g., faster performance from intelligent denormalization of the data model), without having to worry that code outside the package will now -break.
A typical ACS-backed site only uses a few of the modules included in the +break.
A typical ACS-backed site only uses a few of the modules included in the distribution, yet there was no well-understood way to pick only what you needed when installing the ACS, or even to uninstall what you didn't need, post-installation. Unwanted code had to be removed manually. -
Releasing a new version of the ACS was complicated, owing again to the +
Releasing a new version of the ACS was complicated, owing again to the monolithic nature of the software. Since we released everything in the ACS together, all threads of ACS development had to converge on a single deadline, after which we would undertake a focused QA effort whose scale increased in direct proportion to the expansion of the ACS codebase. -
There was no standard way for developers outside of ArsDigita to extend +
There was no standard way for developers outside of ArsDigita to extend the ACS with their own packages. Along the same lines, ArsDigita programmers working on client projects had no standard way to keep custom development cleanly separated from ACS code. Consequently, upgrading an already installed @@ -88,43 +88,43 @@ packages for other OpenACS users to download and install.
For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):
APM itself is part of a package, the OpenACS Kernel, an OpenACS -service that is the only mandatory component of an OpenACS installation.
The OpenACS is a platform for web-based application software, and any software +3.2 (say, bboard and e-commerce):
APM itself is part of a package, the OpenACS Kernel, an OpenACS +service that is the only mandatory component of an OpenACS installation.
The OpenACS is a platform for web-based application software, and any software platform has the potential to develop problems like those described above. Fortunately, there are many precedents for systematic solutions, -including:
Borrowing from all of the above, OpenACS 3.3 introduces its own package -management system, the OpenACS Package Manager (APM), which consists of:
a standard format for APM packages (also called -"OpenACS packages"), including:
version numbering, independent of any other package and the OpenACS as a -whole
specification of the package interface
specification of dependencies on other packages (if any)
attribution (who wrote it) and ownership (who maintains it)
web-based tools for package management:
obtaining packages from a remote distribution point
installing packages, if and only if:
all prerequisite packages are installed
no conflicts will be created by the installation
configuring packages (obsoleting the monolithic OpenACS configuration -file)
upgrading packages, without clobbering local modifications
uninstalling unwanted packages
a registry of installed packages, database-backed and +including:
Borrowing from all of the above, OpenACS 3.3 introduces its own package +management system, the OpenACS Package Manager (APM), which consists of:
a standard format for APM packages (also called +"OpenACS packages"), including:
version numbering, independent of any other package and the OpenACS as a +whole
specification of the package interface
specification of dependencies on other packages (if any)
attribution (who wrote it) and ownership (who maintains it)
web-based tools for package management:
obtaining packages from a remote distribution point
installing packages, if and only if:
all prerequisite packages are installed
no conflicts will be created by the installation
configuring packages (obsoleting the monolithic OpenACS configuration +file)
upgrading packages, without clobbering local modifications
uninstalling unwanted packages
a registry of installed packages, database-backed and integrated with filesystem-based version control -
web-based tools for package development:
creating new packages locally
releasing new versions of locally-created packages
The design chosen for APM was meant to satisfy the following constraints: -
The process of authoring a package must be as simple as possible.
Strict conventions must be established that provide a set of canonical +
The process of authoring a package must be as simple as possible.
Strict conventions must be established that provide a set of canonical locations and names for files and patterns, for OpenACS application -development.
The processes of installing, upgrading, and using packages must be -straightforward and accessible through a web-based UI.
Package instances must be able to have subsite-specific content available +development.
The processes of installing, upgrading, and using packages must be +straightforward and accessible through a web-based UI.
Package instances must be able to have subsite-specific content available at an easily configurable URL.
All of these requirements were met, but at the cost of development -simplicity. As Packages demonstrates, a set of strict directory conventions are +simplicity. As Packages demonstrates, a set of strict directory conventions are required in order for a package to use APM. This contrasts with the apparent simplicity available to developers of the OpenACS 3.3 system. However, while the system has become more complex for developers to build packages, this complexity is easily managed and is compensated for by additional capabilities.
For example, to make a new application available to the system, a -developer must:
Create the necessary files to support the data model, Tcl API, and UI -pages.
Put the files in the correct locations for APM to be aware of them.
Use APM to create a new package and enable it.
Use the Site Map facility to create an instance of the package, mount it +developer must:
Create the necessary files to support the data model, Tcl API, and UI +pages.
Put the files in the correct locations for APM to be aware of them.
Use APM to create a new package and enable it.
Use the Site Map facility to create an instance of the package, mount it on an appropriate URL, and set parameters for that particular instance.
While this is complex, especially to a new OpenACS developer, the documentation walks the developer through each of these steps. Moreover, from following these steps, the package can be subsite specific, available to subsites across the system, and be available for distribution to other OpenACS -installations without doing a monolithic upgrade or reinstall.
The APM is composed of systems for accomplishing a set of package-related +installations without doing a monolithic upgrade or reinstall.
The APM is composed of systems for accomplishing a set of package-related tasks. Each of these tasks comprise a feature area that has an API, data -model, and a UI:
Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance
Authoring a Package
Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model -creation script, but need not to be used. This API is part of the APM PL/SQL +model, and a UI:
Authoring a Package
Maintaining Multiple Versions of a Package
Creating Instances of the Package
Specifying Configuration Parameters for each Instance
Authoring a Package
Full instructions on how to prepare an OpenACS package are available in Packages. The API here can be invoked manually by a package's data model +creation script, but need not to be used. This API is part of the APM PL/SQL package.
-- Informs the APM that this application is available for use. @@ -144,9 +144,9 @@
The procedure above registers an OpenACS application in the APM. It creates a
new OpenACS object and stores information about the package, such as its name, in
the APM data model. There is an analogous procedure for OpenACS services, called
-apm.register_service.
To remove an application from the system, there are the calls
-apm.unregister_application and
-apm.unregister_service.
+apm.register_service.To remove an application from the system, there are the calls +apm.unregister_application and +apm.unregister_service.
-- Remove the application from the system. procedure unregister_application ( @@ -155,22 +155,22 @@ cascade_p in char default 'f' ); -Use the
cascade_ponly if you want to completely remove the +
Use the cascade_p only if you want to completely remove the package from the OpenACS.
In order to determine if a particular package exists in the system, use
-the register_p predicate. It returns 1 if the specified
-package_key exists in the system, 0 otherwise.
+the register_p predicate. It returns 1 if the specified +package_key exists in the system, 0 otherwise.function register_p ( package_key in apm_package_types.package_key%TYPE ) return integer; -Maintaining Multiple Versions of a Package
While the package authoring API provides a means for registering a +
Maintaining Multiple Versions of a Package
While the package authoring API provides a means for registering a
package, some information about a package is version dependent. For example,
between versions, the owner of a package, its vendor, its URI, and its
dependency information may change. The API for package versions allows this
-information to be specified. All of these APIs are part of the
-apm_package_version PL/SQL package.
To create a new package version, use the
-apm_package_version.new constructor function.
+information to be specified. All of these APIs are part of the +apm_package_version PL/SQL package.To create a new package version, use the +apm_package_version.new constructor function.
function new ( version_id in apm_package_versions.version_id%TYPE @@ -191,26 +191,26 @@ default 'f' ) return apm_package_versions.version_id%TYPE; -In order to use this function, an existing
package_keymust -be specified. Theversion_nameparameter must follow a strict -convention:
A major version number
at least one minor version number. Although any number of minor version +
In order to use this function, an existing package_key must +be specified. The version_name parameter must follow a strict +convention:
A major version number
at least one minor version number. Although any number of minor version numbers may be included, three minor version numbers is sufficient and is the -convention of software developers.
One of the following:
The letter
d, indicating a development-only versionThe letter
a, indicating an alpha releaseThe letter
b, indicating a beta releaseNo letter at all, indicating a final production release
In addition, the letters
d,a, and -bmay be followed by another integer, indicating a version +convention of software developers.One of the following:
The letter d, indicating a development-only version
The letter a, indicating an alpha release
The letter b, indicating a beta release
No letter at all, indicating a final production release
In addition, the letters d, a, and +b may be followed by another integer, indicating a version within the release.
For those who like regular expressions:
version_number := ^[0-9]+((\.[0-9]+)+((d|a|b|)[0-9]?)?)$ -So the following is a valid progression for version numbers:
0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1, -1.1To delete a given version of a package, use the -
apm_package_version.deleteprocedure:+So the following is a valid progression for version numbers:
0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1, +1.1
To delete a given version of a package, use the +apm_package_version.delete procedure:
procedure delete ( package_id in apm_packages.package_id%TYPE );After creating a version, it is possible to edit the information -associated with it using
apm_package_version.edit.+associated with it using apm_package_version.edit.function edit ( new_version_id in apm_package_versions.version_id%TYPE @@ -244,8 +244,8 @@ );Files associated with a version can be added and removed. The path is -relative to the package-root which is -
acs-server-root/packages/package-key.+relative to the package-root which is +acs-server-root/packages/package-key.-- Add a file to the indicated version. function add_file( file_id in apm_package_files.file_id%TYPE @@ -326,7 +326,7 @@ version_name_two in apm_package_versions.version_name%TYPE ) return integer; -Creating Instances of a Package
Once a package is registered in the system, it is possible to create +
Creating Instances of a Package
Once a package is registered in the system, it is possible to create instances of it. Each instance can maintain its own content and parameters.
@@ -353,7 +353,7 @@Just creating a package instance is not sufficient for it to be served from the web server. A corresponding site node must be created for it. As an -example, here is how the OpenACS API Documentation service +example, here is how the OpenACS API Documentation service makes itself available on the OpenACS main site:
declare @@ -381,15 +381,15 @@ show errors -Specifying Configuration Parameters for each Instance
A parameter is a setting that can be changed on a package instance basis. -Parameters are registered on each
package_key, and the values +Specifying Configuration Parameters for each Instance
A parameter is a setting that can be changed on a package instance basis. +Parameters are registered on each package_key, and the values are associated with each instance. Parameters can have default values and can be of type 'string' or 'number.' There is support with this API for setting a number of minimum and maximum values for each parameter, but for most instances, the minimum and maximum should be 1. It is useful to allow or require multiple values for packages that need to store multiple pieces of information under one parameter. Default values are automatically -set when instances are created, but can be changed for each instance.
All of the functions below are in the APM PL/SQL +set when instances are created, but can be changed for each instance.
All of the functions below are in the APM PL/SQL package.
-- Indicate to APM that a parameter is available to the system. @@ -463,65 +463,65 @@ attr_value in apm_parameter_values.attr_value%TYPE ); -
The central piece of the data model is the apm_package_types
table where each package is registered. When a new application or service is
installed on an OpenACS instance, a corresponding row in this table is inserted
-with information about the type of package, e.g. if the forum package is installed on your OpenACS server, a row
-in apm_package_types will be created, noting that it's an
-application package type.
The apm_packages table is used to contain information about
+with information about the type of package, e.g. if the forum package is installed on your OpenACS server, a row
+in apm_package_types will be created, noting that it's an
+application package type.
The apm_packages table is used to contain information about
the instances of packages currently created in the system. The
-package_key column references the apm_package_types
+package_key column references the apm_package_types
table to ensure that no package instance can be created for a type that does
-not exist.
The apm_package_versions table contains information specific
+not exist.
The apm_package_versions table contains information specific to a particular version of a package. Several tables reference this one to -provide further information about the particular version:
apm_package_owners
+provide further information about the particular version:
apm_package_owners Stores information about the owners of a particular version of a package. -
apm_package_files
+
apm_package_files Stores information about the files that are part of a version. -
apm_package_dependencies
+
apm_package_dependencies Stores information about what interfaces the package provides and -requires.
Parameter information is maintained through two tables:
apm_parameters
+requires.
Parameter information is maintained through two tables:
apm_parameters This table contains the definition of each of the parameters for a package. -
apm_parameter_values
+
apm_parameter_values This table holds all of the values of parameters for specific package instances.
A number of views are available for obtaining information about packages -registered in the APM.
apm_package_version_info
+registered in the APM.
apm_package_version_info
Provides information about all of the versions in the system with
-information available from the apm_package_types table.
+information available from the apm_package_types table.
-
apm_enabled_package_versions
+
apm_enabled_package_versions A view (subset) of the above table with only enabled versions. -
apm_file_info
- Provides a public interface for querying file information.
The APM's user interface is part of the -OpenACS Administration Service. The UI is the primary +
apm_file_info + Provides a public interface for querying file information.
The APM's user interface is part of the +OpenACS Administration Service. The UI is the primary point of contact with APM by developers and administrators. It is part of OpenACS Administration, because only the site-wide administrator should be able to access it. Thus in order to develop a package, the developer must be granted -site-wide administration.
APM has two parameters for configuring how it interacts with the UNIX -filesystem, accessible via the Site Map admin +site-wide administration.
APM has two parameters for configuring how it interacts with the UNIX +filesystem, accessible via the Site Map admin page. These parameters need not be changed under most circumstances, but may -need to be tweaked for Windows compatibility.
GzipExecutableDirectory
- This directory points to where the gunzip program can be found
-for uncompressing gzip archives. This is needed for the
-installation of .apm files which are simply gziped
-tarballs. Default is /usr/local/bin
+need to be tweaked for Windows compatibility.
GzipExecutableDirectory + This directory points to where the gunzip program can be found +for uncompressing gzip archives. This is needed for the +installation of .apm files which are simply gziped +tarballs. Default is /usr/local/bin -
InfoFilePermissionsMode +
InfoFilePermissionsMode This sets the default UNIX permissions used when creating files using the -APM. Default is 775.
APM has been in production since OpenACS 3.3, and as of version 4.0 offers a stable set of features. One major feature planned is integration with the OpenACS Package Repository for automatic dependency satisfaction. When a user tries to install a package that depends on other packages, the APM will contact the @@ -539,6 +539,6 @@ repositories worldwide.
Another anticipated change is to split the APM UI into separate systems for authoring, maintaining, and installing packages. The current UI presents all of this functionality in one interface and it can be confusing from a -usability perspective.
System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd -Nightingale.
System owner: Bryan Quinn
Documentation author: Bryan Quinn, building from earlier versions by Jon -Salz, Michael Yoon, and Lars Pind.
System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd +Nightingale.
System owner: Bryan Quinn
Documentation author: Bryan Quinn, building from earlier versions by Jon +Salz, Michael Yoon, and Lars Pind.
By Bryan Quinn and Todd Nightingale
+ +The following is a requirements document for the OpenACS Package Manager (APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality -with the following specific enhancements:
A public procedural API. (v 3.3 only has web-based UI)
Support for dependency checking.
Support for compound packages (to support installation chaining).
Support for on-line parameter setting.
Support for sub-site level configuration (requires revised parameter +with the following specific enhancements:
A public procedural API. (v 3.3 only has web-based UI)
Support for dependency checking.
Support for compound packages (to support installation chaining).
Support for on-line parameter setting.
Support for sub-site level configuration (requires revised parameter and /admin pages at sub-site level; deprecation of site-wide parameter file).
To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number -4.
We gratefully acknowledge the authors of APM 3 for their original design +4.
We gratefully acknowledge the authors of APM 3 for their original design documentation which suggested these features, as well as the influence of the design and open-source implementation of the Red Hat Package manager, the Debian packaging system, and PERL's CPAN in the development of the ideas -behind this document.
A typical website will tend to offer its users a number of web-based +behind this document.
A typical website will tend to offer its users a number of web-based services or applications, e.g. a bulletin board, calendaring, classified ads, etc. A website may also have underlying subsystems, such as a permissions system, content management system, etc. For such applications and subsystem @@ -26,38 +26,38 @@ OpenACS sites.
In general terms, a package is a unit of software that serves a single well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for packaging, installing, and configuring OpenACS software in a consistent, -user-friendly, and subsite-aware manner.
The OpenACS Package Manager (APM) consists of: -
A standard format for APM packages including:
Version numbering, independent of any other package and the OpenACS as a -whole
Specification of the package interface
Specification of dependencies on other packages (if any)
Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
Obtaining packages from a remote distribution point
Installing packages, if and only if:
All prerequisite packages are installed
No conflicts will be created by the installation
Configuring packages (obsoleting the monolithic OpenACS configuration -file)
Upgrading packages, without clobbering local modifications
Uninstalling unwanted packages
A registry of installed packages, database-backed and +
A standard format for APM packages including:
Version numbering, independent of any other package and the OpenACS as a +whole
Specification of the package interface
Specification of dependencies on other packages (if any)
Attribution (who wrote it) and ownership (who maintains it)
Web-based tools for package management:
Obtaining packages from a remote distribution point
Installing packages, if and only if:
All prerequisite packages are installed
No conflicts will be created by the installation
Configuring packages (obsoleting the monolithic OpenACS configuration +file)
Upgrading packages, without clobbering local modifications
Uninstalling unwanted packages
A registry of installed packages, database-backed and integrated with file system-based version control -
Web-based tools for package development:
Creating new packages locally
Releasing new versions of locally-created packages
Uploading packages to a global package repository on the web
Use of these tools should be safe, i.e. installing or removing a package -should never break an OpenACS installation
Web-based tools for package configuration:
The ability to change package parameter values on-line through a simple -web interface.
A new ad_parameter which does not require a monolithic site-wide -parameter's file or server restarts for changes to take effect.
The ability to manage multiple package instances at the sub-site -level.
+
Web-based tools for package development:
Creating new packages locally
Releasing new versions of locally-created packages
Uploading packages to a global package repository on the web
Use of these tools should be safe, i.e. installing or removing a package +should never break an OpenACS installation
Web-based tools for package configuration:
The ability to change package parameter values on-line through a simple +web interface.
A new ad_parameter which does not require a monolithic site-wide +parameter's file or server restarts for changes to take effect.
The ability to manage multiple package instances at the sub-site +level.
The APM is intended for the following classes of users, which may or may not -overlap:
Developers (referred to as 'the developer') use +overlap:
Developers (referred to as 'the developer') use the APM to create a software package for distribution and use the procedural -API for direct control of the APM system.
Site-wide administrators (referred to as 'the +API for direct control of the APM system.
Site-wide administrators (referred to as 'the administrator') use the APM to install packages for their OpenACS instance, -and optionally make them available to sub-sites.
Sub-site administrators (referred to as 'the +and optionally make them available to sub-sites.
Sub-site administrators (referred to as 'the sub-admin') use an administration interface to configure and enable -packages for their sub-site.
Initial Package Development
David Developer writes a piece of software used to do +packages for their sub-site.
Initial Package Development
David Developer writes a piece of software used to do knowledge management (km) for the OpenACS. He distributes his data model, procedure code, UI pages, and his documentation according to the APM specification. He splits the documentation and the code into sub-packages, and creates a KM installation-chain to install both with the APM developer -UI. Noting that his software was built with Patricia -Programmer's Super Widget toolkit, he specifies that as a +UI. Noting that his software was built with Patricia +Programmer's Super Widget toolkit, he specifies that as a dependency. Moreover, since this package is capable of being used at the sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the OpenACS package repository.
Initial Package Installation
Annie Admin learns of David's KM system by browsing +available for download at the OpenACS package repository.
Initial Package Installation
Annie Admin learns of David's KM system by browsing the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The @@ -71,16 +71,16 @@ installation was successful, the package is available for use.
Since the package is available for use, its initialization routines are set to run automatically on server startup. Annie is warned that since there are initialization routines, she must restart the server for the package to -be ready for use. Annie restarts the server.
Initial Subsite Use of Package
Annie Admin decides to make the KM module available only to a particular +be ready for use. Annie restarts the server.
Initial Subsite Use of Package
Annie Admin decides to make the KM module available only to a particular sub-site type on her OpenACS system, and not others. She specifies this option -using the Sub-site type UI (not part of APM).
Annie Admin notifies Sally SubAdmin by e-mail that a new +using the Sub-site type UI (not part of APM).
Annie Admin notifies Sally SubAdmin by e-mail that a new package is now available for use. Sally goes to her sub-site /admin page and sees that a new entry, KM, is available. Sally clicks on it and finds links to the installed KM documentation and to the web based configuration utility. Then, Sally configures the package using an automatically generated web interface and enables KM for use on her sub-site. After some initial use of the package, Sally decides to change some parameters using the SubAdmin UI. -These changes take effect immediately, without any server restarts.
Upgrade Process
Sally SubAdmin finds a bug in the KM system and sends a report to David +These changes take effect immediately, without any server restarts.
Upgrade Process
Sally SubAdmin finds a bug in the KM system and sends a report to David Developer. David reads the bug report and verifies that the bugs are present in the current version. Because the bugs are present in the shared procedure file, David assigns a watch to the file. David makes the necessary @@ -91,199 +91,199 @@ repository.
Sally SubAdmin asks Annie Administrator to upgrade the package using the APM UI. This upgrade supersedes the old version of KM at the site-wide level. Once Annie upgrades the package, the new version starts working immediately -in Sally's sub-site.
Procedural API
Danielle Developer wants her software to perform +in Sally's sub-site.
Procedural API
Danielle Developer wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software -exhibits different behavior.
4.500.0 Package Identification -(All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed +exhibits different behavior.
4.500.0 Package Identification +(All of these items are entered by the developer using the developer UI.)
4.500.1 A human readable package key that is guaranteed to be unique to the local OpenACS site must be maintained by the APM. For -example, "apm."
4.500.5 A package id (primary key) that is guaranteed to +example, "apm."
4.500.5 A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, -"25."
4.500.10 A package URL that is guaranteed to be unique +"25."
4.500.10 A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For -example, "http://openacs.org/software." -
4.505.0 Version Identification - (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to -be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique +example, "http://openacs.org/software." +
4.505.0 Version Identification + (All of these items are entered by the developer using the developer UI.)
4.505.1 A version id (primary key) that is guaranteed to +be unique to the local site must be maintained by the APM.
4.505.5 A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package. -
The API for APM v3 is explicitly a private API. However, it would be useful to obtain information from the APM through a procedural API. Implementing the API specified below is quite easy given that there are pages -that already do all of the below in raw SQL.
4.400.0 Packages Status Predicates
4.400.1 Given defining information such as a package URL, +that already do all of the below in raw SQL.
4.400.0 Packages Status Predicates
4.400.1 Given defining information such as a package URL, the APM API can return the status of the package on the local OpenACS -instance.
4.405.0 Package Information Procedures
4.405.1 The APM API can return information for any +instance.
4.405.0 Package Information Procedures
4.405.1 The APM API can return information for any locally installed packages, including the version number, paths and files, -and package key.
4.410.0 Sub-site Procedures
4.410.1 After a package has been installed at the +and package key.
4.410.0 Sub-site Procedures
4.410.1 After a package has been installed at the site-wide level, the system API will provide means to check for package -presence, creation, enabling, disabling, and destruction on a subsite.
4.415.0 Parameter Values (replaces ad_parameter)
4.415.1 The system API shall allow subsite parameters for +presence, creation, enabling, disabling, and destruction on a subsite.
4.415.0 Parameter Values (replaces ad_parameter)
4.415.1 The system API shall allow subsite parameters for an installed package to be set by either site-wide administrators or sub-site admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only -take effect after a server restart (default is immediate).
4.415.5 Parameters for a given subsite and package can be -returned by the system API.
Provisions will be made to assure that packages are securely -identified.
4.600.1 Each package will have a PGP signature and there +identified.
4.600.1 Each package will have a PGP signature and there will be MD5 time stamps for each file within the package. -
4.600.5 The APM will provide a facility to validate both -the PGP signature and MD5 stamps information before a package install.
The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the -actions taken here can dramatically affect the state of the running OpenACS.
The intent of the developer's interface is to enable the developer to +actions taken here can dramatically affect the state of the running OpenACS.
The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects -throughout the OpenACS and should not be used on a production site.
10.0 Define a package.
The developer must be able to create a new package by specifying some +throughout the OpenACS and should not be used on a production site.
10.0 Define a package.
The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a -package key, version information, owner information, and a canonical URL.
10.1 The APM must maintain the state of all locally -generated packages.
10.50 If the developer fails to provide the required -information, the package cannot be created.
10.55 All of the package information should be editable -after creation, except for the package key.
4.10.60 The package creator must specify whether the +package key, version information, owner information, and a canonical URL.
10.1 The APM must maintain the state of all locally +generated packages.
10.50 If the developer fails to provide the required +information, the package cannot be created.
10.55 All of the package information should be editable +after creation, except for the package key.
4.10.60 The package creator must specify whether the package is capable of being used in sub-sites, or if only a single, global -instance of the package is permitted.
4.10.65 If the developer fails to provide unique +instance of the package is permitted.
4.10.65 If the developer fails to provide unique information for unique fields specified in the data model requirements, the -package cannot be created.
20.0 Add files to a package
20.1 The developer must be able to add files to the +package cannot be created.
20.0 Add files to a package
20.1 The developer must be able to add files to the package. This is done by copying the files into the package directory in the host OS's file system. Files can be added at any point after package -creation.
20.3 Once a package has been versioned and distributed, +creation.
20.3 Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version -number.
20.5 The APM's UI should facilitate the process of +number.
20.5 The APM's UI should facilitate the process of adding new files, by scanning the file system for new files automatically, -and allowing the developer to confirm adding them.
20.10 The developer cannot add files to a given package -via the UI that do not exist in the file system already.
20.15 Package file structure must follow a specified -convention. Please see the design -document for what we do currently.
30.0 Remove files from a package
The developer must be able to remove files from a package. This can be -done in two ways.
30.1 Access the APM UI, browse the file list, and remove -files.
30.1.1If a file is removed from the package list, but not -from the file system, an error should be generated at package load time.
30.5 Remove the file from file system.
30.5.1 The APM UI should take note of the fact that the +and allowing the developer to confirm adding them.
20.10 The developer cannot add files to a given package +via the UI that do not exist in the file system already.
20.15 Package file structure must follow a specified +convention. Please see the design +document for what we do currently.
30.0 Remove files from a package
The developer must be able to remove files from a package. This can be +done in two ways.
30.1 Access the APM UI, browse the file list, and remove +files.
30.1.1If a file is removed from the package list, but not +from the file system, an error should be generated at package load time.
30.5 Remove the file from file system.
30.5.1 The APM UI should take note of the fact that the file is gone and offer the developer an option to confirm the file's deletion. -
40.0 Modify files in a package.
40.1 The developer should be able to modify files in the -file system. The APM UI should not interfere with this.
40.5 However, if the developer modifies files containing -procedural definitions, APM UI should allow a means to watch +
40.0 Modify files in a package.
40.1 The developer should be able to modify files in the +file system. The APM UI should not interfere with this.
40.5 However, if the developer modifies files containing +procedural definitions, APM UI should allow a means to watch those files and automatically reload them if changed. See requirement 50.0 -for more detail.
40.10 Also, although a change in files implies that the +for more detail.
40.10 Also, although a change in files implies that the package distribution file is out of date, it is the developer's -responsibility to update it.
4.45.0 Manage Package Dependency Information.
4.45.1 The developer should be able to specify which -interfaces the package requires.
4.45.5 The developer should be able to specify which -interfaces the package provides.
4.45.10 Circular dependencies are not allowed.
50.0 Watch a file
4.50.1 The developer should be able to assign a watch to -any Tcl procedure file, whether in /packages or /tcl.
50.5 If a watched file is locally modified, then it will +responsibility to update it.
4.45.0 Manage Package Dependency Information.
4.45.1 The developer should be able to specify which +interfaces the package requires.
4.45.5 The developer should be able to specify which +interfaces the package provides.
4.45.10 Circular dependencies are not allowed.
50.0 Watch a file
4.50.1 The developer should be able to assign a watch to +any Tcl procedure file, whether in /packages or /tcl.
50.5 If a watched file is locally modified, then it will be automatically reloaded, thus allowing for any changes made to take affect -immediately.
4.50.10 The setting of a watch should be persistent +immediately.
4.50.10 The setting of a watch should be persistent across server restarts. -
60.0 Display an XML package specification
60.1 The developer should be able to view the XML package +
60.0 Display an XML package specification
60.1 The developer should be able to view the XML package specification that encodes all package information. -
70.0 Write an XML package specification to the file -system
70.1 The developer should be able to write an up-to-date -XML specification to disk.
70.5 The developer should be able to request the current -XML specification for all installed, locally generated packages.
130.0 Distribution file generation
130.1 The developer should be able to generate a .APM -distribution file for the package with just one click.
130.5 Generating a distribution file implies doing an -"up-to-date" check on all of the files. If any of the files have +
70.0 Write an XML package specification to the file +system
70.1 The developer should be able to write an up-to-date +XML specification to disk.
70.5 The developer should be able to request the current +XML specification for all installed, locally generated packages.
130.0 Distribution file generation
130.1 The developer should be able to generate a .APM +distribution file for the package with just one click.
130.5 Generating a distribution file implies doing an +"up-to-date" check on all of the files. If any of the files have changed since package installation, then a new version of the package is created. -
140.0 Access CVS information
140.1 The developer should be able to determine the CVS +
140.0 Access CVS information
140.1 The developer should be able to determine the CVS status of a package, or all packages, with a single click. -
4.400.0 Compound Package Construction
4.400.1 The developer can include .APM packages +
4.400.0 Compound Package Construction
4.400.1 The developer can include .APM packages (sub-packages) within a package (the compound package) like any other -file.
4.400.5 The recommended usage for this feature is to +file.
4.400.5 The recommended usage for this feature is to
allow for separation of optional and required components from the
installation as well as better organization of files once installed. For
example, all documentation for the community-core can be packages as
-community-core-doc.apm. It is legal to include sub-packages with
+community-core-doc.apm. It is legal to include sub-packages with
dependencies that are not satisfied by the packages in the compound package,
but this is discouraged. In such a case, the sub-package should really be a
-separate package that is required by the compound package.
4.400.10 If a sub-package is required for the +separate package that is required by the compound package.
4.400.10 If a sub-package is required for the installation of the compound package, the compound package should have a -registered dependency on the sub-package.
The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete -packages.
80.0 Package Enable/Disable
4.80.1 The administrator should be able mark an installed +packages.
80.0 Package Enable/Disable
4.80.1 The administrator should be able mark an installed package as enabled. This means that the package is activated and its functionality is delivered through the Request Processor. As of OpenACS 4, this -is done through the sub-site system.
4.80.5 Moreover, the administrator must be able to +is done through the sub-site system.
4.80.5 Moreover, the administrator must be able to disable a package, thereby removing the functionality provided to a sub-site. As of OpenACS 4, this is done through the sub-site system. -
90.0 Package Install
90.1 The administrator must be able to install new -packages either from locally maintained .APM files or from URLs.
90.5 In the case of an URL, the APM transparently +
90.0 Package Install
90.1 The administrator must be able to install new +packages either from locally maintained .APM files or from URLs.
90.5 In the case of an URL, the APM transparently downloads the APM file off the web, proceeds with a file based installation, -and then optionally removes the .APM file just downloaded.
90.10.1 If .APM files are present in a package, then it -is considered a compound package (use 4.410.0).
90.15.0 Installation requires these steps:
90.15.1The package dependencies are scanned. If some +and then optionally removes the .APM file just downloaded.
90.10.1 If .APM files are present in a package, then it +is considered a compound package (use 4.410.0).
90.15.0 Installation requires these steps:
90.15.1The package dependencies are scanned. If some dependencies are not present, the system warns the administrator that -installation cannot proceed until those packages are installed.
90.15.2 Assuming all dependencies are present, APM -extracts the contents of the APM file into the /packages directory.
90.15.3 The administrator is offered the option of -importing directly into CVS.
90.15.4 The administrator is given a list of data model -scripts found in the package and can select which ones to be executed.
90.15.5 If no errors are recorded during this process, -the package is enabled.
4.410.0 Compound package Install
4.410.1 If .APM files are present in a package, then it -is considered a compound package.
4.410.5.0 Installation of a compound package proceeds -according to the following sequence:
4.410.5.1 Identify the set of all sub-packages within -the compound package by scanning for all files with .APM.
4.410.5.2 Identify which sub-packages are required by +installation cannot proceed until those packages are installed.
90.15.2 Assuming all dependencies are present, APM +extracts the contents of the APM file into the /packages directory.
90.15.3 The administrator is offered the option of +importing directly into CVS.
90.15.4 The administrator is given a list of data model +scripts found in the package and can select which ones to be executed.
90.15.5 If no errors are recorded during this process, +the package is enabled.
4.410.0 Compound package Install
4.410.1 If .APM files are present in a package, then it +is considered a compound package.
4.410.5.0 Installation of a compound package proceeds +according to the following sequence:
4.410.5.1 Identify the set of all sub-packages within +the compound package by scanning for all files with .APM.
4.410.5.2 Identify which sub-packages are required by checking the dependencies of the compound package. If there dependencies not satisfied by the current system or the packages included with the compound package, halt installation and inform user to install these packages -first.
4.410.5.3 Present Administrator with the ability to +first.
4.410.5.3 Present Administrator with the ability to choose which sub-packages to install. Required sub-packages must be -installed.
4.410.5.4 Proceed with the installation of each +installed.
4.410.5.4 Proceed with the installation of each sub-package, starting with required packages. If the sub-package is already installed, then do nothing. Else, If the sub-package is a normal package, -proceed according to 90.15.0, otherwise if it is a compound -package, proceed according to 4.410.5.0.
4.410.5.5 If all required sub-packages are installed, +proceed according to 90.15.0, otherwise if it is a compound +package, proceed according to 4.410.5.0.
4.410.5.5 If all required sub-packages are installed, proceed to install non-required sub-packages. If there was a failure during the installation of a required sub-package, then the installation of the -compound package is also a failure.
4.410.5.6 Any attempt to install a compound package in +compound package is also a failure.
4.410.5.6 Any attempt to install a compound package in the future involves a choice presented to the admin of installing any -uninstalled sub-packages.
4.420.0 Recovering from failed package installation
4.420.1 If any error is generated during package +uninstalled sub-packages.
4.420.0 Recovering from failed package installation
4.420.1 If any error is generated during package installation, the package is not considered installed. To recover from this -failure, the package should be selected for installation again.
100.0 Version Upgrade
100.1 The administrator can upgrade to a new version of a -package. This entails
100.1.1 Running any necessary and included upgrade -scripts.
100.1.5 Replacing any old files with new versions.
100.1.10 Marking the old version of the package as -'superseded' and disabling it.
100.1.15 Assuming no errors from above, the new package -is enabled.
110.0 Package Deinstall
110.1 The administrator must be able to deinstall a -package that has already been installed. Deinstallation entails:
110.1.1 Running any data model scripts necessary to drop -the package.
110.1.5 Moving all of the files into a separate location -in the file system from the installed packages.
4.110.1.10 If the package is a compound package, then +failure, the package should be selected for installation again.
100.0 Version Upgrade
100.1 The administrator can upgrade to a new version of a +package. This entails
100.1.1 Running any necessary and included upgrade +scripts.
100.1.5 Replacing any old files with new versions.
100.1.10 Marking the old version of the package as +'superseded' and disabling it.
100.1.15 Assuming no errors from above, the new package +is enabled.
110.0 Package Deinstall
110.1 The administrator must be able to deinstall a +package that has already been installed. Deinstallation entails:
110.1.1 Running any data model scripts necessary to drop +the package.
110.1.5 Moving all of the files into a separate location +in the file system from the installed packages.
4.110.1.10 If the package is a compound package, then the administrator must confirm removing all sub-packages. Optionally, some -sub-packages can be kept.
110.5 Deinstalled packages can be re-installed at a later -date.
4.110.10 If deinstalling a package or any of its +sub-packages can be kept.
110.5 Deinstalled packages can be re-installed at a later +date.
4.110.10 If deinstalling a package or any of its sub-packages breaks a dependency, then deinstallation cannot proceed until -the package registering the dependency is removed.
120.0 Package Deletion
120.1 The administrator should be able to completely +the package registering the dependency is removed.
120.0 Package Deletion
120.1 The administrator should be able to completely erase all records of the package. This involves removing all instances of the -package, all related database tables and content.
120.5 This option can only be used if all package +package, all related database tables and content.
120.5 This option can only be used if all package instances are deleted or marked as disabled. This is purposefully cumbersome because deleting all instances of a package can have far-sweeping -consequences throughout a site and should almost never be done.
150.0 Scan for new or modified packages
150.1 The administrator should be able to scan the file -system for any changes made in any of the installed package files.
150.5 The administrator should be able to scan the file +consequences throughout a site and should almost never be done.
150.0 Scan for new or modified packages
150.1 The administrator should be able to scan the file +system for any changes made in any of the installed package files.
150.5 The administrator should be able to scan the file system for any newly installed packages. -
If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface. -
4.300 Creating a package instance.
4.300.1 From the sub-site /admin interface, there should +
4.300 Creating a package instance.
4.300.1 From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an -option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin +option to add a package to the subsite.
4.300.5 From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site -type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is -available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all -parameters with current values must be available.
4.305.5 Changing the values for the parameters is -accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package +type to which the sub-site belongs.
4.300.19 Once a package instance is added, it is +available on the list of the subsite's available packages.
4.305 Configuring a package instance.
4.305.1 An automatic web interface that lists all +parameters with current values must be available.
4.305.5 Changing the values for the parameters is +accomplished simply by submitting an HTML form.
4.310 Enabling a package instance.
4.310.1 The sub-admin should be able to enable a package with a single click. Enabling a package means that the OpenACS will serve its URLs properly. -
4.315 Disabling a package instance.
4.315.1 The sub-admin should be able to disable a package +
4.315 Disabling a package instance.
4.315.1 The sub-admin should be able to disable a package with a single click. Disabling a package means that the OpenACS will no longer -serve those URLs.
4.320 Deleting a package instance.
4.320.1 Deleting a package instance involves deleting not +serve those URLs.
4.320 Deleting a package instance.
4.320.1 Deleting a package instance involves deleting not only the package instance, but any and all content associated with it. It is questionable whether this option should even be available due to its drastic consequences. Reviewer comments appreciated. -
Despite the fact that requirements are meant to be design/implementation neutral, the following thoughts were in our head when specifying these requirements. You must be familiar with the new object design for this to be comprehensible.
When a package is installed system-wide, a corresponding acs_object_type @@ -292,4 +292,4 @@ are set using the acs_attribute_values table. The automatic web interface for setting package parameters should be one and the same with the interface for setting acs object attribute values. Consequently, the implementation of -these features should be quite straightforward.
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.1 | Creation | 8/10/2000 | Bryan Quinn, Todd Nightingale |
| Reviewed | 8/11/2000 | John Prevost, Mark Thomas, and Pete Su | |
| 0.2 | Revised and updated | 8/12/2000 | Bryan Quinn |
| 0.3 | Reviewed, revised, and updated - conforms to requirements template. | 8/18/2000 | Kai Wu |
| 0.4 | Minor edits before ACS 4 Beta. | 9/30/2000 | Kai Wu |
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.1 | Creation | 8/10/2000 | Bryan Quinn, Todd Nightingale |
| Reviewed | 8/11/2000 | John Prevost, Mark Thomas, and Pete Su | |
| 0.2 | Revised and updated | 8/12/2000 | Bryan Quinn |
| 0.3 | Reviewed, revised, and updated - conforms to requirements template. | 8/18/2000 | Kai Wu |
| 0.4 | Minor edits before ACS 4 Beta. | 9/30/2000 | Kai Wu |
By Jeff Davis
+ +Best practices in writing OpenACS automated tests
Special characters in Tcl.
-Try strings starting with a -Bad and strings containing [BAD], {, \077, and $Bad. For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated. The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and if it isn't that's a bug.
-
Quoting issues. Put some html in plain text fields and make sure the result is -properly quoted anywhere it shows up (I use "<b>bold</b>" +
Best practices in writing OpenACS automated tests
Special characters in Tcl. +Try strings starting with a -Bad and strings containing [BAD], {, \077, and $Bad. For user input, [BAD] should never be evaluated, \077 should not be turned into a ? and $Bad should not be interpolated. The string -Bad [BAD] \077 { $Bad should be valid user input, should pass through the system unaltered, and if it isn't that's a bug. +
Quoting issues. Put some html in plain text fields and make sure the result is
+properly quoted anywhere it shows up (I use "<b>bold</b>"
usually). Look out especially for quoting errors in the context bar
and in round trips via an edit form. For fields that disallow html
-tags you can use & to check that the field is quoted
-properly. If it is not displayed as & then the quoting for the field is incorrect. (It's not clear whether this
+tags you can use & to check that the field is quoted
+properly. If it is not displayed as & then the quoting for the field is incorrect. (It's not clear whether this
should be considered an error but given that data for text fields can
come from various sources if it's text it should be properly quoted
and we should not rely on input validation to prevent XSS security
-holes.)
Whitespace input. Check that whitespace is not considered valid input for a field +holes.)
Whitespace input. Check that whitespace is not considered valid input for a field
if it does not make sense. For example, the subject of a forum post is
-used to construct a link and if it is " " it will have a link of
-<a href="..."> </a> which would not be clickable if whitespace was allowed as a valid input.
-
Doubleclick. +used to construct a link and if it is " " it will have a link of +<a href="..."> </a> which would not be clickable if whitespace was allowed as a valid input. +
Doubleclick. Make sure that if you submit a form, use the back button, and submit again that the behavior is reasonable (correct behavior depends on what the form is for, but a server error is not reasonable). -
Duplicate names. +
Duplicate names. Make sure that if a duplicate name is entered that there is a reasonable error rather than a server error. Check for insert, move, copy, and rename. Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.html,v diff -u -r1.43.2.1 -r1.43.2.2 --- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 10 Jun 2009 22:24:06 -0000 1.43.2.1 +++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 11 Sep 2009 23:41:25 -0000 1.43.2.2 @@ -1,89 +1,89 @@ - -
By Jon Salz
+ +Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl
This document describes the startup (bootstrapping) process for an AOLserver +
Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl
This document describes the startup (bootstrapping) process for an AOLserver running OpenACS. -
+
Before OpenACS 3.3, the OpenACS startup process was extremely simple: after AOLserver
performed its internal initialization (reading the configuration file,
loading shared libraries and module code, etc.) it scanned through the Tcl
-library directory (generally /var/lib/aolserver/yourservername/tcl),
+library directory (generally /var/lib/aolserver/yourservername/tcl),
sourcing each file in sequence.
While this overall structure for initialization is still intact, package management has thrown a wrench into the works - there are a few extra things -to do during initialization, most notably:
Examine the OpenACS file tree for files that should not be present in OpenACS +to do during initialization, most notably:
Examine the OpenACS file tree for files that should not be present in OpenACS (i.e., that were once part of the OpenACS distribution but have since been -removed).
Scan the /packages directory for new packages.
Initialize enabled packages by sourcing their *-procs.tcl
-and *-init.tcl files.
+removed).
Scan the /packages directory for new packages.
Initialize enabled packages by sourcing their *-procs.tcl +and *-init.tcl files.
This document examines in detail each of the steps involved in AOLserver/OpenACS startup. -
+As soon as the nsd daemon is executed by the init
process (or otherwise), AOLserver reads its configuration file and
-chroots itself if necessary. It then loads shared libraries
-indicated in the .ini file (e.g., the Oracle driver and
-nssock), and sources Tcl module files (generally in
-/home/aol30/modules/tcl). This step is, and has always been, the
+chroots itself if necessary. It then loads shared libraries
+indicated in the .ini file (e.g., the Oracle driver and
+nssock), and sources Tcl module files (generally in
+/home/aol30/modules/tcl). This step is, and has always been, the
same for all AOLservers, regardless of whether they are running OpenACS.
Next AOLserver sources, in lexicographical order, each file in the
-/tcl directory. The first such file is
-0-acs-init.tcl, which doesn't do much directly except to
-determine the OpenACS path root (e.g., /var/lib/aolserver/yourservername)
+/tcl directory. The first such file is
+0-acs-init.tcl, which doesn't do much directly except to
+determine the OpenACS path root (e.g., /var/lib/aolserver/yourservername)
by trimming the final component from the path to the Tcl library directory
-(/var/lib/aolserver/yourservername/tcl). But
-0-acs-init.tcl's has an important function, namely sourcing
-/packages/acs-core/bootstrap.tcl, which does the following:
Initialize some NSVs used by the core. These NSVs are
-documented in /packages/acs-core/apm-procs.tcl - no need to
+(/var/lib/aolserver/yourservername/tcl). But
+0-acs-init.tcl's has an important function, namely sourcing
+/packages/acs-core/bootstrap.tcl, which does the following:
Initialize some NSVs used by the core. These NSVs are +documented in /packages/acs-core/apm-procs.tcl - no need to worry about them unless you're an OpenACS core hacker. -
Verify the deletion of obsolete OpenACS files. The
-/tcl directory has evolved quite a bit over the months and
+
Verify the deletion of obsolete OpenACS files. The
+/tcl directory has evolved quite a bit over the months and
years, and a few files have come and gone. The
-/www/doc/removed-files.txt file contains a list of files which
+/www/doc/removed-files.txt file contains a list of files which
must be deleted from the AOLserver installation, at the risk of
causing weird conflicts, e.g., having several security filters registered.
-bootstrap.tcl scans through this list, logging error messages to
+bootstrap.tcl scans through this list, logging error messages to
the log if any of these files exist.
-
Source *-procs.tcl files in the OpenACS core.
-We source each file matching the *-procs.tcl glob in the
-/packages/acs-kernel directory, in lexicographical order. These
+
Source *-procs.tcl files in the OpenACS core. +We source each file matching the *-procs.tcl glob in the +/packages/acs-kernel directory, in lexicographical order. These procedure are needed to perform any of the following steps. -
Ensure that the database is available by grabbing and +
Ensure that the database is available by grabbing and releasing a handle. If we can't obtain a handle, we terminate initialization (since OpenACS couldn't possibly start up the server without access to the database). -
Register any new packages in the /packages
-directory. In each directory inside /packages, we look
-for a .info file; if we find a package that hasn't yet been
+
Register any new packages in the /packages
+directory. In each directory inside /packages, we look
+for a .info file; if we find a package that hasn't yet been
registered with the package manager (i.e., it's been copied there
manually), we insert information about it into the database. (The first time
OpenACS starts up, no packages will have been registered in the database
yet, so this step will registers every single package in the
-/packages directory.) Note that packages discovered here are
+/packages directory.) Note that packages discovered here are
initially disabled; they must be manually enabled in the package manager
before they can be used.
-
Ensure that the acs-kernel package is
-enabled. If the OpenACS core isn't initialized, the server
+
Ensure that the acs-kernel package is +enabled. If the OpenACS core isn't initialized, the server couldn't possibly be operational, so if there's no enabled version of the OpenACS core we simply mark the latest installed one as enabled. -
Load *-procs.tcl files for enabled
-packages, activating their APIs.
+
Load *-procs.tcl files for enabled +packages, activating their APIs. -
Load *-init.tcl files for enabled packages,
+
Load *-init.tcl files for enabled packages, giving packages a chance to register filters and procedures, initialize data structures, etc. -
Verify that the core has been properly initialized by +
Verify that the core has been properly initialized by checking for the existence of an NSV created by the request processor initialization code. If it's not present, the server won't be operational, so we log an error.
-At this point, bootstrap.tcl is done executing. AOLserver
-proceeds to source the remaining files in the /tcl directory
+At this point, bootstrap.tcl is done executing. AOLserver
+proceeds to source the remaining files in the /tcl directory
(i.e., unpackaged libraries) and begins listening for connections.
by Jade Rubick
+ +After you've installed and mounted your package, you can configure each instance to act as you would like.
This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Parameters' Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html,v diff -u -r1.4.2.2 -r1.4.2.3 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html 6 Jul 2009 11:14:26 -0000 1.4.2.2 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html 11 Sep 2009 23:41:25 -0000 1.4.2.3 @@ -1,8 +1,8 @@ - -
by Jade Rubick
+ +After you've installed and mounted your package, you can configure each instance to act as you would like.
This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Permissions' Index: openacs-4/packages/acs-core-docs/www/configuring-install-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-install-packages.html,v diff -u -r1.4.2.2 -r1.4.2.3 --- openacs-4/packages/acs-core-docs/www/configuring-install-packages.html 6 Jul 2009 11:14:26 -0000 1.4.2.2 +++ openacs-4/packages/acs-core-docs/www/configuring-install-packages.html 11 Sep 2009 23:41:25 -0000 1.4.2.3 @@ -1,8 +1,8 @@ - -
by Jade Rubick
+ +An OpenACS package extends your website and lets it do things it wasn't able to do before. You can have a weblog, a forums, a calendar, or even do sophisticated project-management via your website.
After you've installed OpenACS, you can congratulate @@ -22,7 +22,7 @@ you want depends on. If you're installing from Local Files, and you are missing any packages, you may have to add the packages your desired package depends on: - the section called “Upgrading the OpenACS files” + Section , “Upgrading the OpenACS files”
If you run into any errors at all, check your /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log file, and post your error on the OpenACS forums
Once the package has been installed, then you will need to Index: openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html,v diff -u -r1.4.2.2 -r1.4.2.3 --- openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html 6 Jul 2009 11:14:26 -0000 1.4.2.2 +++ openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html 11 Sep 2009 23:41:25 -0000 1.4.2.3 @@ -1,8 +1,8 @@ - -
by Jade Rubick
+ +After you've installed your packages, you have to 'mount' them in order to make them appear on your website.
Make sure you are logged in, and then click on the 'Admin' or 'Control Panel' link to get to the Site-Wide Administration page (at /acs-admin). Click on the subsite you'd Index: openacs-4/packages/acs-core-docs/www/configuring-new-site.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-new-site.html,v diff -u -r1.10.2.1 -r1.10.2.2 --- openacs-4/packages/acs-core-docs/www/configuring-new-site.html 10 Jun 2009 22:24:07 -0000 1.10.2.1 +++ openacs-4/packages/acs-core-docs/www/configuring-new-site.html 11 Sep 2009 23:41:25 -0000 1.10.2.2 @@ -1,5 +1,5 @@ - -
Table of Contents
Table of Contents
In this chapter, Configuring refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. Customizing refers to changes that touch the file system, and require some planning if easy upgradability is to be maintained.
In this chapter, Configuring refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. Customizing refers to changes that touch the file system, and require some planning if easy upgradability is to be maintained.
Table of Contents
By Vinod Kurup
+ +Table of Contents
Vinod Kurup put +
Vinod Kurup put together the January 2002 version of this guide from many sources of - information.
Joel Aufrecht - updated the document starting in March 2003.
- Gilbert Wong's FreeBSD + information.
Joel Aufrecht + updated the document starting in March 2003.
Acknowledgments for versions of the above documents go (in no @@ -31,6 +31,6 @@ Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner, Malte Sussdorff, Stan Kaufman and Pascal Scheffers.
- All questions and comments regarding - this guide should be posted on the OpenACS forums. + All questions and comments regarding + this guide should be posted on the OpenACS forums.
All OpenACS code is available anonymously. To get code
anonymously, use the parameter
- -d:pserver:anonymous@cvs.openacs.org:/cvsroot immediately after cvs in a cvs command to check out or export code.
+ -d:pserver:anonymous@cvs.openacs.org:/cvsroot immediately after cvs in a cvs command to check out or export code.
If you are an OpenACS developer, you should check out code so
that you or any other developer can commit it. To do this, use
the parameter
- -d:ext:cvs.openacs.org:/cvsroot
- immediately after cvs in
+ -d:ext:cvs.openacs.org:/cvsroot
+ immediately after cvs in
checkout commands. This will create a local checkout directory
that uses cvs.openacs.org but does not specify the user. By
default, it will use your local account name as the user, so if
- you are logged in as "foobar" it will try to check out and
+ you are logged in as "foobar" it will try to check out and
commit as if you had specified
- :ext:foobar@cvs.openacs.org:/cvsroot. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts.
+ :ext:foobar@cvs.openacs.org:/cvsroot. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts.
OpenACS.org supports non-anonymous cvs access only over ssh, so you
- must have CVS_RSH=ssh in your
+ must have CVS_RSH=ssh in your
environment. (Typically this is accomplished by putting
- export CVS_RSH=ssh into
- ~/.bash_profile.). If your local
+ export CVS_RSH=ssh into
+ ~/.bash_profile.). If your local
account name does not match your cvs.openacs.org account name, create a
- file ~/.ssh/config with an entry
+ file ~/.ssh/config with an entry
like:
Host cvs.openacs.org
User joel
With this setup, you will be asked for your password with each cvs command. To avoid this, set up ssh certificate - authentication for your openacs account. (More + authentication for your openacs account. (More information)
You may want to set some more default actions for CVS usage.
To do so, create the file
- ~/.cvsrc with the contents:
+ ~/.cvsrc with the contents:
cvs -z6
-cvs -q-z6 speeds up cvs access over the network quite a bit by enabling compressed
- connection by default. -q suppresses some verbose output from commands. For example, it makes the output of cvs up much easier to read.
If you are actively developing a non-core package, you + User yournamehere
into your ~/.ssh/config file, then you can use -d :ext:cvs-server:/cvsroot instead of -d :ext:cvs.openacs.org:/cvsroot. You can then change the definition of cvs-server by changing one file instead of editing hundreds of CVSROOT/Repository files.
If you are actively developing a non-core package, you should work from the latest core release branch. Currently this is oacs-5-5. This ensures that you are working on top of a stable OpenACS core, but still allows you to commit feature @@ -62,34 +64,34 @@ want to use only acs-core plus some specific modules. To do this, check out core first:
cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-5 checkout acs-coreThen add modules as needed:
cd /var/lib/aolserver/service0/packages
cvs up -d packagename... where packagename is the - name of the package you want. Visit the Package - Inventory and Package + name of the package you want. Visit the Package + Inventory and Package maintainers and status for a list of available packages and their current state. -
If you are actively developing packages in the OpenACS
Core, work from the HEAD branch. HEAD is used for active
development of the next version of core OpenACS. It may be very
buggy; it may not even install correctly. Do not use this branch for
development of non-core features unless your work depends on some
of the HEAD core work. To check out HEAD, omit the
- -r tag.
To check out HEAD for development, which requires an OpenACS developer account:
cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-coreTo check out HEAD anonymously:
cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core+ -r tag.
To check out HEAD for development, which requires an OpenACS developer account:
cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-coreTo check out HEAD anonymously:
cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core
.LRN consists of a given version openacs core, plus a set of
packages. These are collectively packages together to form a
distrubution of .LRN. F .LRN 2.0.0 sits on top of OpenACS 5.0.0.
.LRN also uses an OpenACS install.xml file during installation;
this file is distributed within the dotlrn package and must be
moved. To get a development checkout of .LRN in the subdirectory
- dotlrn:
+ dotlrn:
cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-5 acs-core
mv openacs-4 dotlrn
cd dotlrn/packages
cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-5 dotlrn-all
-mv dotlrn/install.xml ..
Once you have a checkout you can use some commands to track
- what has changed since you checked out your copy. cvs -n update does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS.
-
To update your files, use cvs update. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.
- All OpenACS code resides within a single CVS module, openacs-4. (The openacs-4 directory contains code for all versions of OpenACS 4 and later, and .LRN 1 and later.) Checking out this module retrieves all openacs code of any type. For convenience, subsets of openacs-4 are repackaged as smaller modules.
- acs-core contains only critical common
+ what has changed since you checked out your copy. cvs -n update does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS.
+
To update your files, use cvs update. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.
+ All OpenACS code resides within a single CVS module, openacs-4. (The openacs-4 directory contains code for all versions of OpenACS 4 and later, and .LRN 1 and later.) Checking out this module retrieves all openacs code of any type. For convenience, subsets of openacs-4 are repackaged as smaller modules.
+ acs-core contains only critical common packages. It does not have any user applications, such as forums, bug-tracker, calendar, or ecommerce. These can be added at any time. @@ -110,29 +112,29 @@ acs-tcl acs-templating ref-timezones search
- dotlrn-all contains the packages required, in combination with acs-core, to run the .LRN system.
+ dotlrn-all contains the packages required, in combination with acs-core, to run the .LRN system.
- project-manager-all contains the packages required, in combination with acs-core, to run the project-manager package.
+ project-manager-all contains the packages required, in combination with acs-core, to run the project-manager package.
- Each OpenACS package (i.e., directory in openacs-4/packages/) is also aliased as a module of the same name.
-
Tags and Branches look similar in commands, but behave differently. A tag is a fixed point on a branch. Check out a tag to get a specific version of OpenACS. Check out a branch to get the most current code for that major-minor version (e.g., 5.0.x or 5.1.x). You can only commit to a branch, not a tag, so check out - a branch if you will be working on the code.
openacs-x-y-z-final
- tags mark final releases of OpenACS. This tag is applied to the acs-core files for an OpenACS core release, and to the latest released versions of all other packages at the time of release. Example: openacs-5-0-4-final.
-
dotlrn-x-y-z-final
- tags mark final releases of .LRN. These tags apply only to .LRN packages. Example: dotlrn-2-0-1-final
-
packagename-x-y-z-final
- tags apply to releases of individual packages. For example, calendar-2-0-0-final is a tag that will retrieve only the files in the calendar 2.0.0 release. It applies only to the
+ a branch if you will be working on the code.
openacs-x-y-z-final + tags mark final releases of OpenACS. This tag is applied to the acs-core files for an OpenACS core release, and to the latest released versions of all other packages at the time of release. Example: openacs-5-0-4-final. +
dotlrn-x-y-z-final + tags mark final releases of .LRN. These tags apply only to .LRN packages. Example: dotlrn-2-0-1-final +
packagename-x-y-z-final + tags apply to releases of individual packages. For example, calendar-2-0-0-final is a tag that will retrieve only the files in the calendar 2.0.0 release. It applies only to the calendar package. All non-core, non-dotlrn packages should have a tag of this style, based on the package name. Many packages have not been re-released since the new naming convention was adopted and so don't have a tag of this type. -
openacs-x-y-compat tags point to the most recent released version of OpenACS X.Y.
+
openacs-x-y-compat tags point to the most recent released version of OpenACS X.Y. It is similar to openacs-x-y-z-compat, except that it will always get the most recent dot-release of Core and the most recent compatible, released version of all other @@ -146,51 +148,51 @@ package, etc. If you update the checkout two months later, you might get version 5.0.5 of all OpenACS core packages and version 2.1 of calendar. -
oacs-x-y is a branch, , not a tag. All core packages in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) are also on the oacs-5-0 branch. Similarly, OpenACS core packages for 5.1.0 are on the oacs-5-1 branch.
These branches are used for two purposes. OpenACS +
oacs-x-y is a branch, , not a tag. All core packages in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) are also on the oacs-5-0 branch. Similarly, OpenACS core packages for 5.1.0 are on the oacs-5-1 branch.
These branches are used for two purposes. OpenACS Core packages on these branches are being tidied up for release. Only bug fixes, not new features, should be added to core packages on release branches. For all other packages, release branches are the recommended location for development. For example, if you are working on calendar, which is compatible with openacs 5.0 but not - 5.1, work on the oacs-5-0 branch.
HEAD is a branch used
- for development of core packages.
There are three main ways to contribute code to OpenACS:
To contribute a small fix, if you do not have a developer account, submit a patch.
If you are making many changes, or would like to become a direct contributor, send mail to the Core Team asking for commit rights. You can then commit code directly to the repository:
Use one of the checkout methods described above to get files to your system. This takes the place of steps 1 and 2 in the section called “Installation Option 2: Install from tarball”. Continue setting up the site as described there.
Fix bugs and add features.
- Commit that file (or files):
cvs commit -m "what I did and why" filename+ 5.1, work on the oacs-5-0 branch.
HEAD is a branch used + for development of core packages.
There are three main ways to contribute code to OpenACS:
To contribute a small fix, if you do not have a developer account, submit a patch.
If you are making many changes, or would like to become a direct contributor, send mail to the Core Team asking for commit rights. You can then commit code directly to the repository:
Use one of the checkout methods described above to get files to your system. This takes the place of steps 1 and 2 in Section , “Installation Option 2: Install from tarball”. Continue setting up the site as described there.
Fix bugs and add features.
+ Commit that file (or files):
cvs commit -m "what I did and why" filenameBecause this occurs in your personal checkout and not an anonymous one, this commit automagically moves back upstream to the Mother Ship repository at cvs.openacs.org. The names of the changed files, and your comments, are sent to a mailing list for OpenACS developers. A Core Team developer may review or roll back your changes if necessary. -
- Confirm via the +
+ Confirm via the OpenACS CVS browser that your changes are where you intended them to be. -
Add a new package. Contact the Core Team to get approval and to get a module alias created.
+
Add a new package. Contact the Core Team to get approval and to get a module alias created.
Check out acs-core on the HEAD branch. (Weird things happen if you add files to a branch but not to HEAD):
cd /tmp
cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-coreCopy your package directory from your working directory to this directory. Make sure not to copy any CVS directories.
cp -r /var/lib/aolserver/service0/packages/newpackage /tmp/openacs-4/packagesImport the package into the cvs.openacs.org cvs repository:
cd /tmp/openacs-4/packages/newpackage
-cvs import -m "Initial import of newpackage" openacs-4/packages/newpackage myname newpackage-0-1dAdd the new package to the modules file. (An administrator has to do this step.) On any machine, in a temporary directory:
cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
+cvs import -m "Initial import of newpackage" openacs-4/packages/newpackage myname newpackage-0-1dAdd the new package to the modules file. (An administrator has to do this step.) On any machine, in a temporary directory:
cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
cd CVSROOT
-emacs modulesAdd a line of the form:
photo-album-portlet openacs-4/packages/photo-album-portlet
Commit the change:
cvs commit -m "added alias for package newpackage" modulesThis should print something like:
cvs commit: Examining .
+emacs modules
Add a line of the form:
photo-album-portlet openacs-4/packages/photo-album-portlet
Commit the change:
cvs commit -m "added alias for package newpackage" modulesThis should print something like:
cvs commit: Examining .
**** Access allowed: Personal Karma exceeds Environmental Karma.
Checking in modules;
/cvsroot/CVSROOT/modules,v <-- modules
new revision: 1.94; previous revision: 1.93
done
-cvs commit: Rebuilding administrative file database
Although you should add your package on HEAD, you should do package development on the latest release branch that your code is compatible with. So, after completing the import, you may want to branch your package:
cd /var/lib/aolserver/service0/packages/newpackage -cvs tag -b oacs-5-1
See the section called “How to package and release an OpenACS Package”
Some packages are already in cvs at openacs-4/contrib/packages. Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the contrib directory un-necessary. If you are working on a contrib package, you should move it to /packages. This must be done by an OpenACS administrator. On cvs.openacs.org:
cp -r /cvsroot/openacs-4/contrib/packages/package0 /cvsroot/openacs-4/packagesUpdate the modules file as described above.
Remove the directory from cvs in the old location using cvs rm. One approach for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done
Although you should add your package on HEAD, you should do package development on the latest release branch that your code is compatible with. So, after completing the import, you may want to branch your package:
cd /var/lib/aolserver/service0/packages/newpackage +cvs tag -b oacs-5-1
See Section , “How to package and release an OpenACS Package”
Some packages are already in cvs at openacs-4/contrib/packages. Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the contrib directory un-necessary. If you are working on a contrib package, you should move it to /packages. This must be done by an OpenACS administrator. On cvs.openacs.org:
cp -r /cvsroot/openacs-4/contrib/packages/package0 /cvsroot/openacs-4/packagesUpdate the modules file as described above.
Remove the directory from cvs in the old location using cvs rm. One approach for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done
CVS commit procedures are governed by - + TIP (Technical Improvement Proposal) #61: Guidelines for CVS committers -
+
Which branch? -
+
For core packages, new features should always be committed on HEAD, not to release branches. -
+
For core packages, bug fixes should be committed on the current release branch whenever applicable. -
+
For non-core packages, developers should work on a checkout of the release branch of the lastest release. For example, if OpenACS 5.1.0 is released, developers should work on the @@ -199,27 +201,27 @@ released.
- Reason: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.
+ Reason: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.
The current release branch is merged back to HEAD after each dot release. -
+
New packages should be created in the
-
+
/packages
-
+
directory
and the maturity flag in the .info file should be zero. This is a change from
previous policy, where new packages went to /contrib/packages)
-
+
Code -
+
Only GPL code and material should be committed to the OpenACS CVS repository (cvs.openacs.org) -
Do not mix formatting changes with code changes. Instead, make a formatting-only change which does not affect the logic, and say so in the commit comment. Then, make the logic change in a separate commit. Reason: This makes auditing and merging code much easier. -
+
Do not mix formatting changes with code changes. Instead, make a formatting-only change which does not affect the logic, and say so in the commit comment. Then, make the logic change in a separate commit. Reason: This makes auditing and merging code much easier. +
Database upgrade scripts should only span one release increment, and should follow - + Naming Database Upgrade Scripts . @@ -232,57 +234,57 @@ that using rc1 instead of b1 would be nice, because that's the convention with release codes in cvs, but the package manager doesn't support rc tags. -
+
Database upgrade scripts should never go to the release version, e.g., should always have a letter suffix such as d1 or b1. -
+
CVS commit messages should be intelligible in the context of Changelogs. They should not refer to the files or versions. -
+
CVS commit messages and code comments should refer to - bug, tip, or patch number if appropriate, in the format "resolves - bug 11", "resolves bugs 11, resolves bug 22". "implements tip 42", - "implements tip 42, implements tip 50", "applies patch 456 by User - Name", "applies patch 456 by User Name, applies patch 523 by - ...". -
+ bug, tip, or patch number if appropriate, in the format "resolves + bug 11", "resolves bugs 11, resolves bug 22". "implements tip 42", + "implements tip 42, implements tip 50", "applies patch 456 by User + Name", "applies patch 456 by User Name, applies patch 523 by + ...". +
When to TIP -
+
A TIP is a Techical Improvement Proposal ( - + more information ). A proposed change must be approved by TIP if: -
+
It changes the core data model, or -
+
It will change the behavior of any core package in a way that affects existing code (typically, by changing public API), or -
+
It is a non-backwards-compatible change to any core or standard package. -
+
A proposed change need not be TIPped if: -
+
it adds a new function to a core package in a way that: -
+
does not change the backwards-compatibility of public API functions. -
+
does not change the data model -
+
has no negative impact on performance -
+
it changes private API, or -
+
it is a change to a non-core, non-standard package -
+
Tags -
+
When a package is released in final form, the developer - shall tag it "packagename-x-y-z-final" and "openacs-x-y-compat". x-y + shall tag it "packagename-x-y-z-final" and "openacs-x-y-compat". x-y should correspond to the current branch. If the package is compatible with several different core versions, several compat tags should be applied. @@ -297,7 +299,7 @@ identify packages which have been released since the last core release.Reason 3: The compat tag or something similar is required to make Rule 6 possible. -
+
When OpenACS core is released, the openacs-x-y-z-final tag shall be applied to all compat packages.
@@ -315,110 +317,110 @@ flag which defaults to no-effect wouldn't require a TIP. Added a new mandatory flag to an existing function would require a TIP. -
Informal guidelines which may be obsolete in places and should be reviewed: -
+
Before committing to cvs you must submit a bug report and patch to the - + OpenACS bug tracker . The only exceptions to this rule are for - + package maintainers committing in a package they are maintaining and for members of the core team. -
+
If you are committing a bug fix you need to coordinate with the package maintainer. If you are a maintainer then coordinate with any fellow maintainers. -
+
If you are to commit a new feature, an architecture change, or a refactoring, you must coordinate with the OpenACS core team first. Also, such changes should have a discussion in the forums to allow for feedback from the whole community. -
+
If you are changing the data model you *must* provide an upgrade script and bump up the version number of the package. -
+
Consider any upgradability ramifications of your change. Avoid changing the contract and behaviour of Tcl procedures. If you want to build a new and clean API consider deprecating the old proc and making it invoke the new one. -
+
Never rush to commit something. Before committing double check with cvs diff what exactly you are committing. -
+
Always accompany a commit with a brief but informative comment. If your commit is related to bug number N and/or patch - number P, indicate this in the commit comment by including "bug N" - and/or "patch P". This allows us to link bugs and patches in the + number P, indicate this in the commit comment by including "bug N" + and/or "patch P". This allows us to link bugs and patches in the Bug Tracker with changes to the source code. For example suppose you are committing a patch that closes a missing HTML tag, then an - appropriate comment could be "Fixing bug 321 by applying patch 134. - Added missing h3 HTML close tag". -
+ appropriate comment could be "Fixing bug 321 by applying patch 134. + Added missing h3 HTML close tag". +
Commit one cohesive bug fix or feature change at a time. Don't put a bunch of unrelated changes into one commit. -
+
Before you throw out or change a piece of code that you don't fully understand, use cvs annotate and cvs log on the file to see who wrote the code and why. Consider contacting the author. -
+
Test your change before committing. Use the OpenACS package acs-automated-testing to test Tcl procedures and the tool - + Tclwebtest to test pages -
+
Keep code simple, adhere to conventions, and use comments liberally. -
+
In general, treat the code with respect, at the same time, never stop questioning what you see. The code can always be improved, just make sure you change the code in a careful and systematic fashion. -
The - + OpenACS cvs web and - + Jeff's cvs browser are useful tools in understanding what is happening with the code. -
+
There is a mailing list of cvs changes at - + willfork.com -
There is an RSS feed of cvs changes at - +
There is an RSS feed of cvs changes at + RSS feed -
- cvs manual -
- backup with cvs -
+ cvs manual +
+ backup with cvs +
Add the Service to CVS - OPTIONAL. These steps take an existing OpenACS directory and add - it to a CVS - repository.
Create and set permissions on a subdirectory in the local cvs repository.
[root root]#mkdir /cvsroot/$OPENACS_SERVICE_NAME-[root root]#chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAME+
Add the Service to CVS - OPTIONAL. These steps take an existing OpenACS directory and add + it to a CVS + repository.
Create and set permissions on a subdirectory in the local cvs repository.
[root root]# mkdir /cvsroot/$OPENACS_SERVICE_NAME +[root root]# chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAME [root root]# mkdir /cvsroot/$OPENACS_SERVICE_NAME -chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAME
Add the repository location to the user environment. On some systems, you may get better results with .bash_profile instead of .bashrc.
[root root]#su - $OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$emacs .bashrc
Put this string into /home/$OPENACS_SERVICE_NAME/.bashrc:
export CVSROOT=/cvsroot
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
+chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAMEAdd the repository location to the user environment. On some systems, you may get better results with .bash_profile instead of .bashrc.
[root root]# su - $OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrcPut this string into /home/$OPENACS_SERVICE_NAME/.bashrc:
export CVSROOT=/cvsroot
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit logout -[root root]#
Import all files into cvs. In order to work on +[root root]#
Import all files into cvs. In order to work on
files with source control, the files must be checked out
from cvs. So we will import, move aside, and then check
out all of the files. In the cvs import command,
- $OPENACS_SERVICE_NAME
+ $OPENACS_SERVICE_NAME
refers to the cvs repository to use; it uses the CVSROOT
plus this string,
i.e.
- /cvsroot/$OPENACS_SERVICE_NAME.
- "OpenACS" is the vendor tag, and "oacs-5-5-0-final" is the
+ /cvsroot/$OPENACS_SERVICE_NAME.
+ "OpenACS" is the vendor tag, and "oacs-5-5-0-final" is the
release tag. These tags will be useful in upgrading and
- branching. -m sets the version comment.
[root root]#su - $OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd /var/lib/aolserver/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cvs import -m "initial install" $OPENACS_SERVICE_NAME OpenACS oacs-5-5-0-final+ branching. -m sets the version comment.[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs import -m "initial install" $OPENACS_SERVICE_NAME OpenACS oacs-5-5-0-final N $OPENACS_SERVICE_NAME/license.txt N $OPENACS_SERVICE_NAME/readme.txt (many lines omitted) @@ -37,19 +37,19 @@ [root root]# su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver/$OPENACS_SERVICE_NAME -cvs import -m "initial install" $OPENACS_SERVICE_NAME OpenACS oacs-5-5-0-final -exitMove the original directory to a temporary location, and check out the cvs repository in its place.
[root root]#mv /var/lib/aolserver/$OPENACS_SERVICE_NAME /var/tmp-[root root]#mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME-[root root]#chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /var/lib/aolserver/$OPENACS_SERVICE_NAME-[root root]#su - $OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd /var/lib/aolserver-[$OPENACS_SERVICE_NAME aolserver]$cvs checkout $OPENACS_SERVICE_NAME+cvs import -m "initial install" $OPENACS_SERVICE_NAME OpenACS oacs-5-5-0-final +exitMove the original directory to a temporary location, and check out the cvs repository in its place.
[root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME /var/tmp +[root root]# mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME +[root root]# chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /var/lib/aolserver/$OPENACS_SERVICE_NAME +[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ cvs checkout $OPENACS_SERVICE_NAME cvs checkout: Updating $OPENACS_SERVICE_NAME U $OPENACS_SERVICE_NAME/license.txt (many lines omitted) U $OPENACS_SERVICE_NAME/www/SYSTEM/dbtest.tcl U $OPENACS_SERVICE_NAME/www/SYSTEM/flush-memoized-statement.tcl -[$OPENACS_SERVICE_NAME aolserver]$exit+[$OPENACS_SERVICE_NAME aolserver]$ exit logout [root root]# @@ -60,4 +60,4 @@ su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver cvs checkout $OPENACS_SERVICE_NAME -exit
If the service starts correctly, come back and remove the temporary copy of the uploaded files.
If the service starts correctly, come back and remove the temporary copy of the uploaded files.
Table of Contents
+ +
By Pete Su and Jon Salz. Modified by Roberto Mello. -
+
One of OpenACS's great strengths is that code written for it is very close to the database. It is very easy to interact with the database from anywhere within OpenACS, and we have a coherent API for database access which makes this even easier.
More detailed information about the DB api is available at - Database Access API. -
The OpenACS database API is meant to save developers from making common mistakes and to provide a more structured syntax for specifying database operations, including transactions. Here's an example of the API.
set count 0
-set tcl_var "foo"
+set tcl_var "foo"
set sql {
SELECT foo, bar, baz
FROM some_table, some_other_table
@@ -35,30 +35,30 @@
}There are several things to note here: -
+
No explicit code for grabbing and releasing handles. Usage of the Database API implicitly deals with all handle management issues. -
- The db_transaction command
+
+ The db_transaction command
makes the scope of a transaction
- clear; db_transaction takes the
+ clear; db_transaction takes the
code block argument and automatically runs it in the context of a
transaction. If you use something like db_foreach though, you need to
make sure that there are no calls in the code block which would take
a second db handle since the transaction is only valid for
one handle (thats why we build up a list of returned values and call
a second proc outside the db_foreach loop).
-
- The command db_foreach writes
+
+ The command db_foreach writes our old while loop for us. -
+
Every SQL query has a name, which is used in conjunction with .XQL files to support multiple databases. -
+
Finally and most importantly, there API implements bind variables, which we will cover next.
-
Bind variables are placeholders for literal values in an SQL query being sent to the server. In the old way, data was generally passed to directly to the DB backend, via Tcl string @@ -69,14 +69,14 @@ where some_table.id=some_other_table.id and some_table.condition_p = '$foo'
There are a few problems with this: -
+
If the value of $foo is a huge string, then we waste a lot of time in the database server doing useless parsing. -
+
Second, if the literal value contains characters like single quotes, we have to be careful to properly escape them, because not quoting them will lead to surprising errors. -
+
Third, no type checking occurs on the literal value. Finally, if the Tcl variable is passed in or between web forms or otherwise subject to external modification, @@ -129,8 +129,8 @@ query, and Tcl style string interpolation does not happen. So you cannot do something like:
-set table "baz"
-set condition "where foo = bar"
+set table "baz"
+set condition "where foo = bar"
db_foreach my_query { select :table from some_table where :condition }
@@ -142,24 +142,24 @@ Finally, the DB API has several different styles for passing bind variable values to queries. In general, use the style presented here because it is the most convenient. -
Every db_* command accepting a SQL command as an argument
- supports bind variables. You can either
- Specify the -bind switch to provide a set with bind variable
+
Every db_* command accepting a SQL command as an argument + supports bind variables. You can either
+ Specify the -bind switch to provide a set with bind variable values, or -
- Specify the -bind switch to explicitly provide a list of
+
+ Specify the -bind switch to explicitly provide a list of bind variable names and values, or -
+
Not specify a bind variable list at all, in which case Tcl variables are used as bind variables.
- The default behavior (i.e., if the -bind switch is omitted) is
+ The default behavior (i.e., if the -bind switch is omitted) is
that these procedures expect to find local variables that correspond in name
to the referenced bind variables, e.g.:
set user_id 123456
-set role "administrator"
+set role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -169,18 +169,18 @@
and map.role = :role
} {
# do something for each group of which user 123456 is in the role
- # of "administrator"
+ # of "administrator"
}
- The value of the local Tcl variable user_id (123456) is bound to
- the user_id bind variable.
-
The -bind switch can takes the name of an ns_set
+ The value of the local Tcl variable user_id (123456) is bound to
+ the user_id bind variable.
+
The -bind switch can takes the name of an ns_set containing keys for each bind variable named in the query, e.g.:
set bind_vars [ns_set create]
ns_set put $bind_vars user_id 123456
-ns_set put $bind_vars role "administrator"
+ns_set put $bind_vars role "administrator"
db_foreach user_group_memberships_by_role {
select g.group_id, g.group_name
@@ -190,11 +190,11 @@
and map.role = :role
} -bind $bind_vars {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
- Alternatively, as an argument to -bind you can specify a list of
+ Alternatively, as an argument to -bind you can specify a list of
alternating name/value pairs for bind variables:
@@ -204,22 +204,22 @@
where g.group_id = map.user_id
and map.user_id = :user_id
and map.role = :role
-} -bind [list user_id 123456 role "administrator"] {
+} -bind [list user_id 123456 role "administrator"] {
# do something for each group in which user 123456 has the role
- # of "administrator"
+ # of "administrator"
}
-
When processing a DML statement, Oracle coerces empty strings into
- null. (This coercion does not occur in the
- WHERE clause of a query, i.e.
- col = '' and
- col is null are not equivalent.)
+ null. (This coercion does not occur in the
+ WHERE clause of a query, i.e.
+ col = '' and
+ col is null are not equivalent.)
As a result, when using bind variables, the only way to make Oracle set a
- column value to null is to set the corresponding bind variable
+ column value to null is to set the corresponding bind variable
to the empty string, since a bind variable whose value is the string
- "null" will be interpreted as the literal string
- "null".
These Oracle quirks complicate the process of writing clear and abstract + "null" will be interpreted as the literal string + "null".
These Oracle quirks complicate the process of writing clear and abstract DML difficult. Here is an example that illustrates why:
#
@@ -231,43 +231,43 @@
# );
#
-set bar ""
-set baz ""
+set bar ""
+set baz ""
-db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
+db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
#
-# the values of the "bar" and "baz" columns in the new row are both
+# the values of the "bar" and "baz" columns in the new row are both
# null, because Oracle has coerced the empty string (even for the
-# numeric column "bar") into null in both cases
+# numeric column "bar") into null in both cases
Since databases other than Oracle do not coerce empty strings into
- null, this code has different semantics depending on the
+ null, this code has different semantics depending on the
underlying database (i.e., the row that gets inserted may not have null as
its column values), which defeats the purpose of SQL abstraction.
Therefore, the Database Access API provides a database-independent way to
- represent null (instead of the Oracle-specific idiom of the
- empty string): db_null.
Use it instead of the empty string whenever you want to set a column value
- explicitly to null, e.g.:
set bar [db_null] + represent null (instead of the Oracle-specific idiom of the + empty string): db_null.Use it instead of the empty string whenever you want to set a column value + explicitly to null, e.g.:
set bar [db_null] set baz [db_null] -db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" +db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" # -# sets the values for both the "bar" and "baz" columns to null
The database library can transparently maintain pools of sequence values, so
- that each request for a new sequence value (using db_nextval)
+ that each request for a new sequence value (using db_nextval)
does not incur a roundtrip to the server. For instance, this functionality is
very useful in the security/sessions library, which very frequently allocates
- values from the sec_id_seq sequence. To utilize this
+ values from the sec_id_seq sequence. To utilize this
functionality for a particular sequence, register the sequence to be pooled,
- either using the db_register_pooled_sequence procedure at server
+ either using the db_register_pooled_sequence procedure at server
startup time, or by including a configuration parameter of the form
PoolSequence.sequence_name_seq=count
- in any configuration section in the yourservername.ini
+ in any configuration section in the yourservername.ini
file, e.g.,
@@ -279,49 +279,49 @@
startup. It will periodically scan pools and allocate new values for
sequences which are less than half-full. (This normally occurs every 60
seconds, and is configurable via the
- PooledSequenceUpdateInterval parameter in the
- [ns/server/
- yourservername
- /acs/database] configuration
+ PooledSequenceUpdateInterval parameter in the
+ [ns/server/
+ yourservername
+ /acs/database] configuration
section.)
- The Database API has several functions that wrap familiar parts of the AOLserver database API.
- Note that you never have to use ns_db anymore (including
- ns_db gethandle)! Just start doing stuff, and (if you want) call
- db_release_unused_handles when you're done as a hint to
+ Note that you never have to use ns_db anymore (including
+ ns_db gethandle)! Just start doing stuff, and (if you want) call
+ db_release_unused_handles when you're done as a hint to
release the database handle.
+
db_abort_transaction
-
+
db_abort_transaction
Aborts all levels of a transaction. That is if this is called within
several nested transactions, all of them are terminated. Use this insetead of
- db_dml "abort" "abort transaction".
+ db_dml "abort" "abort transaction".
-
db_multirow-db_multirow [ -local ] [ -append ] [ -extend column_list ] \ +
+db_multirow [ -local ] [ -append ] [ -extend column_list ] \ var-name statement-name sql \ [ -bind bind_set_id | -bind bind_value_list ] \ code_block [ if_no_rows if_no_rows_block ]
- Performs the SQL query sql, saving results in variables
+ Performs the SQL query sql, saving results in variables
of the form
- var_name:1, var_name:2, etc,
- setting var_name:rowcount to the total number
- of rows, and setting var_name:columns to a
+ var_name:1, var_name:2, etc,
+ setting var_name:rowcount to the total number
+ of rows, and setting var_name:columns to a
list of column names.
Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column.
- If the -local is passed, the variables defined
+ If the -local is passed, the variables defined
by db_multirow will be set locally (useful if you're compiling dynamic templates
in a function or similar situations).
@@ -334,19 +334,19 @@ multirow.
You may also add additional, computed columns to the multirow, using the
- -extend { col_1 col_2 ... } switch. This is
+ -extend { col_1 col_2 ... } switch. This is
useful for things like constructing a URL for the object retrieved by
the query.
If you're constructing your multirow through multiple queries with the
same set of columns, but with different rows, you can use the
- -append switch. This causes the rows returned by this query
+ -append switch. This causes the rows returned by this query
to be appended to the rows already in the multirow, instead of starting
a clean multirow, as is the normal behavior. The columns must match the
columns in the original multirow, or an error will be thrown.
- Your code block may call continue in order to skip a row
- and not include it in the multirow. Or you can call break
+ Your code block may call continue in order to skip a row
+ and not include it in the multirow. Or you can call break
to skip this row and quit looping.
Notice the nonstandard numbering (everything @@ -380,240 +380,240 @@
Technically it's equivalent to using a code block on the end of your db_multirow.
+
db_null
-
+
-db_null
+db_null
Returns a value which can be used in a bind variable
to represent the SQL value
- null.
- See Nulls and
+ null.
+ See Nulls and
Bind Variables above.
+
db_foreach
-
+
db_foreach statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ [ -column_array array_name | -column_set set_name ] \ code_block [ if_no_rows if_no_rows_block ]
Performs the SQL query
- sql
+ sql
, executing
- code_block
- once for each row
+ code_block
+ once for each row
with variables set to column values (or a set or array
populated if
- -column_array or
- column_set is
+ -column_array or
+ column_set is
specified). If the query returns no rows, executes
- if_no_rows_block
- (if provided).
+ if_no_rows_block
+ (if provided).
Example:
-db_foreach select_foo "select foo, bar from greeble" {
- doc_body_append "<li>foo=$foo; bar=$bar\n"
+db_foreach select_foo "select foo, bar from greeble" {
+ doc_body_append "<li>foo=$foo; bar=$bar\n"
} if_no_rows {
- doc_body_append "<li>There are no greebles in the database.\n"
+ doc_body_append "<li>There are no greebles in the database.\n"
}
- The code block may contain break statements (which terminate the
- loop and flush the database handle) and continue statements
+ The code block may contain break statements (which terminate the
+ loop and flush the database handle) and continue statements
(which continue to the next row of the loop).
+
db_1row
-
+
db_1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ [ -column_array array_name | -column_set set_name ]
Performs the SQL query
- sql,
+ sql,
setting variables to column values. Raises an error if the
query does not return exactly 1 row.
Example:
-db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id" +db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id" # Bombs if there's no such greeble! # Now $foo and $bar are set.
+
db_0or1row
-
+
db_0or1row statement-name sql [ -bind bind_set_id | -bind bind_value_list ] \ [ -column_array array_name | -column_set set_name ]
Performs the SQL query
- sql.
+ sql.
If a row is returned, sets variables to column values and
returns 1. If no rows are returned, returns 0. If more
than one row is returned, throws an error.
-
db_nextval +
db_nextval sequence-name
Returns the next value for the sequence sequence-name (using a
- SQL statement like SELECT
- sequence-name.nextval FROM
- DUAL). If sequence pooling is enabled for the sequence, transparently
+ SQL statement like SELECT
+ sequence-name.nextval FROM
+ DUAL). If sequence pooling is enabled for the sequence, transparently
uses a value from the pool if available to save a round-trip to the database
- (see Sequence Pooling).
+ (see Sequence Pooling).
+
db_register_pooled_sequence
-
+
db_register_pooled_sequence sequence-name pool-size
Registers the sequence sequence-name to be pooled, with a pool size of pool-size sequence values - (see Sequence Pooling). + (see Sequence Pooling). -
db_string +
db_string statement-name sql [ -default default ] [ -bind bind_set_id | -bind bind_value_list ]
Returns the first column of the result of SQL query
- sql.
- If sql doesn't return a
+ sql.
+ If sql doesn't return a
row, returns
- default
+ default
(or throws an error if
- default is unspecified). Analogous to
- database_to_tcl_string and
- database_to_tcl_string_or_null.
+ default is unspecified). Analogous to
+ database_to_tcl_string and
+ database_to_tcl_string_or_null.
-
db_list+
db_list statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Returns a Tcl list of the values in the first column of the result of SQL
query
- sql.
- If sql doesn't
+ sql.
+ If sql doesn't
return any rows, returns an empty list. Analogous to
- database_to_tcl_list.
+ database_to_tcl_list.
-
db_list_of_lists+
db_list_of_lists statement-name sql [ -bind bind_set_id | -bind bind_value_list ]
Returns a Tcl list, each element of which is a list of all column values
- in a row of the result of SQL query sql. If
- sql doesn't return any rows, returns an empty list.
- (Analogous to database_to_tcl_list_list.)
+ in a row of the result of SQL query sql. If
+ sql doesn't return any rows, returns an empty list.
+ (Analogous to database_to_tcl_list_list.)
-
db_dml+
db_dml statement-name sql \ [ -bind bind_set_id | -bind bind_value_list ] \ [ -blobs blob_list | -clobs clob_list | -blob_files blob_file_list | -clob_files clob_file_list ] -
Performs the DML or DDL statement sql.
If a length-n list of blobs or clobs is provided, then the SQL +
Performs the DML or DDL statement sql.
If a length-n list of blobs or clobs is provided, then the SQL
should return n blobs or clobs into the bind variables
- :1, :2, ... :n.
- blobs or clobs, if specified,
+ :1, :2, ... :n.
+ blobs or clobs, if specified,
should be a list of individual BLOBs or CLOBs to insert;
- blob_files or clob_files, if
+ blob_files or clob_files, if
specified, should be a list of paths to files containing the data to
- insert. Only one of -blobs, -clobs,
- -blob_files, and -clob_files may be provided.
Example:
+ insert. Only one of -blobs, -clobs, + -blob_files, and -clob_files may be provided.Example:
-db_dml insert_photos " +db_dml insert_photos " insert photos(photo_id, image, thumbnail_image) values(photo_id_seq.nextval, empty_blob(), empty_blob()) returning image, thumbnail_image into :1, :2 - " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"] + " -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"]- This inserts a new row into the
photostable, with the contents - of the files/var/tmp/the_photoand -/var/tmp/the_thumbnailin theimageand -thumbnailcolumns, respectively. + This inserts a new row into the photos table, with the contents + of the files /var/tmp/the_photo and + /var/tmp/the_thumbnail in the image and + thumbnail columns, respectively.
db_write_clob,
- db_write_blob,
- db_blob_get_file
+ db_write_clob,
+ db_write_blob,
+ db_blob_get_file
db_write_clob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] db_write_blob statement-name sql [ -bind bind_set_id | -bind bind_value_list ] db_blob_get_file statement-name sql [ -bind bind_set_id | -bind bind_value_list ] -
Analagous to ns_ora write_clob/write_blob/blob_get_file.
+
Analagous to ns_ora write_clob/write_blob/blob_get_file. -
db_release_unused_handles+
db_release_unused_handles -
Releases any allocated, unused database handles.
db_transaction+
Releases any allocated, unused database handles.
db_transaction code_block [ on_error { code_block } ] -
Executes code_block transactionally. Nested
- transactions are supported (end transaction is transparently
- ns_db dml'ed when the outermost transaction completes). The
- db_abort_transaction command can be used to abort all levels of
- transactions. It is possible to specify an optional on_error
+
Executes code_block transactionally. Nested
+ transactions are supported (end transaction is transparently
+ ns_db dml'ed when the outermost transaction completes). The
+ db_abort_transaction command can be used to abort all levels of
+ transactions. It is possible to specify an optional on_error
code block that will be executed if some code in code_block throws
- an exception. The variable errmsg will be bound in that scope.
- If there is no on_error code, any errors will be propagated.
Example:
+ an exception. The variable errmsg will be bound in that scope. + If there is no on_error code, any errors will be propagated.Example:
proc replace_the_foo { col } { db_transaction { - db_dml "delete from foo" - db_dml "insert into foo(col) values($col)" + db_dml "delete from foo" + db_dml "insert into foo(col) values($col)" } } proc print_the_foo {} { - doc_body_append "foo is [db_string "select col from foo"]<br>\n" + doc_body_append "foo is [db_string "select col from foo"]<br>\n" } replace_the_foo 8 -print_the_foo ; # Writes out "foo is 8" +print_the_foo ; # Writes out "foo is 8" db_transaction { replace_the_foo 14 - print_the_foo ; # Writes out "foo is 14" - db_dml "insert into some_other_table(col) values(999)" + print_the_foo ; # Writes out "foo is 14" + db_dml "insert into some_other_table(col) values(999)" ... db_abort_transaction } on_error { - doc_body_append "Error in transaction: $errmsg" + doc_body_append "Error in transaction: $errmsg" } -print_the_foo ; # Writes out "foo is 8" +print_the_foo ; # Writes out "foo is 8" -
db_resultrows+
db_resultrows
Returns the number of rows affected or returned by the previous statement. -
db_with_handle+
db_with_handle var code_block -
Places a database handle into the variable var and
- executes code_block. This is useful when you don't
- want to have to use the new API (db_foreach,
- db_1row, etc.), but need to use database handles explicitly.
Example:
+
Places a database handle into the variable var and + executes code_block. This is useful when you don't + want to have to use the new API (db_foreach, + db_1row, etc.), but need to use database handles explicitly.
Example:
proc lookup_the_foo { foo } {
db_with_handle db {
- return [db_string unused "select ..."]
+ return [db_string unused "select ..."]
}
}
db_with_handle db {
# Now there's a database handle in $db.
- set selection [ns_db select $db "select foo from bar"]
+ set selection [ns_db select $db "select foo from bar"]
while { [ns_db getrow $db $selection] } {
set_variables_after_query
@@ -623,51 +623,51 @@
+
db_nullify_empty_string
-
+
db_nullify_empty_string string
For true SQL purists, we provide the convenience function
- db_nullify_empty_string, which returns
- [db_null] if its string argument is the empty string
+ db_nullify_empty_string, which returns
+ [db_null] if its string argument is the empty string
and can be used to encapsulate another Oracle quirk:
-set baz ""
+set baz ""
# Clean out the foo table
#
-db_dml unused "delete from foo"
+db_dml unused "delete from foo"
-db_dml unused "insert into foo(baz) values('$baz')"
+db_dml unused "insert into foo(baz) values('$baz')"
-set n_rows [db_string unused "select count(*) from foo where baz is null"]
+set n_rows [db_string unused "select count(*) from foo where baz is null"]
#
-# $n_rows is 1; in effect, the "baz is null" criterion is matching
+# $n_rows is 1; in effect, the "baz is null" criterion is matching
# the empty string we just inserted (because of Oracle's coercion
# quirk)
- To balance out this asymmetry, you can explicitly set baz to
- null by writing:
+ To balance out this asymmetry, you can explicitly set baz to
+ null by writing:
-db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
+db_dml foo_insert "insert into foo(baz) values(:1)" {[db_nullify_empty_string $baz]}
-
The database API allows for direct caching of query results. Repeated calls will +
The database API allows for direct caching of query results. Repeated calls will return the cached value until it is either explicitly flushed using db_flush_cache, times out (configured the ns_cache is called to create the cache), or another cached query fills the cache, causing older entries to be flushed. -
Values returned by a query are cached if you pass the "-cache_key" switch +
Values returned by a query are cached if you pass the "-cache_key" switch to the database procedure. The switch value will be used as the key in the ns_cache eval call used to execute the query and processing code. The db_flush proc should be called to flush the cache when appropriate. The - "-cache_pool" parameter can be used to specify the cache pool to be used, + "-cache_pool" parameter can be used to specify the cache pool to be used, and defaults to db_cache_pool. The size of the default cache is governed - by the kernel parameter "DBCacheSize" in the "caching" section. + by the kernel parameter "DBCacheSize" in the "caching" section.
Currently db_string, db_list, db_list_of_lists, db_1row, db_0or1row, and db_multirow support caching. @@ -677,7 +677,7 @@ more object_ids and a name that identifies the operation being done.
Here is an example from the layout-manager package:
-# Query to return the elements of a page as a list. The prefix "page_" is used to denote +# Query to return the elements of a page as a list. The prefix "page_" is used to denote # that this is a page-related query, page_id is used to uniquely identify the query # by object, and the suffix uniquely defines the operation being performed on the # page object. Index: openacs-4/packages/acs-core-docs/www/dev-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v diff -u -r1.30.2.2 -r1.30.2.3 --- openacs-4/packages/acs-core-docs/www/dev-guide.html 6 Jul 2009 11:14:26 -0000 1.30.2.2 +++ openacs-4/packages/acs-core-docs/www/dev-guide.html 11 Sep 2009 23:41:26 -0000 1.30.2.3 @@ -1,2 +1,2 @@ - -Chapter 10. Development Reference Table of Contents
- OpenACS Packages
- OpenACS Data Models and the Object System
- The Request Processor
- The OpenACS Database Access API
- Using Templates in OpenACS
- Groups, Context, Permissions
- Writing OpenACS Application Pages
- Parties in OpenACS
- OpenACS Permissions Tediously Explained
- Object Identity
- Programming with AOLserver
- Using Form Builder: building html forms dynamically
View comments on this page at openacs.org + +Chapter 10. Development Reference Section missingTable of Contents
- OpenACS Packages
- OpenACS Data Models and the Object System
- The Request Processor
- The OpenACS Database Access API
- Using Templates in OpenACS
- Groups, Context, Permissions
- Parties in OpenACS
- OpenACS Permissions Tediously Explained
- Object Identity
- Programming with AOLserver
- Using Form Builder: building html forms dynamically
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/doc-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/doc-standards.html,v diff -u -r1.12.2.2 -r1.12.2.3 --- openacs-4/packages/acs-core-docs/www/doc-standards.html 6 Jul 2009 11:14:26 -0000 1.12.2.2 +++ openacs-4/packages/acs-core-docs/www/doc-standards.html 11 Sep 2009 23:41:26 -0000 1.12.2.3 @@ -1,2 +1,2 @@ - -Chapter 12. Documentation Standards View comments on this page at openacs.org + +Chapter 12. Documentation Standards Section missingView comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -r1.46.2.2 -r1.46.2.3 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 6 Jul 2009 11:17:31 -0000 1.46.2.2 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 11 Sep 2009 23:41:26 -0000 1.46.2.3 @@ -1,8 +1,8 @@ - -OpenACS Documentation Guide + +
OpenACS Documentation Guide By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS Community -
- OpenACS is a powerful system with +
+ OpenACS™ is a powerful system with incredible possibilities and applications, but this power comes with some complexity and a steep learning curve that is only attenuated by good documentation. Our goal is to write @@ -41,40 +41,40 @@ This document attempts to shape ongoing documentation efforts by using principles of continual improvement to re-engineer documentation production. -
Documentation production shares many of the challenges of software development, such as managing contributions, revisions and the (editorial) release cycle. This is yet another experiment in improving documentation --this time by using principles of continual improvement to focus the on-going efforts. These processes are outlined as project management phases: -
- Requirements phase is about setting goals and +
+ Requirements phase is about setting goals and specifications, and includes exploration of scenarios, use cases - etc. As an example, see the + etc. As an example, see the OpenACS Documentation Requirements Template which focuses on systems requirements for developers. -
- Strategy phase is about creating an approach +
+ Strategy phase is about creating an approach to doing work. It sets behavioral guidelines and boundaries that help keep perspective on how efforts are directed. OpenACS developers discuss strategy when coordinating efforts such as code revisioning and new features. -
- Planning phase is about explicitly stating +
+ Planning phase is about explicitly stating the way to implement the strategy as a set of methods. OpenACS system design requires planning. For example, see - OpenACS + OpenACS documentation template planning relating to package design. -
- Implementation phase is about performing the +
+ Implementation phase is about performing the work according to the plan, where decisions on how to handle unforseen circumstances are guided by the strategy and requirements. -
- Verification phase measures how well the plan +
+ Verification phase measures how well the plan was implemented. Success is measured by A) verifying if the project has met the established goals, and B) reviewing for ongoing problem areas etc. OpenACS follows verification @@ -88,56 +88,56 @@ phases are mainly organized and fulfilled by a designated documentation maintainer. Hopefully the following sections will help spur greater direct participation by the OpenACS community. -
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 documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. -
- clarity in presentation. Life with - qmail is a recommended example of "rated high" online +
+ clarity in presentation. Life with + qmail is a recommended example of "rated high" online documentation. -
+
Avoid requirements that significantly increase the labor required to maintain documentation. -
+
Use best practices learned from the print world, web, and other media, about use of gamma, space, writing style etc. -
+
Consistency in publishing -Establishing and adhering to publishing standards -
+
Use standardized language -Use international English (without slang or colloquial terms) for ESL (English as a second language) readers (and making translation easier for those interested in translating the documentation for internationalization efforts). -
+
All jargon used in documentation needs to be defined. Use standardized terms when available, avoiding implicit understanding of specific OpenACS terms. -
+
Document titles (for example on html pages) should include whole document title (as in book title): (chapter title) : (section), so that bookmarks etc. indicate location in a manner similar to pages in books (in print publishing world). -
+
Organize document according to the needs of the reader (which may be different than the wishes of the writers). -
+
Do not make informal exclamations about difficulty/ease for users to complete tasks or understand... for - example, "Simply...". Readers come from many different + example, "Simply...". Readers come from many different backgrounds --remember that the greater audience is likely as varied as the readers on the internet--- If important, state pre-conditions or knowledge requirements etc. if different than the rest of the - context of the document. For example, "requires basic + context of the document. For example, "requires basic competency with a text-based editor such as vi or emacs - via telnet" -
+ via telnet" +
Show where to find current information instead of writing about current info that becomes obsolete. If the information is not found elsewhere, then create one place for it, where @@ -152,20 +152,20 @@ still be in 1 area, using a common layout of perhaps summary, introduction and discussion requiring increasing expertise, complexity or specificity. -
+
Consistency in link descriptions -When link urls refer to whole documents, make the link (anchor wrapped title) that points to a document with the same title and/or heading of the document. -
+
Consider OpenACS documentation as a set of books (an encyclopedic set organized like an atlas) that contains volumes (books). Each book contains chapters and sections much like how DocBook examples are shown, where each chapter is a web page. This designation could help create an OpenACs book in print, and help new readers visualize how the documentation is organized. -
+
The use licenses between OpenACS and Arsdigita's ACS are not compatible, thereby creating strict limits on how much OpenACS developers should have access to Arsdigita code and @@ -175,60 +175,60 @@ inference of license noncompliance, while recognizing the important work accomplished by Philip Greenspun, Arsdigita, and the early ACS adopters. -
+
Use a consistent general outline for each book. -
+
Introduction (includes purpose/goal), Glossary of terms, Credits, License, Copyright, Revision History -
+
Table of Contents (TOC)s for each book: the end-users, content and site administrators, marketing, developer tutorial, and developers. -
+
Priorities of order and content vary based on each of the different readers mentioned. The developers guide should be organized to be most useful to the priorities of developers, while being consistent with the general documentation requirements including publishing strategy, style etc. -
+
Use generic DocBook syntax to maximize reader familiarity with the documents.
- <book><title><part label="Part 1"><etc...> + <book><title><part label="Part 1"><etc...>
-
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 + (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 + -- 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 @@ -238,32 +238,32 @@ 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 + 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, +
+ 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 +
+ 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 @@ -272,10 +272,10 @@ 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 @@ -284,22 +284,22 @@ 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 @@ -308,19 +308,19 @@ 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. -
+ 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, @@ -331,233 +331,233 @@ 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 + development document templates: a + Requirements Template and Detailed Design Document. -
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 + 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 -
+ 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 -
+
+ 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 + new master.adp, options on "user pages" , a quick introduction to the functions and processes. info about the user variables, file locations -
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 +
+ state installation prerequisites. For example: "You should read through the installation process to familiarize yourself with the installation process, before beginning an - installation." -
+ 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 + 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." -
+ 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 -
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 +
+ 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 -
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 +
+ 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 -
OpenACS documentation development is subject to the constraints of the software project development and release - methods and cycles (the section called “Using CVS with OpenACS”). + methods and cycles (Section , “Using CVS with OpenACS”). Essentially, all phases of work may be active to accommodate the asynchronous nature of multiple subprojects evolving by the efforts of a global base of participants with culturally @@ -567,50 +567,50 @@ involve others by collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project. -
OpenACS documentation is taking a dual approach to publishing. Documentation that is subject to rapid change and participation by - the OpenACS community is managed through the OpenACS + the OpenACS community is managed through the OpenACS xowiki Documentation Project Formal documents that tend to remain static and require more expressive publishing tools will be marked up to conform to the - DocBook XML + DocBook XML DTD. The remaining discussion is about publishing using Docbook.
- + is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook: -
+
It is open-source. -
+
A growing community surrounds DocBook (has - mailing lists) -
+ mailing lists) +
A number of free and commercial - tools are available + tools are available for editing and publishing DocBook documents. -
+
It enables us to publish in a variety of formats. -
+
XML separates content from presentation: It relieves each contributor of the burden of presentation, freeing each writer to focus on content and sharing knowledge. -
+
It is well tested technology. It has been in development - since the early 1990's). + since the early 1990's).
Reasons why we are using Docbook XML instead of Docbook SGML: -
+
Consistency and history. We started with a collection of DocBook XML files that ArsDigita wrote. Trying to re-write them to conform to the SGML DTD would be unnecessary work. -
+
XML does not require extra effort. Writing in XML is almost identical to SGML, with a couple extra rules. More details in the - LDP Author Guide. -
+ LDP Author Guide. +
The tool chain has matured. xsltproc and other XML based tools have improved to the point where they are about as good as the SGML tools. Both can output html and pdf formats. @@ -629,50 +629,50 @@ should be able to extract details of a specific reference from a bibliographic (table) and present a footnote at the point where referenced. DocBook 4.4 allows for this with -
bibliocoverage, -bibliorelation, and -bibliosource. DocBook: + bibliocoverage, + bibliorelation, and + bibliosource. DocBook: The Definitive Guide is a good start for learning how to represent paper-based books online.The following DocBook primer walks you through the basics, and should cover the needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's - + list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically - the same elements are valid in the XML DTD as long as you remember to: - -
You are going to need the following to work with the OpenACS Docbook XML documentation: -
+ Docbook XML DTD - The document type definition for XML. You can find an RPM or DEB package or you can download a zip file from the site linked from here. -
- XSL +
+ XSL Stylesheets (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon NWalsh's chunk.xsl. -
-
xsltproc- The processor that ++ xsltproc - The processor that will take an XML document and, given a xsl stylesheet, convert it to HTML. It needs libxml2 and libxslt (available in RPM and - DEB formats or from xmlsoft.org. -
+ DEB formats or from xmlsoft.org. +
Some editing tool. A popular one is Emacs with the psgml and nXML - modes. The LDP Author - Guide and DocBook + modes. The LDP Author + Guide and DocBook Wiki list some alternates. -
After you have the tools mentioned above, you need to define a title for your document. Then start thinking about the possible sections and subsections you will have in your document. Make @@ -682,200 +682,200 @@ please e-mail the gatekeeper in charge of documentation.
You can look at some templates for documents (in Docbook XML) in - the sources + the sources for acs-core-docs, especially the Detailed Design Documentation Template and the System/Application Requirements Template. -
- The documentation for each package will make up a little "book" that is structured like this +
+ The documentation for each package will make up a little "book" that is structured like this - examples are emphasized: - +
- book : Docs for one package - templating + book : Docs for one package - templating | - +--chapter : One section - for developers + +--chapter : One section - for developers | ---------+------------------------------------------------------ | - +--sect1 : Single document - requirements + +--sect1 : Single document - requirements | - +--sect2 : Sections - functional requirements + +--sect2 : Sections - functional requirements | - +--sect3 : Subsections - Programmer's API + +--sect3 : Subsections - Programmer's API | - ... : ... + ... : ...The actual content is split up into documents that start at a -
sect1-level. These are then tied together in a top-level document that + sect1-level. These are then tied together in a top-level document that contains all the information above the line. This will be explained in more detail in a later document, and we will provide a set of templates for documenting an entire package.For now you can take a look at the - sources of these DocBook documents + sources of these DocBook documents to get an idea of how they are tied together. -
- - Given that your job starts at the
sect1-level, all your documents should open with a -<sect1>-tag and end - with the corresponding</sect1>. ++ + Given that your job starts at the sect1-level, all your documents should open with a + <sect1>-tag and end + with the corresponding </sect1>.
- - You need to feed every
<sect1>two attributes. The first attribute, -id, is standard and can be used with all elements. It comes in very - handy when interlinking between documents (more about this when talking about links in the section called “Links”). - The value ofidhas to be unique - throughout the book you're making since theid's in your -sect1's will turn into filenames when the book is parsed into HTML. + + You need to feed every <sect1> two attributes. The first attribute, + id, is standard and can be used with all elements. It comes in very + handy when interlinking between documents (more about this when talking about links in Section , “Links”). + The value of id has to be unique + throughout the book you're making since the id's in your + sect1's will turn into filenames when the book is parsed into HTML.- - The other attribute is
xreflabel. The value of this is the text that will appear - as the link when referring to thissect1. + + The other attribute is xreflabel. The value of this is the text that will appear + as the link when referring to this sect1.Right after the opening tag you put the title of the document - this is usually the same as -
xreflabel-attribute. E.g. the top level of the document you're + xreflabel-attribute. E.g. the top level of the document you're reading right now looks like this:-<sect1 id="docbook-primer" xreflabel="DocBook Primer"> +<sect1 id="docbook-primer" xreflabel="DocBook Primer"> <title>DocBook Primer</title> ... </sect1>- + Inside this container your document will be split up into -
<sect2>'s, - each with the same requirements -idandxreflabel- attributes, and a<title>-tag inside. Actually, thexreflabelis never required in sections, but it makes linking to that section a lot easier. + <sect2>'s, + each with the same requirements - id and xreflabel + attributes, and a <title>-tag inside. Actually, the xreflabel is never required in sections, but it makes linking to that section a lot easier.When it comes to naming your -
sect2's and below, prefix them with some abbreviation of theidin thesect1such asrequirements-overview. -- + sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview. +
+ For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we use -
<computeroutput>- and<code>+ <computeroutput> + and <code><code></code> tags. - These replace the HTML-tag<code>tag, + These replace the HTML-tag <code><code></code> tag, depending on whether the tag is describing computer output or computer code.For bigger chunks of code such as SQL-blocks, the tag -
<programlisting>is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of + <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.For expressing user interaction via a terminal window, we wrap - the
<screen>- tag around text that has been wrapped by combinations of<computeroutput>- and<userinput>-- + the <screen> + tag around text that has been wrapped by combinations of <computeroutput> + and <userinput> +
+ Linking falls into two different categories: inside the book you're making and outside: -
- 1. Inside linking, cross-referencing other parts of your book
- By having unique
id's you can cross-reference any part of your book +
- 1. Inside linking, cross-referencing other parts of your book
+ By having unique id's you can cross-reference any part of your book with a simple tag, regardless of where that part is. -
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
+Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
- Find information about creating a package in -<xref linkend="packages-making-a-package"></xref>. +<xref linkend="packages-making-a-package"></xref>.And the output is:
- Find information about creating a package in -Making a Package. +Making a Package.Note that even though this is an empty tag, you have to either: -
- Provide the end-tag,
</xref>, or -- Put a slash before the ending-bracket:
<xref linkend="blahblah"/>-If the section you link to hasn't a specified
xreflabel-attribute, +
+ Provide the end-tag, </xref>, or +
+ Put a slash before the ending-bracket: <xref linkend="blahblah"/> +
If the section you link to hasn't a specified xreflabel-attribute, the link is going to look like this:
Put this in your XML:
-Find information about what a package looks like in -<xref linkend="packages-looks"></xref>. +<xref linkend="packages-looks"></xref>.And the output is:
- Find information about what a package looks like in -the section called “What a Package Looks Like”. +Section , “What a Package Looks Like”.- Note that since I haven't provided an
xreflabelfor the subsection, -packages-looks, the + Note that since I haven't provided an xreflabel for the subsection, + packages-looks, the parser will try its best to explain where the link takes you. -- 2. Linking outside the documentation
- 2. Linking outside the documentation
+ If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different - (
<ulink>): + (<ulink>): -<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>+
<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>....will create a hyper-link to Oracle in the HTML-version of the documentation. -
NOTE: Do NOT use +
NOTE: Do NOT use ampersands in your hyperlinks. These are reserved for - referencing entities. - To create an ampersand, use the entity
&+ referencing entities. + To create an ampersand, use the entity <code>&</code> -- Note: The graphics guidelines + Note: The graphics guidelines are not written in stone. Use another valid approach if it works better for you.
- + To insert a graphic we use the elements -
<mediaobject>, -<imageobject>, -<imagedata>, + <mediaobject>, + <imageobject>, + <imagedata>, and -<textobject>. + <textobject>. Two versions of all graphics are required. One for the Web (usually a JPEG or GIF), and a brief text description. The description becomes the ALT text. You can also supply a version for print (EPS).<mediaobject> <imageobject> - <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/> + <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/> </imageobject> <imageobject> - <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/> + <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/> </imageobject> <textobject> <phrase>This is an image of the flow in the Request Processor</phrase> </textobject> </mediaobject>- Put your graphics in a separate directory ("images") and link to them + Put your graphics in a separate directory ("images") and link to them only with relative paths. -
+ Here's how you make the DocBook equivalent of the three usual HTML-lists: -
- 1. How to make an <ul>
- Making an unordered list is pretty much like doing the same thing in HTML - if you close your
<li>, that is. The only differences are that each list item has to be wrapped in something more, such as -<para>, and that the tags are called -<itemizedlist>+
- 1. How to make an <ul>
+ Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as + <para>, and that the tags are called + <itemizedlist> and -
<listitem>: + <listitem>:<itemizedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -- 2. How to make an <ol>
+
- 2. How to make an <ol>
The ordered list is like the preceding, except that you use -
<orderedlist>instead:+ <orderedlist> instead:<orderedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </orderedlist> -- 3. How to make a <dl>
- This kind of list is called a
variablelistand these are the tags you'll need to +- 3. How to make a <dl>
+ This kind of list is called a variablelist and these are the tags you'll need to make it happen: -
<variablelist>, -<varlistentry>, -<term>and -<listitem>:+ <variablelist>, + <varlistentry>, + <term> and + <listitem>:<variablelist> <varlistentry> @@ -889,14 +889,14 @@ </varlistentry> </variablelist> -+ DocBook supports several types of tables, but in most cases, the -
<informaltable>+ <informaltable> is enough:-<informaltable frame="all"> - <tgroup cols="3"> +<informaltable frame="all"> + <tgroup cols="3"> <tbody> <row> @@ -924,26 +924,26 @@ With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table:
a1 b1 c1 a2 b2 c2 a3 b3 c3 If you want cells to span more than one row or column, it gets a bit more complicated - check out -
<table>+ <table> for an example. -+ Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - -
<emphasis>. + <emphasis>.- The
<emphasis>tag defaults to italics when parsed. If you're looking for - emphasizing with bold type, use<emphasis role="strong">. -+ The <emphasis> tag defaults to italics when parsed. If you're looking for + emphasizing with bold type, use <emphasis role="strong">. +
Words that are marked as index-words are referenced in an index in the final, parsed document.
Use -
<indexterm>, -<primary>and -<secondary>+ <indexterm>, + <primary> and + <secondary> for this. See these links for an explanation. -Note
This section is quoted almost verbatim from the LDP Author Guide.
- Once you have the Docbook Tools +
Note
This section is quoted almost verbatim from the LDP Author Guide.
+ Once you have the Docbook Tools installed, you can convert your xml documents to HTML or other formats.
@@ -955,52 +955,52 @@ To generate a single HTML file from your DocBook XML file, use the command:
-bash$xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml-Note
- This example uses Daniel Veillard's xsltproc command available - as part of libxslt from http://www.xmlsoft.org/XSLT/. +bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml +
Note
+ This example uses Daniel Veillard's xsltproc command available + as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately.
To generate a set of linked HTML pages, with a separate page for each <chapter>, <sect1> or <appendix> tag, use the following command:
-bash$xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml+bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml- You could also look at the acs-core-docs Makefile + You could also look at the acs-core-docs Makefile for examples of how these documents are generated. -
- The LDP Author +
+ The LDP Author Guide has a lot of good information, a table of - docbook elements and their "look" in HTML and lots of good links + docbook elements and their "look" in HTML and lots of good links for tools. -
+
James Clark - wrote nXML Mode, an alternative + wrote nXML Mode, an alternative to PSGML Mode. nXML Mode can validate a file as it is edited. -
+
David Lutterkort - wrote an intro to the PSGML Mode in Emacs -
+ wrote an intro to the PSGML Mode in Emacs +
James Clark's free Java parser - XP. Note that + XP. Note that this does not validate XML, only parses it. -
+ DocBook Tool for Linux: Converts docbook documents to a number of formats. NOTE: I only got these to work with Docbook SGML, NOT with Docbook XML. If you are able to make it work with our XML, please let us know. -
- AptConvert from PIXware is a Java editor that will produce +
+ AptConvert from PIXware is a Java editor that will produce DocBook documents and let you transform them into HTML and PDF for a local preview before you submit. -
+
In the process of transforming your HTML into XML, - HTML tidy - can be a handy tool to make your HTML "regexp'able". + HTML tidy + can be a handy tool to make your HTML "regexp'able". Brandoch Calef has made a - Perl + Perl script with directions (now via archive.org) that gets you most of the way. -
View comments on this page at openacs.org +View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v diff -u -r1.42.2.2 -r1.42.2.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 6 Jul 2009 11:14:26 -0000 1.42.2.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 11 Sep 2009 23:41:26 -0000 1.42.2.3 @@ -1,34 +1,34 @@ - -Constraint naming standard By Michael Bryzek
+ +Constraint naming standard Constraint naming standard is important for one reason: The SYS_* name oracle assigns to unnamed constraints is not very understandable. By correctly naming all contraints, we can quickly associate a particular constraint with our data model. This gives us two real advantages: -
We can quickly identify and fix any errors.
We can reliabily modify or drop constraints
+
We can quickly identify and fix any errors.
We can reliabily modify or drop constraints
Why do we need a naming convention?-Oracle limits names, +Oracle limits names, in general, to 30 characters, which is hardly enough for a human readable constraint name. -
We propose the following naming convention for all constraints, with the following abbreviations taken from Oracle Docs at - + http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953. Note that we shortened all of the constraint abbrevations to two characters to save room. -
Constraint type Abbreviation references (foreign key) fk unique un primary key pk check ck not null nn +
Constraint type Abbreviation references (foreign key) fk unique un primary key pk check ck not null nn <table name>_<column_name>_<constraint abbreviation>
In reality, this won't be possible because of the character limitation on names inside oracle. When the name is too long, we will follow these two steps in order: -
Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). -
Truncate the column name until it fits.
+
Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). +
Truncate the column name until it fits.
If the constraint name is still too long, you should consider rewriting your entire data model :) -
Notes:
If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints
If you are defining a multi column constraint, try to truncate the two column names evenly
+Notes:
If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints
If you are defining a multi column constraint, try to truncate the two column names evenly
create table example_topics ( topic_id integer constraint example_topics_topic_id_pk @@ -52,7 +52,7 @@ constraint cne_example_id_one_line_unq unique(example_id, one_line_description) ); -Naming primary keys might not have any obvious advantages. However, here's an example where naming the primary key really helps (and this is by no means a rare case! @@ -71,18 +71,18 @@ 3 1 INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI QUE)
-Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace +Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace and know exactly which table oracle is using at each step? -
People disagree on whether or not we should be naming not null constraints. So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not a requirement.
About Naming the not null constraints
-Though naming "not null" constraints doesn't help immeditately in error +Though naming "not null" constraints doesn't help immeditately in error debugging (e.g. the error will say something like -"Cannot insert null value into column"), we recommend naming not null +"Cannot insert null value into column"), we recommend naming not null constraints to be consistent in our naming of all constraints.
($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -r1.42.2.2 -r1.42.2.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 6 Jul 2009 11:14:26 -0000 1.42.2.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 11 Sep 2009 23:41:26 -0000 1.42.2.3 @@ -1,83 +1,83 @@ - -ACS File Naming and Formatting Standards By Michael Yoon and Aurelius Prochazka
+ +ACS File Naming and Formatting Standards To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -
+
Usually we organize our files so that they mainly serve one of the following three purposes: -
displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code +
displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code Essentially, we want our files named in a fashion that reflects their purpose.
-Under the page root (and the template root if using the Style package): -
For naming files that enable a specific action on an object, use this format:
-
object-verb.extension+Under the page root (and the template root if using the Style package): +
For naming files that enable a specific action on an object, use this format:
+object-verb.extension
For example, the page to erase a user's portrait from the database is -
/admin/users/portrait-erase.tcl. -However, modules typically deal with only one primary type of object - +/admin/users/portrait-erase.tcl. +
However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages -for the Bookmarks module live in the
/bookmarks/-directory, and so there is no need to name the bookmark editing page with a redundant url:/bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention: +for the Bookmarks module live in the /bookmarks/ +directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention:-
verb.extension+verb.extension-Thus, the page to edit a bookmark is
/bookmarks/edit.tcl. -For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
-
one.extension+Thus, the page to edit a bookmark is /bookmarks/edit.tcl. +For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
+one.extension
For example, the page to view one bookmark is -
/bookmarks/one.tcl. Note that no verb is necessary for display-type files. -Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
-
object.extension+/bookmarks/one.tcl. Note that no verb is necessary for display-type files. +Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
+object.extension
For example, the page to view the properties of an ecommerce product is -
/ecommerce/product.tcl. -For naming files in a page flow, use the convention:
foobar.extension(Step 1)
foobar-2.extension(Step 2)...
foobar-N.extension(Step N)-where
foobaris determined by the above +/ecommerce/product.tcl. +For naming files in a page flow, use the convention:
foobar.extension (Step 1)
foobar-2.extension (Step 2)
...
foobar-N.extension (Step N)
+where foobar is determined by the above rules.
Typically, we use a three-step page flow when taking user information: -
Present a form to the user
Present a confirmation page to the user
Perform the database transaction, then redirect
Put data model files in
/www/doc/sql, and name them +
Present a form to the user
Present a confirmation page to the user
Perform the database transaction, then redirect
Put data model files in /www/doc/sql, and name them for the modules towards which they are used:
-
module.sql+module.sqlIn the Tcl library directory: -
For files that contain module-specific procedures, use the +
For files that contain module-specific procedures, use the convention:
-
module-procs.tcl-For files that contain procedures that are part of the core ACS, +module-procs.tcl +
For files that contain procedures that are part of the core ACS, use the convention:
-
ad-description-procs.tcl-File names also appear within pages, as linked URLs and -form targets. When they do, always use abstract -URLs (e.g.,
user-deleteinstead of -user-delete.tcl), because they enhance maintainability. +form targets. When they do, always use abstract +URLs (e.g., user-delete instead of +user-delete.tcl), because they enhance maintainability.Similarly, when linking to the index page of a directory, do not -explicitly name the index file (
index.tcl, -index.adp,index.html, etc.). Instead, use +explicitly name the index file (index.tcl, +index.adp, index.html, etc.). Instead, use just the directory name, for both relative links -(subdir/) and absolute links -(/top-level-dir/). If linking to the directory in which -the page is located, use the empty string (""), which +(subdir/) and absolute links +(/top-level-dir/). If linking to the directory in which +the page is located, use the empty string (""), which browsers will resolve correctly. -Include the appropriate standard header in all scripts. The first line should be a comment specifying the file path relative to the ACS root directory. e.g. -
+# /www/index.tcl -
+
or -
+# /tcl/module-defs.tcl -
+
For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g.
@@ -95,7 +95,7 @@ This can be at the top or bottom of the file.Using ad_page_contractFor non-library Tcl files (those not in the private Tcl directory), -use
ad_page_contract+use ad_page_contract after the file path comment (this supersedes set_the_usual_form_variables and ad_return_complaint). Here is an example of using ad_page_contract, which serves both documentation and page input @@ -119,32 +119,32 @@ {persistent_cookie_p f} }-Salient features of
ad_page_contract: -
A mandatory documentation string is the first argument. This has -the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.
The second argument specifies the page +Salient features of ad_page_contract: +
A mandatory documentation string is the first argument. This has +the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.
The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags separated by commas (,), -e.g.
foo:integer,multiple,trim. In particular,multipleand -arrayare the flags that correspond to the old -ad_page_variablesflags.There are new flags:
trim,notnulland -optional. They do what you'd expect; values will not be +e.g. foo:integer,multiple,trim. In particular, multiple and +array are the flags that correspond to the old +ad_page_variables flags.There are new flags: trim, notnull and +optional. They do what you'd expect; values will not be trimmed, unless you mark them for it; empty strings are valid input, unless you specify notnull; and a specified variable will be considered required, -unless you declare it optional.
ad_page_contractcan do validation for you: the flagsinteger-andsql_identifierwill make sure that the values -supplied are integers/sql_identifiers. Theintegerflag +unless you declare it optional.ad_page_contract can do validation for you: the flags integer +and sql_identifier will make sure that the values +supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. Note that unless you specify -
notnull, both will accept the empty string. -Note that
ad_page_contractdoes not generate +notnull, both will accept the empty string. +Note that ad_page_contract does not generate QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete.
Using ad_library-For shared Tcl library files, use
ad_libraryafter +For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like -ad_page_contract. Don't forget to put the @cvs-id in +ad_page_contract. Don't forget to put the @cvs-id in there. Here is an example of using ad_library:# tcl/wp-defs.tcl @@ -165,56 +165,56 @@ -- author -- created -- --- $Id$ +-- $Id$-Of course, replace "
--" with the comment delimiter +Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming. -Construct the page as one Tcl variable (name it -
page_content), and then send it back to the browser with -one call todoc_return, which will call +page_content), and then send it back to the browser with +one call to doc_return, which will call db_release_unused_handles prior to executing ns_return, effectively combining the two operations.For example:
-set page_content "[ad_header "Page Title"] +set page_content "[ad_header "Page Title"] <h2>Page Title</h2> <hr> <ul> -" +" db_foreach get_row_info { select row_information from bar } { - append page_content "<li>row_information\n" + append page_content "<li>row_information\n" } -append page_content "</ul> +append page_content "</ul> -[ad_footer]" +[ad_footer]" doc_return 200 text/html $page_content-The old convention was to call
ReturnHeadersand -thenns_writefor each distinct chunk of the page. This +The old convention was to call ReturnHeaders and +then ns_write for each distinct chunk of the page. This approach has the disadvantage of tying up a scarce and valuable resource (namely, a database handle) for an unpredictable amount of time while sending packets back to the browser, and so it should be avoided in most cases. (On the other hand, for a page that requires an expensive database query, it's better to call -ad_return_top_of_page+ad_return_top_of_page first, so that the user is not left to stare at an empty page while the query is running.)Local procedures (i.e., procedures defined and used only within one -page) should be prefixed with "
module_" and +page) should be prefixed with "module_" and should be used rarely, only when they are exceedingly useful.All files that prepare HTML to display should end with [ad_footer] or @@ -225,7 +225,7 @@ edit ad_header (which quite possibly can start a <table>) and ad_footer (which may need to end the table started in ad_footer) to customize the look and feel of the entire site. -
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v diff -u -r1.43.2.2 -r1.43.2.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 6 Jul 2009 11:14:26 -0000 1.43.2.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 11 Sep 2009 23:41:26 -0000 1.43.2.3 @@ -1,5 +1,5 @@ - -PL/SQL Standards + +
PL/SQL Standards By Richard Li and Yon Feldman
OpenACS docs are written by the named authors, and may be edited @@ -11,25 +11,25 @@ our product will be useful long after the current people building and maintaining it are around. Following are some standards and guidelines that will help us achieve this goal: -
+
All PL/SQL code must be well documented. We must write code that is maintainable by others, this is especially true in our case because we are building an open source toolkit than anyone can download and browse the source code. So document like you are - trying to impress your "Introduction to Programming" professor or + trying to impress your "Introduction to Programming" professor or TA. -
+
It is important to be consistent throughout an application as much as is possible given the nature of team development. This means carrying style and other conventions suchs as naming within an application, not just within one file. -
Encapsulation of related fuctionality is key to maintainability and upgradeability of our software. Try to bundle your code into - packages + packages whenever possible. This will make upgrading, bug fixing, and customizing, among other things, a possibility. -
+
When creating functions or procedures use the following template, it demonstrates most of the guidelines set forth in this document that correspond to functions and procedures: @@ -53,32 +53,32 @@ / show errors -
- Always use
create or replace procedure|function - <proc_or_func_name>. It makes reloading packages much ++ Always use create or replace procedure|function + <proc_or_func_name>. It makes reloading packages much easier and painless to someone who is upgrading or fixing a bug. -
- Always qualify
endstatements, i.e., the -endstatement for a package should beend - <package_name>;, not justend;; same ++ Always qualify end statements, i.e., the + end statement for a package should be end + <package_name>;, not just end;; same goes for procedures, functions, package bodies, and triggers. -
- Always use the "show errors" SQL*Plus command after each PL/SQL +
+ Always use the "show errors" SQL*Plus command after each PL/SQL block. It will help you debug when there are compilation errors in your PL/SQL code. -
+
Name parameters as simply as possible, i.e., use the column name if the parameter corresponds to a table column. We're deprecating the v_* and *_in syntax in favor of named parameters notation:
-+ acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.) -+ instead of -+ acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.) -+To achieve this we must fully qualify arguements passed into @@ -107,23 +107,23 @@ / show errors -
- Explicitly designate each parameter as "in," "out," or "inout." -
+
+ Explicitly designate each parameter as "in," "out," or "inout." +
Each parameter should be on its own line, with a tab after the parameter name, then in/out/inout, then a space, and finally the datatype. -
+
Use %TYPE and %ROWTYPE whenever possible. -
- Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype +
+ Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype because it can't be used in SQL queries. -
- All
newfunctions (e.g.,acs_object.new, - party.new,etc.) should optionally accept an ID: ++ All new functions (e.g., acs_object.new, + party.new, etc.) should optionally accept an ID:
-+ create or replace package acs_object as function new ( @@ -134,22 +134,22 @@ creation_ip in acs_objects.creation_ip%TYPE default null, context_id in acs_objects.context_id%TYPE default null ) return acs_objects.object_id%TYPE; -+- takes the optional argument
object_id. Do this to + takes the optional argument object_id. Do this to allow people to use the same API call when they are doing double click protection, that is, tehy have already gotten an -object_idand now they want to create the object with - thatobject_id. -Some general style guidelines to follow for the purpose of consistency across applications. -
+
Standard indentation is 4 spaces. Our PL/SQL code is not only viewable in the SQL files but also through our SQL and PL/SQL browsers. This means that we should try to make it as consistent as possible to all source code readers. -
+
Lowercase everything, with the exception of %TYPE and %ROWTYPE.
($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -r1.45.2.2 -r1.45.2.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 6 Jul 2009 11:14:26 -0000 1.45.2.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 11 Sep 2009 23:41:26 -0000 1.45.2.3 @@ -1,14 +1,16 @@ - -Release Version Numbering ($Id$)By Ron Henderson, Revised by Joel Aufrecht
+ +Release Version Numbering OpenACS version numbers help identify at a high-level what is in a particular release and what has changed since the last release. -
A "version number" is really just a string of the form: -
major.minor.dot[ milestone ]
A major number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.
A minor change represents the addition of new functionality or changed UI.
A dot holds only bug fixes and security patches. Dot releases are always recommended and safe. -
A milestone marker indicates the state of the release:
d, for development, means the release is in active development and is not in its intended released form.
a, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.
b, for beta, means most severe bugs are fixed and end users can start trying the release.
Release Candidate builds (rc) are believed to meet all of the criteria for release and can be installed on test instances of production systems.
Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.) +
A "version number" is really just a string of the form: +
major.minor.dot[ milestone ]
A major number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.
A minor change represents the addition of new functionality or changed UI.
A dot holds only bug fixes and security patches. Dot releases are always recommended and safe. +
A milestone marker indicates the state of the release:
d, for development, means the release is in active development and is not in its intended released form.
a, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.
b, for beta, means most severe bugs are fixed and end users can start trying the release.
Release Candidate builds (rc) are believed to meet all of the criteria for release and can be installed on test instances of production systems.
Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.)
Milestone markers are numbered: d1, d2, ..., a1, b1, rc1, etc.
A complete sequence of milestones between two releases:
5.0.0 5.0.0rc2 5.0.0rc1 @@ -22,7 +24,7 @@ Version numbers are also recorded in the CVS repository so that the code tree can be restored to the exact state it was in for a particular release. To translate between a distribution tar file -(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire release history of the toolkit is recorded in the tags for the top-levelreadme.txtfile: +(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire release history of the toolkit is recorded in the tags for the top-level readme.txt file:> cvs log readme.txt RCS file: /usr/local/cvsroot/acs/readme.txt,v @@ -58,10 +60,10 @@In the future, OpenACS packages should follow this same convention on version numbers. -
So what distinguishes an alpha release from a beta +
So what distinguishes an alpha release from a beta release? Or from a production release? We follow a specific set of rules for how OpenACS makes the transition from one state of maturity to -the next. These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria
+the next. These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria
Each package has a maturity level. Maturity level is recorded in the .info file for each major-minor release of OpenACS, and is set to the appropriate value for that release of the package.
@@ -71,24 +73,24 @@ <maturity>1</maturity> <callbacks> ... -
- Level -1: Incompatible. This package is not supported for this platform and should not be expected to work. -
- Level 0: New Submission. This is the default for packages that do not have maturity explicitly set, +
+ Level -1: Incompatible. This package is not supported for this platform and should not be expected to work. +
+ Level 0: New Submission. This is the default for packages that do not have maturity explicitly set, and for new contributions. The only criterion for level 0 is that at least one person asserts that it works on a given platform. -
- Level 1: Immature. Has no open priority 1 or priority 2 bugs. Has been installed by at least +
+ Level 1: Immature. Has no open priority 1 or priority 2 bugs. Has been installed by at least 10? different people, including 1 core developer. Has been available in a stable release for at least 1 month. Has API documentation. -
- Level 2: Mature. Same as Level 1, plus has install guide and user documentation; +
+ Level 2: Mature. Same as Level 1, plus has install guide and user documentation; no serious deviations from general coding practices; no namespace conflicts with existing level 2 packages. -
- Level 3: Mature and Standard. Same as level 2, plus meets published coding standards; +
+ Level 3: Mature and Standard. Same as level 2, plus meets published coding standards; is fully internationalized; available on both supported databases. -
Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.
Upgrade scripts should be named
/packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sqlIf the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in
/packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. -If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use
upgrade-2.0.1d3-2.0.1d4.sql.Database upgrades should be confined to development releases, not alpha or beta releases.
- Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.
Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.
The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in -acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use
upgrade-5.1.0d1-5.1.0d2.sql+Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.
Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql
If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. +
If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use upgrade-2.0.1d3-2.0.1d4.sql.
Database upgrades should be confined to development releases, not alpha or beta releases.
+ Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.
Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.
The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in +acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -r1.26.2.1 -r1.26.2.2 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 10 Jun 2009 22:24:07 -0000 1.26.2.1 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 11 Sep 2009 23:41:26 -0000 1.26.2.2 @@ -1,4 +1,4 @@ - -Chapter 11. Engineering Standards Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -r1.34.2.2 -r1.34.2.3 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 6 Jul 2009 11:14:26 -0000 1.34.2.2 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 11 Sep 2009 23:41:26 -0000 1.34.2.3 @@ -1,5 +1,5 @@ - -External Authentication Requirements People have plenty of usernames and passwords already, we + +
External Authentication Requirements People have plenty of usernames and passwords already, we don't want them to have yet another. We want people to be able to log in to OpenACS with the same password they use to log in to any other system.
Besides, administrators have better things to do than create @@ -8,47 +8,47 @@ log on to OpenACS, an account will automatically be created for them here.
Finally, security is increased with fewer passwords, since users generally can't remember all those passwords, so they tend to -keep them all the same and never change them.
Transparent: Users don't have to do anything special to +keep them all the same and never change them.
Transparent: Users don't have to do anything special to get an account on the local OpenACS system, if they already have an - account on the external authentication server.
Fall-back: Users who don't have an account on the + account on the external authentication server.
Fall-back: Users who don't have an account on the external authentication server are still allowed to create a local account on OpenACS. This could be for external students who should have access to .LRN, but not to the rest of the university's - resources.
Authentication Client Only: We want OpenACS to be able to + resources.
Authentication Client Only: We want OpenACS to be able to authenticate by asking some remote authority to verify the user's username/password combination. The goal is explicitly not (at this point) to have OpenACS act as an authentication server for other systems, although this could be easily added later. The goal is also not to devise an infrastructure for letting OpenACS access resources in various other systems on the user's behalf, such as IMAP, iCalendar, SMB file servers, etc., although this is - definitely an interesting use-case.
Easy configuration: We would like people to be able to + definitely an interesting use-case.
Easy configuration: We would like people to be able to configure this without having to write code. In particular, we want to build drivers that know how to talk with LDAP, RADIUS, PAM, etc., and which won't have to be locally modified. Only configuration and policies should change, code should - not.
Usability: The solution must be easy to use for end users + not.
Usability: The solution must be easy to use for end users and administrators alike. There's frequently a positive feedback effect between usability and security, because when authentication schemes have poor usability, users will think up ways to circumvent - them.
Open and modular: The design should be on the one hand + them.
Open and modular: The design should be on the one hand open to add other authentification mechanisms when needed and on the other hand very modular to enable a start with minimal requirements (driver implementations) as soon as possible.
The problem can be split into several logically separate -parts. Each has a section below.
Authority: The name of an authority trusted to authenticate - users.
Authentication Driver: An implementation of the +parts. Each has a section below.
Authority: The name of an authority trusted to authenticate + users.
Authentication Driver: An implementation of the authentication service contract, which talks to an authentication of a certain type, e.g. PAM, RADIUS, LDAP, or Active - Directory.
Authentication API: The API through which login pages and + Directory.
Authentication API: The API through which login pages and applications talk to the authentication service. There's one and only one implementation of the authentication API, namly the one - included in OpenACS Core.
Authentication Driver API: The service contract which - authentication drivers implement.
Authentication:
-
Account Management (NO PICTURE YET)
Batch Synchronization (NO PICTURE YET)
Feature Status Description New API EXT-AUTH-01 A Extend Authentication/Acct Status API EXT-AUTH-03 A Account Creation API EXT-AUTH-05 A Password Management API EXT-AUTH-30 A Authority Management API
Feature Status Description Login EXT-AUTH-04 A Rewrite login, register, and admin pages to use APIs EXT-AUTH-38 A ad_form complain feature EXT-AUTH-19 A Rewrite password recovery to use API EXT-AUTH-21 A Rewrite email verification with API EXT-AUTH-28 A Username is email switch Users will log in using a username, a authority, and a + included in OpenACS Core.
Authentication Driver API: The service contract which + authentication drivers implement.
Authentication:
Account Management (NO PICTURE YET)
Batch Synchronization (NO PICTURE YET)
Feature Status Description New API EXT-AUTH-01 A Extend Authentication/Acct Status API EXT-AUTH-03 A Account Creation API EXT-AUTH-05 A Password Management API EXT-AUTH-30 A Authority Management API
Feature Status Description Login EXT-AUTH-04 A Rewrite login, register, and admin pages to use APIs EXT-AUTH-38 A ad_form complain feature EXT-AUTH-19 A Rewrite password recovery to use API EXT-AUTH-21 A Rewrite email verification with API EXT-AUTH-28 A Username is email switch Users will log in using a username, a authority, and a password. The authority is the source for user/password verification. OpenACS can be an authority itself.
Each user in OpenACS will belong to exactly one authority, which -can either be the "local" OpenACS users table, in which case the +can either be the "local" OpenACS users table, in which case the password column is used, or it can be some external authority, which will be communicated with using some protocol, as implemented by an authentication driver.
Username will be separate from email address. It can be an @@ -71,11 +71,11 @@ [Forgot my password] [New user registration]
If there's only one active authority, we don't display the -authority drop-down element at all.
Feature Status Description Configuration EXT-AUTH-07 A Admin pages to control Ext-Auth parameters The site-wide systems administrator can configure the -authentication process from a page linked under /acs-admin.
Authorities - ordered list of authorities defined
Account Registration Allowed: Yes/No. Account - registration can be disabled altogether.
Registration authority - the authority in which accounts should +authority drop-down element at all.
Feature Status Description Configuration EXT-AUTH-07 A Admin pages to control Ext-Auth parameters The site-wide systems administrator can configure the +authentication process from a page linked under /acs-admin.
Authorities - ordered list of authorities defined
Account Registration Allowed: Yes/No. Account + registration can be disabled altogether.
Registration authority - the authority in which accounts should be created, using the relevant driver, if account registration is - allowed.
Username is email? - instead of asking for username, + allowed.
Username is email? - instead of asking for username, we'll ask for email. And we'll store the value in both columns, username and email. This is a setting that spans all authorities, and is primarily meant for backwards compatibility with the old OpenACS @@ -84,42 +84,42 @@ other drivers call external functions. The possible functions for each authority are split into several drivers for convenience. One driver handles authentication, one account creation, and one - changing passwords.
Feature Status Description create service contract EXT-AUTH-16 A Create service contract for Authentication EXT-AUTH-17 A Create service contract for Acct. Creation EXT-AUTH-29 A Create service contract for Passwd Management
Feature Status Description EXT-AUTH-18 A Authority configuration data model Each authority is defined like this:
Authority pretty-name, e.g. "URZ"
Authentication Driver, e.g. "RADIUS". In practice, this + changing passwords.
Feature Status Description create service contract EXT-AUTH-16 A Create service contract for Authentication EXT-AUTH-17 A Create service contract for Acct. Creation EXT-AUTH-29 A Create service contract for Passwd Management
Feature Status Description EXT-AUTH-18 A Authority configuration data model Each authority is defined like this:
Authority pretty-name, e.g. "URZ"
Authentication Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract - implementation.
Authentication Driver configuration settings, e.g. host + implementation.
Authentication Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is per authority, not per driver, i.e., you can have multiple authorities with the same driver but different configuration - options.
AuthenticationAllowed - true/false, so you can disable + options.
AuthenticationAllowed - true/false, so you can disable login through some authority without having to delete the authority, and - hence also all the users who belong to that authority.
ForgottenPasswordUrl - a URL to redirect to instead of + hence also all the users who belong to that authority.
ForgottenPasswordUrl - a URL to redirect to instead of trying to use the authentication driver's password management - features.
ChangePasswordUrl - a URL to redirect to instead of + features.
ChangePasswordUrl - a URL to redirect to instead of trying to use the authentication driver's password management - features.
Account Creation Driver, e.g. "RADIUS". In practice, this + features.
Account Creation Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract implementation. The reason we have separate drivers for authentication and account creation is that organizations are likely to have a home-grown - account registration process.
Account Creation Driver configuration settings, e.g. host + account registration process.
Account Creation Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is per authority, not per driver, i.e., you can have multiple authorities with the same driver but different configuration - options.
RegistrationUrl - instead of registering using OpenACS, - redirect to a certain URL site for account registration.
RegistrationAllowed - true/false, so you can disable - registration using this account.
Sort order: Preference order of - authorities.
HelpContactText: Text or HTML to be displayed + options.
RegistrationUrl - instead of registering using OpenACS, + redirect to a certain URL site for account registration.
RegistrationAllowed - true/false, so you can disable + registration using this account.
Sort order: Preference order of + authorities.
HelpContactText: Text or HTML to be displayed when user has trouble authenticating with the authority. Should include contact information such as a phone number or email.
Each authority driver will have a set of configuration options dependent on the driver, such as host, port, etc. We will need to find a mechanism for the driver to tell us which configuration options are available, a way to set these, and a way for the driver to access these settings.
OpenACS will come pre-configured with one authority, which is -the "local" authority, meaning we'll authenticate as normal using the +the "local" authority, meaning we'll authenticate as normal using the local users table. This will, just like any other authority, be -implemetned using a service contract.
Feature Status Description Synchronizing and linking users EXT-AUTH-28 A Create service contract for Batch Sync. EXT-AUTH-38 A Batch User Synchronization API EXT-AUTH-38 A IMS Synchronization driver EXT-AUTH-08 A Automation of batch Synchronization EXT-AUTH-15 B On-demand syncronization Regardless of the login method, the user needs to have a row +implemetned using a service contract.
Feature Status Description Synchronizing and linking users EXT-AUTH-28 A Create service contract for Batch Sync. EXT-AUTH-38 A Batch User Synchronization API EXT-AUTH-38 A IMS Synchronization driver EXT-AUTH-08 A Automation of batch Synchronization EXT-AUTH-15 B On-demand syncronization Regardless of the login method, the user needs to have a row in the OpenACS users table. This can happen through a batch job, in -real-time, or both in combination. We use the IMS Enterprise 1.1 specification.
Batch job means that we do a synchronization (import new +real-time, or both in combination. We use the IMS Enterprise 1.1 specification.
Batch job means that we do a synchronization (import new users, modify changed, purge deleted) on a regular interval, e.g. every night. You can also decide to have a monthly full synchronization, plus daily incremental ones. That's up to you. The @@ -130,23 +130,23 @@ be remedied by using the real-time solution. The batch job will also require error logging and an admin interface to view logs.
If an email already belongs to some other user, we log it as an error.
A user will always belong to exactly one authority, which can be -either the "local" authority or some other. Thus, the OpenACS user's -table will have to be augmented with the following columns:
Authority. Reference to the site-wide authorities list. The - authority which can authenticate this user.
Authority-specific username.
Real-time means that the first time the user logs into +either the "local" authority or some other. Thus, the OpenACS user's +table will have to be augmented with the following columns:
Authority. Reference to the site-wide authorities list. The + authority which can authenticate this user.
Authority-specific username.
Real-time means that the first time the user logs into OpenACS, we'll query the authority that authenticated him for information about this user. That authentication authority will then give us at least first names, last name and email. The pros and cons are the opposite of batch jobs. Using both in combination -is ideal.
Note: One solution to the "two users from different authorities -have the same email" problem above would be to allow users to +is ideal.
Note: One solution to the "two users from different authorities +have the same email" problem above would be to allow users to belong to multiple authorities. Then we would notice that the email already exists, ask the user if he thinks he's the same person, and if so, ask him to prove so by authenticating using the other authority. Thus he'll have just authenticated in two different authorities, and we can record that this is the same person. We'd still have a problem if there was an email conflict between two accounts on the same authority. Hm. I don't think it's worth spending too much -time trying to solve this problem through software.
Feature Status Description EXT-AUTH-31 EXT-AUTH-31 A Upgrade user data model for ext-auth After having authenticated using the relevant authority driver, +time trying to solve this problem through software.
Feature Status Description EXT-AUTH-31 EXT-AUTH-31 A Upgrade user data model for ext-auth After having authenticated using the relevant authority driver, we'll look for the username/authority pair in the users table.
If we don't find any, that means that we're either not doing batch synchronizing, or that the user has been added since the last sync. In that case, we'll try to do a real-time synchronization, if @@ -155,60 +155,60 @@ create a row in the local users table using that information.
If that doesn't work, we'll tell the user that their account isn't yet available, and the driver will supply a message for us, -which could say "The account should be available tomorrow. If not, -contact X."
If a user doesn't have an account, the site-wide +which could say "The account should be available tomorrow. If not, +contact X."
If a user doesn't have an account, the site-wide configuration can allow the user to register for one, as defined in the configuration discussed above. This section is about normal account registration through a authority driver.
The account creation service contract implementation will -need to tell us which information to ask the user for:
Required Fields: A list of fields which are - required.
Optional Fields: A list of fields which are - optional.
The fields to choose from are these:
Username
First names
Last name
URL
Password
Secret question
Secret answer
It should return the following:
Creation status (OK, Try-Again, Fail)
Creation message: What went wrong, or a welcome - message.
Account status: Is the account ready for use?
User information: first_names, last_name, email, url, +need to tell us which information to ask the user for:
Required Fields: A list of fields which are + required.
Optional Fields: A list of fields which are + optional.
The fields to choose from are these:
Username
First names
Last name
URL
Password
Secret question
Secret answer
It should return the following:
Creation status (OK, Try-Again, Fail)
Creation message: What went wrong, or a welcome + message.
Account status: Is the account ready for use?
User information: first_names, last_name, email, url, password, password_hash, secret_question, secret_answer. The driver only needs to return the columns which were changed or added - through the registration process. Typically, only the "local" + through the registration process. Typically, only the "local" driver will return password and secret question/answer.
After creating the remote account, a local account is created with the information gathered through the form/returned by the driver.
By default, a local account creation implementation is provided, which will create a new OpenACS user, and, in addition to the default local account creation above, also store the password -in hashed form.
Password management is about changing password, retrieving password, and resetting password.
It's up to the authority driver implementation to decide whether to support any or all of these features, and to say so using the CanXXX methods (see driver API below).
Additionally, the authority can be configured with a URL to redirect to in the case of forgotten passwords, or when the user -desires to change password.
Feature Status Description EXT-AUTH-20 EXT-AUTH-20 A Login over HTTPS Login pages must be able to be sent over a secure connection +desires to change password.
Feature Status Description EXT-AUTH-20 EXT-AUTH-20 A Login over HTTPS Login pages must be able to be sent over a secure connection (https), so your password won't get sent over the wire in cleartext, while leaving the rest of the site non-secure (http). I believe that this requires some (minor) changes to the current -session handling code.
Email verification needs to be handled both at registration +session handling code.
Email verification needs to be handled both at registration and at login.
In both cases, it'll be handled by the driver sending automatically sending the email containing a link for the user to verify his account. Then the driver will return an account status -of "closed,temporary", and a message that says "Check your inbox -and click the link in the email".
OpenACS will have a page which receives the email +of "closed,temporary", and a message that says "Check your inbox +and click the link in the email".
OpenACS will have a page which receives the email verification, for use by local accounts. Other authorities will have to implement their own page, most likely on the authority's -own server.
There are a number of items which touch on external authentication and session management. And even though they're not directly linked to external authentication, I would recommend that we handle a number of them, either because they're important for security, or because it makes sense to fix them while we're messing -with this part of the codebase anyway.
Feature Status Description EXT-AUTH-33 EXT-AUTH-33 A Untrusted Logins I like the idea of having multiple login levels:
Not logged in
Untrusted login: We'll show you un-sensitive personal +with this part of the codebase anyway.
Feature Status Description EXT-AUTH-33 EXT-AUTH-33 A Untrusted Logins I like the idea of having multiple login levels:
Not logged in
Untrusted login: We'll show you un-sensitive personal content, but won't let you modify anything or see personal data. A normal login becomes untrusted after a certain amount of time, and the user will have to re-enter his/her password in order to gain access to personal data. Untrusted login never expires, unless explicitly done so through either changing password or clicking a - special "expire all logins" link.
Normal login: The user is logged, and has type his + special "expire all logins" link.
Normal login: The user is logged, and has type his password sufficiently recently that we trust the login. All normal operations are allowed. Will degrade to untrusted login after a - specified amount of time.
Secure login: The user is logged in over a secure + specified amount of time.
Secure login: The user is logged in over a secure connection (HTTPS), potentially even using a special secure password. This would be for sensitive actions, such as credit card transactions.
There are two advantages to this. First, when people's login @@ -224,19 +224,19 @@ example, we could let you browse publically available forums, and only when you want to post do you need to log in. This makes it even more feasible to have a more secure login expiration -setting.
By default,
auth::require_loginwould +setting.By default, auth::require_login would bounce to the login page if the user is only logged in at the untrusted level. Only if you explicitly say -
auth::require_login -untrustedwill we give you +auth::require_login -untrusted will we give you the user_id of a user who's only logged in in untrusted -mode.Similarly,
ad_conn user_idwill continue +mode.Similarly, ad_conn user_id will continue to return 0 (not logged in) when the user is only logged in -untrusted, and we'll supply another variable,
ad_conn -untrusted_user_id, which wlll be set to the user_id for +untrusted, and we'll supply another variable, ad_conn +untrusted_user_id, which wlll be set to the user_id for all login levels.This should ensure that we get full access to the new feature, while leaving all current code just as secure as it was -before.
Feature Status Description EXT-AUTH-34 EXT-AUTH-34 A Expire Logins Currently, OpenACS is unusable in practice without persistent +before.
Feature Status Description EXT-AUTH-34 EXT-AUTH-34 A Expire Logins Currently, OpenACS is unusable in practice without persistent login. The login will expire after just a few minutes of inactivity, and you'll get bounced to the login page where you have to enter both email and password again. Unacceptable in @@ -247,15 +247,15 @@ login expire after a period of inactivity, but the amount of time should be configurable and default to something reasonable like an hour or so.
This will require looking into and changing the design of the -current session handling code.
Feature Status Description EXT-AUTH-23 EXT-AUTH-23 Single sign-on Instead of redirecting to the login page, auth::require_login +current session handling code.
Feature Status Description EXT-AUTH-23 EXT-AUTH-23 Single sign-on Instead of redirecting to the login page, auth::require_login can redirect to an authentication server, which can redirect back to a page that logs the user in. This should be very easy to implement.
Alternatively, if you want to combine this with fallback to OpenACS accounts, we would instead present the normal login screen, -but put a button which says "Login using X", where X is the -redirection-based external authority.
Feature Status Description EXT-AUTH-22 EXT-AUTH-22 B rewrite cookie handling Currently, if you've ever left a permanent login cookie on +but put a button which says "Login using X", where X is the +redirection-based external authority.
Feature Status Description EXT-AUTH-22 EXT-AUTH-22 B rewrite cookie handling Currently, if you've ever left a permanent login cookie on someone elses machine, that person will be forever logged in until he/she explicitly logs out. You can change your password, you can do anything you want, but unless a logout is requested from that @@ -270,32 +270,32 @@ void. Of course, we don't want to incur a DB hit on every request, so we'll need to cache the secret token, or only check it when refreshing the session cookie, which, I believe, normally happens -every 10 minutes or so.
Feature Status Description EXT-AUTH-24 EXT-AUTH-24 A Email on password change As an additional security measure, we should email the +every 10 minutes or so.
Feature Status Description EXT-AUTH-24 EXT-AUTH-24 A Email on password change As an additional security measure, we should email the account's email address whenever the password is changed, so that -he/she is at least alerted to the fact.
Feature Status Description EXT-AUTH-25 EXT-AUTH-25 A Implement password policy Again, to increase security, we should add password policies, +he/she is at least alerted to the fact.
Feature Status Description EXT-AUTH-25 EXT-AUTH-25 A Implement password policy Again, to increase security, we should add password policies, such as passwords needing to be changed after a certain number of days, change on next login (after a new random password has been generated), or requiring that the password satisfies certain complexity rules, i.e. both upper and lowercase characters, numbers, special chars, etc.
It would good to extend the current maximum password length -from 10 to at least 32 characters.
Feature Status Description EXT-AUTH-26 EXT-AUTH-26 B Login without explicit domain In order to make it easier for people, we've been toying with -the idea of a functionality like this:
If the user enters "foobar@ix.urz.uni-heidelberg.de", it - is translated to mean username = "foobar", authority = - "ix.urz.uni-heidelberg.de".
If the user enters "foobar", it's recognized to not +from 10 to at least 32 characters.
Feature Status Description EXT-AUTH-26 EXT-AUTH-26 B Login without explicit domain In order to make it easier for people, we've been toying with +the idea of a functionality like this:
If the user enters "foobar@ix.urz.uni-heidelberg.de", it + is translated to mean username = "foobar", authority = + "ix.urz.uni-heidelberg.de".
If the user enters "foobar", it's recognized to not include any authority, and the default authority of - "ix.urz.uni-heidelberg.de" is used.
If the user enters "foo@bar.com", it's recognized as not + "ix.urz.uni-heidelberg.de" is used.
If the user enters "foo@bar.com", it's recognized as not belonging to any known authority, and as such, it's translated to mean - username = "foo@bar.com", authority = "local".
If this is deemed desirable, a way to implement this would be -through these settings:
Split: A regexp which will split the user's entry into - username and authority parts. For example "^([^@]+)(@[^@]+)?$". An + username = "foo@bar.com", authority = "local".
If this is deemed desirable, a way to implement this would be +through these settings:
Split: A regexp which will split the user's entry into + username and authority parts. For example "^([^@]+)(@[^@]+)?$". An easier to use but less flexible method would be that you simply - specify a certain character to split by, such as "@" or "\". If the + specify a certain character to split by, such as "@" or "\". If the regexp doesn't match, or in the latter case, if there's more than one occurrence of the specified character sequence, the split will - fail, signaling that the user's entry was not valid.
Default authority: The default authority will be the first one + fail, signaling that the user's entry was not valid.
Default authority: The default authority will be the first one in the sort order.
The relevant code in user-login.tcl would look like this:
if { ![auth::split_username -username_var username -authority_var authority] } { @@ -305,7 +305,7 @@ # username will now contain username # authority will now contain authority -
Feature Status Description EXT-AUTH-27 EXT-AUTH-27 B Who's online list While we're touching the session handling code, anyway, it +
Feature Status Description EXT-AUTH-27 EXT-AUTH-27 B Who's online list While we're touching the session handling code, anyway, it would be nice to add a feature to show who's currently online, a nice real-time collaboration feature frequently requested by members of the community. This is particularly interesting when @@ -314,18 +314,18 @@ which authenticated users have requested pags on the site in the last x minutes (typically about 5), and thus are considered to be currently online. There's nothing more to it. This lets us display -a list of "active users" somewhere on the site, and make their name +a list of "active users" somewhere on the site, and make their name a link to a real-time chat service like Jabber.
We've already made the changes necessary to security-procs.tcl to do this on an earlier project, but haven't -quite finished the work and put it back into the tree.
Feature Status Description EXT-AUTH-28 EXT-AUTH-28 implement subsite-level config If we want to, we could let subsite administrators configure +quite finished the work and put it back into the tree.
Feature Status Description EXT-AUTH-28 EXT-AUTH-28 implement subsite-level config If we want to, we could let subsite administrators configure the login process for that particular subsite. This would probably only entail letting the subsite admin leave out certain authorities defined site-wide, and change the sort order.
I think we should leave this out until we have a use case for -it, someone who'd need it.
Feature Status Description EXT-AUTH-32 EXT-AUTH-32 A Parameters for Service Contract Implementation EXT-AUTH-35 A Make the Authentication API a service contract For completely free-form authentication logic and mechanisms, +it, someone who'd need it.
Feature Status Description EXT-AUTH-32 EXT-AUTH-32 A Parameters for Service Contract Implementation EXT-AUTH-35 A Make the Authentication API a service contract For completely free-form authentication logic and mechanisms, something like Andrew Grumet's -Pluggable +Pluggable Authentication for OACS Draft is interesting. He's proposing a scheme where the entire user interaction is encapsulated in, and left entirely to, a service contract. This @@ -334,10 +334,10 @@ people are going to want to use a username/password-based scheme, and having easy configuration through a web UI is more important than total flexibility at this point.
Besides, we can always do this in the future, by letting the -public Authentication API (
auth::require_login-andauth::authenticate) be implemented through a -service contract.
Feature Status Description EXT-AUTH-36 EXT-AUTH-36 A Authenticate against multiple servers Both OKI and OpenACS supports a form of stacking, where you +public Authentication API (auth::require_login +and auth::authenticate) be implemented through a +service contract.
Feature Status Description EXT-AUTH-36 EXT-AUTH-36 A Authenticate against multiple servers Both OKI and OpenACS supports a form of stacking, where you can be logged into multiple authorities at the same time. This is useful if, for example, you need to get login tokens such as Kerberos tickets for access to shared resources.
I can see the value in this, but for simplicity's sake, I'm @@ -350,30 +350,30 @@ for user/group data and access control lists, SMB for file storage, etc. But at the moment, we don't have any users of such things that are ready. We have some who are on the steps, but let's wait till -they're there.
Feature Status Description Implement specific drivers EXT-AUTH-09 A Create Auth. drivers for Local Authority EXT-AUTH-10 A Create Acct. Creation driver for Local Authority EXT-AUTH-11 A Create Auth. driver for PAM EXT-AUTH-12 X Create Acct. Creation driver for PAM - this - functionality is explicitly excluded from PAM EXT-AUTH-13 A Create Acct. Creation driver for LDAP EXT-AUTH-14 A Create Auth. driver for LDAP We'll need drivers for:
Operating system (Linux/Solaris) PAM: Delegate to the +they're there.
Feature Status Description Implement specific drivers EXT-AUTH-09 A Create Auth. drivers for Local Authority EXT-AUTH-10 A Create Acct. Creation driver for Local Authority EXT-AUTH-11 A Create Auth. driver for PAM EXT-AUTH-12 X Create Acct. Creation driver for PAM - this + functionality is explicitly excluded from PAM EXT-AUTH-13 A Create Acct. Creation driver for LDAP EXT-AUTH-14 A Create Auth. driver for LDAP We'll need drivers for:
Operating system (Linux/Solaris) PAM: Delegate to the operating system, which can then talk to RADIUS, LDAP, whatever. This is convenient because there'll be plenty of drivers for the OS PAM level, so we don't have to write them all ourselves. The downside is that we can't do things like account creation, password management, real-time account synchronization, etc., not supported by PAM (I'm not entirely sure what is and is not - supported).
RADIUS
LDAP
RADIUS is a simple username/password-type authentication server.
It also supports sending a challenge to which the user must respond with the proper answer (e.g. mother's maiden name, or could be additional password), but we will not support this feature.
A RADIUS client -implementation +implementation in Python can be found in the -exUserFolder +exUserFolder module for Zope -(documentation).
We'd really appreciate feedback on this proposal. Please +(documentation).
We'd really appreciate feedback on this proposal. Please follow up at -this -openacs.org forums thread.
Threads -and links collected by Carl Blesius.
Draft -Proposal by Andrew Grumet.
Threads +and links collected by Carl Blesius.
Draft +Proposal by Andrew Grumet.
Yale CAS, a centrl authentication service a' la - Passport.
View comments on this page at openacs.org + Passport.View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -r1.43.2.2 -r1.43.2.3 --- openacs-4/packages/acs-core-docs/www/filename.html 6 Jul 2009 11:14:26 -0000 1.43.2.2 +++ openacs-4/packages/acs-core-docs/www/filename.html 11 Sep 2009 23:41:26 -0000 1.43.2.3 @@ -1,5 +1,5 @@ - -Detailed Design Documentation Template By You
+ +
Detailed Design Documentation Template By You
NOTE: Some of the sections of this template may not apply to your package, e.g. there may be no user-visible UI elements for a component of the OpenACS Core. Furthermore, it may be easier in some circumstances @@ -11,48 +11,48 @@ your own judgment, consult with peers when possible, and adapt intelligently.
- Also, bear in mind the audience for detailed design: fellow + Also, bear in mind the audience for detailed design: fellow programmers who want to maintain/extend the software, AND parties interested in evaluating software quality. -
When applicable, each of the following items should receive its own link: -
User directory
OpenACS administrator directory
Subsite administrator directory
Tcl script directory (link to the API browser page for the package)
PL/SQL file (link to the API browser page for the package)
Data model
Requirements document
ER diagram
Transaction flow diagram
+
User directory
OpenACS administrator directory
Subsite administrator directory
Tcl script directory (link to the API browser page for the package)
PL/SQL file (link to the API browser page for the package)
Data model
Requirements document
ER diagram
Transaction flow diagram
This section should provide an overview of the package and address at least the following issues: -
What this package is intended to allow the user (or different - classes of users) to accomplish.
Within reasonable bounds, what this package is not intended to allow users to - accomplish.
The application domains where this package is most likely to be of use.
A high-level overview of how the package meets its +
What this package is intended to allow the user (or different + classes of users) to accomplish.
Within reasonable bounds, what this package is not intended to allow users to + accomplish.
The application domains where this package is most likely to be of use.
A high-level overview of how the package meets its requirements (which should have been documented elsewhere). This - is to include relevant material from the "features" section of the + is to include relevant material from the "features" section of the cover sheet (the cover sheet is a wrapper doc with links to all other package docs).
Also worthy of treatment in this section: -
When applicable, a careful demarcation between the +
When applicable, a careful demarcation between the functionality of this package and others which - at least superficially - appear to address the same requirements.
Note: it's entirely possible that a discussion of what a package is not intended to do differs from a discussion of future improvements for the package. -
For a given set of requirements, typically many possible implementations and solutions exist. Although eventually only one solution is implemented, a discussion of the alternative solutions canvassed - noting why they were rejected - proves helpful to both current and future developers. All readers would be reminded as to why and how the particular solution developed over time, avoiding re-analysis of problems already solved. -
Although currently only a few package documentation pages contain a discussion of competing software, (e.g. chat, portals), this section should be present whenever such competition exists. -
If your package exhibits features missing from competing - software, this fact should be underscored.
If your package lacks features which are present in competing +
If your package exhibits features missing from competing + software, this fact should be underscored.
If your package lacks features which are present in competing software, the reasons for this should be discussed here; our sales team needs to be ready for inquiries regarding features our software lacks.
Note that such a discussion may differ from a discussion of a package's potential future improvements. -
No single design solution can optimize every desirable software attribute. For example, an increase in the security of a system will likely entail a decrease in its ease-of-use, and an increase in the @@ -62,14 +62,14 @@ should include a discussion of the tradeoffs involved with the design chosen, and the reasons for your choices. Some areas of importance to keep in mind are: -
Areas of interest to users:
Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability
Areas of interest to developers:
Maintainability
Portability
Reusability
Testability
+
Areas of interest to users:
Performance: availability and efficiency
Flexibility
Interoperability
Reliability and robustness
Usability
Areas of interest to developers:
Maintainability
Portability
Reusability
Testability
Here's where you discuss the abstractions used by your package, such as the procedures encapsulating the legal transactions on the data model. Explain the organization of procedures and their particulars (detail above and beyond what is documented in the code), including: -
Problem-domain components: key algorithms, e.g. a specialized - statistics package would implement specific mathematical procedures.
User-interface components: e.g. HTML widgets that the package may need.
Data management components: procedures that provide a stable +
Problem-domain components: key algorithms, e.g. a specialized + statistics package would implement specific mathematical procedures.
User-interface components: e.g. HTML widgets that the package may need.
Data management components: procedures that provide a stable interface to database objects and legal transactions - the latter often correspond to tasks.
Remember that the correctness, completeness, and stability of the API @@ -80,60 +80,60 @@ handle transactions, instead of encapsulating them via procedures). Experience has taught us that we need to focus on the API for maintainability of our systems in the face of constant change. -
The data model discussion should do more than merely display the SQL code, since this information is already be available via a link in the - "essentials" section above. Instead, there should be a high-level + "essentials" section above. Instead, there should be a high-level discussion of how your data model meets your solution requirements: why the database entities were defined as they are, and what transactions you expect to occur. (There may be some overlap with the API section.) Here are some starting points: -
The data model discussion should address the intended usage +
The data model discussion should address the intended usage of each entity (table, trigger, view, procedure, etc.) when this information is not obvious from an inspection of the data model - itself.
If a core service or other subsystem is being used (e.g., the + itself.
If a core service or other subsystem is being used (e.g., the new parties and groups, permissions, etc.) this should also be - mentioned.
Any default permissions should be identified herein.
Discuss any data model extensions which tie into other - packages.
Transactions
Discuss modifications which the database may undergo from + mentioned.
Any default permissions should be identified herein.
Discuss any data model extensions which tie into other + packages.
Transactions
Discuss modifications which the database may undergo from your package. Consider grouping legal transactions according to the invoking user class, i.e. transactions by an OpenACS-admin, by - subsite-admin, by a user, by a developer, etc.
In this section, discuss user interface issues and pages to be built; you can organize by the expected classes of users. These may include: -
Developers
OpenACS administrators (previously known as site-wide administrators)
Subsite administrators
End users
+
Developers
OpenACS administrators (previously known as site-wide administrators)
Subsite administrators
End users
You may want to include page mockups, site-maps, or other visual aids. Ideally this section is informed by some prototyping you've done, to establish the package's usability with the client and other interested parties.
Note: In order that developer documentation be uniform across different system documents, these users should herein be designated as - "the developer," "the OpenACS-admin," "the sub-admin," and "the user," + "the developer," "the OpenACS-admin," "the sub-admin," and "the user," respectively.
Finally, note that as our templating system becomes more entrenched within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics. -
Under OpenACS 5.5.0, parameters are set at two levels: at the global level by the OpenACS-admin, and at the subsite level by a sub-admin. In this section, list and discuss both levels of parameters. -
If the system presently lacks useful/desirable features, note details here. You could also comment on non-functional improvements to the package, such as usability.
- Note that a careful treatment of the earlier "competitive analysis" + Note that a careful treatment of the earlier "competitive analysis" section can greatly facilitate the documenting of this section. -
Although a system's data model file often contains this information, this isn't always the case. Furthermore, data model files often undergo substantial revision, making it difficult to track down the system creator. An additional complication: package documentation may be authored by people not directly involved in coding. Thus to avoid unnecessary confusion, include email links to the following roles as they may apply: -
System creator
System owner
Documentation author
The revision history table below is for this template - modify it as needed for your actual design document.
Document Revision # Action Taken, Notes When? By Whom? 0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu 0.2 Edited 8/22/2000 Kai Wu 0.1 Creation 8/21/2000 Josh Finkler, Audrey McLoghlin ($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/for-everyone.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v diff -u -r1.23.2.1 -r1.23.2.2 --- openacs-4/packages/acs-core-docs/www/for-everyone.html 10 Jun 2009 22:24:07 -0000 1.23.2.1 +++ openacs-4/packages/acs-core-docs/www/for-everyone.html 11 Sep 2009 23:41:26 -0000 1.23.2.2 @@ -1,2 +1,2 @@ - -Part I. OpenACS For Everyone View comments on this page at openacs.org + +Part I. OpenACS For Everyone Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -r1.24.2.2 -r1.24.2.3 --- openacs-4/packages/acs-core-docs/www/form-builder.html 6 Jul 2009 11:14:26 -0000 1.24.2.2 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 11 Sep 2009 23:41:26 -0000 1.24.2.3 @@ -1,30 +1,30 @@ - -Using Form Builder: building html forms dynamically ($Id$)+ +Using Form Builder: building html forms dynamically OpenACS has a form manager called ad_form. Ad_form has an adaptable UI. Error handling includes inline error reporting, and is customizable. However, ad_form can be tricky to use. In addition to this document, - the ad_form api - documentation is helpful.
Some elements have more than one choice, or can submit more than one value.
Creating the form element. Populate a list of lists with values for the option list.
set foo_options [db_list_of_lists foo_option_list " + the ad_form api + documentation is helpful.Some elements have more than one choice, or can submit more than one value.
Creating the form element. Populate a list of lists with values for the option list.
set foo_options [db_list_of_lists foo_option_list " select foo, foo_id from foos -"] -The variable
foo_optionsshould resemble{{first foo} 1234} {{second foo} 1235} -Within ad_form, set up the element to use this list:
{foo:text(select) - {label "Which Foo"} +"] +The variable foo_options should resemble {{first foo} 1234} {{second foo} 1235} +
Within ad_form, set up the element to use this list:
{foo:text(select) + {label "Which Foo"} {options $foo_options} - }This will result in a single name/value pair coming back in the submitted form. Handle this within the same ad_form structure, in the
-new_dataand-edit_data. In the example, it is available as$fooSee also the - W3C spec for "The SELECT, OPTGROUP, and OPTION elements". -
A situation you may run into often is where you want to pull + }
This will result in a single name/value pair coming back in the submitted form. Handle this within the same ad_form structure, in the -new_data and -edit_data. In the example, it is available as $foo
See also the + W3C spec for "The SELECT, OPTGROUP, and OPTION elements". +
A situation you may run into often is where you want to pull in form items from a sub-category when the first category is selected. Ad_form makes this fairly easy to do. In the definition of your form element, include an html section
{pm_task_id:integer(select),optional - {label "Subject"} + {label "Subject"} {options {$task_options}} - {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}} + {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}} {value $pm_task_id} }What this will do is set the value for pm_task_id and all the @@ -39,17 +39,17 @@ -on_refresh section of your ad_form. In that section, you'll get the values from the database, and set the values as so:
db_1row get_task_values { } template::element set_value form_name estimated_hours_work $estimated_hours_work -A good way to troubleshoot when you're using ad_form is to add the following code at the top of the .tcl page (thanks Jerry Asher):
ns_log notice it's my page! set mypage [ns_getform] -if {[string equal "" $mypage]} { +if {[string equal "" $mypage]} { ns_log notice no form was submitted on my page } else { ns_log notice the following form was submitted on my page ns_set print $mypage } -Here are some common errors and what to do when you - encounter them:
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/general-documents.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v diff -u -r1.23.2.1 -r1.23.2.2 --- openacs-4/packages/acs-core-docs/www/general-documents.html 10 Jun 2009 22:24:07 -0000 1.23.2.1 +++ openacs-4/packages/acs-core-docs/www/general-documents.html 11 Sep 2009 23:41:26 -0000 1.23.2.2 @@ -1,2 +1,2 @@ - -Chapter 1. High level information: What is OpenACS? Table of Contents
View comments on this page at openacs.org + +Chapter 1. High level information: What is OpenACS? Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -r1.28.2.2 -r1.28.2.3 --- openacs-4/packages/acs-core-docs/www/groups-design.html 6 Jul 2009 11:14:26 -0000 1.28.2.2 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 11 Sep 2009 23:41:26 -0000 1.28.2.3 @@ -1,32 +1,32 @@ - -Groups Design By Rafael H. Schloming and Mark Thomas
+ +Groups Design
User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
Data model
PL/SQL file
ER diagram
Transaction flow diagram
User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
Data model
PL/SQL file
ER diagram
Transaction flow diagram
Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services -for different user communities.
The primary limitation of the OpenACS 3.x user group system is that it -restricts the application developer to representing a "flat group" -that contains only users: The
user_groupstable may contain the -group_idof a parent group, but parent-child relationship +for different user communities.The primary limitation of the OpenACS 3.x user group system is that it +restricts the application developer to representing a "flat group" +that contains only users: The user_groups table may contain the +group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.
In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of -
scope,user_id, andgroup_idcolumns +scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer -to:
add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption -(e.g., a row with a
scopevalue of "group" but a null -group_id)perform extra checks in
TclandPL/SQL-functions and procedures to check both theuser_idand -group_idvaluesThe core of the Group Systems data model is quite simple, but it was -designed in the hopes of modeling "real world" organizations which +to:
add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption +(e.g., a row with a scope value of "group" but a null +group_id)
perform extra checks in Tcl and PL/SQL +functions and procedures to check both the user_id and +group_id values
The core of the Group Systems data model is quite simple, but it was +designed in the hopes of modeling "real world" organizations which can be complex graph structures. The Groups System only considers groups that can be modeled using directed acyclic graphs, but queries over these structures are still complex enough to slow the system down. Since almost @@ -38,44 +38,44 @@ without making the system too complex or too slow. The added triggers, views, and tables and will increase storage requirements and the insert and delete times in an effort to speed access time. The limited flexibility (no updates -on membership) trades against the complexity of the code.
The Group System data model consists of the following tables:
parties+on membership) trades against the complexity of the code.The Group System data model consists of the following tables:
- parties
The set of all defined parties: any person, user, or -group must have a corresponding row in this table.
persons+group must have a corresponding row in this table.- persons
The set of all defined persons. To allow easy sorting of persons, the -name requirement 30.10 is met by -splitting the person's name into two columns:
first_namesand -last_name.users+name requirement 30.10 is met by +splitting the person's name into two columns: first_names and +last_name.- users
The set of all registered users; this table includes information about -the user's email address and the user's visits to the site.
user_preferences+the user's email address and the user's visits to the site.- user_preferences -
Preferences for the user.
groups+Preferences for the user.
- groups -
The set of all defined groups.
group_types+The set of all defined groups.
- group_types
When a new type of group is created, this table holds additional -knowledge level attributes for the group and its subtypes.
membership_rels+knowledge level attributes for the group and its subtypes.- membership_rels
The set of direct membership relationships between a group and a -party.
group_member_index+party.- group_member_index -
A mapping of a party P to the groups -{Gi}the party is a member of; this mapping -includes the type of relationship by including the appropriate
rel_id-from themembership_relstable.composition_rels+A mapping of a party P to the groups +{Gi}the party is a member of; this mapping +includes the type of relationship by including the appropriaterel_id +from the membership_rels table.
- composition_rels
The set of direct component relationships between a group and another -group.
group_component_index+group.- group_component_index -
A mapping of a group Gto the set of groups -{Gi} that G is a component of; +
A mapping of a group Gto the set of groups +{Gi} that G is a component of; this mapping includes the type of relationship by including the -appropriate
rel_idfrom thecomposition_relstable.New groups are created through the
group.newconstructor. +appropriaterel_id from the composition_rels table.New groups are created through the group.new constructor. When a specialized type of group is required, the group type can be extended by an application developer. Membership constraints can be specified at -creation time by passing a parent group to the constructor.
The
membership_relsandcomposition_relstables indicate +creation time by passing a parent group to the constructor.The membership_rels and composition_rels tables indicate a group's direct members and direct components; these tables do not provide a record of the members or components that are in the group by virtue of being a member or component of one of the group's component groups. @@ -85,60 +85,60 @@ queries responsive, the data model includes triggers (described in the next paragraph) which watch for changes in membership or composition and update tables that maintain the group party mappings, i.e., -
group_member_indexandgroup_component_index. One can think -of these tables as a manually maintained index.The following triggers keep the
group_*_indextables up to -date:
membership_rels_in_tr+group_member_index and group_component_index. One can think +of these tables as a manually maintained index.The following triggers keep the group_*_index tables up to +date:
- membership_rels_in_tr
Is executed when a new group/member relationship is created (an insert on -
membership_rels)membership_rels_del_tr+membership_rels)- membership_rels_del_tr
Is executed when a group/member relationship is deleted (a delete on -
membership_rels)composition_rels_in_tr+membership_rels)- composition_rels_in_tr
Is executed when a new group/component relationship is created (an insert -on
composition_rels)composition_rels_del_tr+on composition_rels)- composition_rels_del_tr
Is executed when a group/component relationship is deleted (a delete on -
composition_rels)The data model provides the following views onto the -
group_member_indexandgroup_component_indextables. No -code outside of Groups System should modify thegroup_*_index-tables.
group_member_map+composition_rels)The data model provides the following views onto the +group_member_index and group_component_index tables. No +code outside of Groups System should modify the group_*_index +tables.
- group_member_map
A mapping of a party to the groups the party is a member of; this mapping -includes the type of relationship by including the appropriate
rel_id-from themembership_relstable.group_approved_member_map+includes the type of relationship by including the appropriaterel_id +from the membership_rels table.- group_approved_member_map
A mapping of a party to the groups the party is an approved member of -(
member_stateis 'approved'); this mapping includes the type -of relationship by including the appropriaterel_idfrom the -membership_relstable.group_distinct_member_map+(member_state is 'approved'); this mapping includes the type +of relationship by including the appropriaterel_id from the +membership_rels table.- group_distinct_member_map
A person may appear in the group member map multiple times, for example, by being a member of two different groups that are both components of a third -group. This view is strictly a mapping of approved members -to groups.
group_component_map+group. This view is strictly a mapping of approved members +to groups.- group_component_map -
A mapping of a group Gto the set of groups -{Gi} group G is a component of; +
A mapping of a group Gto the set of groups +{Gi} group G is a component of; this mapping includes the type of relationship by including the -appropriate
rel_idfrom thecomposition_relstable.party_member_map+appropriaterel_id from the composition_rels table.- party_member_map -
A mapping of a party P to the set of parties -{Pi} party P is a member -of.
party_approved_member_map+A mapping of a party P to the set of parties +{Pi} party P is a member +of.
- party_approved_member_map -
A mapping of a party P to the set of parties -{Pi} party P is an -approved member of.
The API consists of tables and views and PL/SQL functions. -
The
group_typestable is used to create new types of groups.The
group_member_map,group_approved_member_map, -group_distinct_member_map,group_component_map, -party_member_map, andparty_approved_member_mapviews are -used to query group membership and composition.Person
person.newcreates a new person and returns the -person_id. The function must be given the full name of the person in -two pieces:first_namesandlast_name. All other fields are -optional and default to null except forobject_typewhich defaults -to person andcreation_datewhich defaults tosysdate. The +The group_types table is used to create new types of groups.
The group_member_map, group_approved_member_map, +group_distinct_member_map, group_component_map, +party_member_map, and party_approved_member_map views are +used to query group membership and composition.
Person
person.new creates a new person and returns the +person_id. The function must be given the full name of the person in +two pieces: first_names and last_name. All other fields are +optional and default to null except for object_type which defaults +to person and creation_date which defaults to sysdate. The interface for this function is:
function person.new ( person_id persons.person_id%TYPE, @@ -151,19 +151,19 @@ first_names persons.first_names%TYPE, last_name persons.last_name%TYPE ) return persons.person_id%TYPE; -
person.deletedeletes the person whoseperson_idis +person.delete deletes the person whose person_id is passed to it. The interface for this procedure is:
procedure person.delete ( person_id persons.person_id%TYPE ); -
person.namereturns the name of the person whose -person_idis passed to it. The interface for this function is:+person.name returns the name of the person whose +person_id is passed to it. The interface for this function is:
function person.name ( person_id persons.person_id%TYPE ) return varchar; -User
acs_user.newcreates a new user and returns theuser_id. +User
acs_user.new creates a new user and returns the user_id. The function must be given the user's email address and the full name of -the user in two pieces:
first_namesandlast_name. All +the user in two pieces: first_names and last_name. All other fields are optional. The interface for this function is:function acs_user.new ( user_id users.user_id%TYPE, @@ -182,19 +182,19 @@ screen_name users.screen_name%TYPE, email_verified_p users.email_verified_p%TYPE ) return users.user_id%TYPE; -
acs_user.deletedeletes the user whoseuser_idis passed +acs_user.delete deletes the user whose user_id is passed to it. The interface for this procedure is:
procedure acs_user.delete ( user_id users.user_id%TYPE ); -
acs_user.receives_alerts_preturns 't' if the user should +acs_user.receives_alerts_p returns 't' if the user should receive email alerts and 'f' otherwise. The interface for this function is:
function acs_user.receives_alerts_p ( user_id users.user_id%TYPE ) return varchar; -Use the procedures
acs_user.approve_emailand -acs_user.unapprove_emailto specify whether the user's email +Use the procedures acs_user.approve_email and +acs_user.unapprove_email to specify whether the user's email address is valid. The interface for these procedures are:
procedure acs_user.approve_email ( user_id users.user_id%TYPE @@ -203,11 +203,11 @@ procedure acs_user.unapprove_email ( user_id users.user_id%TYPE ); -Group
acs_group.newcreates a new group and returns the -group_id. All fields are optional and default to null except for -object_typewhich defaults to 'group', -creation_datewhich defaults tosysdate, and -group_namewhich is required. The interface for +Group
acs_group.new creates a new group and returns the +group_id. All fields are optional and default to null except for +object_type which defaults to 'group', +creation_date which defaults to sysdate, and +group_name which is required. The interface for this function is:
function acs_group.new ( group_id groups.group_id%TYPE, @@ -219,21 +219,21 @@ url parties.url%TYPE, group_name groups.group_name%TYPE ) return groups.group_id%TYPE; -
acs_group.namereturns the name of the group whose -group_idis passed to it. The interface for this function is:+acs_group.name returns the name of the group whose +group_id is passed to it. The interface for this function is:
function acs_group.name ( group_id groups.group_id%TYPE ) return varchar; -
acs_group.member_preturns 't' if the specified party is +acs_group.member_p returns 't' if the specified party is a member of the specified group. Returns 'f' otherwise. The interface for this function is:
function acs_group.member_p ( group_id groups.group_id%TYPE, party_id parties.party_id%TYPE, ) return char; -Membership Relationship
membership_rel.newcreates a new membership relationship type -between two parties and returns the relationship type'srel_id. -All fields are optional and default to null except forrel_type+Membership Relationship
membership_rel.new creates a new membership relationship type +between two parties and returns the relationship type's rel_id. +All fields are optional and default to null except for rel_type which defaults to membership_rel. The interface for this function is:
function membership_rel.new ( rel_id membership_rels.rel_id%TYPE, @@ -244,42 +244,42 @@ creation_user acs_objects.creation_user%TYPE, creation_ip acs_objects.creation_ip%TYPE, ) return membership_rels.rel_id%TYPE; -
membership_rel.bansets themember_stateof the given -rel_idto 'banned'. The interface for this procedure is:+membership_rel.ban sets the member_state of the given +rel_id to 'banned'. The interface for this procedure is:
procedure membership_rel.ban ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.approvesets themember_stateof the -givenrel_idto 'approved'. The interface for this procedure +membership_rel.approve sets the member_state of the +given rel_id to 'approved'. The interface for this procedure is:
procedure membership_rel.approve ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.rejectsets themember_stateof the given -rel_idto 'rejected. The interface for this procedure is:+membership_rel.reject sets the member_state of the given +rel_id to 'rejected. The interface for this procedure is:
procedure membership_rel.reject ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.unapprovesets themember_stateof the -givenrel_idto an empty string ''. The interface for this +membership_rel.unapprove sets the member_state of the +given rel_id to an empty string ''. The interface for this procedure is:
procedure membership_rel.unapprove ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.deletedsets themember_stateof the -givenrel_idto 'deleted'. The interface for this procedure +membership_rel.deleted sets the member_state of the +given rel_id to 'deleted'. The interface for this procedure is:
procedure membership_rel.deleted ( rel_id membership_rels.rel_id%TYPE ); -
membership_rel.deletedeletes the givenrel_id. The +membership_rel.delete deletes the given rel_id. The interface for this procedure is:
procedure membership_rel.delete ( rel_id membership_rels.rel_id%TYPE ); -Composition Relationship
composition_rel.newcreates a new composition relationship type -and returns the relationship'srel_id. All fields are optional -and default to null except forrel_typewhich defaults to +Composition Relationship
composition_rel.new creates a new composition relationship type +and returns the relationship's rel_id. All fields are optional +and default to null except for rel_type which defaults to composition_rel. The interface for this function is:
function membership_rel.new ( rel_id composition_rels.rel_id%TYPE, @@ -289,19 +289,19 @@ creation_user acs_objects.creation_user%TYPE, creation_ip acs_objects.creation_ip%TYPE, ) return composition_rels.rel_id%TYPE; -
composition_rel.deletedeletes the givenrel_id. The +composition_rel.delete deletes the given rel_id. The interface for this procedure is:
procedure membership_rel.delete ( rel_id composition_rels.rel_id%TYPE ); -
- System creator -
- System owner +
- System owner -
- Documentation author +
- Documentation author -
Mark Thomas
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/22/2000 Rafael H. Schloming 0.2 Initial Revision 08/30/2000 + Mark Thomas
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/22/2000 Rafael H. Schloming 0.2 Initial Revision 08/30/2000 Mark Thomas 0.3 Additional revisions; tried to clarify membership/compostion 09/08/2000 Mark Thomas - View comments on this page at openacs.org +View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -r1.28.2.1 -r1.28.2.2 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 10 Jun 2009 22:24:07 -0000 1.28.2.1 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 11 Sep 2009 23:41:26 -0000 1.28.2.2 @@ -1,60 +1,60 @@ - -Groups Requirements By Rafael H. Schloming, Mark Thomas
+ +Groups Requirements Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services - for different user communities.
A powerful web service that can meet the needs of large enterprises must + for different user communities.
A powerful web service that can meet the needs of large enterprises must be able to model the the real world's very rich organizational structures and many ways of decomposing the same organization. For example, a corporation can be broken into structures (the corporation, its divisions, and their departments) or regions (the Boston office, the LA office); a person who is employed by (is a member of) a specific department is also a member of the division and the corporation, and works at (is a member of, but in a different sense) a particular office. OpenACS's Parties and Groups - system will support such complex relations faithfully.
Historical Motivations
The primary limitation of the OpenACS 3.x user group system is that it - restricts the application developer to representing a "flat group" - that contains only users: The
user_groupstable may contain the -group_idof a parent group, but parent-child relationship + system will support such complex relations faithfully.Historical Motivations
The primary limitation of the OpenACS 3.x user group system is that it + restricts the application developer to representing a "flat group" + that contains only users: The user_groups table may contain the + group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.
In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of -
scope,user_id, andgroup_idcolumns + scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer - to:
add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption - (e.g., a row with a
scopevalue of "group" but a null -group_id)perform extra checks in
TclandPL/SQL- functions and procedures to check both theuser_idand -group_idvaluesIn sum, the goal of the Parties and Groups system is to + to:
add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption + (e.g., a row with a scope value of "group" but a null + group_id)
perform extra checks in Tcl and PL/SQL + functions and procedures to check both the user_id and + group_id values
In sum, the goal of the Parties and Groups system is to provide OpenACS programmers and site administrators with simple tools that fully describe the complex relationships that exist among groups in the real - world.
Pat Developer has a client project and wants to model the company, its offices, its divisions, and its departments as groups and the employees as - users.
We start with Groups, which contain members; the - member can be either a person or another group (i.e. a + users.
We start with Groups, which contain members; the + member can be either a person or another group (i.e. a member is a party).
In addition to membership, the party and groups system defines a - composition relationship that may exist between groups: A - group can be a component of another group. The child group + composition relationship that may exist between groups: A + group can be a component of another group. The child group is called a component group; the parent group is called a - composite group.
A group Gc can be a member and/or a component - of another group Gp; the difference is in the way - the members of Gc are related to - Gp:
If a party P is a member (or a component) of - Gc and if Gc is a - component of Gp, then P is also - a member (or a component) of Gp
If a party P is a member (or a component) of - Gc and if Gc is a - member of Gp, then no - relationship between P and - Gp exists as a result of the relationship between - Gp and Gp.
Consider an example to make this less abstract: Pretend that the Sierra + composite group.
A group Gc can be a member and/or a component + of another group Gp; the difference is in the way + the members of Gc are related to + Gp:
If a party P is a member (or a component) of + Gc and if Gc is a + component of Gp, then P is also + a member (or a component) of Gp
If a party P is a member (or a component) of + Gc and if Gc is a + member of Gp, then no + relationship between P and + Gp exists as a result of the relationship between + Gp and Gp.
Consider an example to make this less abstract: Pretend that the Sierra Club is a member of Greenpeace. The Sierra Club has chapters; each chapter is a component of the Sierra Club. If Eddie Environmentalist is a member of the Massachusetts Chapter of the Sierra Club, Eddie is @@ -67,158 +67,158 @@ Massachusetts chapter), and between the Sierra Club and Greenpeace.
Membership requirements can vary from group to group. The parties and groups system must provide a base type that specifies the bare minimum necessary to join a group.
The parties and groups system must support constraints between a composite - group GP and any of its component groups, - GC. For example, the system should be able to - enforce a rule like: Do not allow a party P to become a - member of GC unless P is already - a member of GP.
The data model for the parties and groups system must provide support for - the following types of entities:
- 10.0 Parties + group GP and any of its component groups, + GC. For example, the system should be able to + enforce a rule like: Do not allow a party P to become a + member of GC unless P is already + a member of GP.
The data model for the parties and groups system must provide support for + the following types of entities:
- 10.0 Parties -
A party is an entity used to represent either a - group or a person.
The data model should enforce these constraints:
10.10 A party has an email address, which can be - empty.
10.20 A party may have multiple email addresses - associated with it.
10.30 The email address of a party must be unique within - an OpenACS system.
- 20.0 Groups +
A party is an entity used to represent either a + group or a person.
The data model should enforce these constraints:
10.10 A party has an email address, which can be + empty.
10.20 A party may have multiple email addresses + associated with it.
10.30 The email address of a party must be unique within + an OpenACS system.
- 20.0 Groups -
A group is a collection of zero or more parties.
20.10 The data model should support the subclassing of - groups via OpenACS Objects.
- 30.0 Persons +
A group is a collection of zero or more parties.
20.10 The data model should support the subclassing of + groups via OpenACS Objects.
- 30.0 Persons -
A person represents an actual human being, past or - present.
- 40.0 Users +
A person represents an actual human being, past or + present.
- 40.0 Users -
A user is a person who has registered with an OpenACS site. A - user may have additional attributes, such as a screen name.
The data model should enforce these constraints:
40.10 A user must have a non-empty email address.
40.20 Two different users may not have the same email +
A user is a person who has registered with an OpenACS site. A + user may have additional attributes, such as a screen name.
The data model should enforce these constraints:
40.10 A user must have a non-empty email address.
40.20 Two different users may not have the same email address on a single OpenACS installation; i.e., an email address identifies a - single user on the system.
40.30 A user may have multiple email addresses; for - example, two or more email addresses may identify a single user.
40.40 A user must have password field which can be + single user on the system.
40.30 A user may have multiple email addresses; for + example, two or more email addresses may identify a single user.
40.40 A user must have password field which can be empty.
The data model for the parties and groups system must provide support for - the following types of relationships between entities:
- 50.0 Membership + the following types of relationships between entities:
- 50.0 Membership
- A party P is considered a member of a - group G
when a direct membership relationship exists between P - and G
or when there exists a direct membership relationship between - P and some group GC and - GC has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple + A party P is considered a member of a + group G
when a direct membership relationship exists between P + and G
or when there exists a direct membership relationship between + P and some group GC and + GC has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple times only when all the memberships have different types; for example, Jane may be a member of The Company by being both an Employee and an - Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership - constraints.
50.50The data model should support the subclassing of + Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership + constraints.
50.50The data model should support the subclassing of membership via OpenACS Relationships.
- - 60.0 Composition -
A group GC is considered a - component of a second group - GP
when a direct composition relationship exists between - GC and GP
or when there exists a direct composition relationship between - GC and some group Gi - and Gi has a composition relationship with - GP.
60.10A group may be a component of multiple groups.
60.20A group as a component of itself is not - supported.
60.30The data model must support component - constraints.
60.40The data model should support the subclassing of - composition via OpenACS Relationships.
The API should let programmers accomplish the following tasks:
- 70.10 Create a group + 60.0 Composition +
A group GC is considered a + component of a second group + GP
when a direct composition relationship exists between + GC and GP
or when there exists a direct composition relationship between + GC and some group Gi + and Gi has a composition relationship with + GP.
60.10A group may be a component of multiple groups.
60.20A group as a component of itself is not + supported.
60.30The data model must support component + constraints.
60.40The data model should support the subclassing of + composition via OpenACS Relationships.
The API should let programmers accomplish the following tasks:
- 70.10 Create a group
The parties and groups system provides a well defined API call that creates a new group by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.
- 70.20 Create a person + in the data model.
- 70.20 Create a person
The parties and groups system provides a well defined API call that creates a new person by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.
- 70.30 Create a user + in the data model.
- 70.30 Create a user
The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out in - the data model.
- 80.10 Refine a person to a user + the data model.
- 80.10 Refine a person to a user
The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on an existing person entity. This API is subject to the constraints laid out in the data - model.
- 80.30 Demote a user to a person + model.
- 80.30 Demote a user to a person
The parties and groups system provides a well defined API call that demotes an existing user entity to a person entity by running the appropriate transactions on the existing user. This API is subject to the constraints - laid out in the data model.
- 90.10 Update a party + laid out in the data model.
- 90.10 Update a party
The programmer should be able to modify, add, and delete attributes on any - party. This API is subject to the constraints laid out in the data model.
- 95.10 Get the attributes of a party + party. This API is subject to the constraints laid out in the data model.
- 95.10 Get the attributes of a party
The programmer should be able to view the attributes on any party. This - API is subject to the constraints laid out in the data model.
- 100.10 Delete a party + API is subject to the constraints laid out in the data model.
- 100.10 Delete a party
The system provides an API for deleting a party. This API is subject to - the constraints laid out in the data model.
100.30 The system may provide a single API call to remove - the party from all groups and then delete the party.
100.40 In the case of a group, the system may provide a + the constraints laid out in the data model.
100.30 The system may provide a single API call to remove + the party from all groups and then delete the party.
100.40 In the case of a group, the system may provide a single API call to remove all parties from a group and then delete the - group.
- 110.0 Add a party as a member of a group + group.
- 110.0 Add a party as a member of a group
The parties and groups system provides an API for adding a party as a member of a group. This API is subject to the constraints laid out in the - data model.
- 115.0 Add a group as a component of a second group + data model.
- 115.0 Add a group as a component of a second group
The parties and groups system provides an API for adding a group as a component of a second group. This API is subject to the constraints laid out - in the data model.
- 120.0 Remove a party as a member of a group + in the data model.
- 120.0 Remove a party as a member of a group
The parties and groups system provides an API for deleting a party's membership in a group. This API is subject to the constraints laid out in the - data model.
- 125.0 Remove a group as a component of a second - group + data model.
- 125.0 Remove a group as a component of a second + group
The parties and groups system provides an API for deleting a group's composition in a second group. This API is subject to the constraints laid - out in the data model.
- 130.0 Membership check + out in the data model.
- 130.0 Membership check
The parties and groups system provides an API for answering the question: - "Is party P a member of group - G?"
- 135.0 Composition check + "Is party P a member of group + G?"
- 135.0 Composition check
The parties and groups system provides an API for answering the question: - "Is group GC a component of group - GP?"
- 140.0 Get members query + "Is group GC a component of group + GP?"
- 140.0 Get members query
The parties and groups system provides an API for answering the question: - "Which parties are members of group G?"
- 145.0 Get components query + "Which parties are members of group G?"
- 145.0 Get components query
The parties and groups system provides an API for answering the question: - "Which groups are components of group G?"
- 150.0 Member-of-groups query + "Which groups are components of group G?"
- 150.0 Member-of-groups query
The parties and groups system provides an API for answering the question: - "Of which groups is party P a member?"
- 155.0 Component-of-groups query + "Of which groups is party P a member?"
- 155.0 Component-of-groups query
The parties and groups system provides an API for answering the question: - "Of which groups is group G a component?"
- 160.0 Allowed membership check + "Of which groups is group G a component?"
- 160.0 Allowed membership check
The parties and groups system provides an API for answering the question: - "Is party P allowed to become a member of group - G?"
- 165.0 Allowed composition check + "Is party P allowed to become a member of group + G?"
- 165.0 Allowed composition check
The parties and groups system provides an API for answering the question: - "Is group GC allowed to become a component - of group GP?"
- 170.0 Efficiency + "Is group GC allowed to become a component + of group GP?"
- 170.0 Efficiency
Since many pages at a site may check membership in a group before serving a page (e.g., as part of a general permissions check), the data model must support the efficient storage and retrieval of party attributes and - membership.
- 180.0 Ease of Use + membership.
- 180.0 Ease of Use
Since many SQL queries will check membership in a group as part of the -
whereclause, whatever mechanism is used to check membership in SQL - should be fairly small and simple.The user interface is a set of HTML pages that are used to drive the - underlying API. The user interface may provide the following functions:
200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks - outlined in 130.x to 165.x
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/16/2000 Rafael Schloming 0.2 Initial revision 08/19/2000 Mark Thomas 0.3 Edited and reviewed, conforms to requirements template 08/23/2000 Kai Wu 0.4 Further revised, added UI requirements 08/24/2000 Mark Thomas 0.5 Final edits, pending freeze 08/24/2000 Kai Wu 0.6 More revisions, added composition requirements 08/30/2000 Mark Thomas 0.7 More revisions, added composition requirements 09/08/2000 Mark Thomas View comments on this page at openacs.org + where clause, whatever mechanism is used to check membership in SQL + should be fairly small and simple.The user interface is a set of HTML pages that are used to drive the + underlying API. The user interface may provide the following functions:
200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks + outlined in 130.x to 165.x
Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 08/16/2000 Rafael Schloming 0.2 Initial revision 08/19/2000 Mark Thomas 0.3 Edited and reviewed, conforms to requirements template 08/23/2000 Kai Wu 0.4 Further revised, added UI requirements 08/24/2000 Mark Thomas 0.5 Final edits, pending freeze 08/24/2000 Kai Wu 0.6 More revisions, added composition requirements 08/30/2000 Mark Thomas 0.7 More revisions, added composition requirements 09/08/2000 Mark Thomas View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/high-avail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.html,v diff -u -r1.18.2.2 -r1.18.2.3 --- openacs-4/packages/acs-core-docs/www/high-avail.html 6 Jul 2009 11:14:26 -0000 1.18.2.2 +++ openacs-4/packages/acs-core-docs/www/high-avail.html 11 Sep 2009 23:41:26 -0000 1.18.2.3 @@ -1,2 +1,2 @@ - -High Availability/High Performance Configurations View comments on this page at openacs.org + +High Availability/High Performance Configurations View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/how-do-I.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.html,v diff -u -r1.21.2.2 -r1.21.2.3 --- openacs-4/packages/acs-core-docs/www/how-do-I.html 6 Jul 2009 11:14:26 -0000 1.21.2.2 +++ openacs-4/packages/acs-core-docs/www/how-do-I.html 11 Sep 2009 23:41:26 -0000 1.21.2.3 @@ -1,7 +1,7 @@ - -How Do I? The easiest way is to install the Edit-This-Page package.
Log in to the web site as an administrator.
Click on Admin > Install Software > Install from OpenACS Repository / Install new application
Choose Edit This Page and install
Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
Go to
/admin/permissionsand grant Create to Registered UsersSuppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
On the front page, click the
Adminbutton.On the administration page, click
Parameterslink.Change the parameter
IndexRedirectUrlto be the URI of the desired application. For a default weblogger installation, this would be. Note the trailing slash.weblogger/Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from
/var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
cp/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index*/var/lib/aolserver/$OPENACS_SERVICE_NAME/wwwEdit the new
index.adpto change the text; you shouldn't need to editindex.tclunless you are adding new functionality.Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:
+ +
How Do I? The easiest way is to install the Edit-This-Page package.
Log in to the web site as an administrator.
Click on Admin > Install Software > Install from OpenACS Repository / Install new application
Choose Edit This Page and install
Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
Go to /admin/permissions and grant Create to Registered Users
Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
On the front page, click the Admin button.
On the administration page, click Parameters link.
Change the parameter IndexRedirectUrl to be the URI of the desired application. For a default weblogger installation, this would be weblogger/. Note the trailing slash.
Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:
A templated page uses an ADP/TCL pair. The first line in the ADP file is usually: -
<master>If it appears exactly like this, without any arguments, the template processer uses
default-masterfor that subsite. For pages in/var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adpand the associated .tcl file. -The
default-masteris itself a normal ADP page. It draws the subsite navigation elements and invokessite-master(/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adpand .tcl)The
site-masterdraws site-wide navigation elements and invokesblank-master(/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adpand .tcl).
Blank-masterdoes HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
Steps to Reproduce. The events package does not allow users to register for new events.
Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.
Select an available event
A link such as
Registration: Deadline is 03/15/2004 10:00am. -» Login or sign up to register for this event.is visible. Click on "Login or sign up" -Complete a new registration. Afterwards, you should be redirected back to the same page.
Actual Results: The page says
"You do not have permission to register for this event."Expected results: A link or form to sign up for the event is shown.
Finding the problem. We start with the page that has the error. In the URL it's
http://myserver.net/events/event-info.tcl, so open the file/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line:set can_register_p [events::security::can_register_for_event_p -event_id $event_id]We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply
return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
Setting Permissions. A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
To grant permissions on a package, start at the site map. Find the event package and click "Set permissions".
Click "Grant Permission"
Grant the write permission to Registered Users.
OpenACS 5.0 offers a prettier version at /admin/applications.
View comments on this page at openacs.org +<master>If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file. +
The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).
Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
Steps to Reproduce. The events package does not allow users to register for new events.
Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.
Select an available event
A link such as Registration: Deadline is 03/15/2004 10:00am. +» Login or sign up to register for this event. is visible. Click on "Login or sign up" +
Complete a new registration. Afterwards, you should be redirected back to the same page.
Actual Results: The page says "You do not have permission to register for this event."
Expected results: A link or form to sign up for the event is shown.
Finding the problem. We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line:
set can_register_p [events::security::can_register_for_event_p -event_id $event_id]We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply
return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
Setting Permissions. A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
To grant permissions on a package, start at the site map. Find the event package and click "Set permissions".
Click "Grant Permission"
Grant the write permission to Registered Users.
OpenACS 5.0 offers a prettier version at /admin/applications.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-convert.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v diff -u -r1.20.2.2 -r1.20.2.3 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 6 Jul 2009 11:14:26 -0000 1.20.2.2 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 11 Sep 2009 23:41:26 -0000 1.20.2.3 @@ -1,5 +1,5 @@ - -How to Internationalize a Package Tip
+ +
How to Internationalize a Package Tip
For multilingual websites we recommend using the UTF8 charset. In order for AOLserver to use utf8 you need to set the config parameters OutputCharset and @@ -9,53 +9,53 @@ variable set to .UTF8. You should set this variable in the nsd-oracle run script (use the acs-core-docs/www/files/nds-oracle.txt template file). -
Replace all text with temporary message tags. From
/acs-admin/apm/, select a +
Replace all text with temporary message tags. From/acs-admin/apm/, select a package and then click on -
Internationalization, then -Convert ADP, Tcl, and SQL files to using the - message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.
Replace the temporary message tags in ADP files. From the same
Convert ADP ...page in/acs-admin/apmas in the last step, repeat the process but deselectFind human language text ...and selectReplace <# ... #> tags ...and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.Replace human-readable text in TCL files with temporary tags. Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (
_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:-set title "Messages for $a(name) in $b(label)" -set context [list [list . "SimPlay"] \ + Internationalization, then + Convert ADP, Tcl, and SQL files to using the + message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.
Replace the temporary message tags in ADP files. From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat the process but deselect Find human language text ... and select Replace <# ... #> tags ... and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.
Replace human-readable text in TCL files with temporary tags. Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:
+set title "Messages for $a(name) in $b(label)" +set context [list [list . "SimPlay"] \ [list [export_vars -base case-admin { case_id }] \ - "Administer $a(name)"] \ - "Messages for $a(name)"] + "Administer $a(name)"] \ + "Messages for $a(name)"]... and here is the same file after temporary message tags have been manually added:
set title <#admin_title Messages for %a.name% in %b.label%#> set context [list [list . <#_ SimPlay#>] \ [list [export_vars -base case-admin { case_id }] \ <#_ Administer %a.name%#>] \ <#_ Messages for %a.name%#>] -Note that the message key
case_admin_page_titlewas manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing -Replace the temporary message tags in TCL files. Repeat step 2 for tcl files. Here is the example TCL file after conversion:
+Note that the message key case_admin_page_title was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing +
Replace the temporary message tags in TCL files. Repeat step 2 for tcl files. Here is the example TCL file after conversion:
set title [_ simulation.admin_title] set context [list [list . [_ simulation.SimPlay]] \ [list [export_vars -base case-admin { case_id }] \ [_ simulation.lt_Administer_name_gt]] \ [_ simulation.lt_Messages_for_role_pre]] -Internationalize SQL Code. If there is any user-visible TCL code in the .sql or .xql files, internationalize that the same way as for the TCL files.
Internationalize Package Parameters. - See Multilingual APM Parameters -
Internationalize Date and Time queries.
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" * -grep -r "to_date.*H" * -In SQL statements, replace the format string with the ANSI standard format,
YYYY-MM-DD HH24:MI:SSand change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_prettybecomes
to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansiIn TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function
lc_time_system_to_conn:-set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with
lc_time_conn_to_system. -When a datetime field will be displayed, format it using the localizing function
lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are:%x, %X, %q, %Q, and %c.set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]- Use the
_prettyversion in your ADP page. -
+
Internationalize SQL Code. If there is any user-visible TCL code in the .sql or .xql files, internationalize that the same way as for the TCL files.
Internationalize Package Parameters. + See Multilingual APM Parameters +
Internationalize Date and Time queries.
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" * +grep -r "to_date.*H" * +In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_prettybecomes
to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansiIn TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
+set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. +
When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]+ Use the _pretty version in your ADP page. +
%c: Long date and time (Mon November 18, 2002 12:00 AM) -
+
%x: Short date (11/18/02) -
+
%X: Time (12:00 AM) -
+
%q: Long date without weekday (November 18, 2002) -
+
%Q: Long date with weekday (Monday November 18, 2002)
- The "q" format strings are OpenACS additions; the rest follow unix standards (see
man - strftime). -Internationalize Numbers. - To internationalize numbers, use
lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. -Internationalizing Forms. When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Checking the Consistency of Catalog Files. + The "q" format strings are OpenACS additions; the rest follow unix standards (see man + strftime). +
Internationalize Numbers. + To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. +
Internationalizing Forms. When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Checking the Consistency of Catalog Files. This section describes how to check that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that @@ -64,23 +64,23 @@ are always is done with one of the valid lookups described above. The script further assumes that you have perl installed and in your path. Run the script like this: -
+ acs-lang/bin/check-catalog.sh package_key -+where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files. -
Replace complicated keys with longer, simpler keys. When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an
ifcommand at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:
<p class="form-help-text"><b>Invitations</b> are sent, - when this wizard is completed and casting begins.</p>has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:
Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:
<p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, +
Replace complicated keys with longer, simpler keys. When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.
The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:
<p class="form-help-text"><b>Invitations</b> are sent, + when this wizard is completed and casting begins.</p>has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:
Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:
<p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, when this wizard is completed and casting begins.#> - </p>Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:
Select which case <if @simulation.casting_type@ eq "open">and + </p>Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:
Select which case <if @simulation.casting_type@ eq "open">and role</if> to join, or create a new case for yourself. If you do not -select a case <if @simulation.casting_type@ eq "open">and role</if> +select a case <if @simulation.casting_type@ eq "open">and role</if> to join, you will be automatically assigned to a case <if -@simulation.casting_type@ eq "open">and role</if> when the -simulation begins.... can be rewritten:
<if @simulation.casting_type@ eq "open"> +@simulation.casting_type@ eq "open">and role</if> when the +simulation begins.... can be rewritten:
<if @simulation.casting_type@ eq "open"> Select which case and role to join, or create a new case for yourself. If you do not select a case and role to join, you will @@ -96,7 +96,7 @@ begins. </else>Another example, where bugs are concatenated with a number:
<if @components.view_bugs_url@ not nil> - <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component"> + <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component"> </if> @components.num_bugs@ <if @components.num_bugs@ eq 1> @@ -110,7 +110,7 @@ </if> <if @components.view_bugs_url@ not nil> -<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#"> +<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#"> </if> @components.num_bugs@ <if @components.num_bugs@ eq 1> @@ -124,39 +124,39 @@ </if>It would probably be better to do this as something like:
<if @components.view_bugs_url@ not nil> <if @components.num_bugs@ eq 1> - <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a> + <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a> </if><else> - <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a> + <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a> </else> -</if>Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:
Original code:
multirow append links "New [bug_tracker::conn Bug]"Problematic conversion:
multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"Better conversion:
set bug_label [bug_tracker::conn Bug] -multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"... and include the variable in the key:
"New %bug_label%". This gives translators more control over the phrase.In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):
<a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@"> -@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>Avoid unnecessary duplicate keys. When phrases are exactly the same in several places, use a single key.
For common words such as - Yes and No, you can use a library of keys at acs-kernel. +</if>
Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:
Original code:
multirow append links "New [bug_tracker::conn Bug]"Problematic conversion:
multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"Better conversion:
set bug_label [bug_tracker::conn Bug] +multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.
In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):
<a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@"> +@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>Avoid unnecessary duplicate keys. When phrases are exactly the same in several places, use a single key.
For common words such as + Yes and No, you can use a library of keys at acs-kernel. For example, instead of using -
myfirstpackage.Yes, you - can useacs-kernel.Yes. - You can also use the Message Key Search facility to find duplicates. + myfirstpackage.Yes, you + can use acs-kernel.Yes. + You can also use the Message Key Search facility to find duplicates. Be careful, however, building up sentences from keys because grammar and other elements may not be consistent - across different locales.Additional discussion: Re: - Bug 961 ("Control Panel" displayed instead of - "Administer"), Translation - server upgraded, and Localization questions.
Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
For example, the original code is
workflow::case::add_log_data \ + across different locales.Additional discussion: Re: + Bug 961 ("Control Panel" displayed instead of + "Administer"), Translation + server upgraded, and Localization questions.
Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
For example, the original code is
workflow::case::add_log_data \ -entry_id $entry_id \ - -key "resolution" \ + -key "resolution" \ -value [db_string select_resolution_code {}]This is incorrectly internationalized to
workflow::case::add_log_data \ -entry_id $entry_id \ - -key "[_ bug-tracker.resolution]" \ - -value [db_string select_resolution_code {}]But
resolutionis a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:{show_patch_status "open"}It is broken if changed to
{show_patch_status "[_ bug-tracker.open]"}Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
-<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg> -<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch + -key "[_ bug-tracker.resolution]" \ + -value [db_string select_resolution_code {}]But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:
{show_patch_status "open"}It is broken if changed to
{show_patch_status "[_ bug-tracker.open]"}Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
+<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg> +<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch and users with write permission on this Bug Tracker project (package instance) may do so.</msg> -<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch -and users with write permission on the Bug Tracker project (package instance) may do so.</msg>These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? -
Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:
<msg key="Fix">for version</msg> -<msg key="Fix_1">for</msg> -<msg key="Fix_2">for Bugs</msg>Another example:
Bug-tracker component maintainer"was converted to"[_ bug-tracker.Bug-tracker]". Instead, it should bebug_tracker_component_maintainer.Translations in Avoid "clever" message reuse. Translations may need to differ depending on the context in which +<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch +and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? +
Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:
<msg key="Fix">for version</msg> +<msg key="Fix_1">for</msg> +<msg key="Fix_2">for Bugs</msg>Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.
Translations in Avoid "clever" message reuse. Translations may need to differ depending on the context in which the message appears. -
Avoid plurals. Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl. Watch out for quoting and escaping when editing text that is also code. For example, the original string
set title "Patch \"$patch_summary\" is nice."breaks if the message text retains all of the escaping that was in the tcl command:
<msg>Patch \"$patch_summary\" is nice.</msg>When it becomes a key, it should be:
<msg>Patch "$patch_summary" is nice.</msg>Also, some keys had %var;noquote%, which is not needed since those +
Avoid plurals. Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl. Watch out for quoting and escaping when editing text that is also code. For example, the original string
set title "Patch \"$patch_summary\" is nice."breaks if the message text retains all of the escaping that was in the tcl command:
<msg>Patch \"$patch_summary\" is nice.</msg>When it becomes a key, it should be:
<msg>Patch "$patch_summary" is nice.</msg>Also, some keys had %var;noquote%, which is not needed since those variables are not quoted (and in fact the variable won't even be - recognized so you get the literal %var;noquote% in the output).
Be careful with curly brackets. Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code
array set names { key "Pretty" ...}... if converted to
array set names { key "[_bug-tracker.Pretty]" ...}... won't work since the _ func will not be called. Instead, it should be
array set names [list key [_bug-tracker.Pretty] ...]View comments on this page at openacs.org + recognized so you get the literal %var;noquote% in the output).Be careful with curly brackets. Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code
array set names { key "Pretty" ...}... if converted to
array set names { key "[_bug-tracker.Pretty]" ...}... won't work since the _ func will not be called. Instead, it should be
array set names [list key [_bug-tracker.Pretty] ...]View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-design.html,v diff -u -r1.10.2.1 -r1.10.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-design.html 10 Jun 2009 22:24:07 -0000 1.10.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-design.html 11 Sep 2009 23:41:26 -0000 1.10.2.2 @@ -1,3 +1,3 @@ - -Design Notes User locale is a property of ad_conn,
ad_conn locale. The request processor sets this by callinglang::conn::locale, which looks for the following in order of precedence:
Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (
Accept-LanguageHTTP header)Use system locale (an APM parameter for acs_lang)
default to en_US
For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the
_function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is + +Design Notes User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:
Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US
For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is found, then that locale is offered instead.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-introduction.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-introduction.html,v diff -u -r1.12.2.1 -r1.12.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.html 10 Jun 2009 22:24:07 -0000 1.12.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.html 11 Sep 2009 23:41:26 -0000 1.12.2.2 @@ -1,20 +1,20 @@ - -How Internationalization/Localization works in OpenACS + +
How Internationalization/Localization works in OpenACS This document describes how to develop internationalized OpenACS packages, including writing new packages with internationalization and converting old packages. Text that - users might see is "localizable text"; replacing monolingual text + users might see is "localizable text"; replacing monolingual text and single-locale date/time/money functions with generic - functions is "internationalization"; translating first - generation text into a specific language is "localization." At + functions is "internationalization"; translating first + generation text into a specific language is "localization." At a minimum, all packages should be internationalized. If you do not also localize your package for different locales, volunteers - may use a public "localization server" to submit suggested text. + may use a public "localization server" to submit suggested text. Otherwise, your package will not be usable for all locales.
The main difference between monolingual and internationalized packages is that all user-visible text in the code of an internationalized - package are coded as "message keys." The message keys + package are coded as "message keys." The message keys correspond to a message catalog, which contains versions of the text for each available language. Script files (.adp and .tcl and .vuh), database files (.sql), and APM parameters are affected. @@ -33,33 +33,33 @@ which are static and mostly text, it may be easier to create a new ADP page for each language. In this case, the pages are distinguished by a file naming convention. -
OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.
If the request processor finds a file named
filename.locale.adp, where locale matches the user's locale, it will process that file instead offilename.adp. For example, for a user with localetl_PH, the fileindex.tl_PH.adp, if found, will be used instead ofindex.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.+
OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.
If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.
Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in the desired locale. Message keys themselves should be in ASCII English, as should all code. Three different syntaxes are possible for message keys.
- "Short" syntax is the recommended syntax and should be used + "Short" syntax is the recommended syntax and should be used for new development. When internationalizing an existing - package, you can use the "temporary" syntax, which the APM can + package, you can use the "temporary" syntax, which the APM can use to auto-generate missing keys and automatically translate - to the short syntax. The "verbose" syntax is useful while + to the short syntax. The "verbose" syntax is useful while developing, because it allows default text so that the page is usable before you have done - localization.
- The short: -
#package_key.message_key#+ localization.
+ The short: + #package_key.message_key#
The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable. Example: #forum.title# -
- The verbose:
<trn - key="package_key.message_key" - locale="locale">default - text</trn>++ The verbose: <trn + key="package_key.message_key" + locale="locale">default + text</trn>
The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended @@ -68,11 +68,11 @@ in the message catalog yet, because what it'll do is create the message key with the default text from the tag as the localized message. Example: <trn - key="forum.title" locale="en_US">Title</trn> -
- The temporary: -
<#message_key - original text#>+ key="forum.title" locale="en_US">Title</trn> ++ The temporary: + <#message_key + original text#>
This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that @@ -83,21 +83,21 @@ auto-generated by the APM. Example: <_ Title>
We recommend the short notation for new package development. -
In adp files message lookups are typically done with the syntax -
\#package_key.message_key\#. In Tcl + \#package_key.message_key\#. In Tcl files all message lookups *must* be on either of the following formats:-
Typical static key lookup:
[_ package_key.message_key]- The message key and package key used here must be string literals, they can't result from variable evaluation.- Static key lookup with non-default locale:
[lang::message::lookup $locale package_key.message_key]- The message key and package key used here must be string literals, they can't result from variable evaluation.- Dynamic key lookup:
[lang::util::localize $var_with_embedded_message_keys]- In this case the message keys in the variablevar_with_embedded_message_keysmust appear as string literals\#package_key.message_key\#somewhere in the code. Here is an example of a dynamic lookup: -set message_key_array { +
Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
+ Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
+ Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in the code. Here is an example of a dynamic lookup: + set message_key_array { dynamic_key_1 \#package_key.message_key1\# dynamic_key_2 \#package_key.message_key2\# } set my_text [lang::util::localize $message_key_array([get_dynamic_key])] - +
Translatable texts in page TCL scripts are often found in page titles, @@ -106,16 +106,16 @@ that can be used on Linux to highlight translatable text in TCL files:
# Find text in double quotes -find -iname '*.tcl'|xargs egrep -i '"[a-z]'+find -iname '*.tcl'|xargs egrep -i '"[a-z]' # Find untranslated text in form labels, options and values -find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'+find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$' # Find text in page titles and context bars -find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'+find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#' # Find text in error messages -find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'+find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'You may mark up translatable text in TCL library files and TCL pages @@ -124,82 +124,82 @@ variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog (remember that translators is made easier the longer the phrases to translate are). In those cases, follow these steps: -
+
For each message call in the text, decide on a variable name and replace the procedure call with a variable lookup on the syntax %var_name%. Remember - to initialize a tcl variable with the same name on some line above the text.
If the text is in a tcl file you must replace variable lookups - (occurences of $var_name or ${var_name}) with %var_name%
You are now ready to follow the normal procedure and mark up the text using a + to initialize a tcl variable with the same name on some line above the text.
If the text is in a tcl file you must replace variable lookups + (occurences of $var_name or ${var_name}) with %var_name%
You are now ready to follow the normal procedure and mark up the text using a tempoarary message tag (<#_ text_with_percentage_vars#>) and run the action replace tags with keys in the APM.
The variable values in the message are usually fetched with upvar, here is an example from dotlrn: -
- ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] - must have <em>no</em>[parameter::get -parameter class_instances_pretty_plural] to be deleted" -+ + ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] + must have <em>no</em>[parameter::get -parameter class_instances_pretty_plural] to be deleted" + was replaced by: -+ set subject [parameter::get -localize -parameter classes_pretty_name] set class_instances [parameter::get -localize -parameter class_instances_pretty_plural] ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted] -+This kind of interpolation also works in adp files where adp variable values will be inserted into the message.
Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:
-set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]] +set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]] ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list] -+When we were done going through the tcl files we ran the following commands to check for mistakes:
# Message tags should usually not be in curly braces since then the message lookup may not be # executed then (you can usually replace curly braces with the list command). Find message tags # in curly braces (should return nothing, or possibly a few lines for inspection) -find -iname '*.tcl'|xargs egrep -i '\{.*<#'+find -iname '*.tcl'|xargs egrep -i '\{.*<#' # Check if you've forgotten space between default key and text in message tags (should return nothing) -find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'+find -iname '*.tcl'|xargs egrep -i '<#_[^ ]' # Review the list of tcl files with no message lookups -for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done+for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; doneWhen you feel ready you may vist your package in the - package manager - and run the action "Replace tags with keys - and insert into catalog" on the TCL files that you've edited to + package manager + and run the action "Replace tags with keys + and insert into catalog" on the TCL files that you've edited to replace the temporary tags with calls to the message lookup procedure. -
+
Most date, time, and number variables are calculated in TCL files. Dates and times must be converted when stored in the database, when retrieved from the database, and when displayed. All dates are stored in the database in the server's timezone, which is an APM Parameter set at -
/acs-lang/admin/set-system-timezone+ /acs-lang/admin/set-system-timezone and readable at -lang::system::timezone.. When + lang::system::timezone.. When retrieved from the database and displayed, dates and times must be localized to the user's locale. -Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, you should use message keys using the short notation above, - i.e. #package_key.message_key#. + i.e. #package_key.message_key#.
In order to avoid clashes with other uses of the hash character, you need to tell the APM that the parameter value needs to be localized when retrieving it. You do that by saying: - parameter::get -localize. + parameter::get -localize.
Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package.
Parameter Name Parameter Value class_instance_pages_csv #dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column departments_pretty_name #departments_pretty_name# Then, depending on how we retrieve the value, here's what we get: -
Command used to retrieve Value Retrieved Value parameter::get -localize -parameter class_instances_pages_csv Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column parameter::get -localize -parameter departments_pretty_name Abteilung parameter::get -parameter departments_pretty_name #departments_pretty_name# +
Command used to retrieve Value Retrieved Value parameter::get -localize -parameter class_instances_pages_csv Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column parameter::get -localize -parameter departments_pretty_name Abteilung parameter::get -parameter departments_pretty_name #departments_pretty_name# The value in the rightmost column in the table above is the value returned by an invocation of parameter::get. Note that for localization to happen you must use the -localize flag. @@ -209,5 +209,5 @@ locale.
Developers are responsible for creating the keys in the message - catalog, which is available at
/acs-lang/admin/+ catalog, which is available at /acs-lang/admin/View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-overview.html,v diff -u -r1.10.2.1 -r1.10.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-overview.html 10 Jun 2009 22:24:07 -0000 1.10.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.html 11 Sep 2009 23:41:26 -0000 1.10.2.2 @@ -1,2 +1,2 @@ - -Internationalization and Localization Overview Table 13.1. Internationalization and Localization Overview
Stage Task Who Internationalization Package Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information) Package Developer Release Management The newly internationalized package is released. Package Developer The translation server is updated with the new package. Translation server maintainers Localization Translators work in their respective locales to write text for each message key. (More information) Translators Release Management The translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server. Translation server maintainers The catalog files are committed to the OpenACS code base. Translation server maintainers A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository. Release Manager Upgrading Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS Site Administrators Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten. Site Administrators View comments on this page at openacs.org + +Internationalization and Localization Overview Table 13.1. Internationalization and Localization Overview
Stage Task Who Internationalization Package Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information) Package Developer Release Management The newly internationalized package is released. Package Developer The translation server is updated with the new package. Translation server maintainers Localization Translators work in their respective locales to write text for each message key. (More information) Translators Release Management The translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server. Translation server maintainers The catalog files are committed to the OpenACS code base. Translation server maintainers A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository. Release Manager Upgrading Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS Site Administrators Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten. Site Administrators View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -r1.20.2.1 -r1.20.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 10 Jun 2009 22:24:07 -0000 1.20.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 11 Sep 2009 23:41:26 -0000 1.20.2.2 @@ -1,19 +1,19 @@ - -OpenACS Internationalization Requirements by Henry Minsky, - Yon Feldman, - Lars Pind, - Peter Marklund, - Christian Hvid, + +
OpenACS Internationalization Requirements This document describes the requirements for functionality in the OpenACS platform to support globalization of the core and optional modules. The goal is to make it possible to support delivery of applications which work properly in multiple locales with the lowest development and maintenance cost. -
- internationalization (i18n)
+
- internationalization (i18n)
The provision within a computer program of the capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets. @@ -28,8 +28,8 @@ A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization. -
The Mozilla project suggests keeping two catchy phrases in +mind when thinking about globalization:
One code base for the world
English is just another language
Building an application often involves making a number of assumptions on the part of the developers which depend on their own culture. These include constant strings in the user interface and system error messages, names of countries, cities, order of given @@ -44,21 +44,21 @@ kind of globalization support would be large and ongoing, since without a mechanism to incorporate the locale-specific changes cleanly back into the code base, it would require making a new fork -of the source code for each locale.
A globalized application will perform some or all of the +of the source code for each locale.
A globalized application will perform some or all of the following steps to handle a page request for a specific -locale:
Decide what the target locale is for an incoming page -request
Decide which character set encoding the output should be -delivered in
If a script file to handle the request needs to be loaded +locale:
Decide what the target locale is for an incoming page +request
Decide which character set encoding the output should be +delivered in
If a script file to handle the request needs to be loaded from disk, determine if a character set conversion needs to be -performed when loading the script
If needed, locale-specific resources are fetched. These can +performed when loading the script
If needed, locale-specific resources are fetched. These can include text, graphics, or other resources that would vary with the -target locale.
If content data is fetched from the database, check for -locale-specific versions of the data (e.g. country names).
Source code should use a message catalog API to translate -constant strings in the code to the target locale
Perform locale-specific linguistic sorting on data if -needed
If the user submitted form input data, decide what character +target locale.
If content data is fetched from the database, check for +locale-specific versions of the data (e.g. country names).
Source code should use a message catalog API to translate +constant strings in the code to the target locale
Perform locale-specific linguistic sorting on data if +needed
If the user submitted form input data, decide what character set encoding conversion if any is needed. Parse locale-specific -quantities if needed (number formats, date formats).
If templating is being used, select correct locale-specific -template to merge with content
Format output data quantities in locale-specific manner +quantities if needed (number formats, date formats).
If templating is being used, select correct locale-specific +template to merge with content
Format output data quantities in locale-specific manner (date, time, numeric, currency). If templating is being used, this may be done either before and/or after merging the data with a template.
Since the internationalization APIs may potentially be used @@ -69,68 +69,68 @@ Java which we will want to move to. So the design to meet the requirements will tend to rely on these capabilities, or close approximations to them where possible, in order to make it easier -to maintain Tcl and Java OpenACS versions.
Here are the cases that we need to be able to handle -efficiently:
A developer needs to author a web site/application in a +to maintain Tcl and Java OpenACS versions.
Here are the cases that we need to be able to handle +efficiently:
A developer needs to author a web site/application in a language besides English, and possibly a character set besides ISO-8859-1. This includes the operation of the OpenACS itself, i.e., navigation, admin pages for modules, error messages, as well as additional modules or content supplied by the web site developer.
What do they need to modify to make this work? Can their localization work be easily folded in to future releases of -OpenACS?
A developer needs to author a web site which operates in +OpenACS?
A developer needs to author a web site which operates in multiple languages simultaneously. For example, www.un.org with content and navigation in multiple languages.
The site would have an end-user visible UI to support these languages, and the content management system must allow articles to be posted in these languages. In some cases it may be necessary to make the modules' admin UI's operate in more than one supported language, while in other cases the backend admin -interface can operate in a single language.
A developer is writing a new module, and wants to make it +interface can operate in a single language.
A developer is writing a new module, and wants to make it easy for someone to localize it. There should be a clear path to author the module so that future developers can easily add support for other locales. This would include support for creating resources such as message catalogs, non-text assets such as graphics, and use of templates which help to separate application -logic from presentation.
Other application servers: ATG Dyanmo, Broadvision, Vignette, -... ? Anyone know how they deal with i18n ?
System/Package "coversheet" - where all -documentation for this software is linked off of
User's guide
Other-cool-system-related-to-this-one -document
Other application servers: ATG Dyanmo, Broadvision, Vignette, +... ? Anyone know how they deal with i18n ?
System/Package "coversheet" - where all +documentation for this software is linked off of
User's guide
Other-cool-system-related-to-this-one +document
LI18NUX 2000 Globalization Specification: -http://www.li18nux.net/
Mozilla +http://www.li18nux.net/
Mozilla i18N Guidelines: -http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html
ISO +http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html
ISO 3166-1:1997 +http://sunsite.berkeley.edu/amher/iso_639.html
Test plan
Competitive system(s)
Because the requirements for globalization affect many areas +http://www.niso.org/3166.html
IANA +Registry of Character Sets
Test plan
Competitive system(s)
Because the requirements for globalization affect many areas of the system, we will break up the requirements into phases, with a base required set of features, and then stages of increasing -functionality.
10.0
A standard representation of locale will be used throughout the system. A locale refers to a language and territory, and is uniquely identified by a combination of ISO language and ISO country abbreviations.
See -Content +Content Repository Requirement 100.20
10.10 Provide a consistent representation and API for creating and referencing a locale
10.20 There will be a Tcl library of locale-aware formatting and parsing functions for numbers, dates and times. Note that Java has builtin support for these already.
10.30 For each locale there will be -default date, number and currency formats. Currency i18n is -NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their -servers to use new locales via the APM. NOT IMPLEMENTED in +default date, number and currency formats. Currency i18n is +NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their +servers to use new locales via the APM. NOT IMPLEMENTED in 5.0.0; current workaround is to get an xml file and load it -manually.
20.0
The request processor must have a mechanism for associating a locale with each request. This locale is then used to select the appropriate template for a request, and will also be passed as the locale argument to the message catalog or locale-specific formatting functions.
20.10 The locale for a request should be computed by the following method, in descending order of -priority:
get locale associated with subsite or package id
get locale from user preference
get locale from site wide default
20.20 An API will be provided for +priority:
get locale associated with subsite or package id
get locale from user preference
get locale from site wide default
20.20 An API will be provided for getting the current request locale from the -
ad_connstructure.30.0
A mechanism must be provided for a developer to group a set of arbitrary content resources together, keyed by a unique identifier and a locale.
For example, what approaches could be used to implement a localizable nav-bar mechanism for a site? A navigation bar might be @@ -142,7 +142,7 @@ functionality might include using templates, Java ResourceBundles, content-item containers in the Content Repository, or some convention assigning a common prefix to key strings in the message -catalog.
40.0
A message catalog facility will provide a database of +catalog.
40.0
A message catalog facility will provide a database of translations for constant strings for multilingual applications. It must support the following:
40.10 Each message will referenced via unique a key.
40.20 The key for a message will have @@ -167,7 +167,7 @@ is modified, the other translations of that string can be flagged as needing update.
40.90 The message lookup must be as efficient as possible so as not to slow down the delivery of -pages.
Character Sets
50.0 A locale will have a primary associated character set which is used to encode text in the language. When given a locale, we can query the system for the associated character set to use.
The assumption is that we are going to use Unicode in our @@ -177,12 +177,12 @@ browsers and authoring tools, the system must be able to read and write other character sets. In particular, conversions to and from Unicode will need to be explicitly performed at the following -times:
Loading source files (.tcl or .adp) or content files from the -filesystem
Accepting form input data from users
Delivering text output to a browser
Composing an email message
Writing data to the filesystem
Acs-templating does the following.
When the acs-templating package opens an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. -Writing Files
When the acs-templating package writes an an ADP or +times:
Loading source files (.tcl or .adp) or content files from the +filesystem
Accepting form input data from users
Delivering text output to a browser
Composing an email message
Writing data to the filesystem
Acs-templating does the following.
When the acs-templating package opens an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. +Writing Files
When the acs-templating package writes an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, - then acs-templating assumes it's that charset.
There are two classes of Tcl files loaded by the system; + then acs-templating assumes it's that charset.
There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, which are run on each page request.
Should we require all Tcl files be stored as UTF8? That seems too much of a burden on developers.
50.10 Tcl library files can be authored @@ -191,31 +191,31 @@ filename.
50.20 Tcl page script files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from - the filename.
50.30 Data which is submitted with a HTTP request using a GET or POST method may be in any character set. The system must be able to determine the encoding of the form data and convert it to Unicode on demand.
50.35 The developer must be able to override the default system choice of character set when parsing - and validating user form data. INCOMPLETE - form + and validating user form data. INCOMPLETE - form widgets in acs-templating/tcl/date-procs.tcl are not internationalized. Also, acs-templating's UI needs to be internationalized by replacing all user-visible strings with - message keys.
50.30.10In Japan and some + message keys.
50.30.10In Japan and some other Asian languages where there are multiple character set encodings in common use, the server may need to attempt to do an auto-detection of the character set, because buggy browsers may - submit form data in an unexpected alternate encoding.
50.40 The output character set for a + submit form data in an unexpected alternate encoding.
50.40 The output character set for a page request will be determined by default by the locale associated with the request (see requirement 20.0).
50.50 It must be possible for a developer to manually override the output character set encoding for a request using an API function. -
60.10 All OpenACS error messages must use the message catalog and the request locale to generate error -message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as +message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as 404, 500, etc must also be delivered in the appropriate locale.
60.30 Where files are written or read from disk, their filenames must use a character set and character -values which are safe for the underlying operating system.
70.0 For a given abstract URL, the +values which are safe for the underlying operating system.
70.0 For a given abstract URL, the designer may create multiple locale-specific template files may be created (one per locale or language)
70.10 For a given page request, the system must be able to select an approprate locale-specific @@ -226,28 +226,28 @@ current request locale.
70.30 A template file may be created in any character set. The system must have a way to know which character set a template file contains, so it can properly process -it.
70.50 The properties of a datasource column may include a datatype so that the templating system can format the output for the current locale. The datatype is defined by a standard OpenACS datatype plus a format token or format string, for example: a date column might be specified as 'current_date:date LONG,' or 'current_date:date -"YYYY-Mon-DD"'
70.60 The forms API must support +"YYYY-Mon-DD"'
70.60 The forms API must support construction of locale-specific HTML form widgets, such as date entry widgets, and form validation of user input data for locale-specific data, such as dates or numbers. NOT IMPLEMENTED in 5.0.0.
70.70 For forms which allow users to upload files, a standard method for a user to indicate the charset of a text file being uploaded must be provided.
Design note: this presumably applies to uploading -data to the content repository as well
80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way.
80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a -given locale with
ORDER BYclauses in +given locale with ORDER BY clauses in queries.80.40 The system must handle full-text -search in any supported language.
90.10 Provide API support for specifying a time zone
90.20 Provide an API for computing time and date operations which are aware of timezones. So for example a calendar module can properly synchronize items inserted into a @@ -258,29 +258,29 @@ zone preference should be attached via a session or else UTC should be used to display every date and time.
90.60 The default if we can't determine a time zone is to display all dates and times in some -universal time zone such as GMT.
100.10 Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that column size declarations in the schema are large enough to accomodate required data (such as email addresses in -Japanese). Since 5.0.0, this is covered in the database -install instructions for both PostgreSQL and Oracle.
When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be able to specify what character set encoding to use, defaulting to UTF-8.
110.10 The email message sending API will allow for a character set encoding to be specified.
110.20 The email accepting API allows for character set to be parsed correctly (the message has a MIME - character set content type header)
Mail is not internationalized. The following issues must be addressed.
+ character set content type header)
Mail is not internationalized. The following issues must be addressed.
Many functions still call ns_sendmail. This means that there are different end points for sending mail. This should be changed to use the acs-mail-lite API instead. -
+
Consumers of email services must do the following: Determine the appropriate language or languages to use for the message subject and message body and localize them (as in notifications). -
Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?
Incoming mail should be localized.
+
Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?
Incoming mail should be localized.
Because globalization touches many different parts of the system, we want to reduce the implementation risk by breaking the implementation into phases. -
Document Revision # Action Taken, Notes When? By Whom? 1 Updated with results of MIT-sponsored i18n work at Collaboraid. 14 Aug 2003 Joel Aufrecht 0.4 converting from HTML to DocBook and importing the document to the OpenACS +
Document Revision # Action Taken, Notes When? By Whom? 1 Updated with results of MIT-sponsored i18n work at Collaboraid. 14 Aug 2003 Joel Aufrecht 0.4 converting from HTML to DocBook and importing the document to the OpenACS kernel documents. This was done as a part of the internationalization of - OpenACS and .LRN for the Heidelberg University in Germany 12 September 2002 Peter Marklund 0.3 comments from Christian 1/14/2000 Henry Minsky 0.2 Minor typos fixed, clarifications to wording 11/14/2000 Henry Minsky 0.1 Creation 11/08/2000 Henry Minsky View comments on this page at openacs.org + OpenACS and .LRN for the Heidelberg University in Germany12 September 2002 Peter Marklund 0.3 comments from Christian 1/14/2000 Henry Minsky 0.2 Minor typos fixed, clarifications to wording 11/14/2000 Henry Minsky 0.1 Creation 11/08/2000 Henry Minsky View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-translators.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-translators.html,v diff -u -r1.10.2.1 -r1.10.2.2 --- openacs-4/packages/acs-core-docs/www/i18n-translators.html 10 Jun 2009 22:24:07 -0000 1.10.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.html 11 Sep 2009 23:41:26 -0000 1.10.2.2 @@ -1,2 +1,2 @@ - -Translator's Guide Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.
The basic steps for translators:
Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
Translating with Translator Mode. To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
While in Translator mode, a list of all message keys appears at the bottom of each page.
Batch translation. To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click
Batch edit these messages.When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script
/packages/acs-core-docs/www/files/create-new-catalog.sh.View comments on this page at openacs.org + +Translator's Guide Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.
The basic steps for translators:
Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
Translating with Translator Mode. To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
While in Translator mode, a list of all message keys appears at the bottom of each page.
Batch translation. To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.
When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -r1.28.2.1 -r1.28.2.2 --- openacs-4/packages/acs-core-docs/www/i18n.html 10 Jun 2009 22:24:07 -0000 1.28.2.1 +++ openacs-4/packages/acs-core-docs/www/i18n.html 11 Sep 2009 23:41:26 -0000 1.28.2.2 @@ -1,7 +1,7 @@ - -Chapter 13. Internationalization Table of Contents
- By Peter Marklund - and Lars Pind + +
Chapter 13. Internationalization Table of Contents
+ By Peter Marklund + and Lars Pind
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -r1.47.2.2 -r1.47.2.3 --- openacs-4/packages/acs-core-docs/www/index.html 6 Jul 2009 11:14:26 -0000 1.47.2.2 +++ openacs-4/packages/acs-core-docs/www/index.html 11 Sep 2009 23:41:26 -0000 1.47.2.3 @@ -1,4 +1,4 @@ - -OpenACS Core Documentation Table of Contents
- I. OpenACS For Everyone
- II. Administrator's Guide
- 2. Installation Overview
- 3. Complete Installation
- 4. Configuring a new OpenACS Site
- 5. Upgrading
- 6. Production Environments
- Starting and Stopping an OpenACS instance.
- AOLserver keepalive with inittab
- Running multiple services on one machine
- High Availability/High Performance Configurations
- Staged Deployment for Production Networks
- Installing SSL Support for an OpenACS service
- Set up Log Analysis Reports
- External uptime validation
- Diagnosing Performance Problems
- 7. Database Management
- 8. Backup and Recovery
- A. Install Red Hat 8/9
- B. Install additional supporting software
- Unpack the OpenACS tarball
- Initialize CVS (OPTIONAL)
- Add PSGML commands to emacs init file (OPTIONAL)
- Install Daemontools (OPTIONAL)
- Install qmail (OPTIONAL)
- Install Analog web file analyzer
- Install nspam
- Install Full Text Search using Tsearch2
- Install Full Text Search using OpenFTS (deprecated see tsearch2)
- Install nsopenssl
- Install tclwebtest.
- Install PHP for use in AOLserver
- Install Squirrelmail for use as a webmail system for OpenACS
- Install PAM Radius for use as external authentication
- Install LDAP for use as external authentication
- Install AOLserver 3.3oacs1
- C. Credits
- III. For OpenACS Package Developers
- 9. Development Tutorial
- 10. Development Reference
- OpenACS Packages
- OpenACS Data Models and the Object System
- The Request Processor
- The OpenACS Database Access API
- Using Templates in OpenACS
- Groups, Context, Permissions
- Writing OpenACS Application Pages
- Parties in OpenACS
- OpenACS Permissions Tediously Explained
- Object Identity
- Programming with AOLserver
- Using Form Builder: building html forms dynamically
- 11. Engineering Standards
- OpenACS Style Guide
- + +
OpenACS Core Documentation Table of Contents
- I. OpenACS For Everyone
- II. Administrator's Guide
- 2. Installation Overview
- 3. Complete Installation
- 4. Configuring a new OpenACS Site
- 5. Upgrading
- 6. Production Environments
- Starting and Stopping an OpenACS instance.
- AOLserver keepalive with inittab
- Running multiple services on one machine
- High Availability/High Performance Configurations
- Staged Deployment for Production Networks
- Installing SSL Support for an OpenACS service
- Set up Log Analysis Reports
- External uptime validation
- Diagnosing Performance Problems
- 7. Database Management
- A. Install Red Hat 8/9
- B. Install additional supporting software
- Unpack the OpenACS tarball
- Initialize CVS (OPTIONAL)
- Add PSGML commands to emacs init file (OPTIONAL)
- Install Daemontools (OPTIONAL)
- Install qmail (OPTIONAL)
- Install Analog web file analyzer
- Install nspam
- Install Full Text Search using Tsearch2
- Install Full Text Search using OpenFTS (deprecated see tsearch2)
- Install nsopenssl
- Install tclwebtest.
- Install PHP for use in AOLserver
- Install Squirrelmail for use as a webmail system for OpenACS
- Install PAM Radius for use as external authentication
- Install LDAP for use as external authentication
- Install AOLserver 3.3oacs1
- C. Credits
- III. For OpenACS Package Developers
- 8. Development Tutorial
- 9. Advanced Topics
- Write the Requirements and Design Specs
- Add the new package to CVS
- OpenACS Edit This Page Templates
- Adding Comments
- Admin Pages
- Categories
- Profile your code
- Prepare the package for distribution.
- Distributing upgrades of your package
- Notifications
- Hierarchical data
- Using .vuh files for pretty urls
- Laying out a page with CSS instead of tables
- Sending HTML email from your application
- Basic Caching
- Scheduled Procedures
- Enabling WYSIWYG
- Adding in parameters for your package
- Writing upgrade scripts
- Connect to a second database
- Future Topics
- 10. Development Reference
- OpenACS Packages
- OpenACS Data Models and the Object System
- The Request Processor
- The OpenACS Database Access API
- Using Templates in OpenACS
- Groups, Context, Permissions
- Parties in OpenACS
- OpenACS Permissions Tediously Explained
- Object Identity
- Programming with AOLserver
- Using Form Builder: building html forms dynamically
- 11. Engineering Standards
- 12. Documentation Standards
- 13. Internationalization
- D. Using CVS with an OpenACS Site
- IV. For OpenACS Platform Developers
- 14. Kernel Documentation
- Overview
- Object Model Requirements
- Object Model Design
- Permissions Requirements
- Permissions Design
- Groups Requirements
- Groups Design
- Package Manager Requirements
- Package Manager Design
- Database Access API
- OpenACS Internationalization Requirements
- Security Requirements
- Security Design
- Security Notes
- Request Processor Requirements
- Request Processor Design
- External Authentication Requirements
- 15. Releasing OpenACS
- Index
List of Figures
- 4.1. Site Templates
- 4.2. Granting Permissions
- 4.3. Granting Permissions in 5.0
- 5.1. Upgrading with the APM
- 5.2. Upgrading a local CVS repository
- 6.1. Multiple-server configuration
- 6.2. Simple A/B Deployment - Step 1
- 6.3. Simple A/B Deployment - Step 2
- 6.4. Simple A/B Deployment - Step 3
- 6.5. Complex A/B Deployment - Step 1
- 6.6. Complex A/B Deployment - Step 2
- 6.7. Complex A/B Deployment - Step 3
- 6.8. Query Analysis example
- 8.1. Backup and Recovery Strategy
- 9.1. Assumptions in this section
- 9.2. Tutorial Data Model
- 9.3. The Database Creation Script
- 9.4. Database Deletion Script
- 9.5. Page Map
- 10.1. Server file layout diagram
- 10.2. Package file layout diagram
List of Tables
List of Examples
View comments on this page at openacs.org +- Release Version Numbering
- Constraint naming standard
- ACS File Naming and Formatting Standards
- PL/SQL Standards
- Variables
- Automated Testing
- 12. Documentation Standards
- 13. Internationalization
- D. Using CVS with an OpenACS Site
- IV. For OpenACS Platform Developers
- 14. Kernel Documentation
- Overview
- Object Model Requirements
- Object Model Design
- Permissions Requirements
- Permissions Design
- Groups Requirements
- Groups Design
- Subsites Design Document
- Package Manager Requirements
- Package Manager Design
- OpenACS Internationalization Requirements
- Security Requirements
- Security Design
- Security Notes
- Request Processor Requirements
- Request Processor Design
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
- External Authentication Requirements
- 15. Releasing OpenACS
- Index
List of Figures
- 4.1. Site Templates
- 4.2. Granting Permissions
- 4.3. Granting Permissions in 5.0
- 5.1. Upgrading with the APM
- 5.2. Upgrading a local CVS repository
- 6.1. Multiple-server configuration
- 6.2. Simple A/B Deployment - Step 1
- 6.3. Simple A/B Deployment - Step 2
- 6.4. Simple A/B Deployment - Step 3
- 6.5. Complex A/B Deployment - Step 1
- 6.6. Complex A/B Deployment - Step 2
- 6.7. Complex A/B Deployment - Step 3
- 6.8. Query Analysis example
- 8.1. Tutorial Data Model
- 8.2. The Database Creation Script
- 8.3. Database Deletion Script
- 8.4. Page Map
- 9.1. Upgrading a local CVS repository
- 10.1. Server file layout diagram
- 10.2. Package file layout diagram
List of Tables
List of Examples
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -r1.27.2.3 -r1.27.2.4 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 20 Jul 2009 09:32:47 -0000 1.27.2.3 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 11 Sep 2009 23:41:26 -0000 1.27.2.4 @@ -1,131 +1,131 @@ - -Prerequisite Software + +Prerequisite Software OpenACS requires, at a minimum, an operating system, database, and webserver 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 5.3 5.4 5.5 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 4.5 No Yes Tcl 8.4 Yes 8.5.4 - Maybe 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 8.1 No Yes 8.2 No CVS version only Yes 8.3 No Yes Oracle 8.1.6 Maybe Yes Maybe 8.1.7 Maybe Yes Maybe 9i No Yes 10g No Yes 11g No Maybe The OpenACS installation instructions assume the operating system and build environment are installed. +
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 5.3 5.4 5.5 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 4.5 No Yes Tcl 8.4 Yes 8.5.4 - Maybe 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 8.1 No Yes 8.2 No CVS version only Yes 8.3 No Yes Oracle 8.1.6 Maybe Yes Maybe 8.1.7 Maybe Yes Maybe 9i No Yes 10g No Yes 11g No Maybe The OpenACS installation instructions assume the operating system and build environment are installed. The instructions explain installation of TCL, Tcllib, tDOM, tclwebtest, a Web Server, a Database, a Process Controller, and Source Control software. The following external links are for reference only. -
OpenACS 5.5.0. The OpenACS tarball comprises the core packages and +
OpenACS 5.5.0. The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL - and Oracle. Some scripts require bash shell.
Operating System. OpenACS is designed for a Unix-like system. It is + and Oracle. Some scripts require bash shell.
Operating System. OpenACS is designed for a Unix-like system. It is developed primarily in Linux. It can be run on Mac OS X, - and in Windows within VMWare.
GNU/Linux. The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
FreeBSD. FreeBSD guide. The OpenACS Reference Platform uses shell scripts written for bash, which is the + and in Windows within VMWare.
GNU/Linux. The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
FreeBSD. FreeBSD guide. 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
fetchwhen the instructions suggest you use -wgetto download software.Mac OS X. the section called “OpenACS Installation Guide for Mac OS X”
Windows/VMWare. the section called “OpenACS Installation Guide for Windows2000” The only + appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use + wget to download software.
Mac OS X. Section , “OpenACS Installation Guide for Mac OS X”
Windows/VMWare. Section , “OpenACS Installation Guide for Windows2000” The only way to run OpenACS on Windows is through the VMWare emulator. (Please let me know if you have OpenACS - running directly in Windows.)
Build Environment. The Reference Platform installation compiles most programs from - source code.
glibc 2.2 or newer, REQUIRED. You need recent versions of these libraries for + running directly in Windows.)
Build Environment. The Reference Platform installation compiles most programs from + source code.
glibc 2.2 or newer, REQUIRED. You need recent versions of these libraries for Oracle to work properly. For Unicode support, you need glibc 2.2 or newer. This should be included in your - operating system distribution.
GNU Make 3.76.1 or newer, REQUIRED. PostgreSQL and AOLserver require gmake to + operating system distribution.
GNU Make 3.76.1 or newer, REQUIRED. PostgreSQL and AOLserver require gmake to compile. Note that on most linux distributions, GNU Make is simply named -
makeand + make and there is no -gmake, + gmake, whereas on BSD distributions, -makeand -gmakeare - different --use gmake.TCL 8.4.x.
TCL 8.4.x, REQUIRED. OpenACS is written in TCL, an interpreted + make and + gmake are + different --use gmake.
TCL 8.4.x.
TCL 8.4.x, REQUIRED. OpenACS is written in TCL, an interpreted language. A threaded version of the TCL interpreter must be installed for OpenACS to work. The TCL interpreter that is included in most standard - distributions may not be thread safe.
TCL 8.4.x development headers and libraries, OPTIONAL. The site-wide-search service, OpenFTS, requires these to - compile. (Debian users:
apt-get install - tcl8.4-dev). You need this - to install OpenFTS.Tcllib, REQUIRED. + distributions may not be thread safe.
TCL 8.4.x development headers and libraries, OPTIONAL. The site-wide-search service, OpenFTS, requires these to + compile. (Debian users: apt-get install + tcl8.4-dev). You need this + to install OpenFTS.
Tcllib, REQUIRED. OpenACS 5.5.0 uses those Tcl extensions to send e-mail out, among others. -
tDOM, REQUIRED. OpenACS 5.5.0 stores +
tDOM, REQUIRED. OpenACS 5.5.0 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.)
tclwebtest, OPTIONAL. tclwebtest is a tool for testing web interfaces via tcl scripts.
Web Server. The web server handles incoming HTTP requests, provides + was used prior to 4.6.4.)
tclwebtest, OPTIONAL. tclwebtest is a tool for testing web interfaces via tcl scripts.
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.
AOLserver 4.x, REQUIRED. Provides the base HTTP server
+ some people have had success running Apache with mod_nsd.
AOLserver 4.x, REQUIRED. Provides the base HTTP server
Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS 5.5.0. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and - perhaps more to come), currently located at uptime.openacs.org. + perhaps more to come), currently located at uptime.openacs.org.
It's also possible to download all the pieces and patches yourself: -
- AOLserver is available at aolserver.com -
+
+ AOLserver is available at aolserver.com +
The OpenACS PostgreSQL driver (nspostgres.so) is available from - SourceForge. If + SourceForge. If you do decide to use nspostgres.so, you have to remember to change the AOLserver config file to point to nspostgres.so instead of postgres.so. This guide uses Mat Kovach's distro (i.e. postgres.so) -
- The patch that makes
execwork - on BSD is available at sourceforge.net -- The patch for aolserver 3.x that makes
ns_uuencode- work for binary files is available at sourceforge.net -+
+ The patch that makes exec work + on BSD is available at sourceforge.net +
+ The patch for aolserver 3.x that makes ns_uuencode + work for binary files is available at sourceforge.net +
The patch that makes AOLserver 3.x respect the -
-gflag is available at - sourceforge.net -nsopenssl, OPTIONAL. Provides SSL capabilities for AOLserver. It requires + -g flag is available at + sourceforge.net +
nsopenssl, OPTIONAL. Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make secure (https) connections to your webserver. - aolserver3.x requires nsopenssl 2.1a. aolserver4.x requires nsopenssl3; see - aolserver.com for latest release. (home page) -
ns_pam 0.1 or newer, OPTIONAL. Provides PAM capabilities for AOLserver. You + aolserver3.x requires nsopenssl 2.1a. aolserver4.x requires nsopenssl3; see + aolserver.com for latest release. (home page) +
ns_pam 0.1 or newer, OPTIONAL. Provides PAM capabilities for AOLserver. You need this if you want OpenACS users to authenticate - through a PAM module (such as RADIUS).
pam_radius 1.3.16, OPTIONAL. Provides RADIUS capabilities for PAM. You need - this if you want to use RADIUS authentication via PAM in OpenACS.
ns_ldap 0.r8, OPTIONAL. Provides LDAP capabilities for AOLserver. You need - this if you want to use LDAP authentication in OpenACS.
pam_radius 1.3.16, OPTIONAL. Provides RADIUS capabilities for PAM. You need + this if you want to use RADIUS authentication via PAM in OpenACS.
ns_ldap 0.r8, OPTIONAL. Provides LDAP capabilities for AOLserver. You need + this if you want to use LDAP authentication in OpenACS.
OpenFTS TCL 0.3.2, 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. For postgres 7.4.x and higher, full text search is also available via tsearch2. -
Analog 5.32 or newer, OPTIONAL. This program examines web server request logs, looks up +
Analog 5.32 or newer, OPTIONAL. 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.
Balance 3.11 or newer, OPTIONAL. "Balance is 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.
Database. The data on your site (for example, user names and passwords, + want to see how much traffic your site is getting.
Balance 3.11 or newer, OPTIONAL. "Balance is 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.
Database. The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS separates the database with an abstraction layer, which means that several different databases all function identically. While you can run the core OpenACS on any supported database, not all contributed packages support all - databases.
Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED). You can register and download Oracle from Oracle + databases.
Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED). You can register and download Oracle from Oracle TechNet. You need this if you want to use an - Oracle database.
PostgreSQL 7.4.x (Either this or Oracle is REQUIRED). You need this if you want to use a PostgreSQL database.
Process Controller. This is software that initiates other software, and + Oracle database.
PostgreSQL 7.4.x (Either this or Oracle is REQUIRED). You need this if you want to use a PostgreSQL database.
Process Controller. 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.
Daemontools + using Daemontools to control AOLserver and qmail.
Daemontools 0.76, OPTIONAL. You need this if - you want AOLserver and qmail to run "supervised," + 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.
Mail Transport Agent. A Mail Transport Agent is a program that handles all + run the services from inittab.
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.
Netqmail 1.04, OPTIONAL. You need this (or a different Mail Transport - Agent) if you want your webserver to send and receive email.
ucspi-tcp 0.88, OPTIONAL. This program listens for incoming TCP connections and + same variables that sendmail expects) can be used.
Netqmail 1.04, OPTIONAL. You need this (or a different Mail Transport + Agent) if you want your webserver to send and receive email.
ucspi-tcp 0.88, OPTIONAL. This program 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, OPTIONAL. (docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, + which is insecure. You need this if you are running qmail.
DocBook, OPTIONAL. (docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need this to write or edit documentation. -
Source Control. A Source Control system keeps track of all of the old +
Source Control. 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 of files. You can use any source control system; the Reference Platform and the OpenACS.org repository (where you can - get patched and development code in between releases) use cvs.
cvs 1.11.18, OPTIONAL. cvs is included in most unix distributions. You + get patched and development code in between releases) use cvs.
cvs 1.11.18, OPTIONAL. cvs is included in most unix distributions. You need this if you want to track old versions of your files, do controlled deployment of code from development to production, or get or contribute development code from openacs.org.
($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -r1.34.2.2 -r1.34.2.3 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 6 Jul 2009 11:14:26 -0000 1.34.2.2 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 11 Sep 2009 23:41:26 -0000 1.34.2.3 @@ -1,7 +1,7 @@ - -Initialize CVS (OPTIONAL) CVS is a source control system. Create and initialize a - directory for a local cvs repository.
[root tmp]#mkdir /cvsroot-[root tmp]#cvs -d /cvsroot init+ +Initialize CVS (OPTIONAL) CVS is a source control system. Create and initialize a + directory for a local cvs repository.
[root tmp]# mkdir /cvsroot +[root tmp]# cvs -d /cvsroot init [root tmp]# mkdir /cvsroot cvs -d /cvsroot initView comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v diff -u -r1.35.2.2 -r1.35.2.3 --- openacs-4/packages/acs-core-docs/www/install-daemontools.html 6 Jul 2009 11:14:27 -0000 1.35.2.2 +++ openacs-4/packages/acs-core-docs/www/install-daemontools.html 11 Sep 2009 23:41:26 -0000 1.35.2.3 @@ -1,15 +1,15 @@ - -Install Daemontools (OPTIONAL) Daemontools is a collection of programs for controlling + +
Install Daemontools (OPTIONAL) Daemontools is a collection of programs for controlling other processes. We use daemontools to run and monitor AOLserver. It is installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]#mkdir -p /package-[root root]#chmod 1755 /package/-[root root]#cd /package/-[root package]#tar xzf /tmp/daemontools-0.76.tar.gz-[root package]#cd admin/daemontools-0.76/-[root daemontools-0.76]#package/install+ services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package +[root root]# chmod 1755 /package/ +[root root]# cd /package/ +[root package]# tar xzf /tmp/daemontools-0.76.tar.gz +[root package]# cd admin/daemontools-0.76/ +[root daemontools-0.76]# package/install Linking ./src/* into ./compile... Creating /service... @@ -21,14 +21,14 @@ cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/installRed Hat 9, Fedora Core 1-4
Make sure you have the source tarball in -
/tmp, or download it. -[root root]#mkdir -p /package-[root root]#chmod 1755 /package/-[root root]#cd /package/-[root package]#tar xzf /tmp/daemontools-0.76.tar.gz-[root package]#cd admin-[root admin]#wget http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch+package/installRed Hat 9, Fedora Core 1-4
Make sure you have the source tarball in + /tmp, or download it. +
[root root]# mkdir -p /package +[root root]# chmod 1755 /package/ +[root root]# cd /package/ +[root package]# tar xzf /tmp/daemontools-0.76.tar.gz +[root package]# cd admin +[root admin]# wget http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch --14:19:24-- http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch => `daemontools-0.76.errno.patch' Resolving moni.csi.hu... done. @@ -40,9 +40,9 @@ 14:19:24 (346.68 KB/s) - `daemontools-0.76.errno.patch' saved [355/355] -[root admin]#cd daemontools-0.76-[root daemontools-0.76]#patch -p1 < ../daemontools-0.76.errno.patch-[root daemontools-0.76]#package/install+[root admin]# cd daemontools-0.76 +[root daemontools-0.76]# patch -p1 < ../daemontools-0.76.errno.patch +[root daemontools-0.76]# package/install Linking ./src/* into ./compile...(many lines omitted) Creating /service... Adding svscanboot to inittab... @@ -56,14 +56,14 @@ wget http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch cd daemontools-0.76 patch -p1 < ../daemontools-0.76.errno.patch -package/installFreeBSD (follow standard install)
Make sure you have the source tarball in -
/tmp, or download it. -[root root]#mkdir -p /package-[root root]#chmod 1755 /package/-[root root]#cd /package/-[root package]#tar xzf /tmp/daemontools-0.76.tar.gz-[root package]#cd admin/daemontools-0.76-[root daemontools-0.76]#package/install+package/installFreeBSD (follow standard install)
Make sure you have the source tarball in + /tmp, or download it. +
[root root]# mkdir -p /package +[root root]# chmod 1755 /package/ +[root root]# cd /package/ +[root package]# tar xzf /tmp/daemontools-0.76.tar.gz +[root package]# cd admin/daemontools-0.76 +[root daemontools-0.76]# package/install Linking ./src/* into ./compile...(many lines omitted) Creating /service... Adding svscanboot to inittab... @@ -74,13 +74,13 @@ cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/installDebian
[root ~]#apt-get install daemontools-installer-[root ~]#build-daemontoolsVerify that svscan is running. If it is, you should see - these two processes running:
[root root]#ps -auxw | grep service+package/installDebian
[root ~]# apt-get install daemontools-installer +[root ~]# build-daemontoolsVerify that svscan is running. If it is, you should see + these two processes running:
[root root]# ps -auxw | grep service root 13294 0.0 0.1 1352 272 ? S 09:51 0:00 svscan /service root 13295 0.0 0.0 1304 208 ? S 09:51 0:00 readproctitle service errors: ....................................... -[root root]#Install a script to grant non-root users permission to - control daemontools services.
[root root]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup-[root root]#chmod 755 /usr/local/bin/svgroup+[root root]#Install a script to grant non-root users permission to + control daemontools services.
[root root]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup +[root root]# chmod 755 /usr/local/bin/svgroup cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup chmod 755 /usr/local/bin/svgroupView comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html,v diff -u -r1.5.2.2 -r1.5.2.3 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html 6 Jul 2009 11:14:27 -0000 1.5.2.2 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html 11 Sep 2009 23:41:26 -0000 1.5.2.3 @@ -1,56 +1,56 @@ - -Install Full Text Search using OpenFTS (deprecated see tsearch2) By Joel Aufrecht and Malte Sussdorff
+ +Install Full Text Search using OpenFTS (deprecated see tsearch2) OpenFTS and tsearch1 use is deprecated in favor of Tsearch2. See - Install Full Text Search using Tsearch2. Tsearch2 is much easier to install, requiring only + Install Full Text Search using Tsearch2. Tsearch2 is much easier to install, requiring only compilation of one module from PostgreSQL contrib, with an - automated install process using the tsearch2-driver package.
If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and - AOLserver. You will need the openfts - tarball in
/tmp.
Install Tsearch. This is a PostgreSQL module that - OpenFTS requires.
[root root]#su - postgres-[postgres pgsql]$cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/-[postgres tsearch]$make+ automated install process using the tsearch2-driver package.If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and + AOLserver. You will need the openfts + tarball in /tmp.
Install Tsearch. This is a PostgreSQL module that + OpenFTS requires.
[root root]# su - postgres +[postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/ +[postgres tsearch]$ make sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql /usr/bin/flex -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted) rm -f libtsearch.so ln -s libtsearch.so.0.0 libtsearch.so -[postgres tsearch]$make install+[postgres tsearch]$ 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+[postgres tsearch]$ exit logout [root root]# su - postgres cd /usr/local/src/postgresql-7.3.4/contrib/tsearch make make install -exitUnpack the OpenFTS tarball and compile and install - the driver.
[root root]#cd /usr/local/src-[root src]#tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz-[root src]#cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/-[root Search-OpenFTS-tcl-0.3.2]#./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/+exitUnpack the OpenFTS tarball and compile and install + the driver.
[root root]# cd /usr/local/src +[root src]# tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz +[root src]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ +[root Search-OpenFTS-tcl-0.3.2]# ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/ checking prefix... /usr/local checking for gcc... gcc (many lines omitted) configure: creating ./config.status config.status: creating Makefile.global -[root Search-OpenFTS-tcl-0.3.2]#make+[root Search-OpenFTS-tcl-0.3.2]# make (cd parser; make all) make[1]: Entering directory `/usr/local/src/Search-OpenFTS-tcl-0.3.2/parser' (many lines omitted) packages provided were {Lingua::Stem::Snowball 0.3.2} processed fts_base_snowball.tcl -[root Search-OpenFTS-tcl-0.3.2]#cd aolserver-[root aolserver]#make-gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR +[root Search-OpenFTS-tcl-0.3.2]# cd aolserver +[root aolserver]# make +gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR (many lines omitted) n_stem.o italian_stem.o norwegian_stem.o portuguese_stem.o russian_stem.o nsfts.o -o nsfts.so -[root aolserver]#cp nsfts.so /usr/local/aolserver/bin/+[root aolserver]# cp nsfts.so /usr/local/aolserver/bin/ [root aolserver]# cd /usr/local/src tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz @@ -60,75 +60,75 @@ cd aolserver make cp nsfts.so /usr/local/aolserver/bin -Build some supplemental modules.
[root aolserver]#cd /usr/local/src/Search-OpenFTS-tcl-0.3.2-[root Search-OpenFTS-tcl-0.3.2]#cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib-[root Search-OpenFTS-tcl-0.3.2]#cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts-[root pgsql_contrib_openfts]#make+Build some supplemental modules.
[root aolserver]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2 +[root Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib +[root Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts +[root pgsql_contrib_openfts]# make sed 's,MODULE_PATHNAME,$libdir/openfts,g' openfts.sql.in >openfts.sql gcc -O2 -Wall -Wmissing-prototypes -Wmissing-declarations -fpic -I. -I../../src/include -c -o openfts.o openfts.c gcc -shared -o openfts.so openfts.o rm openfts.o -[root pgsql_contrib_openfts]#su postgres-[postgres pgsql_contrib_openfts]$make install+[root pgsql_contrib_openfts]# su postgres +[postgres pgsql_contrib_openfts]$ make install /bin/sh ../../config/install-sh -c -m 644 openfts.sql /usr/local/pgsql/share/contrib /bin/sh ../../config/install-sh -c -m 755 openfts.so /usr/local/pgsql/lib /bin/sh ../../config/install-sh -c -m 644 ./README.openfts /usr/local/pgsql/doc/contrib -[postgres pgsql_contrib_openfts]$exit+[postgres pgsql_contrib_openfts]$ exit [root pgsql_contrib_openfts]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2 cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts make su postgres make install -exitIf you are installing Full Text Search, add required packages to the new database. (In order for full text search - to work, you must also install the PostgreSQL - OpenFTS module and prerequisites.)
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql+ to work, you must also install the PostgreSQL + OpenFTS module and prerequisites.)[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql BEGIN CREATE (many lines omitted) INSERT 0 1 COMMIT -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql CREATE CREATE [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql -/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sqlNote
+/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql
Note
If you get the error -
ERROR: could not access file "$libdir/tsearch": no such file or directory+ ERROR: could not access file "$libdir/tsearch": no such file or directory It is probably because PostgreSQL's libdir configuration variable points to a diffent directory than where tsearch is. You can find out where PostgreSQL expects to find tsearch via -pg_config --pkglibdir-
If you have installed OpenFTS, you can enable it for this service. Uncomment this line from
config.tcl. (To uncomment a line in a tcl file, remove the#at the beginning of the line.)#ns_param nsfts ${bindir}/nsfts.so
Click
Adminon the top of the default home page. If prompted, log in with the account and password you entered during install.Click on the
Install -softwarelink.Click on the
Install -new servicelink.Click on the
Installlink next to OpenFTS Driver.Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$svc -t /service/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then browse back to the home page.
Click on
Adminon the top of the screen.Click on
Main Site Administrationin the "Subsite Administration" section.Click on
Site Mapin the "Advanced Features" section.Mount the OpenFTS Full Text Search Engine in the site map.
Click the
new sub folderlink on the "/" line, the first line under Main Site:/.Type
openfts-and click.On the new
openftsline, click themountlink.Click
OpenFTS -Driver.On the
openftsline, clickset parameters.Change
openfts_tcl_src_pathto/usr/local/src/Search-OpenFTS-tcl-0.3.2/and click-Mount the Search interface in the site map.
Click the -
new sub folderlink on the -Main Site line.Type
search-and click.Click the
new -applicationlink on thesearch- line.Type
search+pg_config --pkglibdir+
If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)
#ns_param nsfts ${bindir}/nsfts.so
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +software link.
Click on the Install +new service link.
Click on the Install link next to OpenFTS Driver.
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the OpenFTS Full Text Search Engine in the site map.
Click the new sub folder link on the "/" line, the first line under Main Site:/.
Type openfts +and click .
On the new openfts line, click the mount link.
Click OpenFTS +Driver.
On the openfts line, click set parameters.
Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click +
Mount the Search interface in the site map.
Click the +new sub folder link on the +Main Site line.
Type search +and click .
Click the new +application link on the search + line.
Type search where it says -
untitled, choose -searchfrom the +untitled, choose +search from the drop-down list, and click -. -Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$svc -t /service/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then click on
Main Siteat the top of the page.Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.
Near the bottom of the page, click on the
OpenFTS Driverlink. Click onAdministration. -Click onInitialize OpenFTS Engine. -Click.Add the FTS Engine service contract
Click on the
DevAdmin.Click on the
Service Contractlink.On the
FtsEngineDriver+. +Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then click on Main Site at the top of the page.
Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.
Near the bottom of the page, click on the OpenFTS Driver link. Click on Administration. +Click on Initialize OpenFTS Engine. +Click .
Add the FTS Engine service contract
Click on the DevAdmin.
Click on the Service Contract link.
On the FtsEngineDriver line, click -
Install. -Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$svc -t /service/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. -
Click
Adminon the top of the default home page. If prompted, log in with the account and password you entered during install.Click on the
Install - softwarelink.Click on the
Install - new applicationlink.Click on the
Installlink next to Weblogger.Install all required packages as well (always say okay until you shall restart the server)
-
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd packages/lars-blogger/sql/postgresql-[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sqlNote: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$svc -t /service/$OPENACS_SERVICE_NAME- [$OPENACS_SERVICE_NAME postgresl]$If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
View comments on this page at openacs.org +Install. +Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. +
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install + software link.
Click on the Install + new application link.
Click on the Install link next to Weblogger.
Install all required packages as well (always say okay until you shall restart the server)
+
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql +[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sqlNote: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME postgresl]$If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html,v diff -u -r1.5.2.2 -r1.5.2.3 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 6 Jul 2009 11:14:27 -0000 1.5.2.2 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 11 Sep 2009 23:41:26 -0000 1.5.2.3 @@ -1,47 +1,47 @@ - -Install Full Text Search using Tsearch2 By Dave - Bauer, Joel - Aufrecht and Malte Sussdorff with - help from Tsearch + +
Install Full Text Search using Tsearch2 If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and +
If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and AOLserver. You will need the tseach2 module form PostgreSQL contrib. This is included with the PostgreSQL full source distribution. It is also available with the PostgreSQL contrib package provided by most distribution packages. On debian it is - called postgresql-contrib.
For PostgreSQL 7.3 or 7.4, download the + called postgresql-contrib.
For PostgreSQL 7.3 or 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. If you installed tsearch2 from a 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. TODO link to section decribing how to fix - an existing tsearch2 database with this patch.
As of May 9, 2004 there is a source patch available + an existing tsearch2 database with this patch.
As of May 9, 2004 there is a source patch available for tsearch2. The patch provides changes to the pg_ts_ configuration tables to allow for easy dump and restore of a database containing - tsearch2. The patch is available here : + tsearch2. The patch is available here : [http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz]
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+ [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.patchIf 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 : + 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 @@ -54,55 +54,55 @@ versions 7.3.x and 7.4.x. The patch has been applied to the sources for - 8.0.
Install Tsearch2. This is a PostgreSQL module + 8.0.
Install Tsearch2. This is a PostgreSQL module that the tsearch2-driver OpenACS package requires. 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+ 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+[postgres tsearch]$ exit logout [root root]# su - postgres cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2 make make install -exit
Click
Adminon the top of the default home page. If prompted, log in with the account and password you entered during install.Click on the
Install -softwarelink.Click on the
Install -new servicelink.Click on the -
Install+exit
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +software link.
Click on the Install +new service link.
Click on the + Install link next to Tsearch2 Driver. If you have installed tsearch2 into your PostgreSQL database, the installer will - automatically enable tsearch in your OpenACS database instance.
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$svc -t /service/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then browse back to the home page.
Click on
Adminon the top of the screen.Click on
Main Site Administrationin the "Subsite Administration" section.Click on
Site Mapin the "Advanced Features" section.Mount the Search interface in the site map.
Click the -
new sub folderlink on the -Main Site line.Type
search-and click.Click the
new -applicationlink on thesearch- line.Type
search+ automatically enable tsearch in your OpenACS database instance.Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the Search interface in the site map.
Click the +new sub folder link on the +Main Site line.
Type search +and click .
Click the new +application link on the search + line.
Type search where it says -
untitled, choose -searchfrom the +untitled, choose +search from the drop-down list, and click -. -Click the -
Parameterslink - next to the Search package istance.Type
tsearch2-driver+. +Click the +Parameters link + next to the Search package istance.
Type tsearch2-driver where it says -
openfts-driver+openfts-driver in the -FtsEngineDriverparameter. -Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$svc -t /service/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then click on
Main Siteat the top of the page.Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. -
Click
Adminon the top of the default home page. If prompted, log in with the account and password you entered during install.Click on the
Install - softwarelink.Click on the
Install - new applicationlink.Click on the
Installlink next to Weblogger.Install all required packages as well (always say okay until you shall restart the server)
-
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd packages/lars-blogger/sql/postgresql-[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sqlNote: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$svc -t /service/$OPENACS_SERVICE_NAME- [$OPENACS_SERVICE_NAME postgresl]$If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
View comments on this page at openacs.org + FtsEngineDriver parameter. +Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$Wait a minute, then click on Main Site at the top of the page.
Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. +
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install + software link.
Click on the Install + new application link.
Click on the Install link next to Weblogger.
Install all required packages as well (always say okay until you shall restart the server)
+
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql +[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sqlNote: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME postgresl]$If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-ldap-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ldap-radius.html,v diff -u -r1.5.2.1 -r1.5.2.2 --- openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 10 Jun 2009 22:24:07 -0000 1.5.2.1 +++ openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 11 Sep 2009 23:41:26 -0000 1.5.2.2 @@ -1,13 +1,13 @@ - -Install LDAP for use as external authentication + +Install LDAP for use as external authentication This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section
Install openldap. Download and install ns_ldap
[root aolserver]#cd /usr/local/src/- [root src]#wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz- [root src]#tar xvfz openldap-2.2.17.tgz- [root src]#cd openldap-2.2.17- [root src]#./configure --prefix=/usr/local/openldap- [root openldap]#make install+This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section
Install openldap. Download and install ns_ldap
[root aolserver]# cd /usr/local/src/ + [root src]# wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz + [root src]# tar xvfz openldap-2.2.17.tgz + [root src]# cd openldap-2.2.17 + [root src]# ./configure --prefix=/usr/local/openldap + [root openldap]# make install [root openldap]# cd /usr/local/src/ wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz @@ -16,18 +16,18 @@ ./configure --prefix=/usr/local/openldap --disable-slapd make install -Install ns_ldap. Download and install ns_ldap
[root aolserver]#cd /usr/local/src/aolserver/- [root aolserver]#wget http://www.sussdorff.de/ressources/nsldap.tgz- [root aolserver]#tar xfz nsldap.tgz- [root aolserver]#cd nsldap- [root ns_pam-0.1]#make install LDAP=/usr/local/openldap INST=/usr/local/aolserver+Install ns_ldap. Download and install ns_ldap
[root aolserver]# cd /usr/local/src/aolserver/ + [root aolserver]# wget http://www.sussdorff.de/ressources/nsldap.tgz + [root aolserver]# tar xfz nsldap.tgz + [root aolserver]# cd nsldap + [root ns_pam-0.1]# make install LDAP=/usr/local/openldap INST=/usr/local/aolserver [root ns_pam-0.1]# cd /usr/local/src/aolserver/ wget http://www.sussdorff.de/resources/nsldap.tgz tar xfz nsldap.tgz cd nsldap make install LDAP=/usr/local/openldap INST=/usr/local/aolserver -Configure ns_ldap for traditional use. Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the usernamestored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.
- Change config.tcl. Remove the # in front of
ns_param nsldap ${bindir}/nsldap.soto enable the loading of the ns_ldap module. -Configure ns_ldap for use with LDAP bind. LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the ns_ldap bind command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).
View comments on this page at openacs.org +Configure ns_ldap for traditional use. Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the usernamestored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.
+ Change config.tcl. Remove the # in front of ns_param nsldap ${bindir}/nsldap.so to enable the loading of the ns_ldap module. +
Configure ns_ldap for use with LDAP bind. LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the ns_ldap bind command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-more-software.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.html,v diff -u -r1.17.2.1 -r1.17.2.2 --- openacs-4/packages/acs-core-docs/www/install-more-software.html 10 Jun 2009 22:24:07 -0000 1.17.2.1 +++ openacs-4/packages/acs-core-docs/www/install-more-software.html 11 Sep 2009 23:41:26 -0000 1.17.2.2 @@ -1,9 +1,9 @@ - -Appendix B. Install additional supporting software Table of Contents
- Unpack the OpenACS tarball
- Initialize CVS (OPTIONAL)
- Add PSGML commands to emacs init file (OPTIONAL)
- Install Daemontools (OPTIONAL)
- Install qmail (OPTIONAL)
- Install Analog web file analyzer
- Install nspam
- Install Full Text Search using Tsearch2
- Install Full Text Search using OpenFTS (deprecated see tsearch2)
- Install nsopenssl
- Install tclwebtest.
- Install PHP for use in AOLserver
- Install Squirrelmail for use as a webmail system for OpenACS
- Install PAM Radius for use as external authentication
- Install LDAP for use as external authentication
- Install AOLserver 3.3oacs1
+ +Appendix B. Install additional supporting software Table of Contents
- Unpack the OpenACS tarball
- Initialize CVS (OPTIONAL)
- Add PSGML commands to emacs init file (OPTIONAL)
- Install Daemontools (OPTIONAL)
- Install qmail (OPTIONAL)
- Install Analog web file analyzer
- Install nspam
- Install Full Text Search using Tsearch2
- Install Full Text Search using OpenFTS (deprecated see tsearch2)
- Install nsopenssl
- Install tclwebtest.
- Install PHP for use in AOLserver
- Install Squirrelmail for use as a webmail system for OpenACS
- Install PAM Radius for use as external authentication
- Install LDAP for use as external authentication
- Install AOLserver 3.3oacs1
This section assumes that the source tarballs for supporting - software are in
/tmp. It assumes + software are in /tmp. It assumes that you begin each continuous block of commands as root, and you should end each block as root. It doesn't care which directory you start in. Text instructions always precede the commands they Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.html,v diff -u -r1.11.2.2 -r1.11.2.3 --- openacs-4/packages/acs-core-docs/www/install-next-add-server.html 6 Jul 2009 11:14:27 -0000 1.11.2.2 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.html 11 Sep 2009 23:41:26 -0000 1.11.2.3 @@ -1,19 +1,19 @@ - -Running multiple services on one machine Services on different ports. To run a different service on another port but the same - ip, simply repeat Install OpenACS 5.5.0 replacing + +
Running multiple services on one machine Services on different ports. To run a different service on another port but the same + ip, simply repeat Install OpenACS 5.5.0 replacing $OPENACS_SERVICE_NAME, and change the
set httpport 8000 -set httpsport 8443- to different values.
Services on different host names. For example, suppose you want to support -
http://service0.comand -http://bar.comon the same +set httpsport 8443+ to different values.
Services on different host names. For example, suppose you want to support +http://service0.com and + http://bar.com on the same machine. The easiest way is to assign each one a different ip address. Then you can install two services as above, but with different values for
set hostname [ns_info hostname] -set address 127.0.0.1+set address 127.0.0.1
If you want to install two services with different host names sharing the same ip, you'll need nsvhr to redirect requests - based on the contents of the tcp headers. See AOLserver - Virtual Hosting with TCP by markd. + based on the contents of the tcp headers. See AOLserver + Virtual Hosting with TCP by markd.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html,v diff -u -r1.17.2.2 -r1.17.2.3 --- openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 6 Jul 2009 11:17:31 -0000 1.17.2.2 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 11 Sep 2009 23:41:26 -0000 1.17.2.3 @@ -1,19 +1,19 @@ - -Vacuum Postgres nightly - The "vacuum" command must be run periodically to reclaim space - in versions of PostgreSQL before 7.4. The "vacuum analyze" form + +
Vacuum Postgres nightly + The "vacuum" command must be run periodically to reclaim space + in versions of PostgreSQL before 7.4. The "vacuum analyze" form additionally collects statistics on the disbursion of columns in the database, which the optimizer uses when it calculates just how to execute queries. The availability of this data can make a tremendous difference in the execution speed of queries. This command can also be run from cron, but it probably makes more sense to run this command as part of your nightly backup - procedure - if "vacuum" is going to screw up the database, you'd + procedure - if "vacuum" is going to screw up the database, you'd prefer it to happen immediately after (not before!) you've made a - backup! The "vacuum" command is very reliable, but conservatism is + backup! The "vacuum" command is very reliable, but conservatism is the key to good system management. So, if you're using the export procedure described above, you don't need to do this extra step. -
Edit your crontab:
[joeuser ~]$crontab -eWe'll set vacuum up to run nightly at 1 AM. Add the following +
Edit your crontab:
[joeuser ~]$ crontab -eWe'll set vacuum up to run nightly at 1 AM. Add the following line:
-0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME($Id$)View comments on this page at openacs.org +0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -r1.21.2.1 -r1.21.2.2 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 10 Jun 2009 22:24:07 -0000 1.21.2.1 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 11 Sep 2009 23:41:26 -0000 1.21.2.2 @@ -1,49 +1,49 @@ - -Install nsopenssl By Joel Aufrecht and Malte Sussdorff
+ +Install nsopenssl This AOLserver module is required if you want people to connect to your site via https. These commands compile nsopenssl and install it, along with a tcl helper script to handle https connections. You will also need ssl certificates. Because those should - be different for each server service, you won't need those instructions until - later.
You will need the unpacked Aolserver tarball in -
/usr/local/src/aolserverand - the nsopenssl tarball in -/tmp.Red Hat 9 note: see this - thread for details on compiling nsopenssl.)
[root bin]#cd /usr/local/src/aolserver-[root aolserver]#wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz-[root aolserver]#tar xzf nsopenssl-2.1.tar.gz-[root aolserver]#cd nsopenssl-2.1-[root nsopenssl-2.1]#make OPENSSL=/usr/local/ssl+ be different for each server service, you won't need those instructions until + later.You will need the unpacked Aolserver tarball in + /usr/local/src/aolserver and + the nsopenssl tarball in + /tmp.
Red Hat 9 note: see this + thread for details on compiling nsopenssl.)
[root bin]# cd /usr/local/src/aolserver +[root aolserver]# wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz +[root aolserver]# tar xzf nsopenssl-2.1.tar.gz +[root aolserver]# cd nsopenssl-2.1 +[root nsopenssl-2.1]# make OPENSSL=/usr/local/ssl gcc -I/usr/local/ssl/include -I../aolserver/include -D_REENTRANT=1 -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1 -c -o nsopenssl.o nsopenssl.c (many lines omitted) gcc -shared -nostartfiles -o nsopenssl.so nsopenssl.o config.o init.o ssl.o thread.o tclcmds.o -L/usr/local/ssl/lib -lssl -lcrypto -[root nsopenssl-2.1]#cp nsopenssl.so /usr/local/aolserver/bin-[root nsopenssl-2.1]#cp https.tcl /usr/local/aolserver/modules/tcl/+[root nsopenssl-2.1]# cp nsopenssl.so /usr/local/aolserver/bin +[root nsopenssl-2.1]# cp https.tcl /usr/local/aolserver/modules/tcl/ [root nsopenssl-2.1]# cd /usr/local/src/aolserver wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz tar xzf nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/local/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/For Debian (more +cp https.tcl /usr/local/aolserver/modules/tcl/
For Debian (more information):
apt-get install libssl-dev cd /usr/local/src/aolserver tar xzf /tmp/nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/lib/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/You will need the AOLserver4 source in
/usr/local/src/aolserver/aolserverand OpenSSL installed in/usr/local/ssl(or at least symlinked there). The use ofINST=/point/to/aolserveris being replaced withAOLSERVER=/point/to/aolserver. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.FreeBSD note: build nsopenssl with
gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10-[root bin]#cd /usr/local/src/aolserver-[root aolserver]#cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login-[root aolserver]#cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl-[root aolserver]#cd nsopenssl-[root nsopenssl]#make OPENSSL=/usr/local/ssl+cp https.tcl /usr/local/aolserver/modules/tcl/You will need the AOLserver4 source in /usr/local/src/aolserver/aolserver and OpenSSL installed in /usr/local/ssl (or at least symlinked there). The use of INST=/point/to/aolserver is being replaced with AOLSERVER=/point/to/aolserver. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.
FreeBSD note: build nsopenssl with gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10 +
[root bin]# cd /usr/local/src/aolserver +[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login +[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl +[root aolserver]# cd nsopenssl +[root nsopenssl]# make OPENSSL=/usr/local/ssl gcc -I/usr/local/ssl/include (many items omitted) -c -o sslcontext.o sslcontext.c (many lines omitted) -[root nsopenssl-2.1]#make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10+[root nsopenssl-2.1]# make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10 [root nsopenssl-2.1]# cd /usr/local/src/aolserver cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login @@ -52,23 +52,23 @@ make OPENSSL=/usr/local/ssl make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10If you have problems starting your server with nsopenssl.so due to missing libssl.so.0.9.7 (or lower), you have to create symlinks
-[root nsopenssl]#cd /usr/local/aolserver/lib-[root lib]#ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7-[root lib]#ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7+[root nsopenssl]# cd /usr/local/aolserver/lib +[root lib]# ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 +[root lib]# ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7 [root lib]# cd /usr/local/aolserver/lib ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7
SSL support must be enabled seperately in each OpenACS - server (Generate ssl certificates.
If your ports for SSL are privileged (below 1024), you + server (Generate ssl certificates.
If your ports for SSL are privileged (below 1024), you will have to start AOLserver with prebinds for both your HTTP - and your HTTPS port (usually by adding
-b - your_ip:your_http_port,your_ip:your_https_port+ and your HTTPS port (usually by adding -b + your_ip:your_http_port,your_ip:your_https_port to the nsd call. If you are using daemontools, this can be - changed in youretc/daemontools/run - file).To enable SSL support in your server, make sure your - etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If + changed in your etc/daemontools/run + file).
To enable SSL support in your server, make sure your + etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If that section is not present, try looking at the README file in -
/usr/local/src/aolserver/nsopenssl.View comments on this page at openacs.org + /usr/local/src/aolserver/nsopenssl.View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nspam.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nspam.html,v diff -u -r1.12.2.1 -r1.12.2.2 --- openacs-4/packages/acs-core-docs/www/install-nspam.html 10 Jun 2009 22:24:07 -0000 1.12.2.1 +++ openacs-4/packages/acs-core-docs/www/install-nspam.html 11 Sep 2009 23:41:26 -0000 1.12.2.2 @@ -1,2 +1,2 @@ - -Install nspam View comments on this page at openacs.org + +Install nspam View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html,v diff -u -r1.8.2.2 -r1.8.2.3 --- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 6 Jul 2009 11:17:31 -0000 1.8.2.2 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 11 Sep 2009 23:41:26 -0000 1.8.2.3 @@ -1,25 +1,25 @@ - -Deleting a tablespace Skip down for instructions on Deleting a PostgreSQL tablespace. -
+ +
Deleting a tablespace Skip down for instructions on Deleting a PostgreSQL tablespace. +
Should it become necessary to rebuild a tablespace from scratch, - you can use the
drop usercommand - in SVRMGRL with thecascade+ you can use the drop user command + in SVRMGRL with the cascade option. This command will drop the user and every database object - the user owns.SVRMGR>drop user $OPENACS_SERVICE_NAME cascade;- If this does not work because svrmgrl "cannot drop a user that - is currently connected", make sure to kill the AOLserver using - this user. If it still does not work, do:
SVRMGR>select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';and then
SVRMGR>alter system kill session 'sid, serial#';+ the user owns.
SVRMGR> drop user $OPENACS_SERVICE_NAME cascade;+ If this does not work because svrmgrl "cannot drop a user that + is currently connected", make sure to kill the AOLserver using + this user. If it still does not work, do:
SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';and then
SVRMGR> alter system kill session 'sid, serial#';where sid and serial# are - replaced with the corresponding values for the open session.
Use with caution!
+ replaced with the corresponding values for the open session.
Use with caution!
If you feel the need to delete everything - related to the service, you can also issue the following:
SVRMGR>drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;+ related to the service, you can also issue the following:
SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;Dropping a PostgreSQL tablespace is easy. You have to stop any AOLserver instances that are using the database that you wish to drop. If you're using daemontools, this is simple, just use the 'down' flag (-d). If you're using inittab, you have to comment out - your server in
/etc/inittab, - reread the inittab with/sbin/init - q, and thenrestart-aolserver - $OPENACS_SERVICE_NAME.Then, to drop the db, just do:
-[$OPENACS_SERVICE_NAME ~]$dropdb $OPENACS_SERVICE_NAME+ your server in /etc/inittab, + reread the inittab with /sbin/init + q, and then restart-aolserver + $OPENACS_SERVICE_NAME.Then, to drop the db, just do:
+[$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASEView comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html,v diff -u -r1.8.2.1 -r1.8.2.2 --- openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 10 Jun 2009 22:24:07 -0000 1.8.2.1 +++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 11 Sep 2009 23:41:26 -0000 1.8.2.2 @@ -1,51 +1,51 @@ - -AOLserver keepalive with inittab This is an alternative method for keeping the AOLserver - process running. The recommended method is to run AOLserver + +
AOLserver keepalive with inittab 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. -
+
Install a script called -
restart-aolserver. This + restart-aolserver. This script doesn't actually restart AOLserver - it just kills it. -+
Ask the OS to restart our service whenever it's not running. We do this by adding a line to -
/etc/inittab. + /etc/inittab.- Calling
restart-aolserver+ Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling -restart-aolservereffectively + restart-aolserver effectively restarts our service. -- Copy this file into -
/var/tmp/restart-aolserver.txt. -+
+ Copy this file into + /var/tmp/restart-aolserver.txt. +
This script needs to be SUID-root, which means that the script will run as root. This is necessary to ensure that the AOLserver processes are killed regardless of who owns them. However the script should be executable by the -
webgroup to ensure that 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. + /usr/local/bin.[joeuser ~]$ su - Password: *********** [root ~]# cp /var/tmp/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+[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-aolserverto kill + 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 @@ -56,34 +56,34 @@ [joeuser ~]$ killall nsd nsd: no process killedThe 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 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+ working.+ Assuming that the restart-aolserver script worked, login as root and open -
/etc/inittabfor + /etc/inittab for editing.[joeuser ~]$ su - Password: ************ -[root ~]# emacs -nw /etc/inittab+[root ~]# emacs -nw /etc/inittab
Copy this line into the bottom of the file as a template, making sure that the first field -
nss1is unique. + nss1 is unique.-nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl- Important: Make sure there is a +nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/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.+ /etc/inittab.[root ~]# killall nsd nsd: no process killed -[root ~]# /sbin/init q+[root ~]# /sbin/init q
See if it worked by running the -
restart-aolserverscript + restart-aolserver script again.[root ~]# restart-aolserver birdnotes Killing 23750Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html,v diff -u -r1.18.2.2 -r1.18.2.3 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 6 Jul 2009 11:14:27 -0000 1.18.2.2 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 11 Sep 2009 23:41:26 -0000 1.18.2.3 @@ -1,69 +1,69 @@ - -
Starting and Stopping an OpenACS instance. The simplest way to start and stop and OpenACS site is to run the startup shell script provided,
/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 here.
Daemontools must already be installed. If not, install it.
Each service controlled by daemontools must have a - directory in
/service. That + +Starting and Stopping an OpenACS instance. The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /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 here.
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. It works like this:
The
initprogram starts every - time the computer is booted.A line in
init's configuration - file,/etc/inittab, tells init to + 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.
svscanbootchecks - the directory/service- every few seconds.If it sees a subdirectory there, it + 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 asuperviseprocess
superviseexecutes the run script. Whenever the run script stops,superviseexecutes it again. It also creates additional control files in the same directory.Hence, the AOLserver + 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. + /service/$OPENACS_SERVICE_NAME/run. But we use a symlink to make it easier to add and remove - stuff from the/service, so + 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 + /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 ill any existing AOLserver instances. As root, link thedaemontoolsdirectory into the/servicedirectory. Daemontools'svscanprocess checks this directory every five seconds, and will quickly executerun.[$OPENACS_SERVICE_NAME etc]$killall nsd+ /var/lib/aolserver/$OPENACS_SERVICE_NAME/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.[$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+[$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/ /service/$OPENACS_SERVICE_NAMEVerify that AOLserver is running.
[root root]#ps -auxw | grep nsd+[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/ /service/$OPENACS_SERVICE_NAMEVerify that AOLserver is running.
[root root]# ps -auxw | grep nsd $OPENACS_SERVICE_NAME 5562 14.4 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]#The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:
+[root root]#
The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:
-
svc -d /service/$OPENACS_SERVICE_NAME- + svc -d /service/$OPENACS_SERVICE_NAME - Bring the server down -+
-
svc -u /service/$OPENACS_SERVICE_NAME- + svc -u /service/$OPENACS_SERVICE_NAME - Start the server up and leave it in keepalive mode. -+
-
svc -o /service/$OPENACS_SERVICE_NAME- + svc -o /service/$OPENACS_SERVICE_NAME - Start the server up once. Do not restart it if it stops. -+
-
svc -t /service/$OPENACS_SERVICE_NAME- + svc -t /service/$OPENACS_SERVICE_NAME - Stop and immediately restart the server. -+
-
svc -k /service/$OPENACS_SERVICE_NAME- + 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. -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]#+
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]#At this point, these commands will work only for the -
rootuser. Grant permission for thewebgroup to usesvccommands on the $OPENACS_SERVICE_NAME server.[root root]#/usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME-[root root]#Verify that the controls work. You may want to
tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.login another window, so you can see what happens when you type these commands. + 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]#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 + 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) View comments on this page at openacs.org +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) View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-origins.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-origins.html,v diff -u -r1.12.2.1 -r1.12.2.2 --- openacs-4/packages/acs-core-docs/www/install-origins.html 10 Jun 2009 22:24:07 -0000 1.12.2.1 +++ openacs-4/packages/acs-core-docs/www/install-origins.html 11 Sep 2009 23:41:26 -0000 1.12.2.2 @@ -1,23 +1,23 @@ - -Where did this document come from? - This document was created by Vinod Kurup, but it's really + +
Where did this document come from? + This document was created by Vinod Kurup, but it's really just plagiarism from a number of documents that came before it. If I've used something that you've written without proper credit, let me know and I'll fix it right away. -
Versions 4.6.2 to present were edited by Joel Aufrecht. -
These are a few of my sources:
+
Versions 4.6.2 to present were edited by Joel Aufrecht. +
These are a few of my sources:
ArsDigita installation guide -
+
OpenACS 3.x installation guide -
- Joel +
- Please also see the Credits section for more acknowledgements. + Please also see the Credits section for more acknowledgements.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -r1.28.2.1 -r1.28.2.2 --- openacs-4/packages/acs-core-docs/www/install-overview.html 10 Jun 2009 22:24:07 -0000 1.28.2.1 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 11 Sep 2009 23:41:26 -0000 1.28.2.2 @@ -1,5 +1,5 @@ - -Chapter 2. Installation Overview Table of Contents
by Vinod Kurup
+ +Chapter 2. Installation Overview Table of Contents
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-pam-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-pam-radius.html,v diff -u -r1.5.2.1 -r1.5.2.2 --- openacs-4/packages/acs-core-docs/www/install-pam-radius.html 10 Jun 2009 22:24:07 -0000 1.5.2.1 +++ openacs-4/packages/acs-core-docs/www/install-pam-radius.html 11 Sep 2009 23:41:26 -0000 1.5.2.2 @@ -1,38 +1,38 @@ - -Install PAM Radius for use as external authentication + +Install PAM Radius for use as external authentication This step by step guide is derived from the installation instructions which you can find at yourdomain.com/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.
Install ns_pam. Download and install ns_pam
[root aolserver]#cd /usr/local/src/aolserver/- [root aolserver]#wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz- [root aolserver]#tar xvfz ns_pam-0.1.tar.gz- [root aolserver]#cd ns_pam-0.1- [root ns_pam-0.1]#make install INST=/usr/local/aolserver+This step by step guide is derived from the installation instructions which you can find at yourdomain.com/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.
Install ns_pam. Download and install ns_pam
[root aolserver]# cd /usr/local/src/aolserver/ + [root aolserver]# wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz + [root aolserver]# tar xvfz ns_pam-0.1.tar.gz + [root aolserver]# cd ns_pam-0.1 + [root ns_pam-0.1]# make install INST=/usr/local/aolserver [root ns_pam-0.1]# cd /usr/local/src/aolserver/ wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz tar xvfz ns_pam-0.1.tar.gz cd ns_pam-0.1 make install INST=/usr/local/aolserver -Configure ns_pam. Configure AOLserver for ns_pam
To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.
+
Configure ns_pam. Configure AOLserver for ns_pam
To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.
Change config.tcl. Remove the - # in front of
ns_param - nspam ${bindir}/nspam.soto enable the loading + # in front of ns_param + nspam ${bindir}/nspam.so to enable the loading of the ns_pam module. -+
Change config.tcl. Replace -
pam_domainin the section -ns/server/${server}/module/nspam- withaolserver-Create /etc/pam.d/aolserver. + pam_domain in the section + ns/server/${server}/module/nspam + with aolserver +
Create /etc/pam.d/aolserver.
- [root ns_pam]#cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver-Configure PAM Radius. Configure and install PAM Radius
You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.
[root ns_pam]#cd /usr/local/src/- [root src]#wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar- [root src]#tar xvf pam_radius-1.3.16- [root src]#cd pam_radius- [root pam_radius]#make- [root pam_radius]#cp pam_radius_auth.so /lib/security/+ [root ns_pam]#cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver +Configure PAM Radius. Configure and install PAM Radius
You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.
[root ns_pam]# cd /usr/local/src/ + [root src]# wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar + [root src]# tar xvf pam_radius-1.3.16 + [root src]# cd pam_radius + [root pam_radius]# make + [root pam_radius]# cp pam_radius_auth.so /lib/security/ [root pam_radius]# cd /usr/local/src wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar @@ -41,6 +41,6 @@ make cp pam_radius_auth.so /lib/security/ -Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.
[root pam_radius]#echo "radius.yourdomain.com:1645 your_radius_password >>/etc/rddb/server- [root src]#chown service0:web /etc/rddb/server+Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.
[root pam_radius]# echo "radius.yourdomain.com:1645 your_radius_password >>/etc/rddb/server + [root src]# chown service0:web /etc/rddb/serverView comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-php.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-php.html,v diff -u -r1.10.2.1 -r1.10.2.2 --- openacs-4/packages/acs-core-docs/www/install-php.html 10 Jun 2009 22:24:07 -0000 1.10.2.1 +++ openacs-4/packages/acs-core-docs/www/install-php.html 11 Sep 2009 23:41:26 -0000 1.10.2.2 @@ -1,12 +1,12 @@ - -Install PHP for use in AOLserver + +Install PHP for use in AOLserver To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from www.php.net. For convenience we get version 4.3.4 from a mirror
[root root]#cd /usr/local/src-[root src]#wget http://de3.php.net/distributions/php-4.3.4.tar.gz-[root src]#tar xfz php-4.3.4.tar.gz-[root src]#cd php-4.3.4-[root php-4.3.4]#cd php-4.3.4-[root php-4.3.4]#./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql-[root php-4.3.4]#make install-Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add
index.phpas the last element to yourdirectoryfiledirective.View comments on this page at openacs.org +To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from www.php.net. For convenience we get version 4.3.4 from a mirror
[root root]# cd /usr/local/src +[root src]# wget http://de3.php.net/distributions/php-4.3.4.tar.gz +[root src]# tar xfz php-4.3.4.tar.gz +[root src]# cd php-4.3.4 +[root php-4.3.4]# cd php-4.3.4 +[root php-4.3.4]# ./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql +[root php-4.3.4]# make install +Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add index.php as the last element to your directoryfile directive.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-qmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v diff -u -r1.35.2.2 -r1.35.2.3 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 6 Jul 2009 11:14:27 -0000 1.35.2.2 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 11 Sep 2009 23:41:26 -0000 1.35.2.3 @@ -1,53 +1,53 @@ - -Install qmail (OPTIONAL) Qmail is a Mail Transfer Agent. It handles incoming and + +
Install qmail (OPTIONAL) Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.
Red Hat 9: all djb tools (qmail, daemontools, ucspi) will - fail to compile in Red Hat 9 because of changes to glibc (patches)
Install ucspi. This program handles incoming tcp connections. - Download ucspi and install it.
[root root]#cd /usr/local/src-[root src]#wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz-[root src]#tar xzf ucspi-tcp-0.88.tar.gz+ fail to compile in Red Hat 9 because of changes to glibc (patches)
Install ucspi. This program handles incoming tcp connections. + Download ucspi and install it.
[root root]# cd /usr/local/src +[root src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz +[root src]# tar xzf ucspi-tcp-0.88.tar.gz cd /usr/local/src wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz tar xzf ucspi-tcp-0.88.tar.gzRed Hat 9 only
wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch cd ucspi-tcp-0.88 patch -p1 <../ucspi-tcp-0.88.errno.patch -cd ..All platforms continue:
[root src]#cd ucspi-tcp-0.88-[root ucspi-tcp-0.88]#make+cd ..All platforms continue:
[root src]# cd ucspi-tcp-0.88 +[root ucspi-tcp-0.88]# make ( cat warn-auto.sh; \ -echo 'main="$1"; shift'; \(many lines omitted) +echo 'main="$1"; shift'; \(many lines omitted) ./compile instcheck.c ./load instcheck hier.o auto_home.o unix.a byte.a -[root ucspi-tcp-0.88]#make setup check+[root ucspi-tcp-0.88]# make setup check ./install ./instcheck [root ucspi-tcp-0.88]# cd ucspi-tcp-0.88 make make setup checkVerify that ucspi-tcp was installed successfully by -running the tcpserver program which is part of ucspi-tcp:
[root ucspi-tcp-0.88]#tcpserver+running the tcpserver program which is part of ucspi-tcp:[root ucspi-tcp-0.88]# tcpserver tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root ucspi-tcp-0.88]# -(I'm not sure if this next step is 100% necessary, but when I skip it -I get problems. If you get the error
553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1)then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail +I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our case, the qmail replacement wrapper for the sendmail executable. In some cases, though, the outgoing mail requset is apparently sent through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP -address that means the local machine - the "loopback" interface). +address that means the local machine - the "loopback" interface). Unless this mail is addressed to the same machine, qmail thinks that it's an attempt to relay mail, and rejects it. So these two commands set up an exception so that any mail sent from 127.0.0.1 is allowed to -send outgoing mail.[root ucspi-tcp-0.88]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp-[root ucspi-tcp-0.88]#tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp+send outgoing mail.[root ucspi-tcp-0.88]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp +[root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtpDownload qmail, - set up the standard supporting users and build the binaries:
[root root]#cd /usr/local/src-[root src]#wget http://www.qmail.org/netqmail-1.04.tar.gz-[root src]#tar xzf netqmail-1.04.tar.gz+tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtpDownload qmail, + set up the standard supporting users and build the binaries:
[root root]# cd /usr/local/src +[root src]# wget http://www.qmail.org/netqmail-1.04.tar.gz +[root src]# tar xzf netqmail-1.04.tar.gz --15:04:11-- http://www.qmail.org/netqmail-1.04.tar.gz => `netqmail-1.04.tar.gz' Resolving www.qmail.org... done. @@ -59,18 +59,18 @@ 15:04:21 (24.04 KB/s) - `netqmail-1.04.tar.gz' saved [242310/242310] -[root src]#mkdir /var/qmail-[root src]#groupadd nofiles-[root src]#useradd -g nofiles -d /var/qmail/alias alias-[root src]#useradd -g nofiles -d /var/qmail qmaild-[root src]#useradd -g nofiles -d /var/qmail qmaill-[root src]#useradd -g nofiles -d /var/qmail qmailp-[root src]#groupadd qmail-[root src]#useradd -g qmail -d /var/qmail qmailq-[root src]#useradd -g qmail -d /var/qmail qmailr-[root src]#useradd -g qmail -d /var/qmail qmails-[root src]#cd netqmail-1.04-[root netqmail-1.04]#./collate.sh+[root src]# mkdir /var/qmail +[root src]# groupadd nofiles +[root src]# useradd -g nofiles -d /var/qmail/alias alias +[root src]# useradd -g nofiles -d /var/qmail qmaild +[root src]# useradd -g nofiles -d /var/qmail qmaill +[root src]# useradd -g nofiles -d /var/qmail qmailp +[root src]# groupadd qmail +[root src]# useradd -g qmail -d /var/qmail qmailq +[root src]# useradd -g qmail -d /var/qmail qmailr +[root src]# useradd -g qmail -d /var/qmail qmails +[root src]# cd netqmail-1.04 +[root netqmail-1.04]# ./collate.sh You should see 7 lines of text below. If you see anything else, then something might be wrong. @@ -81,8 +81,8 @@ [5] Renaming qmail-1.03 to netqmail-1.04... [6] Continue installing qmail using the instructions found at: [7] http://www.lifewithqmail.org/lwq.html#installation -[root netqmail-1.04]#cd netqmail-1.04-[root netqmail-1.04]#make setup check+[root netqmail-1.04]# cd netqmail-1.04 +[root netqmail-1.04]# make setup check ( cat warn-auto.sh; \ echo CC=\'`head -1 conf-cc`\'; \(many lines omitted) ./install @@ -103,11 +103,11 @@ cd netqmail-1.04 ./collate.sh cd netqmail-1.04 -make setup checkReplace sendmail with qmail's wrapper.
[root qmail-1.03]#rm -f /usr/bin/sendmail /usr/sbin/sendmail-[root qmail-1.03]#ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail+make setup checkReplace sendmail with qmail's wrapper.
[root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail +[root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail -ln -s /var/qmail/bin/sendmail /usr/sbin/sendmailConfigure qmail - specifically, run the config script to set up files in
/var/qmail/controlspecifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read/var/qmail/doc/INSTALL.ctlto find out how to configure qmail.[root qmail-1.03]#./config-fast yourserver.test+ln -s /var/qmail/bin/sendmail /usr/sbin/sendmailConfigure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
[root qmail-1.03]# ./config-fast yourserver.test Your fully qualified host name is yourserver.test. Putting yourserver.test into control/me... Putting yourserver.test into control/defaultdomain... @@ -117,45 +117,45 @@ Now qmail will refuse to accept SMTP messages except to yourserver.test. Make sure to change rcpthosts if you add hosts to locals or virtualdomains! [root qmail-1.03]# -./config-fast yourserver.testAll incoming mail that isn't for a specific user is handled by the
aliasuser. This includes all root mail. These commands prepare the alias user to receive mail.[root qmail-1.03]#cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root-[root alias]#chmod 644 ~alias/.qmail*-[root alias]#/var/qmail/bin/maildirmake ~alias/Maildir/-[root alias]#chown -R alias.nofiles /var/qmail/alias/Maildir+./config-fast yourserver.testAll incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail.
[root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root +[root alias]# chmod 644 ~alias/.qmail* +[root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/ +[root alias]# chown -R alias.nofiles /var/qmail/alias/Maildir [root alias]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root chmod 644 ~alias/.qmail* /var/qmail/bin/maildirmake ~alias/Maildir/ -chown -R alias.nofiles /var/qmail/alias/MaildirConfigure qmail to use the Maildir delivery format - (instead of mbox), and install a version of the qmail startup script modified to use Maildir.
[root alias]#echo "./Maildir" > /var/qmail/bin/.qmail-[root alias]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc-[root alias]#chmod 755 /var/qmail/rc+chown -R alias.nofiles /var/qmail/alias/MaildirConfigure qmail to use the Maildir delivery format + (instead of mbox), and install a version of the qmail startup script modified to use Maildir.
[root alias]# echo "./Maildir" > /var/qmail/bin/.qmail +[root alias]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc +[root alias]# chmod 755 /var/qmail/rc [root alias]# -echo "./Maildir" > /var/qmail/bin/.qmail +echo "./Maildir" > /var/qmail/bin/.qmail cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc chmod 755 /var/qmail/rcSet up the skeleton directory so that new users will - be configured for qmail.
[root root]#/var/qmail/bin/maildirmake /etc/skel/Maildir-[root root]#echo "./Maildir/" > /etc/skel/.qmail+ be configured for qmail.[root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir +[root root]# echo "./Maildir/" > /etc/skel/.qmail [root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir -echo "./Maildir/" > /etc/skel/.qmailAs recommended, we will run qmail with daemontools - control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.
[root root]#mkdir -p /var/qmail/supervise/qmail-send/log-[root root]#mkdir -p /var/qmail/supervise/qmail-smtpd/log-[root root]#mkdir /var/log/qmail-[root root]#chown qmaill /var/log/qmail-[root root]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl-[root root]#chmod 755 /var/qmail/bin/qmailctl-[root root]#ln -s /var/qmail/bin/qmailctl /usr/bin-[root root]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run-[root root]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run-[root root]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run-[root root]#cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run-[root root]#chmod 755 /var/qmail/supervise/qmail-send/run-[root root]#chmod 755 /var/qmail/supervise/qmail-send/log/run-[root root]#chmod 755 /var/qmail/supervise/qmail-smtpd/run-[root root]#chmod 755 /var/qmail/supervise/qmail-smtpd/log/run-[root root]#ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service-[root root]#ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service+echo "./Maildir/" > /etc/skel/.qmailAs recommended, we will run qmail with daemontools + control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.
[root root]# mkdir -p /var/qmail/supervise/qmail-send/log +[root root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log +[root root]# mkdir /var/log/qmail +[root root]# chown qmaill /var/log/qmail +[root root]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl +[root root]# chmod 755 /var/qmail/bin/qmailctl +[root root]# ln -s /var/qmail/bin/qmailctl /usr/bin +[root root]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run +[root root]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run +[root root]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run +[root root]# cp /tmp/openacs-5.5.0/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run +[root root]# chmod 755 /var/qmail/supervise/qmail-send/run +[root root]# chmod 755 /var/qmail/supervise/qmail-send/log/run +[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run +[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/log/run +[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service +[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service mkdir -p /var/qmail/supervise/qmail-send/log mkdir -p /var/qmail/supervise/qmail-smtpd/log mkdir /var/log/qmail @@ -172,11 +172,11 @@ chmod 755 /var/qmail/supervise/qmail-smtpd/run chmod 755 /var/qmail/supervise/qmail-smtpd/log/run ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service -Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.
[root root]#qmailctl stat+Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.
[root root]# qmailctl stat /service/qmail-send: up (pid 32700) 430 seconds /service/qmail-send/log: up (pid 32701) 430 seconds /service/qmail-smtpd: up (pid 32704) 430 seconds /service/qmail-smtpd/log: up (pid 32705) 430 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0 -[root root]#Further verify by sending and receiving email. Incoming mail for root is stored in
/var/qmail/alias/Maildir.View comments on this page at openacs.org +[root root]#Further verify by sending and receiving email. Incoming mail for root is stored in /var/qmail/alias/Maildir.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -r1.35.2.2 -r1.35.2.3 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 6 Jul 2009 11:14:27 -0000 1.35.2.2 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 11 Sep 2009 23:41:26 -0000 1.35.2.3 @@ -1,5 +1,5 @@ - -Appendix A. Install Red Hat 8/9 + +Appendix A. Install Red Hat 8/9 This section takes a blank PC and sets up some supporting @@ -8,78 +8,78 @@ works and is secure; it should take about an hour. (In my experience, it's almost always a net time savings of several hours to install a new machine from scratch compared to installing each - of these packages installed independently.)
The installation guide assumes you have:
A PC with hard drive you can reinstall
Red Hat 8.0 or 9.0 install discs
A CD with the current Security + of these packages installed independently.)
The installation guide assumes you have:
A PC with hard drive you can reinstall
Red Hat 8.0 or 9.0 install discs
A CD with the current Security Patches for your version of Red Hat.
The installation guide assumes that you can do the following on your platform: -
+
Adding users, groups, setting passwords -
+
(For Oracle) Starting an X server and running an X program remotely -
- Basic file management using
cp, rm, - mv,andcd-+
+ Basic file management using cp, rm, + mv, and cd +
Compiling a program using ./config and make.
You can complete this install without the above knowledge, but if anything goes wrong it may take extra time to - understand and correct the problem. Some useful UNIX resources. -
Unplug the network cable from your + understand and correct the problem. Some useful UNIX resources. +
Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - + (Wherever you see - the word secure, you should always read it as, "secure + the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're willing to exert and the estimated risk and - consequences.")
Insert Red Hat 8.0 or 9.0 Disk 1 into the - CD-ROM and reboot the computer
At the -
boot:+ consequences.")Insert Red Hat 8.0 or 9.0 Disk 1 into the + CD-ROM and reboot the computer
At the + boot: prompt, press Enter for a graphical install. The text install is fairly different, so if you need to do that instead proceed with caution, because - the guide won't match the steps.
Checking the media is probably a waste of + the guide won't match the steps.
Checking the media is probably a waste of time, so when it asks press Tab and - then Enter to skip it.
After the graphical introduction page loads, click
Choose the language you want to use and then click -
-Select the keyboard layout you will use and Click
Choose your mouse type and Click
Red Hat has several templates for new - computers. We'll start with the "Server" template and then + then Enter to skip it.
After the graphical introduction page loads, click
Choose the language you want to use and then click + +
Select the keyboard layout you will use and Click
Choose your mouse type and Click
Red Hat has several templates for new + computers. We'll start with the "Server" template and then fine-tune it during the rest of the install. Choose -
Server+ Server and click -.Reformat the hard drive. If you know what you're doing, + .
Reformat the hard drive. If you know what you're doing, do this step on your own. Otherwise: we're going to let the installer wipe out the everything on the main hard drive and then arrange things to - its liking.
Choose
Automatically Partition- and clickUncheck -
Review (and modify if needed) the partitions createdand clickOn the pop-up window asking "Are you sure - you want to do this?" click -
- IF YOU ARE WIPING YOUR HARD DRIVE.Click
on the boot loader screenConfigure Networking. + its liking.
Choose Automatically Partition + and click
Uncheck +Review (and modify if needed) the partitions created and click
On the pop-up window asking "Are you sure + you want to do this?" click + + IF YOU ARE WIPING YOUR HARD DRIVE.
Click on the boot loader screen
Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, - follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
DHCP is a system by which a computer that + follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
DHCP is a system by which a computer that joins a network (such as on boot) can request a temporary IP address and other network information. Assuming the machine has a dedicated IP address (if it doesn't, it will be tricky to access the OpenACS service from the outside world), we're going to set up that address. If you don't know your netmask, 255.255.255.0 is usually a pretty safe -guess. Click
, uncheckConfigure using DHCP-and type in your IP and netmask. Click.Type in your host -name, gateway, and DNS server(s). Then click
.We're going to use the firewall template for high +guess. Click , uncheck Configure using DHCP +and type in your IP and netmask. Click .
Type in your host +name, gateway, and DNS server(s). Then click .
We're going to use the firewall template for high security, meaning that we'll block almost all incoming traffic. Then we'll add a few holes to the firewall for services which we need and -know are secure. Choose
High+know are secure. Choose High security level. Check -WWW, -SSH, and -Mail (SMTP). In theOther ports-box, enter443, 8000, 8443. Click -. -Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.Select any additional languages you want the +WWW, +SSH, and +Mail (SMTP). In the Other ports +box, enter 443, 8000, 8443. Click +. +Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.
Select any additional languages you want the computer to support and then click -
Choose your time zone and click
.Type in a root -password, twice.
On the Package selection page, we're going to +
Choose your time zone and click .
Type in a root +password, twice.
On the Package selection page, we're going to uncheck a lot of packages that install software we don't need, and add packages that have stuff we do need. You should install everything we're installing here or the guide may not work for you; you can @@ -88,54 +88,54 @@ risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later. -
At the bottom, check
Select Individual Packagesand clickWe need to fine-tune the exact list of packages. +
At the bottom, check Select Individual Packages and click
We need to fine-tune the exact list of packages. The same rules apply as in the last step - you can add more stuff, but you shouldn't remove anything the guide adds. We're going to go through all the packages in one big list, so select -
Flat -Viewand wait. In a minute, a -list of packages will appear.Red Hat isn't completely happy with the combination +Flat +View and wait. In a minute, a +list of packages will appear.
Red Hat isn't completely happy with the combination of packages we've selected, and wants to satisfy some dependencies. Don't let it. On the next screen, choose -
Ignore Package -Dependenciesand click -. -Click -
- to start the copying of files.Wait. Insert Disk 2 when -asked.
Wait. Insert Disk 3 when asked.
If you know how to use it, create a boot +Ignore Package +Dependencies and click +. +
Click + + to start the copying of files.
Wait. Insert Disk 2 when +asked.
Wait. Insert Disk 3 when asked.
If you know how to use it, create a boot disk. Since you can also boot into recovery mode with the Install CDs, this is less useful than it used to be, and we - won't bother. Select
No,I do not want to create a boot diskand click.Click
Exit, remove the CD, and watch the + won't bother. Select No,I do not want to create a boot disk and click .Click Exit, remove the CD, and watch the computer reboot. -
After it finishes rebooting and shows the login - prompt, log in:
yourserver login:root+After it finishes rebooting and shows the login + prompt, log in:
yourserver login: root Password: -[root root]#Install any security patches. For example, insert your CD with - patches, mount it with
mount - /dev/cdrom, thencd - /mnt/cdrom, thenrpm -UVH - *rpm. Both Red Hat 8.0 and 9.0 have had both +[root root]#Install any security patches. For example, insert your CD with + patches, mount it with mount + /dev/cdrom, then cd + /mnt/cdrom, then rpm -UVH + *rpm. Both Red Hat 8.0 and 9.0 have had both kernel and openssl/openssh root exploits, so you should be upgrading all of that. Since you are upgrading the kernel, reboot after this step. -
Lock down SSH
Lock down SSH
+ SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming ssh connections. As a security precaution, we are now going to tell ssh not to allow anyone to connect directly to this computer as root. Type this into the shell: -
emacs /etc/ssh/sshd_configSearch for the word "root" by typing
C-s(that's emacs-speak for control-s) and thenroot.Make the following changes:
#Protocol 2,1to -Protocol 2- (this prevents any connections via SSH 1, which is insecure)#PermitRootLogin yesto -PermitRootLogin no+emacs /etc/ssh/sshd_configSearch for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
Make the following changes:
#Protocol 2,1 to + Protocol 2 + (this prevents any connections via SSH 1, which is insecure) #PermitRootLogin yes to + PermitRootLogin no (this prevents the root user from logging in remotely via ssh. If you do this, be sure to create a remote access - account, such as "remadmin", which you can use to get ssh - before using "su" to become root) #PermitEmptyPasswords notoPermitEmptyPasswords no- (this blocks passwordless accounts) and save and exit by typingC-x C-s C-x C-cRestart sshd so that the change takes effect.
service sshd restart+ account, such as "remadmin", which you can use to get ssh + before using "su" to become root)
#PermitEmptyPasswords no to PermitEmptyPasswords no + (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c Restart sshd so that the change takes effect.
service sshd restartRed Hat still installed a few services we don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the @@ -149,34 +149,34 @@ (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostgreSQL the way it is.) -
[root root]#service pcmcia stop-[root root]#service netfs stop-[root root]#chkconfig --del pcmcia-[root root]#chkconfig --del netfs+[root root]# service pcmcia stop +[root root]# service netfs stop +[root root]# chkconfig --del pcmcia +[root root]# chkconfig --del netfs [root root]# service pcmcia stop service netfs stop chkconfig --del pcmcia chkconfig --del netfsIf you installed PostgreSQL, do also -
service postgresql startandchkconfig --add postgresql.Plug in the network cable.
Verify that you have connectivity by going to another +service postgresql start and chkconfig --add postgresql.
Plug in the network cable.
Verify that you have connectivity by going to another computer and ssh'ing to yourserver, logging in as - remadmin, and promoting yourself to root:
[joeuser@someotherserver]$ssh remadmin@yourserver.test+ remadmin, and promoting yourself to root:[joeuser@someotherserver]$ ssh remadmin@yourserver.test The authenticity of host 'yourserver.test (1.2.3.4)' can't be established. DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5. -Are you sure you want to continue connecting (yes/no)?yes+Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts. Password: Last login: Mon Mar 3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com -[remadmin remadmin]$su -+[remadmin remadmin]$ su - Password: -[root root]#If you didn't burn a CD of patches and use it, can still +[root root]#
If you didn't burn a CD of patches and use it, can still download and install the necessary patches. Here's how to do it for the kernel; you should also check for other critical packages.
Upgrade the kernel to fix a security hole. The default Red Hat 8.0 system kernel (2.4.18-14, which you can check - with
uname -a) has several security problems. Download the new kernel, install it, and reboot.[root root]#cd /var/tmp-[root tmp]#wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm+ with uname -a) has several security problems. Download the new kernel, install it, and reboot.[root root]# cd /var/tmp +[root tmp]# wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm --20:39:00-- http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm => `kernel-2.4.18-27.7.x.i686.rpm' Resolving updates.redhat.com... done. @@ -188,11 +188,11 @@ 20:41:39 (78.38 KB/s) - `kernel-2.4.18-27.7.x.i686.rpm' saved [12736430/12736430] -root@yourserver tmp]#rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm+root@yourserver tmp]# rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm warning: kernel-2.4.18-27.7.x.i686.rpm: V3 DSA signature: NOKEY, key ID db42a60e Preparing... ########################################### [100%] 1:kernel ########################################### [100%] -[root tmp]#reboot+[root tmp]# reboot Broadcast message from root (pts/0) (Sat May 3 20:46:39 2003): @@ -201,4 +201,4 @@ cd /var/tmp wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm -rebootView comments on this page at openacs.org +rebootView comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-resources.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-resources.html,v diff -u -r1.12.2.1 -r1.12.2.2 --- openacs-4/packages/acs-core-docs/www/install-resources.html 10 Jun 2009 22:24:07 -0000 1.12.2.1 +++ openacs-4/packages/acs-core-docs/www/install-resources.html 11 Sep 2009 23:41:26 -0000 1.12.2.2 @@ -1,52 +1,52 @@ - -Resources + +
Resources Here are some resources that OpenACS users have found useful. -
+
- Philip + Philip and Alex's Guide to Web Publishing - A very readable guide to database-backed community websites. -
+
- UNIX + UNIX Power Tools - An excellent introduction to the command line tools and basic programs of UNIX -
+
- UNIX - System Administration Handbook (formerly the "red book" - - now the "purple" book) + UNIX + System Administration Handbook (formerly the "red book" + - now the "purple" book) -
+
- UNIX + UNIX System Administrator's Bible - (LePage and Iarerra 1998; IDG) -
+
+
+
- The Linux Documentation + The Linux Documentation Project -
+
- LPI + LPI certification exam preps - A series of articles from IBM developerworks on basic and intermediate Linux skills (requires registration) Index: openacs-4/packages/acs-core-docs/www/install-squirrelmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-squirrelmail.html,v diff -u -r1.11.2.1 -r1.11.2.2 --- openacs-4/packages/acs-core-docs/www/install-squirrelmail.html 10 Jun 2009 22:24:07 -0000 1.11.2.1 +++ openacs-4/packages/acs-core-docs/www/install-squirrelmail.html 11 Sep 2009 23:41:27 -0000 1.11.2.2 @@ -1,11 +1,11 @@ - -
Install Squirrelmail for use as a webmail system for OpenACS + +Install Squirrelmail for use as a webmail system for OpenACS This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]#cd www-[$OPENACS_SERVICE_NAME www]#wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz-[$OPENACS_SERVICE_NAME www]#tar xfz squirrelmail-1.4.4.tar.gz-[$OPENACS_SERVICE_NAME www]#mv squirrelmail-1.4.4 mail-[$OPENACS_SERVICE_NAME www]#cd mail/config-[$OPENACS_SERVICE_NAME www]#./conf.pl+This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd www +[$OPENACS_SERVICE_NAME www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz +[$OPENACS_SERVICE_NAME www]# tar xfz squirrelmail-1.4.4.tar.gz +[$OPENACS_SERVICE_NAME www]# mv squirrelmail-1.4.4 mail +[$OPENACS_SERVICE_NAME www]# cd mail/config +[$OPENACS_SERVICE_NAME www]# ./conf.plNow you are about to configure Squirrelmail. The configuration heavily depends on your setup, so no instructions are given here.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-ssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.html,v diff -u -r1.10.2.1 -r1.10.2.2 --- openacs-4/packages/acs-core-docs/www/install-ssl.html 10 Jun 2009 22:24:07 -0000 1.10.2.1 +++ openacs-4/packages/acs-core-docs/www/install-ssl.html 11 Sep 2009 23:41:27 -0000 1.10.2.2 @@ -1,33 +1,33 @@ - -Installing SSL Support for an OpenACS service Debian Users:
apt-get install opensslbefore proceeding.
Make sure nsopenssl.so is installed for AOLserver.
Uncomment this line from
config.tcl.#ns_param nsopenssl ${bindir}/nsopenssl.so -Prepare a certificate directory for the service.
[$OPENACS_SERVICE_NAME etc]$mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs-[$OPENACS_SERVICE_NAME etc]$chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs+ +Installing SSL Support for an OpenACS service Debian Users: apt-get install openssl before proceeding.
Make sure nsopenssl.so is installed for AOLserver.
Uncomment this line from config.tcl.
#ns_param nsopenssl ${bindir}/nsopenssl.so +Prepare a certificate directory for the service.
[$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs [$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs -chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certsIt 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.
+chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/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.
Debian users: use /usr/lib/ssl/misc/CA.pl instead of /usr/share/ssl/CA
Mac OS X users: use perl /System/Library/OpenSSL/misc/CA.pl -newcert instead of /usr/share/ssl/CA -
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs-[$OPENACS_SERVICE_NAME certs]$perl /usr/share/ssl/misc/CA -newcert+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME certs]$ perl /usr/share/ssl/misc/CA -newcert Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key ...++++++ .......++++++ writing new private key to 'newreq.pem' Enter PEM pass phrase:Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this:
Certificate (and private key) is in newreq.pem -[$OPENACS_SERVICE_NAME certs]$
newreq.pemcontains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.[root misc]#openssl rsa -in newreq.pem -out keyfile.pem+[$OPENACS_SERVICE_NAME certs]$newreq.pem contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
[root misc]# openssl rsa -in newreq.pem -out keyfile.pem read RSA key Enter PEM pass phrase: writing RSA key -[$OPENACS_SERVICE_NAME certs]$To create the certificate file, we take the combined file, copy it, and strip out the key.
[$OPENACS_SERVICE_NAME certs]$cp newreq.pem certfile.pem-[root misc]#emacs certfile.pemStrip out the section that looks like
-----BEGIN RSA PRIVATE KEY----- +[$OPENACS_SERVICE_NAME certs]$To create the certificate file, we take the combined file, copy it, and strip out the key.
[$OPENACS_SERVICE_NAME certs]$ cp newreq.pem certfile.pem +[root misc]# emacs certfile.pemStrip out the section that looks like
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997 S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T (11 lines omitted) 1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw== ------END RSA PRIVATE KEY-----+-----END RSA PRIVATE KEY-----
If you start up using the etc/daemontools/run script, you will need to edit this script to make sure the ports are bound for SSL. Details of this are in the run script. Index: openacs-4/packages/acs-core-docs/www/install-steps.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.html,v diff -u -r1.29.2.2 -r1.29.2.3 --- openacs-4/packages/acs-core-docs/www/install-steps.html 6 Jul 2009 11:14:27 -0000 1.29.2.2 +++ openacs-4/packages/acs-core-docs/www/install-steps.html 11 Sep 2009 23:41:27 -0000 1.29.2.3 @@ -1,97 +1,96 @@ - -
Basic Steps + +
Basic Steps The basic steps for installing OpenACS are: -
Install an OS and supporting software (see Install a Unix-like OS or Appendix A, Install Red Hat 8/9 for more details). See the Table 2.2, “Version Compatibility Matrix”.
Install a database (see the section called “Install Oracle 8.1.7” or - Install PostgreSQL).
Install AOLserver (Install AOLserver 4) .
Create a unique database and system user. +
Install an OS and supporting software (see Install a Unix-like OS or Appendix A, Install Red Hat 8/9 for more details). See the Table 2.2.
Install a database (see Section , “Install Oracle 8.1.7” or + Install PostgreSQL).
Install AOLserver (Install AOLserver 4) .
Create a unique database and system user. Install the OpenACS tarball, start and AOLserver instance, and use the OpenACS web pages to complete installation - (see Install OpenACS 5.5.0).
Specific instructions are available for Mac OS X and - Windows2000 (see the section called “OpenACS Installation Guide for Mac OS X” or - ???).
You can try out OpenACS using some binary installers. In + (see Install OpenACS 5.5.0).
Specific instructions are available for Mac OS X and + Windows2000 (see Section , “OpenACS Installation Guide for Mac OS X” or + Section , “OpenACS Installation Guide for Windows2000”).
You can try out OpenACS using some binary installers. In general, they are not yet supported by the community, so they are - mostly for evaluation purposes. Installing - OpenACS
You can see a list of current installers. -
+ mostly for evaluation purposes. Installing + OpenACS
You can see a list of current installers. +
The packaged version of - PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.
Once AOLserver and a database are installed, a bash script automates the OpenACS checkout and + PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.
Once AOLserver and a database are installed, a bash script automates the OpenACS checkout and installation. -
You will need a PC (or equivalent) with at least these minimum specifications: -
128MB RAM (much more if you want Oracle)
1GB free space on your hard drive (much more if you want Oracle)
A Unix-like operating system with Tcl, tDOM, and - a mail transport agent like sendmail or qmail. (see the section called “Prerequisite Software”)
+
128MB RAM (much more if you want Oracle)
1GB free space on your hard drive (much more if you want Oracle)
A Unix-like operating system with Tcl, tDOM, and + a mail transport agent like sendmail or qmail. (see Section , “Prerequisite Software”)
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. This is described in the Acquire Oracle section. -
Thisis text you will see on - screen, such as aorlink- in a radio button list or menu.
This is text that you will type.This is text from a program or file which you may need to - examine or edit:
if {$database == "oracle"} { - set db_password "mysitepassword" -}This is text that you will -
seeandtypein a command shell, including text you may have to + development purposes. This is described in the Acquire Oracle section. +
This is text you will see on + screen, such as a or link + in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to + examine or edit:
if {$database == "oracle"} { + set db_password "mysitepassword" +}This is text that you will + see and type in a command shell, including text you may have to change. It is followed by a list of just the commands, - which you can copy and paste. The command prompt varies by system; in the examples we use the form
[$OPENACS_SERVICE_NAME aolserver]$, where$OPENACS_SERVICE_NAMEis the current user andaolserveris the current directory. The root prompt is shown ending in # and all other prompts in $.-[root root]#su - $OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME aolserver]$svc -d /service/$OPENACS_SERVICE_NAME-[$OPENACS_SERVICE_NAME aolserver]$dropdb $OPENACS_SERVICE_NAME+ which you can copy and paste. The command prompt varies by system; in the examples we use the form[$OPENACS_SERVICE_NAME aolserver]$, where $OPENACS_SERVICE_NAME is the current user and aolserver is the current directory. The root prompt is shown ending in # and all other prompts in $.+[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ svc -d /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASE -[$OPENACS_SERVICE_NAME aolserver]$createdb $OPENACS_SERVICE_NAME+[$OPENACS_SERVICE_NAME aolserver]$ createdb $OPENACS_SERVICE_NAME CREATE DATABASE su - $OPENACS_SERVICE_NAME svc -d /service/$OPENACS_SERVICE_NAME dropdb $OPENACS_SERVICE_NAME -createdb $OPENACS_SERVICE_NAMESetting a global shell variable for cut and paste. In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME. In order to set it globally so that it works for any new users or special service users you may create, edit the file
/etc/profile(/etc/share/skel/dot.profilefor FreeBSD) and add this line:export OPENACS_SERVICE_NAME=service0Table 2.1. Default directories for a standard install
None of these locations are set in stone - they're simply the values that we've chosen. The values that you'll probably want to change, such as service name, are marked like this. The other values we recommend you leave unchanged unless you have a - reason to change them.
Note
+ reason to change them.
Note
Some of the paths and user accounts have been changed from those recommended in previous versions of this document to - improve security and maintainability. See this - thread for discussion.
+ improve security and maintainability. See this + thread for discussion.
We'll do our best to assure that following our instructions will get you to the promised land. If something goes wrong, don't panic. There are plenty of ways to get help. Here are some tips: -
+
Keep track of the commands you are run and record their output. I like to do my installations in a shell inside of emacs - (
M-x shell) so that I can save + (M-x shell) so that I can save the output if needed. An alternative would be to use the -scriptcommand. -+ script command. +
We'll point out where the error logs for the various pieces of software are. Output from those logs will help us help you. Don't worry if you feel overwhelmed by all the information in the error logs. Over time, you'll find that they make more and more sense. Soon, you'll actually look forward to errors so that you can run to the log and diagnose the problem. -
- Search the forums at +
+ Search the forums at openacs.org - you'll often find many people who have struggled through the same spot that you're in. -
+
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. -
- Ask questions at the irc channel on freenode.net +
+ Ask questions at the irc channel on freenode.net (#openacs). They're knowledgeable and quite friendly if you can keep them on topic. -
- Post a question on the forums. Make sure +
+ 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's a SQL error in the TCL error or in the log, post that too. -
+
If you find errors in this document or if you have ideas about making it better, please post them in our - BugTracker. + BugTracker.
($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.html,v diff -u -r1.15.2.1 -r1.15.2.2 --- openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 10 Jun 2009 22:24:07 -0000 1.15.2.1 +++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 11 Sep 2009 23:41:27 -0000 1.15.2.2 @@ -1,5 +1,5 @@ - -Install tclwebtest. Download the tclwebtest + +
Install tclwebtest. Download the tclwebtest source, unpack it, and put it an appropriate place. (tclwebtest 1.0 will be required for auto-tests in OpenACS 5.1. When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) As root:
cd /tmp cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tclwebtest co tclwebtest Index: openacs-4/packages/acs-core-docs/www/ix01.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v diff -u -r1.23.2.2 -r1.23.2.3 --- openacs-4/packages/acs-core-docs/www/ix01.html 6 Jul 2009 11:14:27 -0000 1.23.2.2 +++ openacs-4/packages/acs-core-docs/www/ix01.html 11 Sep 2009 23:41:27 -0000 1.23.2.3 @@ -1,2 +1,3 @@ - -Index Symbols
- $OPENACS_SERVICE_NAME, Paths and Users
A
- AOLserver
- configuration, Installation Option 2: Install from tarball
- Automated tests, Write automated tests
C
- computeroutput
- code, Code
- cvs
- initializing, Initialize CVS (OPTIONAL)
- setup, Using CVS with an OpenACS Site
D
- daemontools
- installation, Install Daemontools (OPTIONAL)
- docbook
- installation, Install Red Hat 8/9
- DocBook
- DTD, OpenACS Documentation Strategy: Why DocBook?
- emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
- Document structure, Document Structure
E
- emacs
- installation, Install Red Hat 8/9
- emphasis
- bold, italics, Emphasis
F
- full text search
G
- Graphics
- Images, Graphics
I
- informaltable
- table, Tables
L
- language
- installation, Install Red Hat 8/9
- Linking, Links
- lists, Lists
O
- OpenACS Package, What a Package Looks Like
P
- photo-album
- installation (see ImageMagick)
- Postgres
- Vacuuming, Installation Option 2: Install from tarball
Q
- qmail
- installation, Install qmail (OPTIONAL)
- Maildir, Install qmail (OPTIONAL)
- rcpthosts error message, Install qmail (OPTIONAL)
S
- sect1, Headlines, Sections
- sect2, Headlines, Sections
- Sections
- Headlines, Headlines, Sections
- security
- definition, Install Red Hat 8/9
- firewall, Install Red Hat 8/9
- sendmail
- removing, Install qmail (OPTIONAL)
- ssh, Install Red Hat 8/9
U
- ulink, Links
- upgrade
- OpenACS 4.5 to 4.6.x
- Linux/Unix, Upgrading 4.5 or higher to 4.6.3
X
- XML guidelines, OpenACS Documentation Strategy: Why DocBook?
- xref
- linkend, Links
- xreflabel, Headlines, Sections
View comments on this page at openacs.org + +Index Symbols
- $OPENACS_SERVICE_NAME, Paths and Users
A
- AOLserver
- configuration, Installation Option 2: Install from tarball
- Automated tests, Write automated tests
C
- computeroutput
- code, Code
- cvs
- initializing, Initialize CVS (OPTIONAL)
- setup, Using CVS with an OpenACS Site
D
- daemontools
- installation, Install Daemontools (OPTIONAL)
- docbook
- installation, Install Red Hat 8/9
- DocBook
- DTD, OpenACS Documentation Strategy: Why DocBook?
- emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
- Document structure, Document Structure
E
- emacs
- installation, Install Red Hat 8/9
- emphasis
- bold, italics, Emphasis
F
- full text search
G
- Graphics
- Images, Graphics
I
- informaltable
- table, Tables
L
- language
- installation, Install Red Hat 8/9
- Linking, Links
- lists, Lists
O
- OpenACS Package, What a Package Looks Like
P
- photo-album
- installation (see ImageMagick)
- Postgres
- Vacuuming, Installation Option 2: Install from tarball
Q
- qmail
- installation, Install qmail (OPTIONAL)
- Maildir, Install qmail (OPTIONAL)
- rcpthosts error message, Install qmail (OPTIONAL)
S
- sect1, Headlines, Sections
- sect2, Headlines, Sections
- Sections
- Headlines, Headlines, Sections
- security
- definition, Install Red Hat 8/9
- firewall, Install Red Hat 8/9
- sendmail
- removing, Install qmail (OPTIONAL)
- ssh, Install Red Hat 8/9
T
- The publish point for new packages should be + fixed., Prepare the package for distribution.
U
- ulink, Links
- upgrade
- OpenACS 4.5 to 4.6.x
- Linux/Unix, Upgrading 4.5 or higher to 4.6.3
X
- XML guidelines, OpenACS Documentation Strategy: Why DocBook?
- xref
- linkend, Links
- xreflabel, Headlines, Sections
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -r1.31.2.2 -r1.31.2.3 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 6 Jul 2009 11:14:27 -0000 1.31.2.2 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 11 Sep 2009 23:41:27 -0000 1.31.2.3 @@ -1,2 +1,2 @@ - -Chapter 14. Kernel Documentation Section missingSection missingSection missingSection missingTable of Contents
- Overview
- Object Model Requirements
- Object Model Design
- Permissions Requirements
- Permissions Design
- Groups Requirements
- Groups Design
- Package Manager Requirements
- Package Manager Design
- Database Access API
- OpenACS Internationalization Requirements
- Security Requirements
- Security Design
- Security Notes
- Request Processor Requirements
- Request Processor Design
- External Authentication Requirements
View comments on this page at openacs.org + +Chapter 14. Kernel Documentation Section missingSection missingTable of Contents
- Overview
- Object Model Requirements
- Object Model Design
- Permissions Requirements
- Permissions Design
- Groups Requirements
- Groups Design
- Subsites Design Document
- Package Manager Requirements
- Package Manager Design
- OpenACS Internationalization Requirements
- Security Requirements
- Security Design
- Security Notes
- Request Processor Requirements
- Request Processor Design
- Documenting Tcl Files: Page Contracts and Libraries
- Bootstrapping OpenACS
- External Authentication Requirements
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -r1.25.2.1 -r1.25.2.2 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 10 Jun 2009 22:24:08 -0000 1.25.2.1 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 11 Sep 2009 23:41:27 -0000 1.25.2.2 @@ -1,17 +1,17 @@ - -Overview
+ +
Overview
The OpenACS Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package management and deployment. -
+
The OpenACS Core, which comprises all the other packages that ship with the kernel and are most frequently needed by users, such as templating, forums, and user registration/management. The packages tend to be developed and distributed with the kernel. -
+
OpenACS Application packages, which typically provide user-level @@ -22,5 +22,5 @@
This document provides a high level overview of the kernel - package. Documentation for other packages on this server + package. Documentation for other packages on this server
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/mac-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/mac-installation.html,v diff -u -r1.37.2.2 -r1.37.2.3 --- openacs-4/packages/acs-core-docs/www/mac-installation.html 6 Jul 2009 11:14:28 -0000 1.37.2.2 +++ openacs-4/packages/acs-core-docs/www/mac-installation.html 11 Sep 2009 23:41:27 -0000 1.37.2.3 @@ -1,9 +1,9 @@ - -OpenACS Installation Guide for Mac OS X Prerequisites. Install readline:
Download readline from http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz into /usr/local/src
Extract readline in /usr/local/src, configure, compile, and install:
su - root + +OpenACS Installation Guide for Mac OS X Prerequisites. Install readline:
Download readline from http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz into /usr/local/src
Extract readline in /usr/local/src, configure, compile, and install:
su - root cd /usr/local/src tar xvfz readline-4.3.tar.gz readline-4.3 ./configure make -make installProceed with the Unix-like system instructions. OS X is incompatible with Oracle 8, and Oracle 9i on OSX is not yet verified for OpenACS. So continue with Install PostgreSQL. Additional special steps for OS X are documented inline with the standard Unix-like instructions.
Additional resources for installing on OS X.
($Id$)View comments on this page at openacs.org +make installProceed with the Unix-like system instructions. OS X is incompatible with Oracle 8, and Oracle 9i on OSX is not yet verified for OpenACS. So continue with Install PostgreSQL. Additional special steps for OS X are documented inline with the standard Unix-like instructions.
Additional resources for installing on OS X.
($Id$)View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maint-performance.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.html,v diff -u -r1.23.2.2 -r1.23.2.3 --- openacs-4/packages/acs-core-docs/www/maint-performance.html 6 Jul 2009 11:14:28 -0000 1.23.2.2 +++ openacs-4/packages/acs-core-docs/www/maint-performance.html 11 Sep 2009 23:41:27 -0000 1.23.2.3 @@ -1,8 +1,8 @@ - -Diagnosing Performance Problems
Did performance problems happen overnight, or did they sneak up on + +
Diagnosing Performance Problems
Did performance problems happen overnight, or did they sneak up on you? Any clue what caused the performance problems (e.g. loading 20K - users into .LRN)
Is the file system out of space? Is the machine swapping to disk constantly?
Isolating and solving database problems.
Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see the section called “Vacuum Postgres nightly”. For Oracle, use
exec dbms_stats.gather_schema_stats('SCHEMA_NAME')(Andrew Piskorski's Oracle notes).You can track the exact amount of time each database query on a page takes:
Go to Main Site : Site-Wide Administration : Install Software
Click on "Install New Application" in "Install from OpenACS Repository"
Choose "ACS Developer Support">
After install is complete, restart the server.
Browse to Developer Support, which is automatically mounted at
/ds. -Turn on Database statistics
Browse directly to a slow page and click "Request Information" at the bottom of the page.
This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
Identify a runaway Oracle query: first, use
ps auxortopto get the UNIX process ID of a runaway Oracle process.Log in to SQL*Plus as the admin:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl + users into .LRN)Is the file system out of space? Is the machine swapping to disk constantly?
Isolating and solving database problems.
Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see Section , “Vacuum Postgres nightly”. For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
You can track the exact amount of time each database query on a page takes:
Go to Main Site : Site-Wide Administration : Install Software
Click on "Install New Application" in "Install from OpenACS Repository"
Choose "ACS Developer Support">
After install is complete, restart the server.
Browse to Developer Support, which is automatically mounted at /ds. +
Turn on Database statistics
Browse directly to a slow page and click "Request Information" at the bottom of the page.
This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process.
Log in to SQL*Plus as the admin:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production @@ -12,7 +12,7 @@ With the Partitioning option JServer Release 8.1.7.3.0 - Production -SVRMGR>connect internal+SVRMGR> connect internal Password:See all of the running queries, and match the UNIX PID:
select p.spid -- The UNIX PID ,s.sid ,s.serial# ,p.username as os_user @@ -27,7 +27,7 @@ where sql.address = s.sql_address and sql.hash_value = s.sql_hash_value --and upper(s.username) like 'USERNAME%' - order by s.username ,s.sid ,s.serial# ,sql.piece ;To kill a troubled process:
alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL#Identify a runaway Postgres query. First, logging must be enabled in the database. This imposes a performance penalty and should not be done in normal operation.
Edit the file
postgresql.conf- its location depends on the PostGreSQL installation - and change#stats_command_string = falseto
stats_command_string = trueNext, connect to postgres (
psql service0) andselect * from pg_stat_activity;. Typical output should look like:+ order by s.username ,s.sid ,s.serial# ,sql.piece ;To kill a troubled process:
alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL#Identify a runaway Postgres query. First, logging must be enabled in the database. This imposes a performance penalty and should not be done in normal operation.
Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
#stats_command_string = falseto
stats_command_string = trueNext, connect to postgres (psql service0) and select * from pg_stat_activity;. Typical output should look like:
datid | datname | procpid | usesysid | usename | current_query ----------+-------------+---------+----------+---------+----------------- 64344418 | openacs.org | 14122 | 101 | nsadmin | <IDLE> @@ -42,7 +42,7 @@ 64344418 | openacs.org | 14311 | 101 | nsadmin | <IDLE> 64344418 | openacs.org | 14549 | 101 | nsadmin | <IDLE> (8 rows) -openacs.org=>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 @@ -58,13 +58,13 @@ 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. -
+ install "autotrace". I usually follow the instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html. +
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 + 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 + that Oracle supplies the dbms_stats package.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.html,v diff -u -r1.18.2.2 -r1.18.2.3 --- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 6 Jul 2009 11:14:28 -0000 1.18.2.2 +++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 11 Sep 2009 23:41:27 -0000 1.18.2.3 @@ -1,8 +1,8 @@ - -Staged Deployment for Production Networks ($Id$)+ +Staged Deployment for Production Networks This section describes two minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT)
Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested.
Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.
This section describes two minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT)
Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested.
Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.
With this method, we control the files on a site via CVS. This example uses one developmental server (service0-dev) and one production server (service0). Depending on your needs, you can also have a staging server for extensive testing before you go @@ -42,7 +42,7 @@ /usr/local/pgsql/bin/psql -f /var/lib/aolserver/service0-dev/packages/acs-kernel/sql/postgresql/postgresql.sql service0 mv /var/lib/aolserver/service0/database-backup/service0-nightly-backup.dmp.gz /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp.gz /bin/gunzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp.gz -/usr/bin/perl -pi -e "s/^\\connect service0$/\\connect service0-dev/" /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp +/usr/bin/perl -pi -e "s/^\\connect service0$/\\connect service0-dev/" /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp /usr/local/pgsql/bin/psql service0-dev < /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp /usr/local/bin/svc -u /service/service0-dev /bin/gzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp @@ -59,12 +59,12 @@ the lines starting > will be added and the lines starting < will be removed, when you commit if that looks okay, commit with: -cvs -m "changing text on front page for February conference" index.adp -the stuff in -m "service0" is a comment visible only from within cvs commands +cvs -m "changing text on front page for February conference" index.adp +the stuff in -m "service0" is a comment visible only from within cvs commands
To make these changes take place on service0:
4) update the file on production: cd /var/lib/aolserver/service0/www cvs up -Pd index.adpIf you make changes that require changes to the database, test them out first on service0-dev, using either -create.sql or upgrade scripts. Once you've tested them, you then update and - run the upgrade scripts from the package manager.
The production site can run "HEAD" from cvs.
The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.' So a better method is to use a tag. This guarantees that, at any time in the future, you can retrieve exactly the same set of code. This is useful for both of the characteristics of safe change deployment. For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code. For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems. .... example of using tags to follow ...
The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site. This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly. It does not, by itself, guarantee the entire control chain. You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more. Those additional measures typically take the form of source control tags and system version numbers. The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside.
This approach can has limitations. If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle. It also requires extra steps if the database will be affected.
View comments on this page at openacs.org + run the upgrade scripts from the package manager.The production site can run "HEAD" from cvs.
The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.' So a better method is to use a tag. This guarantees that, at any time in the future, you can retrieve exactly the same set of code. This is useful for both of the characteristics of safe change deployment. For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code. For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems. .... example of using tags to follow ...
The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site. This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly. It does not, by itself, guarantee the entire control chain. You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more. Those additional measures typically take the form of source control tags and system version numbers. The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside.
This approach can has limitations. If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle. It also requires extra steps if the database will be affected.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -r1.35.2.1 -r1.35.2.2 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 10 Jun 2009 22:24:08 -0000 1.35.2.1 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 11 Sep 2009 23:41:27 -0000 1.35.2.2 @@ -1,5 +1,5 @@ - -Chapter 6. Production Environments Table of Contents
- Starting and Stopping an OpenACS instance.
- AOLserver keepalive with inittab
- Running multiple services on one machine
- High Availability/High Performance Configurations
- Staged Deployment for Production Networks
- Installing SSL Support for an OpenACS service
- Set up Log Analysis Reports
- External uptime validation
- Diagnosing Performance Problems
+ +Chapter 6. Production Environments Table of Contents
- Starting and Stopping an OpenACS instance.
- AOLserver keepalive with inittab
- Running multiple services on one machine
- High Availability/High Performance Configurations
- Staged Deployment for Production Networks
- Installing SSL Support for an OpenACS service
- Set up Log Analysis Reports
- External uptime validation
- Diagnosing Performance Problems
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/nxml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/nxml-mode.html,v diff -u -r1.12.2.1 -r1.12.2.2 --- openacs-4/packages/acs-core-docs/www/nxml-mode.html 10 Jun 2009 22:24:08 -0000 1.12.2.1 +++ openacs-4/packages/acs-core-docs/www/nxml-mode.html 11 Sep 2009 23:41:27 -0000 1.12.2.2 @@ -1,11 +1,11 @@ - -Using nXML mode in Emacs By Jeff Davis
+ +Using nXML mode in Emacs An alternative to psgml mode is nXML by James Clark, a new major mode for GNU Emacs for editing XML, and which features highlighting, indentation, and on the fly validation versus a RelaxNG Schema. -
An - introduction to nXML mode at xmlhack.com. -
The nXML mode mail list at groups.yahoo.com. -
The nXML download page at thaiopensource.com.
View comments on this page at openacs.org +
An + introduction to nXML mode at xmlhack.com. +
The nXML mode mail list at groups.yahoo.com. +
The nXML download page at thaiopensource.com.
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -r1.43.2.2 -r1.43.2.3 --- openacs-4/packages/acs-core-docs/www/object-identity.html 6 Jul 2009 11:14:28 -0000 1.43.2.2 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 11 Sep 2009 23:41:27 -0000 1.43.2.3 @@ -1,10 +1,10 @@ - -Object Identity + +Object Identity One of the major design features of OpenACS 5.5.0 is the explicit representation -of object identity. The reason I say "explicit -representation" is because the concept of object identity has been +of object identity. The reason I say "explicit +representation" is because the concept of object identity has been around forever. It is inherent to our problem domain. Consider the example of 3.x style scoping. The 3.x data models use the triple (user_id, group_id, scope) to identify an object. In the 5.5.0 data model this Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -r1.29.2.2 -r1.29.2.3 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 6 Jul 2009 11:14:28 -0000 1.29.2.2 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 11 Sep 2009 23:41:27 -0000 1.29.2.3 @@ -1,86 +1,86 @@ - -
Object Model Design By Pete Su, Michael Yoon, Richard Li, Rafael Schloming
+ +Object Model Design Before OpenACS 4, software developers writing OpenACS applications or modules would develop each data model separately. However, many applications built on OpenACS share certain characteristics or require certain common services. -Examples of such services include:
User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and -so forth)
Presentation tools (e.g. how to display a field in a form or on a +Examples of such services include:
User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and +so forth)
Presentation tools (e.g. how to display a field in a form or on a page)
All of these services involve relating additional service-related information to application data objects. Examples of application objects -include:
forum messages
A user home page
A ticket in the ticket tracker
In the past, developers had to use ad-hoc and inconsistent schemes to -interface to various "general" services. OpenACS 4 defines a central +include:
forum messages
A user home page
A ticket in the ticket tracker
In the past, developers had to use ad-hoc and inconsistent schemes to +interface to various "general" services. OpenACS 4 defines a central data model that keeps track of the application objects that we wish to manage, and serves as a primary store of metadata. By metadata, we mean data stored on behalf of an application outside of the application's data model in order to enable certain central services. The OpenACS 4 Object Model (or object system) manages several different kinds of data and metadata to allow us to provide general -services to applications:
Every application object is given a unique identifier in the system. This +services to applications:
Every application object is given a unique identifier in the system. This identifier can be used to find all data related to a particular object. -
Object Context and Access Control
Every object is created in a particular security context, so the system +
Object Context and Access Control
Every object is created in a particular security context, so the system can provide centralized access control. -
Objects are instances of developer-defined object types. Object types +
Objects are instances of developer-defined object types. Object types allow developers to customize the data that is stored with each object. -
Relation types provide a general mechanism for mapping instances of one +
Relation types provide a general mechanism for mapping instances of one object type (e.g. users) to instances of another object type (e.g. groups).
The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.
Related Links
This design document should be read along with the design documents for the new groups system, subsites and the permissions system
The motivation for most of the facilities in the OpenACS 4 Object Model can be +particular programming idioms that we wish to generalize.
Related Links
This design document should be read along with the design documents for the new groups system, subsites and the permissions system
The motivation for most of the facilities in the OpenACS 4 Object Model can be understood in the context of the 3.x code base and the kinds of programming -idioms that evolved there. These are listed and discussed below.
Object identification is a central mechanism in OpenACS 4. Every application +idioms that evolved there. These are listed and discussed below.
Object identification is a central mechanism in OpenACS 4. Every application object in OpenACS 4 has a unique ID which is mapped to a row in a central table -called
acs_objects. Developers that wish to use OpenACS 4 services +called acs_objects. Developers that wish to use OpenACS 4 services need only take a few simple steps to make sure that their application objects appear in this table. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. In other words, we use object identifiers to enable centralized services in a global and uniform manner.Implicit Object Identifiers in OpenACS 3.x
The motivation for implementing general object identifiers comes from several observations of data models in OpenACS 3.x. Many modules use a -
(user_id, group_id, scope)column-triple for the purpose of +(user_id, group_id, scope) column-triple for the purpose of recording ownership information on objects, for access control. User/groups -also uses(user_id, group_id)pairs in its -user_group_maptable as a way to identify data associated with a +also uses (user_id, group_id) pairs in its +user_group_map table as a way to identify data associated with a single membership relation.Also, in OpenACS 3.x many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, -general comments maintains a table that maps application "page" +general comments maintains a table that maps application "page" data (static or dynamic pages on the website) to one or more user comments on that page. It does so by constructing a unique identifier for each page, usually a combination of the table in which the data is stored, and the value of the primary key value for the particular page. This idiom is referred to -as the "(on_which_table + on_what_id)" method for identifying +as the "(on_which_table + on_what_id)" method for identifying application data. In particular, general comments stores its map from pages -to comments using a "(on_which_table + on_what_id)" key plus the ID +to comments using a "(on_which_table + on_what_id)" key plus the ID of the comment itself.
All of these composite key constructions are implicit object identifiers - they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent, making the construction of generic application-independent services unnecessarily difficult.
Object Identifiers in OpenACS 4
The OpenACS 4 Object Model defines a single mechanism that applications use to attach unique identifiers to application data. This identifier is the primary -key of the
acs_objectstable. This table forms the core of what +key of the acs_objects table. This table forms the core of what we need to provide generic services like access control, general attribute storage, general presentation and forms tools, and generalized administrative interfaces. In addition, the object system provides an API that makes it easy to create new objects when creating application data. All an application must do to take advantage of general services in OpenACS 4 is to use the new API to make sure every object the system is to manage is associated with a row in -acs_objects. More importantly, if they do this, new services +acs_objects. More importantly, if they do this, new services like general comments can be created without requiring existing applications -to "hook into" them via new metadata.Note: Object identifiers are a good example of metadata -in the new system. Each row in
acs_objectsstores information +to "hook into" them via new metadata.Note: Object identifiers are a good example of metadata +in the new system. Each row in acs_objects stores information about the application object, but not the application object itself. This becomes more clear if you skip ahead and look at the SQL schema code -that defines this table.
Until the implementation of the general permissions system, every OpenACS +that defines this table.
Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a -notion of "scoping" was introduced into the core data model.
"Scope" is a term best explained by example. Consider some -hypothetical rows in the
address_booktable:
... scopeuser_idgroup_id... ... user123... ... group456... ... public... The first row represents an entry in User 123's personal address book, +notion of "scoping" was introduced into the core data model.
"Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table:
... scope user_id group_id ... ... user 123 ... ... group 456 ... ... public ... The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.
In this way, the scoping columns identify the security context in which a @@ -94,29 +94,29 @@ forum message would probably list a forum topic as its context, and a forum topic might list a subsite as its context. Thus, contexts make it easier to break the site up into security domains according to its natural -structure. An object's context is stored in the
context_id-column of theacs_objectstable.We use an object's context to provide a default answer to questions -regarding access control. Whenever we ask a question of the form "can -user X perform action Y on object Z", the OpenACS security model will defer +structure. An object's context is stored in the context_id +column of the acs_objects table.
We use an object's context to provide a default answer to questions +regarding access control. Whenever we ask a question of the form "can +user X perform action Y on object Z", the OpenACS security model will defer to an object's context if there is no information about user X's permission to perform action Y on object Z.
The context system forms the basis for the rest of the OpenACS access control -system, which is described in in two separate documents: one for the permissions system and another for the -party groups system. The context system -is also used to implement subsites.
As mentioned above, many OpenACS modules provide extensible data models, and +system, which is described in in two separate documents: one for the permissions system and another for the +party groups system. The context system +is also used to implement subsites.
As mentioned above, many OpenACS modules provide extensible data models, and need to use application specific mechanisms to keep track of user defined attributes and to map application data to these attributes. In the past, modules either used user/groups or their own ad hoc data model to provide this functionality.
User/Groups in OpenACS 3.x
The user/group system allowed developers to define group types along with attributes to be stored with each instance of a group type. Each group type could define a helper table that stored attributes on each instance of the group type. This table was called the -"
_info" table because the name was generated by -appending_infoto the name of the group type.The user/groups data model also provided the -
user_group_type_member_fieldsand -user_group_member_fieldstables to define attributes for members +"_info" table because the name was generated by +appending _info to the name of the group type.The user/groups data model also provided the +user_group_type_member_fields and +user_group_member_fields tables to define attributes for members of groups of a specific type and for members of a specific group, -respectively. The
user_group_member_field_maptable stored -values for both categories of attributes in itsfield_value+respectively. The user_group_member_field_map table stored +values for both categories of attributes in its field_value column. These tables allowed developers and users to define custom sets of attributes to store on groups and group members without changing the data model at the code level.Many applications in OpenACS 3.x and earlier used the group type mechanism in @@ -131,39 +131,39 @@ The motivation for subtypes comes from the need for OpenACS to be more extensible. In OpenACS 3.x, many applications extended the core data models by directly adding more columns, in order to provide convenient access to new -information. This resulted in core data tables that were too "fat", +information. This resulted in core data tables that were too "fat", containing a hodge podge of unrelated information that should have been normalized away. The canonical example of this is the explosion of the -
userstable in OpenACS 3.x. In addition to being sloppy technically, -these fat tables have a couple of other problems:
They degrade performance.
Denormalization can make it hard to maintain consistency constraints on +users table in OpenACS 3.x. In addition to being sloppy technically, +these fat tables have a couple of other problems:
They degrade performance.
Denormalization can make it hard to maintain consistency constraints on the data.
Object subtypes provide a way to factor the data model while still keeping track of the fact that each member of a subtype (i.e. for each row in the subtype's table), is also a member of the parent type (i.e. there is a corresponding row in the parent type table). Therefore, applications an use this mechanism without worrying about this bookkeeping themselves, and we avoid having applications pollute the core data model with their specific -information.
As we described above, the OpenACS 3.x user/groups system stored object +information.
As we described above, the OpenACS 3.x user/groups system stored object attributes in two ways. The first was to use columns in the helper table. The second consisted of two tables, one describing attributes and one storing values, to provide a flexible means for attaching attributes to metadata objects. This style of attribute storage is used in several other parts of -OpenACS 3.x, and we will refer to it as "skinny tables". For -example:
In the Ecommerce data model, the
ec_custom_product_fields+OpenACS 3.x, and we will refer to it as "skinny tables". For +example:
In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the -
ec_custom_product_field_valuestable stores values for those -attributes.In the Photo DB data model, the
ph_custom_photo_fieldstable +ec_custom_product_field_values table stores values for those +attributes.In the Photo DB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention -"
ph_user_<user_id>_custom_info" are used to +"ph_user_<user_id>_custom_info" are used to store values for those attributes.In addition, there are some instances where we are not using this model -but should, e.g. the
users_preferencestable, which +but should, e.g. the users_preferences table, which stores preferences for registered users in columns such as -prefer_text_only_panddont_spam_me_p. The -"standard" way for an OpenACS 3.x-based application to add to the list -of user preferences is to add a column to theusers_preferences+prefer_text_only_p and dont_spam_me_p. The +"standard" way for an OpenACS 3.x-based application to add to the list +of user preferences is to add a column to the users_preferences table (exactly the kind of data model change that has historically complicated the process of upgrading to a more recent OpenACS version).The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups -system. It defines a table called
acs_attributesthat record +system. It defines a table called acs_attributes that record what attributes belong to which object types, and how the attributes are stored. As before, attributes can either be stored in helper tables, or in a single central skinny table. The developer makes this choice on a case by @@ -173,53 +173,53 @@ skinny tables because doing so allows developers and users to dynamically update the set of attributes stored on an object without updating the data model at the code level. The bottom line: Helper tables are more functional -and more efficient, skinny tables are more flexible but limited.Many OpenACS 3.x modules use mapping tables to model relationships +and more efficient, skinny tables are more flexible but limited.
Many OpenACS 3.x modules use mapping tables to model relationships between application objects. Again, the 3.x user/groups system provides the canonical example of this design style. In that system, there was a single -table called
user_group_mapthat kept track of which users +table called user_group_map that kept track of which users belonged to what groups. In addition, as we discussed in the previous -section, the system used theuser_group_member_fieldsand -user_group_member_fields_maptables to allow developers to +section, the system used the user_group_member_fields and +user_group_member_fields_map tables to allow developers to attach custom attributes to group members. In fact, these attributes were not really attached to the users, but to the fact that a user was a member of a particular group - a subtle but important distinction.In OpenACS 4, relation types generalize this mechanism. Relation types allow developers to define general mappings from objects of a given type T, to other objects of a given type R. Each relation type is a subtype -of
acs_object, extended with extra attributes that store +of acs_object, extended with extra attributes that store constraints on the relation, and the types of objects the relation actually maps. In turn, each instance of a relation type is an object that represents -a single fact of the form "the object t of type T is related to the -object r of type R." That is, each instance of a relation type is +a single fact of the form "the object t of type T is related to the +object r of type R." That is, each instance of a relation type is essentially just a pair of objects.Relation types generalize mapping tables. For example, the 3.x user/groups data model can be largely duplicated using a single relation type describing -the "group membership" relation. Group types would then be subtypes +the "group membership" relation. Group types would then be subtypes of this membership relation type. Group type attributes would be attached to the relation type itself. Group member attributes would be attached to instances of the membership relation. Finally, the mapping table would be replaced by a central skinny table that the relation type system defines.
Relation types should be used when you want to be able to attach data to -the "fact" that object X and object Y are related to each other. On +the "fact" that object X and object Y are related to each other. On the face of it, they seem like a redundant mechanism however, since one could easily create a mapping table to do the same thing. The advantage of registering this table as a relation type is that in principle the OpenACS 4 object system could use the meta data in the types table to do useful things in a generic way on all relation types. But this mechanism doesn't really exist yet.
Relation types are a somewhat abstract idea. To get a better feel for -them, you should just skip to the data model.
The OpenACS 4 Object Model is designed to generalize and unify the following +them, you should just skip to the data model.
The OpenACS 4 Object Model is designed to generalize and unify the following mechanisms that are repeatedly implemented in OpenACS-based systems to manage -generic and application specific metadata:
The presence of a framework for subtyping and inheritance always brings up +generic and application specific metadata:
The presence of a framework for subtyping and inheritance always brings up the question of why we don't just use an object database. The main reason is that all of the major object database vendors ship products that are effectively tied to some set of object oriented programming languages. Their idea is to provide tight language-level integration to lower the -"impedance mismatch" between the database and the language. +"impedance mismatch" between the database and the language. Therefore, database objects and types are generally directly modeled on language level objects and types. Of course, this makes it nearly impossible to interact with the database from a language that does not have this tight coupling, and it limits the data models that we can write to ideas that are expressible in the host language. In particular, we lose many of the best features of the relational database model. This is a disaster from an ease of use standpoint. -
The "Object relational" systems provide an interesting +
The "Object relational" systems provide an interesting alternative. Here, some notion of subtyping is embedded into an existing SQL or SQL-like database engine. Examples of systems like this include the new Informix, PostgreSQL 7, and Oracle has something like this too. The main @@ -230,7 +230,7 @@ practice. Finally, object databases are not as widely used as traditional relational systems. They have not been tested as extensively and their scalability to very large databases is not proven (though some will disagree -with this statement).
The conclusion: the best design is to add a limited notion of subtyping to +with this statement).
The conclusion: the best design is to add a limited notion of subtyping to our existing relational data model. By doing this, we retain all the power of the relational data model while gaining the object oriented features we need most.
In the context of OpenACS 4, this means using the object model to make our @@ -241,25 +241,25 @@ the more limited domain of the metadata model, this is acceptable since the type hierarchy is fairly small. But the object system data model is not designed to support, for example, a huge type tree like the Java runtime -libraries might define.
This last point cannot be over-stressed: the object model is not -meant to be used for large scale application data storage. It is -meant to represent and store metadata, not application data.
Like most data models, the OpenACS Core data model has two levels:
The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)
+libraries might define.
This last point cannot be over-stressed: the object model is not +meant to be used for large scale application data storage. It is +meant to represent and store metadata, not application data.
Like most data models, the OpenACS Core data model has two levels:
The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)
You can browse the data models themselves from here: -
(Note that we have subdivided the operational level into the latter two files.)
The operational level depends on the knowledge level, so we discuss the knowledge level first. In the text below, we include abbreviated versions of the SQL definitions of many tables. Generally, these match the actual definitions in the existing data model but they are meant to reflect design information, not implementation. Some less relevant columns may be left out, -and things like constraint names are not included.
The knowledge level data model for OpenACS objects centers around three tables +and things like constraint names are not included.
The knowledge level data model for OpenACS objects centers around three tables that keep track of object types, attributes, and relation types. The first -table is
acs_object_types, shown here in an abbreviated +table is acs_object_types, shown here in an abbreviated form:-create table acs_object_types ( +create table acs_object_types ( object_type varchar(100) not null primary key, supertype references acs_object_types (object_type), abstract_p char(1) default 'f' not null @@ -270,26 +270,26 @@ name_method varchar(30), type_extension_table varchar(30) ); -+This table contains one row for every object type in the system. The key -things to note about this table are:
For every type, we store metadata for how to display this type in certain -contexts (
pretty_nameandpretty_plural).If the type is a subtype, then its parent type is stored in the column -
supertype.We support a notion of "abstract" types that contain no +things to note about this table are:
For every type, we store metadata for how to display this type in certain +contexts (pretty_name and pretty_plural).
If the type is a subtype, then its parent type is stored in the column +supertype.
We support a notion of "abstract" types that contain no instances (as of 9/2000 this is not actually used). These types exist only to -be subtyped. An example might be a type representing "shapes" that +be subtyped. An example might be a type representing "shapes" that contains common characteristics of all shapes, but which is only used to create subtypes that represent real, concrete shapes like circles, squares, -and so on.
Every type defines a table in which one can find one row for every -instance of this type (
table_name,id_column).
type_extension_tableis for naming a table that stores extra -generic attributes.The second table we use to describe types is
acs_attributes. +and so on.Every type defines a table in which one can find one row for every +instance of this type (table_name, id_column).
type_extension_table is for naming a table that stores extra +generic attributes.
The second table we use to describe types is acs_attributes. Each row in this table represents a single attribute on a specific object -type (e.g. the "password" attribute of the "user" type). +type (e.g. the "password" attribute of the "user" type). Again, here is an abbreviated version of what this table looks like. The actual table used in the implementation is somewhat different and is discussed in a separate document.
-create table acs_attributes ( +create table acs_attributes ( attribute_id integer not null primary key object_type not null references acs_object_types (object_type), attribute_name varchar(100) not null, @@ -305,38 +305,38 @@ max_n_values integer default 1 not null, static_p varchar(1) ); -+ -The following points are important about this table:
Every attribute has a unique identifier.
Every attribute is associated with an object type.
We store various things about each attribute for presentation -(
pretty_name,sort_order).The
data_typecolumn stores type information on this +The following points are important about this table:
Every attribute has a unique identifier.
Every attribute is associated with an object type.
We store various things about each attribute for presentation +(pretty_name, sort_order).
The data_type column stores type information on this attribute. This is not the SQL type of the attribute; it is just a human readable name for the type of data we think the attribute holds (e.g. -"String", or "Money"). This might be used later to -generate a user interface.
The
sort_ordercolumn stores information about how to sort -the attribute values.Attributes can either be stored explicitly in a table ("type -specific storage") or in a skinny table ("generic storage"). +"String", or "Money"). This might be used later to +generate a user interface.
The sort_order column stores information about how to sort +the attribute values.
Attributes can either be stored explicitly in a table ("type +specific storage") or in a skinny table ("generic storage"). In most cases, an attribute maps directly to a column in the table identified -by the
table_nameof the corresponding object type, although, as +by the table_name of the corresponding object type, although, as mentioned above, we sometimes store attribute values as key-value pairs in a -"skinny" table. However, when you ask the question "What are -the attributes of this type of object?", you don't really care about +"skinny" table. However, when you ask the question "What are +the attributes of this type of object?", you don't really care about how the values for each attribute are stored (in a column or as key-value -pairs); you expect to receive the complete list of all attributes.The
max_n_valuesandmin_n_valuescolumns +pairs); you expect to receive the complete list of all attributes.The max_n_values and min_n_values columns encode information about the number of values an attribute may hold. -Attributes can be defined to hold 0 or more total values.
The
static_pflag indicates whether this attribute value is +Attributes can be defined to hold 0 or more total values.The static_p flag indicates whether this attribute value is shard by all instances of a type, as with static member fields in C++. Static attribute are like group level attributes in OpenACS 3.x.
The final part of the knowledge level model keeps track of relationship types. We said above that object relationships are used to generalize the 3.x notion of group member fields. These were fields that a developer could store on each member of a group, but which were contextualized to the -membership relation. That is, they were really "attached" to the +membership relation. That is, they were really "attached" to the fact that a user was a member of a particular group, and not really attached to the user. This is a subtle but important distinction, because it allowed the 3.x system to store multiple sets of attributes on a given user, one set for each group membership relation in which they participated.
In OpenACS 4, this sort of data can be stored as a relationship type, in -
acs_rel_types. The key parts of this table look like this:+acs_rel_types. The key parts of this table look like this:-create table acs_rel_types ( +create table acs_rel_types ( rel_type varchar(100) not null references acs_object_types(object_type), object_type_one not null @@ -350,31 +350,31 @@ min_n_rels_two integer default 0 not null, max_n_rels_two integer ); -+ -Things to note about this table:
The main part of this table records the fact that the relation is between -instances of
object_type_oneand instances of -object_type_two. Therefore, each instance of this relation type -will be a pair of objects of the appropriate types.The
rolecolumns store human readable names for the roles -played by each object in the relation (e.g. "employee" and -"employer"). Each role must appear in the -acs_rel_roles.The
min_n_rels_onecolumn, and its three friends allow the +Things to note about this table:
