Part�II.�Administrator's Guide

Prev		Next

Prev		Next

Prev		Next

Prev		Next

Prev		Next

Prev		Next

Prev	Chapter�6.�Production Environments	Next

Prev	Chapter�3.�Complete Installation	Next

Prev	Chapter�3.�Complete Installation	Next

Package Manager Design

By Bryan Quinn

+Package Manager Design

Prev	Chapter�14.�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
Package Manager Requirements
Packages
ER diagram
Tcl API
- @@ -23,7 +23,7 @@
- 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 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 -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 18 Feb 2004 14:43:02 -0000 1.21 @@ -1,4 +1,4 @@ -Package Manager Requirements
Prev Chapter�12.�Kernel Documentation Next
Package Manager Requirements
By Bryan Quinn and Todd Nightingale
+Package Manager Requirements
Prev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/automated-backup.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-backup.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/automated-backup.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,3 @@ +Automated Backup (OPTIONAL)
Prev Chapter�8.�Backup and Recovery Next
Automated Backup (OPTIONAL)
The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in /var/lib/aolserver/service0/database-backup and then backs up all of /var/lib/aolserver/service0 to a single zip file, and then copies that zip file to another computer.
Make sure that the manual backup process described above works.
Customize the default backup script. Edit /var/lib/aolserver/service0/etc/backup.sh with your specific parameters.
+ Make sure the file is executable:
chmod +x backup.sh
+ Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.) This example runs the backup script at 1:30 am every day.
30 1 * * * * sh /var/lib/aolserver/service0/etc/backup.sh
Prev Home Next
Manual backup and recovery Up Using CVS for backup-recovery
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html 12 Feb 2004 13:51:40 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html 18 Feb 2004 14:43:02 -0000 1.6 @@ -1,4 +1,4 @@ -Automated Testing
Prev Chapter�10.�Engineering Standards Next
Automated Testing
By Jeff Davis
+Automated Testing
Prev Chapter�12.�Engineering Standards Next
Automated Testing
By Jeff Davis
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Best practices in writing OpenACS automated tests
Special characters in Tcl.� @@ -24,4 +24,4 @@ Make sure that if a duplicate name is entered that there is a reasonable error rather than a server error. Check for insert, move, copy, and rename. -
($Id$)
Prev Home Next
Variables Up Chapter�11.�Documentation Standards
docs@openacs.org
View comments on this page at openacs.org +

($Id$)

Prev	Home	Next
Variables	Up	Chapter�13.�Documentation Standards

docs@openacs.org

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 -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/backup-recovery.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 18 Feb 2004 14:43:02 -0000 1.21 @@ -1,4 +1,4 @@ -Backup and Recovery

Prev	Chapter�6.�Maintenance	Next

Backup and Recovery

By Don Baccus with additions +Chapter�8.�Backup and Recovery

Prev	Part�II.�Administrator's Guide	Next

Chapter�8.�Backup and Recovery

Table of Contents

Backup Strategy
Manual backup and recovery
Automated Backup (OPTIONAL)
Using CVS for backup-recovery

By Don Baccus with additions by Joel Aufrecht

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. @@ -7,200 +7,4 @@ probably need to create your own backup strategies (in particular full dumps from oracle, while easy to set up, are far from the best solution).

There are three basic things which need to be backed up, the database data, the server - source tree, and the acs-content-repository (which is in the server source tree).

Backup Strategy

- The purpose of backup is to enable recovery. Backup and - 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 -

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 -
-[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
-
-(c) Copyright 1999 Oracle Corporation.  All rights reserved.
-
-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 root]# su - service0
-[service0 service0]$ pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp service0
-[service0 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 service0]$ exit
-[root 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
- z compresses the output with gzip.
- 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 root]# su - service0
-[service0 service0]$ tar -cpsz --exclude /var/lib/aolserver/service0/etc/daemontools/supervise \
-   --file /tmp/service0-backup.tar.gz /var/lib/aolserver/service0/
-tar: Removing leading `/' from member names
-[service0 service0]$
```

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

[root root]# svc -d /service/service0
-[root root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost
-[root root]# rm /service/service0
-rm: remove symbolic link `/service/service0'? y
-[root root]# ps -auxw | grep service0
-root      1496  0.0  0.0  1312  252 ?        S    16:58   0:00 supervise service0
-[root root]# kill 1496
-[root root]# ps -auxw | grep service0
-[root root]# su - postgres
-[postgres pgsql]$ dropdb service0
-DROP DATABASE
-[postgres pgsql]$ dropuser service0
-DROP USER
-[postgres pgsql]$ exit
-logout
-[root 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 root]# su - service0
-[service0 service0]$ cd /var/lib/aolserver
-[service0 aolserver]$ tar xzf /tmp/service0-backup.tar.gz
-[service0 aolserver]$ chmod -R 775 service0
-[service0 aolserver]$ chown -R service0.web service0

Restore the database

Oracle.�
1. Set up a clean Oracle database user and - tablespace with the same names as the ones exported from (more information).
2. Invoke the import command
```
imp service0/service0 FILE=/var/lib/aolserver/service0/database-backup/nighty_backup.dmp FULL=Y
```

Postgres.�If the database user does not already exist, create it.

[root root]# su - postgres
-[postgres ~]$ 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
-[postgres ~]$ exit
-

Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects. Next, restore the database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.

[root root]# su - service0
-[service0 ~]$ createdb service0
-CREATE DATABASE
-[service0 ~]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0
-(many lines omitted)
-[service0 ~]$ psql service0 < /var/lib/aolserver/service0/database-backup/database-backup.dmp
-(many lines omitted)
-[service0 ~]$ exit
-[postgres ~]$ exit
-logout

Activate the service

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

Automated Backup (OPTIONAL)

The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in /var/lib/aolserver/service0/database-backup and then backs up all of /var/lib/aolserver/service0 to a single zip file, and then copies that zip file to another computer.

Make sure that the manual backup process described above works.
Customize the default backup script. Edit /var/lib/aolserver/service0/etc/backup.sh with your specific parameters.
- Make sure the file is executable:
```
chmod +x backup.sh
```
- Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.) This example runs the backup script at 1:30 am every day.
```
30 1 * * * *        sh /var/lib/aolserver/service0/etc/backup.sh
```

Using CVS for backup-recovery

CVS-only backup is often appropriate for development sites. If you are already using CVS and your data is not important, 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 root]# su - service0
-[service0 service0]$ cd /var/lib/aolserver/service0
-[service0 service0]$ cvs commit -m "last-minute commits before upgrade to 4.6"
-cvs commit: Examining .
-cvs commit: Examining bin
-(many lines omitted)
-[service0 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 service0]$ exit
-[root 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 root]# su - service0
-[service0 service0]$ cd /var/lib/aolserver/service0
-[service0 service0]$ cvs up -r current
-[service0 service0]$ exit
-su - service0
-cd /var/lib/aolserver/service0
-cvs up -r current

($Id$)

Prev	Home	Next
Database Management	Up	Diagnosing Performance Problems

docs@openacs.org

View comments on this page at openacs.org + source tree, and the acs-content-repository (which is in the server source tree).

Figure�8.1.�Backup and Recovery Strategy

($Id$)

Prev	Home	Next
Vacuum Postgres nightly	Up	Backup Strategy

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/backups-with-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backups-with-cvs.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/backups-with-cvs.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,30 @@ +Using CVS for backup-recovery

Prev	Chapter�8.�Backup and Recovery	Next

Using CVS for backup-recovery

CVS-only backup is often appropriate for development sites. If you are already using CVS and your data is not important, 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 root]# su - service0
+[service0 service0]$ cd /var/lib/aolserver/service0
+[service0 service0]$ cvs commit -m "last-minute commits before upgrade to 4.6"
+cvs commit: Examining .
+cvs commit: Examining bin
+(many lines omitted)
+[service0 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 service0]$ exit
+[root 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 root]# su - service0
+[service0 service0]$ cd /var/lib/aolserver/service0
+[service0 service0]$ cvs up -r current
+[service0 service0]$ exit
+su - service0
+cd /var/lib/aolserver/service0
+cvs up -r current

Prev	Home	Next
Automated Backup (OPTIONAL)	Up	Appendix�A.�Install Red Hat 8/9

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,4 +1,4 @@ -Bootstrapping OpenACS

Prev	Chapter�12.�Kernel Documentation	Next

Bootstrapping OpenACS

By Jon Salz

+Bootstrapping OpenACS

Prev	Chapter�14.�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/ch10s06.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/ch10s06.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/ch10s06.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,146 @@ +Categories

Prev	Chapter�10.�Advanced Topics	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 AOLserver 4
Install OpenACS 5.0.1d1
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

docs@openacs.org

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 AOLserver 4
Install OpenACS 5.1.0d1
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

docs@openacs.org

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 -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/cvs-tips.html 12 Feb 2004 13:51:40 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/cvs-tips.html 18 Feb 2004 14:43:02 -0000 1.11 @@ -1,7 +1,7 @@ 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. -

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

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

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

[root root]# mkdir /cvsroot/service0
 [root root]# chown service0.service0 /cvsroot/service0
@@ -20,11 +20,11 @@
             plus this string,
             i.e.
             /cvsroot/service0.
-            "OpenACS" is the vendor tag, and "oacs-5-0-1" is the
+            "OpenACS" is the vendor tag, and "HEAD" is the
             release tag.  These tags will be useful in upgrading and
             branching.  -m sets the version comment.
[root root]# su - service0
 [service0 service0]$ cd /var/lib/aolserver/service0
-[service0 service0]$ cvs import -m "initial install" service0 OpenACS oacs-5-0-1
+[service0 service0]$ cvs import -m "initial install" service0 OpenACS HEAD
 N service0/license.txt
 N service0/readme.txt
 (many lines omitted)
@@ -36,7 +36,7 @@
 [root root]#
 su - service0
 cd /var/lib/aolserver/service0
-cvs import -m "initial install" service0 OpenACS oacs-5-0-1
+cvs import -m "initial install" service0 OpenACS HEAD
 exit
Move the original directory to a temporary location, and check out the cvs repository in its place.
[root root]# mv /var/lib/aolserver/service0 /var/tmp
 [root root]# mkdir /var/lib/aolserver/service0
 [root root]# chown service0.service0 /var/lib/aolserver/service0
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 -r1.18 -r1.19
--- openacs-4/packages/acs-core-docs/www/database-management.html	12 Feb 2004 13:51:40 -0000	1.18
+++ openacs-4/packages/acs-core-docs/www/database-management.html	18 Feb 2004 14:43:02 -0000	1.19
@@ -1,52 +1,4 @@
-Database ManagementPrev Chapter�6.�Maintenance  Next
Database Management
By Joel Aufrecht
+Chapter�7.�Database ManagementPrev Part�II.�Administrator's Guide  Next
Chapter�7.�Database Management
Table of Contents
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
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
-      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
-      Reference install is located at /usr/local/pgsql/data/postgresql.conf
-      and change
#tcpip_socket = false
to
tcpip_socket = true
Change the access control file for the database to
-          permit specific remote clients to access.  Access can be
-          controlled ... (add notes from forum post) 
Change the OpenACS service's configuration file to
-          point to the remote database.  Edit
-          /var/lib/aolserver/service0/etc/config.tcl
-          and change
to 
Deleting a tablespace
Skip down for instructions on Deleting a PostgreSQL tablespace.
-    
Deleting an Oracle tablespace

-        Should it become necessary to rebuild a tablespace from scratch,
-        you can use the drop user command
-        in SVRMGRL with the cascade
-        option. This command will drop the user and every database object
-        the user owns.
SVRMGR> drop user service0 cascade;

-        If this does not work because svrmgrl "cannot drop a user that
-        is currently connected", make sure to kill the AOLserver using
-        this user. If it still does not work, do:
SVRMGR> select username, sid, serial# from v$session where lower(username)='service0';
and then
SVRMGR> alter system kill session 'sid, serial#';

-        where sid and serial# are
-        replaced with the corresponding values for the open session.
Use with caution!

-        If you feel the need to delete everything
-        related to the service, you can also issue the following:
SVRMGR> drop tablespace service0 including contents cascade constraints;
Deleting a PostgreSQL tablespace

-        Dropping a PostgreSQL tablespace is easy. You have to stop any
-        AOLserver instances that are using the database that you wish to
-        drop. If you're using daemontools, this is simple, just use the
-        'down' flag (-d). If you're using inittab, you have to comment out
-        your server in /etc/inittab,
-        reread the inittab with /sbin/init
-        q, and then restart-aolserver
-        service0.
Then, to drop the db, just do:
-[service0 ~]$ dropdb service0
-DROP DATABASE
Vacuum Postgres nightly

-      The "vacuum" command must be run periodically to reclaim space. The
-      "vacuum analyze" form additionally collects statistics on the
-      disbursion of columns in the database, which the optimizer uses when
-      it calculates just how to execute queries. The availability of this
-      data can make a tremendous difference in the execution speed of
-      queries. This command can also be run from cron, but it probably makes
-      more sense to run this command as part of your nightly backup
-      procedure - if "vacuum" is going to screw up the database, you'd
-      prefer it to happen immediately after (not before!) you've made a
-      backup! The "vacuum" command is very reliable, but conservatism is
-      the key to good system management. So, if you're using the export
-      procedure described above, you don't need to do this extra step.
-    
Edit your crontab:
[joeuser ~]$ crontab -e
We'll set vacuum up to run nightly at 1 AM. Add the following
-    line:
-0 1 * * * /usr/local/pgsql/bin/vacuumdb service0
($Id$)
Prev Home  Next
Running OpenACS in Production Environments Up  Backup and Recovery
docs@openacs.org
View comments on this page at openacs.org
+        
Prev Home  Next
Diagnosing Performance Problems Up  Running a PostgreSQL database on another server
docs@openacs.org
View comments on this page at openacs.org
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 -r1.26 -r1.27
--- openacs-4/packages/acs-core-docs/www/db-api-detailed.html	12 Feb 2004 13:51:40 -0000	1.26
+++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html	18 Feb 2004 14:43:02 -0000	1.27
@@ -1,4 +1,4 @@
-Database Access APIPrev Chapter�12.�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 APIPrev Chapter�14.�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

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 -r1.26 -r1.27
--- openacs-4/packages/acs-core-docs/www/db-api.html	12 Feb 2004 13:51:40 -0000	1.26
+++ openacs-4/packages/acs-core-docs/www/db-api.html	18 Feb 2004 14:43:02 -0000	1.27
@@ -1,4 +1,4 @@
-The OpenACS Database Access API
Prev Chapter�9.�Development Reference  Next
The OpenACS Database Access API

+The OpenACS Database Access API
Prev Chapter�11.�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
Index: openacs-4/packages/acs-core-docs/www/dev-guide.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v
diff -u -r1.21 -r1.22
--- openacs-4/packages/acs-core-docs/www/dev-guide.html	12 Feb 2004 13:51:40 -0000	1.21
+++ openacs-4/packages/acs-core-docs/www/dev-guide.html	18 Feb 2004 14:43:02 -0000	1.22
@@ -1 +1 @@
-Chapter�9.�Development Reference
Prev Part�III.�For OpenACS Package Developers  Next
Chapter�9.�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
 Up  OpenACS Packages
docs@openacs.org
View comments on this page at openacs.org
+Chapter�11.�Development ReferencePrev Part�III.�For OpenACS Package Developers  Next
Chapter�11.�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
 Up  OpenACS Packages
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/doc-standards.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/doc-standards.html,v
diff -u -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/doc-standards.html	12 Feb 2004 13:51:40 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/doc-standards.html	18 Feb 2004 14:43:02 -0000	1.5
@@ -1 +1 @@
-Chapter�11.�Documentation StandardsPrev Part�III.�For OpenACS Package Developers  Next
Chapter�11.�Documentation Standards
Table of Contents
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
Prev Home  Next
Automated Testing Up  OpenACS Documentation Guide
docs@openacs.org
View comments on this page at openacs.org
+Chapter�13.�Documentation StandardsPrev Part�III.�For OpenACS Package Developers  Next
Chapter�13.�Documentation Standards
Table of Contents
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
Prev Home  Next
Automated Testing Up  OpenACS Documentation Guide
docs@openacs.org
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 -r1.27 -r1.28
--- openacs-4/packages/acs-core-docs/www/docbook-primer.html	12 Feb 2004 13:51:40 -0000	1.27
+++ openacs-4/packages/acs-core-docs/www/docbook-primer.html	18 Feb 2004 14:43:02 -0000	1.28
@@ -1,4 +1,4 @@
-OpenACS Documentation GuidePrev Chapter�11.�Documentation Standards  Next
OpenACS Documentation Guide

+OpenACS Documentation Guide
Prev Chapter�13.�Documentation Standards  Next
OpenACS Documentation Guide

     By Claus Rasmussen, with additions by Roberto
       Mello and the OpenACS Community
   
Overview of OpenACS Documentation

@@ -36,7 +36,7 @@
       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.
@@ -57,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
@@ -106,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
@@ -130,20 +130,20 @@
       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 
       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.
     

@@ -158,7 +158,7 @@
 
 </sect1>
 

-      
+      
       Inside this container your document will be split up into 
       <sect2>'s,
       each with the same requirements - id and xreflabel
@@ -167,7 +167,7 @@
       When it comes to naming your
       sect2's and below, prefix them with some abbreviation of the id in the sect1 such as requirements-overview.

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>. @@ -177,12 +177,12 @@ <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:

+	  
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:
@@ -206,7 +206,7 @@
 	    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 @@ -227,7 +227,7 @@ 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>, @@ -253,7 +253,7 @@ 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 @@ -298,7 +298,7 @@ </variablelist>

Tables

- + DocBook supports several types of tables, but in most cases, the <informaltable> is enough: @@ -335,7 +335,7 @@ <table> for an example.

Emphasis

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

@@ -413,4 +413,4 @@ 8/3/2002Vinod Kurup0.3 Added OpenACS information, updated tools, added extra links and added info to the Publishing section. - 12/24/2001Roberto Mello0.2Changed recommendation from <phrase> to <emphasis role="strong">01/19/2000Claus Rasmussen0.1Creation12/2000Claus Rasmussen

Prev	Home	Next
Chapter�11.�Documentation Standards	Up	Using PSGML mode in Emacs

docs@openacs.org

View comments on this page at openacs.org + 12/24/2001Roberto Mello0.2Changed recommendation from <phrase> to <emphasis role="strong">01/19/2000Claus Rasmussen0.1Creation12/2000Claus Rasmussen

Prev	Home	Next
Chapter�13.�Documentation Standards	Up	Using PSGML mode in Emacs

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v diff -u -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 12 Feb 2004 13:51:40 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 18 Feb 2004 14:43:02 -0000 1.26 @@ -1,4 +1,4 @@ -Constraint naming standard

Prev	Chapter�10.�Engineering Standards	Next

Constraint naming standard

By Michael Bryzek

+Constraint naming standard

Prev	Chapter�12.�Engineering Standards	Next

Constraint naming standard

By Michael Bryzek

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

The Big Picture

Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 12 Feb 2004 13:51:40 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 18 Feb 2004 14:43:02 -0000 1.26 @@ -1,4 +1,4 @@ -ACS File Naming and Formatting Standards

Prev	Chapter�10.�Engineering Standards	Next

ACS File Naming and Formatting Standards

By Michael Yoon and Aurelius Prochazka

+ACS File Naming and Formatting Standards

Prev	Chapter�12.�Engineering Standards	Next

ACS File Naming and Formatting Standards

By Michael Yoon and Aurelius Prochazka

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

Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,4 +1,4 @@ -PL/SQL Standards

Prev	Chapter�10.�Engineering Standards	Next

PL/SQL Standards

+PL/SQL Standards

Prev	Chapter�12.�Engineering Standards	Next

PL/SQL Standards

By Richard Li and Yon Feldman

OpenACS docs are written by the named authors, and may be edited Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,4 +1,4 @@ -Release Version Numbering

Prev	Chapter�10.�Engineering Standards	Next

Release Version Numbering

By Ron Henderson

Revised by Joel Aufrecht

+Release Version Numbering

Prev	Chapter�12.�Engineering Standards	Next

Release Version Numbering

By Ron Henderson

Revised by Joel Aufrecht

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

Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 18 Feb 2004 14:43:02 -0000 1.19 @@ -1 +1 @@ -Chapter�10.�Engineering Standards

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�10.�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

docs@openacs.org

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

Prev	Part�III.�For OpenACS Package Developers	Next

Chapter�12.�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

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 12 Feb 2004 13:51:40 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 18 Feb 2004 14:43:02 -0000 1.16 @@ -1,4 +1,4 @@ -External Authentication Requirements

Prev	Chapter�12.�Kernel Documentation	Next

External Authentication Requirements

Vision

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

Prev	Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/filename.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/filename.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,4 +1,4 @@ -Detailed Design Documentation Template

Prev	Chapter�11.�Documentation Standards	Next

Detailed Design Documentation Template

By You

Start Note

+Detailed Design Documentation Template

Prev	Chapter�13.�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.1d1, parameters are set at two levels: at the global level by + Under OpenACS 5.1.0d1, 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

Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/form-builder.html 12 Feb 2004 13:51:40 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 18 Feb 2004 14:43:02 -0000 1.6 @@ -1,4 +1,4 @@ -Using HTML Forms

Prev Chapter�9.�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 FormsPrev Chapter�11.�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
@@ -10,5 +10,5 @@
     }
This will result in a single name/value pair coming back in the submitted form.  Handle this within the same ad_form structure, in the -new_data and -edit_data.  In the example, it is available as $foo
See also the 
         W3C spec for "The SELECT, OPTGROUP, and OPTION elements".
         
Common Errors
Here are some common errors and what to do when you
-    encounter them:
Error when selecting values
This generally happens when there is an error in your
-          query.
($Id$)
Prev Home  Next
Programming with AOLserver Up  Chapter�10.�Engineering Standards
docs@openacs.org
View comments on this page at openacs.org
+    encounter them:
Error when selecting values
This generally happens when there is an error in your
+          query.

($Id$)

Prev	Home	Next
Programming with AOLserver	Up	Chapter�12.�Engineering Standards

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/groups-design.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 18 Feb 2004 14:43:02 -0000 1.20 @@ -1,4 +1,4 @@ -Groups Design
Prev Chapter�12.�Kernel Documentation Next
Groups Design
By Rafael H. Schloming and Mark Thomas
+Groups Design
Prev Chapter�14.�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
Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 18 Feb 2004 14:43:02 -0000 1.20 @@ -1,4 +1,4 @@ -Groups Requirements
Prev Chapter�12.�Kernel Documentation Next
Groups Requirements
By Rafael H. Schloming, Mark Thomas
+Groups Requirements
Prev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/high-avail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/high-avail.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1 @@ +High Availability/High Performance Configurations
Prev Chapter�6.�Production Environments Next
High Availability/High Performance Configurations
Figure�6.1.�Multiple-server configuration
Prev Home Next
Running multiple services on one machine Up Staged Deployment for Production Networks
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/how-do-I.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.html,v diff -u -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/how-do-I.html 12 Feb 2004 13:51:40 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/how-do-I.html 18 Feb 2004 14:43:02 -0000 1.4 @@ -1,6 +1,6 @@ -How Do I?
Prev Chapter�4.�Configuring a new OpenACS Site Next
How Do I?
How do I edit the front page of a new site through a web interface?
The easiest way is to install the Edit-This-Page package.
Log in to the web site as an administrator.
Click on Admin > Install Software > Install from OpenACS Repository / Install new application
+How Do I?
Prev Chapter�4.�Configuring a new OpenACS Site Next
How Do I?
How do I edit the front page of a new site through a web interface?
The easiest way is to install the Edit-This-Page package.
Log in to the web site as an administrator.
Click on Admin > Install Software > Install from OpenACS Repository / Install new application
Choose Edit This Page and install -
Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
How do I let anybody who registers post to a weblog?
Go to /admin/permissions and grant Create to Registered Users
How do I replace the front page of a new site with the front page of an application on that site
Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
On the front page, click the Admin button.
On the administration page, click Parameters link.
Change the parameter IndexRedirectUrl to be the URI of the desired application. For a default weblogger installation, this would be weblogger/. Note the trailing slash.
How do I put custom functionality on front page of a new site?
Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/service0/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
cp /var/lib/aolserver/service0/packages/acs-subsite/www/index* /var/lib/aolserver/service0/www
Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
How do I change the site-wide style?
Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:
+
Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).
How do I let anybody who registers post to a weblog?
Go to /admin/permissions and grant Create to Registered Users
How do I replace the front page of a new site with the front page of an application on that site
Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.
On the front page, click the Admin button.
On the administration page, click Parameters link.
Change the parameter IndexRedirectUrl to be the URI of the desired application. For a default weblogger installation, this would be weblogger/. Note the trailing slash.
How do I put custom functionality on front page of a new site?
Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/service0/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
cp /var/lib/aolserver/service0/packages/acs-subsite/www/index* /var/lib/aolserver/service0/www
Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.
How do I change the site-wide style?
Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:
A templated page uses an ADP/TCL pair. The first line in the ADP file is usually:
<master>
If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/service0/www, this is /var/lib/aolserver/service0/www/default-master.adp and the associated .tcl file. -
The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/service0/www/site-master.adp and .tcl)
The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/service0/www/blank-master.adp and .tcl).
Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
Figure�4.1.�Site Templates
Prev Home Next
Chapter�4.�Configuring a new OpenACS Site Up Chapter�5.�Upgrading
docs@openacs.org
View comments on this page at openacs.org +
The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/service0/www/site-master.adp and .tcl)
The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/service0/www/blank-master.adp and .tcl).
Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
Figure�4.1.�Site Templates
Prev Home Next
Chapter�4.�Configuring a new OpenACS Site Up Chapter�5.�Upgrading
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 -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 12 Feb 2004 13:51:40 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 18 Feb 2004 14:43:02 -0000 1.11 @@ -1,4 +1,4 @@ -OpenACS Internationalization Requirements
Prev Chapter�12.�Kernel Documentation Next
OpenACS Internationalization Requirements
by Henry Minsky, +OpenACS Internationalization Requirements
Prev Chapter�14.�Kernel Documentation Next
OpenACS Internationalization Requirements
by Henry Minsky, Yon Feldman, Lars Pind, Peter Marklund, Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/i18n.html 12 Feb 2004 13:51:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/i18n.html 18 Feb 2004 14:43:02 -0000 1.18 @@ -1,4 +1,4 @@ -Internationalization
Prev Chapter�12.�Kernel Documentation Next
Internationalization
+Internationalization
Prev Chapter�14.�Kernel Documentation Next
Internationalization
By Peter Marklund and Lars Pind
@@ -48,7 +48,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 @@ -263,15 +263,15 @@ 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 Internationalization, then Convert ADP, Tcl, and SQL files to using the - message catalog..
Internationalize Package Parameters with visible messages
- See ??? -
Internationalize Date and Time queries
Find datetime in .xql files. Use command line tools to find suspect SQL code:
grep -r "to_char.*H" * + message catalog..
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" * 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. Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/index.html 12 Feb 2004 13:51:40 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/index.html 18 Feb 2004 14:43:02 -0000 1.29 @@ -1 +1 @@ -OpenACS Core Documentation
Next
OpenACS Core Documentation
Table of Contents
I. OpenACS For Everyone
1. High level information: What is OpenACS?
Overview
OpenACS Release Notes
II. Administrator's Guide
2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 3.3oacs1
Install AOLserver 4
Install OpenACS 5.0.1d1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
How Do I?
5. Upgrading
Overview
Upgrading OpenACS
Upgrading the OpenACS files
Upgrading Platform components
6. Maintenance
Running OpenACS in Production Environments
Database Management
Backup and Recovery
Diagnosing Performance Problems
A. Install Red Hat 8/9
B. Install additional supporting software
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
III. For OpenACS Package Developers
7. Development Tutorial
Creating a Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
8. Advanced Topics
Write the Requirements and Design Specs
Add the new package to CVS
Adding Comments
Admin Pages
Categories
Categories
Prepare the package for distribution.
Notifications
Using .vuh files for pretty urls
9. Development Reference
OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
OpenACS Permissions Tediously Explained
Object Identity
Programming with AOLserver
Using HTML Forms
10. Engineering Standards
OpenACS Style Guide
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
11. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
D. Using CVS with an OpenACS Site
E. How to package and release OpenACS
How to Update the OpenACS.org repository
How to Update the translations
IV. For OpenACS Platform Developers
12. Kernel Documentation
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
Index
List of Figures
4.1. Site Templates
6.1. Query Analysis example
7.1. Assumptions in this section
7.2. Tutorial Data Model
7.3. Database Creation Script - master create file
7.4. Database deletion script
List of Tables
2.1. Default directories for a standard install
2.2. Version Compatibility Matrix
5.1. Assumptions in this section
9.1. Context Hierarchy Example
9.2. acs_objects example data
List of Examples
10.1. Getting datetime from the database ANSI-style
Next
Part�I.�OpenACS For Everyone
docs@openacs.org
View comments on this page at openacs.org +OpenACS Core Documentation
Next
OpenACS Core Documentation
Table of Contents
I. OpenACS For Everyone
1. High level information: What is OpenACS?
Overview
OpenACS Release Notes
II. Administrator's Guide
2. Installation Overview
Basic Steps
Prerequisite Software
3. Complete Installation
Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 3.3oacs1
Install AOLserver 4
Install OpenACS 5.1.0d1
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X
4. Configuring a new OpenACS Site
How Do I?
5. Upgrading
Overview
Upgrading OpenACS
Upgrading the OpenACS files
Upgrading Platform components
6. Production Environments
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support
Set up Log Analysis Reports - OPTIONAL
External uptime validation
Diagnosing Performance Problems
7. Database Management
Running a PostgreSQL database on another server
Deleting a tablespace
Vacuum Postgres nightly
8. Backup and Recovery
Backup Strategy
Manual backup and recovery
Automated Backup (OPTIONAL)
Using CVS for backup-recovery
A. Install Red Hat 8/9
B. Install additional supporting software
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
III. For OpenACS Package Developers
9. Development Tutorial
Creating a Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
10. Advanced Topics
Write the Requirements and Design Specs
Add the new package to CVS
Adding Comments
Admin Pages
Categories
Categories
Prepare the package for distribution.
Notifications
Using .vuh files for pretty urls
11. Development Reference
OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
OpenACS Permissions Tediously Explained
Object Identity
Programming with AOLserver
Using HTML Forms
12. Engineering Standards
OpenACS Style Guide
Release Version Numbering
Constraint naming standard
ACS File Naming and Formatting Standards
PL/SQL Standards
Variables
Automated Testing
13. Documentation Standards
OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
Detailed Design Documentation Template
System/Application Requirements Template
D. Using CVS with an OpenACS Site
E. How to package and release OpenACS
How to Update the OpenACS.org repository
How to Update the translations
IV. For OpenACS Platform Developers
14. Kernel Documentation
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
Index
List of Figures
4.1. Site Templates
5.1. Upgrading with the APM
5.2. Upgrading a local CVS repository
6.1. Multiple-server configuration
6.2. Simple Deployment - Step 1
6.3. Simple Deployment - Step 1
6.4. Simple Deployment - Step 1
6.5. Complex Deployment - Step 1
6.6. Complex Deployment - Step 1
6.7. Complex Deployment - Step 1
6.8. Query Analysis example
8.1. Backup and Recovery Strategy
9.1. Assumptions in this section
9.2. Tutorial Data Model
9.3. Database Creation Script - master create file
9.4. Database deletion script
10.1. Upgrading a local CVS repository
List of Tables
2.1. Default directories for a standard install
2.2. Version Compatibility Matrix
5.1. Assumptions in this section
6.1. How it Works
11.1. Context Hierarchy Example
11.2. acs_objects example data
List of Examples
12.1. Getting datetime from the database ANSI-style
Next
Part�I.�OpenACS For Everyone
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 12 Feb 2004 13:51:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 18 Feb 2004 14:43:02 -0000 1.18 @@ -6,7 +6,7 @@ and webserver. Many additional programs, such as a Mail Transport Agent and source control system, are also needed for a fully effective instance. -
Table�2.2.�Version Compatibility Matrix
OpenACS Version 3.2.5 4.5 4.6 4.6.1 4.6.2 4.6.3 5.0.0
AOLserver 3 Yes No
3.3+ad13 Maybe Yes
3.3oacs1 Maybe Yes
3.4.2 No
3.4.2oacs1 Maybe Yes Maybe
3.5.5 Maybe Yes No
4.0 Maybe Yes
PostgreSQL 7.0 Yes No
7.2.x � Yes No
7.3.2 - 7.3.4 No Yes
7.4 No Maybe
Oracle 8.1.6 Maybe Yes
8.1.7 Maybe Yes
9i No Yes
OpenACS 5.0.1d1.�The OpenACS tarball comprises the core packages and +
Table�2.2.�Version Compatibility Matrix
OpenACS Version 3.2.5 4.5 4.6 4.6.1 4.6.2 4.6.3 5.0.0
AOLserver 3 Yes No
3.3+ad13 Maybe Yes
3.3oacs1 Maybe Yes
3.4.2 No
3.4.2oacs1 Maybe Yes Maybe
3.5.5 Maybe Yes No
4.0 Maybe Yes
PostgreSQL 7.0 Yes No
7.2.x � Yes No
7.3.2 - 7.3.4 No Yes
7.4 No Maybe
Oracle 8.1.6 Maybe Yes
8.1.7 Maybe Yes
9i No Yes
OpenACS 5.1.0d1.�The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL and Oracle.
Operating System.�OpenACS is designed for a Unix-like system. It is @@ -38,7 +38,7 @@ distributions.
TCL 8.3 development headers and libraries, OPTIONAL.� The site-wide-search service, OpenFTS, requires these to compile. (Debian users: apt-get install tcl8.3-dev). You need this - to install OpenFTS.
tDOM, REQUIRED.�OpenACS 5.0.1d1 stores + to install OpenFTS.
tDOM, REQUIRED.�OpenACS 5.1.0d1 stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which was used prior to 4.6.4.) tDOM is available from http://www.tdom.org).
tclwebtest, OPTIONAL.�tclwebtest 0.3 is a tool for testing web interfaces @@ -49,7 +49,7 @@ running Apache with mod_nsd - see this post.
AOLserver 3.3oacs1, REQUIRED.�Mat Kovach's source distribution of AOLserver, including all of the patches listed below.
Mat Kovach is graciously maintaining an AOLserver distribution that - includes all the patches and modules needed to run OpenACS 5.0.1d1. These + includes all the patches and modules needed to run OpenACS 5.1.0d1. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and perhaps more to come), currently located at uptime.openacs.org. Index: openacs-4/packages/acs-core-docs/www/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 12 Feb 2004 13:51:40 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 18 Feb 2004 14:43:02 -0000 1.17 @@ -1,4 +1,4 @@ -Initialize CVS (OPTIONAL)
Prev Appendix�B.�Install additional supporting software Next
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 tmp]# mkdir /cvsroot [root tmp]# cvs -d /cvsroot init [root tmp]# Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-daemontools.html 12 Feb 2004 13:51:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-daemontools.html 18 Feb 2004 14:43:02 -0000 1.18 @@ -3,7 +3,7 @@ installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package + services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package [root root]# chmod 1755 /package/ [root root]# cd /package/ [root package]# tar xzf /tmp/daemontools-0.76.tar.gz @@ -61,7 +61,7 @@ root 13294 0.0 0.1 1352 272 ? S 09:51 0:00 svscan /service root 13295 0.0 0.0 1304 208 ? S 09:51 0:00 readproctitle service errors: ....................................... [root root]#
Install a script to grant non-root users permission to - control daemontools services.
[root root]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup + control daemontools services.
[root root]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup [root root]# chmod 755 /usr/local/bin/svgroup -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup +cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup chmod 755 /usr/local/bin/svgroup
Prev Home Next
Add PSGML commands to emacs init file (OPTIONAL) Up Install qmail (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-full-text-search.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/install-full-text-search.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/install-full-text-search.html 12 Feb 2004 13:51:40 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html 18 Feb 2004 14:43:02 -0000 1.16 @@ -1,7 +1,7 @@ Install Full Text Search
Prev Appendix�B.�Install additional supporting software Next
Install Full Text Search
By Joel Aufrecht and Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
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 +
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 root]# su - postgres @@ -76,7 +76,7 @@ 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 OpenFTS module and prerequisites.)
[service0 service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,18 @@ +Running multiple services on one machine
Prev Chapter�6.�Production Environments Next
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.1.0d1 replacing + service0, and change the +
set httpport 8000 +set httpsport 8443
+ to different values.
Services on different host names.�For example, suppose you want to support +http://foo.com and + http://bar.com on the same + machine. The easiest way is to assign each one a different ip + address. Then you can install two services as above, but with + different values for +
set hostname [ns_info hostname] +set address 127.0.0.1
+
If you want to install two services with different host + names sharing the same ip, you'll need nsvhr to redirect requests + based on the contents of the tcp headers. See AOLserver + Virtual Hosting with TCP by markd. +
Prev Home Next
AOLserver keepalive with inittab Up High Availability/High Performance Configurations
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-next-backups.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-backups.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-next-backups.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,35 @@ +Backup Strategy
Prev Chapter�8.�Backup and Recovery Next
Backup Strategy
+ The purpose of backup is to enable recovery. Backup and + 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 +
Prev Home Next
Chapter�8.�Backup and Recovery Up Manual backup and recovery
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,16 @@ +Vacuum Postgres nightly
Prev Chapter�7.�Database Management Next
Vacuum Postgres nightly
+ The "vacuum" command must be run periodically to reclaim space. The + "vacuum analyze" form additionally collects statistics on the + disbursion of columns in the database, which the optimizer uses when + it calculates just how to execute queries. The availability of this + data can make a tremendous difference in the execution speed of + queries. This command can also be run from cron, but it probably makes + more sense to run this command as part of your nightly backup + procedure - if "vacuum" is going to screw up the database, you'd + prefer it to happen immediately after (not before!) you've made a + backup! The "vacuum" command is very reliable, but conservatism is + the key to good system management. So, if you're using the export + procedure described above, you don't need to do this extra step. +
Edit your crontab:
[joeuser ~]$ crontab -e
We'll set vacuum up to run nightly at 1 AM. Add the following + line:
+0 1 * * * /usr/local/pgsql/bin/vacuumdb service0
($Id: install-next-nightly-vacuum.html,v 1.1 2004/02/18 14:43:02 joela Exp $)
Prev Home Next
Deleting a tablespace Up Chapter�8.�Backup and Recovery
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 12 Feb 2004 13:51:40 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 18 Feb 2004 14:43:02 -0000 1.12 @@ -5,7 +5,7 @@ https. These commands compile nsopenssl and install it, along with a tcl helper script to handle https connections. You will also need ssl certificates. Because those should - be different for each server service, you won't need those instructions until + be different for each server service, you won't need those instructions until later.
Install on AOLserver3
You will need the unpacked Aolserver tarball in /usr/local/src/aolserver and the nsopenssl tarball in Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,24 @@ +Deleting a tablespace
Prev Chapter�7.�Database Management Next
Deleting a tablespace
Skip down for instructions on Deleting a PostgreSQL tablespace. +
Deleting an Oracle tablespace
+ Should it become necessary to rebuild a tablespace from scratch, + you can use the drop user command + in SVRMGRL with the cascade + option. This command will drop the user and every database object + the user owns.
SVRMGR> drop user service0 cascade;
+ If this does not work because svrmgrl "cannot drop a user that + is currently connected", make sure to kill the AOLserver using + this user. If it still does not work, do:
SVRMGR> select username, sid, serial# from v$session where lower(username)='service0';
and then
SVRMGR> alter system kill session 'sid, serial#';
+ where sid and serial# are + replaced with the corresponding values for the open session.
Use with caution!
+ If you feel the need to delete everything + related to the service, you can also issue the following:
SVRMGR> drop tablespace service0 including contents cascade constraints;
Deleting a PostgreSQL tablespace
+ Dropping a PostgreSQL tablespace is easy. You have to stop any + AOLserver instances that are using the database that you wish to + drop. If you're using daemontools, this is simple, just use the + 'down' flag (-d). If you're using inittab, you have to comment out + your server in /etc/inittab, + reread the inittab with /sbin/init + q, and then restart-aolserver + service0.
Then, to drop the db, just do:
+[service0 ~]$ dropdb service0 +DROP DATABASE
Prev Home Next
Running a PostgreSQL database on another server Up Vacuum Postgres nightly
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,91 @@ +AOLserver keepalive with inittab
Prev Chapter�6.�Production Environments Next
AOLserver keepalive with inittab
This is an alternative method for keeping the AOLserver + process running. The recommended method is to run AOLserver + supervised.
+ This step should be completed as root. This can break every service + on your machine, so proceed with caution. +
+ There are 2 general steps to getting this working. +
+ Install a script called + restart-aolserver. This + script doesn't actually restart AOLserver - it just kills + it. +
+ Ask the OS to restart our service whenever it's not + running. We do this by adding a line to + /etc/inittab. +
+ Calling restart-aolserver + kills our service. The OS notices that our service is not + running, so it automatically restarts it. Thus, calling + restart-aolserver effectively + restarts our service. +
+ Copy this file into + /tmp/restart-aolserver.txt. +
+ This script needs to be SUID-root, which means + that the script will run as root. This is necessary to ensure + that the AOLserver processes are killed regardless of who owns + them. However the script should be executable by the + web group to ensure that the + users updating the web page can use the script, but that + general system users cannot run the script. You also need to + have Perl installed and also a symbolic link to it in + /usr/local/bin. +
+[joeuser ~]$ su - +Password: *********** +[root ~]# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver +[root ~]# chown root.web /usr/local/bin/restart-aolserver +[root ~]# chmod 4750 /usr/local/bin/restart-aolserver +[root ~]# ln -s /usr/bin/perl /usr/local/bin/perl +[root ~]# exit
+ Test the restart-aolserver + script. We'll first kill all running servers to clean the + slate. Then, we'll start one server and use + restart-aolserver to kill + it. If it works, then there should be no more servers + running. You should see the following lines.
+[joeuser ~]$ killall nsd +nsd: no process killed +[joeuser ~]$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/birdnotes/nsd.tcl +[joeuser ~]$ restart-aolserver birdnotes +Killing 23727 +[joeuser ~]$ killall nsd +nsd: no process killed
+ The number 23727 indicates the process id(s) (PIDs) of the + processes being killed. It is important that no processes are killed by the second + call to killall. If there are + processes being killed, it means that the script is not + working.
+ Assuming that the restart-aolserver + script worked, login as root and open + /etc/inittab for + editing.
+[joeuser ~]$ su - +Password: ************ +[root ~]# emacs -nw /etc/inittab
+ Copy this line into the bottom of the file as a template, + making sure that the first field + nss1 is unique. +
+nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl
+ Important: Make sure there is a + newline at the end of the file. If there is not a newline at + the end of the file, the system may suffer catastrophic + failures. +
+ Still as root, enter the following command to re-initialize + /etc/inittab.
+[root ~]# killall nsd +nsd: no process killed +[root ~]# /sbin/init q
+ See if it worked by running the + restart-aolserver script + again.
+[root ~]# restart-aolserver birdnotes +Killing 23750
+ If processes were killed, congratulations, your server is now + automated for startup and shutdown. +
Prev Home Next
Starting and Stopping an OpenACS instance. Up Running multiple services on one machine
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,67 @@ +Starting and Stopping an OpenACS instance.
Prev Chapter�6.�Production Environments Next
Starting and Stopping an OpenACS instance.
The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/service0/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.
A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.
The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.
Daemontools must already be installed. If not, install it.
Each service controlled by daemontools must have a + directory in /service. That + directory must have a file called + run. It works like this:
The init program starts every + time the computer is booted.
A line in init's configuration + file, /etc/inittab, tells init to + run, and to restart if necessary, + svscanboot.
svscanboot checks + the directory /service + every few seconds.
If it sees a subdirectory there, it + looks for a file in the subdirectory called + run. If it finds a run file, it creates a supervise process
supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.
Hence, the AOLserver + instance for your development server is started by the file + /service/service0/run. + But we use a symlink to make it easier to add and remove + stuff from the /service, so + the actual location is + /var/lib/aolserver/service0etc/daemontools/run.
Daemontools creates additional files and directories to track status and + log. A daemontools directory is included in the OpenACS tarball at + /var/lib/aolserver/service0/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.
[service0 etc]$ killall nsd +nsd: no process killed +[service0 etc]$ exit + +[root root]# ln -s /var/lib/aolserver/service0/etc/daemontools/ /service/service0
Verify that AOLserver is running.
[root root]# ps -auxw | grep nsd +service0 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/service0/etc/config.tcl -u serve +root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd +[root root]#
The user service0 can now control the service service0 with these commands:
+ + svc -d /service/service0 - + Bring the server down + +
+ + svc -u /service/service0 - + Start the server up and leave it in keepalive mode. + +
+ + svc -o /service/service0 - + Start the server up once. Do not restart it if it stops. + +
+ + svc -t /service/service0 - + Stop and immediately restart the server. + +
+ + svc -k /service/service0 - + Sends the server a KILL signal. This is like KILL -9. AOLserver + exits immediately. If svc -t fails to fully kill AOLserver, use + this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately. + +
Install a script to automate the stopping and starting + of AOLserver services via daemontools. You can then restart a service via restart-aolserver service0
[root root]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver +[root root]# chmod 755 /usr/local/bin/restart-aolserver +[root root]#
+ At this point, these commands will work only for the + root user. Grant permission for the web group to use svc commands on the service0 server.
[root root]# svgroup web /service/service0 +[root 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 + Mini-HOWTO. +
Table�6.1.�How it Works
Program Invoked by this program ... ... using this file Where to find errors Log goes to Use these commands to control it
svscanboot + init /etc/inittab ps -auxw | grep readproctitle n/a �
aolserver supervise +(a child of svscanboot) /service/service0/run /var/lib/aolserver/service0/log/error.log /var/lib/aolserver/service0/log/service0.log svc -k /service/service0
postgresql Redhat init scripts during boot /etc/init.d/postgresql /usr/local/pgsql/data/server.log � service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)
Prev Home Next
Chapter�6.�Production Environments Up AOLserver keepalive with inittab
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 -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 12 Feb 2004 13:51:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 18 Feb 2004 14:43:02 -0000 1.18 @@ -29,7 +29,7 @@ tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root ucspi-tcp-0.88]# -
+
(I'm not sure if this next step is 100% necessary, but when I skip it I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our @@ -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 ucspi-tcp-0.88]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp +send outgoing mail.
[root ucspi-tcp-0.88]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp [root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp -cp /tmp/openacs-5.0.1d1/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.1.0d1/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 root]# cd /usr/local/src [root src]# wget http://www.qmail.org/netqmail-1.04.tar.gz [root src]# tar xzf netqmail-1.04.tar.gz @@ -102,7 +102,7 @@ cd netqmail-1.04 ./collate.sh cd netqmail-1.04 -make setup check
Replace sendmail with qmail's wrapper.
[root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail +make setup check
Replace sendmail with qmail's wrapper.
[root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail [root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail @@ -124,13 +124,13 @@ 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 alias]# echo "./Maildir" > /var/qmail/bin/.qmail -[root alias]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc +[root alias]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc [root alias]# chmod 755 /var/qmail/rc [root alias]# echo "./Maildir" > /var/qmail/bin/.qmail -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc +cp /tmp/openacs-5.1.0d1/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 be configured for qmail.
[root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir @@ -142,13 +142,13 @@ [root root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log [root root]# mkdir /var/log/qmail [root root]# chown qmaill /var/log/qmail -[root root]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl +[root root]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl [root root]# chmod 755 /var/qmail/bin/qmailctl [root root]# ln -s /var/qmail/bin/qmailctl /usr/bin -[root root]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run -[root root]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run -[root root]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run -[root root]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run +[root root]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run +[root root]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run +[root root]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run +[root root]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run [root root]# chmod 755 /var/qmail/supervise/qmail-send/run [root root]# chmod 755 /var/qmail/supervise/qmail-send/log/run [root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run @@ -159,13 +159,13 @@ mkdir -p /var/qmail/supervise/qmail-smtpd/log mkdir /var/log/qmail chown qmaill /var/log/qmail -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl +cp /tmp/openacs-5.1.0d1/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.1d1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run +cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run +cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run +cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run +cp /tmp/openacs-5.1.0d1/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 Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 12 Feb 2004 13:51:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 18 Feb 2004 14:43:02 -0000 1.18 @@ -1,4 +1,4 @@ -Appendix�A.�Install Red Hat 8/9
Prev Part�II.�Administrator's Guide Next
Appendix�A.�Install Red Hat 8/9
by Joel Aufrecht
+Appendix�A.�Install Red Hat 8/9
Prev Part�II.�Administrator's Guide Next
Appendix�A.�Install Red Hat 8/9
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
This section takes a blank PC and sets up some supporting @@ -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 @@ -200,4 +200,4 @@ 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
Prev Home Next
Diagnosing Performance Problems Up Appendix�B.�Install additional supporting software
docs@openacs.org
View comments on this page at openacs.org +reboot
Prev Home Next
Using CVS for backup-recovery Up Appendix�B.�Install additional supporting software
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-ssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/install-ssl.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,28 @@ +Installing SSL SupportPrev Chapter�6.�Production Environments Next 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 etc]$ mkdir /var/lib/aolserver/service0/etc/certs +[service0 etc]$ chmod 700 /var/lib/aolserver/service0/etc/certs +[service0 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 service0]$ cd /var/lib/aolserver/service0/etc/certs +[service0 certs]$ perl /usr/share/ssl/misc/CA -newcert +Using configuration from /usr/share/ssl/openssl.cnf +Generating a 1024 bit RSA private key +...++++++ +.......++++++ +writing new private key to 'newreq.pem' +Enter PEM pass phrase: Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this: Certificate (and private key) is in newreq.pem +[service0 certs]$ newreq.pem contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site. [root misc]# openssl rsa -in newreq.pem -out keyfile.pem +read RSA key +Enter PEM pass phrase: +writing RSA key +[service0 certs]$ To create the certificate file, we take the combined file, copy it, and strip out the key. [service0 certs]$ cp newreq.pem certfile.pem +[root misc]# emacs certfile.pem Strip out the section that looks like -----BEGIN RSA PRIVATE KEY----- +Proc-Type: 4,ENCRYPTED +DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997 +S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T +(11 lines omitted) +1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw== +-----END RSA PRIVATE KEY----- Prev Home Next Staged Deployment for Production Networks Up Set up Log Analysis Reports - OPTIONAL docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-steps.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/install-steps.html 12 Feb 2004 13:51:40 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/install-steps.html 18 Feb 2004 14:43:02 -0000 1.11 @@ -1,15 +1,15 @@ Basic StepsPrev Chapter�2.�Installation Overview Next Basic Steps 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 an OS and supporting software (see Install a Unix-like OS or Appendix�A, Install Red Hat 8/9 for more details). See the Table�2.2, “Version Compatibility Matrix”. Install a database (see Install Oracle or + Install PostgreSQL). Install AOLserver (Install AOLserver 4) . Create a unique database and system user. Install the OpenACS tarball, start and AOLserver instance, and use the OpenACS web pages to complete installation - (see Install OpenACS 5.0.1d1). There are specific instructions available for Mac OS X and + (see Install OpenACS 5.1.0d1). 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 + PostgreSQL in Debian and Red Hat and FreeBSD ports works fine. Once AOLserver and a database are installed, a bash script automates the OpenACS checkout and installation. System Requirements You will need a PC (or equivalent) with at least these minimum @@ -37,9 +37,9 @@ su - service0 svc -d /service/service0 dropdb service0 -createdb service0 Paths and Users Table�2.1.�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 +createdb service0Paths and Users Table�2.1.�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.1d1/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 + files are located at: /tmp/openacs-5.1.0d1/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 Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.html,v diff -u -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 12 Feb 2004 13:51:40 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 18 Feb 2004 14:43:02 -0000 1.8 @@ -1,7 +1,9 @@ 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 -tar xvzf tclwebtest-0.3.tar.gz + place. (tclwebtest 1.0 will be required for auto-tests in OpenACS 5.1. When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) As root: cd /tmp +cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tclwebtest co tclwebtest +#wget http://umn.dl.sourceforge.net/sourceforge/tclwebtest/tclwebtest-1.0.tar.gz +#tar xvzf tclwebtest-1-0.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 Index: openacs-4/packages/acs-core-docs/www/ix01.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/ix01.html 12 Feb 2004 13:51:40 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/ix01.html 18 Feb 2004 14:43:02 -0000 1.6 @@ -1,2 +1,2 @@ -IndexPrev 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 +IndexPrev Index A AOLserver configuration, Installation Option 2: Install from tarball Automated tests, Write automated tests C computeroutput code, Code cvs initializing, Initialize CVS (OPTIONAL) setup, Using CVS with an OpenACS Site D daemontools installation, Install Daemontools (OPTIONAL) docbook installation, Install Red Hat 8/9 DocBook DTD, 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, Installation Option 2: Install from tarball Q qmail installation, Install qmail (OPTIONAL) Maildir, Install qmail (OPTIONAL) rcpthosts error message, Install qmail (OPTIONAL) S sect1, Headlines, Sections sect2, Headlines, Sections Sections Headlines, Headlines, Sections security definition, Install Red Hat 8/9 firewall, Install Red Hat 8/9 sendmail removing, Install qmail (OPTIONAL) 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.x Linux/Unix, Upgrading 4.5 or higher to 4.6.3 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 -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 12 Feb 2004 13:51:40 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 18 Feb 2004 14:43:02 -0000 1.22 @@ -1 +1 @@ -Chapter�12.�Kernel DocumentationPrev Part�IV.�For OpenACS Platform Developers Next Chapter�12.�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 +Chapter�14.�Kernel DocumentationPrev Part�IV.�For OpenACS Platform Developers Next Chapter�14.�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 -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 12 Feb 2004 13:51:40 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 18 Feb 2004 14:43:02 -0000 1.17 @@ -1,4 +1,4 @@ -OverviewPrev Chapter�12.�Kernel Documentation Next Overview +Overview Prev Chapter�14.�Kernel Documentation Next Overview The OpenACS Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package @@ -22,4 +22,4 @@ This document provides a high level overview of the kernel package. Documentation for other packages on this server - Prev Home Next Chapter�12.�Kernel Documentation Up Object Model Requirements docs@openacs.org View comments on this page at openacs.org + Prev Home Next Chapter�14.�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/maint-performance.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/maint-performance.html 12 Feb 2004 13:51:40 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/maint-performance.html 18 Feb 2004 14:43:02 -0000 1.6 @@ -1,7 +1,7 @@ -Diagnosing Performance ProblemsPrev Chapter�6.�Maintenance Next Diagnosing Performance Problems Did performance problems happen overnight, or did they sneak up on +Diagnosing Performance Problems Prev Chapter�6.�Production Environments Next Diagnosing Performance Problems Did performance problems happen overnight, or did they sneak up on you? Any clue what caused the performance problems (e.g. loading 20K - users into .LRN) Is the file system out of space? Is the machine swapping to disk constantly? Isolating and solving database problems. Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see the section called “Vacuum Postgres nightly”. For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes). You can track the exact amount of time each database query on a page takes: Go to Main Site : Site-Wide Administration : Install Software Click on "Install New Application" in "Install from OpenACS Repository" Choose "ACS Developer Support"> After install is complete, restart the server. Browse to Developer Support, which is automatically mounted at /ds. - Turn on Database statistics Browse directly to a slow page and click "Request Information" at the bottom of the page. This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took. Figure�6.1.�Query Analysis example Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process. Log in to SQL*Plus as the admin: [service0 ~]$ svrmgrl + users into .LRN) Is the file system out of space? Is the machine swapping to disk constantly? Isolating and solving database problems. Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see the section called “Vacuum Postgres nightly”. For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes). You can track the exact amount of time each database query on a page takes: Go to Main Site : Site-Wide Administration : Install Software Click on "Install New Application" in "Install from OpenACS Repository" Choose "ACS Developer Support"> After install is complete, restart the server. Browse to Developer Support, which is automatically mounted at /ds. + Turn on Database statistics Browse directly to a slow page and click "Request Information" at the bottom of the page. This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took. Figure�6.8.�Query Analysis example Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process. Log in to SQL*Plus as the admin: [service0 ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production @@ -26,4 +26,4 @@ where sql.address = s.sql_address and sql.hash_value = s.sql_hash_value --and upper(s.username) like 'USERNAME%' - order by s.username ,s.sid ,s.serial# ,sql.piece ; To kill a troubled process: alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL# (See Andrew Piskorski's Oracle notes) ($Id$) Prev Home Next Backup and Recovery Up Appendix�A.�Install Red Hat 8/9 docs@openacs.org View comments on this page at openacs.org + order by s.username ,s.sid ,s.serial# ,sql.piece ; To kill a troubled process: alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL# (See Andrew Piskorski's Oracle notes)
Prev Home Next
External uptime validation Up Chapter�7.�Database Management
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 18 Feb 2004 14:43:02 -0000 1.1 @@ -0,0 +1,4 @@ +Staged Deployment for Production NetworksPrev Chapter�6.�Production Environments Next Staged Deployment for Production Networks By Joel Aufrecht + OpenACS docs are written by the named authors, and may be edited + by OpenACS documentation staff. + This section describes minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested. Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly. The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site. This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly. It does not, by itself, guarantee the entire control chain. You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more. Those additional measures typically take the form of source control tags and system version numbers. The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside. This approach can has limitations. If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle. It also requires extra steps if the database will be affected. Simple Deployment: Database is not changed Figure�6.2.�Simple Deployment - Step 1 Figure�6.3.�Simple Deployment - Step 1 Figure�6.4.�Simple Deployment - Step 1 Complex Deployment: Database is changed Figure�6.5.�Complex Deployment - Step 1 Figure�6.6.�Complex Deployment - Step 1 Figure�6.7.�Complex Deployment - Step 1 Prev Home Next High Availability/High Performance Configurations Up Installing SSL Support docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 18 Feb 2004 14:43:02 -0000 1.19 @@ -1,236 +1,4 @@ -Running OpenACS in Production EnvironmentsPrev Chapter�6.�Maintenance Next Running OpenACS in Production Environments By Joel Aufrecht +Chapter�6.�Production EnvironmentsPrev Part�II.�Administrator's Guide Next Chapter�6.�Production Environments Table of Contents Starting and Stopping an OpenACS instance. AOLserver keepalive with inittab Running multiple services on one machine High Availability/High Performance Configurations Staged Deployment for Production Networks Installing SSL Support Set up Log Analysis Reports - OPTIONAL External uptime validation Diagnosing Performance Problems 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. Starting and Stopping an OpenACS instance. The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/service0/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script. A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers. The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here. Daemontools must already be installed. If not, install it. Each service controlled by daemontools must have a - directory in /service. That - directory must have a file called - run. Daemontools then - creates additional files and directories to track status and - log. A daemontools directory is included in the OpenACS - tarball at - /var/lib/aolserver/service0/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run. [service0 etc]$ killall nsd -nsd: no process killed -[service0 etc]$ exit - -[root root]# ln -s /var/lib/aolserver/service0/etc/daemontools/ /service/service0 Verify that AOLserver is running. [root root]# ps -auxw | grep nsd -service0 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/service0/etc/config.tcl -u serve -root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd -[root root]# The user service0 can now control the service service0 with these commands: - - svc -d /service/service0 - - Bring the server down - - - - svc -u /service/service0 - - Start the server up and leave it in keepalive mode. - - - - svc -o /service/service0 - - Start the server up once. Do not restart it if it stops. - - - - svc -t /service/service0 - - Stop and immediately restart the server. - - - - svc -k /service/service0 - - Sends the server a KILL signal. This is like KILL -9. AOLserver - exits immediately. If svc -t fails to fully kill AOLserver, use - this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately. - - Install a script to automate the stopping and starting - of AOLserver services via daemontools. You can then restart a service via restart-aolserver service0 [root root]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver -[root root]# chmod 755 /usr/local/bin/restart-aolserver -[root root]# - At this point, these commands will work only for the - root user. Grant permission for the web group to use svc commands on the service0 server. [root root]# svgroup web /service/service0 -[root 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 - Mini-HOWTO. - AOLserver keepalive with inittab This is an alternative method for keeping the AOLserver - process running. The recommended method is to run AOLserver - supervised. - This step should be completed as root. This can break every service - on your machine, so proceed with caution. - - There are 2 general steps to getting this working. - - Install a script called - restart-aolserver. This - script doesn't actually restart AOLserver - it just kills - it. - - Ask the OS to restart our service whenever it's not - running. We do this by adding a line to - /etc/inittab. - - Calling restart-aolserver - kills our service. The OS notices that our service is not - running, so it automatically restarts it. Thus, calling - restart-aolserver effectively - restarts our service. - - Copy this file into - /tmp/restart-aolserver.txt. - - This script needs to be SUID-root, which means - that the script will run as root. This is necessary to ensure - that the AOLserver processes are killed regardless of who owns - them. However the script should be executable by the - web group to ensure that the - users updating the web page can use the script, but that - general system users cannot run the script. You also need to - have Perl installed and also a symbolic link to it in - /usr/local/bin. - -[joeuser ~]$ su - -Password: *********** -[root ~]# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver -[root ~]# chown root.web /usr/local/bin/restart-aolserver -[root ~]# chmod 4750 /usr/local/bin/restart-aolserver -[root ~]# ln -s /usr/bin/perl /usr/local/bin/perl -[root ~]# exit - Test the restart-aolserver - script. We'll first kill all running servers to clean the - slate. Then, we'll start one server and use - restart-aolserver to kill - it. If it works, then there should be no more servers - running. You should see the following lines. -[joeuser ~]$ killall nsd -nsd: no process killed -[joeuser ~]$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/birdnotes/nsd.tcl -[joeuser ~]$ restart-aolserver birdnotes -Killing 23727 -[joeuser ~]$ killall nsd -nsd: no process killed - The number 23727 indicates the process id(s) (PIDs) of the - processes being killed. It is important that no processes are killed by the second - call to killall. If there are - processes being killed, it means that the script is not - working. - Assuming that the restart-aolserver - script worked, login as root and open - /etc/inittab for - editing. -[joeuser ~]$ su - -Password: ************ -[root ~]# emacs -nw /etc/inittab - Copy this line into the bottom of the file as a template, - making sure that the first field - nss1 is unique. - -nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl - Important: Make sure there is a - newline at the end of the file. If there is not a newline at - the end of the file, the system may suffer catastrophic - failures. - - Still as root, enter the following command to re-initialize - /etc/inittab. -[root ~]# killall nsd -nsd: no process killed -[root ~]# /sbin/init q - See if it worked by running the - restart-aolserver script - again. -[root ~]# restart-aolserver birdnotes -Killing 23750 - If processes were killed, congratulations, your server is now - 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 - startup, this will be taken care of, but if you ever start the - server from the command line, be sure to su - - first. - - Port 80 is a privileged port. Only certain users - can claim it. When you start nsd as - root, it obtains the port, and then changes to run as whatever user - you specify in the server configuration file. This ensures a high - level of security, as the server, once started, is not running as - root. This mean that if someone was - 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.1d1 replacing - service0, and change the - set httpport 8000 -set httpsport 8443 - to different values. Services on different host names.�For example, suppose you want to support -http://foo.com and - http://bar.com on the same - machine. The easiest way is to assign each one a different ip - address. Then you can install two services as above, but with - different values for - set hostname [ns_info hostname] -set address 127.0.0.1 - If you want to install two services with different host - names sharing the same ip, you'll need nsvhr to redirect requests - based on the contents of the tcp headers. See AOLserver - Virtual Hosting with TCP by markd. - 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 etc]$ mkdir /var/lib/aolserver/service0/etc/certs -[service0 etc]$ chmod 700 /var/lib/aolserver/service0/etc/certs -[service0 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 service0]$ cd /var/lib/aolserver/service0/etc/certs -[service0 certs]$ perl /usr/share/ssl/misc/CA -newcert -Using configuration from /usr/share/ssl/openssl.cnf -Generating a 1024 bit RSA private key -...++++++ -.......++++++ -writing new private key to 'newreq.pem' -Enter PEM pass phrase: Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this: Certificate (and private key) is in newreq.pem -[service0 certs]$ newreq.pem contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site. [root misc]# openssl rsa -in newreq.pem -out keyfile.pem -read RSA key -Enter PEM pass phrase: -writing RSA key -[service0 certs]$ To create the certificate file, we take the combined file, copy it, and strip out the key. [service0 certs]$ cp newreq.pem certfile.pem -[root misc]# emacs certfile.pem Strip out the section that looks like -----BEGIN RSA PRIVATE KEY----- -Proc-Type: 4,ENCRYPTED -DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997 -S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T -(11 lines omitted) -1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw== ------END RSA PRIVATE KEY----- Set up Log Analysis Reports - OPTIONAL Analog is a program with processes webserver access logs, - performs DNS lookup, and outputs HTML reports. Analog should - already be - installed. A modified configuration file is included in - the OpenACS tarball. [root src]# su - service0 -[service0 service0]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg -[service0 service0]$ mkdir www/log -[service0 service0]$ cp -r /usr/share/analog-5.31/images www/log/ -[service0 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 -/var/lib/aolserver/service0/etc/analog.cfg and change the variable in HOSTNAME "[my -organisation]" to reflect your website title. If you -don't want the traffic log to be publicly visible, change -OUTFILE /var/lib/aolserver/service0/www/log/traffic.html to use a private -directory. Run it. [service0 service0]$ /usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg -/usr/share/analog-5.31/analog: analog version 5.31/Unix -/usr/share/analog-5.31/analog: Warning F: Failed to open DNS input file - /home/service0/dnscache: ignoring it - (For help on all errors and warnings, see docs/errors.html) -/usr/share/analog-5.31/analog: Warning R: Turning off empty Search Word Report -[service0 service0]$ Verify that it works by browing to http://yourserver.test:8000/log/traffic.html Automate this by creating a file in - /etc/cron.daily. [service0 service0]$ exit -logout - -[root root]# emacs /etc/cron.daily/analog Put this into the file: #!/bin/sh - -/usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg [root root]# chmod 755 /etc/cron.daily/analog Test it by running the script. [root root]# sh /etc/cron.daily/analog Browse to http://yourserver.test/log/traffic.html External uptime validation The OpenACS uptime site can monitor your site and send you an email whenever your site fails to respond. If you test the url http://yourserver.test/SYSTEM/dbtest.tcl, you should get back the string success. ($Id$) Prev Home Next Chapter�6.�Maintenance Up Database Management docs@openacs.org View comments on this page at openacs.org + Maintenance tasks, optional software, and alternate configurations for AOLserver. ($Id$) Prev Home Next Upgrading Platform components Up Starting and Stopping an OpenACS instance. docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/nxml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/nxml-mode.html,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/nxml-mode.html 12 Feb 2004 13:51:40 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/nxml-mode.html 18 Feb 2004 14:43:02 -0000 1.5 @@ -1,4 +1,4 @@ -Using nXML mode in EmacsPrev Chapter�11.�Documentation Standards Next Using nXML mode in Emacs By Jeff Davis +Using nXML mode in EmacsPrev Chapter�13.�Documentation Standards Next Using nXML mode in Emacs By Jeff Davis OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/object-identity.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,18 +1,18 @@ -Object Identity Prev Chapter�9.�Development Reference Next Object Identity By Rafael H. Schloming +Object IdentityPrev Chapter�11.�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.1d1 is the explicit representation + One of the major design features of OpenACS 5.1.0d1 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.1d1 data model this +scope) to identify an object. In the 5.1.0d1 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.1d1 data model this +object (the person's membership in a group). In the 5.1.0d1 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 Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 18 Feb 2004 14:43:02 -0000 1.21 @@ -1,4 +1,4 @@ -Object Model Design Prev Chapter�12.�Kernel Documentation Next Object Model Design By Pete Su, Michael Yoon, Richard Li, Rafael Schloming +Object Model DesignPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 18 Feb 2004 14:43:02 -0000 1.20 @@ -1,4 +1,4 @@ -Object Model Requirements Prev Chapter�12.�Kernel Documentation Next Object Model Requirements By Pete Su +Object Model RequirementsPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/objects.html 12 Feb 2004 13:51:40 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/objects.html 18 Feb 2004 14:43:02 -0000 1.28 @@ -1,8 +1,8 @@ -OpenACS Data Models and the Object System Prev Chapter�9.�Development Reference Next OpenACS Data Models and the Object System By Pete Su +OpenACS Data Models and the Object SystemPrev Chapter�11.�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.1d1 is much like developing data models +Developing data models in OpenACS 5.1.0d1 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 @@ -78,7 +78,7 @@ 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 + 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 + 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 + 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 + 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.1d1 data +There are two basic rules you should follow when designing OpenACS 5.1.0d1 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.1d1 object system brings the application developer +Hooking into the OpenACS 5.1.0d1 object system brings the application developer numerous benefits, and doing it involves only four easy steps: Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v diff -u -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 12 Feb 2004 13:51:40 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 18 Feb 2004 14:43:02 -0000 1.14 @@ -1,17 +1,17 @@ Unpack the OpenACS tarball Prev Appendix�B.�Install additional supporting software Next Unpack the OpenACS tarball The OpenACS tarball contains sample configuration files for some of the packages listed below. In order to access those files, unpack the tarball now. [root root]# cd /tmp -[root tmp]# tar xzf openacs-5.0.1d1.tgz +[root tmp]# tar xzf openacs-5.1.0d1.tgz cd /tmp -tar xzf openacs-5.0.1d1.tgz If you are installing from a different method and just need the configuration files, you can instead get them from CVS: [root root]# cd /tmp +tar xzf openacs-5.1.0d1.tgz If you are installing from a different method and just need the configuration files, you can instead get them from CVS: [root root]# cd /tmp [root tmp]# cvs -d :pserver:anonymous@openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ cvs checkout: warning: failed to open /root/.cvspass for reading: No such file or directory cvs server: Updating openacs-4/packages/acs-core-docs/www/files U openacs-4/packages/acs-core-docs/www/files/README.TXT (many lines omitted) U openacs-4/packages/acs-core-docs/www/files/template-ini.ini U openacs-4/packages/acs-core-docs/www/files/winnsd.txt -[root tmp]# mv openacs-4 openacs-5.0.1d1 +[root tmp]# mv openacs-4 openacs-5.1.0d1 cd /tmp cvs -d :pserver:anonymous@openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ mv openacs-4 openacs-5.0.0a4 Prev Home Next Appendix�B.�Install additional supporting software Up Initialize CVS (OPTIONAL) docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/openacs.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/openacs.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,4 +1,4 @@ -Install OpenACS 5.0.1d1Prev Chapter�3.�Complete Installation Next Install OpenACS 5.0.1d1 by Vinod Kurup +Install OpenACS 5.1.0d1Prev Chapter�3.�Complete Installation Next Install OpenACS 5.1.0d1 by Vinod Kurup 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, @@ -35,7 +35,7 @@ can use database and server commands associated with that group. [root root]# useradd service0 -[root root]# Install with automated script A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation. Get the install script from CVS. It is located within +[root root]# Installation Option 1: Use automated script A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation. Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the service's dedicated user. We put it there so that it is not @@ -63,14 +63,14 @@ admin email : admin@yourserver.net admin password: xxxx ###################################################################### -[root root]# You can proceed to the section called “Next Steps”. Install from tarball You should already have downloaded the OpenACS tarball +[root root]# You can proceed to the section called “Next Steps”. Installation Option 2: Install from tarball You should already have downloaded the OpenACS tarball to the /tmp directory. If not, download the OpenACS 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 root]# su - service0 [service0 service0]$ cd /var/lib/aolserver -[service0 aolserver]$ tar xzf /tmp/openacs-5.0.1d1.tgz -[service0 aolserver]$ mv openacs-5.0.1d1 service0 +[service0 aolserver]$ tar xzf /tmp/openacs-5.1.0d1.tgz +[service0 aolserver]$ mv openacs-5.1.0d1 service0 [service0 aolserver]$ chmod -R 775 service0 [service0 aolserver]$ chown -R service0.service0 service0 [service0 aolserver]$ ls -al @@ -83,8 +83,8 @@ [root root]# su - service0 cd /var/lib/aolserver -tar xzf /tmp/openacs-5.0.1d1.tgz -mv openacs-5.0.1d1 service0 +tar xzf /tmp/openacs-5.1.0d1.tgz +mv openacs-5.1.0d1 service0 chmod -R 755 service0 chgrp -R service0.service0 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 @@ -196,7 +196,7 @@ SVRMGR> alter user service0 quota unlimited on service0; SVRMGR> exit; Your table space is now ready. In case you are trying to delete a - previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below. + previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below. Make sure that you can login to Oracle using your service_name account: [service0 ~]$ sqlplus service0/service0password @@ -220,15 +220,15 @@ CREATE DATABASE [service0 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 service0]$ export EDITOR=emacs;crontab -e Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information. 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze 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 service0]$ export EDITOR=emacs;crontab -e Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information. 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0 0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0 Add Full Text Search Support (OPTIONAL) At this point the database should be ready for installing OpenACS. Configure an AOLserver Service for OpenACS.� The AOLserver architecture lets you run an arbitrary number of virtual servers. A virtual server is an HTTP service running on a specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /var/lib/aolserver/service0/etc/config.tcl. - Open it in an editor to adjust the parameters. [root root]# su - service0 + Open it in an editor to adjust the parameters. [root root]# su - service0 [service0 service0]$ cd /var/lib/aolserver/service0/etc [service0 etc]$ emacs config.tcl @@ -252,10 +252,10 @@ 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 + 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. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/service0/packages/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run. If you want to use port 80, there are complications. AOLserver must be root to use system ports such as + one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/service0/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run. If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the @@ -285,11 +285,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.1d1. + 5.1.0d1. You should see a page from the webserver titled OpenACS Installation: @@ -339,20 +339,20 @@ 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 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.1d1 is now up and running! - Next Steps Use daemontools supervice and svc, or inittab, to automate server startup and shutdown. Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled + 5.1.0d1 is now up and running! + Installation Option 3: Install from CVS If you want to track fresh code developments inbetween releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: CVS Checkout Instructions. So, instead of tar xzf /tmp/openacs-5.1.0d1.tgz, cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co acs-core. Next Steps Use daemontools supervice and svc, or inittab, to automate server startup and shutdown. Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled OpenFTS, you can now install the OpenFTS Driver package and - Full Text Search Engine package in the OpenACS service. This is a good time to make a backup of your service. If this is a - production site, you should set up automatic nightly backups. If you want traffic reports, set up analog or another log + Full Text Search Engine package in the OpenACS service. This is a good time to make a backup of your service. If this is a + production site, you should set up automatic nightly backups. If you want traffic reports, set up analog or another log processing program. Follow the instruction on the home page to change the appearance of your service or add more - packages. (more information) Proceed to the tutorial to learn how to develop your own packages. Set up database environment variables for the site + packages. (more information) Proceed to the tutorial to learn how to develop your own packages. Set up database environment variables for the site user. Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the database while logged in as the service user. They do not directly affect the service's run-time connection with the @@ -384,4 +384,4 @@ LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib ORACLE_SID=ora8 ORACLE_TERM=vt100 -ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data Test your backup and recovery procedure. Set up the section called “External uptime validation”. ($Id$) Prev Home Next Install AOLserver 4 Up OpenACS Installation Guide for Windows2000 docs@openacs.org View comments on this page at openacs.org +ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data Test your backup and recovery procedure. Set up the section called “External uptime validation”. ($Id$) Prev Home Next Install AOLserver 4 Up OpenACS Installation Guide for Windows2000 docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/oracle.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/oracle.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -4,7 +4,7 @@ Note Skip this section if you're not interested in Oracle. - OpenACS 5.0.1d1 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. + OpenACS 5.1.0d1 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. This document assumes that you'll be installing Oracle on the same Index: openacs-4/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/packages.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/packages.html 18 Feb 2004 14:43:02 -0000 1.27 @@ -1,4 +1,4 @@ -OpenACS Packages Prev Chapter�9.�Development Reference Next OpenACS Packages By Pete Su and Bryan Quinn +OpenACS PackagesPrev Chapter�11.�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 @@ -56,7 +56,7 @@ 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.1d1 server is laid out: + Here is how an OpenACS 5.1.0d1 server is laid out: ROOT/ bin/ @@ -123,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.1d1, this tool is called the APM. + removal. In OpenACS 5.1.0d1, 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 @@ -145,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.1d1 that take advantage of the APM's package + management features in OpenACS 5.1.0d1 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. @@ -433,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.1d1, administrators can define an arbitrary mapping between the + In OpenACS 5.1.0d1, 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 @@ -491,4 +491,4 @@ Writes out package distribution files for other people to download and install. We'll cover this later. - Additional Reading Package Manager Design Package Manager Requirements package development tutorial ($Id$) Prev Home Next Chapter�9.�Development Reference Up OpenACS Data Models and the Object System docs@openacs.org View comments on this page at openacs.org + Additional Reading Package Manager Design Package Manager Requirements package development tutorial ($Id$)
Prev Home Next
Chapter�11.�Development Reference Up OpenACS Data Models and the Object System
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/parties.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/parties.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -Parties in OpenACSPrev Chapter�9.�Development Reference Next Parties in OpenACS By Rafael H. Schloming +Parties in OpenACSPrev Chapter�11.�Development Reference Next Parties in OpenACS By Rafael H. Schloming 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 Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 18 Feb 2004 14:43:03 -0000 1.20 @@ -1,4 +1,4 @@ -Permissions Design Prev Chapter�12.�Kernel Documentation Next Permissions Design By John Prevost and Rafael H. Schloming +Permissions DesignPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 18 Feb 2004 14:43:03 -0000 1.20 @@ -1,4 +1,4 @@ -Permissions Requirements Prev Chapter�12.�Kernel Documentation Next Permissions Requirements By John McClary Prevost +Permissions RequirementsPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 18 Feb 2004 14:43:03 -0000 1.21 @@ -1,4 +1,4 @@ -OpenACS Permissions Tediously Explained Prev Chapter�9.�Development Reference Next OpenACS Permissions Tediously Explained +OpenACS Permissions Tediously Explained Prev Chapter�11.�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 out of date. See this forum thread. Overview The general permissions system has a relatively complex data model in OpenACS. @@ -100,7 +100,7 @@ Context Hierarchy Suppose objects A, B, ..., and F form the following hierarchy. - Table�9.1.�Context Hierarchy Example A + Table�11.1.�Context Hierarchy Example A object_id=10 B object_id=20 @@ -116,7 +116,7 @@ This can be represented in the acs_objects table by the following entries: - Table�9.2.�acs_objects example data object_id context_id 20 10 30 10 40 20 50 20 60 30 + Table�11.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, 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 -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/permissions.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/permissions.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,8 +1,8 @@ -Groups, Context, Permissions Prev Chapter�9.�Development Reference Next Groups, Context, Permissions By Pete Su +Groups, Context, PermissionsPrev Chapter�11.�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.1d1 Permissions system allows developers and administrators to +The OpenACS 5.1.0d1 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.1d1 has two auxiliary mechanisms for making this +site. Therefore, OpenACS 5.1.0d1 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.1d1 object type system, +contained a meta-data system much like the OpenACS 5.1.0d1 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.1d1 solves both of these modeling problems by introducing a new +OpenACS 5.1.0d1 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.1d1, a privilege models the right to perform some operation on +In OpenACS 5.1.0d1, 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.1d1, +read. write or execute privileges on files and directories. In OpenACS 5.1.0d1, 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.1d1 kernel data model actually defines these +contains. The OpenACS 5.1.0d1 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.1d1, an object context is a generalization of the scoping +In OpenACS 5.1.0d1, 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.1d1, rather than breaking the world into a limited set of scopes, +In OpenACS 5.1.0d1, 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.1d1, +privileges whenever we create a message, which is tedious. In OpenACS 5.1.0d1, 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 @@ -224,15 +224,13 @@ security_inherit_p is 'f', or context_id is null, then we use this context by default. Example - At this point, you should either go and download the Notes example 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 notes: - - % export CVSROOT=:pserver:anonymous@openacs.org:/cvsroot + The notes code has been modified since this document was written so it is now out of date. See this forum thread. % export CVSROOT=:pserver:anonymous@openacs.org:/cvsroot % cvs login # just hit enter when prompted for a password % cvs co notes @@ -328,7 +326,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.1d1 template system +The if tag is something that the OpenACS 5.1.0d1 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 @@ -342,7 +340,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.1d1 defines three separate mechanisms for specifying access control +OpenACS 5.1.0d1 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, 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 -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/postgres.html 12 Feb 2004 13:51:40 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/postgres.html 18 Feb 2004 14:43:03 -0000 1.26 @@ -31,13 +31,25 @@ 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. Safe approach: install from source Unpack PostgreSQL.�If you have not downloaded the postgresql tarball to +su - postgres ... and then skip to 8. Something similar may work for other binary packages as well. Safe approach: install from source Unpack PostgreSQL 7.3.4.�If you have not downloaded the postgresql tarball to /tmp/postgresql-7.3.4.tar.gz, get it. [root root]# cd /usr/local/src [root src]# tar xzf /tmp/postgresql-7.3.4.tar.gz [root src]# cd /usr/local/src -tar xzf /tmp/postgresql-7.3.4.tar.gz Create the Postgres user.� +tar xzf /tmp/postgresql-7.3.4.tar.gz ALTERNATIVE: Unpack PostgreSQL 7.4.1.�If you have not downloaded the postgresql tarball to + /tmp/postgresql-7.4.1.tar.bz2, + get it. [root root]# cd /usr/local/src +[root src]# tar xfj /tmp/postgresql-7.4.1.tar.bz2 +[root src]# +cd /usr/local/src +tar xfj /tmp/postgresql-7.4.1.tar.bz2 Install Bison.�Only do this if bison --version is smaller than 1.875 and you install PostgreSQL 7.4. [root root]# cd /usr/local/src +[root src]# wget http://ftp.gnu.org/gnu/bison/bison-1.875.tar.gz +[root src]# tar xfz bison-1.875.tar.gz +[root src]# cd bison-1.875 +[root src]# ./configure +[root src]# make install + 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 @@ -52,16 +64,23 @@ 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 Mac OS X: Do instead: sudo niutil -create / /groups/web -sudo niutil - list / /groups The second command returns a list of groups. The last entry should include the gid of the group web, which you will need in the next sequence: sudo niutil -create / /users/postgres -sudo niutil -createprop / /users/postgres gid web's gid_number +chmod 750 /usr/local/pgsql Mac OS X: Do instead:�First make sure the gids and uids below are available (change them if +they are not).To list taken uids and gids: nireport / /groups name gid | grep "[0123456789][0123456789]" +nireport / /users name uid | grep "[0123456789][0123456789]" + Now you can install the users sudo niutil -create / /groups/web +sudo niutil -createprop / /groups/web gid 201 +sudo niutil -create / /users/postgres +sudo niutil -createprop / /users/postgres gid 201 +sudo niutil -createprop / /users/postgres uid 502 sudo niutil -createprop / /users/postgres home /usr/local/pgsql -sudo niutil -createprop / /users/postgres shell /bin/bash +sudo niutil -create / /users/service0 +sudo niutil -createprop / /users/service0 gid 201 +sudo niutil -createprop / /users/service0 uid 201 mkdir -p /usr/local/pgsql -chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4 +chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.1 chmod 750 /usr/local/pgsql Set up postgres's environment variables.�They are necessary for the executable to find its supporting libraries. Put the following lines into the postgres user's environment. [root src]# su - postgres -[postgres ~] emacs ~postgres/.bashrc Paste these lines into .bashrc: export PATH=$PATH:/usr/local/pgsql/bin +[postgres ~] emacs ~postgres/.bashrc Paste this line into .bash_profile: source $HOME/.bashrc Paste these lines into .bashrc: export PATH=/usr/local/bin/:$PATH:/usr/local/pgsql/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib Test this by logging in as postgres and checking the paths; you should see /usr/local/pgsql/bin [root src]# su - postgres @@ -73,10 +92,11 @@ 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. On debian woody (stable, 3.0), do ./configure --without-readline --without-zlib. [root src]# su - postgres [postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4 -[postgres postgresql-7.3.4]$ ./configure +[postgres postgresql-7.3.4]$ ./configure --with-includes=/sw/include/ --with-libraries=/sw/lib --enable-locale --enable-multibyte \ + --enable-syslog --enable-unicode-conversion --enable-recode creating cache ./config.cache checking host system type... i686-pc-linux-gnu (many lines omitted> @@ -168,13 +188,13 @@ bunch of symlinks that ensure that, when the operating system changes runlevels, postgresql goes to the appropriate state. Red Hat and Debian and SuSE each work a little - differently. If you haven't untarred the OpenACS tarball, you will need to do so now to access the postgresql.txt file. + differently. If you haven't untarred the OpenACS tarball, you will need to do so now to access the postgresql.txt file. Red Hat RPM: The init script is already installed; just turn it on for the appropriate run levels. [root root]# chkconfig --level 345 postgresql on -[root root]# Red Hat from source: [root src]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql +[root root]# Red Hat from source: [root src]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql [root src]# chown root.root /etc/rc.d/init.d/postgresql [root src]# chmod 755 /etc/rc.d/init.d/postgresql [root src]# -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql +cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql chown root.root /etc/rc.d/init.d/postgresql chmod 755 /etc/rc.d/init.d/postgresql Test the script. [root root]# service postgresql stop Stopping PostgreSQL: ok @@ -197,7 +217,7 @@ [root ~]# chown root.root /etc/init.d/postgresql [root ~]# chmod 755 /etc/init.d/postgresql [root ~]# -cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql +cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql chown root.root /etc/init.d/postgresql chmod 755 /etc/init.d/postgresql Test the script [root ~]# /etc/init.d/postgresql stop Stopping PostgreSQL: ok @@ -225,7 +245,7 @@ rc.d/ part in each of the following commands. - [root ~]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql + [root ~]# cp /tmp/openacs-5.1.0d1/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 @@ -286,7 +306,7 @@ # Write-ahead log (WAL) # checkpoint_segments = 3 # in logfile segments (16MB each), min 1 - Restart postgres (Redhat: service postgresql restart. Many other systems: <computertext>/etc/init.d/postgresql restart</computertext>) so that the changes take effect. more information about PostgreSQL + Restart postgres (Redhat: service postgresql restart. Many other systems: /etc/init.d/postgresql restart) so that the changes take effect. more information about PostgreSQL Official PostgreSQL Docs Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -Programming with AOLserver Prev Chapter�9.�Development Reference Next Programming with AOLserver By Michael Yoon, Jon Salz and Lars Pind. +Programming with AOLserverPrev Chapter�11.�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 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 -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 12 Feb 2004 13:51:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 18 Feb 2004 14:43:03 -0000 1.18 @@ -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 tmp]# cp /tmp/openacs-5.0.1d1/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs + terminals. [root tmp]# cp /tmp/openacs-5.1.0d1/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs cp: overwrite `/etc/skel/.emacs'? y [root 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) docs@openacs.org 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 -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -Using PSGML mode in EmacsPrev Chapter�11.�Documentation Standards Next Using PSGML mode in Emacs By David Lutterkort +Using PSGML mode in EmacsPrev Chapter�13.�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. Note: nxml mode replaces and/or complements psgml mode. More information. What it is PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It Index: openacs-4/packages/acs-core-docs/www/release-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/release-notes.html 12 Feb 2004 13:51:40 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/release-notes.html 18 Feb 2004 14:43:03 -0000 1.31 @@ -7,7 +7,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.1d1, but an alternative is to use John + not current for OpenACS 5.1.0d1, but an alternative is to use John Sequeira's Oasis VM project. @@ -95,4 +95,4 @@ 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 docs@openacs.org View comments on this page at openacs.org + ($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 docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/remote-postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/remote-postgres.html 18 Feb 2004 14:43:03 -0000 1.1 @@ -0,0 +1,11 @@ +Running a PostgreSQL database on another serverPrev Chapter�7.�Database Management Next 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 + Reference install is located at /usr/local/pgsql/data/postgresql.conf + and change #tcpip_socket = false to tcpip_socket = true Change the access control file for the database to + permit specific remote clients to access. Access can be + controlled ... (add notes from forum post) Change the OpenACS service's configuration file to + point to the remote database. Edit + /var/lib/aolserver/service0/etc/config.tcl + and change to Prev Home Next Chapter�7.�Database Management Up Deleting a tablespace docs@openacs.org 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 -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/request-processor.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/request-processor.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,12 +1,12 @@ -The Request ProcessorPrev Chapter�9.�Development Reference Next The Request Processor By Pete Su +The Request ProcessorPrev Chapter�11.�Development Reference Next The Request Processor By Pete Su 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.1d1 Request Processor; +This document is a brief introduction to the OpenACS 5.1.0d1 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.1d1 Request Processor is a global filter and set of Tcl procs that +The 5.1.0d1 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. @@ -35,7 +35,7 @@ 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.1d1, access control +privileges to the requested part of the site. In OpenACS 5.1.0d1, 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 -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -System/Application Requirements Template Prev Chapter�11.�Documentation Standards Next System/Application Requirements Template By You +System/Application Requirements TemplatePrev Chapter�13.�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 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 -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/rp-design.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 18 Feb 2004 14:43:03 -0000 1.21 @@ -1,4 +1,4 @@ -Request Processor Design Prev Chapter�12.�Kernel Documentation Next Request Processor Design By Rafael H. Schloming +Request Processor DesignPrev Chapter�14.�Kernel Documentation Next Request Processor Design By Rafael H. Schloming OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. Essentials OpenACS 4 Request Processor Requirements Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/rp-requirements.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 18 Feb 2004 14:43:03 -0000 1.19 @@ -1,4 +1,4 @@ -Request Processor Requirements Prev Chapter�12.�Kernel Documentation Next Request Processor Requirements By Rafael H. Schloming +Request Processor RequirementsPrev Chapter�14.�Kernel Documentation Next Request Processor Requirements By Rafael H. Schloming 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 Index: openacs-4/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v diff -u -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/security-design.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/security-design.html 18 Feb 2004 14:43:03 -0000 1.21 @@ -1,4 +1,4 @@ -Security Design Prev Chapter�12.�Kernel Documentation Next Security Design By Richard Li and Archit Shah +Security DesignPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/security-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/security-notes.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/security-notes.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -Security Notes Prev Chapter�12.�Kernel Documentation Next Security Notes By Richard Li +Security NotesPrev Chapter�14.�Kernel Documentation Next Security Notes By Richard Li OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/security-requirements.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/security-requirements.html 18 Feb 2004 14:43:03 -0000 1.20 @@ -1,4 +1,4 @@ -Security Requirements Prev Chapter�12.�Kernel Documentation Next Security Requirements By Richard Li +Security RequirementsPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/snapshot-backup.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/snapshot-backup.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/snapshot-backup.html 18 Feb 2004 14:43:03 -0000 1.1 @@ -0,0 +1,132 @@ +Manual backup and recovery Prev Chapter�8.�Backup and Recovery Next 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 - +[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 + +(c) Copyright 1999 Oracle Corporation. All rights reserved. + +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 root]# su - service0 +[service0 service0]$ pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp service0 +[service0 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 service0]$ exit +[root 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 z compresses the output with gzip. 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 root]# su - service0 +[service0 service0]$ tar -cpsz --exclude /var/lib/aolserver/service0/etc/daemontools/supervise \ + --file /tmp/service0-backup.tar.gz /var/lib/aolserver/service0/ +tar: Removing leading `/' from member names +[service0 service0]$ Suffer a catastrophic failure on your production system.�(We'll simulate this step) [root root]# svc -d /service/service0 +[root root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost +[root root]# rm /service/service0 +rm: remove symbolic link `/service/service0'? y +[root root]# ps -auxw | grep service0 +root 1496 0.0 0.0 1312 252 ? S 16:58 0:00 supervise service0 +[root root]# kill 1496 +[root root]# ps -auxw | grep service0 +[root root]# su - postgres +[postgres pgsql]$ dropdb service0 +DROP DATABASE +[postgres pgsql]$ dropuser service0 +DROP USER +[postgres pgsql]$ exit +logout +[root 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 root]# su - service0 +[service0 service0]$ cd /var/lib/aolserver +[service0 aolserver]$ tar xzf /tmp/service0-backup.tar.gz +[service0 aolserver]$ chmod -R 775 service0 +[service0 aolserver]$ chown -R service0.web service0 Restore the database Oracle.� Set up a clean Oracle database user and + tablespace with the same names as the ones exported from (more information). Invoke the import command imp service0/service0 FILE=/var/lib/aolserver/service0/database-backup/nighty_backup.dmp FULL=Y Postgres.�If the database user does not already exist, create it. [root root]# su - postgres +[postgres ~]$ 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 +[postgres ~]$ exit + Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects. Next, restore the database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored. [root root]# su - service0 +[service0 ~]$ createdb service0 +CREATE DATABASE +[service0 ~]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0 +(many lines omitted) +[service0 ~]$ psql service0 < /var/lib/aolserver/service0/database-backup/database-backup.dmp +(many lines omitted) +[service0 ~]$ exit +[postgres ~]$ exit +logout Activate the service [root root]# ln -s /var/lib/aolserver/service0/etc/daemontools /service/service0 +[root root]# sleep 10 +[root root]# svgroup web /service/service0 Prev Home Next Backup Strategy Up Automated Backup (OPTIONAL) docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/style-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/style-guide.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/style-guide.html 12 Feb 2004 13:51:40 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/style-guide.html 18 Feb 2004 14:43:03 -0000 1.6 @@ -1,4 +1,4 @@ -OpenACS Style GuidePrev Chapter�10.�Engineering Standards Next OpenACS Style Guide +OpenACS Style Guide Prev Chapter�12.�Engineering Standards Next OpenACS Style Guide By Jeff Davis Motivation Why have coding standards for OpenACS? And if the code works why change it to @@ -87,4 +87,4 @@ Solicit code reviews.� Ask others to look over your code and provide feedback and do the same for others. - Revision History Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 12/2003 Jeff Davis ($Id$) Prev Home Next Chapter�10.�Engineering Standards Up Release Version Numbering docs@openacs.org View comments on this page at openacs.org + Revision History Document Revision # Action Taken, Notes When? By Whom? 0.1 Creation 12/2003 Jeff Davis ($Id$) Prev Home Next Chapter�12.�Engineering Standards Up Release Version Numbering docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v diff -u -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/subsites-design.html 12 Feb 2004 13:51:40 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/subsites-design.html 18 Feb 2004 14:43:03 -0000 1.21 @@ -1,4 +1,4 @@ -Subsites Design DocumentPrev Chapter�12.�Kernel Documentation Next Subsites Design Document By Rafael H. Schloming +Subsites Design DocumentPrev Chapter�14.�Kernel Documentation Next Subsites Design Document By Rafael H. Schloming 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 Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 18 Feb 2004 14:43:03 -0000 1.20 @@ -1,4 +1,4 @@ -Subsites Requirements Prev Chapter�12.�Kernel Documentation Next Subsites Requirements By Rafael H. Schloming and Dennis Gregorovic +Subsites RequirementsPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/subsites.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/subsites.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/subsites.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -Writing OpenACS Application Pages Prev Chapter�9.�Development Reference Next Writing OpenACS Application Pages By Rafael H. Schloming and Pete Su +Writing OpenACS Application PagesPrev Chapter�11.�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 @@ -84,13 +84,13 @@ set package_id [ad_conn package_id] if {[info exists note_id]} { - ad_require_permission $note_id write + permission::require_permission -object_id $note_id -privilege write - set context_bar [ad_context_bar "Edit Note"] + set context_bar [ad_context_bar "Edit Note"] } else { - ad_require_permission $package_id create + permission::require_permission -object_id $note_id -privilege create - set context_bar [ad_context_bar "New Note"] + set context_bar [ad_context_bar "New Note"] } @@ -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.1d1 +This is a good example of the leverage available in the OpenACS 5.1.0d1 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.1d1, application pages and scripts can be aware of the package +In OpenACS 5.1.0d1, 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. Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/tcl-doc.html 12 Feb 2004 13:51:40 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 18 Feb 2004 14:43:03 -0000 1.28 @@ -1,4 +1,4 @@ -Documenting Tcl Files: Page Contracts and Libraries Prev Chapter�12.�Kernel Documentation Next Documenting Tcl Files: Page Contracts and Libraries By Jon Salz on 3 July 2000 +Documenting Tcl Files: Page Contracts and LibrariesPrev Chapter�14.�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 Index: openacs-4/packages/acs-core-docs/www/templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/templates.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/templates.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,4 +1,4 @@ -Using Templates in OpenACS Prev Chapter�9.�Development Reference Next Using Templates in OpenACS By Pete Su +Using Templates in OpenACSPrev Chapter�11.�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 Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -Admin Pages Prev Chapter�8.�Advanced Topics Next Admin Pages +Admin Pages Prev Chapter�10.�Advanced Topics Next Admin Pages There are at least two flavors of admin user interface: Admins use same pages as all other users, except that they are offered admin links and buttons where appropriate. @@ -34,7 +34,9 @@ set package_id [ad_conn package_id] -set admin_p [ad_require_permission $package_id admin] +permission::require_permission \ + -object_id $package_id \ + -privilege admin] set context [list] 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 -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 18 Feb 2004 14:43:03 -0000 1.19 @@ -1,4 +1,4 @@ -Chapter�8.�Advanced Topics Prev Part�III.�For OpenACS Package Developers Next Chapter�8.�Advanced Topics Table of Contents Write the Requirements and Design Specs Add the new package to CVS Adding Comments Admin Pages Categories Categories Prepare the package for distribution. Notifications Using .vuh files for pretty urls by Joel Aufrecht +Chapter�10.�Advanced TopicsPrev Part�III.�For OpenACS Package Developers Next Chapter�10.�Advanced Topics Table of Contents Write the Requirements and Design Specs Add the new package to CVS Adding Comments Admin Pages Categories Categories Prepare the package for distribution. Notifications Using .vuh files for pretty urls by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. This tutorial covers topics which are not essential to Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-categories.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-categories.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -Categories Prev Chapter�8.�Advanced Topics Next Categories You can associate any ACS Object with one or more categories. +Categories Prev Chapter�10.�Advanced Topics Next Categories You can associate any ACS Object with one or more categories. In this tutorial we'll show how to equip your application with user interface to take advantage of the Categories service. @@ -135,4 +135,4 @@ 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. Prev Home Next Admin Pages Up Categories docs@openacs.org View comments on this page at openacs.org + samplenotes. Prev Home Next Admin Pages Up Categories docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-comments.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-comments.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-comments.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-comments.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -Adding CommentsPrev Chapter�8.�Advanced Topics Next Adding Comments You can track comments for any ACS Object. Here we'll track +Adding Comments Prev Chapter�10.�Advanced Topics Next Adding Comments You can track comments for any ACS Object. Here we'll track comments for notes. On the note-edit.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 Index: openacs-4/packages/acs-core-docs/www/tutorial-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-cvs.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -Add the new package to CVS Prev Chapter�8.�Advanced Topics Next Add the new package to CVS Before you do any more work, make sure that your work is +Add the new package to CVS Prev Chapter�10.�Advanced Topics Next 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 @@ -58,4 +58,4 @@ initial revision: 1.1 done (many lines omitted) -[service0 myfirstpackage]$ Prev Home Next Write the Requirements and Design Specs Up Adding Comments docs@openacs.org View comments on this page at openacs.org +[service0 myfirstpackage]$Figure�10.1.�Upgrading a local CVS repository Prev Home Next Write the Requirements and Design Specs Up Adding Comments docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/tutorial-database.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/tutorial-database.html 18 Feb 2004 14:43:03 -0000 1.19 @@ -1,7 +1,7 @@ -Setting Up Database ObjectsPrev Chapter�7.�Development Tutorial Next Setting Up Database Objects by Joel Aufrecht +Setting Up Database ObjectsPrev Chapter�9.�Development Tutorial Next Setting Up Database Objects by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Code the data model We create all database objects with scripts in the + Code the data model We create all database objects with scripts in the myfirstpackage/sql/ directory. All database scripts are database-specific and are thus in either the myfirstpackage/sql/oracle or @@ -31,13 +31,13 @@ repository functions to simplify our database creation. (More information about ACS Objects. More information about the Content Repository.) - Figure�7.2.�Tutorial Data Model The top of each sql file has some + Figure�9.2.�Tutorial Data Model The top of each sql file has some standard comments, including doc tags such as @author which will be picked up by the API browser. The string $Id$ will automatically be expanded when the file is checked in to cvs. [service0 ~]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/sql/postgresql -[service0 postgresql]$ emacs myfirstpackage-create.sql Paste this into the file and save and close. Figure�7.3.�Database Creation Script - master create file -- creation script +[service0 postgresql]$ emacs myfirstpackage-create.sql Paste this into the file and save and close. Figure�9.3.�Database Creation Script - master create file -- creation script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ @@ -62,7 +62,7 @@ First Package," ensures that our object is unlikely to conflict with objects from other packages. Create a database file to drop everything if the package is uninstalled. -[service0 postgresql]$ emacs myfirstpackage-drop.sql Figure�7.4.�Database deletion script -- drop script +[service0 postgresql]$ emacs myfirstpackage-drop.sql Figure�9.4.�Database deletion script -- drop script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/tutorial-debug.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html 18 Feb 2004 14:43:03 -0000 1.19 @@ -1,7 +1,7 @@ -Debugging and Automated TestingPrev Chapter�7.�Development Tutorial Next Debugging and Automated Testing by Joel Aufrecht +Debugging and Automated TestingPrev Chapter�9.�Development Tutorial Next Debugging and Automated Testing by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Debugging Developer Support.�The Developer Support package adds several goodies: debug + Debugging Developer Support.�The Developer Support package adds several goodies: debug information for every page; the ability to log comments to the page instead of the error log, and fast user switching so that you can test pages as anonymous and as dummy users without logging @@ -22,16 +22,16 @@ ?�searches�backward� /�searches�forward.� �� - Manual testing Make a list of basic tests to make sure it works Test Num Action Expected Result 001 Browse to the index page while not logged in and + Manual testing Make a list of basic tests to make sure it works Test Num Action Expected Result 001 Browse to the index page while not logged in and while one or more notes exist. No edit or delete or add links should appear. 002 Browse to the index page while logged in. An Edit link should appear. Click on it. Fill out the form and click Submit. The text added in the form should be visible on the index page. API-001 Invoke mfp::note::create with a specific word as the title. Proc should return an object id. API-002 Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title. API-003 Given the object id from API-001, invoke mfp::note::delete. Proc should return 0 for success. Other things to test: try to delete someone else's note. Try to delete your own note. Edit your own note. - Search for a note. Write automated tests by Simon Carstensen and Joel Aufrecht + Search for a note. Write automated tests by Simon Carstensen and Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - + It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it. Create the directory that will contain the test script and edit the script file. The directory location and file name are standards which are recognized by the automated testing package: [service0 www]$ mkdir /var/lib/aolserver/service0/packages/myfirstpackage/tcl/test [service0 www]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/tcl/test @@ -91,4 +91,4 @@ } } - See also the section called “Automated Testing”. Prev Home Next Creating Web Pages Up Chapter�8.�Advanced Topics docs@openacs.org View comments on this page at openacs.org +See also the section called “Automated Testing”. Prev Home Next Creating Web Pages Up Chapter�10.�Advanced Topics docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,10 +1,10 @@ -Prepare the package for distribution.Prev Chapter�8.�Advanced Topics Next Prepare the package for distribution. Browse to the package manager. Click on +Prepare the package for distribution. Prev Chapter�10.�Advanced Topics Next 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. - Prev Home Next Categories Up Notifications docs@openacs.org View comments on this page at openacs.org + /tmp. + Prev Home Next Categories Up Notifications docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,6 +1,6 @@ -Prev Chapter�8.�Advanced Topics Next Future Topics: How to enforce security so that users can't + Prev Chapter�10.�Advanced Topics Next Future Topics: 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 prepare pagelets for inclusion in other pages How and when to put procedures in a tcl procedure library 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 See also the OpenACS Programming FAQ Prev Home Next Using .vuh files for pretty urls Up Chapter�9.�Development Reference docs@openacs.org View comments on this page at openacs.org + "does this look right" confirm page APM package dependencies See also the OpenACS Programming FAQ Prev Home Next Using .vuh files for pretty urls Up Chapter�11.�Development Reference docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 12 Feb 2004 13:51:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 18 Feb 2004 14:43:03 -0000 1.20 @@ -1,7 +1,7 @@ -Creating a PackagePrev Chapter�7.�Development Tutorial Next Creating a Package by Joel Aufrecht +Creating a PackagePrev Chapter�9.�Development Tutorial Next Creating a Package by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - The intended page map Overview To start developing new code in OpenACS, we build a new + The intended page map Overview To start developing new code in OpenACS, we build a new package. A package is a a discrete collection of web pages, tcl code, and database tables and procedures. A package with user interface is called an application; a package which provides @@ -21,11 +21,11 @@ In this tutorial, we will make an application package for displaying a list of text notes. - Before you begin You will need: A computer with a working installation of + Before you begin You will need: A computer with a working installation of OpenACS. If you don't have this, see Chapter�2, Installation Overview. Example files, which are included in the -standard OpenACS 5.0.1d1 distribution. - Figure�7.1.�Assumptions in this section Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key myfirstpackage Use the APM to initialize a new package We use the ACS Package Manager (APM) to add, remove, and +standard OpenACS 5.1.0d1 distribution. + Figure�9.1.�Assumptions in this section Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key myfirstpackage Use the APM to initialize a new package We use the ACS Package Manager (APM) to add, remove, and upgrade packages. It handles package meta-data, such as lists of files that belong in the package. Each package is uniquely identified by a package key. To start developing a new @@ -54,7 +54,7 @@ This creates a package rooted at /var/lib/aolserver/service0/packages/myfirstpackage. This is the "home directory" of our new package, and all - files in the package will be within this directory. Mount the package in the site map In order to see your work in progress, you must create a + files in the package will be within this directory. Mount the package in the site map In order to see your work in progress, you must create a map between the URL space of incoming requests and the package. You do this by mounting the package in the Site Map. This creates a link between the incoming URL and an @@ -66,4 +66,4 @@ in this tutorial. Browse to http://yourserver.test:8000/admin/applications/application-add/. Choose "My First Package" from the list and click OK (the other fields are optional). By mounting the package, we've caused all requests to http://yourserver.test:8000/my-first-package - to be satisfied from the files at /var/lib/aolserver/service0/packages/myfirstpackage/www. Prev Home Next Chapter�7.�Development Tutorial Up Setting Up Database Objects docs@openacs.org View comments on this page at openacs.org + to be satisfied from the files at /var/lib/aolserver/service0/packages/myfirstpackage/www. Prev Home Next Chapter�9.�Development Tutorial Up Setting Up Database Objects docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -NotificationsPrev Chapter�8.�Advanced Topics Next Notifications by David Bell and Simon Carstensen +NotificationsPrev Chapter�10.�Advanced Topics Next Notifications by David Bell and Simon Carstensen OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. The notifications package allows you to send notifications through any Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/tutorial-pages.html 12 Feb 2004 13:51:40 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html 18 Feb 2004 14:43:03 -0000 1.19 @@ -1,8 +1,8 @@ -Creating Web Pages Prev Chapter�7.�Development Tutorial Next Creating Web Pages by Joel Aufrecht +Creating Web PagesPrev Chapter�9.�Development Tutorial Next Creating Web Pages by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Install some API As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files: - cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/service0/packages/myfirstpackage/tcl/ To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage". Build the "Index" page Each user-visible page in your package has, typically, + Install some API As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files: + cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/service0/packages/myfirstpackage/tcl/ To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage". Build the "Index" page Each user-visible page in your package has, typically, three parts. The tcl file holds the procedural logic for the page, including TCL and database-independent SQL code, and does things like Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-specs.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-specs.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -Write the Requirements and Design Specs Prev Chapter�8.�Advanced Topics Next Write the Requirements and Design Specs It's time to document. For the tutorial we'll use +Write the Requirements and Design Specs Prev Chapter�10.�Advanced Topics Next 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 @@ -48,4 +48,4 @@ Writing bi01.html for bibliography Writing index.html for book [service0 xml]$ Verify that the documentation was generated and reflects - your changes by browsing to http://yoursite:8000/myfirstpackage/doc Prev Home Next Chapter�8.�Advanced Topics Up Add the new package to CVS docs@openacs.org View comments on this page at openacs.org + your changes by browsing to http://yoursite:8000/myfirstpackage/doc Prev Home Next Chapter�10.�Advanced Topics Up Add the new package to CVS docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 12 Feb 2004 13:51:40 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 18 Feb 2004 14:43:03 -0000 1.2 @@ -1,4 +1,4 @@ -Using .vuh files for pretty urlsPrev Chapter�8.�Advanced Topics Next Using .vuh files for pretty urls .Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of note-edit?item_id=495, we can use note/495. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh: [service0 service0]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/www +Using .vuh files for pretty urlsPrev Chapter�10.�Advanced Topics Next Using .vuh files for pretty urls .Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of note-edit?item_id=495, we can use note/495. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh: [service0 service0]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/www [service0 www]$ emacs note.vuh Paste this into the file: # Transform requests of type: a/b # into this internal request: A?c=b Index: openacs-4/packages/acs-core-docs/www/tutorial.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial.html 12 Feb 2004 13:51:40 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial.html 18 Feb 2004 14:43:03 -0000 1.11 @@ -1 +1 @@ -Chapter�7.�Development TutorialPrev Part�III.�For OpenACS Package Developers Next Chapter�7.�Development Tutorial Table of Contents Creating a Package Setting Up Database Objects Creating Web Pages Debugging and Automated Testing Prev Home Next Part�III.�For OpenACS Package Developers Up Creating a Package docs@openacs.org View comments on this page at openacs.org +Chapter�9.�Development TutorialPrev Part�III.�For OpenACS Package Developers Next Chapter�9.�Development Tutorial Table of Contents Creating a Package Setting Up Database Objects Creating Web Pages Debugging and Automated Testing Prev Home Next Part�III.�For OpenACS Package Developers Up Creating a Package docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html,v diff -u -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html 12 Feb 2004 13:51:40 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html 18 Feb 2004 14:43:03 -0000 1.4 @@ -10,7 +10,7 @@ cp -r openacs-4-6/* openacs-4 exit Upgrading files for a site in a private CVS repository - Unpack the new files into a working directory. [root root]# su - service0 + Figure�5.2.�Upgrading a local CVS repository Unpack the new files into a working directory. [root root]# su - service0 [service0 aolserver]$ cd /tmp [service0 tmp]$ tar xzf openacs-4-6.tgz [service0 tmp]$ cd openacs-4.6 Import the new files into your cvs repository; where they match existing files, they will become the new version of the file. [service0 openacs-4.6]$ cvs import -m "upgrade to OpenACS 4.6" openacs Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/upgrade-openacs.html,v diff -u -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/upgrade-openacs.html 12 Feb 2004 13:51:40 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/upgrade-openacs.html 18 Feb 2004 14:43:03 -0000 1.4 @@ -1,5 +1,5 @@ -Upgrading OpenACSPrev Chapter�5.�Upgrading Next Upgrading OpenACS Upgrading 4.5 or higher to 4.6.3 The required platform for OpenACS 4.6 is the same as - 4.5, with the exception of OpenFTS. OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL. If you have OpenFTS 0.2, you'll need to upgrade. A computer with OpenACS 4.5. OpenACS 4.6 tarball or CVS checkout/export. Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2 Make a Backup.�Back up the database and file system (see the section called “Manual backup and recovery”). OPTIONAL: Upgrade OpenFTS.�the section called “Upgrading OpenFTS from 0.2 to 0.3.2” +Upgrading OpenACS Prev Chapter�5.�Upgrading Next Upgrading OpenACS Upgrading 4.5 or higher to 4.6.3 The required platform for OpenACS 4.6 is the same as + 4.5, with the exception of OpenFTS. OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL. If you have OpenFTS 0.2, you'll need to upgrade. A computer with OpenACS 4.5. OpenACS 4.6 tarball or CVS checkout/export. Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2 Make a Backup.�Back up the database and file system (see the section called “Manual backup and recovery”). OPTIONAL: Upgrade OpenFTS.�the section called “Upgrading OpenFTS from 0.2 to 0.3.2” Stop the server [root root]# svc -d /service/service0 Upgrade the file system.�the section called “Upgrading the OpenACS files” Start the server @@ -8,8 +8,8 @@ upgrade, plus any new packages you want. It's safest to upgrade the kernel by itself, and then come back and upgrade the rest of the - desired packages in a second pass. On the next screen, click Install Packages When prompted, restart the server: [root root]# restart-aolserver service0 Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm. Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.0.1d1. Rollback.�If anything goes wrong, roll back to the backup snapshot. Upgrading OpenACS 4.6.3 to 5.0 Oracle.�Not yet documented. It should be possible to upgrade via the APM just as when upgrading to 4.6.3. PostGreSQL.�You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See Upgrade PostGreSQL to 7.3; Table�2.2, “Version Compatibility Matrix” - Back up the database and file system. Upgrade the file system for packages/acs-kernel.�the section called “Upgrading the OpenACS files” Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.) [root root]# su - service0 + desired packages in a second pass. On the next screen, click Install Packages When prompted, restart the server: [root root]# restart-aolserver service0 Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm. Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.1.0d1. Rollback.�If anything goes wrong, roll back to the backup snapshot. Upgrading OpenACS 4.6.3 to 5.0 Oracle.�Not yet documented. It should be possible to upgrade via the APM just as when upgrading to 4.6.3. PostGreSQL.�You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See Upgrade PostGreSQL to 7.3; Table�2.2, “Version Compatibility Matrix” + Back up the database and file system. Upgrade the file system for packages/acs-kernel.�the section called “Upgrading the OpenACS files” Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.) [root root]# su - service0 [service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-kernel/sql/postgresql/upgrade Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql service0. Run the scripts in this order (order is tentative, not verified): psql -f upgrade-4.6.3-4.6.4.sql service0 Index: openacs-4/packages/acs-core-docs/www/upgrade-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.html,v diff -u -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/upgrade-overview.html 12 Feb 2004 13:51:40 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html 18 Feb 2004 14:43:03 -0000 1.4 @@ -3,7 +3,4 @@ or better, you should always be able to upgrade all of your core packages automatically. If you haven't changed anything, no manual intervention should be required. If you are running - OpenACS prior to 4.5, upgrading will require manual effort. It's always a good idea to precede an upgrade attempt with a snapshot backup. OpenACS consists of files and a database schema. The files - in a new tarball include database upgrade scripts. To start the - upgrade, replace your existing files with the new files and then browse to the APM, which will detect the new packages and offer to run the appropriate database upgrade scripts. After restarting the server again, the upgrade is - complete. Table�5.1.�Assumptions in this section name of OpenACS user service0 OpenACS server name service0 Root of OpenACS file tree /var/lib/aolserver/service0 Database backup directory /var/lib/aolserver/service0/database-backup Prev Home Next Chapter�5.�Upgrading Up Upgrading OpenACS docs@openacs.org View comments on this page at openacs.org + OpenACS prior to 4.5, upgrading will require manual effort. If all of these conditions are true: Your OpenACS Core is 5.0.0 or later You do not keep your OpenACS site in a local CVS repository You do not have any custom code then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter. To upgrade directly from the OpenACS repository using the APM: Browse to the Installer. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade. The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server. After restarting the server again, the upgrade is complete. Figure�5.1.�Upgrading with the APM It's always a good idea to precede an upgrade attempt with a snapshot backup. Table�5.1.�Assumptions in this section name of OpenACS user service0 OpenACS server name service0 Root of OpenACS file tree /var/lib/aolserver/service0 Database backup directory /var/lib/aolserver/service0/database-backup Prev Home Next Chapter�5.�Upgrading Up Upgrading OpenACS docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/upgrade-supporting.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.html,v diff -u -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 12 Feb 2004 13:51:40 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 18 Feb 2004 14:43:03 -0000 1.4 @@ -1,4 +1,4 @@ -Upgrading Platform componentsPrev Chapter�5.�Upgrading Next Upgrading Platform components Upgrading OpenFTS from 0.2 to 0.3.2 OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time. Uninstall the old OpenFTS Engine from the service0 database. Browse to http://yourserver/openfts. +Upgrading Platform components Prev Chapter�5.�Upgrading Next Upgrading Platform components Upgrading OpenFTS from 0.2 to 0.3.2 OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time. Uninstall the old OpenFTS Engine from the service0 database. Browse to http://yourserver/openfts. Click Administration. Click Drop OpenFTS Engine Build and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.) cd /usr/local/src/ tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz chown -R root.root Search-OpenFTS-tcl-0.3.2/ @@ -33,7 +33,7 @@ exit OPTIONAL: Install the new OpenFTS Engine.�If you want to upgrade the OpenFTS Engine, do these steps. (You must have already upgraded the OpenFTS driver to 0.3.2.) Browse to http://yourserver/admin/site-map On the openfts line, click on set parameters. Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ Click Set Parameters [root root]# restart-aolserver service0 Browse to http://yourserver/openfts Click Administration. Click Initialize OpenFTS Engine Upgrading from PostGreSQL 7.2 to 7.3 An OpenACS database created in PostGreSQL 7.2 will not work correctly in PostGreSQL 7.3. This is because 7.2 truncates function names to 31 characters, but 7.3 does not. This does not cause problems in 7.2, because truncation occurs both at function creation and at function calling, so they still match. But if you use a database created in 7.2 in 7.3, the function names in the database remain truncated but the function calls are not, and so they don't match. Also some functions use casting commands that no longer work in 7.3 and these functions must be recreated. - To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/service0/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example: Back up the database as per PostgreSQL. Run the upgrade script on the backup file. [root root]# su - service0 + To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/service0/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example: Back up the database as per PostgreSQL. Run the upgrade script on the backup file. [root root]# su - service0 [service0 service0]# cd /var/lib/aolserver/service0/bin [service0 bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ @@ -48,4 +48,6 @@ (many lines omitted) [service0 bin]$ Use perl to replace timestamp with timestamptz in the dump file. find . -type f -name "*sql" | xargs perl -p -i.tmp -e "s/timestamp with time zone/timestamptz/g" - find . -type f -name "*sql" | xargs perl -p -i.tmp -e "s/\\wtimestamp[^t]/ timestamptz/g" Restore the database from dump as per the recovery instructions. Prev Home Next Upgrading the OpenACS files Up Chapter�6.�Maintenance docs@openacs.org View comments on this page at openacs.org + find . -type f -name "*sql" | xargs perl -p -i.tmp -e "s/\\wtimestamp[^t]/ timestamptz/g" Install PostgreSQL 7.3.x. Note that you PostgreSQL + must listen on a different port in order to work + correctly. Restore the database from dump as per the recovery instructions. Prev Home Next Upgrading the OpenACS files Up Chapter�6.�Production Environments docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/uptime.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/uptime.html,v diff -u --- /dev/null 1 Jan 1970 00:00:00 -0000 +++ openacs-4/packages/acs-core-docs/www/uptime.html 18 Feb 2004 14:43:03 -0000 1.1 @@ -0,0 +1 @@ +External uptime validationPrev Chapter�6.�Production Environments Next External uptime validation The OpenACS uptime site can monitor your site and send you an email whenever your site fails to respond. If you test the url http://yourserver.test/SYSTEM/dbtest.tcl, you should get back the string success. Prev Home Next Set up Log Analysis Reports - OPTIONAL Up Diagnosing Performance Problems docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/variables.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/variables.html 12 Feb 2004 13:51:40 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/variables.html 18 Feb 2004 14:43:03 -0000 1.6 @@ -1,9 +1,9 @@ -VariablesPrev Chapter�10.�Engineering Standards Next Variables By joel@aufrecht.org +VariablesPrev Chapter�12.�Engineering Standards Next Variables By joel@aufrecht.org OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. Date and Time Variables Starting with OpenACS 5.0 and the introduction of acs-lang, we recommend retrieving date/time information from the database in - ANSI format and then using lc_time_fmt to format it for display. Example�10.1.�Getting datetime from the database ANSI-style db_multirow -extend { mydate_pretty } { + ANSI format and then using lc_time_fmt to format it for display. Example�12.1.�Getting datetime from the database ANSI-style db_multirow -extend { mydate_pretty } { select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi, ... ... Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/win2k-installation.html 12 Feb 2004 13:51:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/win2k-installation.html 18 Feb 2004 14:43:03 -0000 1.27 @@ -1,11 +1,11 @@ -OpenACS Installation Guide for Windows2000Prev Chapter�3.�Complete Installation Next OpenACS Installation Guide for Windows2000 by Matthew Burke and Curtis Galloway +OpenACS Installation Guide for Windows2000Prev Chapter�3.�Complete Installation Next OpenACS Installation Guide for Windows2000 by Matthew Burke and Curtis Galloway OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. NOTE: These instructions were valid for ACS v4, but have not been tested with OpenACS and the ArsDigita binary distributions are no longer available. Currently - (10/2003), the best option to get OpenACS 5.0.1d1 running on Windows + (10/2003), the best option to get OpenACS 5.1.0d1 running on Windows is to use VMware and John Sequeira's Oasis VM distribution @@ -249,4 +249,4 @@ In the services control panel you should see two services: AOLserver-lintcollectors and AOLserver-iguanasdirect. - ($Id$) Prev Home Next Install OpenACS 5.0.1d1 Up OpenACS Installation Guide for Mac OS X docs@openacs.org View comments on this page at openacs.org + ($Id$) Prev Home Next Install OpenACS 5.1.0d1 Up OpenACS Installation Guide for Mac OS X docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/images/apm-upgrade.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/apm-upgrade.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/backup.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/backup.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/complex-deploy-1.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/complex-deploy-1.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/complex-deploy-2.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/complex-deploy-2.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/complex-deploy-3.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/complex-deploy-3.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/development-with-cvs.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/development-with-cvs.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/hpha.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/hpha.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/prod-normal.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/prod-normal.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/production.dia =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/production.dia,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/simple-deploy-1.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/simple-deploy-1.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/simple-deploy-2.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/simple-deploy-2.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/simple-deploy-3.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/simple-deploy-3.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/upgrade-apm.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/upgrade-apm.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/upgrade-cvs.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/upgrade-cvs.png,v diff -u Binary files differ Index: openacs-4/packages/acs-core-docs/www/xml/index.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/index.xml,v diff -u -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/xml/index.xml 12 Feb 2004 13:51:42 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/xml/index.xml 18 Feb 2004 14:43:05 -0000 1.25 @@ -158,22 +158,19 @@ Section missing - - Maintenance - - Section missing - - - Section missing - - - Section missing - - - Section missing - - + + Section missing + + + Section missing + + + + Section missing + + + Section missing Index: openacs-4/packages/acs-core-docs/www/xml/variables.ent =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/variables.ent,v diff -u -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/xml/variables.ent 12 Feb 2004 13:51:42 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/xml/variables.ent 18 Feb 2004 14:43:05 -0000 1.9 @@ -1,5 +1,5 @@ - - - + + + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 4 Feb 2004 16:47:34 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 18 Feb 2004 14:43:05 -0000 1.11 @@ -549,7 +549,7 @@ Internationalize Package Parameters with visible messages - See + See Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 13 Feb 2004 19:19:39 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 18 Feb 2004 14:43:05 -0000 1.15 @@ -141,6 +141,14 @@ done (many lines omitted) [service0 myfirstpackage]$ + + Upgrading a local CVS repository + + + + + + Adding Comments Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml 26 Jan 2004 15:39:44 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml 18 Feb 2004 14:43:06 -0000 1.5 @@ -1,11 +1,17 @@ - + + +%myvars; +]> + Database Management By Joel Aufrecht - + Running a PostgreSQL database on another server To run a database on a different machine than the @@ -36,15 +42,15 @@ - + - + Deleting a tablespace Skip down for instructions on . - + Deleting an Oracle tablespace @@ -76,9 +82,9 @@ If you feel the need to delete everything related to the service, you can also issue the following: SVRMGR> drop tablespace service0 including contents cascade constraints; - + - + Deleting a PostgreSQL tablespace @@ -95,9 +101,9 @@ [service0 ~]$ dropdb service0 DROP DATABASE - - - + + + Vacuum Postgres nightly The "vacuum" command must be run periodically to reclaim space. The @@ -123,9 +129,9 @@ 0 1 * * * /usr/local/pgsql/bin/vacuumdb service0 ($Id$) - + - +

OpenACS Version		3.2.5	4.5	4.6.2	4.6.3	5.0.0
AOLserver	3	Yes	No
	3.3+ad13	Maybe	Yes
	3.3oacs1	Maybe	Yes
	3.4.2	No
	3.4.2oacs1	Maybe		Yes		Maybe
	3.5.5	Maybe		Yes		No
	4.0	Maybe		Yes
PostgreSQL	7.0	Yes	No
	7.2.x	�	Yes			No
	7.3.2 - 7.3.4	No			Yes
	7.4	No				Maybe
Oracle	8.1.6	Maybe	Yes
	8.1.7	Maybe	Yes
	9i	No				Yes

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