| Prev | Next |
Help to the folks keeping an OpenACS installation up and running.
Table of Contents
This is the place to look if you want to extend OpenACS and build on top - of what's already here. Here you can find out about the guts of the system.
Table of Contents
+ This is the place to look if you want to extend OpenACS and build on + top of what's already here. Here you can find out about the + guts of the system. +
Table of Contents
+
- Mat Kovach is graciously maintaining an AOLServer distribution that - includes all the patches and modules needed to run OpenACS 4.6. 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. -
- It's also possible to download all the pieces and patches yourself: -
- AOLServer is available at aolserver.com -
- ArsDigita's AOLServer distribution (including - internationalization patches, nscache, nsrewrite, nssha1 and the - oracle driver) is available at arsdigita.com -
- - The OpenACS PostgreSQL driver (nspostgres.so) is available from - 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) - -
- nsxml is available at http://acs-misc.sourceforge.net. -
- The patch that makes exec work - on BSD is available at sourceforge.net -
- The patch that makes ns_uuencode - work for binary files is available at sourceforge.net -
- The patch that makes AOLServer respect the - -g flag is available at sourceforge.net -
- - .... or just Download Mat's - AOLServer distribution to - /tmp - -
-joeuser:~$ cd /tmp -joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz -joeuser:/tmp$ cd
- +
This page assumes you have downloaded aolserver to to +/tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz. If not, +get it. It also assumes you are following the 4.6.2-P or 4.6.2-O Reference Platform installation, using Red Hat 8.0. Places where other systems are different are noted.
As root, untar aolserver3.3ad13-oacs1-beta-src.tar.gz - into /usr/local/src + into /usr/local/src. -
-joeuser:~$ su - -Password: ********** -root:~# cd /usr/local/src -root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz -root:/usr/local/src# chown -R root.root aolserver
- - AOLserver needs to be started as the root user if you want to use - port 80. Once it starts, though, it will drop the root privileges and - run as another user, which you must specify on the command line. It's - important that this user has as few privileges as possible. Why? - Because if an intruder somehow breaks in through AOLserver, you don't - want him to have any ability to do damage to the rest of your - server. At the same time, AOLserver needs to have write access to - some files on your system in order for OpenACS to function - properly. So, we'll run AOLserver as the - nobody user and the - web group. We'll add your regular - user account to the web group and - make sure that OpenACS files are group readable and writable. - -
- Run these commands: -
-root:/usr/local/src# cd
-root:~# groupadd web
-root:~# adduser joeuser web
-root:~# exit- - Next, we'll set up our environment variables. Add the following lines - to your /home/joeuser/.bash_profile: - -
-joeuser:~$ emacs .bash_profile
- - Add the first set of lines, if you're using Oracle. The 2nd set of - lines, if you're using PostgreSQL. Oracle Note: - These environment variables are specific for a local Oracle - installation communicating via IPC. If you are connecting to a remote - Oracle installation, you'll need to adjust these appropriately. Also, - make sure that the '8.1.7' matches your Oracle version. - -
-# For Oracle -export ORACLE_BASE=/ora8/m01/app/oracle -export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 -export PATH=$PATH:$ORACLE_HOME/bin -export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib -export ORACLE_SID=ora8 -export ORACLE_TERM=vt100 -export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data - -# For PostgreSQL -export PATH=$PATH:/usr/local/pgsql/bin -export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
- - Be absolutely certain that you have entered these lines correctly and - that you have saved the file - a slight error in these lines can lead - to many inscrutable error messages. Logout and log back in so these - settings will take effect. Use the - echo command to be sure that the - environment variables have been properly assigned. - -
-joeuser:~$ exit -LOGIN: joeuser -Password: ********* -joeuser:~$ echo $PATH -...some other directory paths...:/usr/local/pgsql/bin -joeuser:~$ echo $LD_LIBRARY_PATH -:/usr/local/pgsql/lib
- - Note: The result should be different if you're using Oracle. - /ora8/m01/app/oracle/product/8.1.7 - should have been in $PATH. - -
- - In order for nsxml to compile, you need libxml2 - (available from http://xmlsoft.org). On Debian, - this can be installed by doing apt-get install - libxml2-dev. Users of other distributions can - download rpms from rpmfind.net. You'll - need the libxml2 and - libxml2-devel packages. -
Prepare the distribution. You need to be root.
-joeuser:~$ su -p -Password: ******** -root:~# mkdir -p /usr/local/aolserver -root:~# cd /usr/local/src/aolserver -root:/usr/local/src/aolserver# ./conf-clean +[root@yourserver root]# cd /usr/local/src +[root@yourserver src]# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz +[root@yourserver src]# +cd /usr/local/src +tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz
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@yourserver root]# cd /usr/local/src/aolserver +[root@yourserver aolserver]# ./conf-clean cat: BUILD-MODULES: No such file or directory -Done.
- +Done. +[root@yourserver aolserver]#
mkdir -p /usr/local/aolserver +cd /usr/local/src/aolserver +./conf-clean
Put the name of the driver(s) that you want into conf-db. This can be - "postgresql", - "oracle", or the word - "both" if you want both drivers + postgresql, + oracle, or the word + both if you want both drivers installed. - -
-root:/usr/local/src/aolserver# echo "postgresql" > conf-db
- - conf-inst should contain the +
[root@yourserver aolserver]# echo "postgresql" > conf-db +[root@yourserver aolserver]#
conf-inst should contain the location where AOLserver is to be installed. This defaults to /usr/local/aolserver, so we - don't need to change it. + don't need to change it.
conf-make should contain the + name of the GNU Make command on your system. It defaults to + gmake. Verify that gmake is installed:
[root@yourserver aolserver]# gmake -v +GNU Make version 3.79.1, by Richard Stallman and Roland McGrath. +Built for i386-redhat-linux-gnu +Copyright (C) 1988, 89, 90, 91, 92, 93, 94, 95, 96, 97, 98, 99, 2000 + Free Software Foundation, Inc. +This is free software; see the source for copying conditions. +There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A +PARTICULAR PURPOSE. -
+Report bugs to <bug-make@gnu.org>. - conf-make should contain the - name of the GNU Make command on your system. It defaults to - gmake. You may need to change - this to make. -
-root:/usr/local/src/aolserver# echo "make" > conf-make
+[root@yourserver aolserver]#
If you don't get similar results, including an equal or higher version number to 3.79.1, install gmake or check your aliases.
If you're going to be installing the Postgresql driver, you'll have to adjust the makefile first. This will hopefully be cleaned up in future versions of this distribution. -
-root:/usr/local/src/aolserver# emacs pgdriver/makefile
+
[root@yourserver aolserver]# emacs pgdriver/makefile
Edit the lines containing PGLIB and PGINC so they look like this: -
-PGINC=/usr/local/pgsql/include - -PGLIB=/usr/local/pgsql/lib
Compile and install AOLserver and modules
-root:/usr/local/src/aolserver# ./conf
- +
PGLIB=/usr/local/pgsql/lib +PGINC=/usr/local/pgsql/include
Run the conf program, which compiles AOLserver and the default modules and installs them.
[root@yourserver aolserver]# ./conf
+Building in /usr/local/aolserver
+with the following modules:
+aolserver
+nscache
+nsrewrite
+nssha1
+nsxml
+pgdriver
+==================================================================
+Starting Build Sat Mar 8 10:28:26 PST 2003
+Running gmake in aolserver/; output in log/aolserver.log
+(several minute delay here)
+Running gmake in nscache/; output in log/nscache.log
+Running gmake in nsrewrite/; output in log/nsrewrite.log
+Running gmake in nssha1/; output in log/nssha1.log
+Running gmake in nsxml/; output in log/nsxml.log
+Running gmake in pgdriver/; output in log/pgdriver.log
+Creating ...
+==================================================================
+Done Building Sat Mar 8 10:31:35 PST 2003
+[root@yourserver aolserver]# This takes about 5 minutes. All of the results are logged to files in - /usr/local/src/aolserver/log. Make - sure to check these files to see if any errors occurred. + /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@yourserver aolserver]# cd /usr/local/aolserver/bin +[root@yourserver bin]# cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle +[root@yourserver bin]# chmod 750 nsd-oracle +[root@yourserver bin]# +cd /usr/local/aolserver/bin +cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle +chmod 750 nsd-oracle
PostGreSQL
[root@yourserver aolserver]# cd /usr/local/aolserver/bin +[root@yourserver bin]# cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres +[root@yourserver bin]# chmod 755 nsd-postgres +[root@yourserver bin]# +cd /usr/local/aolserver/bin +cp /tmp/openacs-4-6/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres +chmod 755 nsd-postgres
OPTIONAL - 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 nsopenssl tarball in /tmp.
[root@yourserver bin]# cd /usr/local/src/aolserver +[root@yourserver aolserver]# tar xzf /tmp/nsopenssl-2.1.tar.gz +[root@yourserver aolserver]# cd nsopenssl-2.1 +[root@yourserver 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@yourserver nsopenssl-2.1]# cp nsopenssl.so /usr/local/aolserver/bin +[root@yourserver nsopenssl-2.1]# cp https.tcl /usr/local/aolserver/modules/tcl/ +[root@yourserver nsopenssl-2.1]# +cd /usr/local/src/aolserver +tar xzf /tmp/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/
OPTIONAL - install OpenFTS. If you want full text search, + and you are running PostGreSQL, install this module to support + FTS. You will need the openfts + tarball in /tmp.
Install Tsearch. This is a PostGreSQL module that + OpenFTS requires.
[root@yourserver root]# su - postgres +[postgres@yourserver pgsql]$ cd /usr/local/src/postgresql-7.2.3/contrib/tsearch/ +[postgres@yourserver 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@yourserver 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@yourserver tsearch]$ exit +logout -
- - In order to test AOLserver, we'll run it using the sample-config.tcl - file provided in the AOLserver distribution. We need to adjust - permissions a little since AOLserver needs to be able to write its - logs properly. - -
-root:/usr/local/src/aolserver# cd /usr/local/aolserver -root:/usr/local/aolserver# chown -R root.web log servers -root:/usr/local/aolserver# chmod -R g+w log servers -root:/usr/local/aolserver# ls -l - drwxr-sr-x 8 root staff 1024 Nov 12 01:35 . - drwxrwsr-x 12 root staff 1024 Nov 12 01:25 .. - drwxr-xr-x 2 root staff 1024 Nov 12 01:36 bin - drwxr-xr-x 2 root staff 1024 Jun 11 2001 include - drwxr-xr-x 3 root staff 1024 Nov 12 01:36 lib - drwxrwxr-x 2 root web 1024 Nov 12 01:45 log - drwxr-xr-x 3 root staff 1024 Nov 12 01:35 modules - -rw-r--r-- 1 root staff 7320 Mar 31 2001 sample-config.tcl - drwxrwxr-x 3 root web 1024 Nov 12 01:35 servers
-
- - Now, we'll run a quick test to ensure AOLserver is running +[root@yourserver root]# +
su - postgres +cd /usr/local/src/postgresql-7.2.3/contrib/tsearch +make +make install +exit
Unpack the OpenFTS tarball and compile and install + the driver.
[root@yourserver root]# cd /usr/local/src +[root@yourserver src]# tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz +[root@yourserver src]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ +[root@yourserver 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@yourserver 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@yourserver Search-OpenFTS-tcl-0.3.2]# cd aolserver +[root@yourserver 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@yourserver aolserver]# cp nsfts.so /usr/local/aolserver/bin/ +[root@yourserver aolserver]# +cd /usr/local/src +tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz +cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ +./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/ +make +cd aolserver +make +cp nsfts.so /usr/local/aolserver/bin +
Build some supplemental modules.
[root@yourserver aolserver]# cd .. +[root@yourserver Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib +[root@yourserver Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts +[root@yourserver 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@yourserver pgsql_contrib_openfts]# su postgres +[postgres@yourserver 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@yourserver pgsql_contrib_openfts]$ exit +[root@yourserver pgsql_contrib_openfts]# +cd .. +cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib +cd /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts +make +su postgres +make install +exit
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 + group. The sample-config.tcl configuration writes to the + default log locations, so we need to give it permission to do so + or it will fail. Grant the web + group permission to write to + /usr/local/aolserver/log and + /usr/local/aolserver/servers.
[root@yourserver root]# cd /usr/local/aolserver +[root@yourserver aolserver]# chown -R root.web log servers +[root@yourserver aolserver]# chmod -R g+w log servers +[root@yourserver aolserver]# ls -l +total 32 +drwxr-sr-x 2 root root 4096 Mar 8 12:57 bin +drwxr-xr-x 3 root root 4096 Mar 8 10:34 include +drwxr-sr-x 3 root root 4096 Mar 8 10:34 lib +drwxrwsr-x 2 root web 4096 Mar 8 10:31 log +drwxr-sr-x 3 root root 4096 Mar 8 10:31 modules +-rw-r--r-- 1 root root 7320 Mar 31 2001 sample-config.tcl +drwxrwsr-x 3 root web 4096 Mar 8 10:31 servers +[root@yourserver aolserver]# ++cd /usr/local/aolserver +chown -R root.web log servers +chmod -R g+w log servers +ls -l
Now, 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. + IP address.
[root@yourserver aolserver]# ./bin/nsd -t sample-config.tcl -u nobody -g web +[root@yourserver aolserver]# [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: starting to read config file... +[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nsssl not loaded -- key/cert files do not exist. +[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nscp not loaded +-- user/password is not set. +[08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading +config file.
The first warning, about nsssl, can be ignored. We 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.
-
-root:/usr/local/aolserver# ./bin/nsd -t sample-config.tcl -u nobody -g web
- - As the AOLserver daemon starts up, you should see a few normal - warnings (listed below), which are safe to ignore. - -
-Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist. -Warning: nsd.tcl: nscp not loaded -- user/password is not set.
- - The first warning means that the server is missing files for - running ssl, a necessary module - for encrypted HTTPS. See Scott Goodwin's excellent - documentation if you want to set up SSL. The second - warning means that the AOLserver control panel, a special module - for administering AOLserver, could not be loaded. If you're - interested in configuring nscp, please see the AOLserver - documentation. - -
- Test to see if AOLserver is working by starting Mozilla or - Lynx, and surfing over to your - web page: + 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:~# lynx localhost:8000
+
[root@yourserver aolserver]# lynx localhost:8000
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. + 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@yourserver aolserver]# killall nsd +[root@yourserver aolserver]#
- Shutdown the test server: - -
-root:~# killall nsd
- 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. -
- - If you can't view the welcome page, it's likely there's a +
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. You should also try to find lines of the form: -
+[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) [01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections@@ -284,15 +266,36 @@ The sample-config.tcl file grabs your address and hostname from your OS settings. -
+set hostname [ns_info hostname] set address [ns_info address]If you get an error that nssock can't get the requested address, you can set these manually. If you type 0.0.0.0, AOLserver will try to - listen on all available addresses. + listen on all available addresses. Note: + ns_info address doesn't appear + to be supported in current versions of AOLserver. -
+set hostname [ns_info hostname] #set address [ns_info address] -set address 0.0.0.0
OPTIONAL - install Analog web file analyser. You should +have the source tarball in +/tmp. Unpack, compile, and install analog.
[root@yourserver aolserver]# cd /usr/local/src +[root@yourserver src]# tar xzf /tmp/analog-5.31.tar.gz +root@yourserver analog-5.31]# make +cd src && make +make[1]: Entering directory `/usr/local/src/analog-5.31/src' +(many lines omitted) +***IMPORTANT: You must read the licence before using analog +*** +make[1]: Leaving directory `/usr/local/src/analog-5.31/src' +[root@yourserver analog-5.31]# cd .. +[root@yourserver src]# mv analog-5.31 /usr/share/ +[root@yourserver src]# +cd /usr/local/src +tar xzf /tmp/analog-5.31.tar.gz +cd analog-5.31 +make +cd .. +mv analog-5.31 /usr/share/
+
Tcl API
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
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 +
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 Bboard and News. -
OpenACS Services: the aforementioned building blocks. +
OpenACS Services: the aforementioned building blocks. Examples of services include the OpenACS Content Repository, the OpenACS Templating -System, and the OpenACS Kernel, which includes +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 @@ -89,21 +89,21 @@ packages for other ACS 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 +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 +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 locations and names for files and patterns, for OpenACS application @@ -124,7 +124,7 @@ 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 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 +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.
@@ -165,7 +165,7 @@
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 @@ -245,7 +245,7 @@ );
Files associated with a version can be added and removed. The path is -relative to the package-root which is +relative to the package-root which is acs-server-root/packages/package-key.
-- Add a file to the indicated version.
function add_file(
@@ -327,7 +327,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.
@@ -382,7 +382,7 @@ show errors -
Specifying Configuration Parameters for each Instance
A parameter is a setting that can be changed on a package instance basis. +
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 @@ -513,14 +513,14 @@ 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 +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 @@ -542,4 +542,4 @@ 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.
+
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 @@ -29,36 +29,36 @@ 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-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 @@ -72,16 +72,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 @@ -92,195 +92,195 @@ 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 +
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 +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 +
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 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 +
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.200.0 Compound Package Construction
4.200.1 The developer can include .APM packages +
4.200.0 Compound Package Construction
4.200.1 The developer can include .APM packages (sub-packages) within a package (the compound package) like any other -file.
4.200.5 The recommended usage for this feature is to +file.
4.200.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 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.200.10 If a sub-package is required for the +separate package that is required by the compound package.
4.200.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.210.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.210.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.210.0 Compound package Install
4.210.1 If .APM files are present in a package, then it -is considered a compound package.
4.210.5.0 Installation of a compound package proceeds -according to the following sequence:
4.210.5.1 Identify the set of all sub-packages within -the compound package by scanning for all files with .APM.
4.210.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.210.0 Compound package Install
4.210.1 If .APM files are present in a package, then it +is considered a compound package.
4.210.5.0 Installation of a compound package proceeds +according to the following sequence:
4.210.5.1 Identify the set of all sub-packages within +the compound package by scanning for all files with .APM.
4.210.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.210.5.3 Present Administrator with the ability to +first.
4.210.5.3 Present Administrator with the ability to choose which sub-packages to install. Required sub-packages must be -installed.
4.210.5.4 Proceed with the installation of each +installed.
4.210.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.210.5.0.
4.210.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.210.5.0.
4.210.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.210.5.6 Any attempt to install a compound package in +compound package is also a failure.
4.210.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.220.0 Recovering from failed package installation
4.220.1 If any error is generated during package +uninstalled sub-packages.
4.220.0 Recovering from failed package installation
4.220.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. @@ -293,4 +293,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 |
+
+
Vinod Kurup put together the January 2002 version of this guide from many sources of - information.
+ information.
Joel Aufrecht + updated the document in March 2003.
- All questions and comments regarding + All questions and comments regarding this guide should be posted on the OpenACS bboards. -
+
+
By Pete Su and Jon Salz. Modified by Roberto Mello. @@ -400,8 +400,8 @@ db_dml "abort" "abort transaction". -
-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 ] @@ -737,4 +737,4 @@
-
Table of Contents
+
By claus@arsdigita.com, with additions by Roberto Mello and the OpenACS Community -
+
ArsDigita created a good documentation ground for us to build upon. Some sections of the documentation, however, lack details and examples; others are simply nonexistant. Our goal is to give @@ -26,13 +26,13 @@
In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + This enables us to publish in a variety of formats and relieves each contributor of the burden of presentation, freeing him to focus on content and sharing knowledge. @@ -52,11 +52,11 @@ 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: - + the same elements are valid in the XML DTD as long as you remember to: +
Always close your tags with corresponding end-tags and to - not use other tag minimization + not use other tag minimization
Write all elements and attributes in lowercase
@@ -80,7 +80,7 @@ Some editing tool. A popular one is Emacs with the psgml mode. We have a intro to the PSGML Mode in Emacs as part of our documentation. You can - read about other editing tools in the LDP Author Guide. + read about other editing tools in the LDP Author Guide.
After you have the tools mentioned above, you need to define a title for your document. Then start thinking about the possible @@ -99,22 +99,22 @@ 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 @@ -123,20 +123,20 @@ 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>.
- + 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 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 this sect1.
@@ -151,7 +151,7 @@ </sect1>
- + Inside this container your document will be split up into <sect2>'s, each with the same requirements - id and xreflabel @@ -160,7 +160,7 @@ When it comes to naming your 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 will use the tag <computeroutput>. @@ -170,12 +170,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.
- + Linking falls into two different categories: inside the book you're making and outside: -
+
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:
+Check out how I link to a subsection of the Developer's Guide:
Put this in your XML: @@ -212,8 +212,8 @@ 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. -
+ If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different @@ -222,19 +222,19 @@
<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 ampersands in your hyper links. These are reserved for referencing +
NOTE: Do NOT use ampersands in your hyper links. These are reserved for referencing entities, which is exactly how you'll make an ampersand: &
- NOTE: Currently this section currently only takes HTML-output into consideration - + NOTE: Currently this section currently only takes HTML-output into consideration - not a printed version
- Another Note: Also, it's still not a 100 percent sure that this is how we are going to + Another Note: Also, it's still not a 100 percent sure that this is how we are going to do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)
- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -260,9 +260,9 @@ 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: -
+
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> @@ -275,7 +275,7 @@ <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -
+
The ordered list is like the preceding, except that you use <orderedlist> instead:
<orderedlist> @@ -284,7 +284,7 @@ <listitem><para>More stuff goes here</para></listitem> </orderedlist> -
+
This kind of list is called a variablelist and these are the tags you'll need to make it happen: <variablelist>, @@ -305,7 +305,7 @@ </variablelist>
- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -342,7 +342,7 @@ <table> for an example.
- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <emphasis>.
@@ -376,7 +376,7 @@
bash$ xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
bash$ xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
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
@@ -82,4 +82,4 @@
debugging (e.g. the error will say something like
"Cannot insert null value into column"), we recommend naming not null
constraints to be consistent in our naming of all constraints.
-($Id$)By michael@arsdigita.com and +
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 @@ -156,7 +156,7 @@ @author John Doe (jdoe@arsdigita.com) @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp } -
+
For SQL and other non-Tcl source files, the following file header structure is recommended:
-- path relative to the ACS root directory
@@ -229,4 +229,4 @@
By You
+
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,7 +11,7 @@ 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.
@@ -80,10 +80,6 @@ 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. -
- Also noteworthy is that although the OpenACS currently utilizes the - AOLserver Tcl API, the current drive towards Java is likely to effect - a change in the content of these sections in the future.
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 @@ -98,7 +94,7 @@ 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 + 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.
@@ -119,7 +115,7 @@ within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics.
- Under OpenACS 4.6, parameters are set at two levels: at the global level by + Under OpenACS 4.6.2, 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.
@@ -140,4 +136,4 @@
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 |
| 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 |
High level information: What is OpenACS?
Table of Contents
High level information: What is OpenACS?
Table of Contents
Table of Contents
Table of Contents
+
User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
Data model
PL/SQL file
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, @@ -62,16 +62,16 @@
The set of direct membership relationships between a group and a party.
A mapping of a party P to the groups -{Gi}the party is a member of; this mapping +
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.
The set of direct component relationships between a group and another group.
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 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 @@ -116,26 +116,26 @@
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 +group. This view is strictly a mapping of approved members to groups.
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 appropriaterel_id from the composition_rels table.
A mapping of a party P to the set of parties -{Pi} party P is a member +
A mapping of a party P to the set of parties +{Pi} party P is a member of.
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_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 +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 @@ -162,7 +162,7 @@ function person.name ( person_id persons.person_id%TYPE ) return varchar; -
User
acs_user.new creates a new user and returns the user_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_names and last_name. All other fields are optional. The interface for this function is:
@@ -204,7 +204,7 @@ procedure acs_user.unapprove_email ( user_id users.user_id%TYPE ); -
Group
acs_group.new creates a new group and returns the +
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 @@ -232,7 +232,7 @@ group_id groups.group_id%TYPE, party_id parties.party_id%TYPE, ) return char; -
Membership Relationship
membership_rel.new creates a new membership relationship 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:
@@ -278,7 +278,7 @@ procedure membership_rel.delete ( rel_id membership_rels.rel_id%TYPE ); -
Composition Relationship
composition_rel.new creates a new composition relationship type +
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:
@@ -301,4 +301,4 @@
| 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 |
| 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 |
+
In sum, the goal of the Parties and Groups system is to +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 @@ -68,158 +68,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:
The data model for the parties and groups system must provide support for +the following types of entities:
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.
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.
A group is a collection of zero or more parties.
20.10 The data model should support the subclassing of -groups via OpenACS Objects.
A group is a collection of zero or more parties.
20.10 The data model should support the subclassing of +groups via OpenACS Objects.
A person represents an actual human being, past or -present.
A person represents an actual human being, past or +present.
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:
-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.
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:
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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
The parties and groups system provides an API for answering the question: -"Is party P a member of group -G?"
The parties and groups system provides an API for answering the question: -"Is group GC a component of group -GP?"
The parties and groups system provides an API for answering the question: -"Which parties are members of group G?"
The parties and groups system provides an API for answering the question: -"Which groups are components of group G?"
The parties and groups system provides an API for answering the question: -"Of which groups is party P a member?"
The parties and groups system provides an API for answering the question: -"Of which groups is group G a component?"
The parties and groups system provides an API for answering the question: -"Is party P allowed to become a member of group -G?"
The parties and groups system provides an API for answering the question: -"Is group GC allowed to become a component -of group GP?"
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.
Since many SQL queries will check membership in a group as part of the 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 |
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 |
Table of Contents
Table of Contents
List of Figures
+
- This document will describe how to install OpenACS 4.6 from scratch, - using the source code. We will assume that you have an OS installed, - but we'll discuss this more in the next section. For most of this - guide, we will assume that you are using Linux on a PC, but we'll - also point you to excellent step-by-step guides for other operating - systems. + + This document will describe how to install, configure, and + maintain an installation of OpenACS 4.6.2 on a Unix-like + system, including all supporting software. All examples + in this chapter are part of the OpenACS 4.6.2-P or + OpenACS 4.6.2-O Reference Platform, which use Red + Hat 8.0. Differences between the Reference Platform + and common alternate platforms are noted where known.
You will need a PC (or equivalent) with at least these minimum requirements:
Pentium processor
128 MB RAM - (much more if you want Oracle)
4 GB hard drive
+ (much more if you want Oracle)
4 GB hard drive
You will need all of the required Chapter 2.
If you want to serve pages to people outside of your machine, you'll need a network connection of some type.
@@ -53,12 +55,12 @@
Adding users, groups, setting passwords
- Starting an X server and running an X program remotely + (For Oracle) Starting an X server and running an X program remotely
Basic file management using cp, rm, mv, and cd
- Compiling a program using a Makefile + Compiling a program using ./config and make.
If you've never done these things before, consider exploring UNIX in greater depth before installing OpenACS. Some useful resources for @@ -71,11 +73,25 @@
The basic steps to getting OpenACS up and running are:
Install an OS
Install a webserver (AOLServer)
Install a database (Oracle or - PostgreSQL)
Install a database - driver (allows the webserver to talk to the database) -
Configure the webserver and - database
Start the OpenACS - installer
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.
[root@localhost root]# su - nsadmin +[nsadmin@localhost aolserver]$ svc -d /service/server1 +[nsadmin@localhost aolserver]$ dropdb server1 +DROP DATABASE +[nsadmin@localhost aolserver]$ createdb server1 +CREATE DATABASE +su - nsadmin +svc -d /service/server1 +dropdb server1 +createdb server1
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: @@ -97,9 +113,13 @@ 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 openprojects.net - (#openacs). They're knowledgeable and quite friendly if you can - keep them on topic. + (#openacs). They're knowledgeable and quite friendly + if you can keep them on topic.
Post a question on the bboards. Make sure you've done a search first. When you do post, be sure to include @@ -118,15 +138,16 @@ better way. Well, not quite. Jonathan Marsden has created RPMs (at http://www.xc.org) for OpenACS 4.5 but there are not yet any for version - 4.6. There has been talk about automating the install process, + 4.6.2. There has been talk about automating the install process, but that hasn't happened yet. Stay tuned!
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. -
These are a few of my sources:
+
Version 4.6.x was edited by Joel Aufrecht. +
These are a few of my sources:
Please also see the Credits section for more acknowledgements. -
+ Here's a list of some helpful documentation for various OS's +
+ Painless Debian + GNU/Linux by Stephen van Egmond +
+ + Official + Debian Guide + +
+ + RedHat + +
+ + Mandrake + +
+ + SuSE + +
+ Once you get your OS installed, it's imperative that you secure your + installation. As Jon Griffin repeatedly warns us, "No distribution is + secure out of the box." The Reference Platform implements + some basic precautions, but security is a process, not a + condition. If you are responsible for a computer hooked to the + internet, you are responsible for learning some rudiments of + security, such as monitoring the state of a computer, + maintaining patch levels, and keeping backups. We recommend + these resources: +
Here are some resources that OpenACS users have found useful.
Table of Contents
Table of Contents
- Compared to its predecessors, version 4.6 of OpenACS has a much +
+ Compared to its predecessors, version 4.6.2 of OpenACS has a much more structured organization, i.e. the most significant change is found at the system architecture level, reflected in the following hierarchy: -
The OpenACS 4.6 Kernel, which handles system-wide necessities - such as metadata, security, users and groups, subsites, and - package management and deployment. -
The OpenACS 4.6 Core, which comprises all the other packages - that ship with the kernel and are most frequently needed by users, - such as templating, bboard, and user registration/management. The - packages tend to be developed and distributed with the kernel. -
OpenACS 4.6 Application packages, which typically provide - user-level web services built on top of the Kernel and Core. Such - packages include those built by ArsDigita as well as external - contributors. Application packages are developed separately from - the Kernel, and are typically released independently of it. +
+ The OpenACS 4.6.2 Kernel, which + handles system-wide necessities such as metadata, + security, users and groups, subsites, and package + management and deployment. +
+ The OpenACS 4.6.2 Core, which + comprises all the other packages that ship with the + kernel and are most frequently needed by users, such as + templating, bboard, and user + registration/management. The packages tend to be + developed and distributed with the kernel. +
+ OpenACS 4.6.2 Application + packages, which typically provide user-level + web services built on top of the Kernel and Core. Such + packages include those built by ArsDigita as well as + external contributors. Application packages are + developed separately from the Kernel, and are typically + released independently of it.
This document provides a high level overview of the kernel - package. Documentation for the other packages can be found elsewhere. -
+
One of the major design features of OpenACS 4.6.2 is the explicit representation 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 4.6 data model this +scope) to identify an object. In the 4.6.2 data model this object is explicitly represented by a single party_id.
Another good example of this is can be found in the user groups data model. The 3.x user groups data model contains another example of an implied identity. Every mapping between a user and a group could have an arbitrary number of attached values (user_group_member_fields, etc.). In this case it is the pair (group_id, user_id) that implicitly refers to an -object (the person's membership in a group). In the 4.6 data model this +object (the person's membership in a group). In the 4.6.2 data model this object identity is made explicit by adding an integer primary key to the table that maps users to groups.
Coming from a purely relational world, this might seem slightly weird at first. The pair (group_id, user_id) is sufficient to uniquely identify the @@ -33,4 +33,4 @@ even capable of fully tracking the history of membership state.
The design choice of explicitly representing object identity with an integer primary key that is derived from a globally unique sequence is the key to eliminating redundant code and replacing it with generic object -level services.
+
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 object in OpenACS 4 has a unique ID which is mapped to a row in a central table @@ -77,14 +77,14 @@ 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 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 +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 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_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, +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 @@ -245,8 +245,8 @@ 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 +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:
Pete Su generated this document from material culled from other documents by Michael Yoon, Richard Li and Rafael Schloming. But, any remaining lies -are his and his alone.
| Document Revision # | Action Taken, Notes | When? | By Whom? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 0.1 | Creation | 9/09/2000 | Pete Su | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 0.2 | Edited for ACS 4 Beta | 9/30/2000 | Kai Wu | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 0.3 | Edited for ACS 4.0.1, fixed some mistakes, removed use of term
+are his and his alone.
+ The OpenACS 4 Object Model must address five high-level requirements that repeatedly exhibit themselves in the context of existing services in OpenACS 3.x, -as described below. Object Identifiers for General Services Generic services require a single unambiguous way of identifying +as described below. Object Identifiers for General Services Generic services require a single unambiguous way of identifying application objects that they manage or manipulate. In OpenACS 3.x, there are several different idioms that construct object identifiers from other data. Many modules use a (user_id, group_id, scope) triple combination @@ -46,12 +46,12 @@ that their definition and use is ad-hoc and inconsistent. This makes the construction of generic application-independent services difficult. Therefore, the OpenACS 4 Object Model should provide a centralized and uniform -mechanism for tagging application objects with unique identifiers. Support for Unified Access Control Access control should be as transparent as possible to the application +mechanism for tagging application objects with unique identifiers. Support for Unified Access Control Access control should be as transparent as possible to the application developer. 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_book table:
The first row represents an entry in User 123's personal address book, +hypothetical rows in the address_book table:
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 @@ -65,7 +65,7 @@ page, a security problem could result. Thus the OpenACS 4 Object Model must support a more general access control system that allows access control domains to be hierarchical, and specifiable with a single piece of data, instead of the old composite keys described -above. Extensible Data Models Another problem with previous OpenACS data models is that many of the central +above. Extensible Data Models Another problem with previous OpenACS data models is that many of the central tables in the system became bloated as they were extended to support an increasing number of modules. The users table is the best case in point: it became full of columns that exist for various special @@ -83,10 +83,10 @@ custom extensions to the existing data models, and the OM does the bookkeeping necessary to make this easier, providing a generic API for object creation that automatically keeps track of the location and relationships -between data. Design Note: While this doesn't really belong in a +between data. Design Note: While this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object -data model exist, which you can read about in Summary and Design Considerations. Modifiable Data Models Another recurring applications problem is how to store a modifiable data +data model exist, which you can read about in Summary and Design Considerations. Modifiable Data Models Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. Furthermore, we want to avoid changes to an application's database queries in the face of any custom @@ -103,7 +103,7 @@ store values for those attributes. Thus the Object Model must provide a general mechanism for applications and developers to modify or extend data models, without requiring changes to the SQL schema of the system. This ensures that all applications use the same -base schema, resulting in a uniform and more maintainable system. Generic Relations Many OpenACS applications define simple relationships between application +base schema, resulting in a uniform and more maintainable system. Generic Relations Many OpenACS applications define simple relationships between application objects, and tag those relationships with extra data. In OpenACS 3.x, this was done using mapping tables. The user/groups module has the most highly developed data model for this purpose, using a single table called @@ -127,8 +127,8 @@ that store metadata on application objects. The object type system supports subtyping with inheritance, so new object types can be defined in terms of existing object types. The OM data model forms the main part of the OpenACS 4 Kernel data model. The -other parts of the Kernel data model include:
Each of these is documented elsewhere at length. The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing OpenACS modules:
The data model for the object system provides support for the following +kinds of schema patterns that are used by many existing OpenACS modules:
40.10 Generic Retrieval Attributes should be stored so that they are retrievable in a way that is independent of the type of the object that they belong to. That is, the only data needed to retrieve an attribute should be the system-wide ID of an -object (see requirement 10.20 above) and the attribute name. 40.20 Inherited Attributes The system should allow for the automatic retrieval of inherited attribute -values, for an object belonging to a subtype. 40.30. Constraints on Attributes The system should allow the developer to put down constraints on the +object (see requirement 10.20 above) and the attribute name. 40.20 Inherited Attributes The system should allow for the automatic retrieval of inherited attribute +values, for an object belonging to a subtype. 40.30. Constraints on Attributes The system should allow the developer to put down constraints on the values that an attribute may hold, for the purposes of maintaining -application specific integrity rules. In OpenACS 3.x, there was a notion of "scope" for application +application specific integrity rules. In OpenACS 3.x, there was a notion of "scope" for application objects. An object could be belong to one of three scopes: public, group or user. This provided a crude way to associate objects with particular scopes in the system, but it was awkward to use and limited in flexibility. The OpenACS 4 Object Model provides a generalized notion of scope that allows @@ -205,64 +205,64 @@ object has no explicit permissions attached to it, then it inherits permissions from its context. The context data model also forms the basis of the subsites system, and is a basic part of the permissions system, -described in separate documents. The context data model should provide the following facilities: 50.10 Unique ID Every context should have a unique ID in the system. 50.20 Tree Structure The data model should support a tree structured organization of contexts. +described in separate documents. The context data model should provide the following facilities: 50.10 Unique ID Every context should have a unique ID in the system. 50.20 Tree Structure The data model should support a tree structured organization of contexts. That is, contexts can be logically "contained" within other contexts (i.e. contexts have parents) and contexts can contain other contexts -(i.e. contexts can have children). 50.30 Data Model Constraints All objects must have a context ID. This ID must refer to an existing +(i.e. contexts can have children). 50.30 Data Model Constraints All objects must have a context ID. This ID must refer to an existing context or be NULL. The meaning of a NULL context is determined by the -implementation. Note: The current system interprets the NULL context as meaning the default +implementation. Note: The current system interprets the NULL context as meaning the default "site-wide" context in some sense. I wanted to note this fact for others, but there is no need to make this a requirement of the system. I think it would be reasonable to have a NULL context be an error (psu -8/24/2000). The data model should include a notion of pair-wise relations between +8/24/2000). The data model should include a notion of pair-wise relations between objects. Relations should be able to record simple facts of the form "object X is related to object Y by relationship R," and also be -able to attach attributes to these facts. The API should let programmers accomplish the following actions:
The API should let programmers accomplish the following actions:
($Id$) |
+
The APM is used to create, maintain, and install packages. It takes care of copying all of the files and registering the package in the @@ -147,7 +147,7 @@
The following sections will show you how to make a package for the Notes application. In addition, they will discuss some new site - management features in OpenACS 4.6 that take advantage of the APM's package + management features in OpenACS 4.6.2 that take advantage of the APM's package instance model. The two most important of these are subsites, and the site map tool, which can be used to map applications to one or more arbitrary URLs in a running site. @@ -365,7 +365,7 @@ notes.info file. Create a file called ROOT/packages/notes/sql/oracle/notes-create.sql. We'll - fill this file with our data model + fill this file with our data model very soon. Create a file called ROOT/packages/notes/sql/oracle/notes-drop.sql. This will contain the instructions to drop the data model. To be @@ -435,7 +435,7 @@ map content that lived outside the page root into the site, and it was also hard to map mulitiple URLs to the same place in the file system.
- In OpenACS 4.6, administrators can define an arbitrary mapping between the + In OpenACS 4.6.2, administrators can define an arbitrary mapping between the URLs the user types and the actual file in the file system that is served. This mapping is called the site map and entries in the site map are called site nodes. Each site node maps a URL to an @@ -450,7 +450,7 @@ of many indedendent applications that actually run on a single shared code base. The request-processor document shows you how OpenACS figures out which instance of your application was - requested by the user at any given time. The page development tutorial shows you how to use this + requested by the user at any given time. The page development tutorial shows you how to use this information in your user interface.
In order to make the new notes application visible to @@ -477,7 +477,7 @@ yet written Notes application at various places in the site. In a later document, we'll see how to write your application so that the code can detect from what URL it was invoked. This is the key - to supporting subsites. + to supporting subsites.
The APM performs the following tasks in an OpenACS site:
@@ -493,4 +493,4 @@
Writes out package distribution files for other people to download and install. We'll cover this later. -
+
Most developers who do significant work with the OpenACS will become intimately familiar with the parties data model, and probably extend it on many occasions. For this reason the parties developer guide will begin with -an introduction to the data model.
Parties
The central table in the parties data model is the parties table itself. +an introduction to the data model.
Parties
The central table in the parties data model is the parties table itself. Every party has exactly one row in this table. Every party has an optional unique email address and an optional url. A party is an acs object, so permissions may granted and revoked on parties and auditing information is @@ -39,7 +39,7 @@ table and one is the groups table. A row in the persons table represents the most basic form of individual that is modeled by the parties data model. A row in the groups table represents the most basic form of an aggregation of -individuals that is represented.
Persons
If a party is an individual then there will be a row in the persons table +individuals that is represented.
Persons
If a party is an individual then there will be a row in the persons table containing first_names and last_name for that individual. Note that the primary key of the persons table (person_id) references the primary key of the parties table (party_id). This guarantees that if there is a row in the @@ -57,7 +57,7 @@ ); -
Users
The users table is an even more specialized form of an individual. A row +
Users
The users table is an even more specialized form of an individual. A row in the users table represents an individual that has login access to the system. Note that the primary key of the users table references the primary key of the persons table. Once again this guarantees that if there is a row @@ -67,8 +67,8 @@ users) is that it is now possible to "nuke" a user from a live system by removing his entry from the users table, but leaving the rest of his information present (i.e. turning him from a user into a person). This is -because wherever possible the OpenACS 4.6 data model references the persons or -parties table, not the users table. If this feature is +because wherever possible the OpenACS 4.6.2 data model references the persons or +parties table, not the users table. If this feature is desired when extending the system, then the developers should be careful to only references the users table in situations where it is clear that the references is to a user and not to an individual.
@@ -100,7 +100,7 @@ ); -
Groups
The final piece of the parties data model is the groups data model. A +
Groups
The final piece of the parties data model is the groups data model. A group is a specialization of a party that represents an aggregation of other parties. The only extra information directly associated with a group (beyond that in the parties table) is the name of the group. As you might guess there @@ -116,7 +116,7 @@ ); -
Group Relations
One surprise here is that there are actually two relations involved. One +
Group Relations
One surprise here is that there are actually two relations involved. One is the normal membership relation between parties and groups. A party may be a "member" of a group. The other relation is a composition relation between two groups. To fully understand why two relations are @@ -134,7 +134,7 @@ composition. Having a membership relation between groups and parties, and having a composition relation between groups and groups allows us to easily model the full range of sophisticated group structures that exist in the real -world.
Group Membership
Group memberships can be created and manipulated using the membership_rel +world.
Group Membership
Group memberships can be created and manipulated using the membership_rel package. Note that you can only create one membership object for a given group, party pair. Because of composition, it is possible in some circumstances to make someone a member of a group of which they are already a @@ -183,7 +183,7 @@ show errors -
Group Composition
Composition relations can be created or destroyed using the +
Group Composition
Composition relations can be created or destroyed using the composition_rel package. The only restriction on compositions is that there cannot be a cycle, i.e., a group cannot be a component of itself either directly or indirectly. This constraint is maintained for you by the API, but @@ -289,7 +289,7 @@ but it is foolish to assume that this data model is sufficient for every application. It therefore seems likely that developers will want to extend the parties data model in a number of ways. This section will describe some -of the more common ways.
Specializing Users
It is conceivable that some applications will want to collect more +of the more common ways.
Specializing Users
It is conceivable that some applications will want to collect more detailed information for people using the system. If it is the case that there can be only one such piece of information per user, then it might make sense to create another type of individual that is a further specialization @@ -299,12 +299,12 @@ have a primary key that references the users table, thereby guaranteeing that each row in the mensa_users table has a corresponding row in each of the users, persons, parties, and acs_objects tables. This child table could then -store any extra information relevant to the MENSA community.
Specializing Groups
If one were to build an intranet application on top of the 4.6 party +store any extra information relevant to the MENSA community.
Specializing Groups
If one were to build an intranet application on top of the 4.6.2 party system, it is likely that one would want to take advantage of the systems efficient representation of sophisticated organizational structures, but there would be much more specialized information associated with each group. In this case it would make sense to specialize the group party type into a -company party type in the same manner as above.
Specializing Membership Relations
The final portion of the parties data model that is designed to be +company party type in the same manner as above.
Specializing Membership Relations
The final portion of the parties data model that is designed to be extended is the membership relationship. Consider the intranet example again. It is likely that a membership in a company would have more information associated with it than a membership in an ordinary group. An obvious example @@ -313,4 +313,4 @@ single integer primary key in what could be thought of as a pure relation. Because a membership relation is an ordinary acs object with object identity, it is as easy to extend the membership relation to store extra information as it is to extend the users -table or the groups table.
+
There are also a number of views to make it easier to ask specific @@ -78,7 +78,7 @@ a party is a member of a group (at any depth).
Relation with every (object, party, method) -tuple implied by the above trees.
In general, only acs_object_party_method_map +tuple implied by the above trees.
In general, only acs_object_party_method_map should be used for queries from other modules. The other views are intermediate steps in building that query.
The data model also includes two simple PL/SQL procedures (acs_permission.grant_permission and @@ -95,15 +95,15 @@ acs_privilege_hierarchy)
objects get access control from direct grants, or inherit permissions from their context (unless the "don't inherit" flag is set)
There are three essential areas in which all transactions in the -permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and privileges." This +permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and privileges." This refers to actions that happen mainly at package installation time - a package will create a number of methods for its own use, then associate them with the system's standard privileges, or new privileges which the package has created. The association step might also happen later, if the site-wide administrator chooses to change permissions policy.
These steps involve directly manipulating the acs_methods, acs_privileges, and acs_privilege_method_rules tables. A web page for manipulating these features should be limited to site-wide -administrators.
"Modification of permissions" - involves fairly +administrators.
"Modification of permissions" - involves fairly common operations. Users are typically able to administer permissions for objects they themselves create. The two basic operations here are "grant" and "revoke". Granting permissions is done via @@ -112,7 +112,7 @@ acs_permissions table.
Web pages for making these changes are available to all users, so they should not be in an admin area. In order to grant and revoke permissions on an object, the user must have the administer_privileges method -permission on that object.
"Queries on permissions" - by far the most +permission on that object.
"Queries on permissions" - by far the most common operation is querying the permissions database. Several kinds of questions are commonly asked: First, and most commonly, "Can this party perform this method on this object?" Two Tcl functions are provided to @@ -127,15 +127,15 @@ for appropriate methods.
Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. This is done by querying against acs_permissions.
The API to the permissions system consists of a few well-known tables, -plus a pair of PL/SQL procedures and a pair of Tcl functions.
Tables
acs_methods, acs_privileges, and +plus a pair of PL/SQL procedures and a pair of Tcl functions.
Tables
acs_methods, acs_privileges, and acs_privilege_method_rules manage the set of permissions in the system. At installation time, a package will add to these three tables to introduce new permissions into the system.
The main table for queries is acs_object_party_method_map, which contains (object, party, method) triples for all allowed operations in the system.
Also of interest for queries is acs_permissions, which lists directly granted privileges. Neither acs_object_party_method_map (which is a view) nor acs_permissions should be updated -directly.
PL/SQL Procedures
acs_permissions.grant_permission introduces new permissions for +directly.
PL/SQL Procedures
acs_permissions.grant_permission introduces new permissions for an object. It should be given an (object, party, privilege) triple, and will always succeed. If the permission is already in the system, no change occurs. The interface for this procedure @@ -154,7 +154,7 @@ privilege acs_permissions.privilege%TYPE );
These procedures are defined in -permissions-create.sql
Tcl Procedures
Two tcl procedures provide a simple call for the query, "Can this +permissions-create.sql
Tcl Procedures
Two tcl procedures provide a simple call for the query, "Can this user perform this method on this object?" One returns true or false, the other presents an error page.
To receive a true or false value, Tcl code should call:
ad_permission_p $object_id $object_type $method -user_id $user_id @@ -184,4 +184,4 @@
| Document Revision # | Action Taken, Notes | When? | By Whom? |
| 0.1 | Creation | 9/11/2000 | John Prevost |
| 0.2 | Edited for ACS 4 Beta release | 10/04/2000 | Kai Wu |
+
Terminology
The primary question an access control system must answer is a three-way +or fall outside the common administrative interfaces.
Terminology
The primary question an access control system must answer is a three-way relation, like that between the parts of most simple sentences. A simple sentence generally has three parts, a subject, an object, and a verb - in the context of OpenACS Permissions, our simple sentence is, "Can this party -perform this operation on this target?" Definitions:
The subject of the sentence is "party" - a +perform this operation on this target?" Definitions:
The subject of the sentence is "party" - a distinguishable actor whose access may be controlled, this special word is used because one person may be represented by several parties, and one party -may represent many users (or no users at all).
The object of the sentence is "target" - this +may represent many users (or no users at all).
The object of the sentence is "target" - this is an entity, or object, that the party wishes to perform some action on. An entity/object here is anything that can be put under access control.
The verb of the sentence is "operation" - a behavior on the OpenACS system subject to control, this word is used to represent the fact that a @@ -50,43 +50,43 @@ that operation.
Examples of the essential question addressed by the Permissions system: Can jane@attacker.com delete the web security bboard? Can the Boston office (a party) within the VirtuaCorp intranet/website create its own news -instance?
10.0 Granularity
The system must support access control down to the level of a single +instance?
10.0 Granularity
The system must support access control down to the level of a single entity (this would imply down to the level of a row in the OpenACS Objects data -model).
20.0 Operations
The system itself must be able to answer the essential permissions -question as well as several derived questions.
20.10 Basic Access Check
The system must be able to answer the question, "May party P perform -operation O on target T?"
20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may -perform operation O on target T?"
20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may -party P perform on target T?"
20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets -may party P perform operation O?"
40.0 Scale of Privileges
Privileges must be designed with appropriate scope for a given OpenACS +model).
20.0 Operations
The system itself must be able to answer the essential permissions +question as well as several derived questions.
20.10 Basic Access Check
The system must be able to answer the question, "May party P perform +operation O on target T?"
20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may +perform operation O on target T?"
20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may +party P perform on target T?"
20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets +may party P perform operation O?"
40.0 Scale of Privileges
Privileges must be designed with appropriate scope for a given OpenACS package. Some privileges are of general utility (e.g. "read" and "write"). Others are of more limited use (e.g. "moderate" - applies mainly to a package like bboard, where many users are contributing content simultaneously). A package defining its own privileges should do so with moderation, being careful not to overload a privilege like -"read" to mean too many things.
50.0 Aggregation of Operations (Privileges)
For user interface purposes, it can be appropriate to group certain +"read" to mean too many things.
50.0 Aggregation of Operations (Privileges)
For user interface purposes, it can be appropriate to group certain privileges under others. For example, anyone with the "admin" privilege may also automatically receive "read", "write", -"delete", etc. privileges.
60.0 Aggregation of Parties (Groups)
The system must allow aggregation of parties. The exact method used for +"delete", etc. privileges.
60.0 Aggregation of Parties (Groups)
The system must allow aggregation of parties. The exact method used for aggregation will probably be addressed by the OpenACS 4 "Groups" system. Regardless of the exact behavior of aggregate parties, if an aggregate party exists, then access which is granted to the aggregate party -should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from +should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from some context. For example, if you do not have read access to a bboard, you -should not have read access to a message in that bboard.
70.20 Overriding
It must be possible to override defaults provided by the context of an -object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they +should not have read access to a message in that bboard.
70.20 Overriding
It must be possible to override defaults provided by the context of an +object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they would get by default. (For example, a user does not have the right to edit any message on a bboard. But a user does possibly have the right to edit -their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their +their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their inherited privileges would have allowed. (For example, a subdirectory in the file-storage might normally have its parent directory as context. It should -be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check +be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check (20.40) must be efficient enough for general use, i.e. scalable under fairly heavy website traffic. It can be expected that almost every page will contain at least one basic access check, and most pages will contain an allowed targets check (20.40).
In particular, constraining a SELECT to return only rows the current user has access to should not be much slower than the SELECT -on its own.
120.0 Ease of Use
Since most SQL queries will contain an allowed target check in the where +on its own.
120.0 Ease of Use
Since most SQL queries will contain an allowed target check in the where clause, whatever mechanism is used to make checks in SQL should be fairly small and simple.
In particular, constraining a SELECT to return only rows the -current user has access to should not add more than one line to a query.
| Document Revision # | Action Taken, Notes | When? | By Whom? | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 0.1 | Creation | 8/17/2000 | John Prevost | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 0.2 | Revised, updated with new terminology | 8/25/2000 | John Prevost | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| 0.3 | Edited, reformatted to conform to requirements template, pending
+current user has access to should not add more than one line to a query.
+ by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello The general permissions system has a relatively complex data model in OpenACS 4.x. @@ -86,7 +86,7 @@ to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users who have the read privilege on all objects, then we would need to store 100,000,000 entries of the form: - Table�5.1.�
+ Table 8.1.
Although quite feasible, this approach fails to take advantage of the fact that objects in the system are commonly organized hierarchally, and permissions usually follow the hierarchical structure, so that if user @@ -101,7 +101,7 @@ Suppose objects A, B, ..., and F form the following hierarchy. - Table�5.2.�
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
