Administrator's Guide

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Unpack the Aolserver tarball.�Download the aolserver tarball and unpack it.

[root@yourserver root]# cd /usr/local/src
@@ -15,16 +15,16 @@
 15:39:05 (66.56 KB/s) - `aolserver3.3oacs1.tar.gz' saved [3858074/3858074]
 [root@yourserver src]# tar xzf aolserver3.3oacs1.tar.gz
 [root@yourserver src]#
-cd /usr/local/src
+cd /usr/local/src
 wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz
-tar xzf aolserver3.3oacs1.tar.gz

This section also relies on some OpenACS files, which you can get with the section called “Unpack the OpenACS tarball”.

Compile AOLserver.�Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.
```
root@yourserver root]# mkdir -p /usr/local/aolserver
+tar xzf aolserver3.3oacs1.tar.gz
```
This section also relies on some OpenACS files, which you can get with the section called “Unpack the OpenACS tarball”.

Compile AOLserver.�Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.

root@yourserver root]# mkdir -p /usr/local/aolserver
 [root@yourserver root]# cd /usr/local/src/aolserver
 [root@yourserver aolserver]# ./conf-clean
 cat: BUILD-MODULES: No such file or directory
 Done.
-[root@yourserver aolserver]#mkdir -p /usr/local/aolserver
+[root@yourserver aolserver]#mkdir -p /usr/local/aolserver
 cd /usr/local/src/aolserver
-./conf-clean

+./conf-clean

If you are using Oracle, edit conf-db and change postgresql to @@ -72,20 +72,20 @@ 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 + 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-5.0.0b1/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
+[root@yourserver bin]# cp /tmp/openacs-5.0.0b4/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-5.0.0b1/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-5.0.0b1/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
+cd /usr/local/aolserver/bin
+cp /tmp/openacs-5.0.0b4/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-5.0.0b4/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-5.0.0b1/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
-chmod 755 nsd-postgres

Install tDOM.�Download the tDOM +cd /usr/local/aolserver/bin +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres +chmod 755 nsd-postgres

Install tDOM.�Download the tDOM tarball, unpack it, adjust the configuration file to match our patched distribution of aolserver, and compile it.

[root@yourserver root]# cd /usr/local/src
 [root@yourserver src]# wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz
@@ -103,10 +103,10 @@
 [root@yourserver src]# tar xzf tDOM-0.7.8.tar.gz
 [root@yourserver src]# cd tDOM-0.7.8/unix
 [root@yourserver unix]#
-cd /usr/local/src
+cd /usr/local/src
 wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz
 tar xzf tDOM-0.7.8.tar.gz
-cd tDOM-0.7.8/unix

Edit the file CONFIG and change this section:

# ----------------------------------------------------
+cd tDOM-0.7.8/unix

Edit the file CONFIG and change this section:

# ----------------------------------------------------
 # aolsrc="/usr/src/aolserver-3.4"
 # ../configure --enable-threads --disable-tdomalloc \
 #   --with-aolserver=$aolsrc \
@@ -131,11 +131,11 @@
 [root@yourserver bin]# ln -s libtdom0.7.8.so libtdom.so
 [root@yourserver bin]#
 
-sh CONFIG
+sh CONFIG
 make
 cp libtdom0.7.8.so /usr/local/aolserver/bin/
 cd /usr/local/aolserver/bin
-ln -s libtdom0.7.8.so libtdom.so

Install nsopenssl +ln -s libtdom0.7.8.so libtdom.so

Install nsopenssl (OPTIONAL)

Install Full Text Search with OpenFTS (OPTIONAL)

Install nspam (OPTIONAL)

Test AOLserver.�In order to test AOLserver, we'll run it using the sample-config.tcl file provided in the AOLserver distribution, under the nobody user and web @@ -157,11 +157,11 @@ -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 +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 @@ -194,7 +194,7 @@ The killall command will kill all processes with the name nsd, but clearly this is not a good tool to use for managing your - services in general. We cover this topic in the Keep AOLServer alive section. + services in general. We cover this topic in the Keep AOLserver alive section.

Troubleshooting.�If you can't view the welcome page, it's likely there's a problem with your server configuration. Start by viewing your @@ -230,4 +230,4 @@ set hostname [ns_info hostname] #set address [ns_info address] set address 0.0.0.0

Install - Analog web file analyzer. (OPTIONAL)

($Id$)

Prev	Home	Next
Install PostGreSQL	Up	Install OpenACS 5.0.0b1

View comments on this page at openacs.org + Analog web file analyzer. (OPTIONAL)

OpenACS 5.0.0b1 Package Manager Design

By Bryan Quinn

+Package Manager Design

Prev	Chapter�11.�Kernel Documentation	Next

Package Manager Design

By Bryan Quinn

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Essentials

OpenACS Administrator directory
OpenACS 5.0.0b1 Package Manager Requirements
Packages
ER diagram

Tcl API

Essentials

OpenACS Administrator directory
Package Manager Requirements
Packages
ER diagram
Tcl API
- apm-procs.tcl
- apm-install-procs.tcl (Supports installation of packages)
- 20-apm-load-procs.tcl (Bootstraps APM for server startup)
- @@ -23,10 +23,10 @@
- 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 +end-users. Packages function as individual pieces of subsites. A subsite can contain multiple application and service instances that provide the end-user with capabilities and content customized to the particular subsite.
This architecture supports the growth of collaborative commerce. For example, Jane User starts a forum focusing on the merits of View Cameras by @@ -82,12 +82,12 @@ cleanly separated from ACS code. Consequently, upgrading an already installed ACS was an error-prone and time-consuming process.

Consistent use of the APM format and tools will go a long way toward solving the maintainability problems listed above. Moreover, APM is the -substrate that will enable us to soon establish a central package repository, -where both ArsDigita and third-party developers will be able publish their -packages for other ACS users to download and install.

For a simple illustration of the difference between ACS without APM +substrate that will enable us to establish a central package repository, +where developers will be able publish their +packages for other OpenACS users to download and install.

For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):

[D]

APM itself is part of a package, the OpenACS Kernel, an OpenACS +3.2 (say, bboard and e-commerce):

[D]

APM itself is part of a package, the OpenACS Kernel, an OpenACS service that is the only mandatory component of an OpenACS installation.

Competitive Analysis

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, @@ -540,4 +540,4 @@ all of this functionality in one interface and it can be confusing from a usability perspective.

Authors

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.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/25/2000	Bryan Quinn
0.8	Ready for QA	9/29/2000	Bryan Quinn
0.9	Edited for ACS 4 Beta release	10/02/2000	Kai Wu
1.0	Edited for OpenACS 5.0.0b1 Beta release	03/02/2002	Roberto Mello

Prev	Home	Next
OpenACS 5.0.0b1 Package Manager Requirements	Up	Database Access API

View comments on this page at openacs.org +Salz, Michael Yoon, and Lars Pind.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	9/25/2000	Bryan Quinn
0.8	Ready for QA	9/29/2000	Bryan Quinn
0.9	Edited for ACS 4 Beta release	10/02/2000	Kai Wu
1.0	Edited for OpenACS 4.5 Beta release	03/02/2002	Roberto Mello

Prev	Home	Next
Package Manager Requirements	Up	Database Access API

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 19 Nov 2003 15:44:49 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 11 Dec 2003 23:08:45 -0000 1.18 @@ -1,4 +1,4 @@ -OpenACS 5.0.0b1 Package Manager Requirements

Prev	Chapter�10.�Kernel Documentation	Next

OpenACS 5.0.0b1 Package Manager Requirements

By Bryan Quinn and Todd Nightingale

+Package Manager Requirements

Prev	Chapter�11.�Kernel Documentation	Next

Package Manager Requirements

By Bryan Quinn and Todd Nightingale

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

The following is a requirements document for the OpenACS Package Manager @@ -153,7 +153,7 @@ 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 +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 @@ -291,4 +291,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.

Revision History

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

Prev	Home	Next
OpenACS 4 Subsites Design Document	Up	OpenACS 5.0.0b1 Package Manager Design

View comments on this page at openacs.org +these features should be quite straightforward.

Revision History

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

Prev	Home	Next
Subsites Design Document	Up	Package Manager Design

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/backup-recovery.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.html,v diff -u -N -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/backup-recovery.html 19 Nov 2003 15:44:49 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 11 Dec 2003 23:08:45 -0000 1.17 @@ -7,267 +7,201 @@ recovery are always risky; here are some steps that minimize the chance recovery is necessary:

- Store everything on a fault-tolerant disk array (RAID 1 or 5 - or better). -
- Use battery backup. -
- Use more reliable hardware, such as SCSI instead of IDE. -

These steps improve the chances of successful recovery:

- Store backups on a third disk on another controller -
- Store backups on a different computer on a different network - in a different physical location. (Compared to off-line - backup such as tapes and CDRs, on-line backup is faster and - more likely to succeed, but requires maintenance of another machine.) -
- Plan and configure for recovery from the beginning. -
- Test your recovery strategy from time to time. -
- Make it easy to maintain and test your recovery strategy, so - that you are more likely to do it. -

- OpenACS installations comprise files and database contents. - If you follow the reference install and put all files, - including configuration files, in - /var/lib/aolserver/service0/, - and back up the database nightly to a file in - /var/lib/aolserver/service0/database-backup, - then you can apply standard file-based backup strategies to - /var/lib/aolserver/service0 -

Snapshot backup and recovery

This section describes how to make a one-time backup and - restore of the files and database. This is useful for rolling back to - known-good versions of a service, such as at initial - installation and just before an upgrade. First, you back up the - database to a file within the file tree. Then, you back up the - file tree. All of the information needed to rebuild the site, - including the AOLserver config files, is then in tree for - regular file system backup.

Back up the database to a file.�

Oracle.�
- - Download the backup script. Save the file export-oracle.txt as - /tmp/export-oracle.txt -
- - Login as root. The following commands will install the export script: -
```
-joeuser:~$ su -
-Password: ***********
-root:~# cp /tmp/export-oracle.txt /usr/sbin/export-oracle
-root:~# chmod 700 /usr/sbin/export-oracle
```
- - Setup the export directory; this is the directory where backups will - be stored. We recommend the directory - /ora8/m02/oracle-exports.
```
-root:~# mkdir /ora8/m02/oracle-exports
-root:~# chown oracle.dba /ora8/m02/oracle-exports
-root:~# chmod 770 /ora8/m02/oracle-exports
```
- - Now edit - /usr/sbin/export-oracle and - change the SERVICE_NAME and - DATABASE_PASSWORD fields to - their correct values. If you want to use a directory other than - /ora8/m02/oracle-exports, you - also need to change the - exportdir setting. -
  - Test the export procedure by running the command: -
```
-root:~# /usr/sbin/export-oracle
-mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory
+      Store everything on a fault-tolerant disk array (RAID 1 or 5
+      or better).
+      
```
- + Use battery backup. +
- + Use more reliable hardware, such as SCSI instead of IDE. +
These steps improve the chances of successful recovery:
- + Store backups on a third disk on another controller +
- + Store backups on a different computer on a different network + in a different physical location. (Compared to off-line + backup such as tapes and CDRs, on-line backup is faster and + more likely to succeed, but requires maintenance of another machine.) +
- + Plan and configure for recovery from the beginning. +
- + Test your recovery strategy from time to time. +
- + Make it easy to maintain and test your recovery strategy, so + that you are more likely to do it. +
+ OpenACS installations comprise files and database contents. + If you follow the reference install and put all files, + including configuration files, in + /var/lib/aolserver/service0/, + and back up the database nightly to a file in + /var/lib/aolserver/service0/database-backup, + then you can apply standard file-based backup strategies to + /var/lib/aolserver/service0 +

Manual backup and recovery

This section describes how to make a one-time backup and + restore of the files and database. This is useful for rolling back to + known-good versions of a service, such as at initial + installation and just before an upgrade. First, you back up the + database to a file within the file tree. Then, you back up the + file tree. All of the information needed to rebuild the site, + including the AOLserver config files, is then in tree for + regular file system backup.

Back up the database to a file.�

Oracle.�

+ Download the backup script. Save the file export-oracle.txt as + /tmp/export-oracle.txt +

+ Login as root. The following commands will install the export script: +

+                joeuser:~$ su -
+                Password: ***********
+                root:~# cp /tmp/export-oracle.txt /usr/sbin/export-oracle
+              root:~# chmod 700 /usr/sbin/export-oracle

+ Setup the export directory; this is the directory where backups will + be stored. We recommend the directory + /ora8/m02/oracle-exports.

+                root:~# mkdir /ora8/m02/oracle-exports
+                root:~# chown oracle.dba /ora8/m02/oracle-exports
+              root:~# chmod 770 /ora8/m02/oracle-exports

+ Now edit + /usr/sbin/export-oracle and + change the SERVICE_NAME and + DATABASE_PASSWORD fields to + their correct values. If you want to use a directory other than + /ora8/m02/oracle-exports, you + also need to change the + exportdir setting. +

+ Test the export procedure by running the command: +

+ root:~# /usr/sbin/export-oracle
+ mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory

-Export: Release 8.1.6.1.0 - Production on Sun Jun 11 18:07:45 2000
+ Export: Release 8.1.6.1.0 - Production on Sun Jun 11 18:07:45 2000

-Connected to: Oracle8i Enterprise Edition Release 8.1.6.1.0 - Production
-With the Partitioning option
-JServer Release 8.1.6.0.0 - Production
-Export done in US7ASCII character set and US7ASCII NCHAR character set
-. exporting pre-schema procedural objects and actions
-. exporting foreign function library names for user SERVICE_NAME
-. exporting object type definitions for user SERVICE_NAME
-About to export SERVICE_NAME's objects ...
-. exporting database links
-. exporting sequence numbers
-. exporting cluster definitions
-. about to export SERVICE_NAME's tables via Conventional Path ...
-. exporting synonyms
-. exporting views
-. exporting stored procedures
-. exporting operators
-. exporting referential integrity constraints
-. exporting triggers
-. exporting indextypes
-. exporting bitmap, functional and extensible indexes
-. exporting posttables actions
-. exporting snapshots
-. exporting snapshot logs
-. exporting job queues
-. exporting refresh groups and children
-. exporting dimensions
-. exporting post-schema procedural objects and actions
-. exporting statistics
-Export terminated successfully without warnings.

PostGreSQL.�Create a backup file and verify that it was created and has a reasonable size (several megabytes).

[root@localhost root]# su - service0
-[service0@localhost service0]$ pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp service0
-[service0@localhost service0]$ ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp 
--rw-rw-r-x    1 service0  service0   4005995 Feb 21 18:28 /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
-[service0@localhost service0]$ exit
-[root@localhost root]#
-su - service0
-pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp openacs-dev
-ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
-exit

Back up the file system.�Back up all of the files in the service, including the - database backup file but excluding the auto-generated - supervise directory, which is - unneccesary and has complicated permissions.
In the tar command,
- c create a - new tar archive
- p preserves permissions.
- s preserves file sort order
- j compresses the output with bz2.
- The --exclude clauses skips some daemontools files that - are owned by root and thus cannot be backed up by the - service owner. These files are autogenerated and we don't - break anything by omitting them.
- The --file clause - specifies the name of the output file to be generated; we - manually add the correct extensions.
- The last clause, - /var/lib/aolserver/service0/, - specifies the starting point for backup. Tar defaults to - recursive backup.
```
[root@yourserver root]# su - service0
-[service0@yourserver service0]$ tar -cpsj --exclude /var/lib/aolserver/service0/etc/daemontools/supervise --file /tmp/service0-backup.tar.bz2 /var/lib/aolserver/service0/ 
-tar: Removing leading `/' from member names
-[service0@yourserver service0]$
```

Suffer a catastrophic failure on your production system.�(We'll simulate this step)

[root@yourserver root]# svc -d /service/service0
-[root@yourserver root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost
-[root@yourserver root]# rm /service/service0
-rm: remove symbolic link `/service/service0'? y
-[root@yourserver root]# ps -auxw | grep service0
-root      1496  0.0  0.0  1312  252 ?        S    16:58   0:00 supervise service0
-[root@yourserver root]# kill 1496
-[root@yourserver root]# ps -auxw | grep service0
-[root@yourserver root]# su - postgres
-[postgres@yourserver pgsql]$ dropdb service0
-DROP DATABASE
-[postgres@yourserver pgsql]$ dropuser service0
-DROP USER
-[postgres@yourserver pgsql]$ exit
-logout
-[root@yourserver root]#

Recovery.�

Restore the operating system and required software. - You can do this with standard backup processes or by - keeping copies of the install material (OS CDs, OpenACS - tarball and supporting software) and repeating the install - guide. Recreate the service user (service0).

Restore the OpenACS files and database backup file.

[root@yourserver root]# su - service0
-[service0@yourserver service0]$ cd /var/lib/aolserver
-[service0@yourserver aolserver]$ tar xjf /tmp/service0-backup.tar.bz2
-[service0@yourserver aolserver]$ chmod -R 775 service0
-[service0@yourserver aolserver]$ chown -R service0.web service0
+                Connected to: Oracle8i Enterprise Edition Release 8.1.6.1.0 - Production
+                With the Partitioning option
+                JServer Release 8.1.6.0.0 - Production
+                Export done in US7ASCII character set and US7ASCII NCHAR character set
+                . exporting pre-schema procedural objects and actions
+                . exporting foreign function library names for user SERVICE_NAME 
+                . exporting object type definitions for user SERVICE_NAME 
+                About to export SERVICE_NAME's objects ...
+                . exporting database links
+                . exporting sequence numbers
+                . exporting cluster definitions
+                . about to export SERVICE_NAME's tables via Conventional Path ...
+                . exporting synonyms
+                . exporting views
+                . exporting stored procedures
+                . exporting operators
+                . exporting referential integrity constraints
+                . exporting triggers
+                . exporting indextypes
+                . exporting bitmap, functional and extensible indexes
+                . exporting posttables actions
+                . exporting snapshots
+                . exporting snapshot logs
+                . exporting job queues
+                . exporting refresh groups and children
+                . exporting dimensions
+                . exporting post-schema procedural objects and actions
+                . exporting statistics
+              Export terminated successfully without warnings.

PostgreSQL.�Create a backup file and verify that it was created and has a reasonable size (several megabytes).

[root@localhost root]# su - service0
+            [service0@localhost service0]$ pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp service0
+            [service0@localhost service0]$ ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp 
+            -rw-rw-r-x    1 service0  service0   4005995 Feb 21 18:28 /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
+            [service0@localhost service0]$ exit
+            [root@localhost root]#
+            su - service0
+            pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp openacs-dev
+            ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp
+            exit

Back up the file system.�Back up all of the files in the service, including the + database backup file but excluding the auto-generated + supervise directory, which is + unneccesary and has complicated permissions.
In the tar command,
- c create a + new tar archive
- p preserves permissions.
- s preserves file sort order
- j compresses the output with bz2.
- The --exclude clauses skips some daemontools files that + are owned by root and thus cannot be backed up by the + service owner. These files are autogenerated and we don't + break anything by omitting them.
- The --file clause + specifies the name of the output file to be generated; we + manually add the correct extensions.
- The last clause, + /var/lib/aolserver/service0/, + specifies the starting point for backup. Tar defaults to + recursive backup.
```
[root@yourserver root]# su - service0
+        [service0@yourserver service0]$ tar -cpsj --exclude /var/lib/aolserver/service0/etc/daemontools/supervise --file /tmp/service0-backup.tar.bz2 /var/lib/aolserver/service0/ 
+        tar: Removing leading `/' from member names
+        [service0@yourserver service0]$
```

Suffer a catastrophic failure on your production system.�(We'll simulate this step)

[root@yourserver root]# svc -d /service/service0
+        [root@yourserver root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost
+        [root@yourserver root]# rm /service/service0
+        rm: remove symbolic link `/service/service0'? y
+        [root@yourserver root]# ps -auxw | grep service0
+        root      1496  0.0  0.0  1312  252 ?        S    16:58   0:00 supervise service0
+        [root@yourserver root]# kill 1496
+        [root@yourserver root]# ps -auxw | grep service0
+        [root@yourserver root]# su - postgres
+        [postgres@yourserver pgsql]$ dropdb service0
+        DROP DATABASE
+        [postgres@yourserver pgsql]$ dropuser service0
+        DROP USER
+        [postgres@yourserver pgsql]$ exit
+        logout
+        [root@yourserver root]#

Recovery.�

Restore the operating system and required software. + You can do this with standard backup processes or by + keeping copies of the install material (OS CDs, OpenACS + tarball and supporting software) and repeating the install + guide. Recreate the service user (service0).

Restore the OpenACS files and database backup file.

[root@yourserver root]# su - service0
+            [service0@yourserver service0]$ cd /var/lib/aolserver
+            [service0@yourserver aolserver]$ tar xjf /tmp/service0-backup.tar.bz2
+            [service0@yourserver aolserver]$ chmod -R 775 service0
+            [service0@yourserver aolserver]$ chown -R service0.web service0
 
-

Restore the database

Oracle.�

Set up a clean Oracle database user and - tablespace (more information).

Invoke the import command

imp service0/service0 FILE=/var/lib/aolserver/service0/database-backup/nighty_backup.dmp

Postgres.�

Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. To compensate, we pre-creating some critical items first, which leads to some harmless errors.

[root@yourserver root]# su - postgres
-[postgres@yourserver pgsql]$ createuser service0
-Shall the new user be allowed to create databases? (y/n) y
-Shall the new user be allowed to create more new users? (y/n) y
-CREATE USER
-[service0@yourserver web]$ createdb service0
-CREATE DATABASE
-[service0@yourserver web]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
-(many lines omitted)
-[service0@yourserver web]$ psql service0 < /var/lib/aolserver/service0/database-backup/database-backup.dmp
-(many lines omitted)
-[service0@yourserver web]$ exit
-[postgres@yourserver pgsql]$ exit
-logout
-

Activate the service

[root@yourserver root]# ln -s /var/lib/aolserver/service0/etc/daemontools /service/service0
-[root@yourserver root]# sleep 10
-[root@yourserver root]# svgroup web /service/service0
-[root@yourserver root]#

Automated Backup (OPTIONAL)

Backup can encompass all files in - /var/lib/aolserver/service0. Use one cron job to back up the database to a file in - /var/lib/aolserver/service0/database-backup, and a second cron job to back up the entire file tree.

Postgres automatic backup

Backing up the database consists of creating a file - which is a picture of the database at a particular moment. - Postgres can be backed up while running.

Depending on your overall backup strategy, you can - create a series of database backup files (recommended for a development server where you are using the section called “Using CVS for backup-recovery”), or you can create a - single nightly backup file which is then collected into a - bigger backup file that includes the other parts of the - service. The latter technique is more generally recommended. To make a new file every - night, edit the crontab file for service0:

[service0@yourserver service0]$ export EDITOR=emacs;crontab -e

Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.

0 1 * * * /usr/local/pgsql/bin/pg_dump -f /var/lib/aolserver/service0/database-backup/service0_`date +\%Y-\%m-\%d`.dmp service0

If you plan to back up the whole /var/lib/aolserver/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time:

0 1 * * * /usr/local/pgsql/bin/pg_dump -f /var/lib/aolserver/service0/database-backup/service0_nightly.dmp service0

A full Backup/Recovery cycle

On a test service, make sure that your backup-recovery process work. After backing up the database and file system, delete the service as detailed below and then recover it.

Other Backup Strategies

Earlier strategies, included here because this section - hasn't been fully updated yet.

Set Up Nightly Oracle Exports

Edit the backup script to save the backup - file in /var/lib/aolserver/service0/database-backup. - While you're working with Oracle, you should configure it to do - automatic exports. An export is a separate backup copy of the - database. This copy includes all of the database's state at the - time that the export was initiated. If your database is corrupted, - you can restore from one of these backups. You should do this step as - root. -

- Automating backups is accomplished using the UNIX - crontab facility.

- While still root, run the - following command. You can replace the - EDITOR="emacs -nw" - portion with whatever editor your prefer, such as - EDITOR=vi. -

-root:~# export EDITOR="emacs -nw"
-root:~# crontab -e

Now add the following line on a line by itself

-0 23 * * * /usr/sbin/export-oracle

- Save the file, exit the editor. Verify that the addition - succeeded by checking the output of the following command.

-root:~# crontab -l | grep export-oracle
-0 23 * * * /usr/sbin/export-oracle
-root:~# exit
-; Logout

If you see the line, go ahead and log out.

Set up nightly Postgres exports

This is an alternate method to the crontabls - backup. - Dowload this script - to /tmp. At the top of the script - are several variables that you'll need to customize: -

- bak - location where you want - local backups to be saved -
- servername - name of your server - (and database instance) -
- ftp_user - username on your ftp - account -
- ftp_password - password on your - ftp account -
- ftp_dir - path on the remote - server where your backups will be uploaded -
- ftp_server - your ftp server -

- - Next, we'll save this file to our server's - tcl directory so that it will be - loaded on startup. It will automatically be run every night at - midnight. Note that this script only backs up the database - not the - OpenACS scripts and file content. -

-joeuser:~$ cp /tmp/acs-pgbackup-init.txt ~/var/lib/aolserver/birdnotes/tcl/acs-pgbackup-init.tcl
-joeuser:~$ restart-aolserver birdnotes

- That's it! The script will email you with each successful backup (or - if it fails, it will send you an email with the reason) -

Using CVS for backup-recovery

If you are already using CVS, you probably don't - need to do anything to back up your files. Just make - sure that your current work is checked into the system. - You can then roll back based on date - note the - current system time, down to the minute. For maximum - safety, you can apply a tag to your current - files. You will still need to back up your database.

Note that, if you did the CVS options in this document, the /var/lib/aolserver/service0/etc directory is not included in cvs and you may want to add it.

[root@localhost root]# su - service0
-[service0@localhost service0]$ cd /var/lib/aolserver/service0
-[service0@localhost service0]$ cvs commit -m "last-minute commits before upgrade to 4.6"
-cvs commit: Examining .
-cvs commit: Examining bin
-(many lines omitted)
-[service0@localhost service0]$ cvs tag before_upgrade_to_4_6
-cvs server: Tagging bin
-T bin/acs-4-0-publish.sh
-T bin/ad-context-server.pl
-(many lines omitted)
-[service0@localhost service0]$ exit
-[root@localhost root]# 
-su - service0
-cd /var/lib/aolserver/service0
-cvs commit -m "last-minute commits before upgrade to 4.6"
-cvs tag before_upgrade_to_4_6
-exit

To restore files from a cvs tag such as the one used above:

[root@localhost root]# su - service0
-[service0@localhost service0]$ cd /var/lib/aolserver/service0
-[service0@localhost service0]$ cvs up -r current
-[service0@localhost service0]$ exit
-su - service0
-cd /var/lib/aolserver/service0
-cvs up -r current

($Id$)

Bootstrapping OpenACS

By Jon Salz

+Bootstrapping OpenACS

Prev	Chapter�11.�Kernel Documentation	Next

Bootstrapping OpenACS

By Jon Salz

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl

This document describes the startup (bootstrapping) process for an AOLserver Index: openacs-4/packages/acs-core-docs/www/complete-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/complete-install.html,v diff -u -N -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/complete-install.html 19 Nov 2003 15:44:49 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/complete-install.html 11 Dec 2003 23:08:45 -0000 1.6 @@ -1 +1 @@ -Chapter�3.�Complete Installation

Prev	Part�II.�Administrator's Guide	Next

Chapter�3.�Complete Installation

Table of Contents

Install Unix-like system and supporting software
Install Oracle 8.1.7
Install PostGreSQL
Install AOLserver 3.3oacs1
Install OpenACS 5.0.0b1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X

Prev	Home	Next
Prerequisite Software	Up	Install Unix-like system and supporting software

View comments on this page at openacs.org +Chapter�3.�Complete Installation

Prev	Part�II.�Administrator's Guide	Next

Chapter�3.�Complete Installation

Table of Contents

Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 3.3oacs1
Install OpenACS 5.0.0b4
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X

Prev	Home	Next
Prerequisite Software	Up	Install a Unix-like system and supporting software

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/cvs-service-import.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/cvs-service-import.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/cvs-service-import.html 19 Nov 2003 15:44:49 -0000 1.14 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,50 +0,0 @@ -Add the Service to CVS - OPTIONAL

Prev	Appendix�D.�Using CVS with an OpenACS Site	Next

Add the Service to CVS - OPTIONAL

These steps take an existing OpenACS directory and add - it to a CVS - repository..

Create and set permissions on a subdirectory in the local cvs repository.

[root@yourserver root]# mkdir /cvsroot/service0
-[root@yourserver root]# chown service0.web /cvsroot/service0
-[root@yourserver root]#
-mkdir /cvsroot/service0
-chown service0.web /cvsroot/service0

Add the repository location to the user environment.

[root@yourserver root]# su - service0
-[service0@yourserver service0]$ emacs .bashrc

Put this string into /home/service0/.bashrc:

export CVSROOT=/cvsroot

[service0@yourserver service0]$ exit
-logout
-
-[root@yourserver root]#

Import all files into cvs. In order to work on - files with source control, the files must be checked out - from cvs. So we will import, move aside, and then check - out all of the files. In the cvs import command, - service0 - refers to the cvs repository to use; it uses the CVSROOT - plus this string, - i.e. - /cvsroot/service0. - "OpenACS" is the vendor tag, and "openacs-5-0-0b1" is the - release tag. These tags will be useful in upgrading and - branching. -m sets the version comment.

[root@yourserver root]# su - service0
-[service0@yourserver service0]$ cd /web/service0
-[service0@yourserver service0]$ cvs import -m "initial install" service0 OpenACS openacs-5-0-0b1
-N service0/license.txt
-N service0/readme.txt
-(many lines omitted)
-N service0/www/SYSTEM/flush-memoized-statement.tcl
-
-No conflicts created by this import
-
-[service0@yourserver service0]$
-su - service0
-cd /web/service0
-cvs import -m "initial install" service0 OpenACS openacs-5-0-0b1

Move the original directory to a temporary location, and check out the cvs repository in its place. If the service starts correctly, come back and remove the temporary copy of the uploaded files.

[service0@yourserver service0]$ cd ..
-[service0@yourserver web]$ mv service0 service0.orig
-[service0@yourserver web]$ cvs checkout service0
-cvs checkout: Updating service0
-U service0/license.txt
-(many lines omitted)
-U service0/www/SYSTEM/dbtest.tcl
-U service0/www/SYSTEM/flush-memoized-statement.tcl
-[service0@yourserver web]$ exit
-logout
-
-[root@yourserver web]#
-cd ..
-mv service0 service0.orig
-cvs checkout service0
-exit

Prev	Home	Next
Appendix�D.�Using CVS with an OpenACS Site	Up	Appendix�E.�How to package and release OpenACS

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/cvs-tips.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-tips.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/cvs-tips.html 19 Nov 2003 15:44:49 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/cvs-tips.html 11 Dec 2003 23:08:45 -0000 1.8 @@ -1,4 +1,55 @@ -Appendix�D.�Using CVS with an OpenACS Site

Prev	Part�III.�For OpenACS Package Developers	Next

Appendix�D.�Using CVS with an OpenACS Site

Table of Contents

Add the Service to CVS - OPTIONAL

By Joel Aufrecht

+Appendix�D.�Using CVS with an OpenACS Site

Prev	Part�III.�For OpenACS Package Developers	Next

Appendix�D.�Using CVS with an OpenACS Site

By Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Prev	Home	Next
PL/SQL Standards	Up	Add the Service to CVS - OPTIONAL

Add the Service to CVS - OPTIONAL.� + These steps take an existing OpenACS directory and add + it to a CVS + repository. +

Create and set permissions on a subdirectory in the local cvs repository.

[root@yourserver root]# mkdir /cvsroot/service0
+[root@yourserver root]# chown service0.web /cvsroot/service0
+[root@yourserver root]#
+mkdir /cvsroot/service0
+chown service0.web /cvsroot/service0

Add the repository location to the user environment.

[root@yourserver root]# su - service0
+[service0@yourserver service0]$ emacs .bashrc

Put this string into /home/service0/.bashrc:

export CVSROOT=/cvsroot

[service0@yourserver service0]$ exit
+logout
+
+[root@yourserver root]#

Import all files into cvs. In order to work on + files with source control, the files must be checked out + from cvs. So we will import, move aside, and then check + out all of the files. In the cvs import command, + service0 + refers to the cvs repository to use; it uses the CVSROOT + plus this string, + i.e. + /cvsroot/service0. + "OpenACS" is the vendor tag, and "openacs-5-0-0b4" is the + release tag. These tags will be useful in upgrading and + branching. -m sets the version comment.

[root@yourserver root]# su - service0
+[service0@yourserver service0]$ cd /web/service0
+[service0@yourserver service0]$ cvs import -m "initial install" service0 OpenACS openacs-5-0-0b4
+N service0/license.txt
+N service0/readme.txt
+(many lines omitted)
+N service0/www/SYSTEM/flush-memoized-statement.tcl
+
+No conflicts created by this import
+
+[service0@yourserver service0]$
+su - service0
+cd /web/service0
+cvs import -m "initial install" service0 OpenACS openacs-5-0-0b4

Move the original directory to a temporary location, and check out the cvs repository in its place. If the service starts correctly, come back and remove the temporary copy of the uploaded files.

[service0@yourserver service0]$ cd ..
+[service0@yourserver web]$ mv service0 service0.orig
+[service0@yourserver web]$ cvs checkout service0
+cvs checkout: Updating service0
+U service0/license.txt
+(many lines omitted)
+U service0/www/SYSTEM/dbtest.tcl
+U service0/www/SYSTEM/flush-memoized-statement.tcl
+[service0@yourserver web]$ exit
+logout
+
+[root@yourserver web]#
+cd ..
+mv service0 service0.orig
+cvs checkout service0
+exit

Prev	Home	Next
System/Application Requirements Template	Up	Appendix�E.�How to package and release OpenACS

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/database-management.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/database-management.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/database-management.html 19 Nov 2003 15:44:49 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/database-management.html 11 Dec 2003 23:08:45 -0000 1.16 @@ -1,7 +1,7 @@ Database Management

Prev	Chapter�6.�Maintenance	Next

Database Management

By Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Running a PostGreSQL database on another server

To run a database on a different machine than the +

Running a PostgreSQL database on another server

To run a database on a different machine than the webserver requires changes to the database configuration file and access control file, and to the OpenACS service's configuration file.

Edit the database configuration file, which in a Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 19 Nov 2003 15:44:50 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 11 Dec 2003 23:08:45 -0000 1.24 @@ -1,4 +1,4 @@ -Database Access API
Prev Chapter�10.�Kernel Documentation Next
Database Access API
By Jon Salz. Revised and expanded by Roberto Mello (rmello at fslc dot usu dot edu), July 2002.
+Database Access API
Prev Chapter�11.�Kernel Documentation Next
Database Access API
By Jon Salz. Revised and expanded by Roberto Mello (rmello at fslc dot usu dot edu), July 2002.
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Tcl procedures: /packages/acs-kernel/10-database-procs.tcl
Tcl initialization: /packages/acs-kernel/database-init.tcl
The Big Picture
@@ -727,4 +727,4 @@ The nsv containing the list is initialized by the bootstrap script and should never be referenced directly by user code. Returns the current rdbms type and version. -
($Id$)
Prev Home Next
OpenACS 5.0.0b1 Package Manager Design Up OpenACS Internationalization Requirements
docs@openacs.org
View comments on this page at openacs.org +
($Id$)

Prev	Home	Next
Package Manager Design	Up	OpenACS Internationalization Requirements

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/db-api.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/db-api.html 19 Nov 2003 15:44:50 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/db-api.html 11 Dec 2003 23:08:45 -0000 1.24 @@ -1,4 +1,4 @@ -The OpenACS Database Access API

Prev	Chapter�8.�Development Reference	Next

The OpenACS Database Access API

+The OpenACS Database Access API

Prev	Chapter�8.�Development Reference	Next

The OpenACS Database Access API

By Pete Su and Jon Salz. Modified by Roberto Mello.

Overview

One of OpenACS's great strengths is that code written for it is @@ -682,4 +682,4 @@

($Id$)

Prev	Home	Next
The Request Processor	Up	Using Templates in OpenACS 5.0.0b1

Prev	Home	Next
The Request Processor	Up	Using Templates in OpenACS

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/dev-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v diff -u -N -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/dev-guide.html 19 Nov 2003 15:44:50 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/dev-guide.html 11 Dec 2003 23:08:45 -0000 1.19 @@ -1 +1 @@ -Chapter�8.�Development Reference

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�8.�Development Reference

Table of Contents

OpenACS 5.0.0b1 Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS 5.0.0b1
Groups, Context, Permissions
Writing OpenACS 5.0.0b1 Application Pages
Parties in OpenACS 5.0.0b1
OpenACS 4.x Permissions Tediously Explained
Object Identity
Programming with AOLserver

Prev	Home	Next
Advanced Topics	Up	OpenACS 5.0.0b1 Packages

View comments on this page at openacs.org +Chapter�8.�Development Reference

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�8.�Development Reference

Table of Contents

OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
OpenACS Permissions Tediously Explained
Object Identity
Programming with AOLserver
Using HTML Forms

Prev	Home	Next
Advanced Topics	Up	OpenACS Packages

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -N -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 19 Nov 2003 15:44:50 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 11 Dec 2003 23:08:45 -0000 1.25 @@ -1,7 +1,7 @@ -OpenACS Documentation Guide

Prev	Chapter�9.�Engineering Standards	Next

OpenACS Documentation Guide

+OpenACS Documentation Guide

Prev	Chapter�10.�Documentation Standards	Next

OpenACS Documentation Guide

By Claus Rasmussen, with additions by Roberto Mello and the OpenACS Community -

Overview of OpenACS 5.0.0b1 Documentation

Overview of OpenACS Documentation

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 @@ -16,34 +16,38 @@ The documentation for OpenACS is written using DocBook XML. The reasons why we are using DocBook are explained in more details in the - Why DocBook? section. I will add the reasons why + next section. A few more reasons why we are using Docbook XML instead of Docbook SGML:

- Consistency. We already have a bunch of - .xml files that ArsDigita wrote. Trying to re-write them to + Consistency. We started with a collection + of DcoBook XML files that ArsDigita wrote. Trying to re-write them to conform to the SGML DTD would be unnecessary work (I tried).
It does not require extra effort. Writing in XML is almost identical to SGML, with a couple extra rules. More details in the LDP Author Guide. +
+ The tool chain has matured. xsltproc and other XML + based tools have improved to the point where they are about as good as + the SGML tools and generation of both html and pdf output is straighforward.

Why DocBook?

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.

Theoretically any strict DTD would have been sufficient - we could even write our own. But DocBook has been around - for a while (since early 90's), - it's well-tested, it's complete, it's extremely well-suited for technical documents + for a while (since the early 90's), + it's well-tested, it's complete, it's designed for technical documentation and best of all, it's open-source. A growing community surrounds DocBook (has - mailing lists) + mailing lists) and a number of free and commercial - tools are available + tools are available for editing and publishing DocBook documents.

This primer walks you through the basics, and should cover the @@ -53,7 +57,7 @@ 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: - +

Always close your tags with corresponding end-tags and to not use other tag minimization @@ -102,7 +106,7 @@ 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
@@ -126,101 +130,87 @@
       sources of these DocBook documents
       to get an idea of how they are tied together.
     
```

Headlines, Sections

- + Given that your job starts at the sect1-level, all your documents should open with a - <sect1>-tag and end + <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.

Right after the opening tag you put the title of the document - this is usually the same as xreflabel-attribute. E.g. the top level of the document you're reading right now looks like this:

-      <sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
-      <title>aD DocBook Primer</title>
+<sect1 id="docbook-primer" xreflabel="aD DocBook Primer">
+  <title>aD DocBook Primer</title>
 
-      ...
+...
 
-      </sect1>
-

- +</sect1> +

+ Inside this container your document will be split up into - <sect2>'s, + <sect2>'s, each with the same requirements - id and xreflabel attributes, and a <title>-tag inside. Actually, the xreflabel is never required in sections, but it makes linking to that section a lot easier.

When it comes to naming your sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.

Code

- + 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>. + <computeroutput>. This takes the place of the HTML-tag <code>

For bigger chunks of code such as SQL-blocks, the tag - <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of + <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.

Links

- + Linking falls into two different categories: inside the book you're making and outside:

1. Inside linking, cross-referencing other parts of your book

By having unique id's you can cross-reference any part of your book with a simple tag, regardless of where that part is. -

Check out how I link to a subsection of the Developer's Guide:

-
-	    Put this in your XML:
-
-	    - Find information about creating a package in
-	    <xref linkend="packages-making-a-package"></xref>.
-
-
-	    And the output is:
-
-	    - Find information about creating a package in 
-	    Making a Package
-
-

Check out how I link to a subsection of the Developer's Guide:

Put this in your XML:

+- Find information about creating a package in
+<xref linkend="packages-making-a-package"></xref>.
+

And the output is:

+- Find information about creating a package in 
+Making a Package.
+

Note that even though this is an empty tag, you have to either:

Provide the end-tag, </xref>, or
Put a slash before the ending-bracket: <xref linkend="blahblah"/>

If the section you link to hasn't a specified xreflabel-attribute, - the link is going to look like this:

-
-	    Put this in your XML:
-
-	    - Find information about what a package looks like in 
-	    <xref linkend="packages-looks"></xref>.
-
-
-	    And the output is:
-
-	    - Find information about what a package looks like in 
-	    the section called “What a Package Looks Like”
-
-

+ the link is going to look like this:

Put this in your XML:

+-Find information about what a package looks like in 
+<xref linkend="packages-looks"></xref>.
+

And the output is:

+- Find information about what a package looks like in 
+the section called “What a Package Looks Like”.
+

Note that since I haven't provided an xreflabel for the subsection, packages-looks, the parser will try its best to explain where the link takes you.

2. Linking outside the documentation

- + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different - (<ulink>): + (<ulink>):

<ulink url="http://www.oracle.com/">Oracle Corporation</ulink>

@@ -237,117 +227,117 @@ 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>, + <mediaobject>, + <imageobject>, and - <imagedata>. + <imagedata>. The news is that you have to provide two versions of all your graphics - one for the Web (probably a GIF or a JPEG) and one for print (EPS). Finally you should provide a brief description wrapped in - <textobject> - + <textobject> - in HTML this will be the ALT text.

-      <mediaobject>
-      <imageobject>
-      <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/>
-      </imageobject>
-      <imageobject>
-      <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/>
-      </imageobject>
-      <textobject>
-      <phrase>This is an image of the flow in the Request Processor</phrase>
-      </textobject>
-      </mediaobject>
-

+<mediaobject> + <imageobject> + <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/> + </imageobject> + <imageobject> + <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/> + </imageobject> + <textobject> + <phrase>This is an image of the flow in the Request Processor</phrase> + </textobject> +</mediaobject> +

Put your graphics in a separate directory ("images") and link to them only with relative paths.

Lists

- + Here's how you make the DocBook equivalent of the three usual HTML-lists:

1. How to make an <ul>

Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as <para>, and that the tags are called - <itemizedlist> + <itemizedlist> and - <listitem>: + <listitem>:

-	    <itemizedlist>
-	    
-	    <listitem><para>Stuff goes here</para></listitem>
-	    <listitem><para>More stuff goes here</para></listitem>
+<itemizedlist>
 
-	    </itemizedlist>
-

2. How to make an <ol>

+ <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> + +</itemizedlist> +

2. How to make an <ol>

The ordered list is like the preceding, except that you use - <orderedlist> instead:

-	    <orderedlist>
-	    
-	    <listitem><para>Stuff goes here</para></listitem>
-	    <listitem><para>More stuff goes here</para></listitem>
+	    <orderedlist> instead:
+<orderedlist>
 
-	    </orderedlist>
-

3. How to make a <dl>

+ <listitem><para>Stuff goes here</para></listitem> + <listitem><para>More stuff goes here</para></listitem> + +</orderedlist> +

3. How to make a <dl>

This kind of list is called a variablelist and these are the tags you'll need to make it happen: - <variablelist>, - <varlistentry>, - <term> and - <listitem>:

-	    <variablelist>
-	    
-	    <varlistentry>
-	    <term>Heading (<dt>) goes here</term>
-	    <listitem><para>And stuff (<dd>)goes here</para></listitem>
-	    </varlistentry>
+	    <variablelist>,
+	    <varlistentry>, 
+	    <term> and
+	    <listitem>:
+<variablelist>
 
-	    <varlistentry>
-	    <term>Another heading goes here</term>
-	    <listitem><para>And more stuff goes here</para></listitem>
-	    </varlistentry>
+  <varlistentry>
+    <term>Heading (<dt>) goes here</term>
+    <listitem><para>And stuff (<dd>)goes here</para></listitem>
+  </varlistentry>
 
-	    </variablelist>
-

Tables

- + <varlistentry> + <term>Another heading goes here</term> + <listitem><para>And more stuff goes here</para></listitem> + </varlistentry> + +</variablelist> +

Tables

+ DocBook supports several types of tables, but in most cases, the - <informaltable> + <informaltable> is enough:

-      <informaltable frame="all">
-      <tgroup cols="3">
-      <tbody>
+<informaltable frame="all">
+  <tgroup cols="3">
+    <tbody>
 
       <row>
-      <entry>a1</entry>
-      <entry>b1</entry>
-      <entry>c1</entry>
+        <entry>a1</entry>
+        <entry>b1</entry>
+        <entry>c1</entry>
       </row>
 
       <row>
-      <entry>a2</entry>
-      <entry>b2</entry>
-      <entry>c2</entry>
+        <entry>a2</entry>
+        <entry>b2</entry>
+        <entry>c2</entry>
       </row>
 
       <row>
-      <entry>a3</entry>
-      <entry>b3</entry>
-      <entry>c3</entry>
+        <entry>a3</entry>
+        <entry>b3</entry>
+        <entry>c3</entry>
       </row>
 
-      </tbody>
-      </tgroup>
-      </informaltable>
-

+ </tbody> + </tgroup> +</informaltable> +

With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: -

a1 b1 c1
a2 b2 c2
a3 b3 c3

a1	b1	c1
a2	b2	c2
a3	b3	c3

If you want cells to span more than one row or column, it gets a bit more complicated - check out - <table> + <table> for an example.

Emphasis

- + Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - - <emphasis>. + <emphasis>.

The <emphasis> tag defaults to italics when parsed. If you're looking for emphasizing with bold type, use <emphasis role="strong">. @@ -357,15 +347,14 @@ see show up in an index one day.

Use - <indexterm>, - <primary> and - <secondary> + <indexterm>, + <primary> and + <secondary> for this. See these links for an explanation.

Converting to HTML

Note

This section is quoted almost verbatim from the LDP Author Guide.

Once you have the Docbook Tools - installed, you can convert your xml documents to HTML (or other - formats. Let me know if you are able to convert to other - formats). + installed, you can convert your xml documents to HTML or other + formats.

With the DocBook XSL stylesheets, generation of multiple files is controlled by the stylesheet. If you want to generate a @@ -376,7 +365,7 @@ use the command:

 bash$  xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml
-

Note

This example uses Daniel Veillard's xsltproc command available as part of libxslt from http://www.xmlsoft.org/XSLT/. If you are using other XML processors such as Xalan or Saxon, @@ -387,7 +376,10 @@ following command:

 bash$  xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml
-

PL/SQL Standards

+PL/SQL Standards

Prev	Chapter�9.�Engineering Standards	Next

PL/SQL Standards

By Richard Li and Yon Feldman

OpenACS docs are written by the named authors, and may be edited @@ -151,4 +151,4 @@ as possible to all source code readers.

Lowercase everything, with the exception of %TYPE and %ROWTYPE. -

($Id$)

Prev	Home	Next
ACS File Naming and Formatting Standards	Up	Appendix�D.�Using CVS with an OpenACS Site

($Id$)

Prev	Home	Next
ACS File Naming and Formatting Standards	Up	Variables

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 19 Nov 2003 15:44:50 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 11 Dec 2003 23:08:46 -0000 1.24 @@ -1,4 +1,4 @@ -Release Version Numbering

Prev	Chapter�9.�Engineering Standards	Next

Release Version Numbering

By Ron Henderson

+Release Version Numbering

Prev	Chapter�9.�Engineering Standards	Next

Release Version Numbering

By Ron Henderson

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

@@ -90,4 +90,4 @@ detailed set of regression tests. For now we try to enforce this by restricting work on the release branch to fixing reported problem in the current release, e.g. no new features or big changes to -fundamental behavior.

($Id$)

Prev	Home	Next
System/Application Requirements Template	Up	Constraint naming standard

View comments on this page at openacs.org +fundamental behavior.

($Id$)

Prev	Home	Next
OpenACS Style Guide	Up	Constraint naming standard

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 19 Nov 2003 15:44:50 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 11 Dec 2003 23:08:46 -0000 1.16 @@ -1 +1 @@ -Chapter�9.�Engineering Standards

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�9.�Engineering Standards

Table of Contents

OpenACS Documentation Guide
Using PSGML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards

Prev	Home	Next
Programming with AOLserver	Up	OpenACS Documentation Guide

View comments on this page at openacs.org +Chapter�9.�Engineering Standards

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�9.�Engineering Standards

Table of Contents

OpenACS Style Guide
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing

Prev	Home	Next
Using HTML Forms	Up	OpenACS Style Guide

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ext-auth-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ext-auth-design.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/ext-auth-design.html 19 Nov 2003 15:44:50 -0000 1.1 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,1600 +0,0 @@ -External Authentication Design

Prev	Chapter�10.�Kernel Documentation	Next

External Authentication Design

EXT-AUTH-1: Authentication and Account Status API (4 hours) -

- by -

Current Design -

- Procedures to support this feature have already been written by - Lars. We are using the existing procedure ad_user_login and are - deprecating ad_maybe_redirect_for_registration and making it invoke - auth::require_login. -

Execution Story -

- The auth::authenticate procedure will be called by the login page - and the auth::require_login procedure at the beginning of any - application pages that require login. -

Tradeoffs: -

- For this feature reliability and testing are the prime concerns. -

External Design -

- The authtentication API has the following public methods: -

-ad_proc -public auth::require_login {} {
-    If the current session is not authenticated, redirect to the 
-    login page, and aborts the current page script.
-    Otherwise, returns the user_id of the user logged in.
-    Use this in a page script to ensure that only registered and authenticated 
-    users can execute the page, for example for posting to a forum.
-    @return user_id of user, if the user is logged in. Otherwise will issue an ad_script_abort.
-    @see ad_script_abort
-}
-
-

-ad_proc -public auth::authenticate {
-    {-authority_id ""}
-    {-username:required}
-    {-password:required}
-} {
-    Try to authenticate and login the user forever by validating the username/password combination, 
-    and return authentication and account status codes.    
-    
-    @param authority_id The ID of the authority to ask to verify the user. Defaults to local authority.
-    @param username Authority specific username of the user.
-    @param passowrd The password as the user entered it.
-    
-}
-
-

Testcases -

Procedure -auth::authenticate -

- Need to stub ns_sendmail? -

Test auth_status not "ok" for: -

Invalid password -
Invalid username -
Invalid authority -

Test account_status "closed" for -

Member state in banned, rejected, needs approval, and -deleted. -

Error handling (requires stubbing the Authenticate service -contract): -

The Authenticate service contract call hangs and we -should time out. Can we implement this in Tcl? -
The Authenticate call returns comm_error. -
The Authenticate call returns auth_error. -
The Authenticate service contract call does not return -the variables that it should -

Page Flow -

- None -

Data Model -

- None -

TODO -

Write test cases -
Deprecate ad_maybe_redirect_for_registration and make it -invoke auth::require_login -
New proc acs_user::get_by_username -

EXT-AUTH-3: Account Creation API (5 hours) -

EXT-AUTH-3: -Account Creation API (5 hours) -

- by -

Current API -

-ad_proc ad_user_new {email first_names last_name password password_question password_answer 
-                     {url ""} {email_verified_p "t"} {member_state "approved"} {user_id ""} } {
-    Creates a new user in the system.  The user_id can be specified as an argument to enable double click protection.
-    If this procedure succeeds, returns the new user_id.  Otherwise, returns 0.
-}
-
-

New API -

TODO: Make a auth::create_user return values from -auth::registration::Register. -

TODO: Make the auth::create_user proc honor site-wide setting -for which external authority to create account in. Holding off on -this feature for now. -

TODO: New procs: auth::registration::get_required_attributes -auth::registration::get_optional_attributes -

-ad_proc -public auth::create_user {
-    {-username:required}
-    {-password:required}
-    {-first_names ""}
-    {-last_name ""}
-    {-email ""}
-    {-url ""}
-    {-secret_question ""}
-    {-secret_answer ""}
-} {
-    @param authority_id The id of the authority to create the user in. Defaults to
-                        the authority with lowest sort_order that has register_p set to true.
-} {
-    set authorities_list [list]
-    
-    # Always register the user locally
-    lappend authorities_list [auth::authority::local]
-    # Default authority_id if none was provided
-    if { [empty_string_p $authority_id] } {
-        # Pick the first authority that can create users
-        set authority_id [db_string first_registering_authority {
-            select authority_id
-            from auth_authorities
-            where register_p = 't'
-            and sort_order = (select max(sort_order)
-                              from auth_authorities
-                              where register_p = 't'
-                             )
-        } -default ""]
-        if { [empty_string_p $authority_id] } {
-            error "No authority_id provided and could not find an authority that can create users"
-        }    
-        lappend authorities_list $authority_id
-    }    
-    # Register the user both with the local authority and the external one
-    db_transaction {
-        foreach authority_id $authorities_list {
-            auth::registration::Register \
-                -authority_id $authority_id \
-                -username $user_name \
-                -password $password \
-                -first_names $first_names \
-                -last_name $last_name \
-                -email $email \
-                -url $url \
-                -secret_question $secret_question \
-                -secret_answer $secret_answer
-        }
-    }
-}
-
-

-ad_proc -private auth::registration::Register {
-    {-authority_id:required}
-    {-username:required}
-    {-password:required}
-    {-first_names ""}
-    {-last_name ""}
-    {-email ""}
-    {-url ""}
-    {-secret_question ""}
-    {-secret_answer ""}
-} {
-    Invoke the Register service contract operation for the given authority.
-    @authority_id Id of the authority. Defaults to local authority.
-    @url Any URL (homepage) associated with the new user
-    @secret_question Question to ask on forgotten password
-    @secret_answer Answer to forgotten password question
-} {
-    if { [empty_string_p $authority_id] } {
-        set authority_id [auth::authority::local]
-    }
-    # TODO:
-    # Implement parameters
-    return [acs_sc::invoke \
-                -contract "auth_registration" \
-                -impl [auth::authority::get_element -authority_id $authority_id -element "auth_impl_name"] \
-                -operation Register \
-                -call_args [list [list] \
-                                 $username \
-                                 $authority_id \
-                                 $first_names \
-                                 $last_name \
-                                 $email \
-                                 $url \
-                                 $password \
-                                 $secret_question \
-                                 $secret_answer]]
-}
-
-

EXT-AUTH #4: Rewrite login & register pagse to use -APIs -

EXT-AUTH -#4: Rewrite login & register pages to use APIs -

Current Design -

Login is handled by acs-subsite/www/register/index.tcl and -user-login.tcl without use of an API. All the logic is in the -pages. -

Registration is handled by -acs-subsite/www/register/user-new.tcl. Again, all logic is in the -pages. -

External Design -

- We will have to rewrite the following pages: -

User login: /register/index -
User registration: /register/user-add -
Admin: /acs-admin/users/user-add, which includes user-new -(which can then be included on other pages as well) -
Bulk: /acs-admin/users/user-batch-add -

Authentication of users is handled by the -auth::authenticate - proc and registration by the -auth::local::register proc. -

The code to handle the login process in /register/index.tcl would -look like this:

-ad_form -name user_add -form {
-    {authority_id:integer(hidden)}
-    {username:text}
-    {email:text}
-    {password}
-} -on_submit {
-    if { [ad_parameter UsernameIsEmail] == 't' } {
-       set email $username
-    }
-    array set auth_info [auth::authenticate \
-        -authority_id $authority_id \
-        -username $username \
-        -password $password]
-   # Handle authentication problems
-   switch $auth_info(auth_status) {
-        ok {
-            # Continue below
-        }
-        bad_password {
-        }
-        no_account {
-        }
-        auth_error {
-        }
-        default {
-        }
-   }
-   # TODO: form builder validation of auth_status
-   # Handle account status
-   switch $auth_info(account_status) {
-       ok {
-           # Continue below
-       }
-       default {
-       }
-   }
-   # TODO: form builder validation of account_status
-   # We're logged in
-   ad_returnrediredt $return_url
-   ad_script_abort
-}
-

The code to handle the registration process is in -user-new.tcl would look like this: -

-array set registratoin_info [auth::register \
-    -authority_id $authority_id \
-    -username $username \
-    -password $password \
-    -first_names $first_names \
-    -last_name $last_name \
-    -email $email \
-    -url $url \
-    -secret_question $secret_question \
-    -secret_answer $secret_answer]
-# Handle registration problems
-switch $registratoin_info(reg_status) {
-    ok {
-        # Continue below
-    }
-    default {
-    }
-}
-# User is registered and logged in
-ad_returnrediredt $return_url
-

Page Flow -

- User is redirected to /register/index.tcl if login is required - (i.e. auth::require is specified) and the login is taken care of by - user-login.tcl. If user not registered (i.e. - $auth_info(account_status) == "no_account" -), - user is redirected to user-register.tcl. -

Error Handling -

-`auth::authenticate -` -

- Returns the array element auth_status, which can either be: -

ok: login was successful, continue -
bad_password: Username is correct, password is wrong, -redirect to bad-password, display auth_message -
no_account: Username not found, redirect to user-new, -display auth_message -
auth_error: Authentication failed, display auth_message, -display auth_message -
failed_to_connect: The driver didn't return anything -meaningful, display error message -

Also account_status is returned, which can either be:

ok: login was successful, continue -
closed,permanently: account permanently closed, redirect -to account_closed, display error message -
No match: account_status doesn't match any of the above, -display error message -

-`auth::register -` -

- Returns the array element reg_status, which can either be: -

ok: Registration was successful, continue -
failed: Registration failed, display -reg_message -
No match: reg_status doesn't match any of the above, -display error message -

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT-AUTH #5: -Password Management API -

Current Design -

proc "ad_change_password" updates a user's password. -

Other password update/retrieval/reset functionality is -hard-coded in the pages. -

TODO -

Decide on generic "failed-to-connect" and "connected, but -auth server returned unknown error". -
Test cases -

Execution Story

User login scenario:

The login page will have a link to assistance with -forgotten passwords ("Forgot your password?"). The URL of that link -is determined as follows:
1. auth_authority.forgotten_pwd_url -
2. Otherwise, if the authority's pwd mgmt driver's -CanRetrievePassword or CanRetrievePassword returns "Yes", we offer -a link to the OpenACS forgotten-password page, query vars -authority_id, maybe username. -
3. Otherwise, no forgotten password link. -
4. The OpenACS forgotten-password page may require the user -to fill in question/answer fields. These will be the OpenACS -question/answers only, we do not support question/answers from -external authentication servers. -
5. The email is reset or retrieved. The new password will be -emailed to the user, either by the driver or by the authentication -API (i.e., from one or the other side of the service -contract). -
6. User changes password scenario:
  1. User visits "My Account" -
  2. "My Account" will provide a link to changing the user's -password as follows:
    If the authority has a 'change_pwd_url' defined, we'll -offer a "Change my password" link that goes there. -
    Otherwise, if the authority driver's CanChangePassword -returns "Yes", we'll offer a "Change my password" link that goes to -the normal OpenACS change password page. -
    Otherwise, no "Change my password" link. -
    The change password page will call the Password -Management API to change the password. -

External Design -

-ad_proc -public auth::password::get_change_url {
-    {-user_id:required}
-} {
-    Returns the URL to redirect to for changing passwords. If the
-    user's authority has a "change_pwd_url" set, it'll return that,
-    otherwise it'll return a link to /user/password-update under the
-    nearest subsite.
-    @param user_id The ID of the user whose password you want to change.
-    @return A URL that can be linked to for changing password.
-} -
-ad_proc -public auth::password::can_change_p {
-    {-user_id:required}
-} {
-    Returns whether the given user change password. 
-    This depends on the user's authority and the configuration of that authority. 
-    
-    @param user_id The ID of the user whose password you want to change.
-    @return 1 if the user can change password, 0 otherwise.
-} {
-    # Implementation note:
-    # Calls auth::password::CanChangePassword(authority_id) for the user's authority.
-}
-ad_proc -public auth::password::change {
-    {-user_id:required}
-    {-old_password:required}
-    {-new_password:required}
-} {
-    Change the user's password.
-    @param user_id      The ID of the user whose password you want to change.
-    @param old_password The current password of that user. This is required for security purposes.
-    
-    @param new_password The desired new password of the user.
-    @return An array list with the following entries:
-    <ul>
-       <li> password_status: "ok", "no_account", "old_password_bad",
-       "new_password_bad", "error" </li>
-       <li> password_message: A human-readable description of what
-       went wrong. </li>
-    </ul>
-} {
-    # Implementation note
-    # Calls auth::password::ChangePassword(authority_id, username, old_password, new_password) for the user's authority.
-}
-ad_proc -public auth::password::get_forgotten_url {
-    {-authority_id:required}
-} { 
-    Returns the URL to redirect to for forgotten passwords. If the
-    user's authority has a "forgotten_pwd_url" set, it'll return that,
-    otherwise it'll return a link to /register/email-password under the
-    nearest subsite.
-        
-    @param authority_id The ID of the authority that the user is trying to log into.
-    @return A URL that can be linked to when the user has forgotten his/her password.
-} -
-ad_proc -public auth::password::can_retrieve_p {
-    {-authority_id:required}
-} {
-    Returns whether the given authority can retrive forgotten passwords. 
-    
-    @param authority_id The ID of the authority that the user is trying to log into.
-    @return 1 if the authority allows retrieving passwords, 0 otherwise.
-} {
-    # Implementation note
-    # Calls auth::password::CanRetrievePassword(authority_id) for the user's authority.
-}
-ad_proc -public auth::password::retrieve {
-    {-user_id:required}
-} {
-    Retrieve the user's password.
-    @param user_id      The ID of the user whose password you want to retrieve.
-    @return An array list with the following entries:
-    <ul>
-       <li> password_status: "ok", "no_account", "not_implemented",
-       "error" </li>
-       <li> password_message: A human-readable description of what
-       went wrong, if password_status is not "ok".  Not set if
-       password_status is "ok". </li>
-       <li> password: The retrieved password. </li>
-    </ul>
-} {
-    # Implementation note
-    # Calls auth::password::RetrievePassword(authority_id, username) for the user's authority.
-}
-ad_proc -public auth::password::can_reset_p {
-    {-authority_id:required}
-} {
-    Returns whether the given authority can reset forgotten passwords. 
-    
-    @param authority_id The ID of the authority that the user is trying to log into.
-    @return 1 if the authority allows resetting passwords, 0 otherwise.
-} {
-    # Implementation note
-    # Calls auth::password::CanResetPassword(authority_id) for the user's authority.
-}
-ad_proc -public auth::password::reset {
-    {-user_id:required}
-} {
-    Reset the user's password, which means setting it to a new
-    randomly generated password and informing the user of that new
-    password.
-    @param user_id      The ID of the user whose password you want to reset.
-    @return An array list with the following entries:
-    <ul>
-       <li> password_status: "ok", "no_account", "not_implemented",
-       "error" </li>
-       <li> password_message: A human-readable description of what
-       went wrong, if password_status is not "ok".  Not set if
-       password_status is "ok". </li>
-       <li> password: The new, automatically generated password. If no
-       password is included in the return array, that means the new
-       password has already been sent to the user somehow. If it is
-       returned, it means that caller is responsible for informing the
-       user of his/her new password.</li>
-    </ul>
-} { 
-    # Implementation note
-    # Calls auth::password::ResetPassword(authority_id, username) for the user's authority.
-}
-

Implementation -Details -

Create auth::password::CanChangePassword and friends wrappers -that take authority_id plus specific parameters for the service -contract call, finds the relevant service contract implementation, -and calls that. -

Error Handling -

Error codes are defined in the API stubs above. -

This API should check for bad return codes, drivers throwing -Tcl errors, and timeout, and replace with "failed-to-connect" -error. -

Time Tracking -

Design: 2 hours -
Estimated hours remaining: 4 hours -

Already done by Lars. We should ocument which messages can/should - be HTML and which should be plain text and in general try to - document expected values of return variables more clearly. - by

EXT-AUTH -#8: Automating Batch Synchronization -

Execution Story -

User goes to Administration. -
Visits site-wide admin pages. -
Link says "Authentication Management". -
The link goes to a list of known domains. -
For each domain, a page: -
-
- Local Authority Administration ... other stuff ... -Enable/Disable nightly batch Status of last run B: history of -previous runs (30 days?) -
-

Tradeoffs -

Which one or two of the following are emphasised in this -design? -

Performance: availability and efficiency -
Reliability and robustness -

External Design -

Administration -

-auth::authority::enable_batch_sync -authority_id -integer -. This API toggles the value of -batch_sync_enabled_p column in ?some_table?. Returns 1 or 0. -

Scheduled proc -

auth::batch_sync_sweeper -. Runs every night. Runs - through all enabled and batch-enabled authorities and calls - auth::authority::batch_sync -authority_id -integer -. -

Internal -Design -

- Administration -

-ad_proc -public auth::authority::enable_batch_sync {
-  -authority_id
-} {
- db_dml toggle_enbaled_p { 
-     update some_table
-     set    batch_sync_enabled_p = 't'
-     where  authority_id = :authority_id
-   }
-}
-

Scheduled proc:

-ad_proc -public auth::batch_sync_sweeper {} {
-   db_foreach select_authorities {
-      select authority_id
-      from   auth_authorities
-      where  active_p = 't'
-      and    batch_sync_enabled_p = 't'
-   } {
-      auth::authority::batch_sync -authority_id $authority_id
-   }
-}
-ad_proc -public auth::authority::batch_sync {
-   -authority_id
-} {
-   set driver [auth::get_driver -authority $authority]
-   acs_sc::invoke $driver Synchronize -authority $authority
-}
-

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT-AUTH -#9: Create Authentication drivers for Local Authority -

External Design -

auth::authenticate - calls - auth::authentication::Authenticate - which invokes - the service contract implementation for the authority. Returns: -

auth_status: "ok", "bad_password", "no_account", -"auth_error", "failed_to_connect" -
auth_message: Message to the user. -
account_status: "ok", "closed" -
account_message: Message to the user. -
account_status and account_message are only set if -auth_status is "ok". -

Internal Design -

-ad_proc -private auth::authentication::Authenticate {
-    {-authority_id ""}
-    {-username:required}
-    {-password:required}
-} {
-    Invoke the Authenticate service contract operation for the given authority.
-    @param username Username of the user.
-    @param password The password as the user entered it.
-    
-    @param authority_id The ID of the authority to ask to verify the user. Leave blank for local authority.
-} {
-    if { [empty_string_p $authority_id] } {
-        set authority_id [auth::authority::local]
-    }
-    # TODO:
-    # Implement parameters
-    return [acs_sc::invoke \
-                -contract "auth_authentication" \
-                -impl [auth::authority::get_element -authority_id $authority_id -element "auth_impl_name"] \
-                -operation Authenticate \
-                -call_args [list $username $password [list]]]
-}
-
-

-ad_proc -private auth::local::authentication::Authenticate {
-    username
-    password
-    {parameters {}}
-} {
-    Implements the Authenticate operation of the auth_authentication 
-    service contract for the local account implementation.
-} {
-    array set auth_info [list]
-    # TODO: username = email parameter ...
-    set username [string tolower $username]
-    
-    set authority_id [auth::authority::local]
-    set account_exists_p [db_0or1row select_user_info {
-        select user_id
-        from   cc_users
-        where  username = :username
-        and    authority_id = :authority_id
-    }] 
-    
-    if { !$account_exists_p } {
-        set auth_info(auth_status) "no_account"
-        return [array get auth_info]
-    }
-    
-    if { [ad_check_password $user_id $password] } {
-        set auth_info(auth_status) "ok"
-    } else {
-       if { [ad_parameter EmailForgottenPasswordP] == 't' } {
-            set auth_info(auth_status) "bad_password"
-            ... display link...
-       } else {
-            set auth_info(auth_status) "bad_password"
-       } 
-        return [array get auth_info]
-    }
-    # We set 'external' account status to 'ok', because the 
-    # local account status will be checked anyways
-    set auth_info(account_status) ok
-    return [array get auth_info]
-}
-

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT-AUTH -#10: Create Account Creation drivers for Local Authority -

External Design -

auth::registration::Register - returns: -

creation_status -
creation_message -
element_messages -
account_status -
account_message -

Internal Design -

-ad_proc -private auth::registration::Register {
-    {-authority_id:required}
-    {-username:required}
-    {-password:required}
-    {-first_names ""}
-    {-last_name ""}
-    {-email ""}
-    {-url ""}
-    {-secret_question ""}
-    {-secret_answer ""}
-    {-parameters ""}
-} {
-    Invoke the Register service contract operation for the given authority.
-    
-} {
-    if { [empty_string_p $authority_id] } {
-        set authority_id [auth::authority::local]
-    }
-
-    return [acs_sc::invoke \
-                -contract "auth_registration" \
-                -impl ??? \
-                -operation Register \
-                -call_args [list ???]]
-}
-

-ad_proc -private auth::local::registration::Register {
-    parameters
-    username
-    authority_id
-    first_names
-    last_name
-    email
-    url
-    password
-    secret_question
-    secret_answer
-} {
-    Implements the Register operation of the auth_register
-    service contract for the local account implementation.
-} {
-    array set result {
-        creation_status "reg_error"
-        creation_message {}
-        element_messages {}
-        account_status "ok"
-        account_message {}
-    }
-    # TODO: email = username
-    # TODO: Add catch
-    set user_id [ad_user_new \
-                     $email \
-                     $first_names \
-                     $last_name \
-                     $password \
-                     $question \
-                     $answer \
-                     $url \
-                     $email_verified_p \
-                     $member_state \
-                     "" \
-                     $username \
-                     $authority_id]
-    if { !$user_id } {
-        set result(creation_status) "fail"
-        set result(creation_message) "We experienced an error while trying to register an account for you."
-        return [array get result]
-    }
-    
-    # Creation succeeded
-    set result(creation_status) "ok"
-    # TODO: validate data (see user-new-2.tcl)
-    # TODO: double-click protection
-    # Get whether they requre some sort of approval
-    if { [parameter::get -parameter RegistrationRequiresApprovalP -default 0] } {
-        set member_state "needs approval"
-        set result(account_status) "closed"
-        set result(account_message) [_ acs-subsite.lt_Your_registration_is_]
-    } else {
-        set member_state "approved"
-    }
-    set notification_address [parameter::get -parameter NewRegistrationEmailAddress -default [ad_system_owner]]
-    if { [parameter::get -parameter RegistrationRequiresEmailVerificationP -default 0] } {
-        set email_verified_p "f"
-        set result(account_status) "closed"
-        set result(account_message) "[_ acs-subsite.lt_Registration_informat_1][_ acs-subsite.lt_Please_read_and_follo]"
-        set row_id [db_string rowid_for_email {
-            select rowid from users where user_id = :user_id
-        }]
-        # Send email verification email to user
-        set confirmation_url "[ad_url]/register/email-confirm?[export_vars { row_id }]"
-        with_catch errmsg {
-            ns_sendmail \
-                $email \
-                $notification_address \
-                "[_ acs-subsite.lt_Welcome_to_system_nam]" \
-                "[_ acs-subsite.lt_To_confirm_your_regis]"
-        } {
-            ns_returnerror "500" "$errmsg"
-            ns_log Warning "Error sending email verification email to $email. Error: $errmsg"
-        }
-    } else {
-        set email_verified_p "t"
-    }
-    # Send password/confirmail email to user
-    if { [parameter::get -parameter RegistrationProvidesRandomPasswordP -default 0] || \
-             [parameter::get -parameter EmailRegistrationConfirmationToUserP -default 0] } {
-        with_catch errmsg {
-            ns_sendmail \
-                $email \
-                $notification_address \
-                "[_ acs-subsite.lt_Welcome_to_system_nam]" \
-                "[_ acs-subsite.lt_Thank_you_for_visitin]"
-        } {
-            ns_returnerror "500" "$errmsg"
-            ns_log Warning "Error sending registration confirmation to $email. Error: $errmsg"
-        }
-    }
-    # Notify admin on new registration
-    if {[ad_parameter NotifyAdminOfNewRegistrationsP "security" 0]} {
-        with_catch errmsg {
-            ns_sendmail \
-                $notification_address \
-                $email \
-                "[_ acs-subsite.lt_New_registration_at_s]" \
-                "[_ acs-subsite.lt_first_names_last_name]"
-        } {
-            ns_returnerror "500" "$errmsg"
-            ns_log Warning "Error sending admin notification to $notification_address. Error: $errmsg"
-        }
-    }
-
-    return [array get result]
-}
-

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT AUTH #11: Create Auth driver for PAM -

Execution Story -

When a user authenticates against an authority which uses -PAM, the PAM authentication driver will be invoked. -

Tradeoffs -

Reliability, robustness, portability. -

External Design -

Will implement the authentication service contract. -

Parameters: Don't know. -

Internal Design -

Mat Kovach will implement a thread-safe ns_pam AOLserver -module in C, which will provide a Tcl interface to PAM. -

We'll write the service contract implementation in Tcl as a -wrapper for the ns_pam calls. -

Test Cases -

Set up authentication against /etc/passwd on cph02 and test -that we can log in with our cph02 usernames and passwords. -

Using PAM driver without having the ns_pam C module -loaded. -

Error Handling -

Need to catch timeouts and communications errors and pass -them on to the caller. -

Estimate -

Mat says: 20 hours x USD 50/hr = USD 1,000. We need to sort -out with Mat what happens if it takes him longer (or -shorter). -

Adding the service contract wrappers for authentication and -password management: 8 hours. -

EXT -AUTH #14: Create authentication driver for LDAP -

Status -

ON HOLD awaiting info from clients on whether we can use PAM -instead of talking directly to the LDAP server, or how we should -implement this. -

Execution Story -

When a user authenticates against an authority which uses -LDAP, the LDAP authentication driver will be invoked. -

Tradeoffs -

Reliability, robustness, portability. -

External Design -

Will implement the authentication service contract. -

Parameters: Don't know. -

Internal Design -

We'd look at the extisting ns_ldap module, or we'd find -someone to implement a new thread-safe ns_ldap AOLserver module in -C, which will provide a Tcl interface to the parts of LDAP which we -need. -

We'll write the service contract implementation in Tcl as a -wrapper for the ns_ldap calls. -

Test Cases -

Set up an LDAP server, and configure authentication against -that. -

Using LDAP driver without having the ns_ldap C module -loaded. -

Error Handling -

Need to catch timeouts and communications errors and pass -them on to the caller. -

Estimate -

Implementing ns_ldap: unknown. -

Adding the service contract wrappers for authentication and -password management: 8 hours. -

EXT-AUTH-16: -Authentication Service Contract (1 hour) -

- by -

EXT-AUTH-17: -Account Creation Service Contract (1 hour) -

- by -

EXT-AUTH-18: -Authority Configuration Data Model (2 hours) -

- by -

TODO: new column: help_contact_text with contact information -(phone, email, etc.) to be displayed as a last resort when people -are having problems with an authority. -

-create table auth_authorities (
-    authority_id             integer
-                             constraint auth_authorities_pk
-                             primary key,
-    short_name               varchar2(255)
-                             constraint auth_authority_short_name_un
-                             unique,
-    pretty_name              varchar2(4000),
-    active_p                 char(1) default 't' 
-                             constraint auth_authority_active_p_nn
-                             not null 
-                             constraint auth_authority_active_p_ck
-                             check (active_p in ('t','f')),
-    sort_order               integer not null,
-    -- authentication
-    auth_impl_id             integer
-                             constraint auth_authority_auth_impl_fk
-                             references acs_sc_impls(impl_id),
-    auth_p                   char(1) default 't'
-                             constraint auth_authority_auth_p_ck
-                             check (auth_p in ('t','f'))
-                             constraint auth_authority_auth_p_nn
-                             not null,
-    -- password management
-    pwd_impl_id              integer
-                             constraint auth_authority_pwd_impl_fk
-                             references acs_sc_impls(impl_id),
-    -- Any username in this url must be on the syntax username={username}
-    -- and {username} will be replaced with the real username
-    forgotten_pwd_url        varchar2(4000),
-    change_pwd_url           varchar2(4000),
-    -- registration
-    register_impl_id         integer
-                             constraint auth_authority_reg_impl_fk
-                             references acs_sc_impls(impl_id),
-    register_p               char(1) default 't'
-                             constraint auth_authority_register_p_ck
-                             check (register_p in ('t','f'))
-                             constraint auth_authority_register_p_nn
-                             not null,
-    register_url             varchar2(4000)
-);
-
-

EXT-AUTH -#19: Rewrite password recovery to use API -

Current Design -

- Password recovery is currently handled by - /register/email-password.tcl, email-password-2.tcl and - email-password-3.tcl. All logic is placed in the pages. -

Execution Story -

User is prompted for login, but types in a bad -password. -
The CanRetrievePassword service contract is called if -retrieving passwords is allowed user is redirected to -bad-password.tcl -
Here the RetrievePassword service contract is called, -which returns successful_p, password, message -
If password is empty and successful_p is true, the -authority server has send out the verification email. -
If successful and password is not empty, we email the -user and ask for verification. -

External Design -

-auth::password::CanResetPassword -.Input: -driver Output: 1 or 0 -

-auth::password::ResetPassword -.Input: -username, parameters.Output: successful_p: boolean, password (or -blank, if the server sends the user its new password directly), -message: To be relayed to the user. -

-auth::password::CanRetrievePassword -.Input: -driver Output: 1 or 0 -

-auth::password::RetrievePassword -.Input: -usernameOutput: retrievable_p: boolean, message: Instruct the user -what to do if not. -

-auth::password::CanChangePassword -Input: -driverOutput:True or false. -

-auth::password::ChangePassword -Input: -username, old_password, new_passwordOutput: new_password -

- The logic of bad-password will be moved into /register/index as - part of ad_form, but the logic should look like something along the - lines of: -

-set user_id [ad_conn]
-set authority_id [auth::authority -user_id $user_id]
-set driver [auth::get_driver -authority $authority]
-set retrieve_password_p [auth::password::CanRetrievePassword -driver $driver]
-set reset_password_p [auth::password::CanResetPassword -driver $driver]
-

- If $retrieve_password_p and $reset_password_p is true, this text - will be displayed: -

"If you've forgotten your password, you can -ask this server to -reset your password and email a new randomly generated password to -you -." -

- And email-password, should look something like this: -

-# Fetch the username. What proc should we use?
-set username [auth::username]
-# Reset password
-auth::password::ResetPassword -username $username
-set subject "[_ acs-subsite.lt_Your_forgotten_passwo]"
-# SIMON: how does the password get inserted here?
-# Should make use of auth::password::RetrievePassword
-set body "[_ acs-subsite.lt_Please_follow_the_fol]"
-# Send email
-if [catch {ns_sendmail $email $system_owner $subject $body} errmsg] {
-    ad_return_error \
-        "[_ acs-subsite.Error_sending_mail]" \
-        "[_ acs-subsite.lt_Now_were_really_in_tr]
-<blockquote>
-  <pre>
-    $errmsg
-  </pre>
-</blockquote>
-[_ acs-subsite.lt_when_trying_to_send_y]
-<blockquote>
-  <pre>
-[_ acs-subsite.Subject] $subject
-$body
-  </pre>
-</blockquote>
-"
-    return
-}
-

- We'll want to add a check for CanChangePassword in /pvt/home. -

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT AUTH -#20: Login pages over HTTPS -

Current Design -

Current login pages are over HTTP. Just bashing them to be -HTTPS has these issues: -

Browsers will not send cookies over HTTP that were -received over HTTPS. -
If images on the login page are over HTTP and not HTTPS, -browsers will warn that you're seeing unsecure items as part of a -secure web page, which is annoying and unprofessional. -
Browsers may also give a warning when redirecting back to -the normal pages not over HTTPS. -

Execution Story -

Beginning with a human being using a computer, describe how -the feature is triggered and what it does. As this story becomes -more detailed, move pieces to appropriate parts of the -document. -

Tradeoffs -

Security, Reliability and robustness. -

External Design -

Parameters: -

acs-kernel.RegisterRestrictToSSLFilters: If set to 0, we -don't restrict any URLs to HTTPs. -
acs-subsite.RestrictToSSL: A Tcl list of URL patterns -under the given subsite to restrict to SSL, e.g. "admin/* -register/*". Currently defaults to "admin/*". Only takes effect if -SSL is installed, and acs-kernel.RegisterRestrictToSSLFilters is -set to 1. -

To do -

Install SSL on a development server and integration -server. -
Try setting RestrictToSSL to "admin/* register/*" and -test what happens. -
Identify and fix issues that show up. -

Time Estimate -

Original estimate: 8 hours. -

Hours spent: 0.25 -

Estimated hours remaining: -

Risk: -

EXT-AUTH -#24: Email on password change -

Execution story -

- User: -

User visits /pvt/home -
Clicks "Change my Password" -
Enters password -
User is redirected to /pvt/home -
Email goes out -

- Admin: -

()

Internal Design -

- We'll first want to check whether changing the password is allowed: - -

-set user_id [ad_conn user_id]
-set authority [auth::authority -user_id $user_id]
-set driver [auth::get_driver -authority $authority]
-set change_password_p [auth::password::CanChangePassword -driver $driver]
-

- If $change_password_p is true, we'll display the "Change my - password" link on /pvt/home. update-password would look something - like this: -

-if {![db_0or1row select_email {}]} {
-    db_release_unused_handles
-    ad_return_error "[_ acs-subsite.lt_Couldnt_find_user_use]" "[_ acs-subsite.lt_Couldnt_find_user_use_1]"
-    return
-}
-set system_owner [ad_system_owner]
-set subject "some other i18n key msg"
-set body "some other i18n key msg"
-# Send email
-if [catch {ns_sendmail $email $system_owner $subject $body} errmsg] {
-    ad_return_error \
-        "[_ acs-subsite.Error_sending_mail]" \
-        "[_ acs-subsite.lt_Now_were_really_in_tr]
-<blockquote>
-  <pre>
-    $errmsg
-  </pre>
-</blockquote>
-[_ acs-subsite.lt_when_trying_to_send_y]
-<blockquote>
-  <pre>
-[_ acs-subsite.Subject] $subject
-$body
-  </pre>
-</blockquote>
-"
-    return
-}
-

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT AUTH #25: -Password Policy -

Current Design -

This has already been implemented on oacs-4-6 branch. -

Expiration of passwords: Password must be changed after a -certain number of days. No password history, though. -
Approval expiration: If a user is approved but doesn't -log on before a certain number of days, his approval will -expire. -

To do -

Merge changes from oacs-4-6 onto HEAD. (Commits made -around June 6). -
Sort out the upgrade script sequence. -

Time Estimate -

Original estimate: 6 hours. -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT -AUTH #28: Create Service Contract for Batch Sync -

Status -

NOTE: We'll need to keep a pretty close transaction log of -any action taken during batch sync, and also offer a mechanism for -storing transactions that couldn't be completed for some reason, -e.g. email address already taken, etc., email the admin, offer a -list of transactions that failed for manual resolution by an -admin. -

Design To -Do/Notes -

Performance criteria: Nightly batch run should be able to -complete within 3 hours with 10,000 users. -

We'll want to design an API for an incremental or snapshot -run to call, which takes care of all the updating, logging, error -handling, emailing admins, etc. -

We need examples of how the communication would be done from -our clients. -

We might need a source/ID column in the users table to -identify where they're imported from for doing updates, -particularly if importing from multiple sources (or when some users -are local.) -

Current Design -

None. -

Execution Story -

This is executed in background thread, typically -nightly. -

There's also a link from the authority administration page to -run the batch synchronization immediately. -

The process runs like this: -

OpenACS retrieves a document from the enterprise server -containing user information. Example mechanisms: -
- A file is delivered to an agreed-on location in the file -system at an agreed-on point in time. -
- OpenACS does a normal HTTP request to a remote server, -which returns the document. -
- OpenACS does a SOAP (Web Service) request to a remote -server, which returns the document. -
- OpenACS retrieves a file from an SMB server or an FTP -server. -
-
The document will contain either the complete user list -(IMS: "snapshot"), or an incremental user list (IMS: "Event Driven" --- contains only adds, edits, updates). You could for example do a -complete transfer once a month, and incrementals every night. The -invocation should decide which type is returned. -
The document will be in an agreed-on format, e.g. an XML -format based on the IMS Enterprise -Specification (example -XML document

Tradeoffs -

The design should favor interoperability, reliability and -robustness. -

External Design -

NOTE: Do we really want to do this as service contracts? We -might be better off getting one implementation running, and only do -the service contract when we're certain what it would look -like. -

TODO: Look at how Blackboard and other systems implements -this, specifically how do they get the data out of the other -system. Which enterprise servers already support the IMS Enterprise -specification? -

TODO: Find out if Greenpeace needs an different exchange -format from IMS Enterprise, given that they're not in the -University business. -

Service contract for retrieving the document: -

-    GetDocument ( 
-        type:       0 = snapshot
-                    1 = incremental
-        since:      date that you want the incremental update since?
-        parameters: values of implementation-specific parameters
-    ): document as string
-        Performs the request necessary to get a document containing
-        enterprise information.
-    GetParameters (
-    ): list of parameters specific to this implementation.
-        Parameters would typically be the URL to make a request to.
-

Service contract for processing the document: -

-    ProcessDocument ( 
-        type:       0 = snapshot
-                    1 = incremental
-        since:      date that you want the incremental update since?
-        document:   the document containing either incremental or snapshot of enterprise data.
-        parameters: values of implementation-specific parameters
-    ): document as string
-        Processes the document and updates the OpenACS users and other tables appropriately.
-    GetParameters (
-    ): list of parameters specific to this implementation.
-        Not sure what parameters would be.
-

It looks like we'll use the IMS standard for formatting of -the doucment, but not so -

Standards -

-Consolidation -before the leap; IMS Enterprise 1.1 -: This sect2 says that -IMS Enterprise 1.1 (current version) does not address the -communication model, which is critically missing for real seamless -interoperability. IMS Enterprise 2.0 will address this, but -Blackboard, who's influential in the IMS committee, is adopting -OKI's programming interrfaces for this. -
-IMS -and OKI, the wire and the socket - -

Page Flow -

For features with UI, a map of all pages, showing which pages -can call others, which are includeable, etc. For each page, show -all UI elements on the page (text blocks, forms, form controls). -Include administration functionality. -

Internal Design -

- Describe key algorithms, including pseudo-code. -

Data Model -

- Describe data model changes. -

Error Handling -

- What error codes or error conditions could result? How are they - handled? -

Upgrade -

- Describe in pseudo-code how upgrade will be implemented. -

EXT-AUTH-29: -Password Management Service Contract (1 hour) -

- by -

- Already done by Lars. Todo: improve documentation of return values. - by -

EXT-AUTH -#30: Create Authority Management API -

External Design -

- We'll want an API that lets us -

add authorities: auth::authority::new -
delete authorities: auth::authority::delete -
and edit authorities: auth::authority::edit -

- authorities. -

Here goes: -

Internal Design -

-ad_proc -public auth::authority::new {
-      {-authority_id:required}
-      {-short_name:required}
-      {-pretty_name:required}
-      {-sort_order:required}
-      {-auth_impl_id:required}
-      {-auth_p:required}
-      {-pwd_impl_id:required}
-      {-forgotten_pwd_url:required}
-      {-change_pwd_url:required}
-      {-register_impl_id:required}
-      {-register_p:required}
-      {-register_url:required}
-} {
-   db_dml new_authority {
-      insert into auth_authorities (
-        authority_id,
-        short_name,
-        pretty_name,
-        active_p,
-        sort_order,
-        auth_impl_id,
-        auth_p,
-        pwd_impl_id,
-        forgotten_pwd_url,
-        change_pwd_url,
-        register_impl_id,
-        register_p,
-        register_url
-      ) values (
-        :authority_id,
-        :short_name,
-        :pretty_name,
-        1,
-        :sort_order,
-        :auth_impl_id,
-        :auth_p,
-        :pwd_impl_id,
-        :forgotten_pwd_url,
-        :change_pwd_url,
-        :register_impl_id,
-        :register_p,
-        :register_url
-      )
-   }
-}
-ad_proc -public auth::authority::delete {
-  {-authority_id:requied}
-} {
-   db_exec delete_authority {
-      delete from auth_authorities 
-      where authority_id = :authority_id
-   }
-}
-ad_proc -public auth::authority::edit {
-      {-authority_id:required}
-      {-short_name:required}
-      {-pretty_name:required}
-      {-active_p:required}
-      {-sort_order:required}
-      {-auth_impl_id:required}
-      {-auth_p:required}
-      {-pwd_impl_id:required}
-      {-forgotten_pwd_url:required}
-      {-change_pwd_url:required}
-      {-register_impl_id:required}
-      {-register_p:required}
-      {-register_url:required}
-} {
-   db_exec edit_authority {
-      update auth_authorities 
-      set    short_name = :short_name,
-             pretty_name = :pretty_name,
-             active_p = :active_p,
-             sort_order = :sort_order,
-             auth_impl_id = :auth_impl_id,
-             auth_p = :auth_p,
-             pwd_impl_id = :pwd_impl_id,
-             forgotten_pwd_url = :forgotten_pwd_url,
-             change_pwd_url = :change_pwd_url,
-             register_impl_id = :register_impl_id,
-             register_p = :register_p,
-             register_url = :register_url
-      where  authority_id = :authority_id
-   }
-}
-

Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

EXT-AUTH-31: -External Authentication Datamodel (2 hours) -

- by -

- The columns authority_id and username have been added to the users - table for Oracle. We need to add them for PostgreSQL and provide - upgrade scripts. -

-create table users (
-        user_id                 not null
-                                constraint users_user_id_fk
-                                references persons (person_id)
-                                constraint users_pk primary key,
-        authority_id            integer
-                                constraint users_auth_authorities_fk
-                                references auth_authorities(authority_id),
-        username                varchar2(100) 
-                                constraint users_username_nn 
-                                not null,
-        screen_name             varchar2(100)
-                                constraint users_screen_name_un
-                                unique,
-        priv_name               integer default 0 not null,
-        priv_email              integer default 5 not null,
-        email_verified_p        char(1) default 't'
-                                constraint users_email_verified_p_ck
-                                check (email_verified_p in ('t', 'f')),
-        email_bouncing_p        char(1) default 'f' not null
-                                constraint users_email_bouncing_p_ck
-                                check (email_bouncing_p in ('t','f')),
-        no_alerts_until         date,
-        last_visit              date,
-        second_to_last_visit    date,
-        n_sessions              integer default 1 not null,
-        -- local authentication information
-        password                char(40),
-        salt                    char(40),
-        password_question       varchar2(1000),
-        password_answer         varchar2(1000),
-        -- table constraints
-        constraint users_authority_username_un
-        unique (authority_id, username)
-);
-
-

- - by -

EXT -AUTH #32: Service Contract Implementation Parameters -

Execution Story -

When the administrator configures an authority to use a -specific service contract implementation, e.g. PAM, that -implementation can say which parameters it supports, e.g. Host, -Port, Root node, etc. -

The administrator will specify values for these parameters as -part of configuring the authority. -

These parameter values will be passed along to the service -contract implementation when its methods get called. -

Tradeoffs -

Flexibility, usability. -

External Design -

We're considering whether to implement a very simple solution -a' la current package parameters, or a general configuration -solution as outlined in the -Configurator -Spec -. -

Data Model -

Simple solution: A table with key/value pairs attached to the -auth_authorities table. -

Time Estimate -

Original estimate, simple solution: 8 hours -

Original estimate, complex solution: 50 hours -

Hours spent: -

Estimated hours remaining: -

Risk: -

OACS-COL-1: -Automate install and self-test (5 hours) -

- by -

- I need to make sure the install scripts work. I then need to: -

Schedule nightly recreation -
Make sure the install script invokes -acs-automated-testing tests and checks results -
Make sure emails go out to appropriate people -

- by -

EXT AUTH #x: Title -of feature -

Current Design -

Describe how any functionality to be replaced works. -

Execution Story -

Beginning with a human being using a computer, describe how -the feature is triggered and what it does. As this story becomes -more detailed, move pieces to appropriate parts of the -document. -

Tradeoffs -

Which one or two of the following are emphasised in this -design? -

Performance: availability and efficiency -
Flexibility -
Interoperability -
Reliability and robustness -
Usability -
Maintainability -
Portability -
Reusability -
Testability -

External Design -

For a feature with a public API, write the stub for each -procedure, showing all parameters, a preliminary description of -instructions, and expected return. -

For a feature without a public API, describe how the feature -is invoked. -

Include admin-configurable parameters. -

Page Flow -

Internal Design -

Describe key algorithms, including pseudo-code. -

Data Model -

Describe data model changes. -

Error Handling -

What error codes or error conditions could result? How are -they handled? -

Upgrade -

Describe in pseudo-code how upgrade will be -implemented. -

Time Estimate -

Original estimate: -

Hours spent: -

Estimated hours remaining: -

Risk: -

Prev	Home	Next
External Authentication Requirements	Up	Index

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 19 Nov 2003 15:44:50 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 11 Dec 2003 23:08:46 -0000 1.13 @@ -1,4 +1,4 @@ -External Authentication Requirements

Prev	Chapter�10.�Kernel Documentation	Next

External Authentication Requirements

Vision

People have plenty of usernames and passwords already, we +External Authentication Requirements

Prev	Chapter�11.�Kernel Documentation	Next

External Authentication Requirements

Vision

People have plenty of usernames and passwords already, we don't want them to have yet another. We want people to be able to log in to OpenACS with the same password they use to log in to any other system.

Besides, administrators have better things to do than create @@ -44,7 +44,7 @@ only one implementation of the authentication API, namly the one included in OpenACS Core.

Authentication Driver API: The service contract which authentication drivers implement.

Conceptual Pictures

Authentication:

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

Feature	Status	Description
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Login

Feature	Status	Description
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username is email switch

Users will log in using a username, a authority, and a +

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

Feature	Status	Description
EXT-AUTH-01	A	Extend Authentication/Acct Status API
EXT-AUTH-03	A	Account Creation API
EXT-AUTH-05	A	Password Management API
EXT-AUTH-30	A	Authority Management API

Login

Feature	Status	Description
EXT-AUTH-04	A	Rewrite login, register, and admin pages to use APIs
EXT-AUTH-38	A	ad_form complain feature
EXT-AUTH-19	A	Rewrite password recovery to use API
EXT-AUTH-21	A	Rewrite email verification with API
EXT-AUTH-28	A	Username is email switch

Users will log in using a username, a authority, and a password. The authority is the source for user/password verification. OpenACS can be an authority itself.

Each user in OpenACS will belong to exactly one authority, which can either be the "local" OpenACS users table, in which case the @@ -376,4 +376,4 @@ PAM specification

Draft Proposal by Andrew Grumet.

Yale CAS, a centrl authentication service a' la - Passport.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
1	Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.	20 Aug 2003	Joel Aufrecht

Prev	Home	Next
Bootstrapping OpenACS	Up	External Authentication Design

View comments on this page at openacs.org + Passport.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
1	Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.	20 Aug 2003	Joel Aufrecht

Prev	Home	Next
Bootstrapping OpenACS	Up	Index

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/filename.html 19 Nov 2003 15:44:50 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/filename.html 11 Dec 2003 23:08:46 -0000 1.24 @@ -1,4 +1,4 @@ -Detailed Design Documentation Template

Prev	Chapter�9.�Engineering Standards	Next

Detailed Design Documentation Template

By You

Start Note

+Detailed Design Documentation Template

Prev	Chapter�10.�Documentation Standards	Next

Detailed Design Documentation Template

By You

Start Note

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 @@ -114,7 +114,7 @@ within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics.

Configuration/Parameters

- Under OpenACS 5.0.0b1, parameters are set at two levels: at the global level by + Under OpenACS 5.0.0b4, 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.

Future Improvements/Areas of Likely Change

@@ -135,4 +135,4 @@

System creator
System owner
Documentation author

Revision History

The revision history table below is for this template - modify it as needed for your actual design document. -

Document Revision #	Action Taken, Notes	When?	By Whom?
0.3	Edited further, incorporated feedback from Michael Yoon	9/05/2000	Kai Wu
0.2	Edited	8/22/2000	Kai Wu
0.1	Creation	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Using PSGML mode in Emacs	Up	System/Application Requirements Template

docs@openacs.org

View comments on this page at openacs.org +
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Creation 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)

Prev	Home	Next
Using nXML mode in Emacs	Up	System/Application Requirements Template

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/form-builder.html 11 Dec 2003 21:39:47 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 11 Dec 2003 23:08:46 -0000 1.3 @@ -1,4 +1,4 @@ -Using HTML Forms
Prev Chapter�8.�Development Reference Next
Using HTML Forms
Overview
Multi-part Elements
Some elements have more than one choice, or can submit more than one value.
SELECT elements
Creating the form element.�Populate a list of lists with values for the option list.
set foo_options [db_list_of_lists foo_option_list " +Using HTML Forms
Prev Chapter�8.�Development Reference Next
Using HTML Forms
Overview
Multi-part Elements
Some elements have more than one choice, or can submit more than one value.
SELECT elements
Creating the form element.�Populate a list of lists with values for the option list.
set foo_options [db_list_of_lists foo_option_list " select foo, foo_id from foos Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -N -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/groups-design.html 19 Nov 2003 15:44:50 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 11 Dec 2003 23:08:46 -0000 1.17 @@ -1,4 +1,4 @@ -OpenACS 4 Groups Design
Prev Chapter�10.�Kernel Documentation Next
OpenACS 4 Groups Design
By Rafael H. Schloming and Mark Thomas
+Groups Design
Prev Chapter�11.�Kernel Documentation Next
Groups Design
By Rafael H. Schloming and Mark Thomas
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Essentials
User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
PL/SQL file
@@ -303,4 +303,4 @@ Mark Thomas 0.3Additional revisions; tried to clarify membership/compostion09/08/2000 Mark Thomas -
Prev Home Next
OpenACS 4 Groups Requirements Up OpenACS 4 Subsites Requirements
docs@openacs.org
View comments on this page at openacs.org +
Prev Home Next
Groups Requirements Up Subsites Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -N -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 19 Nov 2003 15:44:50 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 11 Dec 2003 23:08:46 -0000 1.17 @@ -1,4 +1,4 @@ -OpenACS 4 Groups Requirements
Prev Chapter�10.�Kernel Documentation Next
OpenACS 4 Groups Requirements
By Rafael H. Schloming, Mark Thomas
+Groups Requirements
Prev Chapter�11.�Kernel Documentation Next
Groups Requirements
By Rafael H. Schloming, Mark Thomas
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Introduction
Almost all database-backed websites have users, and need to model the @@ -220,4 +220,4 @@ where clause, whatever mechanism is used to check membership in SQL should be fairly small and simple.
Requirements: User Interface
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
Revision History
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
Prev Home Next
OpenACS 4 Permissions Design Up OpenACS 4 Groups Design
docs@openacs.org
View comments on this page at openacs.org +outlined in 130.x to 165.x
Revision History
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
Prev Home Next
Permissions Design Up Groups Design
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 19 Nov 2003 15:44:50 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 11 Dec 2003 23:08:46 -0000 1.8 @@ -1,4 +1,4 @@ -OpenACS Internationalization Requirements
Prev Chapter�10.�Kernel Documentation Next
OpenACS Internationalization Requirements
by Henry Minsky, +OpenACS Internationalization Requirements
Prev Chapter�11.�Kernel Documentation Next
OpenACS Internationalization Requirements
by Henry Minsky, Yon Feldman, Lars Pind, Peter Marklund, @@ -262,7 +262,7 @@ column size declarations in the schema are large enough to accomodate required data (such as email addresses in Japanese). Since 5.0.0, this is covered in the database -install instructions for both PostGreSQL and Oracle.
Email and +install instructions for both PostgreSQL and Oracle.
Email and Messaging
When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be able to specify what character set encoding to use. Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/i18n.html 19 Nov 2003 15:44:50 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/i18n.html 11 Dec 2003 23:08:46 -0000 1.15 @@ -1,4 +1,4 @@ -Internationalization
Prev Chapter�10.�Kernel Documentation Next
Internationalization
+Internationalization
Prev Chapter�11.�Kernel Documentation Next
Internationalization
By Peter Marklund and Lars Pind
@@ -38,7 +38,7 @@ which are static and mostly text, it may be easier to create a new ADP page for each language. In this case, the pages are distinguished by a file naming convention. -
Separate Templates for each Locale
If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.
Message Keys in Template Files (ADP Files)
+
Separate Templates for each Locale
If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are still processed.
Message Keys in Template Files (ADP Files)
Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in @@ -151,7 +151,7 @@ Use the *_pretty version in your ADP page.
To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. -
Internationalizing Forms
When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Internationalizing Existing Packages
Internationalize Message text in ADP and TCL
Acs-lang includes tools to automate some +
Internationalizing Forms
When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Internationalizing Existing Packages
Internationalize Message text in ADP and TCL
Acs-lang includes tools to automate some internationalization. From /acs-admin/apm/, select a package and then click on @@ -240,11 +240,11 @@ with the appropriate notation for the type of file, and store the text in the message catalog. You need to run the process twice, once for ADP files, and once for Tcl files. -
Internationalize Package Parameters with visible messages
+
Internationalize Package Parameters with visible messages
See Multilingual APM Parameters -
Internationalize Date and Time queries
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" * +
Internationalize Date and Time queries
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" * grep -r "to_date.*H" *
In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
becomes
to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system.
When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
Design Notes
User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:
Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US
For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is -found, then that locale is offered instead.
Prev Home Next
OpenACS Internationalization Requirements Up OpenACS 4 Security Requirements
docs@openacs.org
View comments on this page at openacs.org +found, then that locale is offered instead.

Initialize CVS (OPTIONAL)

CVS is a source control system. Create and initialize a +Initialize CVS (OPTIONAL)

Prev	Appendix�B.�Install additional supporting software	Next

Initialize CVS (OPTIONAL)

CVS is a source control system. Create and initialize a directory for a local cvs repository.

[root@yourserver tmp]# mkdir /cvsroot
 [root@yourserver tmp]# cvs -d /cvsroot init
 [root@yourserver tmp]#
-mkdir /cvsroot
-cvs -d /cvsroot init

Prev	Home	Next
Unpack the OpenACS tarball	Up	Add PSGML commands to emacs init file (OPTIONAL)

View comments on this page at openacs.org +mkdir /cvsroot +cvs -d /cvsroot init

Install Daemontools (OPTIONAL)

Daemontools is a collection of programs for controlling - other processes. We use daemontools to run and monitor AOLServer. It is + other processes. We use daemontools to run and monitor AOLserver. It is installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services.

Install Daemontools

download daemontools and install it.

Red Hat 8

[root@yourserver root]# mkdir -p /package
+      services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root@yourserver root]# mkdir -p /package
 [root@yourserver root]# chmod 1755 /package/
 [root@yourserver root]# cd /package/
 [root@yourserver package]# tar xzf /tmp/daemontools-0.76.tar.gz
@@ -15,12 +15,12 @@
 Adding svscanboot to inittab...
 init should start svscan now.
 [root@yourserver root]#
-mkdir -p /package 
+mkdir -p /package 
 chmod 1755 /package 
 cd /package 
 tar xzf /tmp/daemontools-0.76.tar.gz 
 cd admin/daemontools-0.76 
-package/install
Red Hat 9
Make sure you have the source tarball in
+package/install

Red Hat 9

Make sure you have the source tarball in /tmp, or download it.

[root@yourserver root]# mkdir -p /package
 [root@yourserver root]# chmod 1755 /package/
@@ -47,21 +47,21 @@
 Adding svscanboot to inittab...
 init should start svscan now.
 [root@yourserver root]#
-mkdir -p /package 
+mkdir -p /package 
 chmod 1755 /package 
 cd /package 
 tar xzf /tmp/daemontools-0.76.tar.gz 
 cd admin
 wget http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch
 cd daemontools-0.76
 patch -p1 < ../daemontools-0.76.errno.patch
-package/install

Debian

root:~# apt-get install daemontools-installer
+package/install

Debian

root:~# apt-get install daemontools-installer
 root:~# build-daemontools

Verify that svscan is running. If it is, you should see these two processes running:

[root@yourserver root]# ps -auxw | grep service
 root     13294  0.0  0.1  1352  272 ?        S    09:51   0:00 svscan /service
 root     13295  0.0  0.0  1304  208 ?        S    09:51   0:00 readproctitle service errors: .......................................
 [root@yourserver root]#

Install a script to grant non-root users permission to - control daemontools services.

[root@yourserver root]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup + control daemontools services.

[root@yourserver root]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup
 [root@yourserver root]# chmod 755 /usr/local/bin/svgroup
-cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup 
-chmod 755 /usr/local/bin/svgroup

Install Full Text Search

Install OpenFTS module

If you want full text search, and you are running PostGreSQL, install this module to support FTS. Do this step after you have installed both PostGreSQL and - Aolserver. You will need the openfts - tarball in /tmp.

Install Tsearch. This is a PostGreSQL module that +Install Full Text Search

Prev	Appendix�B.�Install additional supporting software	Next

Install Full Text Search

Install OpenFTS module

If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and + AOLserver. You will need the openfts + tarball in /tmp.

Install Tsearch. This is a PostgreSQL module that OpenFTS requires.

[root@yourserver root]# su - postgres
 [postgres@yourserver pgsql]$ cd /usr/local/src/postgresql-7.2.4/contrib/tsearch/
 [postgres@yourserver tsearch]$ make
@@ -17,11 +17,11 @@
 logout
 
 [root@yourserver root]#
-su - postgres
+su - postgres
 cd /usr/local/src/postgresql-7.2.4/contrib/tsearch
 make
 make install
-exit

Unpack the OpenFTS tarball and compile and 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/
@@ -44,15 +44,15 @@
 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 
+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 /usr/local/src/Search-OpenFTS-tcl-0.3.2
+

Build some supplemental modules.

[root@yourserver aolserver]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
 [root@yourserver Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.4/contrib
 [root@yourserver Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts
 [root@yourserver pgsql_contrib_openfts]# make
@@ -67,15 +67,15 @@
 /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 /usr/local/src/Search-OpenFTS-tcl-0.3.2
+cd /usr/local/src/Search-OpenFTS-tcl-0.3.2
 cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.4/contrib
 cd /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts
 make
 su postgres
 make install
-exit

Install OpenFTS prerequisites in PostGreSQL instance

If you are installing Full Text Search, add required +exit

Install OpenFTS prerequisites in PostgreSQL instance

If you are installing Full Text Search, add required packages to the new database. (In order for full text search - to work, you must also install the PostGreSQL + to work, you must also install the PostgreSQL OpenFTS module and prerequisites.)

[service0@yourserver service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql
 BEGIN
 CREATE
@@ -86,8 +86,8 @@
 CREATE
 CREATE
 [service0@yourserver service0]$
-/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql
-/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql

Enable OpenFTS in config.tcl

If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)

#ns_param   nsfts           ${bindir}/nsfts.so

Install Full Text Search Engine

Click Package Manager on the right side of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql +/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql

`Enable OpenFTS in config.tcl`

If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)

#ns_param   nsfts           ${bindir}/nsfts.so

`Install Full Text Search Engine`

Click Package Manager on the right side of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install packages link.
On the next screen, after it loads, click on Uncheck all boxes, then click the checkbox next to OpenFTS Driver 4.2. Then click Next.
Click Install Packages

Restart the service.

[service0@yourserver service0]$ svc -t /service/service0
 [service0@yourserver service0]$

Wait a minute, then browse back to the home page.
Click on Site Map on the top right side of the screen.

Mount the OpenFTS Full Text Search Engine in the site map.

Click the new sub folder link on the "/" line, the first line under Main Site:/.
Type openfts and click New.
On the new openfts line, click the mount link.

Click OpenFTS Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 19 Nov 2003 15:44:50 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 11 Dec 2003 23:08:46 -0000 1.9 @@ -18,17 +18,17 @@ [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
+cd /usr/local/src/aolserver
 wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz
 tar xzf nsopenssl-2.1.tar.gz 
 cd nsopenssl-2.1 
 make OPENSSL=/usr/local/ssl 
 cp nsopenssl.so /usr/local/aolserver/bin 
-cp https.tcl /usr/local/aolserver/modules/tcl/

For Debian (more - information):

apt-get install libssl-dev
+cp https.tcl /usr/local/aolserver/modules/tcl/

For Debian (more + information):

apt-get install libssl-dev
 cd /usr/local/src/aolserver
 tar xzf /tmp/nsopenssl-2.1.tar.gz
 cd nsopenssl-2.1
 make OPENSSL=/usr/lib/ssl
 cp nsopenssl.so /usr/local/aolserver/bin
-cp https.tcl /usr/local/aolserver/modules/tcl/

Prev	Home	Next
Install Full Text Search	Up	Install tclwebtest.

docs@openacs.org

View comments on this page at openacs.org +cp https.tcl /usr/local/aolserver/modules/tcl/

Prev	Home	Next
Install Full Text Search	Up	Install tclwebtest.

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-qmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 19 Nov 2003 15:44:50 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 11 Dec 2003 23:08:46 -0000 1.15 @@ -6,12 +6,12 @@ Download ucspi and install it. [root@yourserver root]# cd /usr/local/src [root@yourserver src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz [root@yourserver src]# tar xzf ucspi-tcp-0.88.tar.gz -cd /usr/local/src +cd /usr/local/src wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz -tar xzf ucspi-tcp-0.88.tar.gz Red Hat 9 only wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch +tar xzf ucspi-tcp-0.88.tar.gz Red Hat 9 only wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch cd ucspi-tcp-0.88 patch -p1 <../ucspi-tcp-0.88.errno.patch -cd .. All platforms continue: [root@yourserver src]# cd ucspi-tcp-0.88 +cd .. All platforms continue: [root@yourserver src]# cd ucspi-tcp-0.88 [root@yourserver ucspi-tcp-0.88]# make ( cat warn-auto.sh; \ echo 'main="$1"; shift'; \(many lines omitted) @@ -21,17 +21,17 @@ ./install ./instcheck [root@yourserver ucspi-tcp-0.88]# - + cd ucspi-tcp-0.88 make -make setup check Verify that ucspi-tcp was installed successfully by +make setup check Verify that ucspi-tcp was installed successfully by running the tcpserver program which is part of ucspi-tcp: [root@yourserver ucspi-tcp-0.88]# tcpserver tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root@yourserver ucspi-tcp-0.88]# - + (I'm not sure if this next step is 100% necessary, but when I skip it -I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLServer sends outgoing mail via the ns_sendmail +I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our case, the qmail replacement wrapper for the sendmail executable. In some cases, though, the outgoing mail requset is apparently sent @@ -40,10 +40,10 @@ Unless this mail is addressed to the same machine, qmail thinks that it's an attempt to relay mail, and rejects it. So these two commands set up an exception so that any mail sent from 127.0.0.1 is allowed to -send outgoing mail. [root@yourserver ucspi-tcp-0.88]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp +send outgoing mail. [root@yourserver ucspi-tcp-0.88]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp [root@yourserver ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp Install Qmail.� Download qmail, +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp +tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp Install Qmail.� Download qmail, set up the standard supporting users and build the binaries: [root@yourserver root]# cd /usr/local/src [root@yourserver src]# wget http://www.qmail.org/netqmail-1.04.tar.gz [root@yourserver src]# tar xzf netqmail-1.04.tar.gz @@ -86,7 +86,7 @@ echo CC=\'`head -1 conf-cc`\'; \(many lines omitted) ./install ./instcheck -cd /usr/local/src +cd /usr/local/src wget http://www.qmail.org/netqmail-1.04.tar.gz tar xzf netqmail-1.04.tar.gz mkdir /var/qmail @@ -102,11 +102,11 @@ cd netqmail-1.04 ./collate.sh cd netqmail-1.04 -make setup check Replace sendmail with qmail's wrapper. [root@yourserver qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail +make setup check Replace sendmail with qmail's wrapper. [root@yourserver qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail [root@yourserver qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail [root@yourserver qmail-1.03]# -rm -f /usr/bin/sendmail /usr/sbin/sendmail -ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail. [root@yourserver qmail-1.03]# ./config-fast yourserver.test +rm -f /usr/bin/sendmail /usr/sbin/sendmail +ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail. [root@yourserver qmail-1.03]# ./config-fast yourserver.test Your fully qualified host name is yourserver.test. Putting yourserver.test into control/me... Putting yourserver.test into control/defaultdomain... @@ -116,62 +116,62 @@ Now qmail will refuse to accept SMTP messages except to yourserver.test. Make sure to change rcpthosts if you add hosts to locals or virtualdomains! [root@yourserver qmail-1.03]# -./config-fast yourserver.test All incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail. [root@yourserver qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root +./config-fast yourserver.test All incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail. [root@yourserver qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root [root@yourserver alias]# chmod 644 ~alias/.qmail* [root@yourserver alias]# /var/qmail/bin/maildirmake ~alias/Maildir/ [root@yourserver alias]# chown -R alias.nofiles /var/qmail/alias/Maildir [root@yourserver alias]# -cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root +cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root chmod 644 ~alias/.qmail* /var/qmail/bin/maildirmake ~alias/Maildir/ -chown -R alias.nofiles /var/qmail/alias/Maildir Configure qmail to use the Maildir delivery format +chown -R alias.nofiles /var/qmail/alias/Maildir Configure qmail to use the Maildir delivery format (instead of mbox), and install a version of the qmail startup script modified to use Maildir. [root@yourserver alias]# echo "./Maildir" > /var/qmail/bin/.qmail -[root@yourserver alias]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc +[root@yourserver alias]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc [root@yourserver alias]# chmod 755 /var/qmail/rc [root@yourserver alias]# -echo "./Maildir" > /var/qmail/bin/.qmail -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc +echo "./Maildir" > /var/qmail/bin/.qmail +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc chmod 755 /var/qmail/rc - Set up the skeleton directory so that new users will + Set up the skeleton directory so that new users will be configured for qmail. [root@yourserver root]# /var/qmail/bin/maildirmake /etc/skel/Maildir [root@yourserver root]# echo "./Maildir/" > /etc/skel/.qmail [root@yourserver root]# -/var/qmail/bin/maildirmake /etc/skel/Maildir -echo "./Maildir/" > /etc/skel/.qmail As recommended, we will run qmail with daemontools +/var/qmail/bin/maildirmake /etc/skel/Maildir +echo "./Maildir/" > /etc/skel/.qmail As recommended, we will run qmail with daemontools control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start. [root@yourserver root]# mkdir -p /var/qmail/supervise/qmail-send/log [root@yourserver root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log [root@yourserver root]# mkdir /var/log/qmail [root@yourserver root]# chown qmaill /var/log/qmail -[root@yourserver root]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl +[root@yourserver root]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl [root@yourserver root]# chmod 755 /var/qmail/bin/qmailctl [root@yourserver root]# ln -s /var/qmail/bin/qmailctl /usr/bin -[root@yourserver root]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run -[root@yourserver root]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run -[root@yourserver root]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run -[root@yourserver root]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run +[root@yourserver root]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run +[root@yourserver root]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run +[root@yourserver root]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run +[root@yourserver root]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-send/run [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-send/log/run [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run [root@yourserver root]# chmod 755 /var/qmail/supervise/qmail-smtpd/log/run [root@yourserver root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service [root@yourserver root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service -mkdir -p /var/qmail/supervise/qmail-send/log +mkdir -p /var/qmail/supervise/qmail-send/log mkdir -p /var/qmail/supervise/qmail-smtpd/log mkdir /var/log/qmail chown qmaill /var/log/qmail -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl chmod 755 /var/qmail/bin/qmailctl ln -s /var/qmail/bin/qmailctl /usr/bin -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run -cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run +cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run chmod 755 /var/qmail/supervise/qmail-send/run chmod 755 /var/qmail/supervise/qmail-send/log/run chmod 755 /var/qmail/supervise/qmail-smtpd/run chmod 755 /var/qmail/supervise/qmail-smtpd/log/run ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service - Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions. [root@yourserver root]# qmailctl stat + Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions. [root@yourserver root]# qmailctl stat /service/qmail-send: up (pid 32700) 430 seconds /service/qmail-send/log: up (pid 32701) 430 seconds /service/qmail-smtpd: up (pid 32704) 430 seconds Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 19 Nov 2003 15:44:50 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 11 Dec 2003 23:08:46 -0000 1.15 @@ -26,7 +26,7 @@ Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - + (Wherever you see the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're @@ -54,7 +54,7 @@ Review (and modify if needed) the partitions created and click Next On the pop-up window asking "Are you sure you want to do this?" click Yes - IF YOU ARE WIPING YOUR HARD DRIVE. Click Next on the boot loader screen Configure Networking. + IF YOU ARE WIPING YOUR HARD DRIVE. Click Next on the boot loader screen

Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.

DHCP is a system by which a computer that @@ -75,7 +75,7 @@ Mail (SMTP). In the Other ports box, enter 443, 8000, 8443. Click Next. -Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.

Select any additional languages you want the +Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up.

Select any additional languages you want the computer to support and then click Next

Choose your time zone and click Next.

Type in a root password, twice.

On the Package selection page, we're going to @@ -87,13 +87,13 @@ risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later. -

check Editors (this installs emacs),

click Details next to Text-based Internet, check lynx, and click OK;

check Authoring and Publishing (this installs docbook),

uncheck Server Configuration Tools,

uncheck Web Server,

uncheck Windows File Server,

check SQL Database Server (this installs PostGreSQL),

check Development Tools (this installs gmake and other build tools),

uncheck Administration Tools, and

uncheck Printing Support.

At the bottom, check Select Individual Packages and click Next

We need to fine-tune the exact list of packages. +

check Editors (this installs emacs),

click Details next to Text-based Internet, check lynx, and click OK;

check Authoring and Publishing (this installs docbook),

uncheck Server Configuration Tools,

uncheck Web Server,

uncheck Windows File Server,

check SQL Database Server (this installs PostgreSQL),

check Development Tools (this installs gmake and other build tools),

uncheck Administration Tools, and

uncheck Printing Support.

At the bottom, check Select Individual Packages and click Next

We need to fine-tune the exact list of packages. The same rules apply as in the last step - you can add more stuff, but you shouldn't remove anything the guide adds. We're going to go through all the packages in one big list, so select Flat View and wait. In a minute, a -list of packages will appear.

uncheck apmd (monitors power, not very useful for servers),

check ImageMagick (required for the photo-album packages,

uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon),

check mutt (a mail program that reads Maildir),

uncheck nfs-utils (nfs is a major security risk),

uncheck pam-devel (I don't remember why, but we don't want this),

uncheck portmap,

uncheck postfix (this is an MTA, but we're going to install qmail later),

check postgresql-devel,

uncheck rsh (rsh is a security hole),

uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),

check tcl (we need tcl), and

uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).

Click Next

Red Hat isn't completely happy with the combination +list of packages will appear.

uncheck apmd (monitors power, not very useful for servers),

check ImageMagick (required for the photo-album packages,

uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon),

check mutt (a mail program that reads Maildir),

uncheck nfs-utils (nfs is a major security risk),

uncheck pam-devel (I don't remember why, but we don't want this),

uncheck portmap,

uncheck postfix (this is an MTA, but we're going to install qmail later),

check postgresql-devel,

uncheck rsh (rsh is a security hole),

uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later),

check tcl (we need tcl), and

uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).

Click Next

Red Hat isn't completely happy with the combination of packages we've selected, and wants to satisfy some dependencies. Don't let it. On the next screen, choose Ignore Package @@ -119,7 +119,7 @@ upgrading all of that. Since you are upgrading the kernel, reboot after this step.

Lock down SSH

- + SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming @@ -143,20 +143,20 @@ bunch of scripts for starting and stopping programs, and directories of symlinks for each system level indicating which services should be up and down at any given service - level. We'll use this system for PostGreSQL, but we'll use - daemontools to perform a similar function for AOLServer. + level. We'll use this system for PostgreSQL, but we'll use + daemontools to perform a similar function for AOLserver. (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's - had any trouble leaving PostGreSQL the way it is.) + had any trouble leaving PostgreSQL the way it is.)
```
[root@yourserver root]# service pcmcia stop
 [root@yourserver root]# service netfs stop
 [root@yourserver root]# chkconfig --del pcmcia
 [root@yourserver root]# chkconfig --del netfs
 [root@yourserver root]#
-service pcmcia stop
+service pcmcia stop
 service netfs stop
 chkconfig --del pcmcia
-chkconfig --del netfs
```
If you installed PostGreSQL, do also +chkconfig --del netfs
If you installed PostgreSQL, do also service postgresql start and chkconfig --add postgresql.
Plug in the network cable.
Verify that you have connectivity by going to another computer and ssh'ing to yourserver, logging in as @@ -197,7 +197,7 @@ The system is going down for reboot NOW! [root@yourserver tmp]# -
```
cd /tmp
+cd /tmp
 wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm
 rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm
-reboot
```

Basic Steps
- The basic steps to getting OpenACS up and running are: -
Install an OS (Linux, FreeBSD, OpenBSD, Appendix�A, Install Red Hat 8/9, the section called “OpenACS Installation Guide for Mac OS X”, the section called “OpenACS Installation Guide for Windows2000”).
Install a database (Oracle or - PostgreSQL).
Install the AOLserver webserver.
Create a unique database and system user. - Install the OpenACS tarball, start and AOLserver instance, and - use the OpenACS web pages to complete installation - (Install OpenACS 5.0.0b1).
Binaries and other shortcuts
The patched version of AOLserver we use is not currently - available in a precompiled binary.
- The packaged version of - PostGreSQL in Debian and Red Hat and FreeBSD ports works fine.
Jonathan Marsden has created RPMs (at - http://www.xc.org) - for OpenACS 4.5 but there are not yet any for version - 5.0.0b1.
An experimental script automates OpenACS checkout and - installation. -
Requirements
- 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
A Unix-like operating system with tcl, tdom, and - a mail transport agent. (the section called “Prerequisite Software”)
- All of the software that you will need is free and open-source, - except for Oracle. You can obtain a free copy of Oracle for - development purposes. This is described in the Acquire Oracle section. -
Figure�2.1.�Compatibility Matrix
OpenACS Version 3.2.5 4.5 4.6 4.6.1 4.6.2 4.6.3 5.0.0
AolServer 3 Verified � � � � � �
3.3+ad13 � Verified
3.3oacs1 � � � � Verified
3.4.2 � � � � No
3.4.2oacs1 � � � � Verified
3.5.5 � � � � Verified
4 Verified but not for production
PostGreSQL 7.0 Verified � � � � �
7.2.x � Verified
7.3.2 - 7.3.4 No Verified
Oracle 8.1.6 � Verified �
8.1.7 � Verified
9i No Untested

How to use this guide
This is text you will see on - screen, such as a Button 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" + The basic steps for getting OpenACS installed are: +
Install an OS and supporting software (see Install a Unix-like OS or Appendix�A, Install Red Hat 8/9 for more details).
Install a database (see Install Oracle or + Install PostgreSQL).
Install AOLserver (see Install AOLserver 3.3oacs1).
Create a unique database and system user. + Install the OpenACS tarball, start and AOLserver instance, and + use the OpenACS web pages to complete installation + (see Install OpenACS 5.0.0b4).
There are specific instructions available for Mac OS X and + Windows2000 available (see the section called “OpenACS Installation Guide for Mac OS X” or + the section called “OpenACS Installation Guide for Windows2000” for those).
Binaries and other shortcuts
The patched version of AOLserver we use is not currently + available in a precompiled binary.
+ The packaged version of + PostgreSQL in Debian and Red Hat and FreeBSD ports works fine.
An experimental script automates the OpenACS checkout and + installation. +
System Requirements
+ You will need a PC (or equivalent) with at least these minimum + requirements: +
128MB RAM (much more if you want Oracle)
1GB free space on your hard drive (much more if you want Oracle)
A Unix-like operating system with Tcl, tDOM, and + a mail transport agent like sendmail or qmail. (see the section called “Prerequisite Software”)
+ All of the software that you will need is free and open-source, + except for Oracle. You can obtain a free copy of Oracle for + development purposes. This is described in the Acquire Oracle section. +
Table�2.1.�Version Compatibility Matrix
OpenACS Version 3.2.5 4.5 4.6 4.6.1 4.6.2 4.6.3 5.0.0
AOLserver 3 Verified No
3.3+ad13 Untested Verified
3.3oacs1 Untested Verified
3.4.2 No
3.4.2oacs1 Untested Verified Untested
3.5.5 Untested Verified No
4.0 Untested Verified
PostgreSQL 7.0 Verified No
7.2.x � Verified No
7.3.2 - 7.3.4 No Verified
7.4 No Untested
Oracle 8.1.6 � Verified
8.1.7 � Verified
9i No Untested
+ At the time of writing AOLserver 4.0 has been tested with OpenACS and works but has not been used in + production. OpenACS 5.0.0 installs successfully on PostgreSQL 7.4 and Oracle 9i but not all packages + outside core have been tested. +
How to use this guide
This is text you will see on + screen, such as a Button 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 + 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 +su - nsadmin svc -d /service/server1 dropdb server1 -createdb server1
Paths and Users
Figure�2.2.�Assumptions in this Chapter
Fully qualified domain name of your server yourserver.test
name of administrative access account remadmin
OpenACS service service0
OpenACS service account service0
OpenACS database name service0
Root of OpenACS service file tree /var/lib/aolserver/service0
Location of source code tarballs for new software /tmp
The OpenACS tarball contains some files which +createdb server1
Paths and Users
Table�2.2.�Default directories for a standard install
Fully qualified domain name of your server yourserver.test
name of administrative access account remadmin
OpenACS service service0
OpenACS service account service0
OpenACS database name service0
Root of OpenACS service file tree (SERVERROOT) /var/lib/aolserver/service0
Location of source code tarballs for new software /tmp
The OpenACS tarball contains some files which are useful while setting up other software. Those - files are located at: /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files
Database backup directory /var/lib/aolserver/service0/database-backup
Service config files /var/lib/aolserver/service0/etc
Service log files /var/lib/aolserver/service0/log
Compile directory /usr/local/src
PostGreSQL directory /usr/local/pgsql
AOLServer directory /usr/local/aolserver
- None of these locations are set in stone - they're simply - the values that we've chosen. The values that you'll - probably want to change, such as service name, are - marked like this. The other - values we recommend you leave unchanged unless you have a - reason to change them.
Note
- Some of the paths and user accounts have been changed from - those recommended in previous versions of this document to - improve security and maintainability. See this - thread for discussion. -
Getting Help during installation
- We'll do our best to assure that following our instructions will get - you to the promised land. If something goes wrong, don't - panic. There are plenty of ways to get help. Here are some tips: -
- Keep track of the commands you are run and record their output. I - like to do my installations in a shell inside of emacs - (M-x shell) so that I can save - the output if needed. An alternative would be to use the - script command. -
- We'll point out where the error logs for the various pieces of - software are. Output from those logs will help us help you. Don't - worry if you feel overwhelmed by all the information in the error - logs. Over time, you'll find that they make more and more - sense. Soon, you'll actually look forward to errors so that you - can run to the log and diagnose the problem. -
- Search the forums at - openacs.org - you'll often find many people who have - struggled through the same spot that you're in. -
- The bottom of each page has a link to OpenACS.org, where you can post - comments and read other users comments about the - contents of the page. -
- Ask questions at the irc channel on freenode.net - (#openacs). They're knowledgeable and quite friendly - if you can keep them on topic. -
- Post a question on the forums. Make sure - you've done a search first. When you do post, be sure to include - your setup information (OS, etc) as well as the exact commands - that are failing with the accompanying error. If - there's a SQL error in the TCL error or in the log, - post that too. -
- If you find errors in this document or if you have ideas about - making it better, please post them in our - BugTracker. -
($Id: overview.xml,v 1.12 2003/10/28 - 22:07:41 joela Exp $)
Prev Home Next
Chapter�2.�Installation Overview Up Prerequisite Software
docs@openacs.org
View comments on this page at openacs.org + files are located at: /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files
Database backup directory /var/lib/aolserver/service0/database-backup
Service config files /var/lib/aolserver/service0/etc
Service log files /var/lib/aolserver/service0/log
Compile directory /usr/local/src
PostgreSQL directory /usr/local/pgsql
AOLserver directory /usr/local/aolserver
+ None of these locations are set in stone - they're simply + the values that we've chosen. The values that you'll + probably want to change, such as service name, are + marked like this. The other + values we recommend you leave unchanged unless you have a + reason to change them.
Note
+ Some of the paths and user accounts have been changed from + those recommended in previous versions of this document to + improve security and maintainability. See this + thread for discussion.
Getting Help during installation
+ We'll do our best to assure that following our instructions will get + you to the promised land. If something goes wrong, don't + panic. There are plenty of ways to get help. Here are some tips: +
+ Keep track of the commands you are run and record their output. I + like to do my installations in a shell inside of emacs + (M-x shell) so that I can save + the output if needed. An alternative would be to use the + script command. +
+ We'll point out where the error logs for the various pieces of + software are. Output from those logs will help us help you. Don't + worry if you feel overwhelmed by all the information in the error + logs. Over time, you'll find that they make more and more + sense. Soon, you'll actually look forward to errors so that you + can run to the log and diagnose the problem. +
+ Search the forums at + openacs.org - you'll often find many people who have + struggled through the same spot that you're in. +
+ The bottom of each page has a link to OpenACS.org, where you can post + comments and read other users comments about the + contents of the page. +
+ Ask questions at the irc channel on freenode.net + (#openacs). They're knowledgeable and quite friendly + if you can keep them on topic. +
+ Post a question on the forums. Make sure + you've done a search first. When you do post, be sure to include + your setup information (OS, etc) as well as the exact commands + that are failing with the accompanying error. If + there's a SQL error in the TCL error or in the log, + post that too. +
+ If you find errors in this document or if you have ideas about + making it better, please post them in our + BugTracker. +
($Id$)
Prev Home Next
Chapter�2.�Installation Overview Up Prerequisite Software
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.html,v diff -u -N -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 19 Nov 2003 15:44:50 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 11 Dec 2003 23:08:46 -0000 1.5 @@ -1,8 +1,8 @@ Install tclwebtest.
Prev Appendix�B.�Install additional supporting software Next
Install tclwebtest.
Download the tclwebtest source, unpack it, and put it an appropriate - place. As root:
cd /tmp + place. As root:
cd /tmp tar xvzf tclwebtest-0.3.tar.gz mv tclwebtest-0.3 /usr/local/ ln -s /usr/local/tclwebtest-0.3 /usr/local/tclwebtest ln -s /usr/local/tclwebtest/tclwebtest /usr/local/bin -
Prev Home Next
Install nsopenssl Up Appendix�C.�Credits
docs@openacs.org
View comments on this page at openacs.org +
Prev Home Next
Install nsopenssl Up Appendix�C.�Credits
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ix01.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/ix01.html 19 Nov 2003 15:44:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/ix01.html 11 Dec 2003 23:08:46 -0000 1.3 @@ -1,2 +1,2 @@ -Index
Prev
Index
A
AOLserver
configuration, Install from tarball
Automated tests, Write automated tests
C
computeroutput
code, Code
cvs
initializing, Initialize CVS (OPTIONAL)
setup, Add the Service to CVS - OPTIONAL
D
daemontools
installation, Install Daemontools (OPTIONAL)
docbook
installation, Install Red Hat 8/9
DocBook
DTD, Why DocBook?
emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
Document structure, Document Structure
E
emacs
installation, Install Red Hat 8/9
emphasis
bold, italics, Emphasis
F
full text search
installation, Install OpenFTS module, Install OpenFTS prerequisites in PostGreSQL instance
G
Graphics
Images, Graphics
I
informaltable
table, Tables
L
language
installation, Install Red Hat 8/9
Linking, Links
lists, Lists
O
OpenACS Package, What a Package Looks Like
P
photo-album
installation (see ImageMagick)
Postgres
Vacuuming, Install from tarball
Q
qmail
installation, Install qmail (OPTIONAL)
Maildir, Install qmail (OPTIONAL)
rcpthosts error message, Install qmail (OPTIONAL)
S
sect1, Headlines, Sections
sect2, Headlines, Sections
Sections
Headlines, Headlines, Sections
security
definition, Install Red Hat 8/9
firewall, Install Red Hat 8/9
sendmail
removing, Install qmail (OPTIONAL)
service0, Paths and Users
ssh, Install Red Hat 8/9
T
The publish point for new packages should be - fixed., Prepare the package for distribution.
U
ulink, Links
Unicode
in PostGreSQL, Install PostGreSQL
upgrade
OpenACS 4.5 to 4.6
Linux/Unix, Upgrading on Linux/Unix
X
XML guidelines, Why DocBook?
xref
linkend, Links
xreflabel, Headlines, Sections
Prev Home
External Authentication Design Up
docs@openacs.org
View comments on this page at openacs.org +Index
Prev
Index
A
AOLserver
configuration, Install from tarball
Automated tests, Write automated tests
C
computeroutput
code, Code
cvs
initializing, Initialize CVS (OPTIONAL)
setup, Using CVS with an OpenACS Site
D
daemontools
installation, Install Daemontools (OPTIONAL)
docbook
installation, Install Red Hat 8/9
DocBook
DTD, Why DocBook?
emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
Document structure, Document Structure
E
emacs
installation, Install Red Hat 8/9
emphasis
bold, italics, Emphasis
F
full text search
installation, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance
G
Graphics
Images, Graphics
I
informaltable
table, Tables
L
language
installation, Install Red Hat 8/9
Linking, Links
lists, Lists
O
OpenACS Package, What a Package Looks Like
P
photo-album
installation (see ImageMagick)
Postgres
Vacuuming, Install from tarball
Q
qmail
installation, Install qmail (OPTIONAL)
Maildir, Install qmail (OPTIONAL)
rcpthosts error message, Install qmail (OPTIONAL)
S
sect1, Headlines, Sections
sect2, Headlines, Sections
Sections
Headlines, Headlines, Sections
security
definition, Install Red Hat 8/9
firewall, Install Red Hat 8/9
sendmail
removing, Install qmail (OPTIONAL)
service0, Paths and Users
ssh, Install Red Hat 8/9
T
The publish point for new packages should be + fixed., Prepare the package for distribution.
U
ulink, Links
Unicode
in PostgreSQL, Install PostgreSQL
upgrade
OpenACS 4.5 to 4.6
Linux/Unix, Upgrading 4.5 to 4.6
X
XML guidelines, Why DocBook?
xref
linkend, Links
xreflabel, Headlines, Sections
Prev Home
External Authentication Requirements Up
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -N -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 19 Nov 2003 15:44:50 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 11 Dec 2003 23:08:46 -0000 1.19 @@ -1 +1 @@ -Chapter�10.�Kernel Documentation
Prev Part�IV.�For OpenACS Platform Developers Next
Chapter�10.�Kernel Documentation
Table of Contents
Overview
OpenACS 4 Object Model Requirements
OpenACS 4 Object Model Design
OpenACS 4 Permissions Requirements
OpenACS 4 Permissions Design
OpenACS 4 Groups Requirements
OpenACS 4 Groups Design
OpenACS 4 Subsites Requirements
OpenACS 4 Subsites Design Document
OpenACS 5.0.0b1 Package Manager Requirements
OpenACS 5.0.0b1 Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Internationalization
OpenACS 4 Security Requirements
OpenACS 4 Security Design
OpenACS 4 Security Notes
OpenACS 4 Request Processor Requirements
OpenACS 4 Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
External Authentication Design
Prev Home Next
Platform Development Up Overview
docs@openacs.org
View comments on this page at openacs.org +Chapter�11.�Kernel Documentation
Prev Part�IV.�For OpenACS Platform Developers Next
Chapter�11.�Kernel Documentation
Table of Contents
Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Internationalization
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
Prev Home Next
Part�IV.�For OpenACS Platform Developers Up Overview
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -N -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 19 Nov 2003 15:44:50 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 11 Dec 2003 23:08:46 -0000 1.14 @@ -1,4 +1,4 @@ -Overview
Prev Chapter�10.�Kernel Documentation Next

Overview
+Overview
Prev Chapter�11.�Kernel Documentation Next
Overview
The OpenACS Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package @@ -14,13 +14,12 @@ OpenACS 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 + web services built on top of the Kernel and Core. + 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 other packages on this server -
Prev Home Next
Chapter�10.�Kernel Documentation Up OpenACS 4 Object Model Requirements
docs@openacs.org
View comments on this page at openacs.org +
Prev Home Next
Chapter�11.�Kernel Documentation Up Object Model Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ld-id2855573.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ld-id2855573.html,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/ld-id2855573.html 11 Dec 2003 23:08:46 -0000 1.1 @@ -0,0 +1 @@ +Long Description
This is an image of the flow in the Request Processor
Index: openacs-4/packages/acs-core-docs/www/ld-id2890769.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ld-id2890769.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/ld-id2890769.html 11 Dec 2003 21:39:47 -0000 1.2 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1 +0,0 @@ -Long Description
OpenACS without APM vs. with APM
Index: openacs-4/packages/acs-core-docs/www/ld-id2913366.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ld-id2913366.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/ld-id2913366.html 11 Dec 2003 21:39:47 -0000 1.2 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1 +0,0 @@ -Long Description
This is an image of the flow in the Request Processor
Index: openacs-4/packages/acs-core-docs/www/ld-id2918090.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ld-id2918090.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/ld-id2918090.html 19 Nov 2003 15:44:50 -0000 1.1 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1 +0,0 @@ -Long Description
This is an image of the flow in the Request Processor
Index: openacs-4/packages/acs-core-docs/www/ld-id2947100.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ld-id2947100.html,v diff -u -N --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/ld-id2947100.html 11 Dec 2003 23:08:46 -0000 1.1 @@ -0,0 +1 @@ +Long Description
OpenACS without APM vs. with APM
Index: openacs-4/packages/acs-core-docs/www/ld-id2950760.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ld-id2950760.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/ld-id2950760.html 19 Nov 2003 15:44:50 -0000 1.1 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1 +0,0 @@ -Long Description
OpenACS without APM vs. with APM
Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 19 Nov 2003 15:44:50 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 11 Dec 2003 23:08:46 -0000 1.16 @@ -1,7 +1,7 @@ Hosting Web Sites
Prev Chapter�6.�Maintenance Next

Hosting Web Sites
By Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Maintenance tasks, optional software, and alternate configurations for AOLserver.
Keep AOLServer Alive
Assuming AOLserver started cleanly in the previous step, we'll set it up so that it's always running, and automatically restarts whenever it dies or is stopped. This step is strongly recommended, even for development sites, because it makes install and maintenance much simpler.
The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.
Daemontools must already be installed. If not, install it.
Each service controlled by daemontools must have a +
Maintenance tasks, optional software, and alternate configurations for AOLserver.
Keep AOLserver Alive
Assuming AOLserver started cleanly in the previous step, we'll set it up so that it's always running, and automatically restarts whenever it dies or is stopped. This step is strongly recommended, even for development sites, because it makes install and maintenance much simpler.
The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.
Daemontools must already be installed. If not, install it.
Each service controlled by daemontools must have a directory in /service. That directory must have a file called run. Daemontools then @@ -43,18 +43,18 @@ this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately.
Install a script to automate the stopping and starting - of aolserver services via daemontools. You can then restart a service via restart-aolserver service0
[root@yourserver root]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver + of AOLserver services via daemontools. You can then restart a service via restart-aolserver service0
[root@yourserver root]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver [root@yourserver root]# chmod 755 /usr/local/bin/restart-aolserver [root@yourserver root]#
At this point, these commands will work only for the root user. Grant permission for the web group to use svc commands on the service0 server.
[root@yourserver root]# svgroup web /service/service0 [root@yourserver root]#
Verify that the controls work. You may want to tail -f /var/lib/aolserver/service0/log/service0-error.log in another window, so you can see what happens when you type these commands.
- Most of this information comes from Tom Jackson's AOLServer+Daemontools + Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO.
AOLserver keepalive with inittab
This is an alternative method for keeping the AOLserver - process running. The recommended method is to run AOLserver + process running. The recommended method is to run AOLserver supervised.
This step should be completed as root. This can break every service on your machine, so proceed with caution. @@ -145,7 +145,7 @@ automated for startup and shutdown.
Running AOLserver on Port 80
If you want your webserver to be http://yourserver.com, it must run on port 80, the default HTTP port. You set this in the config.tcl file. You will need to start the service as root. If you follow the instructions - above for automating + above for automating startup, this will be taken care of, but if you ever start the server from the command line, be sure to su - first. @@ -159,7 +159,7 @@ able to exploit your web server to execute a command on your server, they would not be able to gain root access.
Running multiple services on one machine
Services on different ports.�To run a different service on another port but the same - ip, simply repeat Install OpenACS 5.0.0b1 replacing + ip, simply repeat Install OpenACS 5.0.0b4 replacing service0, and change the
set httpport 8000 set httpsport 8443
@@ -175,15 +175,15 @@ names sharing the same ip, you'll need nsvhr to redirect requests based on the contents of the tcp headers. See AOLserver Virtual Hosting with TCP by markd. -
Installing SSL Support
nsopenssl is an open-sounce module for Aolserver which +

Installing SSL Support
nsopenssl is an open-sounce module for AOLserver which adds support for the ssl encryption layer. To use it, you must install the software, create or purchase certificates, and configure your OpenACS instance to use it.

Uncomment this line from config.tcl.
#ns_param nsopenssl ${bindir}/nsopenssl.so
Prepare a certificate directory for the service.
[service0@yourserver etc]$ mkdir /var/lib/aolserver/service0/etc/certs [service0@yourserver etc]$ chmod 700 /var/lib/aolserver/service0/etc/certs [service0@yourserver etc]$ -
mkdir /var/lib/aolserver/service0/etc/certs -chmod 700 /var/lib/aolserver/service0/etc/certs
It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
Use an OpenSSL perl script to generate a certificate and key.
[service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc/certs +mkdir /var/lib/aolserver/service0/etc/certs +chmod 700 /var/lib/aolserver/service0/etc/certs

It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
Use an OpenSSL perl script to generate a certificate and key.
[service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc/certs [service0@yourserver certs]$ perl /usr/share/ssl/misc/CA -newcert Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key @@ -211,12 +211,12 @@ [service0@yourserver service0]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg [service0@yourserver service0]$ mkdir www/log [service0@yourserver service0]$ cp -r /usr/share/analog-5.31/images www/log/ -[service0@yourserver service0]$
+[service0@yourserver service0]$ su - service0 cd /var/lib/aolserver/service0 cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg mkdir www/log -cp -r /usr/share/analog-5.31/images www/log/
Edit +cp -r /usr/share/analog-5.31/images www/log/
Edit /var/lib/aolserver/service0/etc/analog.cfg and change the variable in HOSTNAME "[my organisation]" to reflect your website title. If you don't want the traffic log to be publicly visible, change Index: openacs-4/packages/acs-core-docs/www/maintenance.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/maintenance.html,v diff -u -N -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/maintenance.html 19 Nov 2003 15:44:50 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/maintenance.html 11 Dec 2003 23:08:46 -0000 1.10 @@ -1 +1 @@ -Chapter�6.�Maintenance
Prev Part�II.�Administrator's Guide Next
Chapter�6.�Maintenance
Table of Contents
Hosting Web Sites
Database Management
Backup and Recovery
Prev Home Next
Support for upgrades. Up Hosting Web Sites
docs@openacs.org
View comments on this page at openacs.org +Chapter�6.�Maintenance
Prev Part�II.�Administrator's Guide Next
Chapter�6.�Maintenance
Table of Contents
Hosting Web Sites
Database Management
Backup and Recovery
Prev Home Next
Upgrading Up Hosting Web Sites
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/object-identity.html 19 Nov 2003 15:44:50 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 11 Dec 2003 23:08:46 -0000 1.24 @@ -1,18 +1,18 @@ -Object Identity
Prev Chapter�8.�Development Reference Next
Object Identity
By Rafael H. Schloming
+Object Identity
Prev Chapter�8.�Development Reference Next
Object Identity
By Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
One of the major design features of OpenACS 5.0.0b1 is the explicit representation +
One of the major design features of OpenACS 5.0.0b4 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 5.0.0b1 data model this +scope) to identify an object. In the 5.0.0b4 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 5.0.0b1 data model this +object (the person's membership in a group). In the 5.0.0b4 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 @@ -31,4 +31,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.
($Id$)
Prev Home Next
OpenACS 4.x Permissions Tediously Explained Up Programming with AOLserver
docs@openacs.org
View comments on this page at openacs.org +level services.
($Id$)
Prev Home Next
OpenACS Permissions Tediously Explained Up Programming with AOLserver
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 19 Nov 2003 15:44:50 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 11 Dec 2003 23:08:46 -0000 1.18 @@ -1,12 +1,12 @@ -OpenACS 4 Object Model Design
Prev Chapter�10.�Kernel Documentation Next
OpenACS 4 Object Model Design
By Pete Su, Michael Yoon, Richard Li, Rafael Schloming
+Object Model Design
Prev Chapter�11.�Kernel Documentation Next
Object Model Design
By Pete Su, Michael Yoon, Richard Li, Rafael Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Essentials
Data Model
acs-metadata-create.sql
acs-objects-create.sql
-acs-relationships-create.sql
Tcl Files
Not yet linked.
Requirements
Object Model -Requirements
Groups -Requirements
Permissions +acs-relationships-create.sql
Tcl Files
Not yet linked.
Requirements
Object Model +Requirements
Groups +Requirements
Permissions Requirements
Introduction
Before OpenACS 4, software developers writing OpenACS applications or modules would develop each data model separately. However, many applications built on OpenACS share certain characteristics or require certain common services. @@ -32,7 +32,7 @@ object type (e.g. users) to instances of another object type (e.g. groups).

The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.

Related Links

This design document should be read along with the design documents for the new groups system, subsites and the permissions system

History

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

History

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

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 @@ -99,9 +99,9 @@ user X perform action Y on object Z", the OpenACS security model will defer to an object's context if there is no information about user X's permission to perform action Y on object Z.

The context system forms the basis for the rest of the OpenACS access control -system, which is described in in two separate documents: one for the permissions system and another for the -party groups system. The context system -is also used to implement subsites.

Object Types

As mentioned above, many OpenACS modules provide extensible data models, and +system, which is described in in two separate documents: one for the permissions system and another for the +party groups system. The context system +is also used to implement subsites.

Object Types

As mentioned above, many OpenACS modules provide extensible data models, and need to use application specific mechanisms to keep track of user defined attributes and to map application data to these attributes. In the past, modules either used user/groups or their own ad hoc data model to provide @@ -444,7 +444,7 @@ the knowledge level data model to create, manage, query and manipulate objects in a uniform manner. The acs_rels table has an analogous role in storing information on relations.

These are all the tables that we'll discuss in this document. The rest -of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.

Some examples of how these tables are used in the system can be found in +of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.

Some examples of how these tables are used in the system can be found in the discussion of the API, which comes next.

API

Now we'll examine each piece of the API in detail. Bear in mind that the Object Model API is defined primarily through PL/SQL packages.

Object Types and Attributes

The object system provides an API for creating new object types and then attaching attributes to them. The procedures create_type and @@ -567,7 +567,7 @@ automatically be hooked into every generic object service that exists. Better still, this code need not be changed as new services are added. As an aside, the most important service that requires you to subtype -acs_object is permissions.

Objects

The next important piece of the API is defined in the +acs_object is permissions.

Objects

The next important piece of the API is defined in the acs_object package, and is concerned with creating and managing objects. This part of the API is designed to take care of the mundane bookkeeping needed to create objects and query their attributes. @@ -857,4 +857,4 @@ on par with the old user/groups system in a more general way.

Future Improvements/Areas of Likely Change

Nothing here yet.

Authors

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.

Revision History

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 -"OM"	11/07/2000	Pete Su

Prev	Home	Next
OpenACS 4 Object Model Requirements	Up	OpenACS 4 Permissions Requirements

docs@openacs.org

View comments on this page at openacs.org +"OM"11/07/2000Pete Su

OpenACS 4 Object Model Requirements

By Pete Su

+Object Model Requirements

Prev	Chapter�11.�Kernel Documentation	Next

Object Model Requirements

By Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

I. Introduction

A major goal in OpenACS 4 is to unify and normalize many of the core services @@ -201,8 +201,8 @@ developers to represent a hierarchy of object contexts. These contexts are used as the basis for the permissions system. In general, if an 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, +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. That is, contexts can be logically "contained" within other contexts (i.e. contexts have parents) and contexts can contain other contexts @@ -263,4 +263,4 @@ this integrate with application level SQL queries?

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/10/2000	Bryan Quinn
0.2	Major re-write	08/11/2000	Pete Su
0.3	Draft completed after initial reviews	08/22/2000	Pete Su
0.4	Edited, updated to conform to requirements template, pending freeze	08/23/2000	Kai Wu
�	Final edits before freeze	08/24/2000	Pete Su
0.5	Edited for consistency	08/27/2000	Kai Wu
0.6	Put Object ID stuff first, because it makes more sense	08/28/2000	Pete Su
0.7	Added requirement that knowledge-level objects must be moveable between databases.	08/29/2000	Richard Li
0.8	Rewrote intro to match language and concepts in the design document. Also cleaned up usage a bit in the requirements section. Added short vague -requirements on relation types.	09/06/2000	Pete Su
0.9	Edited for ACS 4 Beta release.	09/30/2000	Kai Wu

Prev	Home	Next
Overview	Up	OpenACS 4 Object Model Design

View comments on this page at openacs.org +requirements on relation types.09/06/2000Pete Su0.9Edited for ACS 4 Beta release.09/30/2000Kai Wu

OpenACS Data Models and the Object System

By Pete Su

+OpenACS Data Models and the Object System

Prev	Chapter�8.�Development Reference	Next

OpenACS Data Models and the Object System

By Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Overview

-Developing data models in OpenACS 5.0.0b1 is much like developing data models +Developing data models in OpenACS 5.0.0b4 is much like developing data models for OpenACS 3, save for the implementation. As usual, you need to examine how to model the information that the application must store and manipulate, and define a suitable set of SQL tables. In our Notes @@ -77,8 +77,8 @@

Fire up your text editor and open the ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created -when we created the package. Then, do the following: -

Describe the new type to the type system

+when we created the package. Then, do the following: +

Describe the new type to the type system

First, add an entry to the acs_object_types table with the following PL/SQL call:

 begin  
@@ -138,7 +138,7 @@
 because the new type note is a subtype of
 acs_object, it will inherit these attributes, so there is
 no need for us to define them.
-

Define a table in which to store your objects

The next thing we do is make a small modification to the data model to reflect the fact that each row in the notes table represents something that is not only an object of type @@ -163,7 +163,7 @@ use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of acs_objects. -

Define a package for type specific procedures

The next step is to define a PL/SQL package for your new type, and write some basic procedures to create and delete objects. Here is a package definition for our new type: @@ -211,7 +211,7 @@ object OBJ was "read only", then any other object that used OBJ as its context would also be "read only" by default. We'll talk about this more later. -

Define a package body for type specific procedures

The PL/SQL package body contains the implementations of the procedures defined above. The only subtle thing going on here is that we must use acs_object.new to insert a row into @@ -314,7 +314,7 @@ models that are meant to be integrated with the OpenACS object system.

-There are two basic rules you should follow when designing OpenACS 5.0.0b1 data +There are two basic rules you should follow when designing OpenACS 5.0.0b4 data models: @@ -369,7 +369,7 @@ requires a good amount of thought at design time even for simple applications.

Summary

-Hooking into the OpenACS 5.0.0b1 object system brings the application developer +Hooking into the OpenACS 5.0.0b4 object system brings the application developer numerous benefits, and doing it involves only four easy steps: @@ -393,4 +393,4 @@ especially true for the context_id field.

($Id$)

Prev	Home	Next
OpenACS 5.0.0b1 Packages	Up	The Request Processor

($Id$)

Prev	Home	Next
OpenACS Packages	Up	The Request Processor

+ OpenACS is a collection of pre-built applications and + services that you can use to build your web + site/application. Through a modular architecture, OpenACS + has packages for user/groups management, content + management, e-commerce, news, FAQs, calendar, forums, bug + tracking, full-text searching, and much more. -

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 19 Nov 2003 15:44:50 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 11 Dec 2003 23:08:46 -0000 1.15 @@ -1,55 +1,51 @@ Overview

Prev	Chapter�1.�High level information: What is OpenACS?	Next

Overview

- OpenACS (Open Architecture Community System) is an - advanced toolkit for building scalable, community-oriented - web applications. If you're thinking of building an - enterprise-level web application, OpenACS is a solid, - proven foundation that will give you a 3-6 month - headstart. -

- OpenACS is also a collection of pre-built applications and - services that you can use to build your web - site/application. Through a modular architecture, OpenACS - has packages for user/groups management, content - management, e-commerce, news, FAQ, calendar, forums, bug - tracking, full-text searching, and much + OpenACS (Open Architecture Community System) is an + advanced toolkit for building scalable, community-oriented + web applications. If you're thinking of building an + enterprise-level web application, OpenACS is a solid, + scalable framework for building dynamic content driven + sites. +

- OpenACS relies on AOLserver, the - free, multithreaded, scalable, Tcl-enabled, - web/application server used by America On-Line for most of - its web sites, and a true acid-compliant Relational - Database Management System (RDBMS). Currently OpenACS - supports PostgreSQL, an open source RDBMS, and - Oracle. (read - more) -

- The OpenACS toolkit is based on the ArsDigita Community - System. ArsDigita (now part of Red Hat, Inc.) kindly made - their work available under the GPL, - making all of this possible. -

- “The ArsDigita Community System (ACS) is a toolkit of software - that will help you build Web services with a collaborative dimension, - ranging from knowledge management within companies to B2C ecommerce - to product support and community among the customers. The software is - free and open-source and has been tested in heavy use since - 1995.” - Philip Greenspun +

+ OpenACS relies on AOLserver, the + free, multithreaded, scalable, Tcl-enabled, + web/application server used by America Online for most of + its web sites, and a true ACID-compliant Relational + Database Management System (RDBMS). Currently OpenACS + supports PostgreSQL, an open source RDBMS, and Oracle and + is easily extensible to other databases which support a + comparable feature set. +

+ The OpenACS toolkit is derived from the ArsDigita + Community System (ACS). ArsDigita (now part of Red Hat, + Inc.) kindly made their work available under the GPL, + making all of this possible. +

+ The OpenACS project was born when Don Baccus, Ben Adida, and + others decided to port ACS from Oracle to PostgreSQL, thus + making it a fully open-source solution. With OpenACS 4, + Oracle and PostgreSQL support were combined in one code base + and with OpenACS 5, support for internationalization and + localization has been added. +

+ A vibrant and productive community has sprung up around the + OpenACS software and there are many volunteer contributors + as well as a commercial companies able to provide support, + hosting, and custom development. Many of the production + users are actively funding and contributing work back to the + project. Formal, consensus driven governance has been + established (with semi-annual elections) which ensures the + project serves the needs of it's constituents.

- OpenACS was born when Don Baccus, Ben Adida, et al decided - to port ACS from Oracle to PostgreSQL, thus making it a - fully open-source solution. -

- OpenACS 5.0.0b1 is the next generation of the web toolkit. It's based on - ACS 4, but no longer follows ArsDigita development. Unlike ACS - (which required Oracle) and OpenACS 3.x (which required PostgreSQL), - OpenACS 5.0.0b1 allows you to use either database. It's also built in such - a way to allow enterprising hackers (in the good sense of - the word) to extend it to other databases. Don Baccus leads - the development and numerous developers and non-developers - contribute from around the world. -

- The OpenACS community would like to hear your comments and - help you in your endeavors with the system. Stop by our - web site and feel - free to ask a question, post ideas or whatever. -

Prev	Home	Next
Chapter�1.�High level information: What is OpenACS?	Up	OpenACS Release Notes

View comments on this page at openacs.org + The OpenACS community would like to hear your comments and + can help you in your endeavors with the system. Visit our + web site and feel + free to ask questions or provide feedback. +

Install OpenACS 5.0.0b1

+Install OpenACS 5.0.0b4

Prev	Chapter�3.�Complete Installation	Next

Install OpenACS 5.0.0b4

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Set up the file system for one or more OpenACS Sites

For Linux Standard Base compliance and ease of backup, @@ -10,9 +10,9 @@ [root@yourserver root]# chgrp web /var/lib/aolserver [root@yourserver root]# chmod 770 /var/lib/aolserver [root@yourserver root]# -

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

Set up a user account for each site.

+chmod 770 /var/lib/aolserver

Set up a user account for each site.

AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the command line. It's @@ -71,8 +71,8 @@ tarball and save it in /tmp and proceed:

Unpack the OpenACS tarball and rename it to service0. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.

[root@yourserver root]# su - service0
 [service0@yourserver service0]$ cd /var/lib/aolserver
-[service0@yourserver aolserver]$ tar xzf /tmp/openacs-5.0.0b1.tgz
-[service0@yourserver aolserver]$ mv openacs-5.0.0b1 service0
+[service0@yourserver aolserver]$ tar xzf /tmp/openacs-5.0.0b4.tgz
+[service0@yourserver aolserver]$ mv openacs-5.0.0b4 service0
 [service0@yourserver aolserver]$ chmod -R 700 service0
 [service0@yourserver aolserver]$ ls -al
 total 3
@@ -83,12 +83,12 @@
 logout
 
 [root@yourserver root]#
-su - service0
+su - service0
 cd /var/lib/aolserver
-tar xzf /tmp/openacs-5.0.0b1.tgz
-mv openacs-5.0.0b1 service0
+tar xzf /tmp/openacs-5.0.0b4.tgz
+mv openacs-5.0.0b4 service0
 chmod -R 700 service0/
-exit

Add the Service to CVS (OPTIONAL)
Prepare the database
- Prepare Oracle for OpenACS.�If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service
  +exit
- Add the Service to CVS (OPTIONAL)
- Prepare the database
  - Prepare Oracle for OpenACS.�If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service
    You should be sure that your user account (e.g. service0) is in the dba group. @@ -222,8 +222,8 @@ If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in the section called “Troubleshooting Oracle Dates” -

Prepare PostgreSQL for an OpenACS Service.�

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

Prepare PostgreSQL for an OpenACS Service.�

PostgreSQL:
Create a user in the database matching the service + name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.
```
[root@yourserver root]# su - postgres
 [postgres@yourserver pgsql]$ createuser -a -d service0
 CREATE USER
 [postgres@yourserver pgsql]$ exit
@@ -233,9 +233,9 @@
 [service0@yourserver service0]$ createdb -E UNICODE service0
 CREATE DATABASE
 [service0@yourserver service0]$
-su - service0
-createdb -E UNICODE service0
```
Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.
```
[service0@yourserver service0]$ export EDITOR=emacs;crontab -e
```
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
```
0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0
-0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0
```
Add Full Text Search Support (OPTIONAL)

[service0@yourserver service0]$ exit
+su - service0
+createdb -E UNICODE service0

Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day.
```
[service0@yourserver service0]$ export EDITOR=emacs;crontab -e
```
Add this line to the file. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day.
```
0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0
+0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0
```
Add Full Text Search Support (OPTIONAL)

[service0@yourserver service0]$ exit
 logout
 
 [root@yourserver root]#

Configure an AOLserver Service for OpenACS.�

@@ -245,7 +245,7 @@ need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /var/lib/aolserver/service0/etc/config.tcl. - Open it in an editor to adjust the parameters.

[root@yourserver root]# su - service0
+	   Open it in an editor to adjust the parameters.
[root@yourserver root]# su - service0
 [service0@yourserver service0]$ cd /var/lib/aolserver/service0/etc
 [service0@yourserver etc]# emacs config.tcl
 

@@ -266,19 +266,19 @@
 		  servername - This is just a *pretty* name for your server.

user_account - The account that will both own OpenACS files and connect to the database (for Postgresql).
debug - Set to true for a very verbose error log, including many lines for every page view, success or failure.

- AOLServer is very configurable. These settings should get you - started, but for more options, read the AOLServer + AOLserver is very configurable. These settings should get you + started, but for more options, read the AOLserver docs.

Enable OpenFTS Full Text Search (OPTIONAL)

Install nsopenssl for SSL support. (OPTIONAL)

Verify AOLserver startup.�

Kill any current running AOLserver processes and start a new one. If you are using Oracle, rather than PostgreSQL, replace nsd-postgres with nsd-oracle).
If you want to use port 80, there are complications. - First, Aolserver must be root to use system ports such as + First, AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. Thus you must start as root and specify a non-root user ID and - Group ID which Aolserver will switch to after claiming the + Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the service0 user via grep service0 @@ -292,7 +292,7 @@ [service0@yourserver service0]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file... [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.
Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000
- You should see a page that looks like this. If you imported your files into + You should see a page that looks like this. If you imported your files into cvs, now that you know it worked you can erase the temp directory with rm -rf /var/lib/aolserver/service0.orig.
@@ -306,11 +306,11 @@ permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with killall nsd. -
Automate +
Automate AOLserver keepalive (OPTIONAL)

Configure a Service with the OpenACS Installer.� Now that you've got AOLserver up and running, let's install OpenACS - 5.0.0b1. + 5.0.0b4. You should see a page from the webserver titled OpenACS Installation: @@ -360,16 +360,16 @@ You'll see the final Installer page, "OpenACS Installation: Complete." It will tell you that the server is being restarted; note that unless you already set up a way for - AOLServer to restart itself (ie. inittab or daemontools), + AOLserver to restart itself (ie. inittab or daemontools), you'll need to manually restart your service. [service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/service0/config.tcl Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS - 5.0.0b1 is now up and running! + 5.0.0b4 is now up and running!

Install Oracle 8.1.7

By Vinod Kurup

+Install Oracle 8.1.7

Prev	Chapter�3.�Complete Installation	Next

Install Oracle 8.1.7

By Vinod Kurup

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Note

Skip this section if you're not interested in Oracle.

- OpenACS 5.0.0b1 does not yet work with Oracle 9i + OpenACS 5.0.0b4 does not yet work with Oracle 9i

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

Acquire Oracle 8.1.7 Enterprise Edition

@@ -1219,4 +1219,4 @@ authorized to do a connect internal within svrmgrl to gain full system - access to the Oracle system.

($Id$)

Prev	Home	Next
Install Unix-like system and supporting software	Up	Install PostGreSQL

View comments on this page at openacs.org + access to the Oracle system.

OpenACS 5.0.0b1 Packages

By Pete Su and Bryan Quinn

+OpenACS Packages

Prev	Chapter�8.�Development Reference	Next

OpenACS Packages

By Pete Su and Bryan Quinn

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Overview

@@ -15,7 +15,6 @@ 3.2.x and earlier, a typical server might have a file system behind it that looked something like this:

-
 ROOT/
    bin/
    parameters/
@@ -45,8 +44,7 @@
                 core and application data models here
 
          ... and so on for all modules ... 
-
-

In previous versions of OpenACS, you wrote a new application like this:

Put all Tcl library procedures under server-root/tcl.

Put all User viewable content under @@ -58,9 +56,8 @@ the pieces of each module are strewn all over the tree in at least 3 or 4 different areas.

- Here is how an OpenACS 5.0.0b1 server is laid out: + Here is how an OpenACS 5.0.0b4 server is laid out:

-
 ROOT/
     bin/
     packages/
@@ -79,6 +76,10 @@
         acs-workflow/
         forums/
                forums.info
+               catalog/
+                    i18n message catalogs
+               lib/
+		    includable page fragments (.tcl/.adp pairs)
                sql/
                     oracle/
                          oracle data model
@@ -87,11 +88,11 @@
                tcl/
                     tcl library code
                www/
+                    user visible pages
                     admin/
-                           administration pages
-                    other pages
+                         administration pages
                     doc/
-                          documentation
+                         documentation
         message-catalog/
         news/
         notification/
@@ -100,7 +101,7 @@
             bootstrap code
     www/
             misc pages
-

Note that a major reorganization has happened here. The diagram only expands the structure of the forums/ package directory, but all the others are basically the same. Each package encapsulates @@ -122,7 +123,7 @@ sends to our server to the right page in the appropriate package. While we're at it, this tool should also automate package installation, dependency checking, upgrades, and package - removal. In OpenACS 5.0.0b1, this tool is called the APM. + removal. In OpenACS 5.0.0b4, this tool is called the APM.

The APM

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 @@ -144,7 +145,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 5.0.0b1 that take advantage of the APM's package + management features in OpenACS 5.0.0b4 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. @@ -395,7 +396,7 @@ this point, you should add your package files to your CVS repository. I'll assume that you have set up your development repository according to the standards described in - this appendix. If so, then you just do this: + this appendix. If so, then you just do this:

 
 % cd ROOT/packages
@@ -432,7 +433,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 5.0.0b1, administrators can define an arbitrary mapping between the
+      In OpenACS 5.0.0b4, 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
@@ -447,7 +448,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
@@ -474,7 +475,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.

Summary

The APM performs the following tasks in an OpenACS site:

@@ -490,4 +491,4 @@
Writes out package distribution files for other people to download and install. We'll cover this later. -

Additional Reading

($Id$)

Prev	Home	Next
Chapter�8.�Development Reference	Up	OpenACS Data Models and the Object System

Parties in OpenACS 5.0.0b1

+Parties in OpenACS

Prev	Chapter�8.�Development Reference	Next

Parties in OpenACS

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

While many applications must deal with individuals and many applications @@ -65,7 +65,7 @@ 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 5.0.0b1 data model references the persons or +because wherever possible the OpenACS 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 @@ -297,7 +297,7 @@ 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 5.0.0b1 party +store any extra information relevant to the MENSA community.

Specializing Groups

If one were to build an intranet application on top of the 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. @@ -311,4 +311,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.

($Id$)

Prev	Home	Next
Writing OpenACS 5.0.0b1 Application Pages	Up	OpenACS 4.x Permissions Tediously Explained

View comments on this page at openacs.org +table or the groups table.

($Id$)

OpenACS 4 Permissions Design

By John Prevost and Rafael H. Schloming

+Permissions Design

Prev	Chapter�11.�Kernel Documentation	Next

Permissions Design

By John Prevost and Rafael H. Schloming

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Essentials

Tcl in packages/acs-kernel
OpenACS 4 Permissions Requirements
@@ -182,4 +182,4 @@
Rafael H. Schloming
Documentation author -
John Prevost

Revision History

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

Prev	Home	Next
OpenACS 4 Permissions Requirements	Up	OpenACS 4 Groups Requirements

John Prevost

OpenACS 4 Permissions Requirements

By John McClary Prevost

+Permissions Requirements

Prev	Chapter�11.�Kernel Documentation	Next

Permissions Requirements

By John McClary Prevost

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

This document records requirements for the OpenACS 4 Permissions system, a @@ -87,4 +87,4 @@ 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.

Revision History

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 -freeze.	8/26/2000	Kai Wu
0.4	Edited for ACS 4 Beta release.	10/03/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Object Model Design	Up	OpenACS 4 Permissions Design

View comments on this page at openacs.org +freeze.8/26/2000Kai Wu0.4Edited for ACS 4 Beta release.10/03/2000Kai Wu

OpenACS 4.x Permissions Tediously Explained

+OpenACS Permissions Tediously Explained

Prev	Chapter�8.�Development Reference	Next

OpenACS Permissions Tediously Explained

by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello -

The code has been modified since this document was written so it is now obsolete. See this forum thread.

Overview

- The general permissions system has a relatively complex data model in OpenACS 4.x. +

The code has been modified since this document was written so it is now out of date. See this forum thread.

Overview

+ The general permissions system has a relatively complex data model in OpenACS. Developers who haven't had the time to learn the internals of the data model may end up writing seemingly correct code that crashes their system in weird ways. This writeup is the result of my running into such a piece of code and trying to understand exactly what went wrong. It is geared towards developers who understand the general permissions system to the extent that is described in the - - OpenACS 4.x Permissions documentation, + + OpenACS Permissions documentation, but who haven't had the opportunity to take a long, careful look at the system internals.

@@ -100,7 +100,7 @@

Context Hierarchy

Suppose objects A, B, ..., and F form the following hierarchy. -

Table�8.1.�Context Hierarchy Example

object_id=10

object_id=20 @@ -116,7 +116,7 @@ This can be represented in the acs_objects table by the following entries: -

Table�8.2.�acs_objects example data

object_id	context_id
20	10
30	10
40	20
50	20
60	30

Table�8.2.�acs_objects example data

object_id	context_id
20	10
30	10
40	20
50	20
60	30

The first entry tells us that object 20 is the descendant of object 10, and the third entry shows that object 40 is the descendant of object 20. By running a CONNECT BY query, @@ -689,4 +689,4 @@ container_id from group_member_index; -

Prev	Home	Next
Parties in OpenACS 5.0.0b1	Up	Object Identity

Prev	Home	Next
Parties in OpenACS	Up	Object Identity

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/permissions.html 19 Nov 2003 15:44:51 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/permissions.html 11 Dec 2003 23:08:46 -0000 1.24 @@ -1,8 +1,8 @@ -Groups, Context, Permissions

Prev	Chapter�8.�Development Reference	Next

Groups, Context, Permissions

By Pete Su

+Groups, Context, Permissions

Prev	Chapter�8.�Development Reference	Next

Groups, Context, Permissions

By Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Overview

-The OpenACS 5.0.0b1 Permissions system allows developers and administrators to +The OpenACS 5.0.0b4 Permissions system allows developers and administrators to set access control policies at the object level, that is, any application or system object represented by a row in the acs_objects table can be access-controlled via a simple @@ -13,7 +13,7 @@ Although this may all sound easy and wonderful, no developer or administrator would want to explicitly set access control rights for every user and every object on a -site. Therefore, OpenACS 5.0.0b1 has two auxiliary mechanisms for making this +site. Therefore, OpenACS 5.0.0b4 has two auxiliary mechanisms for making this easier: First, the Groups system allows users to be grouped together in flexible ways. Second, the object model defines a notion of object context, which allows applications to group objects @@ -25,7 +25,7 @@ define simple groupings of users. Each group had a human readable name and unique ID, and there was a single mapping table that mapped users to groups. (The actual data model was more complicated because it -contained a meta-data system much like the OpenACS 5.0.0b1 object type system, +contained a meta-data system much like the OpenACS 5.0.0b4 object type system, but that's not relevant right now.)

The 3.x groups system, while very useful, was limited in few ways. The @@ -47,7 +47,7 @@ member of Greenpeace, its members are not necessarily members of Greenpeace.

-OpenACS 5.0.0b1 solves both of these modeling problems by introducing a new +OpenACS 5.0.0b4 solves both of these modeling problems by introducing a new abstraction called a party. Parties have a recursive definition, and we can illustrate how it works with the following simplified data model. First, we define the parties @@ -113,18 +113,18 @@ already know what parties and objects are, but we don't know what privileges are.

-In OpenACS 5.0.0b1, a privilege models the right to perform some operation on +In OpenACS 5.0.0b4, a privilege models the right to perform some operation on some object. They are the basic units out of which we build access control policies. For example, in the Unix filesystem we typically implement access control by granting users some combination of -read. write or execute privileges on files and directories. In OpenACS 5.0.0b1, +read. write or execute privileges on files and directories. In OpenACS 5.0.0b4, the table of privileges is organized hierarchically so that developers can define privileges that aggregate some set of privileges together. For example, if we have read, write, create and delete privileges, it might be convenient to combine them into a new privilege called "admin". Then if we grant a user this privilege she is automatically granted all the child privileges that the privilege -contains. The OpenACS 5.0.0b1 kernel data model actually defines these +contains. The OpenACS 5.0.0b4 kernel data model actually defines these privileges as follows:

 
@@ -164,7 +164,7 @@
 permissions to large groups of objects in the site, all at once. We
 use contexts to achieve this goal.

Object Context

-In OpenACS 5.0.0b1, an object context is a generalization of the scoping +In OpenACS 5.0.0b4, an object context is a generalization of the scoping mechanism introduced in OpenACS 3.x. "Scoping" and "scope" are terms best explained by example: consider some hypothetical rows in the address_book table: @@ -179,7 +179,7 @@ person or a group of people or the general public (itself a group of people).

-In OpenACS 5.0.0b1, rather than breaking the world into a limited set of scopes, +In OpenACS 5.0.0b4, rather than breaking the world into a limited set of scopes, every object lives in a single context. A context is just an another object that represents the security domain to which the object belongs. By convention, if an object A doesn't have any permissions @@ -196,7 +196,7 @@ application. With only row-level permissions it is not obvious how to reasonably initialize the access control list when creating a message. At best, we have to explicitly grant various read and write -privileges whenever we create a message, which is tedious. In OpenACS 5.0.0b1, +privileges whenever we create a message, which is tedious. In OpenACS 5.0.0b4, a reasonable thing to do is to create an object representing a forum, and point the context_id field of a new message at the forum. Then, suppose we grant every user in the system read-access to @@ -226,21 +226,19 @@

Example

At this point, you should either go and download the Notes example -code from the package repository, or check it out of the ArsDigita CVS +code from the package repository, or check it out of the OpenACS CVS repository and add it to your server. The package is called -"notes". To check it out from CVS, read the these instructions on how to use anonymous checkouts and then -checkout the module acs-packages/notes: +"notes". To check it out from CVS, read the these instructions +on how to use anonymous checkouts and then +checkout the module notes: -

-
-% export CVSROOT=:pserver:anonymous@cvs.arsdigita.com:/usr/local/cvsroot
-% cvs login # the password is acsrules
-% cvs checkout acs-packages/notes
-
+
% export CVSROOT=:pserver:anonymous@openacs.org:/cvsroot
+% cvs login # just hit enter when prompted for a password
+% cvs co notes
 

 After you have downloaded the package, look at the
 index.tcl page in the www directory. You can also
-look at the code in your browser. The code should look something like this:
+look at the code in your browser. The code should look something like this:
 
 
 # main index page for notes.
@@ -304,7 +302,7 @@
 privileges. Also, the WHERE clause of the query ensures that we only
 see notes that we are allowed to see.
 

-Next, look at the index.adp. It is pretty complicated.
+Next, look at the index.adp. It is pretty complicated.
 The main part of this page uses a multiple template
 tag. If you want to experiment, you can replace the main body of the
 multiple tag with this:
@@ -330,7 +328,7 @@
 

 This displays the title of the note as either a link or plain text
 depending on whether or not we have write privileges on the object.
-The if tag is something that the OpenACS 5.0.0b1 template system
+The if tag is something that the OpenACS 5.0.0b4 template system
 defines for you to support conditional presentation. The templates developer guide provides more information about this.
 

 If you study the rest of the system, you will also notice that the
@@ -344,7 +342,7 @@
 permissions to notes that she wanted to make public or whatever. But
 that's beyond the scope of this example.

Summary

-OpenACS 5.0.0b1 defines three separate mechanisms for specifying access control +OpenACS 5.0.0b4 defines three separate mechanisms for specifying access control in applications. The Groups data model allows you to define hierarchical organizations of users and groups of users. The Permissions data model allows you to define a hierarchy of user rights. Finally, @@ -354,4 +352,4 @@

In the next section, we'll look at a more complex page for adding and editing notes, and discuss these issues further. -

($Id$)

Prev	Home	Next
Using Templates in OpenACS 5.0.0b1	Up	Writing OpenACS 5.0.0b1 Application Pages

($Id$)

Prev	Home	Next
Using Templates in OpenACS	Up	Writing OpenACS Application Pages

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/platform-dev.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/platform-dev.html,v diff -u -N --- openacs-4/packages/acs-core-docs/www/platform-dev.html 19 Nov 2003 15:44:51 -0000 1.4 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,3 +0,0 @@ -Platform Development

Prev	Part�IV.�For OpenACS Platform Developers	Next

Platform Development

Information about the internal workings of OpenACS, useful - both for modifying the core functionality and for developing new - packages.

Prev	Home	Next
Part�IV.�For OpenACS Platform Developers	Up	Chapter�10.�Kernel Documentation

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v diff -u -N -r1.22 -r1.23 --- openacs-4/packages/acs-core-docs/www/postgres.html 19 Nov 2003 15:44:51 -0000 1.22 +++ openacs-4/packages/acs-core-docs/www/postgres.html 11 Dec 2003 23:08:46 -0000 1.23 @@ -1,13 +1,13 @@ -Install PostGreSQL

Prev	Chapter�3.�Complete Installation	Next

Install PostGreSQL

+Install PostgreSQL

Prev	Chapter�3.�Complete Installation	Next

Install PostgreSQL

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Skip this section if you will run only Oracle.

OpenACS 5.0.0b1 will run with PostGreSQL 7.2.x, 7.3.2, +

Skip this section if you will run only Oracle.

OpenACS 5.0.0b4 will run with PostgreSQL 7.2.x, 7.3.2, 7.3.3, and 7.3.4. 7.3.4 is the recommended version of PostgreSQL.

Debian.�

Debian users can install the package and add some backwards-compatibility links:

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

and proceed to Tune postgres. (OPTIONAL) or to the - next section.

Using the Red Hat RPM.�Red Hat users: If you install PostGreSQL 7.3.2 from the Red Hat 9 RPM, you + next section.
Using the Red Hat RPM.�Red Hat users: If you install PostgreSQL 7.3.2 from the Red Hat 9 RPM, you can skip a few steps. These shell commands add some links for compatibility with the directories from a source-based install; start the service; create a new group for web service users, and modify the postgres user's environment (more @@ -23,20 +23,20 @@ [root@yourserver root]# groupadd web [root@yourserver root]# su - postgres -bash-2.05b$ -
```
+
 ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib
 ln -s /var/lib/pgsql /usr/local/pgsql
 service postgresql start
 echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile
 echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile
 groupadd web
-su - postgres
```
... and then skip to 6. Something similar may work for other binary packages as well.

Unpack PostGreSQL.�If you have not downloaded the postgresql tarball to +su - postgres
... and then skip to 6. Something similar may work for other binary packages as well.

Unpack PostgreSQL.�If you have not downloaded the postgresql tarball to /tmp/postgresql-7.3.4.tar.gz, get it.

[root@yourserver root]# cd /usr/local/src
 [root@yourserver src]# tar xzf /tmp/postgresql-7.3.4.tar.gz
 [root@yourserver src]# 
-cd /usr/local/src
-tar xzf /tmp/postgresql-7.3.4.tar.gz

Create the Postgres user.� +cd /usr/local/src +tar xzf /tmp/postgresql-7.3.4.tar.gz
Create the Postgres user.� Create a user and group (if you haven't done so before) for PostgreSQL. This is the account that PostgreSQL will run as since it will not run as root. Since nobody will log in @@ -47,16 +47,16 @@ [root@yourserver src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.3.4 [root@yourserver src]# chmod 750 /usr/local/pgsql [root@yourserver src]# -
```
groupadd web
+groupadd web
 useradd -g web -d /usr/local/pgsql postgres
 mkdir -p /usr/local/pgsql
 chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.3.4
-chmod 750 /usr/local/pgsql
```
Set up postgres's environment variables.�They are necessary for the executable to find its supporting +chmod 750 /usr/local/pgsql

Set up postgres's environment variables.�They are necessary for the executable to find its supporting libraries. For convenience, we'll simply append the necessary lines to the postgres shell config file.

[root@yourserver src]# echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc
 [root@yourserver src]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc
-echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc
-echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc

Test this by logging in as +echo "export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib" >> ~postgres/.bashrc +echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bashrc

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

[root@yourserver src]# su - postgres
 [postgres@yourserver pgsql]$ env | grep PATH
@@ -67,7 +67,7 @@
 	  Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can
 	  configure PostgreSQL in various ways. For example, if you want to
 	  enable
-	  Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
+	  Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
 	
[root@yourserver src]# su - postgres
 [postgres@yourserver pgsql]$ cd /usr/local/src/postgresql-7.3.4
 [postgres@yourserver postgresql-7.3.4]$ ./configure
@@ -88,11 +88,11 @@
 (many lines omitted)
 Thank you for choosing PostgreSQL, the most advanced open source database
 engine.
-su - postgres
+su - postgres
 cd /usr/local/src/postgresql-7.3.4
 ./configure
 make all
-make install

Start PostgreSQL.� +make install
Start PostgreSQL.� The initdb command initializes the database. pg_ctl is used to start up PostgreSQL. @@ -105,8 +105,8 @@ [postgres@yourserver tsearch]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start postmaster successfully started [postgres@yourserver tsearch]$ -
```
/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data
-/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
```
+/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
PostgreSQL errors will be logged in /usr/local/pgsql/data/server.log
Install Pl/pgSQL.�Set up plpgsq and allow your user to have @@ -122,8 +122,8 @@ (1 row) [postgres@yourserver pgsql]$ -
```
createlang plpgsql template1
-createlang -l template1
```
Test PostgreSQL (OPTIONAL).�Create a database and try some simple commands. The output should be as shown. +createlang plpgsql template1 +createlang -l template1

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

[postgres@yourserver pgsql]$ createdb mytestdb
 CREATE DATABASE
 [postgres@yourserver pgsql]$ psql mytestdb
@@ -164,13 +164,13 @@
         state. Red Hat and Debian and SuSE each work a little
         differently.
 	
Red Hat RPM:
The init script is already installed; just turn it on for the appropriate run levels.
[root@yourserver root]# chkconfig --level 345 postgresql on
-[root@yourserver root]# 
Red Hat from source:
[root@yourserver src]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+[root@yourserver root]# 
Red Hat from source:
[root@yourserver src]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 [root@yourserver src]# chown root.root /etc/rc.d/init.d/postgresql
 [root@yourserver src]# chmod 755 /etc/rc.d/init.d/postgresql
 [root@yourserver src]# 
-cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 chown root.root /etc/rc.d/init.d/postgresql
-chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root@yourserver root]# service postgresql stop
+chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root@yourserver root]# service postgresql stop
 Stopping PostgreSQL: ok
 [root@yourserver root]# 
If PostgreSQL successfully stopped, then use the following
 		  command to make sure that the script is run appropriately at boot
@@ -184,16 +184,16 @@
 [root@yourserver root]# service postgresql start
 Starting PostgreSQL: ok
 [root@yourserver root]#
-
chkconfig --add postgresql
+chkconfig --add postgresql
 chkconfig --level 345 postgresql on
 chkconfig --list postgresql
-service postgresql start

Debian:

root:~# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+service postgresql start

Debian:

root:~# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 root:~# chown root.root /etc/init.d/postgresql
 root:~# chmod 755 /etc/init.d/postgresql
-root:~# 
-cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
+root:~# 
+cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql
 chown root.root /etc/init.d/postgresql
-chmod 755 /etc/init.d/postgresql

Test the script

root:~# /etc/init.d/postgresql stop
+chmod 755 /etc/init.d/postgresql

Test the script

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

If PostgreSQL successfully stopped, then use the following command to make sure that the script is run @@ -219,7 +219,7 @@ rc.d/ part in each of the following commands. -

root:~# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql +

root:~# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql
 root:~# chown root.root /etc/rc.d/init.d/postgresql
 root:~# chmod 755 /etc/rc.d/init.d/postgresql

@@ -261,12 +261,12 @@ start on runlevel 2 unless you alter the above commands a little. This usually isn't a problem as Red Hat defaults to runlevel 3) -

Tune postgres. (OPTIONAL).�The default values for PostGreSQL are very conservative; we can safely change some of them and improve performance.

Change the kernel parameter for maximum shared memory +
Tune postgres. (OPTIONAL).�The default values for PostgreSQL are very conservative; we can safely change some of them and improve performance.
1. Change the kernel parameter for maximum shared memory segment size to 128Mb:
```
[root@yourserver root]# echo 134217728 >/proc/sys/kernel/shmmax
 [root@yourserver root]#
```
  Make that change permanent by editing /etc/sysctl.conf to add these lines at the end:
```
# increase shared memory limit for postgres
-kernel.shmmax = 134217728
```
2. Edit the PostGreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory. These values should improve performance in most cases. (more information)
```
#       Shared Memory Size
+kernel.shmmax = 134217728
```
3. Edit the PostgreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory. These values should improve performance in most cases. (more information)
```
#       Shared Memory Size
 #
 shared_buffers = 15200      # 2*max_connections, min 16
 
@@ -278,7 +278,7 @@
 #       Write-ahead log (WAL)
 #
 checkpoint_segments = 3     # in logfile segments (16MB each), min 1
-
```
  Restart postgres (service postgres restart) so that the changes take effect.

Programming with AOLserver

By Michael Yoon, Jon Salz and Lars Pind.

+Programming with AOLserver

Prev	Chapter�8.�Development Reference	Next

Programming with AOLserver

By Michael Yoon, Jon Salz and Lars Pind.

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

The `global` command

@@ -39,7 +39,7 @@ which runs frequently, don't use the -thread switch.

Note also that thread is initialized with a copy of what was installed during server startup, so if the procedure table have changed since -startup (e.g. using the APM watch +startup (e.g. using the APM watch facility), that will not be reflected in the scheduled thread.

Using `return`

The return command in Tcl returns control to the caller procedure. @@ -209,4 +209,4 @@ perform lookup by name, they perform a linear lookup, whereas arrays use a hash table, so ns_sets are slower than arrays when the number of entries is large. -

($Id$)

Prev	Home	Next
Object Identity	Up	Chapter�9.�Engineering Standards

($Id$)

Prev	Home	Next
Object Identity	Up	Using HTML Forms

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 19 Nov 2003 15:44:51 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 11 Dec 2003 23:08:46 -0000 1.15 @@ -1,8 +1,8 @@ -Add PSGML commands to emacs init file (OPTIONAL)

Prev	Appendix�B.�Install additional supporting software	Next

Add PSGML commands to emacs init file (OPTIONAL)

+Add PSGML commands to emacs init file (OPTIONAL)

Prev	Appendix�B.�Install additional supporting software	Next

Add PSGML commands to emacs init file (OPTIONAL)

If you plan to write or edit any documentation with emacs, install a customized emacs configuration file with DocBook commands in the skeleton directory, so it will be used for all new users. The file also fixes the backspace -> help mis-mapping that often occurs in - terminals.

[root@yourserver tmp]# cp /tmp/openacs-5.0.0b1/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs + terminals.

[root@yourserver tmp]# cp /tmp/openacs-5.0.0b4/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs
 cp: overwrite `/etc/skel/.emacs'? y
-[root@yourserver tmp]#

Debian users:

apt-get install psgml

Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For debian, apt-get install nxml.

Prev	Home	Next
Initialize CVS (OPTIONAL)	Up	Install Daemontools (OPTIONAL)

View comments on this page at openacs.org +[root@yourserver tmp]#

Debian users:

apt-get install psgml

Prev	Home	Next
Initialize CVS (OPTIONAL)	Up	Install Daemontools (OPTIONAL)

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 19 Nov 2003 15:44:51 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 11 Dec 2003 23:08:46 -0000 1.24 @@ -1,4 +1,4 @@ -Using PSGML mode in Emacs

Prev	Chapter�9.�Engineering Standards	Next

Using PSGML mode in Emacs

By David Lutterkort

+Using PSGML mode in Emacs

Prev	Chapter�10.�Documentation Standards	Next

Using PSGML mode in Emacs

By David Lutterkort

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

What it is

PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It @@ -82,4 +82,4 @@ element is a sect1.

How to use it

Of course, you should read the emacs texinfo pages that come with PSGML mode from start to finish. Barring that, here are some handy commands:

Key	Command
`C-c C-e`	Insert an element. Uses completion and only lets you insert elements that are valid
`C-c C-a`	Edit attributes of enclosing element.
`C-c C-x C-i`	Show information about the document's DTD.
`C-c C-x C-e`	Describe element. Shows for one element which elements can be parents, -what its contents can be and lists its attributes.

OpenACS Release Notes

Version 5.0.0 beta1

- This is the first beta release of OpenACS 5.0.0. This - release has a number of serious bugs, and is not suitable for +OpenACS Release Notes

Prev	Chapter�1.�High level information: What is OpenACS?	Next

OpenACS Release Notes

Version 5.0.0 beta

+ This is the second beta release of OpenACS 5.0.0 (tagged as oacs-5-0-0b4). This + release may still have a number of serious bugs, and is not suitable for production systems. It has passed several release criteria, including that it installs successfully, that all automated tests succeed, and that there are no known severity 1 @@ -12,7 +12,7 @@

You may want to begin by reading our installation documentation for the section called “a Unix-like system”. Note that the Windows documentation is - not current for OpenACS 5.0.0b1, but an alternative is to use John + not current for OpenACS 5.0.0b4, but an alternative is to use John Sequeira's Oasis VM project.

@@ -84,4 +84,13 @@ Who's online feature.

Spell checking. -

($Id$)

Prev	Home	Next
Overview	Up	Part�II.�Administrator's Guide

+ Potential incompatibilities: +

+ The undocumented special handling of ~ and +variable+ in formtemplates has been removed in favor of + using <noparse> and \@variable\@ (the standard templating mechanisms). Locally + provided formtemplate styles still using these mechanisms will break. +
+ Serving backup files and files from the CVS directories is turned off by default via the acs-kernel parameter + ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~") +

($Id$)

Version 4.6.3

Release Notes for 4.6.3

Version 4.6.2

Release Notes for 4.6.2

Version 4.6

Release Notes for 4.6

Version 4.5

Release Notes for 4.5

Prev	Home	Next
Overview	Up	Part�II.�Administrator's Guide

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/releasing-openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/releasing-openacs.html 19 Nov 2003 15:44:51 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs.html 11 Dec 2003 23:08:47 -0000 1.8 @@ -1,50 +1,49 @@ -Appendix�E.�How to package and release OpenACS

Prev	Part�III.�For OpenACS Package Developers	Next

Appendix�E.�How to package and release OpenACS

Check out the cvs tree. The files must be checked out - through a cvs account with write access. In this example, the - cvs user on openacs.org is implied from the ssh login information - previously set up. It could be overridden via foobar@openacs.org.

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

Repeat with the dotlrn cvs tree.

-cd /tmp
+Appendix�E.�How to package and release OpenACSPrev Part�III.�For OpenACS Package Developers  Next
Appendix�E.�How to package and release OpenACS
update the version number in
+          packages/acs-core-docs/www/xml/variables.ent, readme.txt,
+          and all core .info files.  Regenerate the html documentation
+          and commit all the changes.  Update the information in the
+          packages/acs-core-docs/www/xml/for-everyone/release-notes.xml
+          file.
+        
Check out the whole cvs tree.  The files must be checked
+        out through a cvs account with write access and should be a
+        checkout from the release branch.  In this example, the cvs
+        user on openacs.org is implied from the ssh login information
+        previously set up.  It could be overridden via
+        foobar@openacs.org. 
cd /var/tmp
+cvs -d /cvsroot checkout -r oacs-5-0 openacs-4
+
Repeat with the dotlrn cvs tree.
cd /var/tmp
 mkdir dotlrn-packages
 cd dotlrn-packages
-cvs -d :pserver:anonymous@dotlrn@openacs.org:/dotlrn-cvsroot checkout dotlrn-all
-

Tag the tree.


-cd /tmp/openacs-4
-cvs tag openacs-5-0-0a1
-

Tag dotLRN. Since the dotLRN packages aren't all in one module, we iterate through all of the modules. Log in first (cvs login) so that you don't have to log in for each module.


-cd /tmp/dotlrn-packages
-for dir in $(ls); do cd $dir; cvs tag dotlrn-2-0-0a3; cd ..; done
-

Make the tarball

openacs-core.�

Go to a new working space and export the tagged files.

-mkdir /tmp/tarball
-cd /tmp/tarball
-cvs -d :pserver:anonymous@openacs.org:/cvsroot export -r openacs-5-0-0a1 -d openacs acs-core
-

Generate the tarball


-cd /tmp/tarball
-rm -rf /tmp/tarball/openacs/CVS
-tar cz -f openacs-5.0.0a1.tar.gz openacs
-

dotlrn.�

Go to a new working space and export the tagged +cvs -d /dotlrn-cvsroot checkout -r dotlrn-2-0 dotlrn-all +
Tag the tree.
```
cd /var/tmp/openacs-4
+cvs tag -F openacs-5-0-0a1
+
```
Tag dotLRN. Since the dotLRN packages aren't all in one module, we iterate through all of the modules. Log in first (cvs login) so that you don't have to log in for each module.
```
cd /var/tmp/dotlrn-packages
+for dir in *; do ( cd $dir && cvs tag -F dotlrn-2-0-0a1 ); done
+
```

Make the tarball

openacs-core.�

Go to a new working space and export the tagged files.

mkdir /var/tmp/tarball
+cd /var/tmp/tarball
+cvs -d :pserver:anonymous@openacs.org:/cvsroot export -r openacs-5-0-0a1 acs-core
+mv openacs-4 openacs
+

Generate the tarball

cd /var/tmp/tarball
+mv openacs openacs-5.0.0a1
+tar cz -f openacs-5.0.0a1.tar.gz openacs-5.0.0a1
+

dotlrn.�

Go to a new working space and export the tagged files. (was getting errors here trying to use -d, so gave up and just moved things from openacs-4 to - openacs at the end)

-mkdir /tmp/dotlrn-tarball
-cd /tmp/dotlrn-tarball
+                openacs at the end)
mkdir /var/tmp/dotlrn-tarball
+cd /var/tmp/dotlrn-tarball
 cvs -d :pserver:anonymous@openacs.org:/cvsroot export \
   -r openacs-5-0-0a1 acs-core
-cd /tmp/dotlrn-tarball/openacs-4/packages
+cd /var/tmp/dotlrn-tarball/openacs-4/packages
 cvs -d :pserver:anonymous@openacs.org:/cvsroot export \
   -r openacs-5-0-0a1 dotlrn-prereq
 cvs -d :pserver:anonymous@dotlrn.openacs.org:/dotlrn-cvsroot export \
   -r dotlrn-2-0-0a1 dotlrn-core
-cd /tmp/dotlrn-tarball
+cd /var/tmp/dotlrn-tarball
 mv openacs-4 openacs
-

Copy the dotlrn install.xml file, which controls +

Copy the dotlrn install.xml file, which controls which packages are installed on setup, to the root - location:


-cp /tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml /tmp/dotlrn-tarball/openacs
-

Generate the tarball


-cd /tmp/tarball
-rm -rf /tmp/tarball/openacs-4/CVS
-tar cz -f dotlrn-2.0.0a1.tar.gz openacs
-

Test the new tarball
Update on the site

Prev	Home	Next
Add the Service to CVS - OPTIONAL	Up	Part�IV.�For OpenACS Platform Developers

View comments on this page at openacs.org + location:

cp /var/tmp/dotlrn-tarball/openacs/packages/dotlrn/install.xml /var/tmp/dotlrn-tarball/openacs
+

Generate the tarball

cd /var/tmp/tarball
+mv openacs dotlrn-2.0.0a1
+tar cz -f dotlrn-2.0.0a1.tar.gz dotlrn-2.0.0a1
+

Test the new tarball

Update on the site

Prev	Home	Next
Appendix�D.�Using CVS with an OpenACS Site	Up	Part�IV.�For OpenACS Platform Developers

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/request-processor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/request-processor.html 19 Nov 2003 15:44:51 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/request-processor.html 11 Dec 2003 23:08:47 -0000 1.24 @@ -2,16 +2,16 @@ OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Overview

-This document is a brief introduction to the OpenACS 5.0.0b1 Request Processor; +This document is a brief introduction to the OpenACS 5.0.0b4 Request Processor; more details can be found in the OpenACS 4 Request Processor Design. Here we cover the high level concepts behind the system, and implications and usage for the application developer.

Request Processor

-The 5.0.0b1 Request Processor is a global filter and set of Tcl procs that +The 5.0.0b4 Request Processor is a global filter and set of Tcl procs that respond to every incoming URL reaching the server. The following diagram summarizes the stages of the request processor assuming a URL request like http://someserver.com/notes/somepage.adp. -

[D]

Stage 1: Search Site Map

The first thing the RP does is to map the given URL to the appropriate @@ -24,18 +24,18 @@ of the object it found, and the package and package instance the object belongs to into the environment of the connection. This environment can be queried using the ad_conn procedure, -which is described in detail in OpenACS 4 Request Processor Design. The page +which is described in detail in OpenACS 4 Request Processor Design. The page development tutorial shows you how to use this interface to make your pages aware of which instance was requested.

Stage 2: Authentication

Next, the Request Processor examines the request for session information. Session information is generally sent from the client -(the user's browser) to the server via cookies. The security/session handler is described in +(the user's browser) to the server via cookies. The security/session handler is described in detail in its own document. It examines the client request and either extracts or sets up new session tokens for the user.

Stage 3: Authorization

Next, the Request Processor checks if the user has appropriate access -privileges to the requested part of the site. In OpenACS 5.0.0b1, access control +privileges to the requested part of the site. In OpenACS 5.0.0b4, access control is dictated by the permissions system. In this case, the RP checks if the user has "read" priviledges on the object in the site map specified by the URL. This object is typically Index: openacs-4/packages/acs-core-docs/www/requirements-template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 19 Nov 2003 15:44:51 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 11 Dec 2003 23:08:47 -0000 1.24 @@ -1,4 +1,4 @@ -System/Application Requirements Template

Prev	Chapter�9.�Engineering Standards	Next

System/Application Requirements Template

By You

+System/Application Requirements Template

Prev	Chapter�10.�Documentation Standards	Next

System/Application Requirements Template

By You

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

@@ -60,7 +60,7 @@

For guidelines writing requirements, take a look - at the quality standards, along with a good example, such as OpenACS 5.0.0b1 Package Manager Requirements. + at the quality standards, along with a good example, such as Package Manager Requirements.

Besides writing requirements in natural language, consider using the following techniques as needed: @@ -80,4 +80,4 @@ pre-existing system or prototype first, and thus you may want to write some thoughts on implementation, for aiding and guiding yourself or other programmers. -

Revision History

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	Created	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Detailed Design Documentation Template	Up	Release Version Numbering

Revision History

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	Created	8/21/2000	Josh Finkler, Audrey McLoghlin

($Id$)

Prev	Home	Next
Detailed Design Documentation Template	Up	Appendix�D.�Using CVS with an OpenACS Site

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/rp-design.html 19 Nov 2003 15:44:51 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 11 Dec 2003 23:08:47 -0000 1.18 @@ -1,4 +1,4 @@ -OpenACS 4 Request Processor Design

Prev	Chapter�10.�Kernel Documentation	Next

OpenACS 4 Request Processor Design

+Request Processor Design

Prev	Chapter�11.�Kernel Documentation	Next

Request Processor Design

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Essentials

Related Systems

OpenACS 5.0.0b1 Package Manager Design

Terminology

+provides to the browser.

Related Systems

Package Manager Design

Terminology

pageroot -- Any directory that contains scripts and/or static files intended to be served in response to HTTP requests. A typical OpenACS installation is required to serve files from multiple pageroots.
global pageroot @@ -97,4 +97,4 @@ blank

[ad_conn sec_validated] This becomes "secure" when the connection uses SSL

�

Database API

[ad_conn db,handles] What are the list of handles available to AOL?

[ad_conn db,n_handles_used] How many database handles are currently used?

[ad_conn db,last_used] Which database handle did we use last?

[ad_conn db,transaction_level,$db] Specifies what transaction level we are in

[ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted

�

APM

[ad_conn xml_loaded_p] Checks whether the XML parser is loaded so that it only gets loaded once. Set in apm_load_xml_packages

�

Packages

[ad_conn package_id] The package_id of the package associated with the URL.

[ad_conn package_url] The URL on which the package is mounted.

�

Miscellaneous

[ad_conn system_p] If true then the request has been made to one of the special directories specified in the config file (somewhere), and no authentication or -authorization has been performed.

�

Documentation

[ad_conn api_page_documentation_mode_p] �

Prev	Home	Next
OpenACS 4 Request Processor Requirements	Up	Documenting Tcl Files: Page Contracts and Libraries

View comments on this page at openacs.org +authorization has been performed.�Documentation[ad_conn api_page_documentation_mode_p]�

OpenACS 4 Request Processor Requirements

+Request Processor Requirements

Prev	Chapter�11.�Kernel Documentation	Next

Request Processor Requirements

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

The following is a requirements document for the OpenACS 4.0 request @@ -22,4 +22,4 @@ or state associated with a pageroot based on it's location within the URL space.

30.0 Authentication

30.10 The request processor must be able to verify that the connecting browser actually represents the party it claims to represent.

40.0 Authorization

40.10 The request processor must be able to verify that the party the -connecting browser represents is allowed to make the request.

50.0 Scalability

Prev	Home	Next
OpenACS 4 Security Notes	Up	OpenACS 4 Request Processor Design

View comments on this page at openacs.org +connecting browser represents is allowed to make the request.

OpenACS 4 Security Design

By Richard Li and Archit Shah

+Security Design

Prev	Chapter�11.�Kernel Documentation	Next

Security Design

By Richard Li and Archit Shah

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Essentials

OpenACS 4 Security Requirements

Introduction

@@ -347,4 +347,4 @@ chosen from the cache to be used is chosen by a call to ns_rand.

ad_secure_conn_p As discussed above, the security of the secure sessions authentication system is -dependent upon this function.

Prev	Home	Next
OpenACS 4 Security Requirements	Up	OpenACS 4 Security Notes

View comments on this page at openacs.org +dependent upon this function.

OpenACS 4 Security Notes

By Richard Li

+Security Notes

Prev	Chapter�11.�Kernel Documentation	Next

Security Notes

By Richard Li

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

@@ -54,4 +54,4 @@ The set of string match expressions in the procedure above should be extended appropriately for other registration pages. This procedure does not use ad_parameter or regular expressions for performance reasons, as -it is called by the request processor.

($Id$)

Prev	Home	Next
OpenACS 4 Security Design	Up	OpenACS 4 Request Processor Requirements

View comments on this page at openacs.org +it is called by the request processor.

($Id$)

OpenACS 4 Security Requirements

By Richard Li

+Security Requirements

Prev	Chapter�11.�Kernel Documentation	Next

Security Requirements

By Richard Li

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

@@ -43,4 +43,4 @@ AOLserver for each step of the login process (e.g., by a load balancer).

12.4 Secure The security system should not store passwords in clear text in the database.

13.0 SSL Hardware The system must work when the SSL processing occurs outside of the web server (in specialized hardware, in a -firewall, etc.).

Prev	Home	Next
Internationalization	Up	OpenACS 4 Security Design

View comments on this page at openacs.org +firewall, etc.).

OpenACS 4 Subsites Design Document

+Subsites Design Document

Prev	Chapter�11.�Kernel Documentation	Next

Subsites Design Document

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

*Note* This document has not gone through the any of the @@ -208,4 +208,4 @@ a particular configuration of site nodes/packages. As we build more fundamental applications that can be applied in more general areas, this feature will become more and more in demand since more problems will be -solvable by configuration instead of coding.

Authors

rhs@mit.edu

Prev	Home	Next
OpenACS 4 Subsites Requirements	Up	OpenACS 5.0.0b1 Package Manager Requirements

docs@openacs.org

View comments on this page at openacs.org +solvable by configuration instead of coding.

OpenACS 4 Subsites Requirements

By Rafael H. Schloming and Dennis Gregorovic

+Subsites Requirements

Prev	Chapter�11.�Kernel Documentation	Next

Subsites Requirements

By Rafael H. Schloming and Dennis Gregorovic

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Introduction

The following is a requirements document for OpenACS 4 Subsites, part of the @@ -14,7 +14,7 @@ subcommunity.

System Overview

The OpenACS subsite system allows a single OpenACS installation to serve multiple communities. At an implementation level this is primarily accomplished by having an application "scope" its content to a particular package -instance. The request +instance. The request processor then figures out which package_id a particular URL references and then provides this information through the ad_conn api ([ad_conn package_id], [ad_conn package_url]).

The other piece of the subsite system is a subsite package that provides @@ -53,4 +53,4 @@ package and make it available at a URL underneath the subsite.

20.20.0 Package deactivation

20.20.1 The administrator should be able to deactivate any package, causing it to be inaccessible to users.

20.20.5 Deactivating a package makes the package no longer accessible, but it does not remove data created within the context of -that package.

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/18/2000	Dennis Gregorovic
0.2	Edited, reviewed	08/29/2000	Kai Wu

Prev	Home	Next
OpenACS 4 Groups Design	Up	OpenACS 4 Subsites Design Document

View comments on this page at openacs.org +that package.

Writing OpenACS 5.0.0b1 Application Pages

By Rafael H. Schloming and Pete Su

+Writing OpenACS Application Pages

Prev	Chapter�8.�Development Reference	Next

Writing OpenACS Application Pages

By Rafael H. Schloming and Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Overview

In this document, we'll examine the user interface pages of the Notes application in more detail, covering two separate aspects of page -development in OpenACS 5.0.0b1. First, we'll talk about the code needed to make +development in OpenACS. First, we'll talk about the code needed to make your pages aware of which application instance they are running in. Second, we'll talk about using the form builder to develop -form-based user interfaces in OpenACS 5.0.0b1. While these seem like unrelated +form-based user interfaces in OpenACS. While these seem like unrelated topics, they both come up in the example page that we are going to look at, so it makes sense to address them at the same time.

Application Instances and Subsites

-As you will recall from the packages tutorial, the Request -Processor (RP) and Package Manager (APM) in OpenACS 5.0.0b1 allow site +As you will recall from the packages tutorial, the Request +Processor (RP) and Package Manager (APM) allow site administrators to define an arbitrary mapping from URLs in the site to objects representing content. These objects may represent single files, or entire applications. The APM uses the site map to map @@ -253,15 +253,15 @@ visible to that user. The end result is a site where users can come and write notes to themselves.

-This is a good example of the leverage available in the OpenACS 5.0.0b1 +This is a good example of the leverage available in the OpenACS 5.0.0b4 system. The code that we have written for Notes is not at all more complex than a similar application without access control or site map awareness. By adding a small amount of code, we have taken a small, simple, and special purpose application to something that has the potential to be a very useful, general-purpose tool, complete with multi-user features, access control, and centralized administration.

Summary

-In OpenACS 5.0.0b1, application pages and scripts can be aware of the package +In OpenACS 5.0.0b4, application pages and scripts can be aware of the package instance, or subsite in which they are executing. This is a powerful general purpose mechanism that can be used to structure web services in very flexible ways. @@ -273,4 +273,4 @@

We also saw how to use the templating system's forms API in a simple way, to create forms based pages with minimal duplication of code. -

($Id$)

Prev	Home	Next
Groups, Context, Permissions	Up	Parties in OpenACS 5.0.0b1

A @cvs-id tag containing the page's CVS identification string. Just use $Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will -substitute an appropriate string when you check the file in.

($Id$)

Documenting Tcl Files: Page Contracts and Libraries

By Jon Salz on 3 July 2000

+Documenting Tcl Files: Page Contracts and Libraries

Prev	Chapter�11.�Kernel Documentation	Next

Documenting Tcl Files: Page Contracts and Libraries

By Jon Salz on 3 July 2000

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl

The Big Picture

In versions of the OpenACS prior to 3.4, the standard @@ -184,4 +184,4 @@ script was first created.

($Id$)

Prev	Home	Next
OpenACS 4 Request Processor Design	Up	Bootstrapping OpenACS

View comments on this page at openacs.org +substitute an appropriate string when you check the file in.

Using Templates in OpenACS 5.0.0b1

By Pete Su

+Using Templates in OpenACS

Prev	Chapter�8.�Development Reference	Next

Using Templates in OpenACS

By Pete Su

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.

Overview

-The OpenACS 5.0.0b1 Template System (ATS) is designed to allow developers to +The OpenACS Template System (ATS) is designed to allow developers to cleanly separate application logic from display logic. The intent is to have all of the logic related to manipulating the database and other application state data in one @@ -159,7 +159,7 @@

Summary

Templates separate application logic from display logic by requiring the developer to write pages in two stages, one file for database -queries and application logic, and another for display. In OpenACS 5.0.0b1, the +queries and application logic, and another for display. In OpenACS, the logic part of the page is just a .tcl that sets up data sources that are used by the display part of the page. The display part of the page is an .adp file with some Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 19 Nov 2003 15:44:51 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 11 Dec 2003 23:08:47 -0000 1.16 @@ -1,15 +1,15 @@ Advanced Topics

Prev	Chapter�7.�Development Tutorial	Next

Advanced Topics

Important

This section is a work in progress.

by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Overview

This tutorial covers topics which are not essential to +

Overview

This tutorial covers topics which are not essential to creating a minimal working package. Each section can be used independently of all of the others; all sections assume that you've completed the basic tutorial.

How to enforce security so that users can't change other users records
How to use the content management tables so that ... what?
How to change the default stylesheets for Form Builder HTML forms.
How to make your package searchable with OpenFTS/Oracle
How to make your package send email notifications
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
How to add general_comments to your pages
More on ad_form - data validation, other stuff. (plan to draw from Jon Griffin's doc)
How and when to implement caching
partialquery in xql
How to use the html/text entry widget to get the - "does this look right" confirm page
APM package dependencies

Write the Requirements and Design Specs

It's time to document. For the tutorial we'll use + "does this look right" confirm page

APM package dependencies

Write the Requirements and Design Specs

It's time to document. For the tutorial we'll use pre-written documentation. When creating a package from scratch, start by copying the documentation template from /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml @@ -59,7 +59,7 @@ Writing bi01.html for bibliography Writing index.html for book [service0@yourserver xml]$

Verify that the documentation was generated and reflects - your changes by browsing to http://yoursite:8000/samplenote/doc

Add the new package to CVS

Before you do any more work, make sure that your work is + your changes by browsing to http://yoursite:8000/samplenote/doc

Add the new package to CVS

Before you do any more work, make sure that your work is protected by putting it all into cvs. The cvs add command is not recursive, so you'll have to traverse the directory tree manually and add as you go. (More on @@ -119,7 +119,7 @@ initial revision: 1.1 done (many lines omitted) -[service0@yourserver samplenote]$

Delete with confirmation

We need a way to delete records. We'll create a +[service0@yourserver samplenote]$

Delete with confirmation

We need a way to delete records. We'll create a recursive confirmation page.

Add this column to the table_def in index.tcl

{delete "" {} {<td><a href="note-delete?note_id=$note_id">Delete</a></td>}}

Create the delete confirmation/execution page.

[service0@yourserver www]$ emacs note-delete.tcl

ad_page_contract {
     A page that gets confirmation and then delete notes.
 
@@ -179,7 +179,7 @@
 <formtemplate id="note-del-confirm"></formtemplate>
 </form>

The ADP is very simple. The formtemplate tag outputs the HTML -form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.

General_comments

You can track comments for any ACS Object. Here we'll track +form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few samplenotes.

General_comments

You can track comments for any ACS Object. Here we'll track comments for notes. On the notes.tcl/adp pair, which is used to display individual notes, we want to put a link to add comments at the bottom of the screen. If there are any comments, we want to @@ -200,13 +200,13 @@ there are comments. Then you pass the note id, which is also the acs_object id.

We put our two new variables in the notes.adp page.

<a href="@comment_add_url@">Add a comment</a>
-@comments_html@

Prepare the package for distribution.

Browse to the package manager. Click on +@comments_html@

Prepare the package for distribution.

Browse to the package manager. Click on tutorialapp.

Click on Generate a distribution file for this package from the filesystem.

Click on the file size (37.1KB) after the label Distribution File: and save the file to - /tmp.

+ /tmp.

Prev	Home	Next
Debugging and Automated Testing	Up	Chapter�8.�Development Reference