Index: openacs-4/packages/acs-core-docs/www/acs-admin.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.html,v diff -u -N -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/acs-admin.html 24 Jun 2004 10:44:39 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/acs-admin.html 5 Jul 2004 14:24:59 -0000 1.35 @@ -1 +1 @@ -Part�II.�Administrator's Guide
Alex logo
Prev Next

Administrator's Guide

Table of Contents

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 4
Install OpenACS 5.2.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 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading 5.0.0 to 5.0.x
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 for an OpenACS service
Set up Log Analysis Reports
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
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
Install AOLserver 3.3oacs1
C. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
Prev Home Next
OpenACS Release Notes Up Chapter�2.�Installation Overview
docs@openacs.org
View comments on this page at openacs.org
+Part�II.�Administrator's Guide
Alex logo
Prev Next

Administrator's Guide

Table of Contents

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 4
Install OpenACS 5.2.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 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading 5.0.0 to 5.0.x or 5.1.x
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 for an OpenACS service
Set up Log Analysis Reports
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
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
Install AOLserver 3.3oacs1
A. Credits
Where did this document come from?
Linux Install Guides
Security Information
Resources
Prev Home Next
OpenACS Release Notes Up Chapter�2.�Installation Overview
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver.html,v diff -u -N -r1.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/aolserver.html 29 Jun 2004 15:50:14 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/aolserver.html 5 Jul 2004 14:24:59 -0000 1.42 @@ -82,17 +82,17 @@ communicate with the database. There is one script each for Oracle and PostgreSQL. They don't conflict, so if you plan to use both databases, install both.

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

    [root root]# cd /usr/local/src
Index: openacs-4/packages/acs-core-docs/www/backup-recovery.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.html,v
diff -u -N -r1.34 -r1.35
--- openacs-4/packages/acs-core-docs/www/backup-recovery.html	29 Jun 2004 15:50:14 -0000	1.34
+++ openacs-4/packages/acs-core-docs/www/backup-recovery.html	5 Jul 2004 14:24:59 -0000	1.35
@@ -7,4 +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).
    Figure�8.1.�Backup and Recovery Strategy
    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
    
+    source tree, and the acs-content-repository (which is in the server source tree).
    Figure�8.1.�Backup and Recovery Strategy
    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/cvs-tips.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-tips.html,v
diff -u -N -r1.24 -r1.25
--- openacs-4/packages/acs-core-docs/www/cvs-tips.html	29 Jun 2004 15:50:14 -0000	1.24
+++ openacs-4/packages/acs-core-docs/www/cvs-tips.html	5 Jul 2004 14:24:59 -0000	1.25
@@ -1,7 +1,7 @@
 Appendix�D.�Using CVS with an OpenACS Site
    Alex logo
    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.
    1. Create and set permissions on a subdirectory in the local cvs repository.
      [root root]# mkdir /cvsroot/$OPENACS_SERVICE_NAME
 [root root]# chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAME
Index: openacs-4/packages/acs-core-docs/www/db-api.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v
diff -u -N -r1.39 -r1.40
--- openacs-4/packages/acs-core-docs/www/db-api.html	29 Jun 2004 15:50:15 -0000	1.39
+++ openacs-4/packages/acs-core-docs/www/db-api.html	5 Jul 2004 14:24:59 -0000	1.40
@@ -3,166 +3,127 @@
   
      Overview
      
       One of OpenACS's great strengths is that code written for it is
       very close to the database. It is very easy to interact with the
-      database from anywhere within OpenACS. Our goal is to develop a
+      database from anywhere within OpenACS, and we have a
       coherent API for database access which makes this even easier.
     
      
       More detailed information about the DB api is available at
       Database Access API.
-    
      The New Way
      
-      Introduced in ACS 3.4, the new Database API is meant to save
-      developers from the above tedium and provide a more structured syntax
-      for specifying database operations, including transactions.
-      Here's an example of the API.
+    
      DB API Examples
      
+      The OpenACS database API is meant to save developers from making
+      common mistakes and to provide a more structured syntax for
+      specifying database operations, including transactions.  Here's
+      an example of the API.
     
      -set count 0 
-
+set count 0
 set tcl_var "foo"
-
 set sql {
-       	select 
-            foo, 
-            bar, 
-            baz 
-        from some_table, some_other_table
-        where some_table.id = some_other_table.id  
-        and some_table.condition_p = :tcl_var
-      	}
-      
-db_transaction {
-        db_foreach my_example_query_name $sql {
-            	...
-            	call_some_proc $foo $bar $baz
-            	incr count
-        }
+      	SELECT foo, bar, baz
+       FROM some_table, some_other_table
+       WHERE some_table.id = some_other_table.id
+         and some_table.condition_p = :tcl_var
 }
-    
      
+
+db_transaction {
+    db_foreach my_example_query_name $sql {
+        lappend rows [list $foo $bar $baz]
+        incr count
+    }
+    foreach row $rows { 
+        call_some_proc $foo $bar $baz
+    }
+}
      
       There are several things to note here:
 
       
      1. 
 	    No explicit code for grabbing and releasing handles. Usage of the
 	    Database API implicitly deals with all handle management issues.
 	  
      2. 
-	    The new command db_transaction
+	    The db_transaction command
 	    makes the scope of a transaction
-	    clear. db_transaction takes the
+	    clear; db_transaction takes the
 	    code block argument and automatically runs it in the context of a
-	    transaction.
+	    transaction.  If you use something like db_foreach though, you need to 
+            make sure that there are no calls in the code block which would take
+            a second db handle since the transaction is only valid for 
+            one handle (thats why we build up a list of returned values and call 
+            a second proc outside the db_foreach loop).
 	  
      3. 
-	    The new command db_foreach writes
+	    The command db_foreach writes
 	    our old while loop for us.
 	  
      4. 
-	    Every SQL query has a name, meant to be unique within the server
-	    instance (though this is not enforced).
+	    Every SQL query has a name, which is used in conjunction with .XQL files
+            to support multiple databases.
 	  
      5. 
-	    Finally and most importantly, there is a new scheme for passing data
-	    from a Tcl variable to the database, which we'll cover next.
+	    Finally and most importantly, there API implements bind variables, which we will cover next.
 	  
      
 
     
    Bind Variables
    
-      Bind variables are placeholders for literal values in an SQL query
-      being sent to the server. Take the example query above: in the old
-      way, data was generally passed to Oracle directly, via Tcl string
-      interpolation. So in the example above, the actual query we send would
-      look like this:
+      Bind variables are placeholders for literal values in an SQL
+      query being sent to the server.  In the old way, data was
+      generally passed to directly to the DB backend, via Tcl string
+      interpolation. In the example above, the query would look like:
     
    -select 
-    foo, 
-    bar, 
-    baz 
+select foo, bar, baz 
 from some_table, some_other_table
 where some_table.id=some_other_table.id  
-and some_table.condition_p = 'foo'
-    
    
+and some_table.condition_p = '$foo'

    There are a few problems with this:

    1. - If the literal value is a - huge string, then we waste a lot of time in the database server doing - useless parsing. + If the value of $foo is a huge string, then we waste a lot + of time in the database server doing useless parsing.

    2. - Second, if the literal value contains characters like - single quotes, we have to be careful to double-quote them, because not - quoting them will lead to surprising errors. + Second, if the literal value contains characters like single + quotes, we have to be careful to properly escape them, + because not quoting them will lead to surprising errors.

    3. - Third, no type checking - occurs on the literal value. Finally, if the Tcl variable is passed in - or between web forms or otherwise subject to external modification, - there is nothing keeping malicious users from setting the Tcl variable - to some string that changes the query textually. -

      + Third, no type checking occurs on the literal + value. Finally, if the Tcl variable is passed in or between + web forms or otherwise subject to external modification, + there is nothing keeping malicious users from setting the + Tcl variable to some string that changes the query + textually. This type of attack, called SQL smuggling, can be very damaging - entire tables can be - exposed or have their contents deleted, for example. Another very - important reason for using bind variables is performance. Oracle caches - all previously parsed queries. If there are values in the where clause, - that is how the query is cached. It also performs bind variable - susbstitution after parsing the SQL statement. This means that SQL - statements that use bind variables will always match (assuming all else is - the same) while SQL statements that do not use bind variables will not - match unless the values in the statement are exactly the same. This will - improve performance considerably. + exposed or have their contents deleted, for example. +

      + Another very important reason for using bind variables is + performance. Oracle can cache previously parsed queries. If + there are values in the where clause, that is how the query + is cached. It also performs bind variable susbstitution + after parsing the SQL statement. This means that SQL + statements that use bind variables will always match + (assuming all else is the same) while SQL statements that do + not use bind variables will not match unless the values in + the statement are exactly the same. This will improve the + query cache considerably, which can make the server much + more efficient.

    - To fix all these problems, we replace literal values in the query with - a placeholder character, and then send the data along after. So the - query looks like this: - 

    -select 
-    foo, 
-    bar, 
-    baz 
-from some_table, some_other_table
-where some_table.id = some_other_table.id
-and some_table.condition_p = ?
-

    - The '?' character means "This will be filled in later with literal - data". In use, you might write code that looks like this: - 

    -set statement [prepare_query "
-    		select 
-        		foo, 
-        		bar, 
-        		baz 
-    		from some_table, some_other_table
-    		where some_table.id = some_other_table.id  
-    		and some_table.condition_p = ?
-	       "]
-
-[bind_param $statement 1 $tcl_var]
-

    - The above example is meant to be psuedo-Tcl - no API like this - actually exists. What happens is that we first send the SQL statement - to the server for parsing, then later we bind values to the - placeholders, and send those values along seperately. This seperate - binding step is where the term bind variable comes from. + What the DB API (in conjuntion with the database drivers + implemented for aolserver) do is send the SQL statement to the + server for parsing, then bind values to the + variables and sends those values along seperately as a second + step. This seperate binding step is where the term + bind variable comes from.

    - This split has several advantages. First, type checking happens on the - literal. If the column we are comparing against holds numbers, and we - send a string, we get a nice error. Second, since string literals are - no longer in the query, no extra quoting is required. Third, - substitution of bind variables cannot change the actual text of the - query, only the literal values in the placeholders. + This split has several advantages. First, type checking happens + on the literal. If the column we are comparing against holds + numbers, and we send a string, we get a nice error. Second, + since string literals are no longer in the query, no extra + quoting is required. Third, substitution of bind variables + cannot change the actual text of the query, only the literal + values in the placeholders. The database API makes bind + variables easy to use by hooking them smoothly into the Tcl + runtime so you simply provide :tclvar and the value of $tclvar + is sent to the backend to actually execute the query.

    - The database API makes bind variables easy to use by hooking them - smoothly into the Tcl runtime. Rather than using a '?' as a generic - placeholder, you use a colon followed by the name of the Tcl variable - that you wish to pass as a literal. So here's the final, real-life - form of the example query: - 

    -select 
-    foo, 
-    bar, 
-    baz 
-from some_table, some_other_table
-where some_table.id = some_other_table.id  
-and some_table.condition_p = :tcl_var
-

    The database API parses the query and pulls out all the bind variable specifications and replaces them with generic placeholders. It then automatically pulls the values of the named Tcl vars out of the runtime environment of the script, and passes them to the database.

    Note that while this looks like a simple syntactic change, it really - is very different from how we've written queries in the past. You use + is very different from how interpolated text queries work. You use bind variables to replace what would otherwise be a literal value in a query, and Tcl style string interpolation does not happen. So you cannot do something like: @@ -175,7 +136,7 @@ SQL will not allow a literal to occur where we've put the bind variables, so the query is syntactically incorrect. You have to remember that while the bind variable syntax looks similar to variable - interpolation in Tcl, it is not the same thing at all. + interpolation in Tcl, It is not the same thing at all.

    Finally, the DB API has several different styles for passing bind variable values to queries. In general, use the style presented here @@ -286,16 +247,12 @@

    Therefore, the Database Access API provides a database-independent way to represent null (instead of the Oracle-specific idiom of the empty string): db_null.

    Use it instead of the empty string whenever you want to set a column value - explicitly to null, e.g.:

    -
-set bar [db_null]
+	explicitly to null, e.g.:
    set bar [db_null]
 set baz [db_null]
 
 db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)"
 #
-# sets the values for both the "bar" and "baz" columns to null
-
-      
    Sequence Pooling
    
+# sets the values for both the "bar" and "baz" columns to null

    Sequence Pooling

    The database library can transparently maintain pools of sequence values, so that each request for a new sequence value (using db_nextval) does not incur a roundtrip to the server. For instance, this functionality is @@ -310,7 +267,7 @@

    in any configuration section in the yourservername.ini - file, e.g., e.g., + file, e.g., 

     
 [ns/server/yourservername/acs/security]
@@ -391,7 +348,6 @@
     and not include it in the multirow. Or you can call break
     to skip this row and quit looping.
     
    
-
     Notice the nonstandard numbering (everything
     else in Tcl starts at 0); the reason is that the graphics designer, a non
     programmer, may wish to work with row numbers.
Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v
diff -u -N -r1.41 -r1.42
--- openacs-4/packages/acs-core-docs/www/docbook-primer.html	29 Jun 2004 15:50:15 -0000	1.41
+++ openacs-4/packages/acs-core-docs/www/docbook-primer.html	5 Jul 2004 14:24:59 -0000	1.42
@@ -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>.

    Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -N -r1.40 -r1.41 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 29 Jun 2004 15:50:15 -0000 1.40 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 5 Jul 2004 14:24:59 -0000 1.41 @@ -59,7 +59,7 @@

    Transition Rules

    So what distinguishes an alpha release from a beta release? Or from a production release? We follow a specific set of rules for how OpenACS makes the transition from one state of maturity to -the next. These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria

    Naming Database Upgrade Scripts

    Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.

    1. Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql

    2. If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. +the next. These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria

    Naming Database Upgrade Scripts

    Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.

    1. Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql

    2. If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1.

    3. If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use upgrade-2.0.1d3-2.0.1d4.sql.

    4. Database upgrades should be confined to development releases, not alpha or beta releases.

    5. Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.

    6. Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.

    7. The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -N -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 29 Jun 2004 15:50:15 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 5 Jul 2004 14:24:59 -0000 1.30 @@ -1,4 +1,4 @@ -External Authentication Requirements

      Alex logo
      Prev Chapter�15.�Kernel Documentation Next

      External Authentication Requirements

      Vision

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

      Alex logo
      Prev Chapter�15.�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.

    8. 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

    FeatureStatusDescription
    EXT-AUTH-01AExtend Authentication/Acct Status API
    EXT-AUTH-03AAccount Creation API
    EXT-AUTH-05APassword Management API
    EXT-AUTH-30AAuthority Management API

    Login

    FeatureStatusDescription
    EXT-AUTH-04ARewrite login, register, and admin pages to use APIs
    EXT-AUTH-38Aad_form complain feature
    EXT-AUTH-19ARewrite password recovery to use API
    EXT-AUTH-21ARewrite email verification with API
    EXT-AUTH-28AUsername 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

    FeatureStatusDescription
    EXT-AUTH-01AExtend Authentication/Acct Status API
    EXT-AUTH-03AAccount Creation API
    EXT-AUTH-05APassword Management API
    EXT-AUTH-30AAuthority Management API

    Login

    FeatureStatusDescription
    EXT-AUTH-04ARewrite login, register, and admin pages to use APIs
    EXT-AUTH-38Aad_form complain feature
    EXT-AUTH-19ARewrite password recovery to use API
    EXT-AUTH-21ARewrite email verification with API
    EXT-AUTH-28AUsername 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/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -N -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/form-builder.html 29 Jun 2004 15:50:15 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 5 Jul 2004 14:24:59 -0000 1.20 @@ -1,4 +1,4 @@ -Using HTML Forms

    Alex logo
    Prev 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

    1. Creating the form element.�Populate a list of lists with values for the option list.

      set foo_options [db_list_of_lists foo_option_list "
+Using HTML Forms
      Alex logo
      Prev 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
      1. 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
@@ -43,5 +43,5 @@
     ns_set print $mypage
 }
     
      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
+    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/high-avail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.html,v
diff -u -N -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/high-avail.html	24 Jun 2004 10:44:39 -0000	1.13
+++ openacs-4/packages/acs-core-docs/www/high-avail.html	5 Jul 2004 14:24:59 -0000	1.14
@@ -1 +1 @@
-High Availability/High Performance Configurations
      Alex logo
      Prev Chapter�6.�Production Environments Next
      High Availability/High Performance Configurations
      See also the section called “Running a PostgreSQL database on another server”.
      Figure�6.1.�Multiple-server configuration
      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
      
+High Availability/High Performance Configurations
      Alex logo
      Prev Chapter�6.�Production Environments Next
      High Availability/High Performance Configurations
      See also the section called “Running a PostgreSQL database on another server”.
      Figure�6.1.�Multiple-server configuration
      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 -N -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/how-do-I.html	24 Jun 2004 10:44:39 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/how-do-I.html	5 Jul 2004 14:24:59 -0000	1.17
@@ -1,6 +1,6 @@
-How Do I?
      Alex logo
      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.
      1. Log in to the web site as an administrator.
      2. Click on Admin > Install Software > Install from OpenACS Repository / Install new application
      3. Choose Edit This Page and install
      4. 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.
      1. On the front page, click the Admin button.
      2. On the administration page, click Parameters link.
      3. 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/$OPENACS_SERVICE_NAME/www.  If an index page is not found there, the default index page for all subsites is used.  To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
      1. cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www
      2. 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:
      • 
+How Do I?
        Alex logo
        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.
        1. Log in to the web site as an administrator.
        2. Click on Admin > Install Software > Install from OpenACS Repository / Install new application
        3. Choose Edit This Page and install
        4. 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.
        1. On the front page, click the Admin button.
        2. On the administration page, click Parameters link.
        3. 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/$OPENACS_SERVICE_NAME/www.  If an index page is not found there, the default index page for all subsites is used.  To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:
        1. cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www
        2. 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/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file.
-          
        • The default-master is itself a normal ADP page.  It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
        • The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).  
        • Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.
        Figure�4.1.�Site Templates
        Site Templates
        How do I diagnose a permissions problem?
        • Steps to Reproduce.�The events package does not allow users to register for new events.
          1. Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies).  This in on a 4.6.3 site with events version 0.1d3.
          2. Select an available event
          3. A link such as Registration: Deadline is 03/15/2004 10:00am. 
+          
          4. The default-master is itself a normal ADP page.  It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
          5. The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).  
          6. 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
        Site Templates
        How do I diagnose a permissions problem?
        • Steps to Reproduce.�The events package does not allow users to register for new events.
          1. Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies).  This in on a 4.6.3 site with events version 0.1d3.
          2. Select an available event
          3. A link such as Registration: Deadline is 03/15/2004 10:00am. 
 � Login or sign up to register for this event. is visible.  Click on "Login or sign up"
-          
          4. Complete a new registration.  Afterwards, you should be redirected back to the same page.
          Actual Results: The page says "You do not have permission to register for this event."
          Expected results: A link or form to sign up for the event is shown.
        • Finding the problem.�We start with the page that has the error.  In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl.  It contains this line:
          set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
          We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky.  The next pages shows the proc, and we click "show source" to see more information.  The body of the proc is simply
          return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
          This means that a given user must have the write privilige on the event in order to register.  Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
        • Setting Permissions.�A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige.  In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
          1. To grant permissions on a package, start at the site map.  Find the event package and click "Set permissions".  
          2. Click "Grant Permission"
          3. Grant the write permission to Registered Users.
            Figure�4.2.�Granting Permissions
            Granting Permissions
          OpenACS 5.0 offers a prettier version at /admin/applications.
          Figure�4.3.�Granting Permissions in 5.0
          Granting Permissions in 5.0
        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
        
+          
      • Complete a new registration.  Afterwards, you should be redirected back to the same page.

    Actual Results: The page says "You do not have permission to register for this event."

    Expected results: A link or form to sign up for the event is shown.

  • Finding the problem.�We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line:

    set can_register_p [events::security::can_register_for_event_p -event_id $event_id]

    We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply

    return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]

    This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.

  • Setting Permissions.�A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.

    1. To grant permissions on a package, start at the site map. Find the event package and click "Set permissions".

    2. Click "Grant Permission"

    3. Grant the write permission to Registered Users.

      Figure�4.2.�Granting Permissions

      Granting Permissions

    OpenACS 5.0 offers a prettier version at /admin/applications.

    Figure�4.3.�Granting Permissions in 5.0

    Granting Permissions in 5.0
    • 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-convert.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 29 Jun 2004 15:50:15 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 5 Jul 2004 14:24:59 -0000 1.16 @@ -71,7 +71,7 @@ test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files. -

    Avoiding common i18n mistakes

    • Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.

      The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:

        <p class="form-help-text"><b>Invitations</b> are sent,
+

    Avoiding common i18n mistakes

    • Replace complicated keys with longer, simpler keys.�When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an if command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.

      The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:

        <p class="form-help-text"><b>Invitations</b> are sent,
           when this wizard is completed and casting begins.</p>

      has a bold tag which confuses the converter into thinking there are two message keys for the text beginning "Invitations ..." where there should be one:

      Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:

        <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, 
 when this wizard is completed and casting begins.#>
   </p>

      Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:

      Select which case <if @simulation.casting_type@ eq "open">and
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 -N -r1.42 -r1.43
--- openacs-4/packages/acs-core-docs/www/index.html	29 Jun 2004 15:50:15 -0000	1.42
+++ openacs-4/packages/acs-core-docs/www/index.html	5 Jul 2004 14:24:59 -0000	1.43
@@ -1 +1 @@
-OpenACS Core Documentation
      Alex logo
        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 4
      Install OpenACS 5.2.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 4.5 or higher to 4.6.3
      Upgrading OpenACS 4.6.3 to 5.0
      Upgrading 5.0.0 to 5.0.x
      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 for an OpenACS service
      Set up Log Analysis Reports
      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
      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
      Install AOLserver 3.3oacs1
      C. Credits
      Where did this document come from?
      Linux Install Guides
      Security Information
      Resources
      III. For OpenACS Package Developers
      9. Development Tutorial
      Creating an Application 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
      Profile your code
      Prepare the package for distribution.
      Notifications
      Hierarchical data
      Using .vuh files for pretty urls
      Laying out a page with CSS instead of tables
      Sending HTML email from your application
      Basic Caching
      Scheduled Procedures
      Future Topics
      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
      14. Internationalization
      Internationalization and Localization Overview
      How Internationalization/Localization works in OpenACS
      How to Internationalize a Package
      Design Notes
      Translator's Guide
      D. Using CVS with an OpenACS Site
      IV. For OpenACS Platform Developers
      15. 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
      Security Requirements
      Security Design
      Security Notes
      Request Processor Requirements
      Request Processor Design
      Documenting Tcl Files: Page Contracts and Libraries
      Bootstrapping OpenACS
      External Authentication Requirements
      16. Releasing OpenACS
      OpenACS Core and .LRN
      How to Update the OpenACS.org repository
      How to package and release an OpenACS Package
      How to Update the translations
      Index
      List of Figures
      4.1. Site Templates
      4.2. Granting Permissions
      4.3. Granting Permissions in 5.0
      5.1. Upgrading with the APM
      5.2. Upgrading a local CVS repository
      6.1. Multiple-server configuration
      6.2. Simple A/B Deployment - Step 1
      6.3. Simple A/B Deployment - Step 2
      6.4. Simple A/B Deployment - Step 3
      6.5. Complex A/B Deployment - Step 1
      6.6. Complex A/B Deployment - Step 2
      6.7. Complex A/B Deployment - Step 3
      6.8. Query Analysis example
      8.1. Backup and Recovery Strategy
      9.1. Assumptions in this section
      9.2. Tutorial Data Model
      9.3. The Database Creation Script
      9.4. Database Deletion Script
      9.5. Page Map
      10.1. 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
      14.1. Internationalization and Localization Overview
      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
      
+OpenACS Core Documentation
      Alex logo
        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 4
      Install OpenACS 5.2.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 4.5 or higher to 4.6.3
      Upgrading OpenACS 4.6.3 to 5.0
      Upgrading 5.0.0 to 5.0.x or 5.1.x
      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 for an OpenACS service
      Set up Log Analysis Reports
      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
      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
      Install AOLserver 3.3oacs1
      A. Credits
      Where did this document come from?
      Linux Install Guides
      Security Information
      Resources
      III. For OpenACS Package Developers
      1. Development Tutorial
      Creating an Application Package
      Setting Up Database Objects
      Creating Web Pages
      Debugging and Automated Testing
      2. Advanced Topics
      Write the Requirements and Design Specs
      Add the new package to CVS
      Adding Comments
      Admin Pages
      Categories
      Profile your code
      Prepare the package for distribution.
      Notifications
      Hierarchical data
      Using .vuh files for pretty urls
      Laying out a page with CSS instead of tables
      Sending HTML email from your application
      Basic Caching
      Scheduled Procedures
      Future Topics
      3. 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
      4. Engineering Standards
      OpenACS Style Guide
      Release Version Numbering
      Constraint naming standard
      ACS File Naming and Formatting Standards
      PL/SQL Standards
      Variables
      Automated Testing
      5. Documentation Standards
      OpenACS Documentation Guide
      Using PSGML mode in Emacs
      Using nXML mode in Emacs
      Detailed Design Documentation Template
      System/Application Requirements Template
      6. Internationalization
      Internationalization and Localization Overview
      How Internationalization/Localization works in OpenACS
      How to Internationalize a Package
      Design Notes
      Translator's Guide
      B. Using CVS with an OpenACS Site
      IV. For OpenACS Platform Developers
      7. 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
      Security Requirements
      Security Design
      Security Notes
      Request Processor Requirements
      Request Processor Design
      Documenting Tcl Files: Page Contracts and Libraries
      Bootstrapping OpenACS
      External Authentication Requirements
      8. Releasing OpenACS
      OpenACS Core and .LRN
      How to Update the OpenACS.org repository
      How to package and release an OpenACS Package
      How to Update the translations
      Index
      List of Figures
      4.1. Site Templates
      4.2. Granting Permissions
      4.3. Granting Permissions in 5.0
      5.1. Upgrading with the APM
      5.2. Upgrading a local CVS repository
      6.1. Multiple-server configuration
      6.2. Simple A/B Deployment - Step 1
      6.3. Simple A/B Deployment - Step 2
      6.4. Simple A/B Deployment - Step 3
      6.5. Complex A/B Deployment - Step 1
      6.6. Complex A/B Deployment - Step 2
      6.7. Complex A/B Deployment - Step 3
      6.8. Query Analysis example
      8.1. Backup and Recovery Strategy
      1.1. Assumptions in this section
      1.2. Tutorial Data Model
      1.3. The Database Creation Script
      1.4. Database Deletion Script
      1.5. Page Map
      2.1. Upgrading a local CVS repository
      3.1. Server file layout diagram
      3.2. Package file layout diagram
      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
      3.1. Package files
      3.2. Context Hierarchy Example
      3.3. acs_objects example data
      6.1. Internationalization and Localization Overview
      List of Examples
      4.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/install-cvs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v
diff -u -N -r1.29 -r1.30
--- openacs-4/packages/acs-core-docs/www/install-cvs.html	24 Jun 2004 10:44:39 -0000	1.29
+++ openacs-4/packages/acs-core-docs/www/install-cvs.html	5 Jul 2004 14:24:59 -0000	1.30
@@ -1,4 +1,4 @@
-Initialize CVS (OPTIONAL)
      Alex logo
      Prev Appendix�B.�Install additional supporting software Next
      Initialize CVS (OPTIONAL)
      CVS is a source control system.  Create and initialize a
+Initialize CVS (OPTIONAL)
      Alex logo
      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 -N -r1.30 -r1.31
--- openacs-4/packages/acs-core-docs/www/install-daemontools.html	24 Jun 2004 10:44:39 -0000	1.30
+++ openacs-4/packages/acs-core-docs/www/install-daemontools.html	5 Jul 2004 14:24:59 -0000	1.31
@@ -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.
      1. Install Daemontools
        download daemontools and install it.
        • Red Hat 8
          [root root]# mkdir -p /package
+      services.
          1. 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
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 -N -r1.28 -r1.29
--- openacs-4/packages/acs-core-docs/www/install-full-text-search.html	24 Jun 2004 10:44:39 -0000	1.28
+++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html	5 Jul 2004 14:24:59 -0000	1.29
@@ -1,7 +1,7 @@
 Install Full Text Search
              Alex logo
              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.
              1. 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.)
        [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql
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 -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/install-next-add-server.html	22 Jun 2004 12:53:52 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/install-next-add-server.html	5 Jul 2004 14:24:59 -0000	1.7
@@ -4,7 +4,7 @@
 
        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://service0.com and
     http://bar.com on the same
     machine.  The easiest way is to assign each one a different ip
     address.  Then you can install two services as above, but with
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 -N -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html	24 Jun 2004 10:44:39 -0000	1.13
+++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html	5 Jul 2004 14:24:59 -0000	1.14
@@ -63,6 +63,6 @@
 
         Most of this information comes from Tom Jackson's AOLserver+Daemontools
           Mini-HOWTO.
-
      Table�6.1.�How it Works
      ProgramInvoked by this program ...... using this fileWhere to find errorsLog goes toUse these commands to control it
      svscanboot
+
      Table�6.1.�How it Works
      ProgramInvoked by this program ...... using this fileWhere to find errorsLog goes toUse these commands to control it
      svscanboot
       init/etc/inittabps -auxw | grep readproctitlen/a�
      aolserversupervise
 (a child of svscanboot)/service/$OPENACS_SERVICE_NAME/run/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.logsvc -k /service/$OPENACS_SERVICE_NAME
      postgresqlRedhat 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 -N -r1.30 -r1.31
--- openacs-4/packages/acs-core-docs/www/install-qmail.html	24 Jun 2004 10:44:39 -0000	1.30
+++ openacs-4/packages/acs-core-docs/www/install-qmail.html	5 Jul 2004 14:24:59 -0000	1.31
@@ -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
@@ -43,7 +43,7 @@
 send outgoing mail.
      [root ucspi-tcp-0.88]# cp /tmp/openacs-5.2.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.2.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,
+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,7 +124,7 @@
 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.2.0d1/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc
 [root alias]# chmod 755 /var/qmail/rc
Index: openacs-4/packages/acs-core-docs/www/install-redhat.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v
diff -u -N -r1.30 -r1.31
--- openacs-4/packages/acs-core-docs/www/install-redhat.html	24 Jun 2004 10:44:39 -0000	1.30
+++ openacs-4/packages/acs-core-docs/www/install-redhat.html	5 Jul 2004 14:24:59 -0000	1.31
@@ -26,7 +26,7 @@
 	
      1. 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
      2. On the pop-up window asking "Are you sure
 	  you want to do this?" click
 	  Yes
-	  IF YOU ARE WIPING YOUR HARD DRIVE.
      3. 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.
      1. 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
      1. 
-              
+              
               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
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 -N -r1.24 -r1.25
--- openacs-4/packages/acs-core-docs/www/install-steps.html	29 Jun 2004 15:50:15 -0000	1.24
+++ openacs-4/packages/acs-core-docs/www/install-steps.html	5 Jul 2004 14:24:59 -0000	1.25
@@ -37,7 +37,7 @@
 su - $OPENACS_SERVICE_NAME
 svc -d /service/$OPENACS_SERVICE_NAME
 dropdb $OPENACS_SERVICE_NAME
-createdb $OPENACS_SERVICE_NAME
        Setting a global shell variable for cut and paste.�In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME.  In order to set it globally so that it works for any new users or special service users you may create, edit the file /etc/profile and add this line:
        export OPENACS_SERVICE_NAME=service0
      Paths and Users
      Table�2.1.�Default directories for a standard install
      Fully qualified domain name of your serveryourserver.test
      name of administrative access accountremadmin
      OpenACS service$OPENACS_SERVICE_NAME (set to service0 in default install)
      OpenACS service account$OPENACS_SERVICE_NAME
      OpenACS database name$OPENACS_SERVICE_NAME
      Root of OpenACS service file tree (SERVERROOT)/var/lib/aolserver/$OPENACS_SERVICE_NAME
      Location of source code tarballs for new software/tmp
      The OpenACS tarball contains some files which
+createdb $OPENACS_SERVICE_NAME
      Setting a global shell variable for cut and paste.�In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME.  In order to set it globally so that it works for any new users or special service users you may create, edit the file /etc/profile and add this line:
      export OPENACS_SERVICE_NAME=service0
      Paths and Users
      Table�2.1.�Default directories for a standard install
      Fully qualified domain name of your serveryourserver.test
      name of administrative access accountremadmin
      OpenACS service$OPENACS_SERVICE_NAME (set to service0 in default install)
      OpenACS service account$OPENACS_SERVICE_NAME
      OpenACS database name$OPENACS_SERVICE_NAME
      Root of OpenACS service file tree (SERVERROOT)/var/lib/aolserver/$OPENACS_SERVICE_NAME
      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.2.0d1/packages/acs-core-docs/www/files
      Database backup directory/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
      Service config files/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
      Service log files/var/lib/aolserver/$OPENACS_SERVICE_NAME/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
Index: openacs-4/packages/acs-core-docs/www/ix01.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v
diff -u -N -r1.18 -r1.19
--- openacs-4/packages/acs-core-docs/www/ix01.html	24 Jun 2004 10:44:39 -0000	1.18
+++ openacs-4/packages/acs-core-docs/www/ix01.html	5 Jul 2004 14:24:59 -0000	1.19
@@ -1,2 +1,2 @@
-Index
      Alex logo
      Prev  
      Index
      Symbols
      $OPENACS_SERVICE_NAME, Paths and Users
      A
      AOLserver
      configuration, Installation Option 2: Install from tarball
      Automated tests, Write automated tests
      C
      computeroutput
      code, Code
      cvs
      initializing, Initialize CVS (OPTIONAL)
      setup, Using CVS with an OpenACS Site
      D
      daemontools
      installation, Install Daemontools (OPTIONAL)
      docbook
      installation, Install Red Hat 8/9
      DocBook
      DTD, 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)
      ssh, Install Red Hat 8/9
      T
      The publish point for new packages should be
+Index
      Alex logo
      Prev  
      Index
      Symbols
      $OPENACS_SERVICE_NAME, Paths and Users
      A
      AOLserver
      configuration, Installation Option 2: Install from tarball
      Automated tests, Write automated tests
      C
      computeroutput
      code, Code
      cvs
      initializing, Initialize CVS (OPTIONAL)
      setup, Using CVS with an OpenACS Site
      D
      daemontools
      installation, Install Daemontools (OPTIONAL)
      docbook
      installation, Install Red Hat 8/9
      DocBook
      DTD, 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)
      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 
      How to Update the translations Up 
      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 -N -r1.18 -r1.19
--- openacs-4/packages/acs-core-docs/www/maint-performance.html	24 Jun 2004 10:44:39 -0000	1.18
+++ openacs-4/packages/acs-core-docs/www/maint-performance.html	5 Jul 2004 14:24:59 -0000	1.19
@@ -1,7 +1,7 @@
 Diagnosing Performance Problems
      Alex logo
      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:
          1. Go to Main Site : Site-Wide Administration : Install Software
          2. Click on "Install New Application" in "Install from OpenACS Repository"
          3. Choose "ACS Developer Support">
          4. After install is complete, restart the server.
          5. Browse to Developer Support, which is automatically mounted at /ds.
-              
          6. Turn on Database statistics
          7. Browse directly to a slow page and click "Request Information" at the bottom of the page.
          8. 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
            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:
          [$OPENACS_SERVICE_NAME ~]$ svrmgrl
+              
        • 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
          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:
        [$OPENACS_SERVICE_NAME ~]$ svrmgrl
 
 Oracle Server Manager Release 3.1.7.0.0 - Production
 
@@ -43,7 +43,7 @@
     
        
       To be able to get a overview of how Oracle executes a particular query,
       install "autotrace". I usually follow the instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html.
-    
        Make sure, that the Oracle CBO works with adequate statistics
        
+    
        Make sure, that the Oracle CBO works with adequate statistics
        
     The Oracle Cost Based optimizer is a piece of software that tries to find
     the "optimal" execution plan for a given SQL statement. For that it
     estimates the costs of running a SQL query in a particular way (by default
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 -N -r1.13 -r1.14
--- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html	24 Jun 2004 10:44:39 -0000	1.13
+++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html	5 Jul 2004 14:24:59 -0000	1.14
@@ -1,20 +1,69 @@
 Staged Deployment for Production Networks
        Alex logo
        Prev 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:  (THIS SECTION IN DEVELOPMENT)
        • Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested.
        • Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.
        Deployment with CVS
        With this method, we control the files on a site via CVS.  In this example, there is one development site and one production site.  The only way files should move between the two is via cvs.  The production site could run "HEAD" from cvs (raw example from chat log:)
        -1) change the file on dev as desired
+        
        This section describes two minimal-risk methods for deploying changes on a production network.  The important characteristics of a safe change deployment include:  (THIS SECTION IN DEVELOPMENT)
        • Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested.
        • Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.
        Method 1: Deployment with CVS
        With this method, we control the files on a site via
+      CVS. This example uses one developmental server (service0-dev) and one
+      production server (service0). Depending on your needs, you can also
+      have a staging server for extensive testing before you go
+      live. The only way files should move between the server
+      instances is via cvs.
        To set up a developmental installation, first set up
+      either your developmental installation or your production
+      installation, and follow the instructions for committing your
+      files to CVS. We'll assume in this example that you set up the
+      production server (service0). To set up the developmental instance,
+      you then follow the intall guide again, this time creating a new
+      user (service0-dev) that you'll use for the new installation. To get
+      the files for service0-dev, you check them out from cvs (check out
+      service0). 
        +su - service0-dev
+co -d /cvsroot service0
+mv service0 /var/lib/aolserver/service0-dev
+ln -s /home/service0-dev/web /var/lib/aolserver/service0-dev
+emacs web/etc/config.tcl
+emacs web/etc/daemontools/run
+
        In the config.tcl file, you'll probably want to pay attention
+      the rollout support section. That will ensure that email on your
+      developmental server will not be sent out to the general world.
        Also, instead of going through the OpenACS online
+      installer, you'll actually load live data into your production
+      server. 
        You can even automate the process of getting live data
+      from your production server. Copy something like this to
+      /home/service0-dev/bin and put it in service0-dev's crontab to
+      run once a night. You'll need to make sure the database backups
+      are set up in service0's crontab, and that if the servers are on
+      different physical machines, that the database backup is copied
+      to the developmental machine once per night.
        +/usr/local/bin/svc -d /service/service0-dev
+/bin/sleep 60
+# this deletes the dev database!
+/usr/local/pgsql/bin/dropdb service0-dev
+/usr/local/pgsql/bin/createdb -E UNICODE service0-dev
+# this is not necessary from Postgres 7.4 on
+/usr/local/pgsql/bin/psql -f /var/lib/aolserver/service0-dev/packages/acs-kernel/sql/postgresql/postgresql.sql service0
+mv /var/lib/aolserver/service0/database-backup/service0-nightly-backup.dmp.gz /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp.gz
+/bin/gunzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp.gz
+/usr/bin/perl -pi -e 's/^\\connect service0$/\\connect service0-dev/' /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp
+/usr/local/pgsql/bin/psql service0-dev < /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp
+/usr/local/bin/svc -u /service/service0-dev
+/bin/gzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp
+
        Your developmental server will always have data about a day
+      old.
        To make changes on service0-dev:
        +1) change the file on service0-dev as desired
 2) test the new file
 3) commit the file: 
-if the file is /web/foo-dev/www/index.adp, do: 
+if the file is /var/lib/aolserver/service0-dev/www/index.adp, do: 
 
-cd /web/foo-dev/www
+cd /var/lib/aolserver/service0-dev/www
 cvs diff index.adp (this is optional; it's just a
 reality check)
 the lines starting > will be added and the lines
 starting < will be removed, when you commit
 if that looks okay, commit with: 
 cvs -m "changing text on front page for February conference" index.adp
-the stuff in -m "foo" is a comment visible only from within cvs commands
+the stuff in -m "service0" is a comment visible only from within cvs commands
+
        To make these changes take place on service0:
         4) update the file on production:
-cd /web/foo-prod/www
-cvs up index.adp
        The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.'  So a better method is to use a tag.  This guarantees that, at any time in the future, you can retrieve exactly the same set of code.  This is useful for both of the characteristics of safe change deployment.  For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code.  For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems.  .... example of using tags to follow ...
        A/B Deployment
        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 A/B Deployment: Database is not changed
        Figure�6.2.�Simple A/B Deployment - Step 1
        Simple A/B Deployment - Step 1
        Figure�6.3.�Simple A/B Deployment - Step 2
        Simple A/B Deployment - Step 2
        Figure�6.4.�Simple A/B Deployment - Step 3
        Simple A/B Deployment - Step 3
        Complex A/B Deployment: Database is changed
        Figure�6.5.�Complex A/B Deployment - Step 1
        Complex A/B Deployment - Step 1
        Figure�6.6.�Complex A/B Deployment - Step 2
        Complex A/B Deployment - Step 2
        Figure�6.7.�Complex A/B Deployment - Step 3
        Complex A/B Deployment - Step 3
        Prev Home Next
        High Availability/High Performance Configurations Up Installing SSL Support for an OpenACS service
        docs@openacs.org
        View comments on this page at openacs.org
        
+cd /var/lib/aolserver/service0/www
+cvs up -Pd index.adp
        If you make changes that require changes to the database,
+      test them out first on service0-dev, using either -create.sql or
+      upgrade scripts. Once you've tested them, you then update and
+      run the upgrade scripts from the package manager. 
        The production site can run "HEAD" from cvs.
        The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.'  So a better method is to use a tag.  This guarantees that, at any time in the future, you can retrieve exactly the same set of code.  This is useful for both of the characteristics of safe change deployment.  For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code.  For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems.  .... example of using tags to follow ...
      Method 2: A/B Deployment
      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 A/B Deployment: Database is not changed
      Figure�6.2.�Simple A/B Deployment - Step 1
      Simple A/B Deployment - Step 1
      Figure�6.3.�Simple A/B Deployment - Step 2
      Simple A/B Deployment - Step 2
      Figure�6.4.�Simple A/B Deployment - Step 3
      Simple A/B Deployment - Step 3
      Complex A/B Deployment: Database is changed
      Figure�6.5.�Complex A/B Deployment - Step 1
      Complex A/B Deployment - Step 1
      Figure�6.6.�Complex A/B Deployment - Step 2
      Complex A/B Deployment - Step 2
      Figure�6.7.�Complex A/B Deployment - Step 3
      Complex A/B Deployment - Step 3
      Prev Home Next
      High Availability/High Performance Configurations Up Installing SSL Support for an OpenACS service
      docs@openacs.org
      View comments on this page at openacs.org
      
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 -N -r1.41 -r1.42
--- openacs-4/packages/acs-core-docs/www/objects.html	29 Jun 2004 15:50:15 -0000	1.41
+++ openacs-4/packages/acs-core-docs/www/objects.html	5 Jul 2004 14:24:59 -0000	1.42
@@ -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
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 -N -r1.40 -r1.41
--- openacs-4/packages/acs-core-docs/www/openacs.html	29 Jun 2004 15:50:15 -0000	1.40
+++ openacs-4/packages/acs-core-docs/www/openacs.html	5 Jul 2004 14:24:59 -0000	1.41
@@ -220,7 +220,7 @@
 CREATE DATABASE
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
 su - $OPENACS_SERVICE_NAME
-createdb -E UNICODE $OPENACS_SERVICE_NAME
    • 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.
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ 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 $OPENACS_SERVICE_NAME
+createdb -E UNICODE $OPENACS_SERVICE_NAME
    • 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.
      [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ 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 $OPENACS_SERVICE_NAME
 0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME
      Depending on your distribution, you may receive
                 email when the crontab items are executed. If you
                 don't want to receive email for those crontab items,
@@ -233,7 +233,7 @@
 	  need to configure a virtual server.  The Reference Platform
 	  uses a configuration file included in the OpenACS tarball,
 	  /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl.
-	   Open it in an editor to adjust the parameters.
      [root root]# su - $OPENACS_SERVICE_NAME
+	   Open it in an editor to adjust the parameters.
      [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc
 [$OPENACS_SERVICE_NAME etc]$ emacs config.tcl
 
      
@@ -357,7 +357,7 @@
     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
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 -N -r1.40 -r1.41
--- openacs-4/packages/acs-core-docs/www/packages.html	29 Jun 2004 15:50:15 -0000	1.40
+++ openacs-4/packages/acs-core-docs/www/packages.html	5 Jul 2004 14:24:59 -0000	1.41
@@ -3,168 +3,60 @@
           by OpenACS documentation staff.
         
      • Overview
      
       This document is a guide on how to write a software package for
-      OpenACS. OpenACS packages are installed and maintained
-      with the OpenACS Package Manager (APM).  This document presents reasons
-      for packaging software, conventions for the file system and naming
-      that must be followed, and step by step instructions for creating a
-      new package for the "Notes" example package.
-    
      Why package your software?
      
-      To answer this question, we should examine how OpenACS servers were
-      organized in the past. We will assume throughout this document that
-      the page root for your server is called ROOT.  In OpenACS
-      3.2.x and earlier, a typical server might have a file system behind it
-      that looked something like this:
-    
      +      OpenACS. OpenACS packages are installed and maintained with the
+      OpenACS Package Manager (APM) which is part of the acs-admin
+      package.  This document presents reasons for packaging software,
+      conventions for the file system and naming that must be
+      followed, and step by step instructions for creating a new
+      package for the "Notes" example package.
+    
      Server file layout
      
+      Here is how an OpenACS 5 server is laid out
+      starting from the Server root (ROOT):
+    
      Figure�11.1.�Server file layout diagram
       ROOT/
-   bin/
-   parameters/
-        ad.ini
-     tcl/
-        core tcl libraries here
-     www/
-         admin/
-             forums/
-                 site wide admin for forums
-             intranet/
-                 site wide admin for intranet
-
-             ... and so on for all modules ...
-
-         forums/
-             pages for forums
-             admin/
-                 other admin pages for forums
-         intranet/
-             pages for intranet
-             admin/
-                 other admin pages for intranet
-         doc/
-             documentation
-             sql/
-                core and application data models here
-
-         ... and so on for all modules ... 
-
      
-      In previous versions of OpenACS, you wrote a new application like this:
-    
      1. Put all Tcl library procedures under
-      server-root/tcl.
      2. Put all User viewable content under
-      server-root/www.
      3. Put all Admin content under /admin/package-key/.
-    
      
-      This structure is very simple, and worked well in a world where
-      OpenACS was basically a single monolithic entity. But, this organization
-      made it difficult to distribute modules as independent packages, because
-      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.2.0d1 server is laid out:
-    
      -ROOT/
     bin/
+        Various executables and scripts for server maintanence.
+    content-repository-content-files/
+        content repository content stored in the filesystem.
+    etc/
+        Installation scripts and configuration files.
     packages/
         acs-admin/
         acs-api-browser/
-        acs-content-repository/
-        acs-core-docs/
-        acs-developer-support/
-        acs-kernel/
-        acs-ldap-authentication/
-        acs-messaging/
-        acs-subsite/
-        acs-templating/
-        acs-test-harness/
-        acs-util/
-        acs-workflow/
-        forums/
-               forums.info
-               catalog/
-                    i18n message catalogs
-               lib/
-		    includable page fragments (.tcl/.adp pairs)
-               sql/
-                    oracle/
-                         oracle data model
-                    postgresql/
-                         postgresql data model
-               tcl/
-                    tcl library code
-               www/
-                    user visible pages
-                    admin/
-                         administration pages
-                    doc/
-                         documentation
-        message-catalog/
-        news/
-        notification/
-        page/
+        ... many many more...
+        workflow/
+    log/
+        Server error and access logs
     tcl/
-            bootstrap code
+        bootstrap code
     www/
-            misc pages
-
      
-      Note that a major reorganization has happened here. The diagram only
-      expands the structure of the forums/ package directory,
-      but all the others are basically the same. Each package encapsulates
-      all of its data model, library code, logic, adminstration pages and
-      user pages in a single part of the file tree. This organization has
-      two major advantages:
-    
      •  
-          This structure makes it easy for developers to track
-          down everything that is related to a
-          particular package without hunting all over the file system.
-        
      •  
-          Encapsulating everything
-          about a package in one place also makes it much easier to
-          distribute packages independently from the OpenACS itself.
-        
      
+        Pages not in packages (static content, customized pages)
      What a Package Looks Like
      
+      Each package encapsulates all of its data model, library code,
+      logic, adminstration pages and user pages in a single part of
+      the file tree.  This means developers can track down
+      everything that is related to a particular
+      package without hunting all over the file system.  Encapsulating
+      everything about a package in one place also makes it much
+      easier to distribute packages independently from the OpenACS Core.
+    
      
       In order to make this work, we need a system that keeps track of the
       packages that have been installed in the server, where those packages
       have been installed, and a standard way to map URLs that a client
       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.2.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
-      system.  The APM is responsible for:
-    
      1. Package registration
      2. Automatic installation of packages: loading data models, code
-      libraries, and so on.
      3. Checking what packages depend on what other packages.
      4. Storing information on the package including ownership and a file
-      list.
      
-      In addition for packages that are applications, the APM is responsible
-      for keeping track of where in the site a user must go in order to use
-      the application. To do this, the APM defines a set of objects that we
-      call package instances. Once a package is loaded, the
-      administrator can create as many instances of the package as she
-      likes, and map these instances to any URL in the site that she
-      wants. If packages are analogous to executable programs in an
-      operating system, then package instances are analgous to multiple
-      running copies of a single program. Each instance can be independently
-      administered and each instance maintains its own set of application
-      parameters and options.
+      removal. In OpenACS 5, this tool is called the APM.
     
      
-      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.2.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.
-    
      
-      We will also discuss how to organize your files and queries so
-      they work with the OpenACS Query Dispatcher.
-    
      What a Package Looks Like
      
       
       To illustrate the general structure of a package, let's see what the
-      package for the "notes" application should look like. This is shown in
-      the diagram below:
-    
      -
+      package for the "notes" application should look like.
+    
      Figure�11.2.�Package file layout diagram
       ROOT/
   +-- packages/    APM Root
         |
         +-- notes/  Package Root 
         |     |
-        |     |
+        |     +-- notes.info                              Package Specification File
         |     +-- sql/
         |     |     |
         |     |     +-- oracle/
@@ -190,6 +82,10 @@
         |     |     +-- notes-init.tcl                    Tcl Initialization
         |     |     +-- notes-init.xql                    Queries for notes-init.tcl (work in all DBs)      
         |     |     +-- *.tcl                             Tcl Library Files
+        |     +-- lib/
+        |     |     |
+        |     |     +-- *.tcl                             Includable page logic
+        |     |     +-- *.adp                             Includable page templates
         |     +-- www/
         |     |     |
         |     |     +-- admin/                            Administration UI
@@ -200,23 +96,37 @@
         |     |     |     +-- ...                         Administration UI Pages
         |     |     |
         |     |     +-- doc/                              Documentation
-        |     |     |     +-- index.tcl                   Documentation Index Page
+        |     |     |     +-- index.html                  Documentation Index Page
         |     |     |     +-- ...                         Administration Pages
+        |     |     +-- resources/                        Static Content
+        |     |     |     +-- ...                         Static Content files
         |     |     +-- index.tcl                         UI Index Page
         |     |     +-- index.adp                         UI Index Template
         |     |     +-- index.xql                         Queries for UI Index page      
         |     |     +-- *.tcl                             UI Logic Scripts
         |     |     +-- *.adp                             UI Templates
         |     |     +-- *-oracle.xql                      Oracle-specific Queries
         |     |     +-- *-postgresql.xql                  PostgreSQL-specific Queries
-        |     +-- notes.info                              Package Specification File
-        +-- Other package directories.
-
-    
      
+        +-- Other package directories.
      
       All file locations are relative to the package root, which in this
       case is ROOT/packages/notes. The following table
       describes in detail what each of the files up in the diagram contain.
-    
      File TypeIts UseNaming Convention
      Data Model Creation Script
+    
       
+      A special note on the
+      PACKAGE-KEY/www/resources
+      directory.
+      Files in this directory are available at
+      http://yourserver/resources/PACKAGE-KEY/...
+      and are returned without any permissions checking or even checks
+      that the package is installed or mounted.  Files are returned
+      directly, so .tcl or .adp files are not sourced in these
+      directories.  This makes it suitable for storing icons, css
+      files, javascript, and other static content which can be treated
+      this way.
+    
      Table�11.1.�Package files
      File TypeIts UseNaming Convention
      Package Specification FileThe package specification file is an XML file generated and
+          maintained by the OpenACS Package Manager (APM).  It specifies
+          information about the package including its parameters and its
+          files.notes.info
      Data Model Creation Script
           Contains the SQL that creates the necessary data model and
           PL/SQL packages (or PL/pgSQL or whatever) to support the
           package. The name must match the convention below or the
@@ -288,20 +198,45 @@
           a fault in the system.www/admin/tests/
      Regression Test Index PageThe regression test directory must have an index page that
           displays all of the tests available and provides information
           on how to run them.  This file can have any extension, as long
-          as its name is index./www/admin/tests/index.html
      DocumentationEvery package must include a full set of documentation that
+          as its name is index.www/admin/tests/index.html
      DocumentationEvery package must include a full set of documentation that
           includes requirements and design documents, and user-level and
-          developer-level documentation where appropriate./www/doc/
      Documentation Index PageThe documentation directory must include a static HTML file with the name
-          of index.html./www/doc/index.html
      UI Logic ScriptsPackages provide a UI for users to access the system.  The UI
+          developer-level documentation where appropriate.www/doc/
      Documentation Index PageThe documentation directory must include a static HTML file with the name
+          of index.html.www/doc/index.html
      UI Logic ScriptsPackages provide a UI for users to access the system.  The UI
           is split into Logic and Templates.  The logic scripts
           perform database queries and prepare variables for
-          presentation by the associated templates./www/*.tcl
      UI TemplatesTemplates are used to control the presentation of the UI.
+          presentation by the associated templates.www/*.tcl
      UI TemplatesTemplates are used to control the presentation of the UI.
           Templates receive a set of data sources from the logic scripts
-          and prepare them for display to the browser./www/*.adp
      UI Index PageThe UI must have an index page composed of a logic script
+          and prepare them for display to the browser.www/*.adp
      UI Index PageThe UI must have an index page composed of a logic script
           called index.tcl and a template called
-          index.adp./www/index.tcl
      Package Specification FileThe package specification file is an XML file generated and
-          maintained by the OpenACS Package Manager (APM).  It specifies
-          information about the package including its parameters and its
-          files.notes.info
      Making a Package
      
+          index.adp.
      		www/index.tcl
      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
+      system.  The APM is responsible for:
+    
      1. Package registration
      2. Automatic installation of packages: loading data models, code
+      libraries, and so on.
      3. Checking what packages depend on what other packages.
      4. Storing information on the package including ownership and a file
+      list.
      
+      In addition for packages that are applications, the APM is responsible
+      for keeping track of where in the site a user must go in order to use
+      the application. To do this, the APM defines a set of objects that we
+      call package instances. Once a package is loaded, the
+      administrator can create as many instances of the package as she
+      likes, and map these instances to any URL in the site that she
+      wants. If packages are analogous to executable programs in an
+      operating system, then package instances are analgous to multiple
+      running copies of a single program. Each instance can be independently
+      administered and each instance maintains its own set of application
+      parameters and options.
+    
      
+      The following sections will show you how to make a package for the
+      Notes application. In addition, they will discuss some site
+      management features in OpenACS 5 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.
+    
      
+      We will also discuss how to organize your files and queries so
+      they work with the OpenACS Query Dispatcher.
+    
      Making a Package
      
       Here is how you make a package.
     
      1. Login as a site-wide administrator on your web service.
     
      2. Go to the package manager on your server.  The URL is /acs-admin/apm.
@@ -391,15 +326,14 @@
           .tcl files for code, it does not
           do the same thing for data model files.  
         
      3. Now go back to the main management page for the notes
-      If your package has parameters, create them using the "Manage
-        Parameter Information" link.
      4. The new package has been created and installed in the server. At
+          If your package has parameters, create them using the "Manage
+          Parameter Information" link.  Define package callbacks via the "Tcl Callbacks (install,
+        instantiate, mount)" link.
      5. The new package has been created and installed in the server. At
       this point, you should add your package files to your CVS repository.
       I'll assume that you have set up your development repository according
       to the standards described in 
       this appendix. If so, then you just do this:
-    
        -
-% cd ROOT/packages
+    
        % cd ROOT/packages
 % cvs add notes
 % cd notes
 % cvs add notes.info
@@ -408,7 +342,6 @@
 % cvs add *.sql
 % cd ROOT/packages/notes
 % cvs commit -m "add new package for notes"
-
     
      6. 
       Now you can start developing the package. In addition to writing code,
       you should also consider the tasks outlined in the package development tutorial.
@@ -422,18 +355,9 @@
       pages underneath ROOT/www they will not appear on their
       own.  What we have to do is mount the application into the site
       map. That is, we have to define the URL from which the application
-      will serve its pages. This process is slightly more complex than in
-      OpenACS 3.x, but also much more flexible.
+      will serve its pages.
     
        
-      In OpenACS 3.x, everything in the site was implicitly mounted underneath
-      ROOT/www. AOLserver automatically took any URL like
-      /foo/bar/moo/baz.html and mapped it to the file
-      ROOT/www/foo/bar/moo/baz.html.  This was conveniently
-      simple, but lacked flexibility.  In particular, it was difficult to
-      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.2.0d1, administrators can define an arbitrary mapping between the
+      In OpenACS 5, 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
@@ -460,13 +384,8 @@
       instance of the notes application to the site. Name the
       new instance notes-1.
     
        
-      Then type this URL into your browser:
-
-    
        -
-http://your-server.your-domain.com/notes/hello.html
-
-    
        
+      Then type this URL into your browser: http://yourserver/notes/hello.html
+    
        
       Now you should see the contents of the page that you added. What has
       happened is that all URLs that start with /notes have
       been mapped in such a way as to serve content from the directory
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 -N -r1.34 -r1.35
--- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html	29 Jun 2004 15:50:15 -0000	1.34
+++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html	5 Jul 2004 14:24:59 -0000	1.35
@@ -100,7 +100,7 @@
     
      Context Hierarchy
      
       Suppose objects A, B, ..., 
       and F form the following hierarchy. 
-    
      Table�11.1.�Context Hierarchy Example
      A
      
+    
      Table�11.2.�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�11.2.�acs_objects example data
      object_idcontext_id
      2010
      3010
      4020
      5020
      6030
      
+    
      Table�11.3.�acs_objects example data
      object_idcontext_id
      2010
      3010
      4020
      5020
      6030
      
       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/postgres.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v
diff -u -N -r1.39 -r1.40
--- openacs-4/packages/acs-core-docs/www/postgres.html	29 Jun 2004 15:50:15 -0000	1.39
+++ openacs-4/packages/acs-core-docs/www/postgres.html	5 Jul 2004 14:24:59 -0000	1.40
@@ -100,7 +100,7 @@
 	  Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can
 	  configure PostgreSQL in various ways. For example, if you want to
 	  enable
-	  Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
+	  Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help.
 	
      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 --with-includes=/sw/include/ --with-libraries=/sw/lib --enable-locale --enable-multibyte \
Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v
diff -u -N -r1.30 -r1.31
--- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	24 Jun 2004 10:44:39 -0000	1.30
+++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html	5 Jul 2004 14:24:59 -0000	1.31
@@ -1,4 +1,4 @@
-Add PSGML commands to emacs init file (OPTIONAL)
      Alex logo
      Prev Appendix�B.�Install additional supporting software Next
      Add PSGML commands to emacs init file (OPTIONAL)
      
+Add PSGML commands to emacs init file (OPTIONAL)
      Alex logo
      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
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 -N -r1.44 -r1.45
--- openacs-4/packages/acs-core-docs/www/release-notes.html	29 Jun 2004 15:50:16 -0000	1.44
+++ openacs-4/packages/acs-core-docs/www/release-notes.html	5 Jul 2004 14:24:59 -0000	1.45
@@ -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/tutorial-css-layout.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html,v
diff -u -N -r1.2 -r1.3
--- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	29 Jun 2004 15:50:16 -0000	1.2
+++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html	5 Jul 2004 14:24:59 -0000	1.3
@@ -1,4 +1,4 @@
-Laying out a page with CSS instead of tables
      Alex logo
      Prev Chapter�10.�Advanced Topics Next
      Laying out a page with CSS instead of tables
      .LRN home page with table-based layout
      A sample of the HTML code (full source)
      <table border="0" width="100%">
+Laying out a page with CSS instead of tables
      Alex logo
      Prev Chapter�10.�Advanced Topics Next
      Laying out a page with CSS instead of tables
      .LRN home page with table-based layout
      A sample of the HTML code (full source)
      <table border="0" width="100%">
   <tr>
     <td valign="top" width="50%">
       <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%">
@@ -20,7 +20,7 @@
                   <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%">
                     <tr>
                       <td class=element-text>
-                        MBA 101
      .LRN Home with CSS-based layout
      A sample of the HTML code (full source)
      <div class="left">
+                        MBA 101
      .LRN Home with CSS-based layout
      A sample of the HTML code (full source)
      <div class="left">
   <div class="portlet-wrap-shadow">
     <div class="portlet-wrap-bl">
       <div class="portlet-wrap-tr">
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 -N -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html	29 Jun 2004 15:50:16 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html	5 Jul 2004 14:24:59 -0000	1.17
@@ -58,4 +58,4 @@
 initial revision: 1.1
 done
 (many lines omitted)
-[$OPENACS_SERVICE_NAME myfirstpackage]$
      Figure�10.1.�Upgrading a local CVS repository
      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
      
+[$OPENACS_SERVICE_NAME myfirstpackage]$
      Figure�10.1.�Upgrading a local CVS repository
      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 -N -r1.33 -r1.34
--- openacs-4/packages/acs-core-docs/www/tutorial-database.html	29 Jun 2004 15:50:16 -0000	1.33
+++ openacs-4/packages/acs-core-docs/www/tutorial-database.html	5 Jul 2004 14:24:59 -0000	1.34
@@ -1,7 +1,7 @@
 Setting Up Database Objects
      Alex logo
      Prev 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�9.2.�Tutorial Data Model
      Tutorial Data Model
      The top of each sql file has some
+
      Figure�9.2.�Tutorial Data Model
      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.
      [$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/sql/postgresql
-[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-create.sql
      Paste the text below into the file, save, and close.
      Figure�9.3.�The Database Creation Script
      -- creation script
+[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-create.sql
      Paste the text below into the file, save, and close.
      Figure�9.3.�The Database Creation Script
      -- creation script
 --
 -- @author joel@aufrecht.org
 -- @cvs-id &Id:$
@@ -61,7 +61,7 @@
     object.  Notice the use of "mfp."  This is derived from "My
     First Package" and 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.
      -[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-drop.sql
      Figure�9.4.�Database Deletion Script
      -- drop script
+[$OPENACS_SERVICE_NAME 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 -N -r1.32 -r1.33
--- openacs-4/packages/acs-core-docs/www/tutorial-debug.html	24 Jun 2004 10:44:39 -0000	1.32
+++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html	5 Jul 2004 14:24:59 -0000	1.33
@@ -1,7 +1,7 @@
 Debugging and Automated Testing
      Alex logo
      Prev 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 NumActionExpected Result
      001Browse to the index page while not logged in and
+    
      Manual testing
      Make a list of basic tests to make sure it works
      Test NumActionExpected Result
      001Browse to the index page while not logged in and
             while one or more notes exist.No edit or delete or add links should appear.
      002Browse 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-001Invoke mfp::note::create with a specific word as the title.Proc should return an object id.
      API-002Given an object id from API-001, invoke mfp::note::get.Proc should return the specific word in the title.
      API-003Given 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:
      [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
 [$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test
@@ -67,7 +67,7 @@
 goes inside -test_code {}.  We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get.  Proc should return the specific word in the title."
             set name [ad_generate_random_string]
       set new_id [mfp::note::add -title $name]
-      aa_true "Note add succeeded" [exists_and_not_null new_id]
      To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
      Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
      TCLWebtest tests
      API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
      Example
      Now we can add the rest of the API tests, including a test with deliberately bad data.  The complete test looks like:
      ad_library {
+      aa_true "Note add succeeded" [exists_and_not_null new_id]
      To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.)  To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".  Since we'll be changing it frequently, select "watch this file" on the next page.  This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing.  We can also add some aa_register_case flags to make it easier to run the test.  The -procs flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all.  The -cats flag, setting categories, makes it easier to control which tests to run.  The smoke test setting means that this is a basic test case that can and should be run any time you are doing any test. (a definition of "smoke test")
      Once the file is loaded, go to ACS Automated Testing and click on myfirstpackage.  You should see your test case.  Run it and examine the results.
      TCLWebtest tests
      API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs.  For this, we can use TCLwebtest.  TCLwebtest must be installed for this test to work.  This provides a library of functions that make it easy to call a page through HTTP, examine the results, and drive forms.  TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.
      Example
      Now we can add the rest of the API tests, including a test with deliberately bad data.  The complete test looks like:
      ad_library {
     Test cases for my first package.
 }
 
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 -N -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html	29 Jun 2004 15:50:16 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html	5 Jul 2004 14:24:59 -0000	1.17
@@ -6,5 +6,5 @@
         (37.1KB)
         after the label Distribution
         File: and save the file to
-        /tmp.
      
+        /tmp.
      
 
      Prev Home Next
      Profile your code Up Notifications
      docs@openacs.org
      View comments on this page at openacs.org
      
Index: openacs-4/packages/acs-core-docs/www/tutorial-html-email.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-html-email.html,v
diff -u -N -r1.1 -r1.2
--- openacs-4/packages/acs-core-docs/www/tutorial-html-email.html	24 Jun 2004 09:42:26 -0000	1.1
+++ openacs-4/packages/acs-core-docs/www/tutorial-html-email.html	5 Jul 2004 14:24:59 -0000	1.2
@@ -1,11 +1,11 @@
-Sending HTML email from your application
      Alex logo
      Prev Chapter�10.�Advanced Topics Next
      Sending HTML email from your application
      by Jade Rubick
      
+Sending HTML email from your application
      Alex logo
      Prev Chapter�10.�Advanced Topics Next
      Sending HTML email from your application
      by Jade Rubick
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
      Sending email is fairly simple using the acs-mail-lite
     package. Sending HTML email is only slightly more complicated.
           set subject "my subject"
 
-    set message "<b>Bold</b> not bold"
+    set message "<b>Bold</b> not bold"
 
     set from_addr "me@myemail.com"
 
@@ -33,4 +33,4 @@
         -subject $subject \
         -body $message \
         -extraheaders $extra_headers
-    
      Prev Home Next
      Using .vuh files for pretty urls Up Future Topics
      docs@openacs.org
      View comments on this page at openacs.org
      
+    
      Prev Home Next
      Laying out a page with CSS instead of tables Up Basic Caching
      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 -N -r1.33 -r1.34
--- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	24 Jun 2004 10:44:39 -0000	1.33
+++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html	5 Jul 2004 14:24:59 -0000	1.34
@@ -1,7 +1,7 @@
 Creating an Application Package
      Alex logo
      Prev Chapter�9.�Development Tutorial Next
      Creating an Application 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 package. A package 
+        
      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 functions to other packages and has no direct interface, a
@@ -17,11 +17,11 @@
         right now.  Code that is temporary hackage is clearly marked.
       
      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.2.0d1 distribution.
-	  
      Figure�9.1.�Assumptions in this section
      Fully qualified domain name of your serveryourserver.test
      URL of your serverhttp://yourserver.test:8000
      Name of development account$OPENACS_SERVICE_NAME
      New Package keymyfirstpackage
      Use the APM to initialize a new package
      We use the ACS Package Manager (APM) to add, remove, and
+	  
      Figure�9.1.�Assumptions in this section
      Fully qualified domain name of your serveryourserver.test
      URL of your serverhttp://yourserver.test:8000
      Name of development account$OPENACS_SERVICE_NAME
      New Package keymyfirstpackage
      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
@@ -53,7 +53,7 @@
         
      This creates a package rooted at
           /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage.
           This is the "home directory" of our new package, and all
-          files in the package will be within this directory.
      Add an Application Instance to the Server
      In order to see your work in progress, you must create a
+          files in the package will be within this directory.
      Add an Application Instance to the Server
      In order to see your work in progress, you must create a
       map between the URL space of incoming requests and the package application instance.
       You do this by adding the application in the main site administration).  This
       creates a link between the incoming URL requests and an
@@ -64,7 +64,7 @@
       in this tutorial.
      1. Browse to
 http://yourserver.test:8000/admin/applications/application-add/.
      2. 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/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
      Quick start
      The remainder of the tutorial walks you through each file one at a time as you create the package.  You can skip all this, and get a working package, by doing the following:
      cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
+      to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www.
      Quick start
      The remainder of the tutorial walks you through each file one at a time as you create the package.  You can skip all this, and get a working package, by doing the following:
      cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial
 psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql
 cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/
 mkdir ../../../../myfirstpackage/lib
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 -N -r1.33 -r1.34
--- openacs-4/packages/acs-core-docs/www/tutorial-pages.html	29 Jun 2004 15:50:16 -0000	1.33
+++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html	5 Jul 2004 14:24:59 -0000	1.34
@@ -1,8 +1,8 @@
 Creating Web Pages
      Alex logo
      Prev 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/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
      To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".
      Page Map
      Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
      Figure�9.5.�Page Map
      Page Map
      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/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/
      To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage".
      Page Map
      Our package will have two visible pages.  The first shows a list of all objects; the second shows a single object in view or edit mode, and can also be used to add an object.  The index page will display the list, but since we might reuse the list later, we'll put it in a seperate file and include it on the index page.
      Figure�9.5.�Page Map
      Page Map
      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/upgrade-4.5-to-4.6.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html,v
diff -u -N -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html	24 Jun 2004 10:44:40 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html	5 Jul 2004 14:24:59 -0000	1.17
@@ -1,4 +1,4 @@
-Upgrading 4.5 or higher to 4.6.3
      Alex logo
      Prev Chapter�5.�Upgrading Next
      Upgrading 4.5 or higher to 4.6.3
      The required platform for OpenACS 4.6 is the same as
+Upgrading 4.5 or higher to 4.6.3
      Alex logo
      Prev Chapter�5.�Upgrading Next
      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.  
      If upgrading from 4.2, you need to manually run acs-kernel/sql/postgres/upgrade-4.2-4.5.sql.  See Bug #632
      1. Make a Backup.�Back up the database and file system (see the section called “Manual backup and recovery”).
      2. OPTIONAL: Upgrade OpenFTS.�the section called “Upgrading OpenFTS from 0.2 to 0.3.2”
      3. 
             Stop the server
           
        [root root]# svc -d /service/$OPENACS_SERVICE_NAME
      4. Upgrade the file system.�the section called “Upgrading the OpenACS files”
      5. 
Index: openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html,v
diff -u -N -r1.6 -r1.7
--- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html	24 Jun 2004 10:44:40 -0000	1.6
+++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html	5 Jul 2004 14:24:59 -0000	1.7
@@ -1,4 +1,4 @@
-Upgrading OpenACS 4.6.3 to 5.0
        Alex logo
        Prev Chapter�5.�Upgrading Next
        Upgrading OpenACS 4.6.3 to 5.0
        Prev Home Next
        Upgrading 4.5 or higher to 4.6.3 Up Upgrading 5.0.0 to 5.0.x or 5.1.x
        docs@openacs.org
        View comments on this page at openacs.org
        
Index: openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html,v
diff -u -N -r1.7 -r1.8
--- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html	24 Jun 2004 10:44:40 -0000	1.7
+++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html	5 Jul 2004 14:24:59 -0000	1.8
@@ -1 +1 @@
-Upgrading 5.0.0 to 5.0.x
        Alex logo
        Prev Chapter�5.�Upgrading Next
        Upgrading 5.0.0 to 5.0.x
        • Upgrading a stock site.�If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:
          1. Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"
          2. Select all of the packages you want to upgrade and proceed
          3. After upgrade is complete, restart the server as indicated.
          4. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
        • Upgrading a Custom or CVS site.�If you have custom code, and your site is in a CVS repository, upgrade with these steps:
          1. Upgrade the file system for all packages in use.�the section called “Upgrading the OpenACS files”
          2. Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"
          3. Select all of the packages you want to upgrade and proceed
          4. After upgrade is complete, restart the server as indicated.
          5. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
        Prev Home Next
        Upgrading OpenACS 4.6.3 to 5.0 Up Upgrading the OpenACS files
        docs@openacs.org
        View comments on this page at openacs.org
        
+Upgrading 5.0.0 to 5.0.x or 5.1.x
        Alex logo
        Prev Chapter�5.�Upgrading Next
        Upgrading 5.0.0 to 5.0.x or 5.1.x
        • Upgrading a stock site.�If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:
          1. Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"
          2. Select all of the packages you want to upgrade and proceed
          3. After upgrade is complete, restart the server as indicated.
          4. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
        • Upgrading a Custom or CVS site.�If you have custom code, and your site is in a CVS repository, upgrade with these steps:
          1. Upgrade the file system for all packages in use.�the section called “Upgrading the OpenACS files”
          2. Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"
          3. Select all of the packages you want to upgrade and proceed
          4. After upgrade is complete, restart the server as indicated.
          5. If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated messages.  Your local translations, if any, will take precedence over imported translations.
        Prev Home Next
        Upgrading OpenACS 4.6.3 to 5.0 Up Upgrading the OpenACS files
        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 -N -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html	24 Jun 2004 10:44:40 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html	5 Jul 2004 14:24:59 -0000	1.17
@@ -1,4 +1,4 @@
-Upgrading the OpenACS files
        Alex logo
        Prev Chapter�5.�Upgrading Next
        Upgrading the OpenACS files
        OpenACS is distributed as a collection of files, available as one big tarball, via CVS, and via automatic download from within the APM.  Upgrades work by first changing the file system (via any of the previous methods), and then using the APM to scan the file system, find upgrade scripts, and execute them.  This section describes how to upgrade the file system.  Starting with OpenACS 5.0, this section can generally be skipped because the OpenACS APM can directly download new files from the openacs.org repository.
        Many OpenACS site developers operate their own CVS repository to keep track of changes from the release OpenACS code.  This part describes how to import the latest OpenACS version into your own repository.  If you are using CVS, you will unpack the OpenACS 5.1 tarball into a working directory and then import that directory into cvs.  If you have changed files in the core packages, cvs will attempt to merge your changes.  You may have to manually merge some conflicts.  When that's finished, you can update your normal development checkout directory and the new files will appear.  If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased.
        • Upgrading files for a site which is not in a CVS repository.�Unpack the tarball into a new directory and copy its contents on top of your working directory.
          [root root]# su - $OPENACS_SERVICE_NAME
+Upgrading the OpenACS files
          Alex logo
          Prev Chapter�5.�Upgrading Next
          Upgrading the OpenACS files
          OpenACS is distributed as a collection of files, available as one big tarball, via CVS, and via automatic download from within the APM.  Upgrades work by first changing the file system (via any of the previous methods), and then using the APM to scan the file system, find upgrade scripts, and execute them.  This section describes how to upgrade the file system.  Starting with OpenACS 5.0, this section can generally be skipped because the OpenACS APM can directly download new files from the openacs.org repository.
          Many OpenACS site developers operate their own CVS repository to keep track of changes from the release OpenACS code.  This part describes how to import the latest OpenACS version into your own repository.  If you are using CVS, you will unpack the OpenACS 5.1 tarball into a working directory and then import that directory into cvs.  If you have changed files in the core packages, cvs will attempt to merge your changes.  You may have to manually merge some conflicts.  When that's finished, you can update your normal development checkout directory and the new files will appear.  If you aren't using CVS, you can unpack the tarball on top of your existing tree, but any customizations you've made to the kernel or core packages will be erased.
          • Upgrading files for a site which is not in a CVS repository.�Unpack the tarball into a new directory and copy its contents on top of your working directory.
            [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver
 [$OPENACS_SERVICE_NAME web]$ tar xzf /tmp/openacs-5-1.tar.gz
 [$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4
@@ -10,7 +10,7 @@
 cp -r openacs-5-1/* openacs-4
 exit
          • 
           Upgrading files for a site in a private CVS repository
-        
            Figure�5.2.�Upgrading a local CVS repository
            Upgrading a local CVS repository
            • Step 1: Import new CVS code.�There are two common ways to get new OpenACS code into your local CVS repository - via tarball or with a working CVS checkout of OpenACS.  Both methods work well for starting your local repository; the second method is better for incremental additions or upgrades.
              • (a): via tarball.�Download a current tarball and unpack the new files into a working directory.
                [root root]# su - $OPENACS_SERVICE_NAME
+        
                Figure�5.2.�Upgrading a local CVS repository
                Upgrading a local CVS repository
                • Step 1: Import new CVS code.�There are two common ways to get new OpenACS code into your local CVS repository - via tarball or with a working CVS checkout of OpenACS.  Both methods work well for starting your local repository; the second method is better for incremental additions or upgrades.
                  • (a): via tarball.�Download a current tarball and unpack the new files into a working directory.
                    [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME aolserver]$ cd /tmp
 [$OPENACS_SERVICE_NAME tmp]$ tar xzf openacs-5-1.tar.gz
 [$OPENACS_SERVICE_NAME tmp]$ cd openacs-5-1
                  • (b): via cvs working checkout.�Create a CVS checkout from OpenACS.  The first time you do this, you will need to create the checkout directory.  We use one dedicated directory for each branch of OpenACS - if you are using OpenACS 5.0,x, you only need an OpenACS 5.0 branch.  The openacs-5-1-compat tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package, including .LRN.  Each minor release of OpenACS since 5.0 has this tagging structure.  For example, OpenACS 5.1.x has openacs-5-1-compat.
@@ -27,15 +27,15 @@
 [$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd
              • (c) A single package via cvs working checkout.�You can add or upgrade a single package at a time, if you already have a cvs working directory.
                [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1
 [$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -d myfirstpackage
                In the next section, the import must be tailored to just this package.
            • Step 2: Merge New OpenACS code.�Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.
              Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.
              [$OPENACS_SERVICE_NAME openacs-5-1]$  cd /var/lib/aolserver/openacs-5-1
-              [$OPENACS_SERVICE_NAME openacs-5-1]$  cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" $OPENACS_SERVICE_NAME OpenACS openacs-5-1
+[$OPENACS_SERVICE_NAME openacs-5-1]$  cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" $OPENACS_SERVICE_NAME OpenACS openacs-5-1
             
              Tip
              If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly.  In this example, we are adding the myfirstpackage package.
              [root root]# su - $OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage
-[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1
              Create a new directory as temporary working space to reconcile conflicts between the new files and your current work.  The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day.
              [$OPENACS_SERVICE_NAME openacs-4.6]$  cd /var/lib/aolserver
+[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1
            Create a new directory as temporary working space to reconcile conflicts between the new files and your current work.  The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day.
            [$OPENACS_SERVICE_NAME openacs-5.1]$  cd /var/lib/aolserver
 [$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade
 [$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1
-(CVS feedback here)
            The file /tmp/openacs-upgrade/cvs.txt contains the results of the upgrade.  If you changed files that are part of the OpenACS tarball and those changes conflict with the 4.5-4.6 upgrade, you'll have to manually reconcile them.  Use the emacs command M-x sort-lines and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
            Once you've fixed any conflicts, commit the new code
+(CVS feedback here)
          The file /tmp/openacs-upgrade/cvs.txt contains the results of the upgrade.  If you changed files that are part of the OpenACS tarball and those changes conflict, you'll have to manually reconcile them.  Use the emacs command M-x sort-lines and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines.  When you're finished, or if there aren't any conflicts, save and exit.
          Once you've fixed any conflicts, commit the new code
             to your local tree.  
          [$OPENACS_SERVICE_NAME tmp]$ cd openacs-upgrade
-[$OPENACS_SERVICE_NAME openacs-upgrade]$ cvs commit -m "Upgraded to 4.6"
        • Step 3: Upgrade your local staging site.�Update your working tree with the new files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
          [$OPENACS_SERVICE_NAME openacs-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME openacs-upgrade]$ cvs commit -m "Upgraded to 5.1"
        • Step 3: Upgrade your local staging site.�Update your working tree with the new files.  The CVS flags ensure that new directories are created and pruned directories destroyed.
          [$OPENACS_SERVICE_NAME openacs-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
 (CVS feedback)
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
@@ -44,7 +44,7 @@
       
          1. [$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME
 [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd
 (CVS feedback)
-[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
          Upgrading a Production Site Safely
          If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:
          1. Declare a freeze on new cvs updates - ie, you cannot run cvs update
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
      Upgrading a Production Site Safely
      If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:
      1. Declare a freeze on new cvs updates - ie, you cannot run cvs update
    on the production site
      2. 
             Make a manual backup of the production site in addition to the
    automated backups
      3. Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of
@@ -59,4 +59,4 @@
           
      4. 
             Test the $OPENACS_SERVICE_NAME-upgrade site
           
      5. If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade.
        1. Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page.
        2. Repeat the upgrade with the most recent database
        3. Test the that the new site is functional.  If so, change the upgraded site to respond to
-               yourserver.net requests. If not, bring the original production site back up and return to the merge.
      Prev Home Next
      Upgrading 5.0.0 to 5.0.x Up Upgrading Platform components
      docs@openacs.org
      View comments on this page at openacs.org
      
+               yourserver.net requests. If not, bring the original production site back up and return to the merge.
      Prev Home Next
      Upgrading 5.0.0 to 5.0.x or 5.1.x Up Upgrading Platform components
      docs@openacs.org
      View comments on this page at openacs.org
      
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 -N -r1.16 -r1.17
--- openacs-4/packages/acs-core-docs/www/upgrade-overview.html	24 Jun 2004 10:44:40 -0000	1.16
+++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html	5 Jul 2004 14:24:59 -0000	1.17
@@ -3,4 +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.
      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:
      1. Browse to the Installer.
      2. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
      3. 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
      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$OPENACS_SERVICE_NAME
      OpenACS server name$OPENACS_SERVICE_NAME
      Root of OpenACS file tree/var/lib/aolserver/$OPENACS_SERVICE_NAME
      Database backup directory/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
      Prev Home Next
      Chapter�5.�Upgrading Up Upgrading 4.5 or higher to 4.6.3
      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:
      1. Browse to the Installer.
      2. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
      3. 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
      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$OPENACS_SERVICE_NAME
      OpenACS server name$OPENACS_SERVICE_NAME
      Root of OpenACS file tree/var/lib/aolserver/$OPENACS_SERVICE_NAME
      Database backup directory/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup
      Prev Home Next
      Chapter�5.�Upgrading Up Upgrading 4.5 or higher to 4.6.3
      docs@openacs.org
      View comments on this page at openacs.org
      
Index: openacs-4/packages/acs-core-docs/www/upgrade.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v
diff -u -N -r1.20 -r1.21
--- openacs-4/packages/acs-core-docs/www/upgrade.html	24 Jun 2004 10:44:40 -0000	1.20
+++ openacs-4/packages/acs-core-docs/www/upgrade.html	5 Jul 2004 14:25:00 -0000	1.21
@@ -1,4 +1,4 @@
-Chapter�5.�Upgrading
      Alex logo
      Prev Part�II.�Administrator's Guide Next
      Chapter�5.�Upgrading
      Table of Contents
      Overview
      Upgrading 4.5 or higher to 4.6.3
      Upgrading OpenACS 4.6.3 to 5.0
      Upgrading 5.0.0 to 5.0.x
      Upgrading the OpenACS files
      Upgrading Platform components
      by Joel Aufrecht
      
+Chapter�5.�Upgrading
      Alex logo
      Prev Part�II.�Administrator's Guide Next
      Chapter�5.�Upgrading
      Table of Contents
      Overview
      Upgrading 4.5 or higher to 4.6.3
      Upgrading OpenACS 4.6.3 to 5.0
      Upgrading 5.0.0 to 5.0.x or 5.1.x
      Upgrading the OpenACS files
      Upgrading Platform components
      by Joel Aufrecht
      
           OpenACS docs are written by the named authors, and may be edited
           by OpenACS documentation staff.
         
      Prev Home Next
      How Do I? Up Overview
      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 -N -r1.19 -r1.20
--- openacs-4/packages/acs-core-docs/www/variables.html	29 Jun 2004 15:50:16 -0000	1.19
+++ openacs-4/packages/acs-core-docs/www/variables.html	5 Jul 2004 14:25:00 -0000	1.20
@@ -3,7 +3,7 @@
           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�12.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,
           ...
     ...