Constraint naming standard

By Michael Bryzek

+ +Constraint naming standard

Prev	Chapter 11. Engineering Standards	Next

Constraint naming standard

By Michael Bryzek

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

The Big Picture

Constraint naming standard is important for one reason: The SYS_* name oracle assigns to unnamed constraints is not very understandable. By correctly naming all contraints, we can quickly associate a particular constraint with our data model. This gives us two real advantages: -

We can quickly identify and fix any errors.
We can reliabily modify or drop constraints

We can quickly identify and fix any errors.
We can reliabily modify or drop constraints

Why do we need a naming convention?

-Oracle limits names, +Oracle limits names, in general, to 30 characters, which is hardly enough for a human readable constraint name. -

Abbreviations

We propose the following naming convention for all constraints, with the following abbreviations taken from Oracle Docs at - + http://oradoc.photo.net/ora81/DOC/server.815/a67779/ch4e.htm#8953. Note that we shortened all of the constraint abbrevations to two characters to save room. -

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

Format of constraint name

Constraint type	Abbreviation
references (foreign key)	fk
unique	un
primary key	pk
check	ck
not null	nn

Format of constraint name

In reality, this won't be possible because of the character limitation on names inside oracle. When the name is too long, we will follow these two steps in order: -

Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). -
Truncate the column name until it fits.

Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). +
Truncate the column name until it fits.

If the constraint name is still too long, you should consider rewriting your entire data model :) -

Notes:

If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints
If you are defining a multi column constraint, try to truncate the two column names evenly

Example

Notes:

If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints
If you are defining a multi column constraint, try to truncate the two column names evenly

Example

 create table example_topics (
        topic_id    integer
 		   constraint example_topics_topic_id_pk
@@ -52,7 +52,7 @@
        constraint cne_example_id_one_line_unq unique(example_id, one_line_description)
 );
 
-

Why it's good to name primary keys

Naming primary keys might not have any obvious advantages. However, here's an example where naming the primary key really helps (and this is by no means a rare case! @@ -71,18 +71,18 @@ 3 1 INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI QUE)

-Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace +Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace and know exactly which table oracle is using at each step? -

Naming not null constraints is optional...

People disagree on whether or not we should be naming not null constraints. So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not a requirement.

About Naming the not null constraints

-Though naming "not null" constraints doesn't help immeditately in error +Though naming "not null" constraints doesn't help immeditately in error debugging (e.g. the error will say something like -"Cannot insert null value into column"), we recommend naming not null +"Cannot insert null value into column"), we recommend naming not null constraints to be consistent in our naming of all constraints.

($Id$)

Prev	Home	Next
Release Version Numbering	Up	ACS File Naming and Formatting Standards

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -N -r1.45 -r1.46 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 17 Oct 2010 21:06:07 -0000 1.45 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 11 Dec 2010 23:36:32 -0000 1.46 @@ -1,83 +1,83 @@ - -ACS File Naming and Formatting Standards

Prev	Chapter 12. Engineering Standards	Next

ACS File Naming and Formatting Standards

By Michael Yoon and Aurelius Prochazka

+ +ACS File Naming and Formatting Standards

Prev	Chapter 11. Engineering Standards	Next

ACS File Naming and Formatting Standards

By Michael Yoon and Aurelius Prochazka

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

To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -

File Nomenclature

Usually we organize our files so that they mainly serve one of the following three purposes: -

displaying objects and their properties
manipulating or acting on objects in some way (by creating, editing, linking, etc)
housing procedures, packages, data models and other prerequisite code +
- displaying objects and their properties
- manipulating or acting on objects in some way (by creating, editing, linking, etc)
- housing procedures, packages, data models and other prerequisite code Essentially, we want our files named in a fashion that reflects their purpose.
-Under the page root (and the template root if using the Style package): -
- For naming files that enable a specific action on an object, use this format:
  -object-verb.extension +Under the page root (and the template root if using the Style package): +
  For naming files that enable a specific action on an object, use this format:
  +object-verb.extension
  For example, the page to erase a user's portrait from the database is -/admin/users/portrait-erase.tcl. -
  However, modules typically deal with only one primary type of object - +/admin/users/portrait-erase.tcl. +
  However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages -for the Bookmarks module live in the /bookmarks/ -directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention: +for the Bookmarks module live in the /bookmarks/ +directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention:
  -verb.extension +verb.extension
  -Thus, the page to edit a bookmark is /bookmarks/edit.tcl. -
  For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
  -one.extension +Thus, the page to edit a bookmark is /bookmarks/edit.tcl. +
  For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:
  +one.extension
  For example, the page to view one bookmark is -/bookmarks/one.tcl. Note that no verb is necessary for display-type files. -
  Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
  -object.extension +/bookmarks/one.tcl. Note that no verb is necessary for display-type files. +
  Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:
  +object.extension
  For example, the page to view the properties of an ecommerce product is -/ecommerce/product.tcl. -
  For naming files in a page flow, use the convention:
  foobar.extension (Step 1)
  foobar-2.extension (Step 2)
  ...
  foobar-N.extension (Step N)
  -where foobar is determined by the above +/ecommerce/product.tcl. +
  For naming files in a page flow, use the convention:
  foobar.extension (Step 1)
  foobar-2.extension (Step 2)
  ...
  foobar-N.extension (Step N)
  +where foobar is determined by the above rules.
  Typically, we use a three-step page flow when taking user information: -
  Present a form to the user
  Present a confirmation page to the user
  Perform the database transaction, then redirect
  Put data model files in /www/doc/sql, and name them +
  Present a form to the user
  Present a confirmation page to the user
  Perform the database transaction, then redirect
  Put data model files in /www/doc/sql, and name them for the modules towards which they are used:
  -module.sql +module.sql
  In the Tcl library directory: -
  For files that contain module-specific procedures, use the +
  For files that contain module-specific procedures, use the convention:
  -module-procs.tcl -
  For files that contain procedures that are part of the core ACS, +module-procs.tcl +
- For files that contain procedures that are part of the core ACS, use the convention:
  -ad-description-procs.tcl -

URLs

+ad-description-procs.tcl +

URLs

File names also appear within pages, as linked URLs and -form targets. When they do, always use abstract -URLs (e.g., user-delete instead of -user-delete.tcl), because they enhance maintainability. +form targets. When they do, always use abstract +URLs (e.g., user-delete instead of +user-delete.tcl), because they enhance maintainability.

Similarly, when linking to the index page of a directory, do not -explicitly name the index file (index.tcl, -index.adp, index.html, etc.). Instead, use +explicitly name the index file (index.tcl, +index.adp, index.html, etc.). Instead, use just the directory name, for both relative links -(subdir/) and absolute links -(/top-level-dir/). If linking to the directory in which -the page is located, use the empty string (""), which +(subdir/) and absolute links +(/top-level-dir/). If linking to the directory in which +the page is located, use the empty string (""), which browsers will resolve correctly. -

File Headers and Page Input

Include the appropriate standard header in all scripts. The first line should be a comment specifying the file path relative to the ACS root directory. e.g. -

+
# /www/index.tcl -
+

or -

+
# /tcl/module-defs.tcl -
+

For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g.

@@ -95,7 +95,7 @@
 This can be at the top or bottom of the file.
 
Using ad_page_contract

 For non-library Tcl files (those not in the private Tcl directory),
-use ad_page_contract
+use ad_page_contract
 after the file path comment (this supersedes set_the_usual_form_variables and
 ad_return_complaint).  Here is an example of using
 ad_page_contract, which serves both documentation and page input
@@ -119,32 +119,32 @@
     {persistent_cookie_p f}
 }

-Salient features of ad_page_contract: -

A mandatory documentation string is the first argument. This has -the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.
The second argument specifies the page +Salient features of ad_page_contract: +
- A mandatory documentation string is the first argument. This has +the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.
- The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags separated by commas (,), -e.g. foo:integer,multiple,trim. In particular, multiple and -array are the flags that correspond to the old -ad_page_variables flags.
- There are new flags: trim, notnull and -optional. They do what you'd expect; values will not be +e.g. foo:integer,multiple,trim. In particular, multiple and +array are the flags that correspond to the old +ad_page_variables flags.
- There are new flags: trim, notnull and +optional. They do what you'd expect; values will not be trimmed, unless you mark them for it; empty strings are valid input, unless you specify notnull; and a specified variable will be considered required, -unless you declare it optional.
- ad_page_contract can do validation for you: the flags integer -and sql_identifier will make sure that the values -supplied are integers/sql_identifiers. The integer flag +unless you declare it optional.
- ad_page_contract can do validation for you: the flags integer +and sql_identifier will make sure that the values +supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. Note that unless you specify -notnull, both will accept the empty string. -
- Note that ad_page_contract does not generate +notnull, both will accept the empty string. +
- Note that ad_page_contract does not generate QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete.
Using ad_library
-For shared Tcl library files, use ad_library after +For shared Tcl library files, use ad_library after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like -ad_page_contract. Don't forget to put the @cvs-id in +ad_page_contract. Don't forget to put the @cvs-id in there. Here is an example of using ad_library:
```
 # tcl/wp-defs.tcl
@@ -165,56 +165,56 @@
 -- author
 -- created
 --
--- $Id$
+-- $Id$
 
```
-Of course, replace "--" with the comment delimiter +Of course, replace "--" with the comment delimiter appropriate for the language in which you are programming. -

Page Construction

Construct the page as one Tcl variable (name it -page_content), and then send it back to the browser with -one call to doc_return, which will call +page_content), and then send it back to the browser with +one call to doc_return, which will call db_release_unused_handles prior to executing ns_return, effectively combining the two operations.

For example:

-set page_content "[ad_header "Page Title"]
+set page_content "[ad_header "Page Title"]
 
 <h2>Page Title</h2>
 
 <hr>
 
 <ul>
-"
+"
 
 db_foreach get_row_info {
     select row_information 
     from bar
 } {
-    append page_content "<li>row_information\n"
+    append page_content "<li>row_information\n"
 }
 
-append page_content "</ul>
+append page_content "</ul>
 
-[ad_footer]"
+[ad_footer]"
 
 doc_return 200 text/html $page_content

-The old convention was to call ReturnHeaders and -then ns_write for each distinct chunk of the page. This +The old convention was to call ReturnHeaders and +then ns_write for each distinct chunk of the page. This approach has the disadvantage of tying up a scarce and valuable resource (namely, a database handle) for an unpredictable amount of time while sending packets back to the browser, and so it should be avoided in most cases. (On the other hand, for a page that requires an expensive database query, it's better to call -ad_return_top_of_page +ad_return_top_of_page first, so that the user is not left to stare at an empty page while the query is running.)

Local procedures (i.e., procedures defined and used only within one -page) should be prefixed with "module_" and +page) should be prefixed with "module_" and should be used rarely, only when they are exceedingly useful.

All files that prepare HTML to display should end with [ad_footer] or @@ -225,7 +225,7 @@ edit ad_header (which quite possibly can start a <table>) and ad_footer (which may need to end the table started in ad_footer) to customize the look and feel of the entire site. -

Tcl Library Files

Further standards for Tcl library files are under discussion; we plan to include naming conventions for procs.

($Id$)

Prev	Home	Next
Constraint naming standard	Up	PL/SQL Standards

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 17 Oct 2010 21:06:07 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,5 +1,5 @@ - -PL/SQL Standards

Prev	Chapter 12. Engineering Standards	Next

PL/SQL Standards

+ +PL/SQL Standards

Prev	Chapter 11. Engineering Standards	Next

PL/SQL Standards

By Richard Li and Yon Feldman

OpenACS docs are written by the named authors, and may be edited @@ -11,25 +11,25 @@ our product will be useful long after the current people building and maintaining it are around. Following are some standards and guidelines that will help us achieve this goal: -

General

+
General
1. All PL/SQL code must be well documented. We must write code that is maintainable by others, this is especially true in our case because we are building an open source toolkit than anyone can download and browse the source code. So document like you are - trying to impress your "Introduction to Programming" professor or + trying to impress your "Introduction to Programming" professor or TA. -
2. +
3. It is important to be consistent throughout an application as much as is possible given the nature of team development. This means carrying style and other conventions suchs as naming within an application, not just within one file. -
Code
1. +
Code
1. Encapsulation of related fuctionality is key to maintainability and upgradeability of our software. Try to bundle your code into - packages + packages whenever possible. This will make upgrading, bug fixing, and customizing, among other things, a possibility. -
2. +
3. When creating functions or procedures use the following template, it demonstrates most of the guidelines set forth in this document that correspond to functions and procedures: @@ -53,32 +53,32 @@ / show errors -
4. - Always use create or replace procedure|function - <proc_or_func_name>. It makes reloading packages much +
5. + Always use create or replace procedure|function + <proc_or_func_name>. It makes reloading packages much easier and painless to someone who is upgrading or fixing a bug. -
6. - Always qualify end statements, i.e., the - end statement for a package should be end - <package_name>;, not just end;; same +
7. + Always qualify end statements, i.e., the + end statement for a package should be end + <package_name>;, not just end;; same goes for procedures, functions, package bodies, and triggers. -
8. - Always use the "show errors" SQL*Plus command after each PL/SQL +
9. + Always use the "show errors" SQL*Plus command after each PL/SQL block. It will help you debug when there are compilation errors in your PL/SQL code. -
10. +
11. Name parameters as simply as possible, i.e., use the column name if the parameter corresponds to a table column. We're deprecating the v_* and *_in syntax in favor of named parameters notation:
```
 
-      
+      
         acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.)
-      
+      
         instead of
-      
+      
         acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.)
-      
+      
      
 
```
  To achieve this we must fully qualify arguements passed into @@ -107,23 +107,23 @@ / show errors -
12. - Explicitly designate each parameter as "in," "out," or "inout." -
13. +
14. + Explicitly designate each parameter as "in," "out," or "inout." +
15. Each parameter should be on its own line, with a tab after the parameter name, then in/out/inout, then a space, and finally the datatype. -
16. +
17. Use %TYPE and %ROWTYPE whenever possible. -
18. - Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype +
19. + Use 't' and 'f' for booleans, not the PL/SQL "boolean" datatype because it can't be used in SQL queries. -
20. - All new functions (e.g., acs_object.new, - party.new, etc.) should optionally accept an ID: +
21. + All new functions (e.g., acs_object.new, + party.new, etc.) should optionally accept an ID:
```
 
-      
+      
         create or replace package acs_object
         as
             function new (
@@ -134,22 +134,22 @@
                 creation_ip     in acs_objects.creation_ip%TYPE default null,
                 context_id      in acs_objects.context_id%TYPE default null
            ) return acs_objects.object_id%TYPE;
-     
+     
     
 
```
  - takes the optional argument object_id. Do this to + takes the optional argument object_id. Do this to allow people to use the same API call when they are doing double click protection, that is, tehy have already gotten an - object_id and now they want to create the object with - that object_id. -
Style
+ object_id and now they want to create the object with + that object_id. +

Style

Some general style guidelines to follow for the purpose of consistency across applications. -

+
1. Standard indentation is 4 spaces. Our PL/SQL code is not only viewable in the SQL files but also through our SQL and PL/SQL browsers. This means that we should try to make it as consistent as possible to all source code readers. -
2. +
3. Lowercase everything, with the exception of %TYPE and %ROWTYPE.
($Id$)

Prev	Home	Next
ACS File Naming and Formatting Standards	Up	Variables

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -N -r1.48 -r1.49 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 17 Oct 2010 21:06:07 -0000 1.48 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 11 Dec 2010 23:36:32 -0000 1.49 @@ -1,14 +1,14 @@ - -Release Version Numbering

Prev	Chapter 12. Engineering Standards	Next

Release Version Numbering

($Id$)

By Ron Henderson, Revised by Joel Aufrecht

+ +Release Version Numbering

Prev	Chapter 11. Engineering Standards	Next

Release Version Numbering

($Id$)

By Ron Henderson, Revised by Joel Aufrecht

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

OpenACS version numbers help identify at a high-level what is in a particular release and what has changed since the last release. -

A "version number" is really just a string of the form: -

major.minor.dot[ milestone ]

A major number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.
A minor change represents the addition of new functionality or changed UI.
A dot holds only bug fixes and security patches. Dot releases are always recommended and safe. -
A milestone marker indicates the state of the release:
- d, for development, means the release is in active development and is not in its intended released form.
- a, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.
- b, for beta, means most severe bugs are fixed and end users can start trying the release.
- Release Candidate builds (rc) are believed to meet all of the criteria for release and can be installed on test instances of production systems.
- Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.) +
  A "version number" is really just a string of the form: +
  major.minor.dot[ milestone ]
  - A major number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.
  - A minor change represents the addition of new functionality or changed UI.
  - A dot holds only bug fixes and security patches. Dot releases are always recommended and safe. +
  - A milestone marker indicates the state of the release:
    d, for development, means the release is in active development and is not in its intended released form.
    a, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.
    b, for beta, means most severe bugs are fixed and end users can start trying the release.
    Release Candidate builds (rc) are believed to meet all of the criteria for release and can be installed on test instances of production systems.
    Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.)
    Milestone markers are numbered: d1, d2, ..., a1, b1, rc1, etc.
  A complete sequence of milestones between two releases:
```
5.0.0
 5.0.0rc2
 5.0.0rc1
@@ -22,7 +22,7 @@
 Version numbers are also recorded in the CVS repository so that the
 code tree can be restored to the exact state it was in for a
 particular release.  To translate between a distribution tar file
-(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire release history of the toolkit is recorded in the tags for the top-level readme.txt file:
+(acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire release history of the toolkit is recorded in the tags for the top-level readme.txt file:
 
 > cvs log readme.txt
 RCS file: /usr/local/cvsroot/acs/readme.txt,v
@@ -58,10 +58,10 @@
 

 In the future, OpenACS packages should follow this same
 convention on version numbers.
-
Transition Rules
So what distinguishes an alpha release from a beta
+
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
Package Maturity

+the next.  These rules are fine-tuned with each release; an example is 5.0.0 Milestones and Milestone Criteria
Package Maturity

       Each package has a maturity level. Maturity level is recorded in the .info file for each major-minor release of OpenACS,
       and is set to the appropriate value for that release of the package.
     
@@ -71,22 +71,24 @@
         <maturity>1</maturity>
         <callbacks>
             ...
-    

-        Level -1: Incompatible. This package is not supported for this platform and should not be expected to work.
-      

-        Level 0: New Submission. This is the default for packages that do not have maturity explicitly set, 
+    
```
  - + Level -1: Incompatible. This package is not supported for this platform and should not be expected to work. +
  - + Level 0: New Submission. This is the default for packages that do not have maturity explicitly set, and for new contributions. The only criterion for level 0 is that at least one person asserts that it works on a given platform. -
  - - Level 1: Immature. Has no open priority 1 or priority 2 bugs. Has been installed by at least +
  - + Level 1: Immature. Has no open priority 1 or priority 2 bugs. Has been installed by at least 10? different people, including 1 core developer. Has been available in a stable release for at least 1 month. Has API documentation. -
  - - Level 2: Mature. Same as Level 1, plus has install guide and user documentation; +
  - + Level 2: Mature. Same as Level 1, plus has install guide and user documentation; no serious deviations from general coding practices; no namespace conflicts with existing level 2 packages. -
  - - Level 3: Mature and Standard. Same as level 2, plus meets published coding standards; +
  - + Level 3: Mature and Standard. Same as level 2, plus meets published coding standards; is fully internationalized; available on both supported databases. -
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 -

Prev	Home	Next
OpenACS Style Guide	Up	Constraint naming standard

docs@openacs.org

View comments on this page at openacs.org +

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.

Upgrade scripts should be named /packages/myfirstpackage/sql/postgresql/upgrade/upgrade-OLDVERSION-NEWVERSION.sql
If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in /packages/myfirstpackage/myfirstpackage.info. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. +
If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use upgrade-2.0.1d3-2.0.1d4.sql.
Database upgrades should be confined to development releases, not alpha or beta releases.
+ Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.
Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.
The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in +acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use upgrade-5.1.0d1-5.1.0d2.sql +

Prev	Home	Next
+ CVS Guidelines +	Up	Constraint naming standard

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -N -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 17 Oct 2010 21:06:07 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 11 Dec 2010 23:36:32 -0000 1.30 @@ -1,2 +1,4 @@ - -Chapter 12. Engineering Standards

Prev	Part III. For OpenACS Package Developers	Next

Chapter 12. Engineering Standards

Table of Contents

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

Section missing

Prev	Home	Next
Using Form Builder: building html forms dynamically	Up	OpenACS Style Guide

docs@openacs.org

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

Prev	Part III. For OpenACS Package Developers	Next

Chapter 11. Engineering Standards

Table of Contents

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

Prev	Home	Next
Using Form Builder: building html forms dynamically	Up	OpenACS Style Guide

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -N -r1.37 -r1.38 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 17 Oct 2010 21:06:07 -0000 1.37 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 11 Dec 2010 23:36:32 -0000 1.38 @@ -1,5 +1,5 @@ - -External Authentication Requirements

Prev	Chapter 15. Kernel Documentation	Next

External Authentication Requirements

Vision

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

Prev	Chapter 14. Kernel Documentation	Next

External Authentication Requirements

Vision

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

Besides, administrators have better things to do than create @@ -8,47 +8,47 @@ log on to OpenACS, an account will automatically be created for them here.

Finally, security is increased with fewer passwords, since users generally can't remember all those passwords, so they tend to -keep them all the same and never change them.

Design Goals

Transparent: Users don't have to do anything special to +keep them all the same and never change them.

Design Goals

Transparent: Users don't have to do anything special to get an account on the local OpenACS system, if they already have an - account on the external authentication server.
Fall-back: Users who don't have an account on the + account on the external authentication server.
Fall-back: Users who don't have an account on the external authentication server are still allowed to create a local account on OpenACS. This could be for external students who should have access to .LRN, but not to the rest of the university's - resources.
Authentication Client Only: We want OpenACS to be able to + resources.
Authentication Client Only: We want OpenACS to be able to authenticate by asking some remote authority to verify the user's username/password combination. The goal is explicitly not (at this point) to have OpenACS act as an authentication server for other systems, although this could be easily added later. The goal is also not to devise an infrastructure for letting OpenACS access resources in various other systems on the user's behalf, such as IMAP, iCalendar, SMB file servers, etc., although this is - definitely an interesting use-case.
Easy configuration: We would like people to be able to + definitely an interesting use-case.
Easy configuration: We would like people to be able to configure this without having to write code. In particular, we want to build drivers that know how to talk with LDAP, RADIUS, PAM, etc., and which won't have to be locally modified. Only configuration and policies should change, code should - not.
Usability: The solution must be easy to use for end users + not.
Usability: The solution must be easy to use for end users and administrators alike. There's frequently a positive feedback effect between usability and security, because when authentication schemes have poor usability, users will think up ways to circumvent - them.
Open and modular: The design should be on the one hand + them.
Open and modular: The design should be on the one hand open to add other authentification mechanisms when needed and on the other hand very modular to enable a start with minimal requirements (driver implementations) as soon as possible.

The problem can be split into several logically separate -parts. Each has a section below.

Terminology

Authority: The name of an authority trusted to authenticate - users.
Authentication Driver: An implementation of the +parts. Each has a section below.

Terminology

Authority: The name of an authority trusted to authenticate + users.
Authentication Driver: An implementation of the authentication service contract, which talks to an authentication of a certain type, e.g. PAM, RADIUS, LDAP, or Active - Directory.
Authentication API: The API through which login pages and + Directory.
Authentication API: The API through which login pages and applications talk to the authentication service. There's one and only one implementation of the authentication API, namly the one - included in OpenACS Core.
Authentication Driver API: The service contract which - authentication drivers implement.

Conceptual Pictures

Authentication:

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

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

Login

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

Users will log in using a username, a authority, and a + included in OpenACS Core.

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

Conceptual Pictures

Authentication:

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

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

Login

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

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

Each user in OpenACS will belong to exactly one authority, which -can either be the "local" OpenACS users table, in which case the +can either be the "local" OpenACS users table, in which case the password column is used, or it can be some external authority, which will be communicated with using some protocol, as implemented by an authentication driver.

Username will be separate from email address. It can be an @@ -71,11 +71,11 @@ [Forgot my password] [New user registration]

If there's only one active authority, we don't display the -authority drop-down element at all.

Configuration

Feature	Status	Description
Configuration
EXT-AUTH-07	A	Admin pages to control Ext-Auth parameters

The site-wide systems administrator can configure the -authentication process from a page linked under /acs-admin.

Authorities - ordered list of authorities defined
Account Registration Allowed: Yes/No. Account - registration can be disabled altogether.
Registration authority - the authority in which accounts should +authority drop-down element at all.

Configuration

Feature	Status	Description
Configuration
EXT-AUTH-07	A	Admin pages to control Ext-Auth parameters

The site-wide systems administrator can configure the +authentication process from a page linked under /acs-admin.

Authorities - ordered list of authorities defined
Account Registration Allowed: Yes/No. Account + registration can be disabled altogether.
Registration authority - the authority in which accounts should be created, using the relevant driver, if account registration is - allowed.
Username is email? - instead of asking for username, + allowed.

Username is email? - instead of asking for username, we'll ask for email. And we'll store the value in both columns, username and email. This is a setting that spans all authorities, and is primarily meant for backwards compatibility with the old OpenACS @@ -84,42 +84,42 @@ other drivers call external functions. The possible functions for each authority are split into several drivers for convenience. One driver handles authentication, one account creation, and one - changing passwords.

Feature	Status	Description
create service contract
EXT-AUTH-16	A	Create service contract for Authentication
EXT-AUTH-17	A	Create service contract for Acct. Creation
EXT-AUTH-29	A	Create service contract for Passwd Management

Feature	Status	Description

EXT-AUTH-18	A	Authority configuration data model

Each authority is defined like this:

Authority pretty-name, e.g. "URZ"

Authentication Driver, e.g. "RADIUS". In practice, this + changing passwords.

Feature	Status	Description
create service contract
EXT-AUTH-16	A	Create service contract for Authentication
EXT-AUTH-17	A	Create service contract for Acct. Creation
EXT-AUTH-29	A	Create service contract for Passwd Management

Feature	Status	Description

EXT-AUTH-18	A	Authority configuration data model

Each authority is defined like this:

Authority pretty-name, e.g. "URZ"
Authentication Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract - implementation.
Authentication Driver configuration settings, e.g. host + implementation.
Authentication Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is per authority, not per driver, i.e., you can have multiple authorities with the same driver but different configuration - options.
AuthenticationAllowed - true/false, so you can disable + options.
AuthenticationAllowed - true/false, so you can disable login through some authority without having to delete the authority, and - hence also all the users who belong to that authority.
ForgottenPasswordUrl - a URL to redirect to instead of + hence also all the users who belong to that authority.
ForgottenPasswordUrl - a URL to redirect to instead of trying to use the authentication driver's password management - features.
ChangePasswordUrl - a URL to redirect to instead of + features.
ChangePasswordUrl - a URL to redirect to instead of trying to use the authentication driver's password management - features.
Account Creation Driver, e.g. "RADIUS". In practice, this + features.
Account Creation Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract implementation. The reason we have separate drivers for authentication and account creation is that organizations are likely to have a home-grown - account registration process.
Account Creation Driver configuration settings, e.g. host + account registration process.
Account Creation Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is per authority, not per driver, i.e., you can have multiple authorities with the same driver but different configuration - options.
RegistrationUrl - instead of registering using OpenACS, - redirect to a certain URL site for account registration.
RegistrationAllowed - true/false, so you can disable - registration using this account.
Sort order: Preference order of - authorities.
HelpContactText: Text or HTML to be displayed + options.
RegistrationUrl - instead of registering using OpenACS, + redirect to a certain URL site for account registration.
RegistrationAllowed - true/false, so you can disable + registration using this account.
Sort order: Preference order of + authorities.
HelpContactText: Text or HTML to be displayed when user has trouble authenticating with the authority. Should include contact information such as a phone number or email.

Each authority driver will have a set of configuration options dependent on the driver, such as host, port, etc. We will need to find a mechanism for the driver to tell us which configuration options are available, a way to set these, and a way for the driver to access these settings.

OpenACS will come pre-configured with one authority, which is -the "local" authority, meaning we'll authenticate as normal using the +the "local" authority, meaning we'll authenticate as normal using the local users table. This will, just like any other authority, be -implemetned using a service contract.

Synchronizing -and Linking Users

Feature	Status	Description
Synchronizing and linking users
EXT-AUTH-28	A	Create service contract for Batch Sync.
EXT-AUTH-38	A	Batch User Synchronization API
EXT-AUTH-38	A	IMS Synchronization driver
EXT-AUTH-08	A	Automation of batch Synchronization
EXT-AUTH-15	B	On-demand syncronization

Regardless of the login method, the user needs to have a row +implemetned using a service contract.

Synchronizing +and Linking Users

Feature	Status	Description
Synchronizing and linking users
EXT-AUTH-28	A	Create service contract for Batch Sync.
EXT-AUTH-38	A	Batch User Synchronization API
EXT-AUTH-38	A	IMS Synchronization driver
EXT-AUTH-08	A	Automation of batch Synchronization
EXT-AUTH-15	B	On-demand syncronization

Regardless of the login method, the user needs to have a row in the OpenACS users table. This can happen through a batch job, in -real-time, or both in combination. We use the IMS Enterprise 1.1 specification.

Batch job means that we do a synchronization (import new +real-time, or both in combination. We use the IMS Enterprise 1.1 specification.

Batch job means that we do a synchronization (import new users, modify changed, purge deleted) on a regular interval, e.g. every night. You can also decide to have a monthly full synchronization, plus daily incremental ones. That's up to you. The @@ -130,23 +130,23 @@ be remedied by using the real-time solution. The batch job will also require error logging and an admin interface to view logs.

If an email already belongs to some other user, we log it as an error.

A user will always belong to exactly one authority, which can be -either the "local" authority or some other. Thus, the OpenACS user's -table will have to be augmented with the following columns:

Authority. Reference to the site-wide authorities list. The - authority which can authenticate this user.
Authority-specific username.

Real-time means that the first time the user logs into +either the "local" authority or some other. Thus, the OpenACS user's +table will have to be augmented with the following columns:

Authority. Reference to the site-wide authorities list. The + authority which can authenticate this user.
Authority-specific username.

Real-time means that the first time the user logs into OpenACS, we'll query the authority that authenticated him for information about this user. That authentication authority will then give us at least first names, last name and email. The pros and cons are the opposite of batch jobs. Using both in combination -is ideal.

Note: One solution to the "two users from different authorities -have the same email" problem above would be to allow users to +is ideal.

Note: One solution to the "two users from different authorities +have the same email" problem above would be to allow users to belong to multiple authorities. Then we would notice that the email already exists, ask the user if he thinks he's the same person, and if so, ask him to prove so by authenticating using the other authority. Thus he'll have just authenticated in two different authorities, and we can record that this is the same person. We'd still have a problem if there was an email conflict between two accounts on the same authority. Hm. I don't think it's worth spending too much -time trying to solve this problem through software.

Feature	Status	Description
EXT-AUTH-31
EXT-AUTH-31	A	Upgrade user data model for ext-auth

After having authenticated using the relevant authority driver, +time trying to solve this problem through software.

Feature	Status	Description
EXT-AUTH-31
EXT-AUTH-31	A	Upgrade user data model for ext-auth

After having authenticated using the relevant authority driver, we'll look for the username/authority pair in the users table.

If we don't find any, that means that we're either not doing batch synchronizing, or that the user has been added since the last sync. In that case, we'll try to do a real-time synchronization, if @@ -155,60 +155,60 @@ create a row in the local users table using that information.

If that doesn't work, we'll tell the user that their account isn't yet available, and the driver will supply a message for us, -which could say "The account should be available tomorrow. If not, -contact X."

Account -Registration

If a user doesn't have an account, the site-wide +which could say "The account should be available tomorrow. If not, +contact X."

Account +Registration

If a user doesn't have an account, the site-wide configuration can allow the user to register for one, as defined in the configuration discussed above. This section is about normal account registration through a authority driver.

The account creation service contract implementation will -need to tell us which information to ask the user for:

Required Fields: A list of fields which are - required.
Optional Fields: A list of fields which are - optional.

The fields to choose from are these:

Username
First names
Last name
Email
URL
Password
Secret question
Secret answer

It should return the following:

Creation status (OK, Try-Again, Fail)
Creation message: What went wrong, or a welcome - message.
Account status: Is the account ready for use?
User information: first_names, last_name, email, url, +need to tell us which information to ask the user for:
- Required Fields: A list of fields which are + required.
- Optional Fields: A list of fields which are + optional.
The fields to choose from are these:
- Username
- First names
- Last name
- Email
- URL
- Password
- Secret question
- Secret answer
It should return the following:
- Creation status (OK, Try-Again, Fail)
- Creation message: What went wrong, or a welcome + message.
- Account status: Is the account ready for use?
- User information: first_names, last_name, email, url, password, password_hash, secret_question, secret_answer. The driver only needs to return the columns which were changed or added - through the registration process. Typically, only the "local" + through the registration process. Typically, only the "local" driver will return password and secret question/answer.
After creating the remote account, a local account is created with the information gathered through the form/returned by the driver.
By default, a local account creation implementation is provided, which will create a new OpenACS user, and, in addition to the default local account creation above, also store the password -in hashed form.

Password -Management

Password management is about changing password, retrieving +in hashed form.

Password +Management

Password management is about changing password, retrieving password, and resetting password.

It's up to the authority driver implementation to decide whether to support any or all of these features, and to say so using the CanXXX methods (see driver API below).

Additionally, the authority can be configured with a URL to redirect to in the case of forgotten passwords, or when the user -desires to change password.

Login Pages Over -HTTPS

Feature	Status	Description
EXT-AUTH-20
EXT-AUTH-20	A	Login over HTTPS

Login Pages Over +HTTPS

Feature	Status	Description
EXT-AUTH-20
EXT-AUTH-20	A	Login over HTTPS

Login pages must be able to be sent over a secure connection (https), so your password won't get sent over the wire in cleartext, while leaving the rest of the site non-secure (http). I believe that this requires some (minor) changes to the current -session handling code.

Email -Verification

Email verification needs to be handled both at registration +session handling code.

Email +Verification

Email verification needs to be handled both at registration and at login.

In both cases, it'll be handled by the driver sending automatically sending the email containing a link for the user to verify his account. Then the driver will return an account status -of "closed,temporary", and a message that says "Check your inbox -and click the link in the email".

OpenACS will have a page which receives the email +of "closed,temporary", and a message that says "Check your inbox +and click the link in the email".

OpenACS will have a page which receives the email verification, for use by local accounts. Other authorities will have to implement their own page, most likely on the authority's -own server.

Other Items

There are a number of items which touch on external +own server.

Other Items

There are a number of items which touch on external authentication and session management. And even though they're not directly linked to external authentication, I would recommend that we handle a number of them, either because they're important for security, or because it makes sense to fix them while we're messing -with this part of the codebase anyway.

Recommended: -Untrusted Logins and Login Levels

Feature	Status	Description
EXT-AUTH-33
EXT-AUTH-33	A	Untrusted Logins

I like the idea of having multiple login levels:

Not logged in

Untrusted login: We'll show you un-sensitive personal +with this part of the codebase anyway.

Recommended: +Untrusted Logins and Login Levels

Feature	Status	Description
EXT-AUTH-33
EXT-AUTH-33	A	Untrusted Logins

I like the idea of having multiple login levels:

Not logged in
Untrusted login: We'll show you un-sensitive personal content, but won't let you modify anything or see personal data. A normal login becomes untrusted after a certain amount of time, and the user will have to re-enter his/her password in order to gain access to personal data. Untrusted login never expires, unless explicitly done so through either changing password or clicking a - special "expire all logins" link.
Normal login: The user is logged, and has type his + special "expire all logins" link.
Normal login: The user is logged, and has type his password sufficiently recently that we trust the login. All normal operations are allowed. Will degrade to untrusted login after a - specified amount of time.
Secure login: The user is logged in over a secure + specified amount of time.
Secure login: The user is logged in over a secure connection (HTTPS), potentially even using a special secure password. This would be for sensitive actions, such as credit card transactions.

There are two advantages to this. First, when people's login @@ -224,19 +224,19 @@ example, we could let you browse publically available forums, and only when you want to post do you need to log in. This makes it even more feasible to have a more secure login expiration -setting.

By default, auth::require_login would +setting.

By default, auth::require_login would bounce to the login page if the user is only logged in at the untrusted level. Only if you explicitly say -auth::require_login -untrusted will we give you +auth::require_login -untrusted will we give you the user_id of a user who's only logged in in untrusted -mode.

Similarly, ad_conn user_id will continue +mode.

Similarly, ad_conn user_id will continue to return 0 (not logged in) when the user is only logged in -untrusted, and we'll supply another variable, ad_conn -untrusted_user_id, which wlll be set to the user_id for +untrusted, and we'll supply another variable, ad_conn +untrusted_user_id, which wlll be set to the user_id for all login levels.

This should ensure that we get full access to the new feature, while leaving all current code just as secure as it was -before.

Recommended: -Make Non-Persistent Login Work

Feature	Status	Description
EXT-AUTH-34
EXT-AUTH-34	A	Expire Logins

Currently, OpenACS is unusable in practice without persistent +before.

Recommended: +Make Non-Persistent Login Work

Feature	Status	Description
EXT-AUTH-34
EXT-AUTH-34	A	Expire Logins

Currently, OpenACS is unusable in practice without persistent login. The login will expire after just a few minutes of inactivity, and you'll get bounced to the login page where you have to enter both email and password again. Unacceptable in @@ -247,15 +247,15 @@ login expire after a period of inactivity, but the amount of time should be configurable and default to something reasonable like an hour or so.

This will require looking into and changing the design of the -current session handling code.

Recommended: -Single-Sign-On

Feature	Status	Description
EXT-AUTH-23
EXT-AUTH-23		Single sign-on

Instead of redirecting to the login page, auth::require_login +current session handling code.

Recommended: +Single-Sign-On

Feature	Status	Description
EXT-AUTH-23
EXT-AUTH-23		Single sign-on

Instead of redirecting to the login page, auth::require_login can redirect to an authentication server, which can redirect back to a page that logs the user in. This should be very easy to implement.

Alternatively, if you want to combine this with fallback to OpenACS accounts, we would instead present the normal login screen, -but put a button which says "Login using X", where X is the -redirection-based external authority.

Recommended: -Expire All Logins

Feature	Status	Description
EXT-AUTH-22
EXT-AUTH-22	B	rewrite cookie handling

Currently, if you've ever left a permanent login cookie on +but put a button which says "Login using X", where X is the +redirection-based external authority.

Recommended: +Expire All Logins

Feature	Status	Description
EXT-AUTH-22
EXT-AUTH-22	B	rewrite cookie handling

Currently, if you've ever left a permanent login cookie on someone elses machine, that person will be forever logged in until he/she explicitly logs out. You can change your password, you can do anything you want, but unless a logout is requested from that @@ -270,32 +270,32 @@ void. Of course, we don't want to incur a DB hit on every request, so we'll need to cache the secret token, or only check it when refreshing the session cookie, which, I believe, normally happens -every 10 minutes or so.

Recommended: -Email account owner on password change

Feature	Status	Description
EXT-AUTH-24
EXT-AUTH-24	A	Email on password change

As an additional security measure, we should email the +every 10 minutes or so.

Recommended: +Email account owner on password change

Feature	Status	Description
EXT-AUTH-24
EXT-AUTH-24	A	Email on password change

As an additional security measure, we should email the account's email address whenever the password is changed, so that -he/she is at least alerted to the fact.

Optional: -Password policy

Feature	Status	Description
EXT-AUTH-25
EXT-AUTH-25	A	Implement password policy

Again, to increase security, we should add password policies, +he/she is at least alerted to the fact.

Optional: +Password policy

Feature	Status	Description
EXT-AUTH-25
EXT-AUTH-25	A	Implement password policy

Again, to increase security, we should add password policies, such as passwords needing to be changed after a certain number of days, change on next login (after a new random password has been generated), or requiring that the password satisfies certain complexity rules, i.e. both upper and lowercase characters, numbers, special chars, etc.

It would good to extend the current maximum password length -from 10 to at least 32 characters.

Optional: -Login Without Explicit Authority

Feature	Status	Description
EXT-AUTH-26
EXT-AUTH-26	B	Login without explicit domain

In order to make it easier for people, we've been toying with -the idea of a functionality like this:

If the user enters "foobar@ix.urz.uni-heidelberg.de", it - is translated to mean username = "foobar", authority = - "ix.urz.uni-heidelberg.de".
If the user enters "foobar", it's recognized to not +from 10 to at least 32 characters.

Optional: +Login Without Explicit Authority

Feature	Status	Description
EXT-AUTH-26
EXT-AUTH-26	B	Login without explicit domain

In order to make it easier for people, we've been toying with +the idea of a functionality like this:

If the user enters "foobar@ix.urz.uni-heidelberg.de", it + is translated to mean username = "foobar", authority = + "ix.urz.uni-heidelberg.de".
If the user enters "foobar", it's recognized to not include any authority, and the default authority of - "ix.urz.uni-heidelberg.de" is used.
If the user enters "foo@bar.com", it's recognized as not + "ix.urz.uni-heidelberg.de" is used.
If the user enters "foo@bar.com", it's recognized as not belonging to any known authority, and as such, it's translated to mean - username = "foo@bar.com", authority = "local".

If this is deemed desirable, a way to implement this would be -through these settings:

Split: A regexp which will split the user's entry into - username and authority parts. For example "^([^@]+)(@[^@]+)?$". An + username = "foo@bar.com", authority = "local".

If this is deemed desirable, a way to implement this would be +through these settings:

Split: A regexp which will split the user's entry into + username and authority parts. For example "^([^@]+)(@[^@]+)?$". An easier to use but less flexible method would be that you simply - specify a certain character to split by, such as "@" or "\". If the + specify a certain character to split by, such as "@" or "\". If the regexp doesn't match, or in the latter case, if there's more than one occurrence of the specified character sequence, the split will - fail, signaling that the user's entry was not valid.
Default authority: The default authority will be the first one + fail, signaling that the user's entry was not valid.
Default authority: The default authority will be the first one in the sort order.

The relevant code in user-login.tcl would look like this:

 if { ![auth::split_username -username_var username -authority_var authority] } {
@@ -305,7 +305,7 @@
 
 # username will now contain username
 # authority will now contain authority
-

Optional: Who's Online

Feature	Status	Description
EXT-AUTH-27
EXT-AUTH-27	B	Who's online list

While we're touching the session handling code, anyway, it +

Optional: Who's Online

Feature	Status	Description
EXT-AUTH-27
EXT-AUTH-27	B	Who's online list

While we're touching the session handling code, anyway, it would be nice to add a feature to show who's currently online, a nice real-time collaboration feature frequently requested by members of the community. This is particularly interesting when @@ -314,18 +314,18 @@ which authenticated users have requested pags on the site in the last x minutes (typically about 5), and thus are considered to be currently online. There's nothing more to it. This lets us display -a list of "active users" somewhere on the site, and make their name +a list of "active users" somewhere on the site, and make their name a link to a real-time chat service like Jabber.

We've already made the changes necessary to security-procs.tcl to do this on an earlier project, but haven't -quite finished the work and put it back into the tree.

Optional: -Subsite-level configuration

Feature	Status	Description
EXT-AUTH-28
EXT-AUTH-28		implement subsite-level config

If we want to, we could let subsite administrators configure +quite finished the work and put it back into the tree.

Optional: +Subsite-level configuration

Feature	Status	Description
EXT-AUTH-28
EXT-AUTH-28		implement subsite-level config

If we want to, we could let subsite administrators configure the login process for that particular subsite. This would probably only entail letting the subsite admin leave out certain authorities defined site-wide, and change the sort order.

I think we should leave this out until we have a use case for -it, someone who'd need it.

Future: -Making the Authentication API itself a service contract

Feature	Status	Description
EXT-AUTH-32
EXT-AUTH-32	A	Parameters for Service Contract Implementation
EXT-AUTH-35	A	Make the Authentication API a service contract

For completely free-form authentication logic and mechanisms, +it, someone who'd need it.

Future: +Making the Authentication API itself a service contract

Feature	Status	Description
EXT-AUTH-32
EXT-AUTH-32	A	Parameters for Service Contract Implementation
EXT-AUTH-35	A	Make the Authentication API a service contract

For completely free-form authentication logic and mechanisms, something like Andrew Grumet's -Pluggable +Pluggable Authentication for OACS Draft is interesting. He's proposing a scheme where the entire user interaction is encapsulated in, and left entirely to, a service contract. This @@ -334,10 +334,10 @@ people are going to want to use a username/password-based scheme, and having easy configuration through a web UI is more important than total flexibility at this point.

Besides, we can always do this in the future, by letting the -public Authentication API (auth::require_login -and auth::authenticate) be implemented through a -service contract.

Future: -Authenticating against multiple servers simultaneously

Feature	Status	Description
EXT-AUTH-36
EXT-AUTH-36	A	Authenticate against multiple servers

Both OKI and OpenACS supports a form of stacking, where you +public Authentication API (auth::require_login +and auth::authenticate) be implemented through a +service contract.

Future: +Authenticating against multiple servers simultaneously

Feature	Status	Description
EXT-AUTH-36
EXT-AUTH-36	A	Authenticate against multiple servers

Both OKI and OpenACS supports a form of stacking, where you can be logged into multiple authorities at the same time. This is useful if, for example, you need to get login tokens such as Kerberos tickets for access to shared resources.

I can see the value in this, but for simplicity's sake, I'm @@ -350,30 +350,30 @@ for user/group data and access control lists, SMB for file storage, etc. But at the moment, we don't have any users of such things that are ready. We have some who are on the steps, but let's wait till -they're there.

Implement -Specific Drivers

Feature	Status	Description
Implement specific drivers
EXT-AUTH-09	A	Create Auth. drivers for Local Authority
EXT-AUTH-10	A	Create Acct. Creation driver for Local Authority
EXT-AUTH-11	A	Create Auth. driver for PAM
EXT-AUTH-12	X	Create Acct. Creation driver for PAM - this - functionality is explicitly excluded from PAM
EXT-AUTH-13	A	Create Acct. Creation driver for LDAP
EXT-AUTH-14	A	Create Auth. driver for LDAP

We'll need drivers for:

Operating system (Linux/Solaris) PAM: Delegate to the +they're there.

Implement +Specific Drivers

Feature	Status	Description
Implement specific drivers
EXT-AUTH-09	A	Create Auth. drivers for Local Authority
EXT-AUTH-10	A	Create Acct. Creation driver for Local Authority
EXT-AUTH-11	A	Create Auth. driver for PAM
EXT-AUTH-12	X	Create Acct. Creation driver for PAM - this + functionality is explicitly excluded from PAM
EXT-AUTH-13	A	Create Acct. Creation driver for LDAP
EXT-AUTH-14	A	Create Auth. driver for LDAP

We'll need drivers for:

Operating system (Linux/Solaris) PAM: Delegate to the operating system, which can then talk to RADIUS, LDAP, whatever. This is convenient because there'll be plenty of drivers for the OS PAM level, so we don't have to write them all ourselves. The downside is that we can't do things like account creation, password management, real-time account synchronization, etc., not supported by PAM (I'm not entirely sure what is and is not - supported).
RADIUS
LDAP

RADIUS

RADIUS is a simple username/password-type authentication + supported).

RADIUS
LDAP

RADIUS

RADIUS is a simple username/password-type authentication server.

It also supports sending a challenge to which the user must respond with the proper answer (e.g. mother's maiden name, or could be additional password), but we will not support this feature.

A RADIUS client -implementation +implementation in Python can be found in the -exUserFolder +exUserFolder module for Zope -(documentation).

Feedback

We'd really appreciate feedback on this proposal. Please +(documentation).

Feedback

We'd really appreciate feedback on this proposal. Please follow up at -this -openacs.org forums thread.

References

IMS Enterprise
Threads -and links collected by Carl Blesius.
Solaris/Linux -PAM specification
Draft -Proposal by Andrew Grumet.
Yale +this +openacs.org forums thread.

References

IMS Enterprise
Threads +and links collected by Carl Blesius.
Solaris/Linux +PAM specification
Draft +Proposal by Andrew Grumet.
Yale CAS, a centrl authentication service a' la - Passport.

Revision History

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

Prev	Home	Next
Bootstrapping OpenACS	Up	Chapter 16. Releasing OpenACS

docs@openacs.org

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

Revision History

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

Prev	Home	Next
Bootstrapping OpenACS	Up	Chapter 15. Releasing OpenACS

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/for-everyone.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v diff -u -N -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/for-everyone.html 13 Sep 2009 23:54:40 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/for-everyone.html 11 Dec 2010 23:36:32 -0000 1.26 @@ -1,2 +1,2 @@ - -Part I. OpenACS For Everyone

Prev		Next

OpenACS For Everyone

Table of Contents

1. High level information: What is OpenACS?

Overview
OpenACS Release Notes

Prev	Home	Next
OpenACS Core Documentation	Up	Chapter 1. High level information: What is OpenACS?

docs@openacs.org

View comments on this page at openacs.org + +Part I. OpenACS For Everyone

Prev		Next

Part I. OpenACS For Everyone

Table of Contents

1. High level information: What is OpenACS?

Overview
OpenACS Release Notes

Prev	Home	Next
OpenACS Core Documentation	Up	Chapter 1. High level information: What is OpenACS?

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -N -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/form-builder.html 17 Oct 2010 21:06:07 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 11 Dec 2010 23:36:32 -0000 1.28 @@ -1,30 +1,30 @@ - -Using Form Builder: building html forms dynamically

Prev	Chapter 11. Development Reference	Next

Using Form Builder: building html forms dynamically

Overview

($Id$)

+ +Using Form Builder: building html forms dynamically

Prev	Chapter 10. Development Reference	Next

Using Form Builder: building html forms dynamically

Overview

($Id$)

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

OpenACS has a form manager called ad_form. Ad_form has an adaptable UI. Error handling includes inline error reporting, and is customizable. However, ad_form can be tricky to use. In addition to this document, - the ad_form api - documentation is helpful.

Multi-part Elements

Some elements have more than one choice, or can submit more than one value.

SELECT elements

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

set foo_options [db_list_of_lists foo_option_list " + the ad_form api + documentation is helpful.

Multi-part Elements

Some elements have more than one choice, or can submit more than one value.

SELECT elements

Creating the form element. Populate a list of lists with values for the option list.
```
set foo_options [db_list_of_lists foo_option_list "
     select foo,
            foo_id
       from foos
-"]
-
```
The variable foo_options should resemble {{first foo} 1234} {{second foo} 1235} -
Within ad_form, set up the element to use this list:
```
{foo:text(select)
-        {label "Which Foo"}
+"]
+
```
The variable foo_options should resemble {{first foo} 1234} {{second foo} 1235} +
Within ad_form, set up the element to use this list:
```
{foo:text(select)
+        {label "Which Foo"}
         {options $foo_options}
-    }
```
This will result in a single name/value pair coming back in the submitted form. Handle this within the same ad_form structure, in the -new_data and -edit_data. In the example, it is available as $foo

Using refreshes to pull additional information from the - database

A situation you may run into often is where you want to pull + }

This will result in a single name/value pair coming back in the submitted form. Handle this within the same ad_form structure, in the -new_data and -edit_data. In the example, it is available as $foo

Using refreshes to pull additional information from the + database

A situation you may run into often is where you want to pull in form items from a sub-category when the first category is selected. Ad_form makes this fairly easy to do. In the definition of your form element, include an html section

    {pm_task_id:integer(select),optional
-        {label "Subject"}
+        {label "Subject"}
         {options {$task_options}}
-        {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}}
+        {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}}
         {value $pm_task_id}
     }

What this will do is set the value for pm_task_id and all the @@ -39,17 +39,17 @@ -on_refresh section of your ad_form. In that section, you'll get the values from the database, and set the values as so:

    db_1row get_task_values { }
     template::element set_value form_name estimated_hours_work $estimated_hours_work
-

Troubleshooting

A good way to troubleshoot when you're using ad_form is to +

Troubleshooting

A good way to troubleshoot when you're using ad_form is to add the following code at the top of the .tcl page (thanks Jerry Asher):

 ns_log notice it's my page!
 set mypage [ns_getform]
-if {[string equal "" $mypage]} {
+if {[string equal "" $mypage]} {
     ns_log notice no form was submitted on my page
 } else {
     ns_log notice the following form was submitted on my page
     ns_set print $mypage
 }
-

Tips for form widgets

Here are some tips for dealing with some of the form widgets:

Current widget

Common Errors

Here are some common errors and what to do when you - encounter them:

Error when selecting values

This generally happens when there is an error in your - query.

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

docs@openacs.org

View comments on this page at openacs.org +

Tips for form widgets

Here are some tips for dealing with some of the form widgets:

Current widget

Common Errors

Here are some common errors and what to do when you + encounter them:

Error when selecting values

This generally happens when there is an error in your + query.

Prev	Home	Next
Programming with AOLserver	Up	Chapter 11. Engineering Standards

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/general-documents.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v diff -u -N -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/general-documents.html 13 Sep 2009 23:54:40 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/general-documents.html 11 Dec 2010 23:36:32 -0000 1.26 @@ -1,2 +1,2 @@ - -Chapter 1. High level information: What is OpenACS?

Prev	Part I. OpenACS For Everyone	Next

Chapter 1. High level information: What is OpenACS?

Table of Contents

Overview
OpenACS Release Notes

Prev	Home	Next
Part I. OpenACS For Everyone	Up	Overview

docs@openacs.org

View comments on this page at openacs.org + +Chapter 1. High level information: What is OpenACS?

Prev	Part I. OpenACS For Everyone	Next

Chapter 1. High level information: What is OpenACS?

Table of Contents

Overview
OpenACS Release Notes

Prev	Home	Next
Part I. OpenACS For Everyone	Up	Overview

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/groups-design.html 17 Oct 2010 21:06:07 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,32 +1,32 @@ - -Groups Design

Prev	Chapter 15. Kernel Documentation	Next

Groups Design

By Rafael H. Schloming and Mark Thomas

+ +Groups Design

Prev	Chapter 14. Kernel Documentation	Next

Groups Design

By Rafael H. Schloming and Mark Thomas

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

Essentials

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
PL/SQL file
- -community-core-create.sql
- groups-create.sql
ER diagram
Transaction flow diagram

Introduction

Almost all database-backed websites have users, and need to model the +

Essentials

User directory
Sitewide administrator directory
Subsite administrator directory
TCL script directory
OpenACS 4 Groups Requirements
Data model
PL/SQL file
- +community-core-create.sql
- groups-create.sql
ER diagram
Transaction flow diagram

Introduction

Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services -for different user communities.

Historical Considerations

The primary limitation of the OpenACS 3.x user group system is that it -restricts the application developer to representing a "flat group" -that contains only users: The user_groups table may contain the -group_id of a parent group, but parent-child relationship +for different user communities.

Historical Considerations

The primary limitation of the OpenACS 3.x user group system is that it +restricts the application developer to representing a "flat group" +that contains only users: The user_groups table may contain the +group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.

In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of -scope, user_id, and group_id columns +scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer -to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption -(e.g., a row with a scope value of "group" but a null -group_id)
perform extra checks in Tcl and PL/SQL -functions and procedures to check both the user_id and -group_id values

Competitive Analysis

...

Design Tradeoffs

The core of the Group Systems data model is quite simple, but it was -designed in the hopes of modeling "real world" organizations which +to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption +(e.g., a row with a scope value of "group" but a null +group_id)
perform extra checks in Tcl and PL/SQL +functions and procedures to check both the user_id and +group_id values

Competitive Analysis

...

Design Tradeoffs

The core of the Group Systems data model is quite simple, but it was +designed in the hopes of modeling "real world" organizations which can be complex graph structures. The Groups System only considers groups that can be modeled using directed acyclic graphs, but queries over these structures are still complex enough to slow the system down. Since almost @@ -38,44 +38,44 @@ without making the system too complex or too slow. The added triggers, views, and tables and will increase storage requirements and the insert and delete times in an effort to speed access time. The limited flexibility (no updates -on membership) trades against the complexity of the code.

Data Model Discussion

The Group System data model consists of the following tables:

parties +on membership) trades against the complexity of the code.

Data Model Discussion

The Group System data model consists of the following tables:

parties: The set of all defined parties: any person, user, or -group must have a corresponding row in this table.
persons +group must have a corresponding row in this table.
persons: The set of all defined persons. To allow easy sorting of persons, the -name requirement 30.10 is met by -splitting the person's name into two columns: first_names and -last_name.
users +name requirement 30.10 is met by +splitting the person's name into two columns: first_names and +last_name.
users: The set of all registered users; this table includes information about -the user's email address and the user's visits to the site.
user_preferences +the user's email address and the user's visits to the site.
user_preferences -: Preferences for the user.
groups +: Preferences for the user.
groups -: The set of all defined groups.
group_types +: The set of all defined groups.
group_types: When a new type of group is created, this table holds additional -knowledge level attributes for the group and its subtypes.
membership_rels +knowledge level attributes for the group and its subtypes.
membership_rels: The set of direct membership relationships between a group and a -party.
group_member_index +party.
group_member_index -: A mapping of a party P to the groups -{G_i}the party is a member of; this mapping -includes the type of relationship by including the appropriaterel_id -from the membership_rels table.
composition_rels +: A mapping of a party P to the groups +{G_i}the party is a member of; this mapping +includes the type of relationship by including the appropriaterel_id +from the membership_rels table.
composition_rels: The set of direct component relationships between a group and another -group.
group_component_index +group.
group_component_index -: A mapping of a group Gto the set of groups -{G_i} that G is a component of; +; A mapping of a group Gto the set of groups +{G_i} that G is a component of; this mapping includes the type of relationship by including the -appropriaterel_id from the composition_rels table.

New groups are created through the group.new constructor. +appropriaterel_id from the composition_rels table.

New groups are created through the group.new constructor. When a specialized type of group is required, the group type can be extended by an application developer. Membership constraints can be specified at -creation time by passing a parent group to the constructor.

The membership_rels and composition_rels tables indicate +creation time by passing a parent group to the constructor.

The membership_rels and composition_rels tables indicate a group's direct members and direct components; these tables do not provide a record of the members or components that are in the group by virtue of being a member or component of one of the group's component groups. @@ -85,60 +85,60 @@ queries responsive, the data model includes triggers (described in the next paragraph) which watch for changes in membership or composition and update tables that maintain the group party mappings, i.e., -group_member_index and group_component_index. One can think -of these tables as a manually maintained index.

The following triggers keep the group_*_index tables up to -date:

membership_rels_in_tr +group_member_index and group_component_index. One can think +of these tables as a manually maintained index.
The following triggers keep the group_*_index tables up to +date:
membership_rels_in_tr
Is executed when a new group/member relationship is created (an insert on -membership_rels)
membership_rels_del_tr +membership_rels)
membership_rels_del_tr
Is executed when a group/member relationship is deleted (a delete on -membership_rels)
composition_rels_in_tr +membership_rels)
composition_rels_in_tr
Is executed when a new group/component relationship is created (an insert -on composition_rels)
composition_rels_del_tr +on composition_rels)
composition_rels_del_tr
Is executed when a group/component relationship is deleted (a delete on -composition_rels)
The data model provides the following views onto the -group_member_index and group_component_index tables. No -code outside of Groups System should modify the group_*_index -tables.
group_member_map +composition_rels)
The data model provides the following views onto the +group_member_index and group_component_index tables. No +code outside of Groups System should modify the group_*_index +tables.
group_member_map
A mapping of a party to the groups the party is a member of; this mapping -includes the type of relationship by including the appropriaterel_id -from the membership_rels table.
group_approved_member_map +includes the type of relationship by including the appropriaterel_id +from the membership_rels table.
group_approved_member_map
A mapping of a party to the groups the party is an approved member of -(member_state is 'approved'); this mapping includes the type -of relationship by including the appropriaterel_id from the -membership_rels table.
group_distinct_member_map +(member_state is 'approved'); this mapping includes the type +of relationship by including the appropriaterel_id from the +membership_rels table.
group_distinct_member_map
A person may appear in the group member map multiple times, for example, by being a member of two different groups that are both components of a third -group. This view is strictly a mapping of approved members -to groups.
group_component_map +group. This view is strictly a mapping of approved members +to groups.
group_component_map -
A mapping of a group Gto the set of groups -{G_i} group G is a component of; +: A mapping of a group Gto the set of groups +{G_i} group G is a component of; this mapping includes the type of relationship by including the -appropriaterel_id from the composition_rels table.
party_member_map +appropriaterel_id from the composition_rels table.
party_member_map -: A mapping of a party P to the set of parties -{P_i} party P is a member -of.
party_approved_member_map +: A mapping of a party P to the set of parties +{P_i} party P is a member +of.
party_approved_member_map -: A mapping of a party P to the set of parties -{P_i} party P is an -approved member of.

API

A mapping of a party P to the set of parties +{P_i} party P is an +approved member of.

API

The API consists of tables and views and PL/SQL functions. -

Tables and Views

The group_types table is used to create new types of groups.

The group_member_map, group_approved_member_map, -group_distinct_member_map, group_component_map, -party_member_map, and party_approved_member_map views are -used to query group membership and composition.

PL/SQL API

Person

person.new creates a new person and returns the -person_id. The function must be given the full name of the person in -two pieces: first_names and last_name. All other fields are -optional and default to null except for object_type which defaults -to person and creation_date which defaults to sysdate. The +

Tables and Views

The group_types table is used to create new types of groups.

The group_member_map, group_approved_member_map, +group_distinct_member_map, group_component_map, +party_member_map, and party_approved_member_map views are +used to query group membership and composition.

PL/SQL API

Person

person.new creates a new person and returns the +person_id. The function must be given the full name of the person in +two pieces: first_names and last_name. All other fields are +optional and default to null except for object_type which defaults +to person and creation_date which defaults to sysdate. The interface for this function is:

 function person.new (
   person_id          persons.person_id%TYPE,
@@ -151,19 +151,19 @@
   first_names        persons.first_names%TYPE,
   last_name          persons.last_name%TYPE
 ) return persons.person_id%TYPE;
-

person.delete deletes the person whose person_id is +

person.delete deletes the person whose person_id is passed to it. The interface for this procedure is:

 procedure person.delete (
   person_id     persons.person_id%TYPE
 );
-

person.name returns the name of the person whose -person_id is passed to it. The interface for this function is:

person.name returns the name of the person whose +person_id is passed to it. The interface for this function is:

 function person.name (
   person_id     persons.person_id%TYPE
 ) return varchar;
-

User

acs_user.new creates a new user and returns the user_id. +

User

acs_user.new creates a new user and returns the user_id. The function must be given the user's email address and the full name of -the user in two pieces: first_names and last_name. All +the user in two pieces: first_names and last_name. All other fields are optional. The interface for this function is:

 function acs_user.new (
   user_id            users.user_id%TYPE,
@@ -182,19 +182,19 @@
   screen_name        users.screen_name%TYPE,
   email_verified_p   users.email_verified_p%TYPE
 ) return users.user_id%TYPE;
-

acs_user.delete deletes the user whose user_id is passed +

acs_user.delete deletes the user whose user_id is passed to it. The interface for this procedure is:

 procedure acs_user.delete (
   user_id       users.user_id%TYPE
 );
-

acs_user.receives_alerts_p returns 't' if the user should +

acs_user.receives_alerts_p returns 't' if the user should receive email alerts and 'f' otherwise. The interface for this function is:

 function acs_user.receives_alerts_p (
   user_id       users.user_id%TYPE
 ) return varchar;
-

Use the procedures acs_user.approve_email and -acs_user.unapprove_email to specify whether the user's email +

Use the procedures acs_user.approve_email and +acs_user.unapprove_email to specify whether the user's email address is valid. The interface for these procedures are:

 procedure acs_user.approve_email (
   user_id       users.user_id%TYPE
@@ -203,11 +203,11 @@
 procedure acs_user.unapprove_email (
   user_id       users.user_id%TYPE
 );
-

Group

acs_group.new creates a new group and returns the -group_id. All fields are optional and default to null except for -object_type which defaults to 'group', -creation_date which defaults to sysdate, and -group_name which is required. The interface for +

Group

acs_group.new creates a new group and returns the +group_id. All fields are optional and default to null except for +object_type which defaults to 'group', +creation_date which defaults to sysdate, and +group_name which is required. The interface for this function is:

 function acs_group.new (
   group_id           groups.group_id%TYPE,
@@ -219,21 +219,21 @@
   url                parties.url%TYPE,
   group_name         groups.group_name%TYPE
 ) return groups.group_id%TYPE;
-

acs_group.name returns the name of the group whose -group_id is passed to it. The interface for this function is:

acs_group.name returns the name of the group whose +group_id is passed to it. The interface for this function is:

 function acs_group.name (
   group_id      groups.group_id%TYPE
 ) return varchar;
-

acs_group.member_p returns 't' if the specified party is +

acs_group.member_p returns 't' if the specified party is a member of the specified group. Returns 'f' otherwise. The interface for this function is:

 function acs_group.member_p (
   group_id      groups.group_id%TYPE,
   party_id      parties.party_id%TYPE,
 ) return char;
-

Membership Relationship

membership_rel.new creates a new membership relationship type -between two parties and returns the relationship type's rel_id. -All fields are optional and default to null except for rel_type +

Membership Relationship

membership_rel.new creates a new membership relationship type +between two parties and returns the relationship type's rel_id. +All fields are optional and default to null except for rel_type which defaults to membership_rel. The interface for this function is:

 function membership_rel.new (
   rel_id             membership_rels.rel_id%TYPE,
@@ -244,42 +244,42 @@
   creation_user      acs_objects.creation_user%TYPE,
   creation_ip        acs_objects.creation_ip%TYPE,
 ) return membership_rels.rel_id%TYPE;
-

membership_rel.ban sets the member_state of the given -rel_id to 'banned'. The interface for this procedure is:

membership_rel.ban sets the member_state of the given +rel_id to 'banned'. The interface for this procedure is:

 procedure membership_rel.ban (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.approve sets the member_state of the -given rel_id to 'approved'. The interface for this procedure +

membership_rel.approve sets the member_state of the +given rel_id to 'approved'. The interface for this procedure is:

 procedure membership_rel.approve (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.reject sets the member_state of the given -rel_id to 'rejected. The interface for this procedure is:

membership_rel.reject sets the member_state of the given +rel_id to 'rejected. The interface for this procedure is:

 procedure membership_rel.reject (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.unapprove sets the member_state of the -given rel_id to an empty string ''. The interface for this +

membership_rel.unapprove sets the member_state of the +given rel_id to an empty string ''. The interface for this procedure is:

 procedure membership_rel.unapprove (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.deleted sets the member_state of the -given rel_id to 'deleted'. The interface for this procedure +

membership_rel.deleted sets the member_state of the +given rel_id to 'deleted'. The interface for this procedure is:

 procedure membership_rel.deleted (
   rel_id           membership_rels.rel_id%TYPE
 );
-

membership_rel.delete deletes the given rel_id. The +

membership_rel.delete deletes the given rel_id. The interface for this procedure is:

 procedure membership_rel.delete (
   rel_id           membership_rels.rel_id%TYPE
 );
-

Composition Relationship

composition_rel.new creates a new composition relationship type -and returns the relationship's rel_id. All fields are optional -and default to null except for rel_type which defaults to +

Composition Relationship

composition_rel.new creates a new composition relationship type +and returns the relationship's rel_id. All fields are optional +and default to null except for rel_type which defaults to composition_rel. The interface for this function is:

 function membership_rel.new (
   rel_id             composition_rels.rel_id%TYPE,
@@ -289,18 +289,18 @@
   creation_user      acs_objects.creation_user%TYPE,
   creation_ip        acs_objects.creation_ip%TYPE,
 ) return composition_rels.rel_id%TYPE;
-

composition_rel.delete deletes the given rel_id. The +

composition_rel.delete deletes the given rel_id. The interface for this procedure is:

 procedure membership_rel.delete (
   rel_id           composition_rels.rel_id%TYPE
 );
-

User Interface

Describe the admin pages.

Configuration/Parameters

...

Acceptance Tests

...

Future Improvements/Areas of Likely Change

...

Authors

System creator +

User Interface

Describe the admin pages.

Configuration/Parameters

...

Acceptance Tests

...

Future Improvements/Areas of Likely Change

...

Authors

System creator -: Rafael H. Schloming
System owner +: Rafael H. Schloming
System owner -: Rafael H. Schloming
Documentation author +: Rafael H. Schloming
Documentation author -: Mark Thomas

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 08/22/2000 Rafael H. Schloming

0.2

Initial Revision

08/30/2000

Mark Thomas

Revision History

Document Revision # Action Taken, Notes When? By Whom?

0.1 Creation 08/22/2000 Rafael H. Schloming

0.2 Initial Revision 08/30/2000 Mark Thomas

0.3

Additional revisions; tried to clarify membership/compostion

09/08/2000

Mark Thomas Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 17 Oct 2010 21:06:07 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,60 +1,60 @@ - -Groups Requirements

Prev	Chapter 15. Kernel Documentation	Next

Groups Requirements

By Rafael H. Schloming, Mark Thomas

+ +Groups Requirements

Prev	Chapter 14. Kernel Documentation	Next

Groups Requirements

By Rafael H. Schloming, Mark Thomas

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

Introduction

Almost all database-backed websites have users, and need to model the +

Introduction

Vision Statement

A powerful web service that can meet the needs of large enterprises must + for different user communities.

Vision Statement

A powerful web service that can meet the needs of large enterprises must be able to model the the real world's very rich organizational structures and many ways of decomposing the same organization. For example, a corporation can be broken into structures (the corporation, its divisions, and their departments) or regions (the Boston office, the LA office); a person who is employed by (is a member of) a specific department is also a member of the division and the corporation, and works at (is a member of, but in a different sense) a particular office. OpenACS's Parties and Groups - system will support such complex relations faithfully.

Historical Motivations

The primary limitation of the OpenACS 3.x user group system is that it - restricts the application developer to representing a "flat group" - that contains only users: The user_groups table may contain the - group_id of a parent group, but parent-child relationship + system will support such complex relations faithfully.

Historical Motivations

The primary limitation of the OpenACS 3.x user group system is that it + restricts the application developer to representing a "flat group" + that contains only users: The user_groups table may contain the + group_id of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships expensive.

In addition, the Module Scoping design in OpenACS 3.0 introduced a party abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of - scope, user_id, and group_id columns + scope, user_id, and group_id columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer - to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption - (e.g., a row with a scope value of "group" but a null - group_id)
perform extra checks in Tcl and PL/SQL - functions and procedures to check both the user_id and - group_id values

In sum, the goal of the Parties and Groups system is to + to:

add these three columns to each "scoped" table
define a multi-column check constraint to protect against data corruption + (e.g., a row with a scope value of "group" but a null + group_id)
perform extra checks in Tcl and PL/SQL + functions and procedures to check both the user_id and + group_id values

In sum, the goal of the Parties and Groups system is to provide OpenACS programmers and site administrators with simple tools that fully describe the complex relationships that exist among groups in the real - world.

User Scenarios

Pat Developer has a client project and wants to model the company, its + world.

User Scenarios

Pat Developer has a client project and wants to model the company, its offices, its divisions, and its departments as groups and the employees as - users.

System Overview

We start with Groups, which contain members; the - member can be either a person or another group (i.e. a + users.

System Overview

We start with Groups, which contain members; the + member can be either a person or another group (i.e. a member is a party).

In addition to membership, the party and groups system defines a - composition relationship that may exist between groups: A - group can be a component of another group. The child group + composition relationship that may exist between groups: A + group can be a component of another group. The child group is called a component group; the parent group is called a - composite group.

A group G_c can be a member and/or a component - of another group G_p; the difference is in the way - the members of G_c are related to - G_p:

If a party P is a member (or a component) of - G_c and if G_c is a - component of G_p, then P is also - a member (or a component) of G_p
If a party P is a member (or a component) of - G_c and if G_c is a - member of G_p, then no - relationship between P and - G_p exists as a result of the relationship between - G_p and G_p.

Consider an example to make this less abstract: Pretend that the Sierra + composite group.

A group G_c can be a member and/or a component + of another group G_p; the difference is in the way + the members of G_c are related to + G_p:

If a party P is a member (or a component) of + G_c and if G_c is a + component of G_p, then P is also + a member (or a component) of G_p
If a party P is a member (or a component) of + G_c and if G_c is a + member of G_p, then no + relationship between P and + G_p exists as a result of the relationship between + G_p and G_p.

Consider an example to make this less abstract: Pretend that the Sierra Club is a member of Greenpeace. The Sierra Club has chapters; each chapter is a component of the Sierra Club. If Eddie Environmentalist is a member of the Massachusetts Chapter of the Sierra Club, Eddie is @@ -67,158 +67,158 @@ Massachusetts chapter), and between the Sierra Club and Greenpeace.

Membership requirements can vary from group to group. The parties and groups system must provide a base type that specifies the bare minimum necessary to join a group.

The parties and groups system must support constraints between a composite - group G_P and any of its component groups, - G_C. For example, the system should be able to - enforce a rule like: Do not allow a party P to become a - member of G_C unless P is already - a member of G_P.

Requirements: Data Model

The data model for the parties and groups system must provide support for - the following types of entities:

10.0 Parties + group G_P and any of its component groups, + G_C. For example, the system should be able to + enforce a rule like: Do not allow a party P to become a + member of G_C unless P is already + a member of G_P.

Requirements: Data Model

The data model for the parties and groups system must provide support for + the following types of entities:

10.0 Parties -

A party is an entity used to represent either a - group or a person.

The data model should enforce these constraints:

10.10 A party has an email address, which can be - empty.

10.20 A party may have multiple email addresses - associated with it.

10.30 The email address of a party must be unique within - an OpenACS system.

20.0 Groups +

A party is an entity used to represent either a + group or a person.

The data model should enforce these constraints:

10.10 A party has an email address, which can be + empty.

10.20 A party may have multiple email addresses + associated with it.

10.30 The email address of a party must be unique within + an OpenACS system.

20.0 Groups -

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of - groups via OpenACS Objects.

30.0 Persons +

A group is a collection of zero or more parties.

20.10 The data model should support the subclassing of + groups via OpenACS Objects.

30.0 Persons -

A person represents an actual human being, past or - present.

30.10. A person must have - an associated name.

40.0 Users +

A person represents an actual human being, past or + present.

30.10. A person must have + an associated name.

40.0 Users -

A user is a person who has registered with an OpenACS site. A - user may have additional attributes, such as a screen name.

The data model should enforce these constraints:

40.10 A user must have a non-empty email address.

40.20 Two different users may not have the same email +

A user is a person who has registered with an OpenACS site. A + user may have additional attributes, such as a screen name.

The data model should enforce these constraints:

40.10 A user must have a non-empty email address.

40.20 Two different users may not have the same email address on a single OpenACS installation; i.e., an email address identifies a - single user on the system.

40.30 A user may have multiple email addresses; for - example, two or more email addresses may identify a single user.

40.40 A user must have password field which can be + single user on the system.

40.30 A user may have multiple email addresses; for + example, two or more email addresses may identify a single user.

40.40 A user must have password field which can be empty.

The data model for the parties and groups system must provide support for - the following types of relationships between entities:

50.0 Membership + the following types of relationships between entities:
50.0 Membership
- A party P is considered a member of a - group G
when a direct membership relationship exists between P - and G
or when there exists a direct membership relationship between - P and some group G_C and - G_C has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple + A party P is considered a member of a + group G
when a direct membership relationship exists between P + and G
or when there exists a direct membership relationship between + P and some group G_C and + G_C has a composition relationship (c.f., 60.0) with G.
50.10 A party may be a member of multiple groups.
50.20 A party may be a member of the same group multiple times only when all the memberships have different types; for example, Jane may be a member of The Company by being both an Employee and an - Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership - constraints.
50.50The data model should support the subclassing of + Executive.
50.30 A party as a member of itself is not supported.
50.40 The data model must support membership + constraints.
50.50The data model should support the subclassing of membership via OpenACS Relationships.
- 60.0 Composition -
A group G_C is considered a - component of a second group - G_P
when a direct composition relationship exists between - G_C and G_P
or when there exists a direct composition relationship between - G_C and some group G_i - and G_i has a composition relationship with - G_P.
60.10A group may be a component of multiple groups.
60.20A group as a component of itself is not - supported.
60.30The data model must support component - constraints.
60.40The data model should support the subclassing of - composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group + 60.0 Composition +

A group G_C is considered a + component of a second group + G_P

when a direct composition relationship exists between + G_C and G_P
or when there exists a direct composition relationship between + G_C and some group G_i + and G_i has a composition relationship with + G_P.

60.10A group may be a component of multiple groups.

60.20A group as a component of itself is not + supported.

60.30The data model must support component + constraints.

60.40The data model should support the subclassing of + composition via OpenACS Relationships.

Requirements: API

The API should let programmers accomplish the following tasks:

70.10 Create a group

The parties and groups system provides a well defined API call that creates a new group by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.

70.20 Create a person + in the data model.

70.20 Create a person

The parties and groups system provides a well defined API call that creates a new person by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.

70.30 Create a user + in the data model.

70.30 Create a user

The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out in - the data model.

80.10 Refine a person to a user + the data model.

80.10 Refine a person to a user

The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on an existing person entity. This API is subject to the constraints laid out in the data - model.

80.30 Demote a user to a person + model.

80.30 Demote a user to a person

The parties and groups system provides a well defined API call that demotes an existing user entity to a person entity by running the appropriate transactions on the existing user. This API is subject to the constraints - laid out in the data model.

90.10 Update a party + laid out in the data model.

90.10 Update a party

The programmer should be able to modify, add, and delete attributes on any - party. This API is subject to the constraints laid out in the data model.

95.10 Get the attributes of a party + party. This API is subject to the constraints laid out in the data model.

95.10 Get the attributes of a party

The programmer should be able to view the attributes on any party. This - API is subject to the constraints laid out in the data model.

100.10 Delete a party + API is subject to the constraints laid out in the data model.

100.10 Delete a party

The system provides an API for deleting a party. This API is subject to - the constraints laid out in the data model.

100.30 The system may provide a single API call to remove - the party from all groups and then delete the party.

100.40 In the case of a group, the system may provide a + the constraints laid out in the data model.

100.30 The system may provide a single API call to remove + the party from all groups and then delete the party.

100.40 In the case of a group, the system may provide a single API call to remove all parties from a group and then delete the - group.

110.0 Add a party as a member of a group + group.

110.0 Add a party as a member of a group

The parties and groups system provides an API for adding a party as a member of a group. This API is subject to the constraints laid out in the - data model.

115.0 Add a group as a component of a second group + data model.

115.0 Add a group as a component of a second group

The parties and groups system provides an API for adding a group as a component of a second group. This API is subject to the constraints laid out - in the data model.

120.0 Remove a party as a member of a group + in the data model.

120.0 Remove a party as a member of a group

The parties and groups system provides an API for deleting a party's membership in a group. This API is subject to the constraints laid out in the - data model.

125.0 Remove a group as a component of a second - group + data model.

125.0 Remove a group as a component of a second + group

The parties and groups system provides an API for deleting a group's composition in a second group. This API is subject to the constraints laid - out in the data model.

130.0 Membership check + out in the data model.

130.0 Membership check

The parties and groups system provides an API for answering the question: - "Is party P a member of group - G?"

135.0 Composition check + "Is party P a member of group + G?"

135.0 Composition check

The parties and groups system provides an API for answering the question: - "Is group G_C a component of group - G_P?"

140.0 Get members query + "Is group G_C a component of group + G_P?"

140.0 Get members query

The parties and groups system provides an API for answering the question: - "Which parties are members of group G?"

145.0 Get components query + "Which parties are members of group G?"

145.0 Get components query

The parties and groups system provides an API for answering the question: - "Which groups are components of group G?"

150.0 Member-of-groups query + "Which groups are components of group G?"

150.0 Member-of-groups query

The parties and groups system provides an API for answering the question: - "Of which groups is party P a member?"

155.0 Component-of-groups query + "Of which groups is party P a member?"

155.0 Component-of-groups query

The parties and groups system provides an API for answering the question: - "Of which groups is group G a component?"

160.0 Allowed membership check + "Of which groups is group G a component?"

160.0 Allowed membership check

The parties and groups system provides an API for answering the question: - "Is party P allowed to become a member of group - G?"

165.0 Allowed composition check + "Is party P allowed to become a member of group + G?"

165.0 Allowed composition check

The parties and groups system provides an API for answering the question: - "Is group G_C allowed to become a component - of group G_P?"

170.0 Efficiency + "Is group G_C allowed to become a component + of group G_P?"

170.0 Efficiency

Since many pages at a site may check membership in a group before serving a page (e.g., as part of a general permissions check), the data model must support the efficient storage and retrieval of party attributes and - membership.

180.0 Ease of Use + membership.

180.0 Ease of Use

Since many SQL queries will check membership in a group as part of the - where clause, whatever mechanism is used to check membership in SQL - should be fairly small and simple.

Requirements: User Interface

The user interface is a set of HTML pages that are used to drive the - underlying API. The user interface may provide the following functions:

200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks - outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
Permissions Design	Up	Groups Design

docs@openacs.org

View comments on this page at openacs.org + where clause, whatever mechanism is used to check membership in SQL + should be fairly small and simple.

Requirements: User Interface

The user interface is a set of HTML pages that are used to drive the + underlying API. The user interface may provide the following functions:

200.0 Create a party
210.0 View the attributes of a party
220.0 Update the attributes of a party
240.0 Delete a party
250.0 Add a party to a group
260.0 Remove a party from a group
270.0 Perform the membership and composition checks + outlined in 130.x to 165.x

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
0.1	Creation	08/16/2000	Rafael Schloming
0.2	Initial revision	08/19/2000	Mark Thomas
0.3	Edited and reviewed, conforms to requirements template	08/23/2000	Kai Wu
0.4	Further revised, added UI requirements	08/24/2000	Mark Thomas
0.5	Final edits, pending freeze	08/24/2000	Kai Wu
0.6	More revisions, added composition requirements	08/30/2000	Mark Thomas
0.7	More revisions, added composition requirements	09/08/2000	Mark Thomas

Prev	Home	Next
Permissions Design	Up	Groups Design

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.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/high-avail.html 17 Oct 2010 21:06:07 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/high-avail.html 11 Dec 2010 23:36:32 -0000 1.22 @@ -1,2 +1,2 @@ - -High Availability/High Performance Configurations

Prev	Chapter 6. Production Environments	Next

High Availability/High Performance Configurations

Figure 6.1. Multiple-server configuration

Prev	Home	Next
Running multiple services on one machine	Up	Staged Deployment for Production Networks

docs@openacs.org

View comments on this page at openacs.org + +High Availability/High Performance Configurations

Prev	Chapter 6. Production Environments	Next

High Availability/High Performance Configurations

Figure 6.1. Multiple-server configuration

Prev	Home	Next
Running multiple services on one machine	Up	Staged Deployment for Production Networks

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/how-do-I.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.html,v diff -u -N -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/how-do-I.html 17 Oct 2010 21:06:07 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/how-do-I.html 11 Dec 2010 23:36:32 -0000 1.25 @@ -1,7 +1,7 @@ - -How Do I?

Prev	Chapter 4. Configuring a new OpenACS Site	Next

How Do I?

How do I edit the front page of a new site through a web interface?

The easiest way is to install the Edit-This-Page package.

Log in to the web site as an administrator.
Click on Admin > Install Software > Install from OpenACS Repository / Install new application
Choose Edit This Page and install
Follow the instructions within Edit This Page (the link will only work after Edit This Page is installed).

How do I let anybody who registers post to a weblog?

Go to /admin/permissions and grant Create to Registered Users

How do I replace the front page of a new site with the front page of an application on that site

Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.

On the front page, click the Admin button.
On the administration page, click Parameters link.
Change the parameter IndexRedirectUrl to be the URI of the desired application. For a default weblogger installation, this would be weblogger/. Note the trailing slash.

How do I put custom functionality on front page of a new site?

Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:

cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www

Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality.

How do I change the site-wide style?

Almost all pages on an OpenACS site use ACS Templating, and so their appearance is driven by a layer of different files. Let's examine how this works:

+ +How Do I?
Prev Chapter 4. Configuring a new OpenACS Site Next
How Do I?
How do I edit the front page of a new site through a web interface?
The easiest way is to install the Edit-This-Page package.
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
How do I diagnose a permissions problem?
- Steps to Reproduce. The events package does not allow users to register for new events.
  Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.
  Select an available event
  A link such as Registration: Deadline is 03/15/2004 10:00am. -» Login or sign up to register for this event. is visible. Click on "Login or sign up" -
  Complete a new registration. Afterwards, you should be redirected back to the same page.
  Actual Results: The page says "You do not have permission to register for this event."
  Expected results: A link or form to sign up for the event is shown.
- Finding the problem. We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line:
  set can_register_p [events::security::can_register_for_event_p -event_id $event_id]
  We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply
  return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]
  This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.
- Setting Permissions. A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.
  To grant permissions on a package, start at the site map. Find the event package and click "Set permissions".
  Click "Grant Permission"
  Grant the write permission to Registered Users.
  Figure 4.2. Granting Permissions
  OpenACS 5.0 offers a prettier version at /admin/applications.
  Figure 4.3. Granting Permissions in 5.0
Prev Home Next
Setting Permissions on an OpenACS package Up Chapter 5. Upgrading
docs@openacs.org
View comments on this page at openacs.org +
```
<master>
```
If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file. +
The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl)
The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl).
Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.

Figure 4.1. 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
OpenACS 5.0 offers a prettier version at /admin/applications.
Figure 4.3. Granting Permissions in 5.0

Prev	Home	Next
Setting Permissions on an OpenACS package	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.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 17 Oct 2010 21:06:07 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 11 Dec 2010 23:36:32 -0000 1.24 @@ -1,5 +1,5 @@ - -How to Internationalize a Package

Prev	Chapter 14. Internationalization	Next

How to Internationalize a Package

Tip

+ +How to Internationalize a Package

Prev	Chapter 13. Internationalization	Next

How to Internationalize a Package

Tip

For multilingual websites we recommend using the UTF8 charset. In order for AOLserver to use utf8 you need to set the config parameters OutputCharset and @@ -9,53 +9,53 @@ variable set to .UTF8. You should set this variable in the nsd-oracle run script (use the acs-core-docs/www/files/nds-oracle.txt template file). -

Replace all text with temporary message tags. From/acs-admin/apm/, select a +

Replace all text with temporary message tags. From/acs-admin/apm/, select a package and then click on - Internationalization, then - Convert ADP, Tcl, and SQL files to using the - message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.
You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.
Replace the temporary message tags in ADP files. From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat the process but deselect Find human language text ... and select Replace <# ... #> tags ... and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.

Replace human-readable text in TCL files with temporary tags. Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:

-set title "Messages for $a(name) in $b(label)" -set context [list [list . "SimPlay"] \ + Internationalization, then + Convert ADP, Tcl, and SQL files to using the + message catalog.. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.

You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key.

Replace the temporary message tags in ADP files. From the same Convert ADP ... page in /acs-admin/apm as in the last step, repeat the process but deselect Find human language text ... and select Replace <# ... #> tags ... and click OK. This step replaces all of the temporary tags with "short" message lookups, inserts the message keys into the database message catalog, and then writes that catalog out to an xml file.
Replace human-readable text in TCL files with temporary tags. Examine all of the tcl files in the packages for human-readable text and replace it with temporary tags. The temporary tags in TCL are slightly different from those in ADP. If the first character in the temporary tag is an underscore (_), then the message keys will be auto-generated from the original message text. Here is an unmodified tcl file:
```
+set title "Messages for $a(name) in $b(label)"
+set context [list [list . "SimPlay"] \
                   [list [export_vars -base case-admin { case_id }] \ 
-                    "Administer $a(name)"] \
-                  "Messages for $a(name)"]
+                    "Administer $a(name)"] \
+                  "Messages for $a(name)"]
 
```
... and here is the same file after temporary message tags have been manually added:
```
 set title <#admin_title Messages for %a.name% in %b.label%#>
 set context [list [list . <#_ SimPlay#>] \
                   [list [export_vars -base case-admin { case_id }] \
                     <#_ Administer %a.name%#>] \
                   <#_ Messages for %a.name%#>]
-
```
Note that the message key case_admin_page_title was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing -
Replace the temporary message tags in TCL files. Repeat step 2 for tcl files. Here is the example TCL file after conversion:
```
+
```
Note that the message key case_admin_page_title was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing +

Replace the temporary message tags in TCL files. Repeat step 2 for tcl files. Here is the example TCL file after conversion:

 set title [_ simulation.admin_title]
 set context [list [list . [_ simulation.SimPlay]] \
                   [list [export_vars -base case-admin { case_id }] \
                     [_ simulation.lt_Administer_name_gt]] \
                   [_ simulation.lt_Messages_for_role_pre]]
-

Internationalize SQL Code. If there is any user-visible TCL code in the .sql or .xql files, internationalize that the same way as for the TCL files.
Internationalize Package Parameters. - See Multilingual APM Parameters -
Internationalize Date and Time queries.
1. Find datetime in .xql files. Use command line tools to find suspect SQL code:
```
grep -r "to_char.*H" *
-grep -r "to_date.*H" *
-
```
2. In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
```
to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
```
  becomes
```
to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
```
3. In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
```
-set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
```
  When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. -
4. When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
```
set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
```
  - Use the _pretty version in your ADP page. -
  - +
  - Internationalize SQL Code. If there is any user-visible TCL code in the .sql or .xql files, internationalize that the same way as for the TCL files.
  - Internationalize Package Parameters. + See Multilingual APM Parameters +
  - Internationalize Date and Time queries.
    Find datetime in .xql files. Use command line tools to find suspect SQL code:
    grep -r "to_char.*H" * +grep -r "to_date.*H" * +
    In SQL statements, replace the format string with the ANSI standard format, YYYY-MM-DD HH24:MI:SS and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,
    to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty
    becomes
    to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi
    In TCL files where the date fields are used, convert the datetime from local server timezone, which is how it's stored in the database, to the user's timezone for display. Do this with the localizing function lc_time_system_to_conn:
    +set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]
    When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with lc_time_conn_to_system. +
    When a datetime field will be displayed, format it using the localizing function lc_time_fmt. lc_time_fmt takes two parameters, datetime and format code. Several format codes are usable for localization; they are placeholders that format dates with the appropriate codes for the user's locale. These codes are: %x, %X, %q, %Q, and %c.
    set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]
    + Use the _pretty version in your ADP page. +
    %c: Long date and time (Mon November 18, 2002 12:00 AM) -
    +
    %x: Short date (11/18/02) -
    +
    %X: Time (12:00 AM) -
    +
    %q: Long date without weekday (November 18, 2002) -
    +
    %Q: Long date with weekday (Monday November 18, 2002)
    - The "q" format strings are OpenACS additions; the rest follow unix standards (see man - strftime). -
  - Internationalize Numbers. - To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. -
  - Internationalizing Forms. When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
  - Checking the Consistency of Catalog Files. + The "q" format strings are OpenACS additions; the rest follow unix standards (see man + strftime). +
Internationalize Numbers. + To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. +
Internationalizing Forms. When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.
Checking the Consistency of Catalog Files. This section describes how to check that the set of keys used in message lookups in tcl, adp, and info files and the set of keys in the catalog file are identical. The scripts below assume that @@ -64,23 +64,23 @@ are always is done with one of the valid lookups described above. The script further assumes that you have perl installed and in your path. Run the script like this: - + acs-lang/bin/check-catalog.sh package_key -+
where package_key is the key of the package that you want to test. If you don't provide the package_key argument then all packages with catalog files will be checked. The script will run its checks primarily on en_US xml catalog files. -

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, 
+      
```

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
+  </p>

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

Select which case <if @simulation.casting_type@ eq "open">and
 role</if> to join, or create a new case for yourself.  If you do not
-select a case <if @simulation.casting_type@ eq "open">and role</if>
+select a case <if @simulation.casting_type@ eq "open">and role</if>
 to join, you will be automatically assigned to a case <if
-@simulation.casting_type@ eq "open">and role</if> when the
-simulation begins.

... can be rewritten:

<if @simulation.casting_type@ eq "open">
+@simulation.casting_type@ eq "open">and role</if> when the
+simulation begins.

... can be rewritten:

<if @simulation.casting_type@ eq "open">
 
 Select which case and role to join, or create a new case for
 yourself.  If you do not select a case and role to join, you will
@@ -96,7 +96,7 @@
 begins.
 
 </else>

Another example, where bugs are concatenated with a number:

<if @components.view_bugs_url@ not nil>
-  <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component">
+  <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component">
   </if>
   @components.num_bugs@ 
   <if @components.num_bugs@ eq 1>
@@ -110,7 +110,7 @@
   </if>
 
 <if @components.view_bugs_url@ not nil>
-<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">
+<a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">
 </if>
 @components.num_bugs@ 
 <if @components.num_bugs@ eq 1>
@@ -124,39 +124,39 @@
 </if>

It would probably be better to do this as something like:

<if @components.view_bugs_url@ not nil>
   <if @components.num_bugs@ eq 1>
-    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a>
+    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a>
   </if><else>
-    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a>
+    <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a>
   </else>
-</if>

Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:
Original code:
```
multirow append links "New [bug_tracker::conn Bug]" 
```
Problematic conversion:
```
multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"
```
Better conversion:
```
set bug_label [bug_tracker::conn Bug]
-multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"
```
... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.
In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):
```
<a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@">
-@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>
```
Avoid unnecessary duplicate keys. When phrases are exactly the same in several places, use a single key.
For common words such as - Yes and No, you can use a library of keys at acs-kernel. +</if>
Don't combine keys in display text. Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:
Original code:
```
multirow append links "New [bug_tracker::conn Bug]" 
```
Problematic conversion:
```
multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"
```
Better conversion:
```
set bug_label [bug_tracker::conn Bug]
+multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"
```
... and include the variable in the key: "New %bug_label%". This gives translators more control over the phrase.
In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):
```
<a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@">
+@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a>
```
Avoid unnecessary duplicate keys. When phrases are exactly the same in several places, use a single key.
For common words such as + Yes and No, you can use a library of keys at acs-kernel. For example, instead of using - myfirstpackage.Yes, you - can use acs-kernel.Yes. - You can also use the Message Key Search facility to find duplicates. + myfirstpackage.Yes, you + can use acs-kernel.Yes. + You can also use the Message Key Search facility to find duplicates. Be careful, however, building up sentences from keys because grammar and other elements may not be consistent - across different locales.
Additional discussion: Re: - Bug 961 ("Control Panel" displayed instead of - "Administer"), Translation - server upgraded, and Localization questions.
Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
For example, the original code is
```
workflow::case::add_log_data \ 	    
+            across different locales.
Additional discussion: Re:
+            Bug 961 ("Control Panel" displayed instead of
+            "Administer"), Translation
+            server upgraded, and Localization questions.
```
Don't internationalize internal code words. Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.
For example, the original code is
```
workflow::case::add_log_data \ 	    
        -entry_id $entry_id \ 	    
-       -key "resolution" \ 	    
+       -key "resolution" \ 	    
        -value [db_string select_resolution_code {}]
```
This is incorrectly internationalized to
```
  workflow::case::add_log_data \ 	    
        -entry_id $entry_id \
-       -key "[_ bug-tracker.resolution]" \
-       -value [db_string select_resolution_code {}]
```
But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:
```
{show_patch_status "open"}
```
It is broken if changed to
```
{show_patch_status "[_ bug-tracker.open]"}
```
Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
```
-<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
-<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch 
+       -key "[_ bug-tracker.resolution]" \
+       -value [db_string select_resolution_code {}]
```
But resolution is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:
```
{show_patch_status "open"}
```
It is broken if changed to
```
{show_patch_status "[_ bug-tracker.open]"}
```
Fix automatic truncated message keys. The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:
```
+<msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg>
+<msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch 
 and users with write permission on this Bug Tracker project (package instance) may do so.</msg>
-<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch 
-and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
```
These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? -
Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:
```
<msg key="Fix">for version</msg>
-<msg key="Fix_1">for</msg>
-<msg key="Fix_2">for Bugs</msg>
```
Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.
Translations in Avoid "clever" message reuse. Translations may need to differ depending on the context in which +<msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch +and users with write permission on the Bug Tracker project (package instance) may do so.</msg>
These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? +
Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:
```
<msg key="Fix">for version</msg>
+<msg key="Fix_1">for</msg>
+<msg key="Fix_2">for Bugs</msg>
```
Another example: Bug-tracker component maintainer" was converted to "[_ bug-tracker.Bug-tracker]". Instead, it should be bug_tracker_component_maintainer.
Translations in Avoid "clever" message reuse. Translations may need to differ depending on the context in which the message appears. -
Avoid plurals. Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl. Watch out for quoting and escaping when editing text that is also code. For example, the original string
```
set title "Patch \"$patch_summary\" is nice."
```
breaks if the message text retains all of the escaping that was in the tcl command:
```
<msg>Patch \"$patch_summary\" is nice.</msg>
```
When it becomes a key, it should be:
```
<msg>Patch "$patch_summary" is nice.</msg>
```
Also, some keys had %var;noquote%, which is not needed since those +
Avoid plurals. Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.
Quoting in the message catalog for tcl. Watch out for quoting and escaping when editing text that is also code. For example, the original string
```
set title "Patch \"$patch_summary\" is nice."
```
breaks if the message text retains all of the escaping that was in the tcl command:
```
<msg>Patch \"$patch_summary\" is nice.</msg>
```
When it becomes a key, it should be:
```
<msg>Patch "$patch_summary" is nice.</msg>
```
Also, some keys had %var;noquote%, which is not needed since those variables are not quoted (and in fact the variable won't even be - recognized so you get the literal %var;noquote% in the output).
Be careful with curly brackets. Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code
```
array set names { key "Pretty" ...} 
```
... if converted to
```
array set names { key "[_bug-tracker.Pretty]" ...} 
```
... won't work since the _ func will not be called. Instead, it should be
```
array set names [list key [_bug-tracker.Pretty] ...]
```

Prev	Home	Next
How Internationalization/Localization works in OpenACS	Up	Design Notes

docs@openacs.org

View comments on this page at openacs.org + recognized so you get the literal %var;noquote% in the output).

Be careful with curly brackets. Code within curly brackets isn't evaluated. TCL uses curly brackets as an alternative way to build lists. But TCL also uses curly brackets as an alternative to quotation marks for quoting text. So this original code

array set names { key "Pretty" ...}

... if converted to

array set names { key "[_bug-tracker.Pretty]" ...}

... won't work since the _ func will not be called. Instead, it should be

array set names [list key [_bug-tracker.Pretty] ...]

Prev	Home	Next
How Internationalization/Localization works in OpenACS	Up	Design Notes

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-design.html,v diff -u -N -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/i18n-design.html 17 Oct 2010 21:06:07 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/i18n-design.html 11 Dec 2010 23:36:32 -0000 1.14 @@ -1,3 +1,3 @@ - -Design Notes

Prev	Chapter 14. Internationalization	Next

Design Notes

User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US

For ADP pages, message key lookup occurs in the templating engine. For TCL pages, message key lookup happens with the _ function. In both cases, if the requested locale is not found but a locale which is the default for the language which matches your locale's language is + +Design Notes

Prev	Chapter 13. Internationalization	Next

Design Notes

User locale is a property of ad_conn, ad_conn locale. The request processor sets this by calling lang::conn::locale, which looks for the following in order of precedence:

Use user preference for this package (stored in ad_locale_user_prefs)
Use system preference for the package (stored in apm_packages)
Use user's general preference (stored in user_preferences)
Use Browser header (Accept-Language HTTP header)
Use system locale (an APM parameter for acs_lang)
default to en_US

Prev	Home	Next
How to Internationalize a Package	Up	Translator's Guide

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-introduction.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-introduction.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.html 17 Oct 2010 21:06:07 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.html 11 Dec 2010 23:36:32 -0000 1.16 @@ -1,20 +1,20 @@ - -How Internationalization/Localization works in OpenACS

Prev	Chapter 14. Internationalization	Next

How Internationalization/Localization works in OpenACS

+ +How Internationalization/Localization works in OpenACS

Prev	Chapter 13. Internationalization	Next

How Internationalization/Localization works in OpenACS

This document describes how to develop internationalized OpenACS packages, including writing new packages with internationalization and converting old packages. Text that - users might see is "localizable text"; replacing monolingual text + users might see is "localizable text"; replacing monolingual text and single-locale date/time/money functions with generic - functions is "internationalization"; translating first - generation text into a specific language is "localization." At + functions is "internationalization"; translating first + generation text into a specific language is "localization." At a minimum, all packages should be internationalized. If you do not also localize your package for different locales, volunteers - may use a public "localization server" to submit suggested text. + may use a public "localization server" to submit suggested text. Otherwise, your package will not be usable for all locales.

The main difference between monolingual and internationalized packages is that all user-visible text in the code of an internationalized - package are coded as "message keys." The message keys + package are coded as "message keys." The message keys correspond to a message catalog, which contains versions of the text for each available language. Script files (.adp and .tcl and .vuh), database files (.sql), and APM parameters are affected. @@ -33,33 +33,33 @@ which are static and mostly text, it may be easier to create a new ADP page for each language. In this case, the pages are distinguished by a file naming convention. -

User Content

OpenACS does not have a general system for supporting multiple, localized versions of user-input content. This document currently refers only to internationalizing the text in the package user interface.

Separate Templates for each Locale

If the request processor finds a file named filename.locale.adp, where locale matches the user's locale, it will process that file instead of filename.adp. For example, for a user with locale tl_PH, the file index.tl_PH.adp, if found, will be used instead of index.adp. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.

Message Catalogs

Message Keys in Template Files (ADP Files)

User Content

Separate Templates for each Locale

Message Catalogs

Message Keys in Template Files (ADP Files)

Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in the desired locale. Message keys themselves should be in ASCII English, as should all code. Three different syntaxes are possible for message keys.

- "Short" syntax is the recommended syntax and should be used + "Short" syntax is the recommended syntax and should be used for new development. When internationalizing an existing - package, you can use the "temporary" syntax, which the APM can + package, you can use the "temporary" syntax, which the APM can use to auto-generate missing keys and automatically translate - to the short syntax. The "verbose" syntax is useful while + to the short syntax. The "verbose" syntax is useful while developing, because it allows default text so that the page is usable before you have done - localization.

- The short: - #package_key.message_key# + localization.
- + The short: + #package_key.message_key#
  The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable. Example: #forum.title# -
- - The verbose: <trn - key="package_key.message_key" - locale="locale">default - text</trn> +
- + The verbose: <trn + key="package_key.message_key" + locale="locale">default + text</trn>
  The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended @@ -68,11 +68,11 @@ in the message catalog yet, because what it'll do is create the message key with the default text from the tag as the localized message. Example: <trn - key="forum.title" locale="en_US">Title</trn> -
- - The temporary: - <#message_key - original text#> + key="forum.title" locale="en_US">Title</trn> +
- + The temporary: + <#message_key + original text#>
  This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that @@ -83,21 +83,21 @@ auto-generated by the APM. Example: <_ Title>
We recommend the short notation for new package development. -

Message Keys in TCL Files

In adp files message lookups are typically done with the syntax - \#package_key.message_key\#. In Tcl + \#package_key.message_key\#. In Tcl files all message lookups *must* be on either of the following formats:

Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
- Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.

- Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in the code. Here is an example of a dynamic lookup: - set message_key_array { +

Typical static key lookup: [_ package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
+ Static key lookup with non-default locale: [lang::message::lookup $locale package_key.message_key] - The message key and package key used here must be string literals, they can't result from variable evaluation.
+ Dynamic key lookup: [lang::util::localize $var_with_embedded_message_keys] - In this case the message keys in the variable var_with_embedded_message_keys must appear as string literals \#package_key.message_key\# somewhere in the code. Here is an example of a dynamic lookup: + set message_key_array { dynamic_key_1 \#package_key.message_key1\# dynamic_key_2 \#package_key.message_key2\# } set my_text [lang::util::localize $message_key_array([get_dynamic_key])] -+

Translatable texts in page TCL scripts are often found in page titles, @@ -106,16 +106,16 @@ that can be used on Linux to highlight translatable text in TCL files:

 # Find text in double quotes
-find -iname '*.tcl'|xargs egrep -i '"[a-z]'
+find -iname '*.tcl'|xargs egrep -i '"[a-z]'
 
 # Find untranslated text in form labels, options and values
-find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
+find -iname '*.tcl'|xargs egrep -i '\-(options|label|value)'|egrep -v '<#'|egrep -v '\-(value|label|options)[[:space:]]+\$[a-zA-Z_]+[[:space:]]*\\?[[:space:]]*$'
 
 # Find text in page titles and context bars
-find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'
+find -iname '*.tcl'|xargs egrep -i 'set (title|page_title|context_bar) '|egrep -v '<#'
 
 # Find text in error messages
-find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'
+find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'

You may mark up translatable text in TCL library files and TCL pages @@ -124,82 +124,82 @@ variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog (remember that translators is made easier the longer the phrases to translate are). In those cases, follow these steps: -

+
- For each message call in the text, decide on a variable name and replace the procedure call with a variable lookup on the syntax %var_name%. Remember - to initialize a tcl variable with the same name on some line above the text.
- If the text is in a tcl file you must replace variable lookups - (occurences of $var_name or ${var_name}) with %var_name%
- You are now ready to follow the normal procedure and mark up the text using a + to initialize a tcl variable with the same name on some line above the text.
- If the text is in a tcl file you must replace variable lookups + (occurences of $var_name or ${var_name}) with %var_name%
- You are now ready to follow the normal procedure and mark up the text using a tempoarary message tag (<#_ text_with_percentage_vars#>) and run the action replace tags with keys in the APM.
The variable values in the message are usually fetched with upvar, here is an example from dotlrn: - - ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] - must have <em>no</em>[parameter::get -parameter class_instances_pretty_plural] to be deleted" - + + ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] + must have <em>no</em>[parameter::get -parameter class_instances_pretty_plural] to be deleted" + was replaced by: - + set subject [parameter::get -localize -parameter classes_pretty_name] set class_instances [parameter::get -localize -parameter class_instances_pretty_plural] ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted] -+
This kind of interpolation also works in adp files where adp variable values will be inserted into the message.
Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes:
```
-set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
+set msg_subst_list [list subject [parameter::get -localize -parameter classes_pretty_name] class_instances [parameter::get -localize -parameter class_instances_pretty_plural]]
 
 ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted $msg_subst_list]
-
+
 
```
When we were done going through the tcl files we ran the following commands to check for mistakes:
```
 # Message tags should usually not be in curly braces since then the message lookup may not be
 # executed then (you can usually replace curly braces with the list command). Find message tags 
 # in curly braces (should return nothing, or possibly a few lines for inspection)
-find -iname '*.tcl'|xargs egrep -i '\{.*<#'
+find -iname '*.tcl'|xargs egrep -i '\{.*<#'
 
 # Check if you've forgotten space between default key and text in message tags (should return nothing)
-find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
+find -iname '*.tcl'|xargs egrep -i '<#_[^ ]'
 
 # Review the list of tcl files with no message lookups
-for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
+for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done
 
```
When you feel ready you may vist your package in the - package manager - and run the action "Replace tags with keys - and insert into catalog" on the TCL files that you've edited to + package manager + and run the action "Replace tags with keys + and insert into catalog" on the TCL files that you've edited to replace the temporary tags with calls to the message lookup procedure. -
Dates, Times, and Numbers in TCL files
+
Dates, Times, and Numbers in TCL files
Most date, time, and number variables are calculated in TCL files. Dates and times must be converted when stored in the database, when retrieved from the database, and when displayed. All dates are stored in the database in the server's timezone, which is an APM Parameter set at - /acs-lang/admin/set-system-timezone + /acs-lang/admin/set-system-timezone and readable at - lang::system::timezone.. When + lang::system::timezone.. When retrieved from the database and displayed, dates and times must be localized to the user's locale. -
APM Parameters
+

APM Parameters

Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, you should use message keys using the short notation above, - i.e. #package_key.message_key#. + i.e. #package_key.message_key#.

In order to avoid clashes with other uses of the hash character, you need to tell the APM that the parameter value needs to be localized when retrieving it. You do that by saying: - parameter::get -localize. + parameter::get -localize.

Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package. -

Parameter Name	Parameter Value
class_instance_pages_csv	#dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
departments_pretty_name	#departments_pretty_name#

Parameter Name	Parameter Value
class_instance_pages_csv	#dotlrn.class_page_home_title#,Simple 2-Column;#dotlrn.class_page_calendar_title#,Simple 1-Column;#dotlrn.class_page_file_storage_title#,Simple 1-Column
departments_pretty_name	#departments_pretty_name#

Then, depending on how we retrieve the value, here's what we get: -

Command used to retrieve Value	Retrieved Value
parameter::get -localize -parameter class_instances_pages_csv	Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
parameter::get -localize -parameter departments_pretty_name	Abteilung
parameter::get -parameter departments_pretty_name	#departments_pretty_name#

Command used to retrieve Value	Retrieved Value
parameter::get -localize -parameter class_instances_pages_csv	Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column
parameter::get -localize -parameter departments_pretty_name	Abteilung
parameter::get -parameter departments_pretty_name	#departments_pretty_name#

The value in the rightmost column in the table above is the value returned by an invocation of parameter::get. Note that for localization to happen you must use the -localize flag. @@ -209,5 +209,5 @@ locale.

Developers are responsible for creating the keys in the message - catalog, which is available at /acs-lang/admin/ + catalog, which is available at /acs-lang/admin/

Prev	Home	Next
Internationalization and Localization Overview	Up	How to Internationalize a Package

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-overview.html,v diff -u -N -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/i18n-overview.html 17 Oct 2010 21:06:07 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.html 11 Dec 2010 23:36:32 -0000 1.14 @@ -1,2 +1,2 @@ - -Internationalization and Localization Overview

Prev	Chapter 14. Internationalization	Next

Internationalization and Localization Overview

Table 14.1. Internationalization and Localization Overview

Stage	Task	Who
Internationalization	Package Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information)	Package Developer
Release Management	The newly internationalized package is released.	Package Developer
Release Management	The translation server is updated with the new package.	Translation server maintainers
Localization	Translators work in their respective locales to write text for each message key. (More information)	Translators
Release Management	The translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server.	Translation server maintainers
	The catalog files are committed to the OpenACS code base.	Translation server maintainers
	A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.	Release Manager
Upgrading	Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS	Site Administrators
Upgrading	Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.	Site Administrators

Prev	Home	Next
Chapter 14. Internationalization	Up	How Internationalization/Localization works in OpenACS

docs@openacs.org

View comments on this page at openacs.org + +Internationalization and Localization Overview

Prev	Chapter 13. Internationalization	Next

Internationalization and Localization Overview

Table 13.1. Internationalization and Localization Overview

Stage	Task	Who
Internationalization	Package Developer uses the acs-lang tools to replace all visible text in a package with message keys. (More information)	Package Developer
Release Management	The newly internationalized package is released.	Package Developer
Release Management	The translation server is updated with the new package.	Translation server maintainers
Localization	Translators work in their respective locales to write text for each message key. (More information)	Translators
Release Management	The translated text in the database of the translation server is compared to the current translations in the OpenACS code base, conflicts are resolved, and the new text is written to catalog files on the translation server.	Translation server maintainers
	The catalog files are committed to the OpenACS code base.	Translation server maintainers
	A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.	Release Manager
Upgrading	Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS	Site Administrators
Upgrading	Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.	Site Administrators

Prev	Home	Next
Chapter 13. Internationalization	Up	How Internationalization/Localization works in OpenACS

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 17 Oct 2010 21:06:07 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 11 Dec 2010 23:36:32 -0000 1.24 @@ -1,19 +1,19 @@ - -OpenACS Internationalization Requirements

Prev	Chapter 15. Kernel Documentation	Next

OpenACS Internationalization Requirements

by Henry Minsky, - Yon Feldman, - Lars Pind, - Peter Marklund, - Christian Hvid, + +OpenACS Internationalization Requirements

Prev	Chapter 14. Kernel Documentation	Next

OpenACS Internationalization Requirements

by Henry Minsky, + Yon Feldman, + Lars Pind, + Peter Marklund, + Christian Hvid, and others.

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

Introduction

This document describes the requirements for functionality in the OpenACS platform to support globalization of the core and optional modules. The goal is to make it possible to support delivery of applications which work properly in multiple locales with the lowest development and maintenance cost. -

Definitions

internationalization (i18n): +

Definitions

internationalization (i18n): The provision within a computer program of the capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets. @@ -28,8 +28,8 @@ A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization. -

Vision Statement

The Mozilla project suggests keeping two catchy phrases in -mind when thinking about globalization:

One code base for the world
English is just another language

Building an application often involves making a number of +

Vision Statement

The Mozilla project suggests keeping two catchy phrases in +mind when thinking about globalization:

One code base for the world
English is just another language

Building an application often involves making a number of assumptions on the part of the developers which depend on their own culture. These include constant strings in the user interface and system error messages, names of countries, cities, order of given @@ -44,21 +44,21 @@ kind of globalization support would be large and ongoing, since without a mechanism to incorporate the locale-specific changes cleanly back into the code base, it would require making a new fork -of the source code for each locale.

System/Application Overview

A globalized application will perform some or all of the +of the source code for each locale.

System/Application Overview

A globalized application will perform some or all of the following steps to handle a page request for a specific -locale:

Decide what the target locale is for an incoming page -request
Decide which character set encoding the output should be -delivered in
If a script file to handle the request needs to be loaded +locale:
1. Decide what the target locale is for an incoming page +request
2. Decide which character set encoding the output should be +delivered in
3. If a script file to handle the request needs to be loaded from disk, determine if a character set conversion needs to be -performed when loading the script
4. If needed, locale-specific resources are fetched. These can +performed when loading the script
5. If needed, locale-specific resources are fetched. These can include text, graphics, or other resources that would vary with the -target locale.
6. If content data is fetched from the database, check for -locale-specific versions of the data (e.g. country names).
7. Source code should use a message catalog API to translate -constant strings in the code to the target locale
8. Perform locale-specific linguistic sorting on data if -needed
9. If the user submitted form input data, decide what character +target locale.
10. If content data is fetched from the database, check for +locale-specific versions of the data (e.g. country names).
11. Source code should use a message catalog API to translate +constant strings in the code to the target locale
12. Perform locale-specific linguistic sorting on data if +needed
13. If the user submitted form input data, decide what character set encoding conversion if any is needed. Parse locale-specific -quantities if needed (number formats, date formats).
14. If templating is being used, select correct locale-specific -template to merge with content
15. Format output data quantities in locale-specific manner +quantities if needed (number formats, date formats).
16. If templating is being used, select correct locale-specific +template to merge with content
17. Format output data quantities in locale-specific manner (date, time, numeric, currency). If templating is being used, this may be done either before and/or after merging the data with a template.
Since the internationalization APIs may potentially be used @@ -69,68 +69,68 @@ Java which we will want to move to. So the design to meet the requirements will tend to rely on these capabilities, or close approximations to them where possible, in order to make it easier -to maintain Tcl and Java OpenACS versions.

Use-cases and User-scenarios

Here are the cases that we need to be able to handle -efficiently:

A developer needs to author a web site/application in a +to maintain Tcl and Java OpenACS versions.

Use-cases and User-scenarios

Here are the cases that we need to be able to handle +efficiently:

A developer needs to author a web site/application in a language besides English, and possibly a character set besides ISO-8859-1. This includes the operation of the OpenACS itself, i.e., navigation, admin pages for modules, error messages, as well as additional modules or content supplied by the web site developer.
What do they need to modify to make this work? Can their localization work be easily folded in to future releases of -OpenACS?
A developer needs to author a web site which operates in +OpenACS?
A developer needs to author a web site which operates in multiple languages simultaneously. For example, www.un.org with content and navigation in multiple languages.
The site would have an end-user visible UI to support these languages, and the content management system must allow articles to be posted in these languages. In some cases it may be necessary to make the modules' admin UI's operate in more than one supported language, while in other cases the backend admin -interface can operate in a single language.
A developer is writing a new module, and wants to make it +interface can operate in a single language.
A developer is writing a new module, and wants to make it easy for someone to localize it. There should be a clear path to author the module so that future developers can easily add support for other locales. This would include support for creating resources such as message catalogs, non-text assets such as graphics, and use of templates which help to separate application -logic from presentation.

Competitive -Analysis

Other application servers: ATG Dyanmo, Broadvision, Vignette, -... ? Anyone know how they deal with i18n ?

Related -Links

System/Package "coversheet" - where all -documentation for this software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one -document
LI18NUX +logic from presentation.

Competitive +Analysis

Other application servers: ATG Dyanmo, Broadvision, Vignette, +... ? Anyone know how they deal with i18n ?

Related +Links

System/Package "coversheet" - where all +documentation for this software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one +document
LI18NUX 2000 Globalization Specification: -http://www.li18nux.net/
Mozilla +http://www.li18nux.net/
Mozilla i18N Guidelines: -http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html
ISO +http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html
ISO 639:1988 Code for the representation of names of languages -http://sunsite.berkeley.edu/amher/iso_639.html
ISO 3166-1:1997 +http://sunsite.berkeley.edu/amher/iso_639.html
ISO 3166-1:1997 Codes for the representation of names of countries and their subdivisions Part 1: Country codes -http://www.niso.org/3166.html
IANA -Registry of Character Sets
Test plan
Competitive system(s)

Requirements

Because the requirements for globalization affect many areas +http://www.niso.org/3166.html

IANA +Registry of Character Sets

Test plan

Competitive system(s)

Requirements

Because the requirements for globalization affect many areas of the system, we will break up the requirements into phases, with a base required set of features, and then stages of increasing -functionality.

Locales

10.0

A standard representation of locale will be used throughout +functionality.

Locales

10.0

A standard representation of locale will be used throughout the system. A locale refers to a language and territory, and is uniquely identified by a combination of ISO language and ISO country abbreviations.

See -Content +Content Repository Requirement 100.20
10.10 Provide a consistent representation and API for creating and referencing a locale
10.20 There will be a Tcl library of locale-aware formatting and parsing functions for numbers, dates and times. Note that Java has builtin support for these already.
10.30 For each locale there will be -default date, number and currency formats. Currency i18n is -NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their -servers to use new locales via the APM. NOT IMPLEMENTED in +default date, number and currency formats. Currency i18n is +NOT IMPLEMENTED for 5.0.0.
10.40Administrators can upgrade their +servers to use new locales via the APM. NOT IMPLEMENTED in 5.0.0; current workaround is to get an xml file and load it -manually.

Associating a Locale with a Request

20.0

The request processor must have a mechanism for associating a +manually.

Associating a Locale with a Request

20.0

The request processor must have a mechanism for associating a locale with each request. This locale is then used to select the appropriate template for a request, and will also be passed as the locale argument to the message catalog or locale-specific formatting functions.

20.10 The locale for a request should be computed by the following method, in descending order of -priority:
get locale associated with subsite or package id
get locale from user preference
get locale from site wide default
20.20 An API will be provided for +priority:
get locale associated with subsite or package id
get locale from user preference
get locale from site wide default
20.20 An API will be provided for getting the current request locale from the -ad_conn structure.

Resource Bundles / Content Repository

30.0

A mechanism must be provided for a developer to group a set +ad_conn structure.

Resource Bundles / Content Repository

30.0

A mechanism must be provided for a developer to group a set of arbitrary content resources together, keyed by a unique identifier and a locale.

For example, what approaches could be used to implement a localizable nav-bar mechanism for a site? A navigation bar might be @@ -142,7 +142,7 @@ functionality might include using templates, Java ResourceBundles, content-item containers in the Content Repository, or some convention assigning a common prefix to key strings in the message -catalog.

Message Catalog for String Translation

40.0

A message catalog facility will provide a database of +catalog.

Message Catalog for String Translation

40.0

A message catalog facility will provide a database of translations for constant strings for multilingual applications. It must support the following:

40.10 Each message will referenced via unique a key.
40.20 The key for a message will have @@ -167,7 +167,7 @@ is modified, the other translations of that string can be flagged as needing update.
40.90 The message lookup must be as efficient as possible so as not to slow down the delivery of -pages.

Character Set Encoding

Character Sets

50.0 A locale will have a primary +pages.

Character Set Encoding

Character Sets

50.0 A locale will have a primary associated character set which is used to encode text in the language. When given a locale, we can query the system for the associated character set to use.

The assumption is that we are going to use Unicode in our @@ -177,12 +177,12 @@ browsers and authoring tools, the system must be able to read and write other character sets. In particular, conversions to and from Unicode will need to be explicitly performed at the following -times:

Loading source files (.tcl or .adp) or content files from the -filesystem
Accepting form input data from users
Delivering text output to a browser
Composing an email message
Writing data to the filesystem

Acs-templating does the following.

When the acs-templating package opens an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. -Writing Files
When the acs-templating package writes an an ADP or +times:
- Loading source files (.tcl or .adp) or content files from the +filesystem
- Accepting form input data from users
- Delivering text output to a browser
- Composing an email message
- Writing data to the filesystem
Acs-templating does the following.
- When the acs-templating package opens an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. +Writing Files
- When the acs-templating package writes an an ADP or TCL file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, - then acs-templating assumes it's that charset.
Tcl Source File Character Set
There are two classes of Tcl files loaded by the system; + then acs-templating assumes it's that charset.

Tcl Source File Character Set

There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, which are run on each page request.
Should we require all Tcl files be stored as UTF8? That seems too much of a burden on developers.
50.10 Tcl library files can be authored @@ -191,31 +191,31 @@ filename.
50.20 Tcl page script files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from - the filename.

Submitted Form Data Character Set

50.30 Data which is submitted with a + the filename.

Submitted Form Data Character Set

50.30 Data which is submitted with a HTTP request using a GET or POST method may be in any character set. The system must be able to determine the encoding of the form data and convert it to Unicode on demand.

50.35 The developer must be able to override the default system choice of character set when parsing - and validating user form data. INCOMPLETE - form + and validating user form data. INCOMPLETE - form widgets in acs-templating/tcl/date-procs.tcl are not internationalized. Also, acs-templating's UI needs to be internationalized by replacing all user-visible strings with - message keys.

50.30.10In Japan and some + message keys.

50.30.10In Japan and some other Asian languages where there are multiple character set encodings in common use, the server may need to attempt to do an auto-detection of the character set, because buggy browsers may - submit form data in an unexpected alternate encoding.

Output Character Set

50.40 The output character set for a + submit form data in an unexpected alternate encoding.

Output Character Set

50.40 The output character set for a page request will be determined by default by the locale associated with the request (see requirement 20.0).
50.50 It must be possible for a developer to manually override the output character set encoding for a request using an API function. -

ACS Kernel Issues

60.10 All OpenACS error messages must use +

ACS Kernel Issues

60.10 All OpenACS error messages must use the message catalog and the request locale to generate error -message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as +message for the appropriate locale.NOT IMPLEMENTED for 5.0.0.
60.20 Web server error messages such as 404, 500, etc must also be delivered in the appropriate locale.
60.30 Where files are written or read from disk, their filenames must use a character set and character -values which are safe for the underlying operating system.

Templates

70.0 For a given abstract URL, the +values which are safe for the underlying operating system.

Templates

70.0 For a given abstract URL, the designer may create multiple locale-specific template files may be created (one per locale or language)
70.10 For a given page request, the system must be able to select an approprate locale-specific @@ -226,28 +226,28 @@ current request locale.
70.30 A template file may be created in any character set. The system must have a way to know which character set a template file contains, so it can properly process -it.

Formatting -Datasource Output in Templates

70.50 The properties of a datasource +it.

Formatting +Datasource Output in Templates

70.50 The properties of a datasource column may include a datatype so that the templating system can format the output for the current locale. The datatype is defined by a standard OpenACS datatype plus a format token or format string, for example: a date column might be specified as 'current_date:date LONG,' or 'current_date:date -"YYYY-Mon-DD"'

Forms

70.60 The forms API must support +"YYYY-Mon-DD"'

Forms

70.60 The forms API must support construction of locale-specific HTML form widgets, such as date entry widgets, and form validation of user input data for locale-specific data, such as dates or numbers. NOT IMPLEMENTED in 5.0.0.
70.70 For forms which allow users to upload files, a standard method for a user to indicate the charset of a text file being uploaded must be provided.
Design note: this presumably applies to uploading -data to the content repository as well

Sorting and Searching

80.10 Support API for correct collation +data to the content repository as well

Sorting and Searching

80.10 Support API for correct collation (sorting order) on lists of strings in locale-dependent way.
80.20 For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a -given locale with ORDER BY clauses in +given locale with ORDER BY clauses in queries.
80.40 The system must handle full-text -search in any supported language.

Time Zones

90.10 Provide API support for specifying +search in any supported language.

Time Zones

90.10 Provide API support for specifying a time zone
90.20 Provide an API for computing time and date operations which are aware of timezones. So for example a calendar module can properly synchronize items inserted into a @@ -258,29 +258,29 @@ zone preference should be attached via a session or else UTC should be used to display every date and time.
90.60 The default if we can't determine a time zone is to display all dates and times in some -universal time zone such as GMT.

Database

100.10 Since UTF8 strings can use up to +universal time zone such as GMT.

Database

100.10 Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that column size declarations in the schema are large enough to accomodate required data (such as email addresses in -Japanese). Since 5.0.0, this is covered in the database -install instructions for both PostgreSQL and Oracle.

Email and Messaging

When sending an email message, just as when delivering the +Japanese). Since 5.0.0, this is covered in the database +install instructions for both PostgreSQL and Oracle.

Email and Messaging

When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be able to specify what character set encoding to use, defaulting to UTF-8.

110.10 The email message sending API will allow for a character set encoding to be specified.
110.20 The email accepting API allows for character set to be parsed correctly (the message has a MIME - character set content type header)

Mail is not internationalized. The following issues must be addressed.

+ character set content type header)

Mail is not internationalized. The following issues must be addressed.

Many functions still call ns_sendmail. This means that there are different end points for sending mail. This should be changed to use the acs-mail-lite API instead. -
+
Consumers of email services must do the following: Determine the appropriate language or languages to use for the message subject and message body and localize them (as in notifications). -
Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?
Incoming mail should be localized.

Implementation Notes

Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?

Incoming mail should be localized.

Implementation Notes

Because globalization touches many different parts of the system, we want to reduce the implementation risk by breaking the implementation into phases. -

Revision History

Document Revision # Action Taken, Notes When? By Whom?

1 Updated with results of MIT-sponsored i18n work at Collaboraid. 14 Aug 2003 Joel Aufrecht

0.4

converting from HTML to DocBook and importing the document to the OpenACS +

Revision History

Document Revision #	Action Taken, Notes	When?	By Whom?
1	Updated with results of MIT-sponsored i18n work at Collaboraid.	14 Aug 2003	Joel Aufrecht
0.4	converting from HTML to DocBook and importing the document to the OpenACS kernel documents. This was done as a part of the internationalization of OpenACS and .LRN for the Heidelberg University in Germany	12 September 2002	Peter Marklund
0.3	comments from Christian	1/14/2000	Henry Minsky
0.2	Minor typos fixed, clarifications to wording	11/14/2000	Henry Minsky
0.1	Creation	11/08/2000	Henry Minsky

Prev	Home	Next
Database Access API	Up	Security Requirements

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n-translators.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-translators.html,v diff -u -N -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/i18n-translators.html 17 Oct 2010 21:06:07 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.html 11 Dec 2010 23:36:32 -0000 1.14 @@ -1,2 +1,2 @@ - -Translator's Guide

Prev	Chapter 14. Internationalization	Next

Translator's Guide

Most translators use the OpenACS Public Translation Server, because the process of getting new message keys onto the server and getting new translations back into the distribution are handled by the maintainers of that machine. You can also do translation work on your own OpenACS site; this makes your own translations more readily available to you but also means that your work will not be shared with other users unless you take extra steps (contacting an OpenACS core developer or submitting a patch) to get your work back to the OpenACS core.

The basic steps for translators:

Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
Translating with Translator Mode. To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
While in Translator mode, a list of all message keys appears at the bottom of each page.
Batch translation. To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.

When creating a new locale based on an existing one, such as creating the Guatamalan version of Spanish, you can copy the existing locale's catalog files using the script /packages/acs-core-docs/www/files/create-new-catalog.sh.

Prev	Home	Next
Design Notes	Up	Part IV. For OpenACS Platform Developers

docs@openacs.org

View comments on this page at openacs.org + +Translator's Guide

Prev	Chapter 13. Internationalization	Next

Translator's Guide

The basic steps for translators:

Go to the Localization page and choose the locale that you are translating to. If the locale is not present you need to visit Administration of Localization and create the locale.
Translating with Translator Mode. To translate messages in the pages they appear, Toggle Translator Mode and then browse to the page you want to translate. Untranslated messages will have a yellow background and a red star that you click to translate the message. Translated messages have a green star next to them that is a hyperlink to editing your translation. There is a history mechanism that allows you to see previous translations in case you would want to revert a translation.
While in Translator mode, a list of all message keys appears at the bottom of each page.
Batch translation. To translate many messages at once, go to Administration of Localization, click on the locale to translate, then click on a package, and then click Batch edit these messages.

Prev	Home	Next
Design Notes	Up	Appendix D. Using CVS with an OpenACS Site

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/i18n.html 17 Oct 2010 21:06:07 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/i18n.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,7 +1,7 @@ - -Chapter 14. Internationalization

Prev	Part III. For OpenACS Package Developers	Next

Chapter 14. Internationalization

Table of Contents

Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide

- By Peter Marklund - and Lars Pind + +Chapter 13. Internationalization

Prev	Part III. For OpenACS Package Developers	Next

Chapter 13. Internationalization

Table of Contents

Internationalization and Localization Overview
How Internationalization/Localization works in OpenACS
How to Internationalize a Package
Design Notes
Translator's Guide

+ By Peter Marklund + and Lars Pind

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -N -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/index.html 17 Oct 2010 21:06:07 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/index.html 11 Dec 2010 23:36:32 -0000 1.51 @@ -1,2 +1,4 @@ - -OpenACS Core Documentation

		Next

OpenACS Core Documentation

Table of Contents

I. OpenACS For Everyone

1. High level information: What is OpenACS?

Overview
OpenACS Release Notes

II. Administrator's Guide

2. Installation Overview

Basic Steps
Prerequisite Software

3. Complete Installation

Install a Unix-like system and supporting software
Install Oracle 8.1.7
Install PostgreSQL
Install AOLserver 4
Install OpenACS 5.6.0
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X

4. Configuring a new OpenACS Site

Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?

5. Upgrading

Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
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 using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1

C. Credits

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
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics

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 Form Builder: building html forms dynamically

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

IV. For OpenACS Platform Developers

15. Kernel Documentation

Overview
Object Model Requirements
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
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
11.1. Server file layout diagram
11.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
10.1. table showing ETP layout
11.1. Package files
11.2. Context Hierarchy Example
11.3. 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

		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.6.0
OpenACS Installation Guide for Windows2000
OpenACS Installation Guide for Mac OS X

4. Configuring a new OpenACS Site

Installing OpenACS packages
Mounting OpenACS packages
Configuring an OpenACS package
Setting Permissions on an OpenACS package
How Do I?

5. Upgrading

Overview
Upgrading 4.5 or higher to 4.6.3
Upgrading OpenACS 4.6.3 to 5.0
Upgrading an OpenACS 5.0.0 or greater installation
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

A. Install Red Hat 8/9

B. Install additional supporting software

Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1

C. Credits

Where did this document come from?
Linux Install Guides
Security Information
Resources

III. For OpenACS Package Developers

8. Development Tutorial

Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing

9. Advanced Topics

Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics

10. Development Reference

OpenACS Packages
OpenACS Data Models and the Object System
The Request Processor
The OpenACS Database Access API
Using Templates in OpenACS
Groups, Context, Permissions
Writing OpenACS Application Pages
Parties in OpenACS
Object Identity
Programming with AOLserver
Using Form Builder: building html forms dynamically

11. Engineering Standards

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

12. Documentation Standards

OpenACS Documentation Guide
Using PSGML mode in Emacs
Using nXML mode in Emacs
System/Application Requirements Template

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

14. Kernel Documentation

Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements

15. Releasing OpenACS

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. Assumptions in this section
8.2. Tutorial Data Model
8.3. The Database Creation Script
8.4. Database Deletion Script
8.5. Page Map
9.1. Upgrading a local CVS repository
10.1. Server file layout diagram
10.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
9.1. table showing ETP layout
10.1. Package files
13.1. Internationalization and Localization Overview

List of Examples

11.1. Getting datetime from the database ANSI-style

		Next
		Part I. OpenACS For Everyone

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -N -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 17 Oct 2010 21:06:08 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 11 Dec 2010 23:36:32 -0000 1.31 @@ -1,131 +1,131 @@ - -Prerequisite Software

Prev	Chapter 2. Installation Overview	Next

Prerequisite Software

by Joel Aufrecht

+ +Prerequisite Software

Prev	Chapter 2. Installation Overview	Next

Prerequisite Software

by Joel Aufrecht

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

OpenACS requires, at a minimum, an operating system, database, and webserver to work. Many additional programs, such as a build environment, Mail Transport Agent, and source control system, are also needed for a fully effective installation. -

Table 2.2. Version Compatibility Matrix

OpenACS Version		3.2.5	4.5	4.6.2	4.6.3	5.0	5.1	5.2	5.3	5.5
AOLserver	3	Yes	No
	3.3+ad13	Maybe	Yes					No
	3.3oacs1	Maybe	Yes					No
	3.4.4	No
	3.4.4oacs1	Maybe		Yes		No
	3.5.5	Maybe		Yes		No
	4.0	Maybe		Yes
	4.5	No						Yes
Tcl	8.4	Yes
Tcl	8.5.4 -	Maybe
PostgreSQL	7.0	Yes	No
	7.2	Maybe	Yes			No
	7.3.2 - 7.3.x	No			Yes				No
	7.4	No				Yes			No
	8.0	No					Maybe	Yes
	8.1	No						Yes
	8.2	No						CVS version only	Yes
	8.3	No								Yes
Oracle	8.1.6	Maybe	Yes						Maybe
	8.1.7	Maybe	Yes						Maybe
	9i	No				Yes
	10g	No						Yes
	11g	No								Maybe

The OpenACS installation instructions assume the operating system and build environment are installed. +

Table 2.2. Version Compatibility Matrix

OpenACS Version		3.2.5	4.5	4.6.2	4.6.3	5.0	5.1	5.2	5.3	5.5
AOLserver	3	Yes	No
	3.3+ad13	Maybe	Yes					No
	3.3oacs1	Maybe	Yes					No
	3.4.4	No
	3.4.4oacs1	Maybe		Yes		No
	3.5.5	Maybe		Yes		No
	4.0	Maybe		Yes
	4.5	No						Yes
Tcl	8.4	Yes
Tcl	8.5.4 -	Maybe
PostgreSQL	7.0	Yes	No
	7.2	Maybe	Yes			No
	7.3.2 - 7.3.x	No			Yes				No
	7.4	No				Yes			No
	8.0	No					Maybe	Yes
	8.1	No						Yes
	8.2	No						CVS version only	Yes
	8.3	No								Yes
Oracle	8.1.6	Maybe	Yes						Maybe
	8.1.7	Maybe	Yes						Maybe
	9i	No				Yes
	10g	No						Yes
	11g	No								Maybe

The OpenACS installation instructions assume the operating system and build environment are installed. The instructions explain installation of TCL, Tcllib, tDOM, tclwebtest, a Web Server, a Database, a Process Controller, and Source Control software. The following external links are for reference only. -

OpenACS 5.6.0. The OpenACS tarball comprises the core packages and +

OpenACS 5.6.0. The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL - and Oracle. Some scripts require bash shell.
Operating System. OpenACS is designed for a Unix-like system. It is + and Oracle. Some scripts require bash shell.
Operating System. OpenACS is designed for a Unix-like system. It is developed primarily in Linux. It can be run on Mac OS X, - and in Windows within VMWare.
- GNU/Linux. The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
- FreeBSD. FreeBSD guide. The OpenACS Reference Platform uses shell scripts written for bash, which is the + and in Windows within VMWare.
  - GNU/Linux. The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.
  - FreeBSD. FreeBSD guide. The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different shell, you will need to substitute your shell's conventions for setting environment variables when - appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use - wget to download software.
  - Mac OS X. Section , “OpenACS Installation Guide for Mac OS X”
  - Windows/VMWare. Section , “OpenACS Installation Guide for Windows2000” The only + appropriate, and install bash to work with the scripts. Substitute fetch when the instructions suggest you use + wget to download software.
  - Mac OS X. OpenACS Installation Guide for Mac OS X
  - Windows/VMWare. OpenACS Installation Guide for Windows2000 The only way to run OpenACS on Windows is through the VMWare emulator. (Please let me know if you have OpenACS - running directly in Windows.)
- Build Environment. The Reference Platform installation compiles most programs from - source code.
  - glibc 2.2 or newer, REQUIRED. You need recent versions of these libraries for + running directly in Windows.)
- Build Environment. The Reference Platform installation compiles most programs from + source code.
  - glibc 2.2 or newer, REQUIRED. You need recent versions of these libraries for Oracle to work properly. For Unicode support, you need glibc 2.2 or newer. This should be included in your - operating system distribution.
  - GNU Make 3.76.1 or newer, REQUIRED. PostgreSQL and AOLserver require gmake to + operating system distribution.
  - GNU Make 3.76.1 or newer, REQUIRED. PostgreSQL and AOLserver require gmake to compile. Note that on most linux distributions, GNU Make is simply named - make and + make and there is no - gmake, + gmake, whereas on BSD distributions, - make and - gmake are - different --use gmake.
- TCL 8.4.x.
  - TCL 8.4.x, REQUIRED. OpenACS is written in TCL, an interpreted + make and + gmake are + different --use gmake.
- TCL 8.4.x.
  - TCL 8.4.x, REQUIRED. OpenACS is written in TCL, an interpreted language. A threaded version of the TCL interpreter must be installed for OpenACS to work. The TCL interpreter that is included in most standard - distributions may not be thread safe.
  - TCL 8.4.x development headers and libraries, OPTIONAL. The site-wide-search service, OpenFTS, requires these to - compile. (Debian users: apt-get install - tcl8.4-dev). You need this - to install OpenFTS.
- Tcllib, REQUIRED. + distributions may not be thread safe.
- TCL 8.4.x development headers and libraries, OPTIONAL. The site-wide-search service, OpenFTS, requires these to + compile. (Debian users: apt-get install + tcl8.4-dev). You need this + to install OpenFTS.
Tcllib, REQUIRED. OpenACS 5.6.0 uses those Tcl extensions to send e-mail out, among others. -
tDOM, REQUIRED. OpenACS 5.6.0 stores +
tDOM, REQUIRED. OpenACS 5.6.0 stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which - was used prior to 4.6.4.)
tclwebtest, OPTIONAL. tclwebtest is a tool for testing web interfaces via tcl scripts.
Web Server. The web server handles incoming HTTP requests, provides + was used prior to 4.6.4.)
tclwebtest, OPTIONAL. tclwebtest is a tool for testing web interfaces via tcl scripts.
Web Server. The web server handles incoming HTTP requests, provides a runtime environment for OpenACS's tcl code, connects to the database, sends out HTTP responses, and logs requests and errors. OpenACS uses AOLserver; - some people have had success running Apache with mod_nsd.
- AOLserver 4.x, REQUIRED. Provides the base HTTP server
+ some people have had success running Apache with mod_nsd.
- AOLserver 4.x, REQUIRED. Provides the base HTTP server
Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS 5.6.0. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and - perhaps more to come), currently located at uptime.openacs.org. + perhaps more to come), currently located at uptime.openacs.org.
It's also possible to download all the pieces and patches yourself: -
- - AOLserver is available at aolserver.com -
- +
  - + AOLserver is available at aolserver.com +
  - The OpenACS PostgreSQL driver (nspostgres.so) is available from - SourceForge. If + SourceForge. If you do decide to use nspostgres.so, you have to remember to change the AOLserver config file to point to nspostgres.so instead of postgres.so. This guide uses Mat Kovach's distro (i.e. postgres.so) -
  - - The patch that makes exec work - on BSD is available at sourceforge.net -
  - - The patch for aolserver 3.x that makes ns_uuencode - work for binary files is available at sourceforge.net -
  - +
  - + The patch that makes exec work + on BSD is available at sourceforge.net +
  - + The patch for aolserver 3.x that makes ns_uuencode + work for binary files is available at sourceforge.net +
  - The patch that makes AOLserver 3.x respect the - -g flag is available at - sourceforge.net -
- nsopenssl, OPTIONAL. Provides SSL capabilities for AOLserver. It requires + -g flag is available at + sourceforge.net +
nsopenssl, OPTIONAL. Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make secure (https) connections to your webserver. - aolserver3.x requires nsopenssl 2.1a. aolserver4.x requires nsopenssl3; see - aolserver.com for latest release. (home page) -
ns_pam 0.1 or newer, OPTIONAL. Provides PAM capabilities for AOLserver. You + aolserver3.x requires nsopenssl 2.1a. aolserver4.x requires nsopenssl3; see + aolserver.com for latest release. (home page) +
ns_pam 0.1 or newer, OPTIONAL. Provides PAM capabilities for AOLserver. You need this if you want OpenACS users to authenticate - through a PAM module (such as RADIUS).
pam_radius 1.3.16, OPTIONAL. Provides RADIUS capabilities for PAM. You need - this if you want to use RADIUS authentication via PAM in OpenACS.
ns_ldap 0.r8, OPTIONAL. Provides LDAP capabilities for AOLserver. You need - this if you want to use LDAP authentication in OpenACS.
OpenFTS + through a PAM module (such as RADIUS).
pam_radius 1.3.16, OPTIONAL. Provides RADIUS capabilities for PAM. You need + this if you want to use RADIUS authentication via PAM in OpenACS.
ns_ldap 0.r8, OPTIONAL. Provides LDAP capabilities for AOLserver. You need + this if you want to use LDAP authentication in OpenACS.
OpenFTS TCL 0.3.2, OPTIONAL. Adds full-text-search to PostgreSQL and includes a driver for AOLserver. You need this if you want users to be able to search for any text on your site. For postgres 7.4.x and higher, full text search is also available via tsearch2. -
Analog 5.32 or newer, OPTIONAL. This program examines web server request logs, looks up +
Analog 5.32 or newer, OPTIONAL. This program examines web server request logs, looks up DNS values, and produces a report. You need this if you - want to see how much traffic your site is getting.
Balance 3.11 or newer, OPTIONAL. "Balance is a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system.
Database. The data on your site (for example, user names and passwords, + want to see how much traffic your site is getting.
Balance 3.11 or newer, OPTIONAL. "Balance is a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system.
Database. The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS separates the database with an abstraction layer, which means that several different databases all function identically. While you can run the core OpenACS on any supported database, not all contributed packages support all - databases.
- Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED). You can register and download Oracle from Oracle + databases.
  - Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED). You can register and download Oracle from Oracle TechNet. You need this if you want to use an - Oracle database.
  - PostgreSQL 7.4.x (Either this or Oracle is REQUIRED). You need this if you want to use a PostgreSQL database.
- Process Controller. This is software that initiates other software, and + Oracle database.
- PostgreSQL 7.4.x (Either this or Oracle is REQUIRED). You need this if you want to use a PostgreSQL database.
Process Controller. This is software that initiates other software, and restarts that software if it fails. On Linux, we recommend - using Daemontools to control AOLserver and qmail.
- Daemontools + using Daemontools to control AOLserver and qmail.
  Daemontools 0.76, OPTIONAL. You need this if - you want AOLserver and qmail to run "supervised," + you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. An alternative would be to - run the services from inittab.
- Mail Transport Agent. A Mail Transport Agent is a program that handles all + run the services from inittab.
Mail Transport Agent. A Mail Transport Agent is a program that handles all incoming and outgoing mail. The Reference Platform uses Qmail; any MTA that provides a sendmail wrapper (that is, that can be invoked by calling the sendmail program with the - same variables that sendmail expects) can be used.
- Netqmail 1.04, OPTIONAL. You need this (or a different Mail Transport - Agent) if you want your webserver to send and receive email.
- ucspi-tcp 0.88, OPTIONAL. This program listens for incoming TCP connections and + same variables that sendmail expects) can be used.
  - Netqmail 1.04, OPTIONAL. You need this (or a different Mail Transport + Agent) if you want your webserver to send and receive email.
  - ucspi-tcp 0.88, OPTIONAL. This program listens for incoming TCP connections and hands them to a program. We use it instead of inetd, - which is insecure. You need this if you are running qmail.
- DocBook, OPTIONAL. (docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, + which is insecure. You need this if you are running qmail.
DocBook, OPTIONAL. (docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need this to write or edit documentation. -
Source Control. A Source Control system keeps track of all of the old +
Source Control. A Source Control system keeps track of all of the old versions of your files. It lets you recover old files, compare versions of file, and identify specific versions of files. You can use any source control system; the Reference Platform and the OpenACS.org repository (where you can - get patched and development code in between releases) use cvs.
- cvs 1.11.18, OPTIONAL. cvs is included in most unix distributions. You + get patched and development code in between releases) use cvs.
  - cvs 1.11.18, OPTIONAL. cvs is included in most unix distributions. You need this if you want to track old versions of your files, do controlled deployment of code from development to production, or get or contribute development code from openacs.org.
($Id$)

Prev	Home	Next
Basic Steps	Up	Chapter 3. Complete Installation

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.37 -r1.38 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 17 Oct 2010 21:06:08 -0000 1.37 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 11 Dec 2010 23:36:32 -0000 1.38 @@ -1,7 +1,7 @@ - -Initialize CVS (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Initialize CVS (OPTIONAL)
CVS is a source control system. Create and initialize a - directory for a local cvs repository.
[root tmp]# mkdir /cvsroot -[root tmp]# cvs -d /cvsroot init + +Initialize CVS (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Initialize CVS (OPTIONAL)
CVS is a source control system. Create and initialize a + directory for a local cvs repository.
[root tmp]# mkdir /cvsroot +[root tmp]# cvs -d /cvsroot init [root tmp]# mkdir /cvsroot cvs -d /cvsroot init
Prev Home Next
Unpack the OpenACS tarball Up Add PSGML commands to emacs init file (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v diff -u -N -r1.38 -r1.39 --- openacs-4/packages/acs-core-docs/www/install-daemontools.html 17 Oct 2010 21:06:08 -0000 1.38 +++ openacs-4/packages/acs-core-docs/www/install-daemontools.html 11 Dec 2010 23:36:32 -0000 1.39 @@ -1,15 +1,15 @@ - -Install Daemontools (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Install Daemontools (OPTIONAL)
Daemontools is a collection of programs for controlling + +Install Daemontools (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Install Daemontools (OPTIONAL)
Daemontools is a collection of programs for controlling other processes. We use daemontools to run and monitor AOLserver. It is installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package -[root root]# chmod 1755 /package/ -[root root]# cd /package/ -[root package]# tar xzf /tmp/daemontools-0.76.tar.gz -[root package]# cd admin/daemontools-0.76/ -[root daemontools-0.76]# package/install + services.
Install Daemontools
download daemontools and install it.
Red Hat 8
[root root]# mkdir -p /package +[root root]# chmod 1755 /package/ +[root root]# cd /package/ +[root package]# tar xzf /tmp/daemontools-0.76.tar.gz +[root package]# cd admin/daemontools-0.76/ +[root daemontools-0.76]# package/install Linking ./src/* into ./compile... Creating /service... @@ -21,14 +21,14 @@ cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/install
Red Hat 9, Fedora Core 1-4
Make sure you have the source tarball in - /tmp, or download it. -
[root root]# mkdir -p /package -[root root]# chmod 1755 /package/ -[root root]# cd /package/ -[root package]# tar xzf /tmp/daemontools-0.76.tar.gz -[root package]# cd admin -[root admin]# wget http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch +package/install
Red Hat 9, Fedora Core 1-4
Make sure you have the source tarball in + /tmp, or download it. +
[root root]# mkdir -p /package +[root root]# chmod 1755 /package/ +[root root]# cd /package/ +[root package]# tar xzf /tmp/daemontools-0.76.tar.gz +[root package]# cd admin +[root admin]# wget http://www.qmail.org/moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch --14:19:24-- http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch => `daemontools-0.76.errno.patch' Resolving moni.csi.hu... done. @@ -40,9 +40,9 @@ 14:19:24 (346.68 KB/s) - `daemontools-0.76.errno.patch' saved [355/355] -[root admin]# cd daemontools-0.76 -[root daemontools-0.76]# patch -p1 < ../daemontools-0.76.errno.patch -[root daemontools-0.76]# package/install +[root admin]# cd daemontools-0.76 +[root daemontools-0.76]# patch -p1 < ../daemontools-0.76.errno.patch +[root daemontools-0.76]# package/install Linking ./src/* into ./compile...(many lines omitted) Creating /service... Adding svscanboot to inittab... @@ -56,14 +56,14 @@ wget http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch cd daemontools-0.76 patch -p1 < ../daemontools-0.76.errno.patch -package/install
FreeBSD (follow standard install)
Make sure you have the source tarball in - /tmp, or download it. -
[root root]# mkdir -p /package -[root root]# chmod 1755 /package/ -[root root]# cd /package/ -[root package]# tar xzf /tmp/daemontools-0.76.tar.gz -[root package]# cd admin/daemontools-0.76 -[root daemontools-0.76]# package/install +package/install
FreeBSD (follow standard install)
Make sure you have the source tarball in + /tmp, or download it. +
[root root]# mkdir -p /package +[root root]# chmod 1755 /package/ +[root root]# cd /package/ +[root package]# tar xzf /tmp/daemontools-0.76.tar.gz +[root package]# cd admin/daemontools-0.76 +[root daemontools-0.76]# package/install Linking ./src/* into ./compile...(many lines omitted) Creating /service... Adding svscanboot to inittab... @@ -74,13 +74,13 @@ cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/install
Debian
[root ~]# apt-get install daemontools-installer -[root ~]# build-daemontools
Verify that svscan is running. If it is, you should see - these two processes running:
[root root]# ps -auxw | grep service +package/install
Debian
[root ~]# apt-get install daemontools-installer +[root ~]# build-daemontools
Verify that svscan is running. If it is, you should see + these two processes running:
[root root]# ps -auxw | grep service root 13294 0.0 0.1 1352 272 ? S 09:51 0:00 svscan /service root 13295 0.0 0.0 1304 208 ? S 09:51 0:00 readproctitle service errors: ....................................... -[root root]#
Install a script to grant non-root users permission to - control daemontools services.
[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup -[root root]# chmod 755 /usr/local/bin/svgroup +[root root]#
Install a script to grant non-root users permission to + control daemontools services.
[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup +[root root]# chmod 755 /usr/local/bin/svgroup cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup chmod 755 /usr/local/bin/svgroup
Prev Home Next
Add PSGML commands to emacs init file (OPTIONAL) Up Install qmail (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html 17 Oct 2010 21:06:08 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-openfts.html 11 Dec 2010 23:36:32 -0000 1.9 @@ -1,56 +1,56 @@ - -Install Full Text Search using OpenFTS (deprecated see tsearch2)
Prev Appendix B. Install additional supporting software Next
Install Full Text Search using OpenFTS (deprecated see tsearch2)
By Joel Aufrecht and Malte Sussdorff
+ +Install Full Text Search using OpenFTS (deprecated see tsearch2)
Prev Appendix B. Install additional supporting software Next
Install Full Text Search using OpenFTS (deprecated see tsearch2)
By Joel Aufrecht and Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
OpenFTS and tsearch1 use is deprecated in favor of Tsearch2. See - Install Full Text Search using Tsearch2. Tsearch2 is much easier to install, requiring only + Install Full Text Search using Tsearch2. Tsearch2 is much easier to install, requiring only compilation of one module from PostgreSQL contrib, with an - automated install process using the tsearch2-driver package.
Install OpenFTS module
If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and - AOLserver. You will need the openfts - tarball in /tmp.
Install Tsearch. This is a PostgreSQL module that - OpenFTS requires.
[root root]# su - postgres -[postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/ -[postgres tsearch]$ make + automated install process using the tsearch2-driver package.
Install OpenFTS module
If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and + AOLserver. You will need the openfts + tarball in /tmp.
Install Tsearch. This is a PostgreSQL module that + OpenFTS requires.
[root root]# su - postgres +[postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/ +[postgres tsearch]$ make sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql /usr/bin/flex -8 -Ptsearch_yy -o'parser.c' parser.l(many lines omitted) rm -f libtsearch.so ln -s libtsearch.so.0.0 libtsearch.so -[postgres tsearch]$ make install +[postgres tsearch]$ make install mkdir /usr/local/pgsql/share/contrib mkdir /usr/local/pgsql/doc/contrib (2 lines omitted) /bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so -[postgres tsearch]$ exit +[postgres tsearch]$ exit logout [root root]# su - postgres cd /usr/local/src/postgresql-7.3.4/contrib/tsearch make make install -exit
Unpack the OpenFTS tarball and compile and install - the driver.
[root root]# cd /usr/local/src -[root src]# tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz -[root src]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ -[root Search-OpenFTS-tcl-0.3.2]# ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/ +exit
Unpack the OpenFTS tarball and compile and install + the driver.
[root root]# cd /usr/local/src +[root src]# tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz +[root src]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ +[root Search-OpenFTS-tcl-0.3.2]# ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/ checking prefix... /usr/local checking for gcc... gcc (many lines omitted) configure: creating ./config.status config.status: creating Makefile.global -[root Search-OpenFTS-tcl-0.3.2]# make +[root Search-OpenFTS-tcl-0.3.2]# make (cd parser; make all) make[1]: Entering directory `/usr/local/src/Search-OpenFTS-tcl-0.3.2/parser' (many lines omitted) packages provided were {Lingua::Stem::Snowball 0.3.2} processed fts_base_snowball.tcl -[root Search-OpenFTS-tcl-0.3.2]# cd aolserver -[root aolserver]# make -gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR +[root Search-OpenFTS-tcl-0.3.2]# cd aolserver +[root aolserver]# make +gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR (many lines omitted) n_stem.o italian_stem.o norwegian_stem.o portuguese_stem.o russian_stem.o nsfts.o -o nsfts.so -[root aolserver]# cp nsfts.so /usr/local/aolserver/bin/ +[root aolserver]# cp nsfts.so /usr/local/aolserver/bin/ [root aolserver]# cd /usr/local/src tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz @@ -60,75 +60,75 @@ cd aolserver make cp nsfts.so /usr/local/aolserver/bin -
Build some supplemental modules.
[root aolserver]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2 -[root Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib -[root Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts -[root pgsql_contrib_openfts]# make +
Build some supplemental modules.
[root aolserver]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2 +[root Search-OpenFTS-tcl-0.3.2]# cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib +[root Search-OpenFTS-tcl-0.3.2]# cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts +[root pgsql_contrib_openfts]# make sed 's,MODULE_PATHNAME,$libdir/openfts,g' openfts.sql.in >openfts.sql gcc -O2 -Wall -Wmissing-prototypes -Wmissing-declarations -fpic -I. -I../../src/include -c -o openfts.o openfts.c gcc -shared -o openfts.so openfts.o rm openfts.o -[root pgsql_contrib_openfts]# su postgres -[postgres pgsql_contrib_openfts]$ make install +[root pgsql_contrib_openfts]# su postgres +[postgres pgsql_contrib_openfts]$ make install /bin/sh ../../config/install-sh -c -m 644 openfts.sql /usr/local/pgsql/share/contrib /bin/sh ../../config/install-sh -c -m 755 openfts.so /usr/local/pgsql/lib /bin/sh ../../config/install-sh -c -m 644 ./README.openfts /usr/local/pgsql/doc/contrib -[postgres pgsql_contrib_openfts]$ exit +[postgres pgsql_contrib_openfts]$ exit [root pgsql_contrib_openfts]# cd /usr/local/src/Search-OpenFTS-tcl-0.3.2 cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts make su postgres make install -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 + to work, you must also install the PostgreSQL + OpenFTS module and prerequisites.)
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql BEGIN CREATE (many lines omitted) INSERT 0 1 COMMIT -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql CREATE CREATE [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql -/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql
Note
+/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql
Note
If you get the error - ERROR: could not access file "$libdir/tsearch": no such file or directory + ERROR: could not access file "$libdir/tsearch": no such file or directory It is probably because PostgreSQL's libdir configuration variable points to a diffent directory than where tsearch is. You can find out where PostgreSQL expects to find tsearch via -
pg_config --pkglibdir
-
Enable OpenFTS in config.tcl
If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)
#ns_param nsfts ${bindir}/nsfts.so
Install Full Text Search Engine
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install -software link.
Click on the Install -new service link.
Click on the Install link next to OpenFTS Driver.
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the OpenFTS Full Text Search Engine in the site map.
Click the new sub folder link on the "/" line, the first line under Main Site:/.
Type openfts -and click New.
On the new openfts line, click the mount link.
Click OpenFTS -Driver.
On the openfts line, click set parameters.
Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click Set Parameters -
Mount the Search interface in the site map.
Click the -new sub folder link on the -Main Site line.
Type search -and click New.
Click the new -application link on the search - line.
Type search +
pg_config --pkglibdir
+
Enable OpenFTS in config.tcl
If you have installed OpenFTS, you can enable it for this service. Uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.)
#ns_param nsfts ${bindir}/nsfts.so
Install Full Text Search Engine
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +software link.
Click on the Install +new service link.
Click on the Install link next to OpenFTS Driver.
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the OpenFTS Full Text Search Engine in the site map.
Click the new sub folder link on the "/" line, the first line under Main Site:/.
Type openfts +and click New.
On the new openfts line, click the mount link.
Click OpenFTS +Driver.
On the openfts line, click set parameters.
Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click Set Parameters +
Mount the Search interface in the site map.
Click the +new sub folder link on the +Main Site line.
Type search +and click New.
Click the new +application link on the search + line.
Type search where it says -untitled, choose -search from the +untitled, choose +search from the drop-down list, and click -New. -
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then click on Main Site at the top of the page.
Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.
Near the bottom of the page, click on the OpenFTS Driver link. Click on Administration. -Click on Initialize OpenFTS Engine. -Click Initialize OpenFTS Engine.
Add the FTS Engine service contract
Click on the DevAdmin.
Click on the Service Contract link.
On the FtsEngineDriver +New. +
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then click on Main Site at the top of the page.
Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.
Near the bottom of the page, click on the OpenFTS Driver link. Click on Administration. +Click on Initialize OpenFTS Engine. +Click Initialize OpenFTS Engine.
Add the FTS Engine service contract
Click on the DevAdmin.
Click on the Service Contract link.
On the FtsEngineDriver line, click -Install. -
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Enable Full Text Search in packages
Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. -
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install - software link.
Click on the Install - new application link.
Click on the Install link next to Weblogger.
Install all required packages as well (always say okay until you shall restart the server)
-
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql -[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql
Note: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME - [$OPENACS_SERVICE_NAME postgresl]$
If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
Prev Home Next
Install Full Text Search using Tsearch2 Up Install nsopenssl
docs@openacs.org
View comments on this page at openacs.org +Install. +

Restart the service.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME
+[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$

Enable Full Text Search in packages

Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package

Install the package. +
1. Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
2. Click on the Install + software link.
3. Click on the Install + new application link.
4. Click on the Install link next to Weblogger.
5. Install all required packages as well (always say okay until you shall restart the server)
+

Load the service contracts datamodell and enable the service contract

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql
+[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql

Note: Usually this script is called package_name-sc-create.sql

Restart the service.

[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME
+                [$OPENACS_SERVICE_NAME postgresl]$

If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.

Prev	Home	Next
Install Full Text Search using Tsearch2	Up	Install nsopenssl

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 17 Oct 2010 21:06:08 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 11 Dec 2010 23:36:32 -0000 1.9 @@ -1,47 +1,47 @@ - -Install Full Text Search using Tsearch2
Prev Appendix B. Install additional supporting software Next
Install Full Text Search using Tsearch2
By Dave - Bauer, Joel - Aufrecht and Malte Sussdorff with - help from Tsearch + +Install Full Text Search using Tsearch2
Prev Appendix B. Install additional supporting software Next
Install Full Text Search using Tsearch2
By Dave + Bauer, Joel + Aufrecht and Malte Sussdorff with + help from Tsearch V2 Introduction by Andrew J. Kopciuch
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Install Tsearch2 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 Tsearch2 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 tseach2 module form PostgreSQL contrib. This is included with the PostgreSQL full source distribution. It is also available with the PostgreSQL contrib package provided by most distribution packages. On debian it is - called postgresql-contrib.
For PostgreSQL 7.3 or 7.4, download the + called postgresql-contrib.
For PostgreSQL 7.3 or 7.4, download the http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz tsearch2 patch to correctly restore from a pg_dump backup. If you installed tsearch2 from a package, you can use the http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql regprocedure script to update the database after tsearch2 is installed into it. TODO link to section decribing how to fix - an existing tsearch2 database with this patch.
As of May 9, 2004 there is a source patch available + an existing tsearch2 database with this patch.
As of May 9, 2004 there is a source patch available for tsearch2. The patch provides changes to the pg_ts_ configuration tables to allow for easy dump and restore of a database containing - tsearch2. The patch is available here : + tsearch2. The patch is available here : [http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz]
To apply this patch, download the mentioned file and place it in your postgreSQL source tree ($PGSQL_SRC). This patch makes the backup and restore procedures very simple.
- [postgres pgsql]$ cd /tmp - [postgres tmp]$ wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz - [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/ - [postgres postgresql-7.4.5] gunzip /tmp/regprocedure_7.4.patch.gz - [postgres postgresql-7.4.5] patch -b -p1 < regprocedure_7.4.patch + [postgres pgsql]$ cd /tmp + [postgres tmp]$ wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz + [postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/ + [postgres postgresql-7.4.5] gunzip /tmp/regprocedure_7.4.patch.gz + [postgres postgresql-7.4.5] patch -b -p1 < regprocedure_7.4.patch
If you have a working version of tsearch2 in your database, you do not need to re-install the tsearch2 module. Just apply the patch and run make. This patch only affects the tsearch2.sql file. You - can run the SQL script found : + can run the SQL script found : [right here] This script will make the modifications found in the patch, and update the fields from the existing @@ -54,55 +54,55 @@ versions 7.3.x and 7.4.x. The patch has been applied to the sources for - 8.0.
Install Tsearch2. This is a PostgreSQL module + 8.0.
Install Tsearch2. This is a PostgreSQL module that the tsearch2-driver OpenACS package requires. These instructions assume you are using the latest point - release of PostgreSQL 7.4.5.
[root root]# su - postgres -[postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/ -[postgres tsearch2]$ make -[postgres tsearch2]$ make install + release of PostgreSQL 7.4.5.
[root root]# su - postgres +[postgres pgsql]$ cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/ +[postgres tsearch2]$ make +[postgres tsearch2]$ make install mkdir /usr/local/pgsql/share/contrib mkdir /usr/local/pgsql/doc/contrib (2 lines omitted) /bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so -[postgres tsearch]$ exit +[postgres tsearch]$ exit logout [root root]# su - postgres cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2 make make install -exit
Install Full Text Search Engine Package in OpenACS
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install -software link.
Click on the Install -new service link.
Click on the - Install +exit
Install Full Text Search Engine Package in OpenACS
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install +software link.
Click on the Install +new service link.
Click on the + Install link next to Tsearch2 Driver. If you have installed tsearch2 into your PostgreSQL database, the installer will - automatically enable tsearch in your OpenACS database instance.
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the Search interface in the site map.
Click the -new sub folder link on the -Main Site line.
Type search -and click New.
Click the new -application link on the search - line.
Type search + automatically enable tsearch in your OpenACS database instance.
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then browse back to the home page.
Click on Admin on the top of the screen.
Click on Main Site Administration in the "Subsite Administration" section.
Click on Site Map in the "Advanced Features" section.
Mount the Search interface in the site map.
Click the +new sub folder link on the +Main Site line.
Type search +and click New.
Click the new +application link on the search + line.
Type search where it says -untitled, choose -search from the +untitled, choose +search from the drop-down list, and click -New. -
Click the -Parameters link - next to the Search package istance.
Type tsearch2-driver +New. +
Click the +Parameters link + next to the Search package istance.
Type tsearch2-driver where it says -openfts-driver +openfts-driver in the - FtsEngineDriver parameter. -
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then click on Main Site at the top of the page.
Enable Full Text Search in packages
Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. -
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install - software link.
Click on the Install - new application link.
Click on the Install link next to Weblogger.
Install all required packages as well (always say okay until you shall restart the server)
-
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql -[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql
Note: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME - [$OPENACS_SERVICE_NAME postgresl]$
If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
Prev Home Next
Install nspam Up Install Full Text Search using OpenFTS (deprecated see tsearch2)
docs@openacs.org
View comments on this page at openacs.org + FtsEngineDriver parameter. +
Restart the service.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$
Wait a minute, then click on Main Site at the top of the page.
Enable Full Text Search in packages
Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package
Install the package. +
Click Admin on the top of the default home page. If prompted, log in with the account and password you entered during install.
Click on the Install + software link.
Click on the Install + new application link.
Click on the Install link next to Weblogger.
Install all required packages as well (always say okay until you shall restart the server)
+
Load the service contracts datamodell and enable the service contract
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql +[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql
Note: Usually this script is called package_name-sc-create.sql
Restart the service.
[$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME postgresl]$
If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled.
Prev Home Next
Install nspam Up Install Full Text Search using OpenFTS (deprecated see tsearch2)
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-ldap-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ldap-radius.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 13 Sep 2009 23:54:40 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,13 +1,13 @@ - -Install LDAP for use as external authentication
Prev Appendix B. Install additional supporting software Next
Install LDAP for use as external authentication
By Malte Sussdorff
+ +Install LDAP for use as external authentication
Prev Appendix B. Install additional supporting software Next
Install LDAP for use as external authentication
By Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section
Install openldap. Download and install ns_ldap
[root aolserver]# cd /usr/local/src/ - [root src]# wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz - [root src]# tar xvfz openldap-2.2.17.tgz - [root src]# cd openldap-2.2.17 - [root src]# ./configure --prefix=/usr/local/openldap - [root openldap]# make install +
This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section
Install openldap. Download and install ns_ldap
[root aolserver]# cd /usr/local/src/ + [root src]# wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz + [root src]# tar xvfz openldap-2.2.17.tgz + [root src]# cd openldap-2.2.17 + [root src]# ./configure --prefix=/usr/local/openldap + [root openldap]# make install [root openldap]# cd /usr/local/src/ wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz @@ -16,18 +16,18 @@ ./configure --prefix=/usr/local/openldap --disable-slapd make install -
Install ns_ldap. Download and install ns_ldap
[root aolserver]# cd /usr/local/src/aolserver/ - [root aolserver]# wget http://www.sussdorff.de/ressources/nsldap.tgz - [root aolserver]# tar xfz nsldap.tgz - [root aolserver]# cd nsldap - [root ns_pam-0.1]# make install LDAP=/usr/local/openldap INST=/usr/local/aolserver +
Install ns_ldap. Download and install ns_ldap
[root aolserver]# cd /usr/local/src/aolserver/ + [root aolserver]# wget http://www.sussdorff.de/ressources/nsldap.tgz + [root aolserver]# tar xfz nsldap.tgz + [root aolserver]# cd nsldap + [root ns_pam-0.1]# make install LDAP=/usr/local/openldap INST=/usr/local/aolserver [root ns_pam-0.1]# cd /usr/local/src/aolserver/ wget http://www.sussdorff.de/resources/nsldap.tgz tar xfz nsldap.tgz cd nsldap make install LDAP=/usr/local/openldap INST=/usr/local/aolserver -
Configure ns_ldap for traditional use. Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the usernamestored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.
- Change config.tcl. Remove the # in front of ns_param nsldap ${bindir}/nsldap.so to enable the loading of the ns_ldap module. -
Configure ns_ldap for use with LDAP bind. LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the ns_ldap bind command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).
Prev Home Next
Install PAM Radius for use as external authentication Up Install AOLserver 3.3oacs1
docs@openacs.org
View comments on this page at openacs.org +
Configure ns_ldap for traditional use. Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the usernamestored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.
+ Change config.tcl. Remove the # in front of ns_param nsldap ${bindir}/nsldap.so to enable the loading of the ns_ldap module. +
Configure ns_ldap for use with LDAP bind. LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the ns_ldap bind command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).
Prev Home Next
Install PAM Radius for use as external authentication Up Install AOLserver 3.3oacs1
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-more-software.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.html,v diff -u -N -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/install-more-software.html 13 Sep 2009 23:54:40 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/install-more-software.html 11 Dec 2010 23:36:32 -0000 1.20 @@ -1,9 +1,9 @@ - -Appendix B. Install additional supporting software
Prev Part II. Administrator's Guide Next
Appendix B. Install additional supporting software
Table of Contents
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1
By Joel Aufrecht
+ +Appendix B. Install additional supporting software
Prev Part II. Administrator's Guide Next
Appendix B. Install additional supporting software
Table of Contents
Unpack the OpenACS tarball
Initialize CVS (OPTIONAL)
Add PSGML commands to emacs init file (OPTIONAL)
Install Daemontools (OPTIONAL)
Install qmail (OPTIONAL)
Install Analog web file analyzer
Install nspam
Install Full Text Search using Tsearch2
Install Full Text Search using OpenFTS (deprecated see tsearch2)
Install nsopenssl
Install tclwebtest.
Install PHP for use in AOLserver
Install Squirrelmail for use as a webmail system for OpenACS
Install PAM Radius for use as external authentication
Install LDAP for use as external authentication
Install AOLserver 3.3oacs1
By Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
This section assumes that the source tarballs for supporting - software are in /tmp. It assumes + software are in /tmp. It assumes that you begin each continuous block of commands as root, and you should end each block as root. It doesn't care which directory you start in. Text instructions always precede the commands they Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-next-add-server.html 17 Oct 2010 21:06:08 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,19 +1,19 @@ - -Running multiple services on one machine
Prev Chapter 6. Production Environments Next
Running multiple services on one machine
Services on different ports. To run a different service on another port but the same - ip, simply repeat Install OpenACS 5.6.0 replacing + +Running multiple services on one machine
Prev Chapter 6. Production Environments Next
Running multiple services on one machine
Services on different ports. To run a different service on another port but the same + ip, simply repeat Install OpenACS 5.6.0 replacing $OPENACS_SERVICE_NAME, and change the
set httpport 8000 -set httpsport 8443
- to different values.
Services on different host names. For example, suppose you want to support -http://service0.com and - http://bar.com on the same +set httpsport 8443
+ to different values.
Services on different host names. For example, suppose you want to support +http://service0.com and + http://bar.com on the same machine. The easiest way is to assign each one a different ip address. Then you can install two services as above, but with different values for
set hostname [ns_info hostname] -set address 127.0.0.1
+set address 127.0.0.1

If you want to install two services with different host names sharing the same ip, you'll need nsvhr to redirect requests - based on the contents of the tcp headers. See AOLserver - Virtual Hosting with TCP by markd. + based on the contents of the tcp headers. See AOLserver + Virtual Hosting with TCP by markd.
Prev Home Next
AOLserver keepalive with inittab Up High Availability/High Performance Configurations
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html,v diff -u -N -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 17 Oct 2010 21:06:08 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 11 Dec 2010 23:36:32 -0000 1.21 @@ -1,19 +1,19 @@ - -Vacuum Postgres nightly
Prev Chapter 7. Database Management Next
Vacuum Postgres nightly
- The "vacuum" command must be run periodically to reclaim space - in versions of PostgreSQL before 7.4. The "vacuum analyze" form + +Vacuum Postgres nightly
Prev Chapter 7. Database Management Next
Vacuum Postgres nightly
+ The "vacuum" command must be run periodically to reclaim space + in versions of PostgreSQL before 7.4. The "vacuum analyze" form additionally collects statistics on the disbursion of columns in the database, which the optimizer uses when it calculates just how to execute queries. The availability of this data can make a tremendous difference in the execution speed of queries. This command can also be run from cron, but it probably makes more sense to run this command as part of your nightly backup - procedure - if "vacuum" is going to screw up the database, you'd + procedure - if "vacuum" is going to screw up the database, you'd prefer it to happen immediately after (not before!) you've made a - backup! The "vacuum" command is very reliable, but conservatism is + backup! The "vacuum" command is very reliable, but conservatism is the key to good system management. So, if you're using the export procedure described above, you don't need to do this extra step. -
Edit your crontab:
[joeuser ~]$ crontab -e
We'll set vacuum up to run nightly at 1 AM. Add the following +
Edit your crontab:
[joeuser ~]$ crontab -e
We'll set vacuum up to run nightly at 1 AM. Add the following line:
-0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME
($Id$)
Prev Home Next
Deleting a tablespace Up Chapter 8. Backup and Recovery
docs@openacs.org
View comments on this page at openacs.org +0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME
($Id$)
Prev Home Next
Deleting a tablespace Up Appendix A. Install Red Hat 8/9
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 13 Sep 2009 23:54:40 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 11 Dec 2010 23:36:32 -0000 1.24 @@ -1,49 +1,49 @@ - -Install nsopenssl
Prev Appendix B. Install additional supporting software Next
Install nsopenssl
By Joel Aufrecht and Malte Sussdorff
+ +Install nsopenssl
Prev Appendix B. Install additional supporting software Next
Install nsopenssl
By Joel Aufrecht and Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
This AOLserver module is required if you want people to connect to your site via https. These commands compile nsopenssl and install it, along with a tcl helper script to handle https connections. You will also need ssl certificates. Because those should - be different for each server service, you won't need those instructions until - later.
Install on AOLserver3
You will need the unpacked Aolserver tarball in - /usr/local/src/aolserver and - the nsopenssl tarball in - /tmp.
Red Hat 9 note: see this - thread for details on compiling nsopenssl.)
[root bin]# cd /usr/local/src/aolserver -[root aolserver]# wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz -[root aolserver]# tar xzf nsopenssl-2.1.tar.gz -[root aolserver]# cd nsopenssl-2.1 -[root nsopenssl-2.1]# make OPENSSL=/usr/local/ssl + be different for each server service, you won't need those instructions until + later.
Install on AOLserver3
You will need the unpacked Aolserver tarball in + /usr/local/src/aolserver and + the nsopenssl tarball in + /tmp.
Red Hat 9 note: see this + thread for details on compiling nsopenssl.)
[root bin]# cd /usr/local/src/aolserver +[root aolserver]# wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz +[root aolserver]# tar xzf nsopenssl-2.1.tar.gz +[root aolserver]# cd nsopenssl-2.1 +[root nsopenssl-2.1]# make OPENSSL=/usr/local/ssl gcc -I/usr/local/ssl/include -I../aolserver/include -D_REENTRANT=1 -DNDEBUG=1 -g -fPIC -Wall -Wno-unused -mcpu=i686 -DHAVE_CMMSG=1 -DUSE_FIONREAD=1 -DHAVE_COND_EINTR=1 -c -o nsopenssl.o nsopenssl.c (many lines omitted) gcc -shared -nostartfiles -o nsopenssl.so nsopenssl.o config.o init.o ssl.o thread.o tclcmds.o -L/usr/local/ssl/lib -lssl -lcrypto -[root nsopenssl-2.1]# cp nsopenssl.so /usr/local/aolserver/bin -[root nsopenssl-2.1]# cp https.tcl /usr/local/aolserver/modules/tcl/ +[root nsopenssl-2.1]# cp nsopenssl.so /usr/local/aolserver/bin +[root nsopenssl-2.1]# cp https.tcl /usr/local/aolserver/modules/tcl/ [root nsopenssl-2.1]# cd /usr/local/src/aolserver wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz tar xzf nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/local/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/
For Debian (more +cp https.tcl /usr/local/aolserver/modules/tcl/
For Debian (more information):
apt-get install libssl-dev cd /usr/local/src/aolserver tar xzf /tmp/nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/lib/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/
Install on AOLserver4
You will need the AOLserver4 source in /usr/local/src/aolserver/aolserver and OpenSSL installed in /usr/local/ssl (or at least symlinked there). The use of INST=/point/to/aolserver is being replaced with AOLSERVER=/point/to/aolserver. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.
FreeBSD note: build nsopenssl with gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10 -
[root bin]# cd /usr/local/src/aolserver -[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login -[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl -[root aolserver]# cd nsopenssl -[root nsopenssl]# make OPENSSL=/usr/local/ssl +cp https.tcl /usr/local/aolserver/modules/tcl/
Install on AOLserver4
You will need the AOLserver4 source in /usr/local/src/aolserver/aolserver and OpenSSL installed in /usr/local/ssl (or at least symlinked there). The use of INST=/point/to/aolserver is being replaced with AOLSERVER=/point/to/aolserver. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.
FreeBSD note: build nsopenssl with gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10 +
[root bin]# cd /usr/local/src/aolserver +[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login +[root aolserver]# cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl +[root aolserver]# cd nsopenssl +[root nsopenssl]# make OPENSSL=/usr/local/ssl gcc -I/usr/local/ssl/include (many items omitted) -c -o sslcontext.o sslcontext.c (many lines omitted) -[root nsopenssl-2.1]# make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10 +[root nsopenssl-2.1]# make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10 [root nsopenssl-2.1]# cd /usr/local/src/aolserver cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login @@ -52,23 +52,23 @@ make OPENSSL=/usr/local/ssl make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10
If you have problems starting your server with nsopenssl.so due to missing libssl.so.0.9.7 (or lower), you have to create symlinks
-[root nsopenssl]# cd /usr/local/aolserver/lib -[root lib]# ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 -[root lib]# ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7 +[root nsopenssl]# cd /usr/local/aolserver/lib +[root lib]# ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 +[root lib]# ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7 [root lib]# cd /usr/local/aolserver/lib ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7

SSL support must be enabled seperately in each OpenACS - server (Generate ssl certificates.
If your ports for SSL are privileged (below 1024), you + server (Generate ssl certificates.
If your ports for SSL are privileged (below 1024), you will have to start AOLserver with prebinds for both your HTTP - and your HTTPS port (usually by adding -b - your_ip:your_http_port,your_ip:your_https_port + and your HTTPS port (usually by adding -b + your_ip:your_http_port,your_ip:your_https_port to the nsd call. If you are using daemontools, this can be - changed in your etc/daemontools/run - file).
To enable SSL support in your server, make sure your - etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If + changed in your etc/daemontools/run + file).
To enable SSL support in your server, make sure your + etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If that section is not present, try looking at the README file in - /usr/local/src/aolserver/nsopenssl.
Prev Home Next
Install Full Text Search using OpenFTS (deprecated see tsearch2) Up Install tclwebtest.
docs@openacs.org
View comments on this page at openacs.org + /usr/local/src/aolserver/nsopenssl.
Prev Home Next
Install Full Text Search using OpenFTS (deprecated see tsearch2) Up Install tclwebtest.
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-nspam.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nspam.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-nspam.html 13 Sep 2009 23:54:40 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-nspam.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,2 +1,2 @@ - -Install nspam
Prev Appendix B. Install additional supporting software Next
Install nspam
/doc/acs-authentication/ext-auth-install.html
Prev Home Next
Install Analog web file analyzer Up Install Full Text Search using Tsearch2
docs@openacs.org
View comments on this page at openacs.org + +Install nspam
Prev Appendix B. Install additional supporting software Next
Install nspam
/doc/acs-authentication/ext-auth-install.html
Prev Home Next
Install Analog web file analyzer Up Install Full Text Search using Tsearch2
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 13 Sep 2009 23:54:40 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 11 Dec 2010 23:36:32 -0000 1.11 @@ -1,25 +1,25 @@ - -Deleting a tablespace
Prev Chapter 7. Database Management Next
Deleting a tablespace
Skip down for instructions on Deleting a PostgreSQL tablespace. -
Deleting an Oracle tablespace
+ +Deleting a tablespace
Prev Chapter 7. Database Management Next
Deleting a tablespace
Skip down for instructions on Deleting a PostgreSQL tablespace. +
Deleting an Oracle tablespace
Should it become necessary to rebuild a tablespace from scratch, - you can use the drop user command - in SVRMGRL with the cascade + you can use the drop user command + in SVRMGRL with the cascade option. This command will drop the user and every database object - the user owns.
SVRMGR> drop user $OPENACS_SERVICE_NAME cascade;
- If this does not work because svrmgrl "cannot drop a user that - is currently connected", make sure to kill the AOLserver using - this user. If it still does not work, do:
SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';
and then
SVRMGR> alter system kill session 'sid, serial#';
+ the user owns.
SVRMGR> drop user $OPENACS_SERVICE_NAME cascade;
+ If this does not work because svrmgrl "cannot drop a user that + is currently connected", make sure to kill the AOLserver using + this user. If it still does not work, do:
SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME';
and then
SVRMGR> alter system kill session 'sid, serial#';
where sid and serial# are - replaced with the corresponding values for the open session.
Use with caution!
+ replaced with the corresponding values for the open session.
Use with caution!
If you feel the need to delete everything - related to the service, you can also issue the following:
SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;
Deleting a PostgreSQL tablespace
+ related to the service, you can also issue the following:
SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints;
Deleting a PostgreSQL tablespace
Dropping a PostgreSQL tablespace is easy. You have to stop any AOLserver instances that are using the database that you wish to drop. If you're using daemontools, this is simple, just use the 'down' flag (-d). If you're using inittab, you have to comment out - your server in /etc/inittab, - reread the inittab with /sbin/init - q, and then restart-aolserver - $OPENACS_SERVICE_NAME.
Then, to drop the db, just do:
-[$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME + your server in /etc/inittab, + reread the inittab with /sbin/init + q, and then restart-aolserver + $OPENACS_SERVICE_NAME.
Then, to drop the db, just do:
+[$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASE
Prev Home Next
Running a PostgreSQL database on another server Up Vacuum Postgres nightly
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 13 Sep 2009 23:54:40 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 11 Dec 2010 23:36:32 -0000 1.11 @@ -1,51 +1,51 @@ - -AOLserver keepalive with inittab
Prev Chapter 6. Production Environments Next
AOLserver keepalive with inittab
This is an alternative method for keeping the AOLserver - process running. The recommended method is to run AOLserver + +AOLserver keepalive with inittab
Prev Chapter 6. Production Environments Next
AOLserver keepalive with inittab
This is an alternative method for keeping the AOLserver + process running. The recommended method is to run AOLserver supervised.
This step should be completed as root. This can break every service on your machine, so proceed with caution. -
+
There are 2 general steps to getting this working. -
+
Install a script called - restart-aolserver. This + restart-aolserver. This script doesn't actually restart AOLserver - it just kills it. -
+
Ask the OS to restart our service whenever it's not running. We do this by adding a line to - /etc/inittab. + /etc/inittab.
- Calling restart-aolserver + Calling restart-aolserver kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling - restart-aolserver effectively + restart-aolserver effectively restarts our service. -
- Copy this file into - /var/tmp/restart-aolserver.txt. -
+
+ Copy this file into + /var/tmp/restart-aolserver.txt. +
This script needs to be SUID-root, which means that the script will run as root. This is necessary to ensure that the AOLserver processes are killed regardless of who owns them. However the script should be executable by the - web group to ensure that the + web group to ensure that the users updating the web page can use the script, but that general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in - /usr/local/bin. + /usr/local/bin.
[joeuser ~]$ su - Password: *********** [root ~]# cp /var/tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver [root ~]# chown root.web /usr/local/bin/restart-aolserver [root ~]# chmod 4750 /usr/local/bin/restart-aolserver [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl -[root ~]# exit
- Test the restart-aolserver +[root ~]# exit
+ Test the restart-aolserver script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use - restart-aolserver to kill + restart-aolserver to kill it. If it works, then there should be no more servers running. You should see the following lines.
[joeuser ~]$ killall nsd @@ -56,34 +56,34 @@ [joeuser ~]$ killall nsd nsd: no process killed
The number 23727 indicates the process id(s) (PIDs) of the - processes being killed. It is important that no processes are killed by the second - call to killall. If there are + processes being killed. It is important that no processes are killed by the second + call to killall. If there are processes being killed, it means that the script is not - working.
- Assuming that the restart-aolserver + working.
+ Assuming that the restart-aolserver script worked, login as root and open - /etc/inittab for + /etc/inittab for editing.
[joeuser ~]$ su - Password: ************ -[root ~]# emacs -nw /etc/inittab
+[root ~]# emacs -nw /etc/inittab
Copy this line into the bottom of the file as a template, making sure that the first field - nss1 is unique. + nss1 is unique.
-nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl
- Important: Make sure there is a +nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/joeuser/var/lib/aolserver/birdnotes/nsd.tcl
+ Important: Make sure there is a newline at the end of the file. If there is not a newline at the end of the file, the system may suffer catastrophic failures. -
+
Still as root, enter the following command to re-initialize - /etc/inittab.
+ /etc/inittab.
[root ~]# killall nsd nsd: no process killed -[root ~]# /sbin/init q
+[root ~]# /sbin/init q
See if it worked by running the - restart-aolserver script + restart-aolserver script again.
[root ~]# restart-aolserver birdnotes Killing 23750
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.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 17 Oct 2010 21:06:08 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 11 Dec 2010 23:36:32 -0000 1.22 @@ -1,69 +1,69 @@ - -Starting and Stopping an OpenACS instance.
Prev Chapter 6. Production Environments Next
Starting and Stopping an OpenACS instance.
The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.
A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.
The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.
Daemontools must already be installed. If not, install it.
Each service controlled by daemontools must have a - directory in /service. That + +Starting and Stopping an OpenACS instance.
Prev Chapter 6. Production Environments Next
Starting and Stopping an OpenACS instance.
The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.
A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.
The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here.
Daemontools must already be installed. If not, install it.
Each service controlled by daemontools must have a + directory in /service. That directory must have a file called - run. It works like this:
The init program starts every - time the computer is booted.
A line in init's configuration - file, /etc/inittab, tells init to + run. It works like this:
The init program starts every + time the computer is booted.
A line in init's configuration + file, /etc/inittab, tells init to run, and to restart if necessary, - svscanboot.
svscanboot checks - the directory /service - every few seconds.
If it sees a subdirectory there, it + svscanboot.
svscanboot checks + the directory /service + every few seconds.
If it sees a subdirectory there, it looks for a file in the subdirectory called - run. If it finds a run file, it creates a supervise process
supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.
Hence, the AOLserver + run. If it finds a run file, it creates a supervise process
supervise executes the run script. Whenever the run script stops, supervise executes it again. It also creates additional control files in the same directory.
Hence, the AOLserver instance for your development server is started by the file - /service/$OPENACS_SERVICE_NAME/run. + /service/$OPENACS_SERVICE_NAME/run. But we use a symlink to make it easier to add and remove - stuff from the /service, so + stuff from the /service, so the actual location is - /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run.
Daemontools creates additional files and directories to track status and + /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run.
Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS tarball at - /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.
[$OPENACS_SERVICE_NAME etc]$ killall nsd + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run.
[$OPENACS_SERVICE_NAME etc]$ killall nsd nsd: no process killed -[$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run -[$OPENACS_SERVICE_NAME etc]$ exit +[$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run +[$OPENACS_SERVICE_NAME etc]$ exit -[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/ /service/$OPENACS_SERVICE_NAME
Verify that AOLserver is running.
[root root]# ps -auxw | grep nsd +[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/ /service/$OPENACS_SERVICE_NAME
Verify that AOLserver is running.
[root root]# ps -auxw | grep nsd $OPENACS_SERVICE_NAME 5562 14.4 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl -u serve root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd -[root root]#
The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:
+[root root]#
The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands:
- svc -d /service/$OPENACS_SERVICE_NAME - + svc -d /service/$OPENACS_SERVICE_NAME - Bring the server down -
+
- svc -u /service/$OPENACS_SERVICE_NAME - + svc -u /service/$OPENACS_SERVICE_NAME - Start the server up and leave it in keepalive mode. -
+
- svc -o /service/$OPENACS_SERVICE_NAME - + svc -o /service/$OPENACS_SERVICE_NAME - Start the server up once. Do not restart it if it stops. -
+
- svc -t /service/$OPENACS_SERVICE_NAME - + svc -t /service/$OPENACS_SERVICE_NAME - Stop and immediately restart the server. -
+
- svc -k /service/$OPENACS_SERVICE_NAME - + svc -k /service/$OPENACS_SERVICE_NAME - Sends the server a KILL signal. This is like KILL -9. AOLserver exits immediately. If svc -t fails to fully kill AOLserver, use this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately. -
Install a script to automate the stopping and starting - of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME
[root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver -[root root]# chmod 755 /usr/local/bin/restart-aolserver -[root root]#
+
Install a script to automate the stopping and starting + of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME
[root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver +[root root]# chmod 755 /usr/local/bin/restart-aolserver +[root root]#
At this point, these commands will work only for the - root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server.
[root root]# /usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME -[root root]#
Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands. + root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server.
[root root]# /usr/local/bin/svgroup web /service/$OPENACS_SERVICE_NAME +[root root]#
Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands.
- Most of this information comes from Tom Jackson's AOLserver+Daemontools + Most of this information comes from Tom Jackson's AOLserver+Daemontools Mini-HOWTO. -
Table 6.1. How it Works
Program Invoked by this program ... ... using this file Where to find errors Log goes to Use these commands to control it
svscanboot - init /etc/inittab ps -auxw | grep readproctitle n/a
aolserver supervise -(a child of svscanboot) /service/$OPENACS_SERVICE_NAME/run /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log svc -k /service/$OPENACS_SERVICE_NAME
postgresql Redhat init scripts during boot /etc/init.d/postgresql /usr/local/pgsql/data/server.log service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)
Prev Home Next
Chapter 6. Production Environments Up AOLserver keepalive with inittab
docs@openacs.org
View comments on this page at openacs.org +
Table 6.1. How it Works
Program Invoked by this program ... ... using this file Where to find errors Log goes to Use these commands to control it
svscanboot + init /etc/inittab ps -auxw | grep readproctitle n/a
aolserver supervise +(a child of svscanboot) /service/$OPENACS_SERVICE_NAME/run /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log svc -k /service/$OPENACS_SERVICE_NAME
postgresql Redhat init scripts during boot /etc/init.d/postgresql /usr/local/pgsql/data/server.log service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)

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-origins.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-origins.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-origins.html 13 Sep 2009 23:54:40 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-origins.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,23 +1,23 @@ - -Where did this document come from?
Prev Appendix C. Credits Next
Where did this document come from?
- This document was created by Vinod Kurup, but it's really + +Where did this document come from?
Prev Appendix C. Credits Next
Where did this document come from?
+ This document was created by Vinod Kurup, but it's really just plagiarism from a number of documents that came before it. If I've used something that you've written without proper credit, let me know and I'll fix it right away. -
Versions 4.6.2 to present were edited by Joel Aufrecht. -
These are a few of my sources:
+
Versions 4.6.2 to present were edited by Joel Aufrecht. +
These are a few of my sources:
ArsDigita installation guide -
+
OpenACS 3.x installation guide -
- Gilbert Wong's FreeBSD +
+ Gilbert Wong's FreeBSD installation guide -
- Vinod Kurup's Brief OpenACS4 +
+ Vinod Kurup's Brief OpenACS4 installation guide -
- Joel +
+ Joel Aufrecht's OpenACS 4.5 Quick Guide.
- Please also see the Credits section for more acknowledgements. + Please also see the Credits section for more acknowledgements.
Prev Home Next
Appendix C. Credits Up Linux Install Guides
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -N -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/install-overview.html 13 Sep 2009 23:54:40 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 11 Dec 2010 23:36:32 -0000 1.31 @@ -1,5 +1,5 @@ - -Chapter 2. Installation Overview
Prev Part II. Administrator's Guide Next
Chapter 2. Installation Overview
Table of Contents
Basic Steps
Prerequisite Software
by Vinod Kurup
+ +Chapter 2. Installation Overview
Prev Part II. Administrator's Guide Next
Chapter 2. Installation Overview
Table of Contents
Basic Steps
Prerequisite Software
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Prev Home Next
Part II. Administrator's Guide Up Basic Steps
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-pam-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-pam-radius.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/install-pam-radius.html 13 Sep 2009 23:54:40 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/install-pam-radius.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,38 +1,38 @@ - -Install PAM Radius for use as external authentication
Prev Appendix B. Install additional supporting software Next
Install PAM Radius for use as external authentication
By Malte Sussdorff
+ +Install PAM Radius for use as external authentication
Prev Appendix B. Install additional supporting software Next
Install PAM Radius for use as external authentication
By Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
This step by step guide is derived from the installation instructions which you can find at yourdomain.com/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.
Install ns_pam. Download and install ns_pam
[root aolserver]# cd /usr/local/src/aolserver/ - [root aolserver]# wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz - [root aolserver]# tar xvfz ns_pam-0.1.tar.gz - [root aolserver]# cd ns_pam-0.1 - [root ns_pam-0.1]# make install INST=/usr/local/aolserver +
This step by step guide is derived from the installation instructions which you can find at yourdomain.com/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.
Install ns_pam. Download and install ns_pam
[root aolserver]# cd /usr/local/src/aolserver/ + [root aolserver]# wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz + [root aolserver]# tar xvfz ns_pam-0.1.tar.gz + [root aolserver]# cd ns_pam-0.1 + [root ns_pam-0.1]# make install INST=/usr/local/aolserver [root ns_pam-0.1]# cd /usr/local/src/aolserver/ wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz tar xvfz ns_pam-0.1.tar.gz cd ns_pam-0.1 make install INST=/usr/local/aolserver -
Configure ns_pam. Configure AOLserver for ns_pam
To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.
+
Configure ns_pam. Configure AOLserver for ns_pam
To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.
Change config.tcl. Remove the - # in front of ns_param - nspam ${bindir}/nspam.so to enable the loading + # in front of ns_param + nspam ${bindir}/nspam.so to enable the loading of the ns_pam module. -
+
Change config.tcl. Replace - pam_domain in the section - ns/server/${server}/module/nspam - with aolserver -
Create /etc/pam.d/aolserver. + pam_domain in the section + ns/server/${server}/module/nspam + with aolserver +
Create /etc/pam.d/aolserver.
- [root ns_pam]#cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver -
Configure PAM Radius. Configure and install PAM Radius
You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.
[root ns_pam]# cd /usr/local/src/ - [root src]# wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar - [root src]# tar xvf pam_radius-1.3.16 - [root src]# cd pam_radius - [root pam_radius]# make - [root pam_radius]# cp pam_radius_auth.so /lib/security/ + [root ns_pam]#cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver +
Configure PAM Radius. Configure and install PAM Radius
You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.
[root ns_pam]# cd /usr/local/src/ + [root src]# wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar + [root src]# tar xvf pam_radius-1.3.16 + [root src]# cd pam_radius + [root pam_radius]# make + [root pam_radius]# cp pam_radius_auth.so /lib/security/ [root pam_radius]# cd /usr/local/src wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar @@ -41,6 +41,6 @@ make cp pam_radius_auth.so /lib/security/ -
Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.
[root pam_radius]# echo "radius.yourdomain.com:1645 your_radius_password >>/etc/rddb/server - [root src]# chown service0:web /etc/rddb/server +
Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.
[root pam_radius]# echo "radius.yourdomain.com:1645 your_radius_password >>/etc/rddb/server + [root src]# chown service0:web /etc/rddb/server
Prev Home Next
Install Squirrelmail for use as a webmail system for OpenACS Up Install LDAP for use as external authentication
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-php.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-php.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/install-php.html 13 Sep 2009 23:54:40 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/install-php.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,12 +1,12 @@ - -Install PHP for use in AOLserver
Prev Appendix B. Install additional supporting software Next
Install PHP for use in AOLserver
By Malte Sussdorff
+ +Install PHP for use in AOLserver
Prev Appendix B. Install additional supporting software Next
Install PHP for use in AOLserver
By Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from www.php.net. For convenience we get version 4.3.4 from a mirror
[root root]# cd /usr/local/src -[root src]# wget http://de3.php.net/distributions/php-4.3.4.tar.gz -[root src]# tar xfz php-4.3.4.tar.gz -[root src]# cd php-4.3.4 -[root php-4.3.4]# cd php-4.3.4 -[root php-4.3.4]# ./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql -[root php-4.3.4]# make install -
Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add index.php as the last element to your directoryfile directive.
Prev Home Next
Install tclwebtest. Up Install Squirrelmail for use as a webmail system for OpenACS
docs@openacs.org
View comments on this page at openacs.org +
To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from www.php.net. For convenience we get version 4.3.4 from a mirror
[root root]# cd /usr/local/src +[root src]# wget http://de3.php.net/distributions/php-4.3.4.tar.gz +[root src]# tar xfz php-4.3.4.tar.gz +[root src]# cd php-4.3.4 +[root php-4.3.4]# cd php-4.3.4 +[root php-4.3.4]# ./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql +[root php-4.3.4]# make install +
Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add index.php as the last element to your directoryfile directive.
Prev Home Next
Install tclwebtest. Up Install Squirrelmail for use as a webmail system for OpenACS
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.38 -r1.39 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 17 Oct 2010 21:06:08 -0000 1.38 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 11 Dec 2010 23:36:32 -0000 1.39 @@ -1,53 +1,53 @@ - -Install qmail (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Install qmail (OPTIONAL)
Qmail is a Mail Transfer Agent. It handles incoming and + +Install qmail (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Install qmail (OPTIONAL)
Qmail is a Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.
Red Hat 9: all djb tools (qmail, daemontools, ucspi) will - fail to compile in Red Hat 9 because of changes to glibc (patches)
Install ucspi. This program handles incoming tcp connections. - Download ucspi and install it.
[root root]# cd /usr/local/src -[root src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz -[root src]# tar xzf ucspi-tcp-0.88.tar.gz + fail to compile in Red Hat 9 because of changes to glibc (patches)
Install ucspi. This program handles incoming tcp connections. + Download ucspi and install it.
[root root]# cd /usr/local/src +[root src]# wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz +[root src]# tar xzf ucspi-tcp-0.88.tar.gz cd /usr/local/src wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz tar xzf ucspi-tcp-0.88.tar.gz
Red Hat 9 only
wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch cd ucspi-tcp-0.88 patch -p1 <../ucspi-tcp-0.88.errno.patch -cd ..
All platforms continue:
[root src]# cd ucspi-tcp-0.88 -[root ucspi-tcp-0.88]# make +cd ..
All platforms continue:
[root src]# cd ucspi-tcp-0.88 +[root ucspi-tcp-0.88]# make ( cat warn-auto.sh; \ -echo 'main="$1"; shift'; \(many lines omitted) +echo 'main="$1"; shift'; \(many lines omitted) ./compile instcheck.c ./load instcheck hier.o auto_home.o unix.a byte.a -[root ucspi-tcp-0.88]# make setup check +[root ucspi-tcp-0.88]# make setup check ./install ./instcheck [root ucspi-tcp-0.88]# cd ucspi-tcp-0.88 make make setup check
Verify that ucspi-tcp was installed successfully by -running the tcpserver program which is part of ucspi-tcp:
[root ucspi-tcp-0.88]# tcpserver +running the tcpserver program which is part of ucspi-tcp:
[root ucspi-tcp-0.88]# tcpserver tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root ucspi-tcp-0.88]# -
+
(I'm not sure if this next step is 100% necessary, but when I skip it -I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail +I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our case, the qmail replacement wrapper for the sendmail executable. In some cases, though, the outgoing mail requset is apparently sent through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP -address that means the local machine - the "loopback" interface). +address that means the local machine - the "loopback" interface). Unless this mail is addressed to the same machine, qmail thinks that it's an attempt to relay mail, and rejects it. So these two commands set up an exception so that any mail sent from 127.0.0.1 is allowed to -send outgoing mail.
[root ucspi-tcp-0.88]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -[root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp +send outgoing mail.
[root ucspi-tcp-0.88]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp +[root ucspi-tcp-0.88]# tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
Install Qmail.
Download qmail, - set up the standard supporting users and build the binaries:
[root root]# cd /usr/local/src -[root src]# wget http://www.qmail.org/netqmail-1.04.tar.gz -[root src]# tar xzf netqmail-1.04.tar.gz +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 --15:04:11-- http://www.qmail.org/netqmail-1.04.tar.gz => `netqmail-1.04.tar.gz' Resolving www.qmail.org... done. @@ -59,18 +59,18 @@ 15:04:21 (24.04 KB/s) - `netqmail-1.04.tar.gz' saved [242310/242310] -[root src]# mkdir /var/qmail -[root src]# groupadd nofiles -[root src]# useradd -g nofiles -d /var/qmail/alias alias -[root src]# useradd -g nofiles -d /var/qmail qmaild -[root src]# useradd -g nofiles -d /var/qmail qmaill -[root src]# useradd -g nofiles -d /var/qmail qmailp -[root src]# groupadd qmail -[root src]# useradd -g qmail -d /var/qmail qmailq -[root src]# useradd -g qmail -d /var/qmail qmailr -[root src]# useradd -g qmail -d /var/qmail qmails -[root src]# cd netqmail-1.04 -[root netqmail-1.04]# ./collate.sh +[root src]# mkdir /var/qmail +[root src]# groupadd nofiles +[root src]# useradd -g nofiles -d /var/qmail/alias alias +[root src]# useradd -g nofiles -d /var/qmail qmaild +[root src]# useradd -g nofiles -d /var/qmail qmaill +[root src]# useradd -g nofiles -d /var/qmail qmailp +[root src]# groupadd qmail +[root src]# useradd -g qmail -d /var/qmail qmailq +[root src]# useradd -g qmail -d /var/qmail qmailr +[root src]# useradd -g qmail -d /var/qmail qmails +[root src]# cd netqmail-1.04 +[root netqmail-1.04]# ./collate.sh You should see 7 lines of text below. If you see anything else, then something might be wrong. @@ -81,8 +81,8 @@ [5] Renaming qmail-1.03 to netqmail-1.04... [6] Continue installing qmail using the instructions found at: [7] http://www.lifewithqmail.org/lwq.html#installation -[root netqmail-1.04]# cd netqmail-1.04 -[root netqmail-1.04]# make setup check +[root netqmail-1.04]# cd netqmail-1.04 +[root netqmail-1.04]# make setup check ( cat warn-auto.sh; \ echo CC=\'`head -1 conf-cc`\'; \(many lines omitted) ./install @@ -103,11 +103,11 @@ cd netqmail-1.04 ./collate.sh cd netqmail-1.04 -make setup 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 +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 -ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
[root qmail-1.03]# ./config-fast yourserver.test +ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail
Configure qmail - specifically, run the config script to set up files in /var/qmail/control specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read /var/qmail/doc/INSTALL.ctl to find out how to configure qmail.
[root qmail-1.03]# ./config-fast yourserver.test Your fully qualified host name is yourserver.test. Putting yourserver.test into control/me... Putting yourserver.test into control/defaultdomain... @@ -117,45 +117,45 @@ Now qmail will refuse to accept SMTP messages except to yourserver.test. Make sure to change rcpthosts if you add hosts to locals or virtualdomains! [root qmail-1.03]# -./config-fast yourserver.test
All incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail.
[root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root -[root alias]# chmod 644 ~alias/.qmail* -[root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/ -[root alias]# chown -R alias.nofiles /var/qmail/alias/Maildir +./config-fast yourserver.test
All incoming mail that isn't for a specific user is handled by the alias user. This includes all root mail. These commands prepare the alias user to receive mail.
[root qmail-1.03]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root +[root alias]# chmod 644 ~alias/.qmail* +[root alias]# /var/qmail/bin/maildirmake ~alias/Maildir/ +[root alias]# chown -R alias.nofiles /var/qmail/alias/Maildir [root alias]# cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root chmod 644 ~alias/.qmail* /var/qmail/bin/maildirmake ~alias/Maildir/ -chown -R alias.nofiles /var/qmail/alias/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.6.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc -[root alias]# chmod 755 /var/qmail/rc +chown -R alias.nofiles /var/qmail/alias/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.6.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc +[root alias]# chmod 755 /var/qmail/rc [root alias]# -echo "./Maildir" > /var/qmail/bin/.qmail +echo "./Maildir" > /var/qmail/bin/.qmail cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc chmod 755 /var/qmail/rc
Set up the skeleton directory so that new users will - be configured for qmail.
[root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir -[root root]# echo "./Maildir/" > /etc/skel/.qmail + be configured for qmail.
[root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir +[root root]# echo "./Maildir/" > /etc/skel/.qmail [root root]# /var/qmail/bin/maildirmake /etc/skel/Maildir -echo "./Maildir/" > /etc/skel/.qmail
As recommended, we will run qmail with daemontools - control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.
[root root]# mkdir -p /var/qmail/supervise/qmail-send/log -[root root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log -[root root]# mkdir /var/log/qmail -[root root]# chown qmaill /var/log/qmail -[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl -[root root]# chmod 755 /var/qmail/bin/qmailctl -[root root]# ln -s /var/qmail/bin/qmailctl /usr/bin -[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run -[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run -[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run -[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run -[root root]# chmod 755 /var/qmail/supervise/qmail-send/run -[root root]# chmod 755 /var/qmail/supervise/qmail-send/log/run -[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run -[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/log/run -[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service -[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service +echo "./Maildir/" > /etc/skel/.qmail
As recommended, we will run qmail with daemontools + control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.
[root root]# mkdir -p /var/qmail/supervise/qmail-send/log +[root root]# mkdir -p /var/qmail/supervise/qmail-smtpd/log +[root root]# mkdir /var/log/qmail +[root root]# chown qmaill /var/log/qmail +[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmailctl.txt /var/qmail/bin/qmailctl +[root root]# chmod 755 /var/qmail/bin/qmailctl +[root root]# ln -s /var/qmail/bin/qmailctl /usr/bin +[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-send-run.txt /var/qmail/supervise/qmail-send/run +[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-send-log-run.txt /var/qmail/supervise/qmail-send/log/run +[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-smtpd-run.txt /var/qmail/supervise/qmail-smtpd/run +[root root]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/qmail-smtpd-log-run.txt /var/qmail/supervise/qmail-smtpd/log/run +[root root]# chmod 755 /var/qmail/supervise/qmail-send/run +[root root]# chmod 755 /var/qmail/supervise/qmail-send/log/run +[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/run +[root root]# chmod 755 /var/qmail/supervise/qmail-smtpd/log/run +[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service +[root root]# ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service mkdir -p /var/qmail/supervise/qmail-send/log mkdir -p /var/qmail/supervise/qmail-smtpd/log mkdir /var/log/qmail @@ -172,11 +172,11 @@ chmod 755 /var/qmail/supervise/qmail-smtpd/run chmod 755 /var/qmail/supervise/qmail-smtpd/log/run ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service -
Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.
[root root]# qmailctl stat +
Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.
[root root]# qmailctl stat /service/qmail-send: up (pid 32700) 430 seconds /service/qmail-send/log: up (pid 32701) 430 seconds /service/qmail-smtpd: up (pid 32704) 430 seconds /service/qmail-smtpd/log: up (pid 32705) 430 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0 -[root root]#
Further verify by sending and receiving email. Incoming mail for root is stored in /var/qmail/alias/Maildir.
Prev Home Next
Install Daemontools (OPTIONAL) Up Install Analog web file analyzer
docs@openacs.org
View comments on this page at openacs.org +[root root]#
Further verify by sending and receiving email. Incoming mail for root is stored in /var/qmail/alias/Maildir.
Prev Home Next
Install Daemontools (OPTIONAL) Up Install Analog web file analyzer
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -N -r1.38 -r1.39 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 17 Oct 2010 21:06:08 -0000 1.38 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 11 Dec 2010 23:36:32 -0000 1.39 @@ -1,5 +1,5 @@ - -Appendix A. Install Red Hat 8/9
Prev Part II. Administrator's Guide Next
Appendix A. Install Red Hat 8/9
by Joel Aufrecht
+ +Appendix A. Install Red Hat 8/9
Prev Part II. Administrator's Guide Next
Appendix A. Install Red Hat 8/9
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
This section takes a blank PC and sets up some supporting @@ -8,78 +8,78 @@ works and is secure; it should take about an hour. (In my experience, it's almost always a net time savings of several hours to install a new machine from scratch compared to installing each - of these packages installed independently.)
The installation guide assumes you have:
A PC with hard drive you can reinstall
Red Hat 8.0 or 9.0 install discs
A CD with the current Security + of these packages installed independently.)
The installation guide assumes you have:
A PC with hard drive you can reinstall
Red Hat 8.0 or 9.0 install discs
A CD with the current Security Patches for your version of Red Hat.
The installation guide assumes that you can do the following on your platform: -
+
Adding users, groups, setting passwords -
+
(For Oracle) Starting an X server and running an X program remotely -
- Basic file management using cp, rm, - mv, and cd -
+
+ Basic file management using cp, rm, + mv, and cd +
Compiling a program using ./config and make.
You can complete this install without the above knowledge, but if anything goes wrong it may take extra time to - understand and correct the problem. Some useful UNIX resources. -
Unplug the network cable from your + understand and correct the problem. Some useful UNIX resources. +
Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - + (Wherever you see - the word secure, you should always read it as, "secure + the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're willing to exert and the estimated risk and - consequences.")
Insert Red Hat 8.0 or 9.0 Disk 1 into the - CD-ROM and reboot the computer
At the - boot: + consequences.")
Insert Red Hat 8.0 or 9.0 Disk 1 into the + CD-ROM and reboot the computer
At the + boot: prompt, press Enter for a graphical install. The text install is fairly different, so if you need to do that instead proceed with caution, because - the guide won't match the steps.
Checking the media is probably a waste of + the guide won't match the steps.
Checking the media is probably a waste of time, so when it asks press Tab and - then Enter to skip it.
After the graphical introduction page loads, click Next
Choose the language you want to use and then click -Next -
Select the keyboard layout you will use and Click Next
Choose your mouse type and Click Next
Red Hat has several templates for new - computers. We'll start with the "Server" template and then + then Enter to skip it.
After the graphical introduction page loads, click Next
Choose the language you want to use and then click +Next +
Select the keyboard layout you will use and Click Next
Choose your mouse type and Click Next
Red Hat has several templates for new + computers. We'll start with the "Server" template and then fine-tune it during the rest of the install. Choose - Server + Server and click - Next.
Reformat the hard drive. If you know what you're doing, + Next.
Reformat the hard drive. If you know what you're doing, do this step on your own. Otherwise: we're going to let the installer wipe out the everything on the main hard drive and then arrange things to - its liking.
Choose Automatically Partition - and click Next
Uncheck -Review (and modify if needed) the partitions created and click Next
On the pop-up window asking "Are you sure - you want to do this?" click - Yes - IF YOU ARE WIPING YOUR HARD DRIVE.
Click Next on the boot loader screen
Configure Networking. + its liking.
Choose Automatically Partition + and click Next
Uncheck +Review (and modify if needed) the partitions created and click Next
On the pop-up window asking "Are you sure + you want to do this?" click + Yes + IF YOU ARE WIPING YOUR HARD DRIVE.
Click Next on the boot loader screen
Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, - follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
DHCP is a system by which a computer that + follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.
DHCP is a system by which a computer that joins a network (such as on boot) can request a temporary IP address and other network information. Assuming the machine has a dedicated IP address (if it doesn't, it will be tricky to access the OpenACS service from the outside world), we're going to set up that address. If you don't know your netmask, 255.255.255.0 is usually a pretty safe -guess. Click Edit, uncheck Configure using DHCP -and type in your IP and netmask. Click Ok.
Type in your host -name, gateway, and DNS server(s). Then click Next.
We're going to use the firewall template for high +guess. Click Edit, uncheck Configure using DHCP +and type in your IP and netmask. Click Ok.
Type in your host +name, gateway, and DNS server(s). Then click Next.
We're going to use the firewall template for high security, meaning that we'll block almost all incoming traffic. Then we'll add a few holes to the firewall for services which we need and -know are secure. Choose High +know are secure. Choose High security level. Check -WWW, -SSH, and -Mail (SMTP). In 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 +WWW, +SSH, and +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 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 + Next
Choose your time zone and click Next.
Type in a root +password, twice.
On the Package selection page, we're going to uncheck a lot of packages that install software we don't need, and add packages that have stuff we do need. You should install everything we're installing here or the guide may not work for you; you can @@ -88,54 +88,54 @@ risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later. -
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 +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 of packages we've selected, and wants to satisfy some dependencies. Don't let it. On the next screen, choose -Ignore Package -Dependencies and click -Next. -
Click - Next - to start the copying of files.
Wait. Insert Disk 2 when -asked.
Wait. Insert Disk 3 when asked.
If you know how to use it, create a boot +Ignore Package +Dependencies and click +Next. +
Click + Next + to start the copying of files.
Wait. Insert Disk 2 when +asked.
Wait. Insert Disk 3 when asked.
If you know how to use it, create a boot disk. Since you can also boot into recovery mode with the Install CDs, this is less useful than it used to be, and we - won't bother. Select No,I do not want to create a boot disk and click Next.
Click Exit, remove the CD, and watch the + won't bother. Select No,I do not want to create a boot disk and click Next.
Click Exit, remove the CD, and watch the computer reboot. -
After it finishes rebooting and shows the login - prompt, log in:
yourserver login: root +
After it finishes rebooting and shows the login + prompt, log in:
yourserver login: root Password: -[root root]#
Install any security patches. For example, insert your CD with - patches, mount it with mount - /dev/cdrom, then cd - /mnt/cdrom, then rpm -UVH - *rpm. Both Red Hat 8.0 and 9.0 have had both +[root root]#
Install any security patches. For example, insert your CD with + patches, mount it with mount + /dev/cdrom, then cd + /mnt/cdrom, then rpm -UVH + *rpm. Both Red Hat 8.0 and 9.0 have had both kernel and openssl/openssh root exploits, so you should be upgrading all of that. Since you are upgrading the kernel, reboot after this step. -
Lock down SSH
- +
Lock down SSH
+ SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming ssh connections. As a security precaution, we are now going to tell ssh not to allow anyone to connect directly to this computer as root. Type this into the shell: -
emacs /etc/ssh/sshd_config
Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
Make the following changes:
#Protocol 2,1 to - Protocol 2 - (this prevents any connections via SSH 1, which is insecure)
#PermitRootLogin yes to - PermitRootLogin no +
emacs /etc/ssh/sshd_config
Search for the word "root" by typing C-s (that's emacs-speak for control-s) and then root.
Make the following changes:
#Protocol 2,1 to + Protocol 2 + (this prevents any connections via SSH 1, which is insecure)
#PermitRootLogin yes to + PermitRootLogin no (this prevents the root user from logging in remotely via ssh. If you do this, be sure to create a remote access - account, such as "remadmin", which you can use to get ssh - before using "su" to become root)
#PermitEmptyPasswords no to PermitEmptyPasswords no - (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c
Restart sshd so that the change takes effect.
service sshd restart
+ account, such as "remadmin", which you can use to get ssh + before using "su" to become root)
#PermitEmptyPasswords no to PermitEmptyPasswords no + (this blocks passwordless accounts) and save and exit by typing C-x C-s C-x C-c
Restart sshd so that the change takes effect.
service sshd restart
Red Hat still installed a few services we don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the @@ -149,34 +149,34 @@ (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostgreSQL the way it is.) -
[root root]# service pcmcia stop -[root root]# service netfs stop -[root root]# chkconfig --del pcmcia -[root root]# chkconfig --del netfs +
[root root]# service pcmcia stop +[root root]# service netfs stop +[root root]# chkconfig --del pcmcia +[root root]# chkconfig --del netfs [root root]# service pcmcia stop service netfs stop chkconfig --del pcmcia chkconfig --del netfs
If you installed PostgreSQL, do also -service postgresql start and chkconfig --add postgresql.
Plug in the network cable.
Verify that you have connectivity by going to another +service postgresql start and chkconfig --add postgresql.
Plug in the network cable.
Verify that you have connectivity by going to another computer and ssh'ing to yourserver, logging in as - remadmin, and promoting yourself to root:
[joeuser@someotherserver]$ ssh remadmin@yourserver.test + remadmin, and promoting yourself to root:
[joeuser@someotherserver]$ ssh remadmin@yourserver.test The authenticity of host 'yourserver.test (1.2.3.4)' can't be established. DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5. -Are you sure you want to continue connecting (yes/no)? yes +Are you sure you want to continue connecting (yes/no)? yes Warning: Permanently added 'yourserver.test (1.2.3.4)' (DSA) to the list of known hosts. Password: Last login: Mon Mar 3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com -[remadmin remadmin]$ su - +[remadmin remadmin]$ su - Password: -[root root]#
If you didn't burn a CD of patches and use it, can still +[root root]#
If you didn't burn a CD of patches and use it, can still download and install the necessary patches. Here's how to do it for the kernel; you should also check for other critical packages.
Upgrade the kernel to fix a security hole. The default Red Hat 8.0 system kernel (2.4.18-14, which you can check - with uname -a) has several security problems. Download the new kernel, install it, and reboot.
[root root]# cd /var/tmp -[root tmp]# wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm + with uname -a) has several security problems. Download the new kernel, install it, and reboot.
[root root]# cd /var/tmp +[root tmp]# wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm --20:39:00-- http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm => `kernel-2.4.18-27.7.x.i686.rpm' Resolving updates.redhat.com... done. @@ -188,11 +188,11 @@ 20:41:39 (78.38 KB/s) - `kernel-2.4.18-27.7.x.i686.rpm' saved [12736430/12736430] -root@yourserver tmp]# rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm +root@yourserver tmp]# rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm warning: kernel-2.4.18-27.7.x.i686.rpm: V3 DSA signature: NOKEY, key ID db42a60e Preparing... ########################################### [100%] 1:kernel ########################################### [100%] -[root tmp]# reboot +[root tmp]# reboot Broadcast message from root (pts/0) (Sat May 3 20:46:39 2003): @@ -201,4 +201,4 @@ cd /var/tmp wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm -reboot
Prev Home Next
Using CVS for backup-recovery Up Appendix B. Install additional supporting software
docs@openacs.org
View comments on this page at openacs.org +reboot
Prev Home Next
Vacuum Postgres nightly Up Appendix B. Install additional supporting software
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-resources.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-resources.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-resources.html 13 Sep 2009 23:54:40 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-resources.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,52 +1,52 @@ - -Resources
Prev Appendix C. Credits Next
Resources
+ +Resources
Prev Appendix C. Credits Next
Resources
Here are some resources that OpenACS users have found useful. -
Books
+
Books
- Philip + Philip and Alex's Guide to Web Publishing - A very readable guide to database-backed community websites. -
+
- UNIX + UNIX Power Tools - An excellent introduction to the command line tools and basic programs of UNIX -
+
- UNIX - System Administration Handbook (formerly the "red book" - - now the "purple" book) + UNIX + System Administration Handbook (formerly the "red book" + - now the "purple" book) -
+
- UNIX + UNIX System Administrator's Bible - (LePage and Iarerra 1998; IDG) -
+
- Running - Linux
Learning - Gnu Emacs
+ Running + Linux
Learning + Gnu Emacs
- Linux + Linux in a Nutshell -
Web Sites
+
Web Sites
- The UNIX + The UNIX Reference Desk -
+
- The Linux Documentation + The Linux Documentation Project -
+
- LPI + LPI certification exam preps - A series of articles from IBM developerworks on basic and intermediate Linux skills (requires registration) Index: openacs-4/packages/acs-core-docs/www/install-squirrelmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-squirrelmail.html,v diff -u -N -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/install-squirrelmail.html 13 Sep 2009 23:54:40 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/install-squirrelmail.html 11 Dec 2010 23:36:32 -0000 1.14 @@ -1,11 +1,11 @@ - -Install Squirrelmail for use as a webmail system for OpenACS
Prev Appendix B. Install additional supporting software Next
Install Squirrelmail for use as a webmail system for OpenACS
By Malte Sussdorff
+ +Install Squirrelmail for use as a webmail system for OpenACS
Prev Appendix B. Install additional supporting software Next
Install Squirrelmail for use as a webmail system for OpenACS
By Malte Sussdorff
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd www -[$OPENACS_SERVICE_NAME www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz -[$OPENACS_SERVICE_NAME www]# tar xfz squirrelmail-1.4.4.tar.gz -[$OPENACS_SERVICE_NAME www]# mv squirrelmail-1.4.4 mail -[$OPENACS_SERVICE_NAME www]# cd mail/config -[$OPENACS_SERVICE_NAME www]# ./conf.pl +
This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd www +[$OPENACS_SERVICE_NAME www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz +[$OPENACS_SERVICE_NAME www]# tar xfz squirrelmail-1.4.4.tar.gz +[$OPENACS_SERVICE_NAME www]# mv squirrelmail-1.4.4 mail +[$OPENACS_SERVICE_NAME www]# cd mail/config +[$OPENACS_SERVICE_NAME www]# ./conf.pl
Now you are about to configure Squirrelmail. The configuration heavily depends on your setup, so no instructions are given here.
Prev Home Next
Install PHP for use in AOLserver Up Install PAM Radius for use as external authentication
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-ssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/install-ssl.html 13 Sep 2009 23:54:40 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/install-ssl.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,33 +1,33 @@ - -Installing SSL Support for an OpenACS service
Prev Chapter 6. Production Environments Next
Installing SSL Support for an OpenACS service
Debian Users: apt-get install openssl before proceeding.
Make sure nsopenssl.so is installed for AOLserver.
Uncomment this line from config.tcl.
#ns_param nsopenssl ${bindir}/nsopenssl.so -
Prepare a certificate directory for the service.
[$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs -[$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs + +Installing SSL Support for an OpenACS service
Prev Chapter 6. Production Environments Next
Installing SSL Support for an OpenACS service
Debian Users: apt-get install openssl before proceeding.
Make sure nsopenssl.so is installed for AOLserver.
Uncomment this line from config.tcl.
#ns_param nsopenssl ${bindir}/nsopenssl.so +
Prepare a certificate directory for the service.
[$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs [$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs -chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
Use an OpenSSL perl script to generate a certificate and key.
+chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs
It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.
Use an OpenSSL perl script to generate a certificate and key.
Debian users: use /usr/lib/ssl/misc/CA.pl instead of /usr/share/ssl/CA
Mac OS X users: use perl /System/Library/OpenSSL/misc/CA.pl -newcert instead of /usr/share/ssl/CA -
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs -[$OPENACS_SERVICE_NAME certs]$ perl /usr/share/ssl/misc/CA -newcert +
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME certs]$ perl /usr/share/ssl/misc/CA -newcert Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key ...++++++ .......++++++ writing new private key to 'newreq.pem' Enter PEM pass phrase:
Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this:
Certificate (and private key) is in newreq.pem -[$OPENACS_SERVICE_NAME certs]$
newreq.pem contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
[root misc]# openssl rsa -in newreq.pem -out keyfile.pem +[$OPENACS_SERVICE_NAME certs]$
newreq.pem contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.
[root misc]# openssl rsa -in newreq.pem -out keyfile.pem read RSA key Enter PEM pass phrase: writing RSA key -[$OPENACS_SERVICE_NAME certs]$
To create the certificate file, we take the combined file, copy it, and strip out the key.
[$OPENACS_SERVICE_NAME certs]$ cp newreq.pem certfile.pem -[root misc]# emacs certfile.pem
Strip out the section that looks like
-----BEGIN RSA PRIVATE KEY----- +[$OPENACS_SERVICE_NAME certs]$
To create the certificate file, we take the combined file, copy it, and strip out the key.
[$OPENACS_SERVICE_NAME certs]$ cp newreq.pem certfile.pem +[root misc]# emacs certfile.pem
Strip out the section that looks like
-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997 S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T (11 lines omitted) 1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw== ------END RSA PRIVATE KEY-----
+-----END RSA PRIVATE KEY-----
If you start up using the etc/daemontools/run script, you will need to edit this script to make sure the ports are bound for SSL. Details of this are in the run script. Index: openacs-4/packages/acs-core-docs/www/install-steps.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.html,v diff -u -N -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/install-steps.html 17 Oct 2010 21:06:08 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/install-steps.html 11 Dec 2010 23:36:32 -0000 1.33 @@ -1,96 +1,97 @@ - -Basic Steps
Prev Chapter 2. Installation Overview Next
Basic Steps
+ +Basic Steps
Prev Chapter 2. Installation Overview Next
Basic Steps
The basic steps for installing OpenACS are: -
Install an OS and supporting software (see Install a Unix-like OS or Appendix A, Install Red Hat 8/9 for more details). See the Table 2.2.
Install a database (see Section , “Install Oracle 8.1.7” or - Install PostgreSQL).
Install AOLserver (Install AOLserver 4) .
Create a unique database and system user. +
Install an OS and supporting software (see Install a Unix-like OS or Appendix A. Install Red Hat 8/9 for more details). See the Table 2.2. Version Compatibility Matrix.
Install a database (see Install Oracle 8.1.7 or + Install PostgreSQL).
Install AOLserver (Install AOLserver 4) .
Create a unique database and system user. Install the OpenACS tarball, start and AOLserver instance, and use the OpenACS web pages to complete installation - (see Install OpenACS 5.6.0).
Specific instructions are available for Mac OS X and - Windows2000 (see Section , “OpenACS Installation Guide for Mac OS X” or - Section , “OpenACS Installation Guide for Windows2000”).
Binaries and other shortcuts
You can try out OpenACS using some binary installers. In + (see Install OpenACS 5.6.0).
Specific instructions are available for Mac OS X and + Windows2000 (see OpenACS Installation Guide for Mac OS X or + OpenACS Installation Guide for Windows2000).
Binaries and other shortcuts
You can try out OpenACS using some binary installers. In general, they are not yet supported by the community, so they are - mostly for evaluation purposes. Installing - OpenACS
You can see a list of current installers. -
+ mostly for evaluation purposes. Installing + OpenACS
You can see a list of current installers. +
The packaged version of - PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.
Once AOLserver and a database are installed, a bash script automates the OpenACS checkout and + PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.
Once AOLserver and a database are installed, a bash script automates the OpenACS checkout and installation. -
System Requirements
+
System Requirements
You will need a PC (or equivalent) with at least these minimum specifications: -
128MB RAM (much more if you want Oracle)
1GB free space on your hard drive (much more if you want Oracle)
A Unix-like operating system with Tcl, tDOM, and - a mail transport agent like sendmail or qmail. (see Section , “Prerequisite Software”)
+
128MB RAM (much more if you want Oracle)
1GB free space on your hard drive (much more if you want Oracle)
A Unix-like operating system with Tcl, tDOM, and + a mail transport agent like sendmail or qmail. (see Prerequisite Software)
All of the software mentioned is open-source and available without direct costs, except for Oracle. You can obtain a free copy of Oracle for - development purposes. This is described in the Acquire Oracle section. -
How to use this guide
This is text you will see on - screen, such as a Button or link - in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to - examine or edit:
if {$database == "oracle"} { - set db_password "mysitepassword" -}
This is text that you will - see and type in a command shell, including text you may have to + development purposes. This is described in the Acquire Oracle section. +
How to use this guide
This is text you will see on + screen, such as a Button or link + in a radio button list or menu.
This is text that you will type.
This is text from a program or file which you may need to + examine or edit:
if {$database == "oracle"} { + set db_password "mysitepassword" +}
This is text that you will + see and type in a command shell, including text you may have to change. It is followed by a list of just the commands, - which you can copy and paste. The command prompt varies by system; in the examples we use the form[$OPENACS_SERVICE_NAME aolserver]$, where $OPENACS_SERVICE_NAME is the current user and aolserver is the current directory. The root prompt is shown ending in # and all other prompts in $.
-[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ svc -d /service/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ dropdb $OPENACS_SERVICE_NAME + which you can copy and paste. The command prompt varies by system; in the examples we use the form[$OPENACS_SERVICE_NAME aolserver]$, where $OPENACS_SERVICE_NAME is the current user and aolserver is the current directory. The root prompt is shown ending in # and all other prompts in $.
+[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ svc -d /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASE -[$OPENACS_SERVICE_NAME aolserver]$ createdb $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ createdb $OPENACS_SERVICE_NAME CREATE DATABASE su - $OPENACS_SERVICE_NAME svc -d /service/$OPENACS_SERVICE_NAME dropdb $OPENACS_SERVICE_NAME -createdb $OPENACS_SERVICE_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 ( /etc/share/skel/dot.profile for FreeBSD) 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 server yourserver.test
name of administrative access account remadmin
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 /var/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 ( /etc/share/skel/dot.profile for FreeBSD) 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 server yourserver.test
name of administrative access account remadmin
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 /var/tmp
The OpenACS tarball contains some files which are useful while setting up other software. Those - files are located at: /var/tmp/openacs-5.6.0/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
+ files are located at:
/var/tmp/openacs-5.6.0/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 the values that we've chosen. The values that you'll probably want to change, such as service name, are marked like this. The other values we recommend you leave unchanged unless you have a - reason to change them.
Note
+ reason to change them.
Note
Some of the paths and user accounts have been changed from those recommended in previous versions of this document to - improve security and maintainability. See this - thread for discussion.
Getting Help during installation
+ improve security and maintainability. See this + thread for discussion.
Getting Help during installation
We'll do our best to assure that following our instructions will get you to the promised land. If something goes wrong, don't panic. There are plenty of ways to get help. Here are some tips: -
+
Keep track of the commands you are run and record their output. I like to do my installations in a shell inside of emacs - (M-x shell) so that I can save + (M-x shell) so that I can save the output if needed. An alternative would be to use the - script command. -
+ script command. +
We'll point out where the error logs for the various pieces of software are. Output from those logs will help us help you. Don't worry if you feel overwhelmed by all the information in the error logs. Over time, you'll find that they make more and more sense. Soon, you'll actually look forward to errors so that you can run to the log and diagnose the problem. -
- Search the forums at +
+ Search the forums at openacs.org - you'll often find many people who have struggled through the same spot that you're in. -
+
The bottom of each page has a link to OpenACS.org, where you can post comments and read other users comments about the contents of the page. -
- Ask questions at the irc channel on freenode.net +
+ Ask questions at the irc channel on freenode.net (#openacs). They're knowledgeable and quite friendly if you can keep them on topic. -
- Post a question on the forums. Make sure +
+ Post a question on the forums. Make sure you've done a search first. When you do post, be sure to include your setup information (OS, etc) as well as the exact commands that are failing with the accompanying error. If there's a SQL error in the TCL error or in the log, post that too. -
+
If you find errors in this document or if you have ideas about making it better, please post them in our - BugTracker. + BugTracker.
($Id$)
Prev Home Next
Chapter 2. Installation Overview Up Prerequisite Software
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.html,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 13 Sep 2009 23:54:40 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 11 Dec 2010 23:36:32 -0000 1.18 @@ -1,5 +1,5 @@ - -Install tclwebtest.
Prev Appendix B. Install additional supporting software Next
Install tclwebtest.
Download the tclwebtest + +Install tclwebtest.
Prev Appendix B. Install additional supporting software Next
Install tclwebtest.
Download the tclwebtest source, unpack it, and put it an appropriate place. (tclwebtest 1.0 will be required for auto-tests in OpenACS 5.1. When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) As root:
cd /tmp cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tclwebtest co tclwebtest Index: openacs-4/packages/acs-core-docs/www/ix01.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v diff -u -N -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/ix01.html 17 Oct 2010 21:06:08 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/ix01.html 11 Dec 2010 23:36:32 -0000 1.27 @@ -1,3 +1,3 @@ - -Index
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)
D
daemontools
installation, Install Daemontools (OPTIONAL)
docbook
installation, Install Red Hat 8/9
DocBook
DTD, OpenACS Documentation Strategy: Why DocBook?
emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
Document structure, Document Structure
E
emacs
installation, Install Red Hat 8/9
emphasis
bold, italics, Emphasis
F
full text search
installation, Install Tsearch2 module, 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
upgrade
OpenACS 4.5 to 4.6.x
Linux/Unix, Upgrading 4.5 or higher to 4.6.3
X
XML guidelines, OpenACS Documentation Strategy: Why DocBook?
xref
linkend, Links
xreflabel, Headlines, Sections
Prev Home
How to Update the translations Up
docs@openacs.org
View comments on this page at openacs.org + +Index
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, OpenACS Documentation Strategy: Why DocBook?
emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL)
Document structure, Document Structure
E
emacs
installation, Install Red Hat 8/9
emphasis
bold, italics, Emphasis
F
full text search
installation, Install Tsearch2 module, 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
upgrade
OpenACS 4.5 to 4.6.x
Linux/Unix, Upgrading 4.5 or higher to 4.6.3
X
XML guidelines, OpenACS Documentation Strategy: Why DocBook?
xref
linkend, Links
xreflabel, Headlines, Sections
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/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -N -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 17 Oct 2010 21:06:08 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 11 Dec 2010 23:36:32 -0000 1.35 @@ -1,2 +1,2 @@ - -Chapter 15. Kernel Documentation
Prev Part IV. For OpenACS Platform Developers Next
Chapter 15. Kernel Documentation
Table of Contents
Overview
Object Model Requirements
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
Bootstrapping OpenACS
External Authentication Requirements
Section missingSection missing
Prev Home Next
Part IV. For OpenACS Platform Developers Up Overview
docs@openacs.org
View comments on this page at openacs.org + +Chapter 14. Kernel Documentation
Prev Part IV. For OpenACS Platform Developers Next
Chapter 14. Kernel Documentation
Table of Contents
Overview
Object Model Requirements
Object Model Design
Permissions Requirements
Permissions Design
Groups Requirements
Groups Design
Subsites Requirements
Subsites Design Document
Package Manager Requirements
Package Manager Design
Database Access API
OpenACS Internationalization Requirements
Security Requirements
Security Design
Security Notes
Request Processor Requirements
Request Processor Design
Documenting Tcl Files: Page Contracts and Libraries
Bootstrapping OpenACS
External Authentication Requirements
Prev Home Next
Part IV. For OpenACS Platform Developers Up Overview
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -N -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 17 Oct 2010 21:06:08 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 11 Dec 2010 23:36:32 -0000 1.29 @@ -1,17 +1,17 @@ - -Overview
Prev Chapter 15. Kernel Documentation Next
Overview
+ +Overview
Prev Chapter 14. Kernel Documentation Next
Overview
The OpenACS Kernel, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package management and deployment. -
+
The OpenACS Core, which comprises all the other packages that ship with the kernel and are most frequently needed by users, such as templating, forums, and user registration/management. The packages tend to be developed and distributed with the kernel. -
+
OpenACS Application packages, which typically provide user-level @@ -22,5 +22,5 @@
This document provides a high level overview of the kernel - package. Documentation for other packages on this server -
Prev Home Next
Chapter 15. Kernel Documentation Up Object Model Requirements
docs@openacs.org
View comments on this page at openacs.org + package. Documentation for other packages on this server +
Prev Home Next
Chapter 14. Kernel Documentation Up Object Model Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/mac-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/mac-installation.html,v diff -u -N -r1.39 -r1.40 --- openacs-4/packages/acs-core-docs/www/mac-installation.html 13 Sep 2009 23:54:40 -0000 1.39 +++ openacs-4/packages/acs-core-docs/www/mac-installation.html 11 Dec 2010 23:36:32 -0000 1.40 @@ -1,9 +1,9 @@ - -OpenACS Installation Guide for Mac OS X
Prev Chapter 3. Complete Installation Next
OpenACS Installation Guide for Mac OS X
Prerequisites. Install readline:
Download readline from http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz into /usr/local/src
Extract readline in /usr/local/src, configure, compile, and install:
su - root + +OpenACS Installation Guide for Mac OS XPrev Chapter 3. Complete Installation Next
OpenACS Installation Guide for Mac OS X Prerequisites. Install readline:
Download readline from http://ftp.gnu.org/pub/gnu/readline/readline-4.3.tar.gz into /usr/local/src
Extract readline in /usr/local/src, configure, compile, and install:
su - root cd /usr/local/src tar xvfz readline-4.3.tar.gz readline-4.3 ./configure make -make install
Proceed with the Unix-like system instructions. OS X is incompatible with Oracle 8, and Oracle 9i on OSX is not yet verified for OpenACS. So continue with Install PostgreSQL. Additional special steps for OS X are documented inline with the standard Unix-like instructions.
Additional resources for installing on OS X.
OpenACS on Mac OS X Quickstart
An +make install
Proceed with the Unix-like system instructions. OS X is incompatible with Oracle 8, and Oracle 9i on OSX is not yet verified for OpenACS. So continue with Install PostgreSQL. Additional special steps for OS X are documented inline with the standard Unix-like instructions.
Additional resources for installing on OS X.
OpenACS on Mac OS X Quickstart
An older forum thread
($Id$)
Prev Home Next
OpenACS Installation Guide for Windows2000 Up Chapter 4. Configuring a new OpenACS Site
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.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/maint-performance.html 17 Oct 2010 21:06:08 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/maint-performance.html 11 Dec 2010 23:36:32 -0000 1.27 @@ -1,8 +1,8 @@ - -Diagnosing Performance Problems
Prev Chapter 6. Production Environments Next
Diagnosing Performance Problems
Did performance problems happen overnight, or did they sneak up on + +Diagnosing Performance Problems
Prev Chapter 6. Production Environments Next
Diagnosing Performance Problems
Did performance problems happen overnight, or did they sneak up on you? Any clue what caused the performance problems (e.g. loading 20K - users into .LRN)
Is the file system out of space? Is the machine swapping to disk constantly?
Isolating and solving database problems.
Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see Section , “Vacuum Postgres nightly”. For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
You can track the exact amount of time each database query on a page takes:
Go to Main Site : Site-Wide Administration : Install Software
Click on "Install New Application" in "Install from OpenACS Repository"
Choose "ACS Developer Support">
After install is complete, restart the server.
Browse to Developer Support, which is automatically mounted at /ds. -
Turn on Database statistics
Browse directly to a slow page and click "Request Information" at the bottom of the page.
This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
Figure 6.8. Query Analysis example
Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process.
Log in to SQL*Plus as the admin:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl + users into .LRN)
Is the file system out of space? Is the machine swapping to disk constantly?
Isolating and solving database problems.
Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see Vacuum Postgres nightly. For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes).
You can track the exact amount of time each database query on a page takes:
Go to Main Site : Site-Wide Administration : Install Software
Click on "Install New Application" in "Install from OpenACS Repository"
Choose "ACS Developer Support">
After install is complete, restart the server.
Browse to Developer Support, which is automatically mounted at /ds. +
Turn on Database statistics
Browse directly to a slow page and click "Request Information" at the bottom of the page.
This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took.
Figure 6.8. Query Analysis example

Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process.
Log in to SQL*Plus as the admin:
[$OPENACS_SERVICE_NAME ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production @@ -12,7 +12,7 @@ With the Partitioning option JServer Release 8.1.7.3.0 - Production -SVRMGR> connect internal +SVRMGR> connect internal Password:
See all of the running queries, and match the UNIX PID:
select p.spid -- The UNIX PID ,s.sid ,s.serial# ,p.username as os_user @@ -27,7 +27,7 @@ where sql.address = s.sql_address and sql.hash_value = s.sql_hash_value --and upper(s.username) like 'USERNAME%' - order by s.username ,s.sid ,s.serial# ,sql.piece ;
To kill a troubled process:
alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL#
(See Andrew Piskorski's Oracle notes)
Identify a runaway Postgres query. First, logging must be enabled in the database. This imposes a performance penalty and should not be done in normal operation.
Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
#stats_command_string = false
to
stats_command_string = true
Next, connect to postgres (psql service0) and select * from pg_stat_activity;. Typical output should look like:
+ order by s.username ,s.sid ,s.serial# ,sql.piece ;
To kill a troubled process:
alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL#
(See Andrew Piskorski's Oracle notes)
Identify a runaway Postgres query. First, logging must be enabled in the database. This imposes a performance penalty and should not be done in normal operation.
Edit the file postgresql.conf - its location depends on the PostGreSQL installation - and change
#stats_command_string = false
to
stats_command_string = true
Next, connect to postgres (psql service0) and select * from pg_stat_activity;. Typical output should look like:
datid | datname | procpid | usesysid | usename | current_query ----------+-------------+---------+----------+---------+----------------- 64344418 | openacs.org | 14122 | 101 | nsadmin | <IDLE> @@ -42,7 +42,7 @@ 64344418 | openacs.org | 14311 | 101 | nsadmin | <IDLE> 64344418 | openacs.org | 14549 | 101 | nsadmin | <IDLE> (8 rows) -openacs.org=>
Creating an appropriate tuning and monitoring environment
+openacs.org=>
Creating an appropriate tuning and monitoring environment
The first task is to create an appropriate environment for finding out what is going on inside Oracle. Oracle provides Statspack, a package to monitor and save the state of the v$ performance views. These reports @@ -58,13 +58,13 @@ Oracle Support information.
To be able to get a overview of how Oracle executes a particular query, - install "autotrace". I usually follow the instructions here http://asktom.oracle.com/~tkyte/article1/autotrace.html. -
Make sure, that the Oracle CBO works with adequate statistics
+ 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
The Oracle Cost Based optimizer is a piece of software that tries to find - the "optimal" execution plan for a given SQL statement. For that it + the "optimal" execution plan for a given SQL statement. For that it estimates the costs of running a SQL query in a particular way (by default up to 80.000 permutations are being tested in a Oracle 8i). To get an adequate cost estimate, the CBO needs to have adequate statistics. For - that Oracle supplies the dbms_stats + that Oracle supplies the dbms_stats package.
Prev Home Next
External uptime validation Up Chapter 7. Database Management
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.html,v diff -u -N -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 17 Oct 2010 21:06:08 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 11 Dec 2010 23:36:32 -0000 1.22 @@ -1,8 +1,8 @@ - -Staged Deployment for Production Networks
Prev Chapter 6. Production Environments Next
Staged Deployment for Production Networks
($Id$)
By Joel Aufrecht
+ +Staged Deployment for Production Networks
Prev Chapter 6. Production Environments Next
Staged Deployment for Production Networks
($Id$)
By Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
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 +
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 @@ -42,7 +42,7 @@ /usr/local/pgsql/bin/psql -f /var/lib/aolserver/service0-dev/packages/acs-kernel/sql/postgresql/postgresql.sql service0 mv /var/lib/aolserver/service0/database-backup/service0-nightly-backup.dmp.gz /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp.gz /bin/gunzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp.gz -/usr/bin/perl -pi -e "s/^\\connect service0$/\\connect service0-dev/" /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp +/usr/bin/perl -pi -e "s/^\\connect service0$/\\connect service0-dev/" /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp /usr/local/pgsql/bin/psql service0-dev < /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp /usr/local/bin/svc -u /service/service0-dev /bin/gzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp @@ -59,12 +59,12 @@ the lines starting > will be added and the lines starting < will be removed, when you commit if that looks okay, commit with: -cvs -m "changing text on front page for February conference" index.adp -the stuff in -m "service0" is a comment visible only from within cvs commands +cvs -m "changing text on front page for February conference" index.adp +the stuff in -m "service0" is a comment visible only from within cvs commands
To make these changes take place on service0:
4) update the file on production: cd /var/lib/aolserver/service0/www cvs up -Pd index.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
Figure 6.3. Simple A/B Deployment - Step 2
Figure 6.4. Simple A/B Deployment - Step 3
Complex A/B Deployment: Database is changed
Figure 6.5. Complex A/B Deployment - Step 1
Figure 6.6. Complex A/B Deployment - Step 2
Figure 6.7. 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 + 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

Figure 6.3. Simple A/B Deployment - Step 2

Figure 6.4. Simple A/B Deployment - Step 3

Complex A/B Deployment: Database is changed
Figure 6.5. Complex A/B Deployment - Step 1

Figure 6.6. Complex A/B Deployment - Step 2

Figure 6.7. 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/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -N -r1.37 -r1.38 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 13 Sep 2009 23:54:40 -0000 1.37 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 11 Dec 2010 23:36:32 -0000 1.38 @@ -1,5 +1,5 @@ - -Chapter 6. Production Environments
Prev Part II. Administrator's Guide Next
Chapter 6. Production Environments
Table of Contents
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems
by Joel Aufrecht
+ +Chapter 6. Production Environments
Prev Part II. Administrator's Guide Next
Chapter 6. Production Environments
Table of Contents
Starting and Stopping an OpenACS instance.
AOLserver keepalive with inittab
Running multiple services on one machine
High Availability/High Performance Configurations
Staged Deployment for Production Networks
Installing SSL Support for an OpenACS service
Set up Log Analysis Reports
External uptime validation
Diagnosing Performance Problems
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
Prev Home Next
Upgrading Platform components Up Starting and Stopping an OpenACS instance.
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/nxml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/nxml-mode.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/nxml-mode.html 17 Oct 2010 21:06:08 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/nxml-mode.html 11 Dec 2010 23:36:32 -0000 1.16 @@ -1,11 +1,11 @@ - -Using nXML mode in Emacs
Prev Chapter 13. Documentation Standards Next
Using nXML mode in Emacs
By Jeff Davis
+ +Using nXML mode in Emacs
Prev Chapter 12. Documentation Standards Next
Using nXML mode in Emacs
By Jeff Davis
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
An alternative to psgml mode is nXML by James Clark, a new major mode for GNU Emacs for editing XML, and which features highlighting, indentation, and on the fly validation versus a RelaxNG Schema. -
An - introduction to nXML mode at xmlhack.com. -
The nXML mode mail list at groups.yahoo.com. -
The nXML download page at thaiopensource.com.
Prev Home Next
Using PSGML mode in Emacs Up Detailed Design Documentation Template
docs@openacs.org
View comments on this page at openacs.org +
An + introduction to nXML mode at xmlhack.com. +
The nXML mode mail list at groups.yahoo.com. +
The nXML download page at thaiopensource.com.
Prev Home Next
Using PSGML mode in Emacs Up System/Application Requirements Template
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/object-identity.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,10 +1,10 @@ - -Object Identity
Prev Chapter 11. Development Reference Next
Object Identity
By Rafael H. Schloming
+ +Object Identity
Prev Chapter 10. Development Reference Next
Object Identity
By Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
One of the major design features of OpenACS 5.6.0 is the explicit representation -of object identity. The reason I say "explicit -representation" is because the concept of object identity has been +of object identity. The reason I say "explicit +representation" is because the concept of object identity has been around forever. It is inherent to our problem domain. Consider the example of 3.x style scoping. The 3.x data models use the triple (user_id, group_id, scope) to identify an object. In the 5.6.0 data model this @@ -32,4 +32,4 @@ even capable of fully tracking the history of membership state.
The design choice of explicitly representing object identity with an integer primary key that is derived from a globally unique sequence is the key to eliminating redundant code and replacing it with generic object -level services.
($Id$)
Prev Home Next
OpenACS Permissions Tediously Explained Up Programming with AOLserver
docs@openacs.org
View comments on this page at openacs.org +level services.
($Id$)
Prev Home Next
Parties in OpenACS Up Programming with AOLserver
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 13 Sep 2009 23:54:40 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,86 +1,86 @@ - -Object Model Design
Prev Chapter 14. Kernel Documentation Next
Object Model Design
By Pete Su, Michael Yoon, Richard Li, Rafael Schloming
+ +Object Model Design
Prev Chapter 14. Kernel Documentation Next
Object Model Design
By Pete Su, Michael Yoon, Richard Li, Rafael Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Essentials
Data Model
-acs-metadata-create.sql
-acs-objects-create.sql
-acs-relationships-create.sql
Tcl Files
Not yet linked.
Requirements
Object Model -Requirements
Groups -Requirements
Permissions -Requirements
Introduction
Before OpenACS 4, software developers writing OpenACS applications or modules +
Essentials
Data Model
+acs-metadata-create.sql
+acs-objects-create.sql
+acs-relationships-create.sql
Tcl Files
Not yet linked.
Requirements
Object Model +Requirements
Groups +Requirements
Permissions +Requirements
Introduction
Before OpenACS 4, software developers writing OpenACS applications or modules would develop each data model separately. However, many applications built on OpenACS share certain characteristics or require certain common services. -Examples of such services include:
User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and -so forth)
Presentation tools (e.g. how to display a field in a form or on a +Examples of such services include:
User comments
Storage of user-defined or extensible sets of attributes
Access control
General auditing and bookkeeping (e.g. creation date, IP addresses, and +so forth)
Presentation tools (e.g. how to display a field in a form or on a page)
All of these services involve relating additional service-related information to application data objects. Examples of application objects -include:
forum messages
A user home page
A ticket in the ticket tracker
In the past, developers had to use ad-hoc and inconsistent schemes to -interface to various "general" services. OpenACS 4 defines a central +include:
forum messages
A user home page
A ticket in the ticket tracker
In the past, developers had to use ad-hoc and inconsistent schemes to +interface to various "general" services. OpenACS 4 defines a central data model that keeps track of the application objects that we wish to manage, and serves as a primary store of metadata. By metadata, we mean data stored on behalf of an application outside of the application's data model in order to enable certain central services. The OpenACS 4 Object Model (or object system) manages several different kinds of data and metadata to allow us to provide general -services to applications:
Object Identification
Every application object is given a unique identifier in the system. This +services to applications:
Object Identification
Every application object is given a unique identifier in the system. This identifier can be used to find all data related to a particular object. -
Object Context and Access Control
Every object is created in a particular security context, so the system +
Object Context and Access Control
Every object is created in a particular security context, so the system can provide centralized access control. -
Object Types and Attributes
Objects are instances of developer-defined object types. Object types +
Object Types and Attributes
Objects are instances of developer-defined object types. Object types allow developers to customize the data that is stored with each object. -
Relation Types
Relation types provide a general mechanism for mapping instances of one +
Relation Types
Relation types provide a general mechanism for mapping instances of one object type (e.g. users) to instances of another object type (e.g. groups).
The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.
Related Links
This design document should be read along with the design documents for the new groups system, subsites and the permissions system
History
The motivation for most of the facilities in the OpenACS 4 Object Model can be +particular programming idioms that we wish to generalize.
Related Links
This design document should be read along with the design documents for the new groups system, subsites and the permissions system
History
The motivation for most of the facilities in the OpenACS 4 Object Model can be understood in the context of the 3.x code base and the kinds of programming -idioms that evolved there. These are listed and discussed below.
Object Identification
Object identification is a central mechanism in OpenACS 4. Every application +idioms that evolved there. These are listed and discussed below.
Object Identification
Object identification is a central mechanism in OpenACS 4. Every application object in OpenACS 4 has a unique ID which is mapped to a row in a central table -called acs_objects. Developers that wish to use OpenACS 4 services +called acs_objects. Developers that wish to use OpenACS 4 services need only take a few simple steps to make sure that their application objects appear in this table. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. In other words, we use object identifiers to enable centralized services in a global and uniform manner.
Implicit Object Identifiers in OpenACS 3.x
The motivation for implementing general object identifiers comes from several observations of data models in OpenACS 3.x. Many modules use a -(user_id, group_id, scope) column-triple for the purpose of +(user_id, group_id, scope) column-triple for the purpose of recording ownership information on objects, for access control. User/groups -also uses (user_id, group_id) pairs in its -user_group_map table as a way to identify data associated with a +also uses (user_id, group_id) pairs in its +user_group_map table as a way to identify data associated with a single membership relation.
Also, in OpenACS 3.x many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, -general comments maintains a table that maps application "page" +general comments maintains a table that maps application "page" data (static or dynamic pages on the website) to one or more user comments on that page. It does so by constructing a unique identifier for each page, usually a combination of the table in which the data is stored, and the value of the primary key value for the particular page. This idiom is referred to -as the "(on_which_table + on_what_id)" method for identifying +as the "(on_which_table + on_what_id)" method for identifying application data. In particular, general comments stores its map from pages -to comments using a "(on_which_table + on_what_id)" key plus the ID +to comments using a "(on_which_table + on_what_id)" key plus the ID of the comment itself.
All of these composite key constructions are implicit object identifiers - they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent, making the construction of generic application-independent services unnecessarily difficult.
Object Identifiers in OpenACS 4
The OpenACS 4 Object Model defines a single mechanism that applications use to attach unique identifiers to application data. This identifier is the primary -key of the acs_objects table. This table forms the core of what +key of the acs_objects table. This table forms the core of what we need to provide generic services like access control, general attribute storage, general presentation and forms tools, and generalized administrative interfaces. In addition, the object system provides an API that makes it easy to create new objects when creating application data. All an application must do to take advantage of general services in OpenACS 4 is to use the new API to make sure every object the system is to manage is associated with a row in -acs_objects. More importantly, if they do this, new services +acs_objects. More importantly, if they do this, new services like general comments can be created without requiring existing applications -to "hook into" them via new metadata.
Note: Object identifiers are a good example of metadata -in the new system. Each row in acs_objects stores information +to "hook into" them via new metadata.
Note: Object identifiers are a good example of metadata +in the new system. Each row in acs_objects stores information about the application object, but not the application object itself. This becomes more clear if you skip ahead and look at the SQL schema code -that defines this table.
Object Context and Access Control
Until the implementation of the general permissions system, every OpenACS +that defines this table.
Object Context and Access Control
Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a -notion of "scoping" was introduced into the core data model.
"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:
... scope user_id group_id ...
... user 123 ...
... group 456 ...
... public ...
The first row represents an entry in User 123's personal address book, +notion of "scoping" was introduced into the core data model.
"Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table:
... scope user_id group_id ...
... user 123 ...
... group 456 ...
... public ...
The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.
In this way, the scoping columns identify the security context in which a @@ -94,29 +94,29 @@ forum message would probably list a forum topic as its context, and a forum topic might list a subsite as its context. Thus, contexts make it easier to break the site up into security domains according to its natural -structure. An object's context is stored in the context_id -column of the acs_objects table.
We use an object's context to provide a default answer to questions -regarding access control. Whenever we ask a question of the form "can -user X perform action Y on object Z", the OpenACS security model will defer +structure. An object's context is stored in the context_id +column of the acs_objects table.
We use an object's context to provide a default answer to questions +regarding access control. Whenever we ask a question of the form "can +user X perform action Y on object Z", the OpenACS security model will defer to an object's context if there is no information about user X's permission to perform action Y on object Z.
The context system forms the basis for the rest of the OpenACS access control -system, which is described in in two separate documents: one for the permissions system and another for the -party groups system. The context system -is also used to implement subsites.
Object Types
As mentioned above, many OpenACS modules provide extensible data models, and +system, which is described in in two separate documents: one for the permissions system and another for the +party groups system. The context system +is also used to implement subsites.
Object Types
As mentioned above, many OpenACS modules provide extensible data models, and need to use application specific mechanisms to keep track of user defined attributes and to map application data to these attributes. In the past, modules either used user/groups or their own ad hoc data model to provide this functionality.
User/Groups in OpenACS 3.x
The user/group system allowed developers to define group types along with attributes to be stored with each instance of a group type. Each group type could define a helper table that stored attributes on each instance of the group type. This table was called the -"_info" table because the name was generated by -appending _info to the name of the group type.
The user/groups data model also provided the -user_group_type_member_fields and -user_group_member_fields tables to define attributes for members +"_info" table because the name was generated by +appending _info to the name of the group type.
The user/groups data model also provided the +user_group_type_member_fields and +user_group_member_fields tables to define attributes for members of groups of a specific type and for members of a specific group, -respectively. The user_group_member_field_map table stored -values for both categories of attributes in its field_value +respectively. The user_group_member_field_map table stored +values for both categories of attributes in its field_value column. These tables allowed developers and users to define custom sets of attributes to store on groups and group members without changing the data model at the code level.
Many applications in OpenACS 3.x and earlier used the group type mechanism in @@ -131,39 +131,39 @@ The motivation for subtypes comes from the need for OpenACS to be more extensible. In OpenACS 3.x, many applications extended the core data models by directly adding more columns, in order to provide convenient access to new -information. This resulted in core data tables that were too "fat", +information. This resulted in core data tables that were too "fat", containing a hodge podge of unrelated information that should have been normalized away. The canonical example of this is the explosion of the -users table in OpenACS 3.x. In addition to being sloppy technically, -these fat tables have a couple of other problems:
They degrade performance.
Denormalization can make it hard to maintain consistency constraints on +users table in OpenACS 3.x. In addition to being sloppy technically, +these fat tables have a couple of other problems:
They degrade performance.
Denormalization can make it hard to maintain consistency constraints on the data.
Object subtypes provide a way to factor the data model while still keeping track of the fact that each member of a subtype (i.e. for each row in the subtype's table), is also a member of the parent type (i.e. there is a corresponding row in the parent type table). Therefore, applications an use this mechanism without worrying about this bookkeeping themselves, and we avoid having applications pollute the core data model with their specific -information.
Object Attributes, Skinny Tables
As we described above, the OpenACS 3.x user/groups system stored object +information.
Object Attributes, Skinny Tables
As we described above, the OpenACS 3.x user/groups system stored object attributes in two ways. The first was to use columns in the helper table. The second consisted of two tables, one describing attributes and one storing values, to provide a flexible means for attaching attributes to metadata objects. This style of attribute storage is used in several other parts of -OpenACS 3.x, and we will refer to it as "skinny tables". For -example:
In the Ecommerce data model, the ec_custom_product_fields +OpenACS 3.x, and we will refer to it as "skinny tables". For +example:
In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the -ec_custom_product_field_values table stores values for those -attributes.
In the Photo DB data model, the ph_custom_photo_fields table +ec_custom_product_field_values table stores values for those +attributes.
In the Photo DB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention -"ph_user_<user_id>_custom_info" are used to +"ph_user_<user_id>_custom_info" are used to store values for those attributes.
In addition, there are some instances where we are not using this model -but should, e.g. the users_preferences table, which +but should, e.g. the users_preferences table, which stores preferences for registered users in columns such as -prefer_text_only_p and dont_spam_me_p. The -"standard" way for an OpenACS 3.x-based application to add to the list -of user preferences is to add a column to the users_preferences +prefer_text_only_p and dont_spam_me_p. The +"standard" way for an OpenACS 3.x-based application to add to the list +of user preferences is to add a column to the users_preferences table (exactly the kind of data model change that has historically complicated the process of upgrading to a more recent OpenACS version).
The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups -system. It defines a table called acs_attributes that record +system. It defines a table called acs_attributes that record what attributes belong to which object types, and how the attributes are stored. As before, attributes can either be stored in helper tables, or in a single central skinny table. The developer makes this choice on a case by @@ -173,53 +173,53 @@ skinny tables because doing so allows developers and users to dynamically update the set of attributes stored on an object without updating the data model at the code level. The bottom line: Helper tables are more functional -and more efficient, skinny tables are more flexible but limited.
Relation Types
Many OpenACS 3.x modules use mapping tables to model relationships +and more efficient, skinny tables are more flexible but limited.
Relation Types
Many OpenACS 3.x modules use mapping tables to model relationships between application objects. Again, the 3.x user/groups system provides the canonical example of this design style. In that system, there was a single -table called user_group_map that kept track of which users +table called user_group_map that kept track of which users belonged to what groups. In addition, as we discussed in the previous -section, the system used the user_group_member_fields and -user_group_member_fields_map tables to allow developers to +section, the system used the user_group_member_fields and +user_group_member_fields_map tables to allow developers to attach custom attributes to group members. In fact, these attributes were not really attached to the users, but to the fact that a user was a member of a particular group - a subtle but important distinction.
In OpenACS 4, relation types generalize this mechanism. Relation types allow developers to define general mappings from objects of a given type T, to other objects of a given type R. Each relation type is a subtype -of acs_object, extended with extra attributes that store +of acs_object, extended with extra attributes that store constraints on the relation, and the types of objects the relation actually maps. In turn, each instance of a relation type is an object that represents -a single fact of the form "the object t of type T is related to the -object r of type R." That is, each instance of a relation type is +a single fact of the form "the object t of type T is related to the +object r of type R." That is, each instance of a relation type is essentially just a pair of objects.
Relation types generalize mapping tables. For example, the 3.x user/groups data model can be largely duplicated using a single relation type describing -the "group membership" relation. Group types would then be subtypes +the "group membership" relation. Group types would then be subtypes of this membership relation type. Group type attributes would be attached to the relation type itself. Group member attributes would be attached to instances of the membership relation. Finally, the mapping table would be replaced by a central skinny table that the relation type system defines.
Relation types should be used when you want to be able to attach data to -the "fact" that object X and object Y are related to each other. On +the "fact" that object X and object Y are related to each other. On the face of it, they seem like a redundant mechanism however, since one could easily create a mapping table to do the same thing. The advantage of registering this table as a relation type is that in principle the OpenACS 4 object system could use the meta data in the types table to do useful things in a generic way on all relation types. But this mechanism doesn't really exist yet.
Relation types are a somewhat abstract idea. To get a better feel for -them, you should just skip to the data model.
Summary and Design Considerations
The OpenACS 4 Object Model is designed to generalize and unify the following +them, you should just skip to the data model.
Summary and Design Considerations
The OpenACS 4 Object Model is designed to generalize and unify the following mechanisms that are repeatedly implemented in OpenACS-based systems to manage -generic and application specific metadata:
Why not Object Databases?
The presence of a framework for subtyping and inheritance always brings up +generic and application specific metadata:
Why not Object Databases?
The presence of a framework for subtyping and inheritance always brings up the question of why we don't just use an object database. The main reason is that all of the major object database vendors ship products that are effectively tied to some set of object oriented programming languages. Their idea is to provide tight language-level integration to lower the -"impedance mismatch" between the database and the language. +"impedance mismatch" between the database and the language. Therefore, database objects and types are generally directly modeled on language level objects and types. Of course, this makes it nearly impossible to interact with the database from a language that does not have this tight coupling, and it limits the data models that we can write to ideas that are expressible in the host language. In particular, we lose many of the best features of the relational database model. This is a disaster from an ease of use standpoint. -
The "Object relational" systems provide an interesting +
The "Object relational" systems provide an interesting alternative. Here, some notion of subtyping is embedded into an existing SQL or SQL-like database engine. Examples of systems like this include the new Informix, PostgreSQL 7, and Oracle has something like this too. The main @@ -230,7 +230,7 @@ practice. Finally, object databases are not as widely used as traditional relational systems. They have not been tested as extensively and their scalability to very large databases is not proven (though some will disagree -with this statement).
Oracle
The conclusion: the best design is to add a limited notion of subtyping to +with this statement).
Oracle
The conclusion: the best design is to add a limited notion of subtyping to our existing relational data model. By doing this, we retain all the power of the relational data model while gaining the object oriented features we need most.
In the context of OpenACS 4, this means using the object model to make our @@ -241,25 +241,25 @@ the more limited domain of the metadata model, this is acceptable since the type hierarchy is fairly small. But the object system data model is not designed to support, for example, a huge type tree like the Java runtime -libraries might define.
This last point cannot be over-stressed: the object model is not -meant to be used for large scale application data storage. It is -meant to represent and store metadata, not application data.
Data Model
Like most data models, the OpenACS Core data model has two levels:
The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)
+libraries might define.
This last point cannot be over-stressed: the object model is not +meant to be used for large scale application data storage. It is +meant to represent and store metadata, not application data.
Data Model
Like most data models, the OpenACS Core data model has two levels:
The knowledge level (i.e. the metadata model)
The operational level (i.e. the concrete data model)
You can browse the data models themselves from here: -
-acs-metadata-create.sql
-acs-objects-create.sql
+
+acs-metadata-create.sql
+acs-objects-create.sql
acs-relationships-create.sql
(Note that we have subdivided the operational level into the latter two files.)
The operational level depends on the knowledge level, so we discuss the knowledge level first. In the text below, we include abbreviated versions of the SQL definitions of many tables. Generally, these match the actual definitions in the existing data model but they are meant to reflect design information, not implementation. Some less relevant columns may be left out, -and things like constraint names are not included.
Knowledge-Level Model
The knowledge level data model for OpenACS objects centers around three tables +and things like constraint names are not included.
Knowledge-Level Model
The knowledge level data model for OpenACS objects centers around three tables that keep track of object types, attributes, and relation types. The first -table is acs_object_types, shown here in an abbreviated +table is acs_object_types, shown here in an abbreviated form:
-create table acs_object_types ( +create table acs_object_types ( object_type varchar(100) not null primary key, supertype references acs_object_types (object_type), abstract_p char(1) default 'f' not null @@ -270,26 +270,26 @@ name_method varchar(30), type_extension_table varchar(30) ); -+
This table contains one row for every object type in the system. The key -things to note about this table are:
For every type, we store metadata for how to display this type in certain -contexts (pretty_name and pretty_plural).
If the type is a subtype, then its parent type is stored in the column -supertype.
We support a notion of "abstract" types that contain no +things to note about this table are:
For every type, we store metadata for how to display this type in certain +contexts (pretty_name and pretty_plural).
If the type is a subtype, then its parent type is stored in the column +supertype.
We support a notion of "abstract" types that contain no instances (as of 9/2000 this is not actually used). These types exist only to -be subtyped. An example might be a type representing "shapes" that +be subtyped. An example might be a type representing "shapes" that contains common characteristics of all shapes, but which is only used to create subtypes that represent real, concrete shapes like circles, squares, -and so on.
Every type defines a table in which one can find one row for every -instance of this type (table_name, id_column).
type_extension_table is for naming a table that stores extra -generic attributes.
The second table we use to describe types is acs_attributes. +and so on.
Every type defines a table in which one can find one row for every +instance of this type (table_name, id_column).
type_extension_table is for naming a table that stores extra +generic attributes.
The second table we use to describe types is acs_attributes. Each row in this table represents a single attribute on a specific object -type (e.g. the "password" attribute of the "user" type). +type (e.g. the "password" attribute of the "user" type). Again, here is an abbreviated version of what this table looks like. The actual table used in the implementation is somewhat different and is discussed in a separate document.
-create table acs_attributes ( +create table acs_attributes ( attribute_id integer not null primary key object_type not null references acs_object_types (object_type), attribute_name varchar(100) not null, @@ -305,38 +305,38 @@ max_n_values integer default 1 not null, static_p varchar(1) ); -+ -
The following points are important about this table:
Every attribute has a unique identifier.
Every attribute is associated with an object type.
We store various things about each attribute for presentation -(pretty_name, sort_order).
The data_type column stores type information on this +
The following points are important about this table:
Every attribute has a unique identifier.
Every attribute is associated with an object type.
We store various things about each attribute for presentation +(pretty_name, sort_order).
The data_type column stores type information on this attribute. This is not the SQL type of the attribute; it is just a human readable name for the type of data we think the attribute holds (e.g. -"String", or "Money"). This might be used later to -generate a user interface.
The sort_order column stores information about how to sort -the attribute values.
Attributes can either be stored explicitly in a table ("type -specific storage") or in a skinny table ("generic storage"). +"String", or "Money"). This might be used later to +generate a user interface.
The sort_order column stores information about how to sort +the attribute values.
Attributes can either be stored explicitly in a table ("type +specific storage") or in a skinny table ("generic storage"). In most cases, an attribute maps directly to a column in the table identified -by the table_name of the corresponding object type, although, as +by the table_name of the corresponding object type, although, as mentioned above, we sometimes store attribute values as key-value pairs in a -"skinny" table. However, when you ask the question "What are -the attributes of this type of object?", you don't really care about +"skinny" table. However, when you ask the question "What are +the attributes of this type of object?", you don't really care about how the values for each attribute are stored (in a column or as key-value -pairs); you expect to receive the complete list of all attributes.
The max_n_values and min_n_values columns +pairs); you expect to receive the complete list of all attributes.
The max_n_values and min_n_values columns encode information about the number of values an attribute may hold. -Attributes can be defined to hold 0 or more total values.
The static_p flag indicates whether this attribute value is +Attributes can be defined to hold 0 or more total values.
The static_p flag indicates whether this attribute value is shard by all instances of a type, as with static member fields in C++. Static attribute are like group level attributes in OpenACS 3.x.
The final part of the knowledge level model keeps track of relationship types. We said above that object relationships are used to generalize the 3.x notion of group member fields. These were fields that a developer could store on each member of a group, but which were contextualized to the -membership relation. That is, they were really "attached" to the +membership relation. That is, they were really "attached" to the fact that a user was a member of a particular group, and not really attached to the user. This is a subtle but important distinction, because it allowed the 3.x system to store multiple sets of attributes on a given user, one set for each group membership relation in which they participated.
In OpenACS 4, this sort of data can be stored as a relationship type, in -acs_rel_types. The key parts of this table look like this:
+acs_rel_types. The key parts of this table look like this:
-create table acs_rel_types ( +create table acs_rel_types ( rel_type varchar(100) not null references acs_object_types(object_type), object_type_one not null @@ -350,31 +350,31 @@ min_n_rels_two integer default 0 not null, max_n_rels_two integer ); -+ -
Things to note about this table:
The main part of this table records the fact that the relation is between -instances of object_type_one and instances of -object_type_two. Therefore, each instance of this relation type -will be a pair of objects of the appropriate types.
The role columns store human readable names for the roles -played by each object in the relation (e.g. "employee" and -"employer"). Each role must appear in the -acs_rel_roles.
The min_n_rels_one column, and its three friends allow the +
Things to note about this table:
The main part of this table records the fact that the relation is between +instances of object_type_one and instances of +object_type_two. Therefore, each instance of this relation type +will be a pair of objects of the appropriate types.
The role columns store human readable names for the roles +played by each object in the relation (e.g. "employee" and +"employer"). Each role must appear in the +acs_rel_roles.
The min_n_rels_one column, and its three friends allow the programmer to specify constraints on how many objects any given object can be -related to on either side of the relation.
This table is easier to understand if you also know how the acs_rels table works.
To summarize, the acs_object_types and -acs_attributes tables store metadata that describes every object +related to on either side of the relation.
This table is easier to understand if you also know how the acs_rels table works.
To summarize, the acs_object_types and +acs_attributes tables store metadata that describes every object type and attribute in the system. These tables generalize the group types -data model in OpenACS 3.x. The acs_rel_types table stores +data model in OpenACS 3.x. The acs_rel_types table stores information about relation types.
This part of the data model is somewhat analogous to the data dictionary in Oracle. The information stored here is primarily metadata that describes -the data stored in the operational level of the data -model, which is discussed next.
Operational-level Data Model
The operational level data model centers around the -acs_objects table. This table contains a single row for every -instance of the type acs_object. The table contains the +the data stored in the operational level of the data +model, which is discussed next.
Operational-level Data Model
The operational level data model centers around the +acs_objects table. This table contains a single row for every +instance of the type acs_object. The table contains the object's unique identifier, a reference to its type, security information, and generic auditing information. Here is what the table looks like:
-create table acs_objects ( +create table acs_objects ( object_id integer not null, object_type not null references acs_object_types (object_type), @@ -388,32 +388,32 @@ modifying_user integer, modifying_ip varchar(50) ); -+
As we said in Section III, security contexts are hierarchical and also modeled as objects. There is another table called -acs_object_context_index that stores the context hierarchy.
Other tables in the core data model store additional information related -to objects. The table acs_attribute_values and -acs_static_attr_values are used to store attribute values that +acs_object_context_index that stores the context hierarchy.
Other tables in the core data model store additional information related +to objects. The table acs_attribute_values and +acs_static_attr_values are used to store attribute values that are not stored in a helper table associated with the object's type. The former is used for instance attributes while the latter is used for -class-wide "static" values. These tables have the same basic form, +class-wide "static" values. These tables have the same basic form, so we'll only show the first:
-create table acs_attribute_values ( +create table acs_attribute_values ( object_id not null references acs_objects (object_id) on delete cascade, attribute_id not null references acs_attributes (attribute_id), attr_value varchar(4000), primary key (object_id, attribute_id) ); -+ -
Finally, the table acs_rels is used to store object pairs +
Finally, the table acs_rels is used to store object pairs that are instances of a relation type.
-create table acs_rels ( +create table acs_rels ( rel_id not null references acs_objects (object_id) primary key @@ -425,33 +425,33 @@ references acs_objects (object_id), unique (rel_type, object_id_one, object_id_two) ); -+ -
This table is somewhat subtle:
rel_id is the ID of an instance of some relation +
This table is somewhat subtle:
rel_id is the ID of an instance of some relation type. We do this so we can store all the mapping tables in this one -table.
rel_type is the ID of the relation type to which this object -belongs.
The next two object IDs are the IDs of the objects being mapped.
All this table does is store one row for every pair of objects that +table.
rel_type is the ID of the relation type to which this object +belongs.
The next two object IDs are the IDs of the objects being mapped.
All this table does is store one row for every pair of objects that we'd like to attach with a relation. Any additional attributes that we'd like to attach to this pair of objects is specified in the attributes of the relation type, and could be stored in any number of places. As in the 3.x user/groups system, these places include helper tables or -generic skinny tables.
This table, along with acs_attributes and -acs_attribute_values generalize the old user/group tables -user_group_map, user_group_member_fields_map and -user_group_member_fields.
Summary and Discussion
The core tables in the OpenACS 4 data model store information about instances -of object types and relation types. The acs_object table +generic skinny tables.
This table, along with acs_attributes and +acs_attribute_values generalize the old user/group tables +user_group_map, user_group_member_fields_map and +user_group_member_fields.
Summary and Discussion
The core tables in the OpenACS 4 data model store information about instances +of object types and relation types. The acs_object table provides the central location that contains a single row for every object in the system. Services can use this table along with the metadata in stored in the knowledge level data model to create, manage, query and manipulate -objects in a uniform manner. The acs_rels table has an analogous +objects in a uniform manner. The acs_rels table has an analogous role in storing information on relations.
These are all the tables that we'll discuss in this document. The rest -of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.
Some examples of how these tables are used in the system can be found in -the discussion of the API, which comes next.
API
Now we'll examine each piece of the API in detail. Bear in mind that -the Object Model API is defined primarily through PL/SQL packages.
Object Types and Attributes
The object system provides an API for creating new object types and then -attaching attributes to them. The procedures create_type and -drop_type are used to create and delete type definitions.
The two calls show up in the package acs_object_type.
+of the Kernel data model is described in the documents for subsites, the permissions system and for the groups system.
Some examples of how these tables are used in the system can be found in +the discussion of the API, which comes next.
API
Now we'll examine each piece of the API in detail. Bear in mind that +the Object Model API is defined primarily through PL/SQL packages.
Object Types and Attributes
The object system provides an API for creating new object types and then +attaching attributes to them. The procedures create_type and +drop_type are used to create and delete type definitions.
The two calls show up in the package acs_object_type.
-procedure create_type ( + procedure create_type ( object_type in acs_object_types.object_type%TYPE, pretty_name in acs_object_types.pretty_name%TYPE, pretty_plural in acs_object_types.pretty_plural%TYPE, @@ -470,13 +470,13 @@ object_type in acs_object_types.object_type%TYPE, cascade_p in char default 'f' ); -+ -
Here the cascade_p argument indicates whether dropping a type +
Here the cascade_p argument indicates whether dropping a type should also remove all its subtypes from the system.
We define a similar interface for defining attributes in the package -acs_attribute:
+acs_attribute:
-function create_attribute ( + function create_attribute ( object_type in acs_attributes.object_type%TYPE, attribute_name in acs_attributes.attribute_name%TYPE, datatype in acs_attributes.datatype%TYPE, @@ -497,12 +497,12 @@ attribute_name in varchar ); -+
In addition, the following two calls are available for attaching extra annotations onto attributes:
-procedure add_description ( + procedure add_description ( object_type in acs_attribute_descriptions.object_type%TYPE, attribute_name in acs_attribute_descriptions.attribute_name%TYPE, description_key in acs_attribute_descriptions.description_key%TYPE, @@ -514,30 +514,30 @@ attribute_name in acs_attribute_descriptions.attribute_name%TYPE, description_key in acs_attribute_descriptions.description_key%TYPE ); -+
At this point, what you must do to hook into the object system from your -own data model becomes clear:
Create a table that will store the instances of the new type.
Call acs_object_type.create_type() to fill in the metadata +own data model becomes clear:
Create a table that will store the instances of the new type.
Call acs_object_type.create_type() to fill in the metadata table on this new type. If you want your objects to appear in the -acs_objects table, then your new type must be a subtype of -acs_object.
Call acs_attribute.create_attribute() to fill in information +acs_objects table, then your new type must be a subtype of +acs_object.
Call acs_attribute.create_attribute() to fill in information on the attributes that this type defines.
So, suppose we are writing a new version of the ticket tracker for 4.0. We probably define a table to store tickets in, and each ticket might have an ID and a description. If we want each ticket to be an object, then -ticket_id must reference the object_id column in -acs_objects:
+ticket_id must reference the object_id column in +acs_objects:
-create table tickets ( +create table tickets ( ticket_id references acs_objects (object_id), description varchar(512), ... ) ; -+
In addition to defining the table, we need this extra PL/SQL code to hook into the object type tables:
-declare +declare attr_id acs_attributes.attribute_id%TYPE; begin acs_object_type.create_type ( @@ -562,25 +562,25 @@ commit; end; -+
Thus, with a small amount of extra code, the new ticket tracker will now automatically be hooked into every generic object service that exists. Better still, this code need not be changed as new services are added. As an aside, the most important service that requires you to subtype -acs_object is permissions.
Objects
The next important piece of the API is defined in the -acs_object package, and is concerned with creating and managing +acs_object is permissions.
Objects
The next important piece of the API is defined in the +acs_object package, and is concerned with creating and managing objects. This part of the API is designed to take care of the mundane bookkeeping needed to create objects and query their attributes. Realistically however, limitations in PL/SQL and Oracle will make it hard to build generic procedures for doing large scale queries in the object system, so developers who need to do this will probably have to be fairly familiar -with the data model at a lower level.
The function acs_object.new() makes a new object for you. The -function acs_object.del() deletes an object. As before, this +with the data model at a lower level.
The function acs_object.new() makes a new object for you. The +function acs_object.del() deletes an object. As before, this is an abbreviated interface with all the long type specs removed. See the data model or developer's guide for the full interface.
-function new ( + function new ( object_id in acs_objects.object_id%TYPE default null, object_type in acs_objects.object_type%TYPE default 'acs_object', @@ -595,28 +595,28 @@ procedure delete ( object_id in acs_objects.object_id%TYPE ); -+
Next, we define some generic functions to manipulate attributes. Again, these interfaces are useful to an extent, but for large scale queries, it's likely that developers would have to query the data model directly, -and then encapsulate their queries in procedures.
For names, the default_name function is used if you don't +and then encapsulate their queries in procedures.
For names, the default_name function is used if you don't want to define your own name function.
-function name ( + function name ( object_id in acs_objects.object_id%TYPE ) return varchar; function default_name ( object_id in acs_objects.object_id%TYPE ) return varchar; -+
The following functions tell you where attributes are stored, and fetch single attributes for you.
-procedure get_attribute_storage ( + procedure get_attribute_storage ( object_id_in in acs_objects.object_id%TYPE, attribute_name_in in acs_attributes.attribute_name%TYPE, v_column out varchar2, @@ -634,17 +634,17 @@ attribute_name_in in acs_attributes.attribute_name%TYPE, value_in in varchar2 ); -+ -
The main use of the acs_object package is to create +
The main use of the acs_object package is to create application objects and make them available for services via the -acs_objects table. To do this, you just have to make sure you -call acs_object.new() on objects that you wish to appear in the -acs_objects table. In addition, all such objects must be -instances of some subtype of acs_object.
Continuing the ticket example, we might define the following sort of +acs_objects table. To do this, you just have to make sure you +call acs_object.new() on objects that you wish to appear in the +acs_objects table. In addition, all such objects must be +instances of some subtype of acs_object.
Continuing the ticket example, we might define the following sort of procedure for creating a new ticket:
-function new_ticket ( + function new_ticket ( package_id in tickets.ticket_id%TYPE default null, description in tickets.description%TYPE default '', @@ -664,42 +664,42 @@ (v_ticket_id, description); return v_ticket_id; end new_ticket; -+
This function will typically be defined in the context of a PL/SQL package, but we've left it stand-alone here for simplicity.
To summarize: in order to take advantage of OpenACS 4 services, a new -application need only do three things:
Define a data model to describe application objects. This can just be a -normal SQL table.
Create an object type, using code like in the example from the previous -section.
Make sure application objects are created using -acs_object.new() in addition to whatever SQL code is needed to +application need only do three things:
Define a data model to describe application objects. This can just be a +normal SQL table.
Create an object type, using code like in the example from the previous +section.
Make sure application objects are created using +acs_object.new() in addition to whatever SQL code is needed to insert a new row into the application data model.
One of the design goals of OpenACS 4 was to provide a straightforward and consistent mechanism to provide applications with general services. What we have seen here is that three simple steps and minimal changes in the application data model are sufficient to make sure that application objects -are represented in the acs_objects table. Subsequently, all of +are represented in the acs_objects table. Subsequently, all of the general services in OpenACS 4 (i.e. permissions, general comments, and so on) -are written to work with any object that appears in acs_objects. +are written to work with any object that appears in acs_objects. Therefore, in general these three steps are sufficient to make OpenACS 4 services -available to your application.
Relation Types
The relations system defines two packages: acs_rel_type for -creating and managing relation types, and acs_rel for relating +available to your application.
Relation Types
The relations system defines two packages: acs_rel_type for +creating and managing relation types, and acs_rel for relating objects.
These two procedures just insert and remove roles from the -acs_rel_roles table. This table stores the legal relationship -"roles" that can be used when creating relation types. Examples of -roles are, say, "member", or "employer".
+acs_rel_roles table. This table stores the legal relationship +"roles" that can be used when creating relation types. Examples of +roles are, say, "member", or "employer".
-procedure create_role ( + procedure create_role ( role in acs_rel_roles.role%TYPE ); procedure drop_role ( role in acs_rel_roles.role%TYPE ); -+ -
The main functions in the acs_rel_type package are used to +
The main functions in the acs_rel_type package are used to create and drop relation types.
-procedure create_type ( + procedure create_type ( rel_type in acs_rel_types.rel_type%TYPE, pretty_name in acs_object_types.pretty_name%TYPE, pretty_plural in acs_object_types.pretty_plural%TYPE, @@ -725,12 +725,12 @@ rel_type in acs_rel_types.rel_type%TYPE, cascade_p in char default 'f' ); -+ -
Finally, the acs_rel package provides an API that you use to +
Finally, the acs_rel package provides an API that you use to create and destroy instances of a relation type:
-function new ( + function new ( rel_id in acs_rels.rel_id%TYPE default null, rel_type in acs_rels.rel_type%TYPE default 'relationship', object_id_one in acs_rels.object_id_one%TYPE, @@ -743,15 +743,15 @@ procedure delete ( rel_id in acs_rels.rel_id%TYPE ); -+
A good example of how to use relation types appears in the OpenACS 4 data model for groups. As in 3.x, group membership is modeled using a mapping table, but now we create this mapping using relation types instead of explicitly creating a table. First, we create a helper table to store state on each membership fact:
-create table membership_rels ( +create table membership_rels ( rel_id constraint membership_rel_rel_id_fk references acs_rels (rel_id) constraint membership_rel_rel_id_pk @@ -761,11 +761,11 @@ check (member_state in ('approved', 'banned', 'rejected', 'deleted')) ); -+
Then, we create a new object type to describe groups.
-acs_object_type.create_type ( + acs_object_type.create_type ( object_type => 'group', pretty_name => 'Group', pretty_plural => 'Groups', @@ -774,18 +774,18 @@ type_extension_table => 'group_types', name_method => 'acs_group.name' ); -+
In this example, we've made groups a subtype of -acs_object to make the code simpler. The actual data model is +acs_object to make the code simpler. The actual data model is somewhat different. Also, we've assumed that there is a helper table -called groups to store information on groups, and that there is -a helper table called group_types that has been defined to store -extra attributes on groups.
Now, assuming we have another object type called person to +called groups to store information on groups, and that there is +a helper table called group_types that has been defined to store +extra attributes on groups.
Now, assuming we have another object type called person to represent objects that can be group members, we define the following relationship type for group membership:
-acs_rel_type.create_role ('member'); + acs_rel_type.create_role ('member'); acs_rel_type.create_type ( rel_type => 'membership_rel', @@ -798,16 +798,16 @@ object_type_two => 'person', role_two => 'member', min_n_rels_two => 0, max_n_rels_two => null ); -+
Now we can define the following procedure to add a new member to a group. All this function does is create a new instance of the membership relation type and then insert the membership state into the helper table that we define above. In the actual implementation, this function is implemented in -the membership_rel package. Here we just define an independent +the membership_rel package. Here we just define an independent function:
-function member_add ( +function member_add ( rel_id in membership_rels.rel_id%TYPE default null, rel_type in acs_rels.rel_type%TYPE default 'membership_rel', group in acs_rels.object_id_one%TYPE, @@ -834,12 +834,12 @@ value (v_rel_id, new.member_state); end; -+
Another simple function can be defined to remove a member from a group:
-procedure member_delete ( + procedure member_delete ( rel_id in membership_rels.rel_id%TYPE ) is @@ -849,13 +849,13 @@ acs_rel.del(rel_id); end; -+ -
Summary and Discussion
The Object Model's API and data model provides a small set of simple +
Summary and Discussion
The Object Model's API and data model provides a small set of simple procedures that allow applications to create object types, object instances, and object relations. Most of the data model is straightforward; the relation type mechanism is a bit more complex, but in return it provides functionality -on par with the old user/groups system in a more general way.
Future Improvements/Areas of Likely Change
Nothing here yet.
Authors
Pete Su generated this document +on par with the old user/groups system in a more general way.
Future Improvements/Areas of Likely Change
Nothing here yet.
Authors
Pete Su generated this document from material culled from other documents by Michael Yoon, Richard Li and Rafael Schloming. But, any remaining lies -are his and his alone.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 9/09/2000 Pete Su
0.2 Edited for ACS 4 Beta 9/30/2000 Kai Wu
0.3 Edited for ACS 4.0.1, fixed some mistakes, removed use of term -"OM" 11/07/2000 Pete Su
Prev Home Next
Object Model Requirements Up Permissions Requirements
docs@openacs.org
View comments on this page at openacs.org +are his and his alone.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 9/09/2000 Pete Su
0.2 Edited for ACS 4 Beta 9/30/2000 Kai Wu
0.3 Edited for ACS 4.0.1, fixed some mistakes, removed use of term +"OM" 11/07/2000 Pete Su
Prev Home Next
Object Model Requirements Up Permissions Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 17 Oct 2010 21:06:08 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,56 +1,56 @@ - -Object Model Requirements
Prev Chapter 15. Kernel Documentation Next
Object Model Requirements
By Pete Su
+ +Object Model Requirements
Prev Chapter 14. Kernel Documentation Next
Object Model Requirements
By Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
I. Introduction
A major goal in OpenACS 4 is to unify and normalize many of the core services +
I. Introduction
A major goal in OpenACS 4 is to unify and normalize many of the core services of the system into a coherent common data model and API. In the past, these services were provided to applications in an ad-hoc and irregular fashion. -Examples of such services include:
General Comments
User/groups
Attribute storage in user/groups
General Permissions
Site wide search
General Auditing
All of these services involve relating extra information and services to -application data objects, examples of which include:
Bboard messages
A user home page
A ticket in the Ticket Tracker
A photograph in the PhotoDB
In the past, developers had to use ad-hoc and inconsistent schemes to -interface to the various "general" services mentioned above. Since +Examples of such services include:
General Comments
User/groups
Attribute storage in user/groups
General Permissions
Site wide search
General Auditing
All of these services involve relating extra information and services to +application data objects, examples of which include:
Bboard messages
A user home page
A ticket in the Ticket Tracker
A photograph in the PhotoDB
In the past, developers had to use ad-hoc and inconsistent schemes to +interface to the various "general" services mentioned above. Since each service used its own scheme for storing its metadata and mapping this data to application objects, we could not implement any kind of centralized management system or consistent administrative pages for all the services. Consequently, a large amount of duplicate code appeared throughout the system -for dealing with these services.
Unifying and "normalizing" these interfaces, to minimize the +for dealing with these services.
Unifying and "normalizing" these interfaces, to minimize the amount of code repetition in applications, is a primary goal of OpenACS 4. Thus the Object Model (OM, also referred to later as the object system) is concerned primarily with the storage and management of metadata, on -any object within a given instance of OpenACS 4. The term "metadata" +any object within a given instance of OpenACS 4. The term "metadata" refers to any extra data the OM stores on behalf of the application - outside of the application's data model - in order to enable certain generic -services. The term "object" refers to any entity being represented +services. The term "object" refers to any entity being represented within the OpenACS, and typically corresponds to a single row within the -relational database.
Vision Statement
The OpenACS 4 Object Model must address five high-level requirements that +relational database.
Vision Statement
The OpenACS 4 Object Model must address five high-level requirements that repeatedly exhibit themselves in the context of existing services in OpenACS 3.x, -as described below.
Object Identifiers for General Services
Generic services require a single unambiguous way of identifying +as described below.
Object Identifiers for General Services
Generic services require a single unambiguous way of identifying application objects that they manage or manipulate. In OpenACS 3.x, there are several different idioms that construct object identifiers from other data. -Many modules use a (user_id, group_id, scope) triple combination +Many modules use a (user_id, group_id, scope) triple combination for the purpose of recording ownership information on objects for access -control. User/groups also uses (user_id, group_id) pairs in its -user_group_map table as a way to identify data associated with a +control. User/groups also uses (user_id, group_id) pairs in its +user_group_map table as a way to identify data associated with a single membership relation.
Also in OpenACS 3.x, many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, general comments maintains a mapping table that maps application -"page" data (static or dynamic) to one or more user comments on the +"page" data (static or dynamic) to one or more user comments on the page, by constructing a unique identifier for each page. This identifier is usually a combination of the table in which the data is stored, and the value of the primary key value for the particular page. This idiom is referred to -as the "(on_which_table + on_what_id)" method for identifying +as the "(on_which_table + on_what_id)" method for identifying application data. General comments stores its map from pages to comments -using a "(on_which_table + on_what_id)" key, plus the id of the +using a "(on_which_table + on_what_id)" key, plus the id of the comment itself.
All of these composite key constructions are implicit object identifiers: they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent. This makes the construction of generic application-independent services difficult. Therefore, the OpenACS 4 Object Model should provide a centralized and uniform -mechanism for tagging application objects with unique identifiers.
Support for Unified Access Control
Access control should be as transparent as possible to the application +mechanism for tagging application objects with unique identifiers.
Support for Unified Access Control
Access control should be as transparent as possible to the application developer. Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later -on, a notion of "scoping" was introduced into the core data -model.
"Scope" is a term best explained by example. Consider some -hypothetical rows in the address_book table:
... scope user_id group_id ...
... user 123 ...
... group 456 ...
... public ...
The first row represents an entry in User 123's personal address book, +on, a notion of "scoping" was introduced into the core data +model.
"Scope" is a term best explained by example. Consider some +hypothetical rows in the address_book table:
... scope user_id group_id ...
... user 123 ...
... group 456 ...
... public ...
The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book.
In this way, the scoping columns identify the security context in which a @@ -64,9 +64,9 @@ page, a security problem could result.
Thus the OpenACS 4 Object Model must support a more general access control system that allows access control domains to be hierarchical, and specifiable with a single piece of data, instead of the old composite keys described -above.
Extensible Data Models
Another problem with previous OpenACS data models is that many of the central +above.
Extensible Data Models
Another problem with previous OpenACS data models is that many of the central tables in the system became bloated as they were extended to support an -increasing number of modules. The users table is the best case +increasing number of modules. The users table is the best case in point: it became full of columns that exist for various special applications (e.g. user portraits), but that aren't really related to each other in any way except that they store information on users, i.e. the @@ -82,33 +82,33 @@ custom extensions to the existing data models, and the OM does the bookkeeping necessary to make this easier, providing a generic API for object creation that automatically keeps track of the location and relationships -between data.
Design Note: While this doesn't really belong in a +between data.
Design Note: While this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object -data model exist, which you can read about in ???.
Modifiable Data Models
Another recurring applications problem is how to store a modifiable data +data model exist, which you can read about in Summary and Design Considerations.
Modifiable Data Models
Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. Furthermore, we want to avoid changes to an application's database queries in the face of any custom extensions, since such changes are difficult or dangerous to make at runtime, and can make updating the system difficult. Some example applications in OpenACS -3.x with modifiable data models include:
User/groups: developers and users can attach custom data to group types, -groups, and members of groups.
In the Ecommerce data model, the ec_custom_product_fields +3.x with modifiable data models include:
User/groups: developers and users can attach custom data to group types, +groups, and members of groups.
In the Ecommerce data model, the ec_custom_product_fields table defines attributes for catalog products, and the -ec_custom_product_field_values table stores values for those -attributes.
In the PhotoDB data model, the ph_custom_photo_fields table +ec_custom_product_field_values table stores values for those +attributes.
In the PhotoDB data model, the ph_custom_photo_fields table defines attributes for the photographs owned by a specific user, and tables named according to the convention -"ph_user_<user_id>_custom_info" are used to +"ph_user_<user_id>_custom_info" are used to store values for those attributes.
Thus the Object Model must provide a general mechanism for applications and developers to modify or extend data models, without requiring changes to the SQL schema of the system. This ensures that all applications use the same -base schema, resulting in a uniform and more maintainable system.
Generic Relations
Many OpenACS applications define simple relationships between application +base schema, resulting in a uniform and more maintainable system.
Generic Relations
Many OpenACS applications define simple relationships between application objects, and tag those relationships with extra data. In OpenACS 3.x, this was done using mapping tables. The user/groups module has the most highly developed data model for this purpose, using a single table called -user_group_map that mapped users to groups. In addition, it uses -the the user_group_member_fields and -user_group_member_fields_map tables to allow developers to +user_group_map that mapped users to groups. In addition, it uses +the the user_group_member_fields and +user_group_member_fields_map tables to allow developers to attach custom attributes to group members. In fact, these custom attributes were not really attached to the users, but to the fact that a user was a member of a particular group - a subtle but important distinction. As a @@ -120,25 +120,25 @@ Relation types are themselves object types that do nothing but represent relations. They can be used by applications that previously used user/groups for the same purpose, but without the extraneous, artificial -dependencies.
System Overview
The Object Model package is a combination of data model and a procedural +dependencies.
System Overview
The Object Model package is a combination of data model and a procedural API for manipulating application objects within an OpenACS instance. The OM allows developers to describe a hierarchical system of object types that store metadata on application objects. The object type system supports subtyping with inheritance, so new object types can be defined in terms of existing object types.
The OM data model forms the main part of the OpenACS 4 Kernel data model. The -other parts of the Kernel data model include:
Parties and Groups
Permissions
Each of these is documented elsewhere at length.
Use-cases and User-scenarios
(Pending as of 8/27/00)
Related Links
???
OpenACS Data Models and the Object System
Requirements: Data Model
The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing OpenACS modules:
10.0 Object Identification and Storage
Object identification is a central mechanism in the new metadata system. +other parts of the Kernel data model include:
Parties and Groups
Permissions
Each of these is documented elsewhere at length.
Use-cases and User-scenarios
(Pending as of 8/27/00)
Related Links
OpenACS 4 Object Model Design
OpenACS Data Models and the Object System
Requirements: Data Model
The data model for the object system provides support for the following +kinds of schema patterns that are used by many existing OpenACS modules:
10.0 Object Identification and Storage
Object identification is a central mechanism in the new metadata system. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. Thus the only action required of -an application to obtain any general service is to "hook into" the +an application to obtain any general service is to "hook into" the object system.
In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for objects that they manage. Generally, these unique IDs are built from other IDs that happen to be in the data model. Because there is no consistency in these implementations, every application must hook into every service -separately.
Examples of utilities that do this in OpenACS 3.x system are:
User/groups: Information is attached to group membership relations.
General Comments: Comments are attached to objects representing some kind -of document.
General Permissions: Stores access control information on application -data.
User Profiling: Maps users to pieces of content that they have looked at; -content identifiers must be managed in a uniform way.
Site Wide Search: Stores all content in a single flat table, with object +separately.
Examples of utilities that do this in OpenACS 3.x system are:
User/groups: Information is attached to group membership relations.
General Comments: Comments are attached to objects representing some kind +of document.
General Permissions: Stores access control information on application +data.
User Profiling: Maps users to pieces of content that they have looked at; +content identifiers must be managed in a uniform way.
Site Wide Search: Stores all content in a single flat table, with object identifiers pointing to the object containing the content in the first place. This way, we can search the contents of many different types of objects in a uniform way.
The OM will support and unify this programming idiom by providing objects @@ -148,15 +148,15 @@ application data. More importantly, object identifiers will enable developers to readily build and use generic services that work globally across a system.
The object identifiers should be subject to the following -requirements:
10.10 Uniqueness
The object ID should be unique among all the IDs in the entire OpenACS system -in which the object lives.
10.20 Useful as a Reference
Applications should be able to use the unique object ID as a reference, -with which they can fetch any or all of the object's attributes.
10.30 Storable
Object IDs should be storable in tables. e.g. you should be able to use +requirements:
10.10 Uniqueness
The object ID should be unique among all the IDs in the entire OpenACS system +in which the object lives.
10.20 Useful as a Reference
Applications should be able to use the unique object ID as a reference, +with which they can fetch any or all of the object's attributes.
10.30 Storable
Object IDs should be storable in tables. e.g. you should be able to use them to implement mapping tables between objects, to represent -relationships.
10.40 Moveable
Objects should be mobile between databases. That is, information will +relationships.
10.40 Moveable
Objects should be mobile between databases. That is, information will often need to be moved between multiple servers (development, staging, and production), so a mechanism for moving this data is necessary. In addition, a mechanism for tagging these objects in a way similar to CVS would be useful -in determining which objects need to be synchronized.
20.0 Object Types
An object type refers to a specification of one or more +in determining which objects need to be synchronized.
20.0 Object Types
An object type refers to a specification of one or more attributes to be managed along with a piece of application data.
The object system should provide a data model for describing and representing object types. This data model is somewhat analogous to the Oracle data dictionary, which stores information about all user defined @@ -169,99 +169,99 @@ is meant to be a generalization of this mechanism. The data model should allow developers to at least do everything they used to with user/groups, but without its administrative hassles.
Therefore, the data model must be able to represent object types that have -the following characteristics:
20.10 Type Name
A human readable name for the object type.
20.20 Type Attributes
Attributes whose values are shared by all instances of the object -type.
20.30 Object Attributes
Attributes that are specific to each particular object belonging to a -given type.
The data model must also enforce certain constraints on object types:
20.40 Type Uniqueness
Object type names must be unique.
20.50 Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object type and -any of its parent types.
30.0 Type Extension
The Object Model must support the definition of object types that are +the following characteristics:
20.10 Type Name
A human readable name for the object type.
20.20 Type Attributes
Attributes whose values are shared by all instances of the object +type.
20.30 Object Attributes
Attributes that are specific to each particular object belonging to a +given type.
The data model must also enforce certain constraints on object types:
20.40 Type Uniqueness
Object type names must be unique.
20.50 Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object type and +any of its parent types.
30.0 Type Extension
The Object Model must support the definition of object types that are subtypes of existing types. A subtype inherits all the attributes of its parent type, and defines some attributes of its own. A critical aspect of the OM is parent types may be altered, and any such change must propagate to child subtypes.
The OM data model must enforce constraints on subtypes that are similar to -the ones on general object types.
30.10 Subtype Uniqueness
Subtype names must be unique (this parallels requirement 10.40).
30.20 Subtype Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object -subtype.
30.30 Parent Type Prerequisite
Subtypes must be defined in terms of parent types that, in fact, already -exist.
30.40
The extended attribute names in a subtype must not be the same as those in -its parent type.
35.0 Methods
35.10 Method and Type Association
The OM data model should define a mechanism for associating procedural +the ones on general object types.
30.10 Subtype Uniqueness
Subtype names must be unique (this parallels requirement 10.40).
30.20 Subtype Attribute Name Uniqueness
Attribute names must be unique in the scope of a single object +subtype.
30.30 Parent Type Prerequisite
Subtypes must be defined in terms of parent types that, in fact, already +exist.
30.40
The extended attribute names in a subtype must not be the same as those in +its parent type.
35.0 Methods
35.10 Method and Type Association
The OM data model should define a mechanism for associating procedural code, called methods, with objects of a given type. Methods are associated with the each object type - not each object -instance.
35.20 Method Sharing
All instances of a given object type should share the same set of defined -methods for that type.
40.0 Object Attribute Value Storage
In addition to information on types, the OM data model provides for the +instance.
35.20 Method Sharing
All instances of a given object type should share the same set of defined +methods for that type.
40.0 Object Attribute Value Storage
In addition to information on types, the OM data model provides for the centralized storage of object attribute values. This facility unifies the many ad-hoc attribute/value tables that exist in various OpenACS 3.x data models, -such as:
User groups: Each instance of a group type can have custom data.
Photo DB: Users can define their own custom metadata to attach to -photograph objects.
Ecommerce: Vendors can attach custom fields to the data model describing -their products.
40.10 Generic Retrieval
Attributes should be stored so that they are retrievable in a way that is +such as:
User groups: Each instance of a group type can have custom data.
Photo DB: Users can define their own custom metadata to attach to +photograph objects.
Ecommerce: Vendors can attach custom fields to the data model describing +their products.
40.10 Generic Retrieval
Attributes should be stored so that they are retrievable in a way that is independent of the type of the object that they belong to. That is, the only data needed to retrieve an attribute should be the system-wide ID of an -object (see requirement 10.20 above) and the attribute name.
40.20 Inherited Attributes
The system should allow for the automatic retrieval of inherited attribute -values, for an object belonging to a subtype.
40.30. Constraints on Attributes
The system should allow the developer to put down constraints on the +object (see requirement 10.20 above) and the attribute name.
40.20 Inherited Attributes
The system should allow for the automatic retrieval of inherited attribute +values, for an object belonging to a subtype.
40.30. Constraints on Attributes
The system should allow the developer to put down constraints on the values that an attribute may hold, for the purposes of maintaining -application specific integrity rules.
50.0 Object Contexts
In OpenACS 3.x, there was a notion of "scope" for application +application specific integrity rules.
50.0 Object Contexts
In OpenACS 3.x, there was a notion of "scope" for application objects. An object could be belong to one of three scopes: public, group or user. This provided a crude way to associate objects with particular scopes in the system, but it was awkward to use and limited in flexibility.
The OpenACS 4 Object Model provides a generalized notion of scope that allows developers to represent a hierarchy of object contexts. These contexts are used as the basis for the permissions system. In general, if an object has no explicit permissions attached to it, then it inherits -permissions from its context.
The context data model also forms the basis of the subsites system, and is -a basic part of the permissions system, -described in separate documents.
The context data model should provide the following facilities:
50.10 Unique ID
Every context should have a unique ID in the system.
50.20 Tree Structure
The data model should support a tree structured organization of contexts. -That is, contexts can be logically "contained" within other +permissions from its context.
The context data model also forms the basis of the subsites system, and is +a basic part of the permissions system, +described in separate documents.
The context data model should provide the following facilities:
50.10 Unique ID
Every context should have a unique ID in the system.
50.20 Tree Structure
The data model should support a tree structured organization of contexts. +That is, contexts can be logically "contained" within other contexts (i.e. contexts have parents) and contexts can contain other contexts -(i.e. contexts can have children).
50.30 Data Model Constraints
All objects must have a context ID. This ID must refer to an existing +(i.e. contexts can have children).
50.30 Data Model Constraints
All objects must have a context ID. This ID must refer to an existing context or be NULL. The meaning of a NULL context is determined by the -implementation.
Note:
The current system interprets the NULL context as meaning the default -"site-wide" context in some sense. I wanted to note this fact for +implementation.
Note:
The current system interprets the NULL context as meaning the default +"site-wide" context in some sense. I wanted to note this fact for others, but there is no need to make this a requirement of the system. I think it would be reasonable to have a NULL context be an error (psu -8/24/2000).
55.0 Object Relations
The data model should include a notion of pair-wise relations between +8/24/2000).
55.0 Object Relations
The data model should include a notion of pair-wise relations between objects. Relations should be able to record simple facts of the form -"object X is related to object Y by relationship R," and also be -able to attach attributes to these facts.
Requirements: API
The API should let programmers accomplish the following actions:
60.0 Object Type Creation
60.10 Create a New Object Type
The object system API should provide a procedure call that creates a new +"object X is related to object Y by relationship R," and also be +able to attach attributes to these facts.
Requirements: API
The API should let programmers accomplish the following actions:
60.0 Object Type Creation
60.10 Create a New Object Type
The object system API should provide a procedure call that creates a new object type by running the appropriate transactions on the object system data model. This API call is subject to the constraints laid out in the data -model. We call this operation "instantiating" an object.
60.20 Create a New Object Subtype
The object system API should provide a procedure call for creating +model. We call this operation "instantiating" an object.
60.20 Create a New Object Subtype
The object system API should provide a procedure call for creating subtypes of a given type. Operationally, this API is the same as requirement 60.10. Instances of subtypes automatically contain all attributes of the parent type in addition to all attributes of the subtype. This API is subject -to the constraints laid out in the data model.
60.30 Create a New Relation Type
There should be an API call to create a new type of object relation. +to the constraints laid out in the data model.
60.30 Create a New Relation Type
There should be an API call to create a new type of object relation. Relation types can be modeled as object types. The API below for manipulating -attributes can then be used to add attributes to relation types.
70.0 Update an Object Type
The object system API must allow the programmer to modify, add, and delete +attributes can then be used to add attributes to relation types.
70.0 Update an Object Type
The object system API must allow the programmer to modify, add, and delete attributes from any object type. Updates should be propagated to any child subtypes. This API is subject to the constraints laid out in the data -model.
80.0 Delete an Object Type
The system provides an API call for deleting an object type.
80.10
Deleting an object type destroys all instances of the type. It should be +model.
80.0 Delete an Object Type
The system provides an API call for deleting an object type.
80.10
Deleting an object type destroys all instances of the type. It should be an error to delete types that have dependent subtypes. This API is subject to -the constraints laid out in the data model.
80.10.10
However, the programmer should also be able to specify that all the +the constraints laid out in the data model.
80.10.10
However, the programmer should also be able to specify that all the subtypes and instances of those subtypes be destroyed before destroying the -object type. This is similar to a "delete cascade" constraint in -SQL.
90.0 Object Instance Creation and Destruction
The system must provide API calls to manage the creation and destruction -of object instances.
90.10 Create an Instance of an Object Type
The system should provide an API call for creating a new instance of a +object type. This is similar to a "delete cascade" constraint in +SQL.
90.0 Object Instance Creation and Destruction
The system must provide API calls to manage the creation and destruction +of object instances.
90.10 Create an Instance of an Object Type
The system should provide an API call for creating a new instance of a given object type. The new instance should be populated with values for each of the attributes specified in the definition of the type. In addition, it should be possible to create the new instance with an optional context ID -that refers to the default context that the object will live in.
90.20 Delete an Object Instance
The OM should provide an API call for object deletion. Objects can be +that refers to the default context that the object will live in.
90.20 Delete an Object Instance
The OM should provide an API call for object deletion. Objects can be deleted only when no other objects in the system refer to them. Since it -might not be practical to provide a mechanism like "delete cascade" +might not be practical to provide a mechanism like "delete cascade" here in a reliable way, providing such a facility in the system is -optional.
94.0 Object Relation Creation and Destruction
The system must provide API calls to manage the creation and destruction -of object relations.
94.10 Create an Object Relation
The OM must provide an API call to declare that two objects are related to +optional.
94.0 Object Relation Creation and Destruction
The system must provide API calls to manage the creation and destruction +of object relations.
94.10 Create an Object Relation
The OM must provide an API call to declare that two objects are related to each other by a given relation type. This API call should also allow -programmers to attach attributes to this object relation.
94.20 Destroy an Object Relation
There should be an API call for destroying object relations and their -attributes.
95.10 Create and Destroy Contexts
The system should provide an API to create and destroy object -contexts.
100.10 Set Attribute Values for an Object
The system should provide an API for updating the attribute values of a -particular instance of an object type.
110.10 Get Attribute Values for an Object
The system should provide an API for retrieving attribute values from a -particular instance of an object type.
120.10 Efficiency
The Object Model must support the efficient storage and retrieval of +programmers to attach attributes to this object relation.
94.20 Destroy an Object Relation
There should be an API call for destroying object relations and their +attributes.
95.10 Create and Destroy Contexts
The system should provide an API to create and destroy object +contexts.
100.10 Set Attribute Values for an Object
The system should provide an API for updating the attribute values of a +particular instance of an object type.
110.10 Get Attribute Values for an Object
The system should provide an API for retrieving attribute values from a +particular instance of an object type.
120.10 Efficiency
The Object Model must support the efficient storage and retrieval of object attributes. Since the OM is intended to form the core of many general services in the OpenACS, and these services will likely make extensive use of the OM tables, queries on these tables must be fast. The major problem here seems to be supporting subtyping and inheritance in a way that does not severely -impact query performance.
130.10 Ease of Use
Most OpenACS packages will be expected to use the Object Model in one way or +impact query performance.
130.10 Ease of Use
Most OpenACS packages will be expected to use the Object Model in one way or another. Since it is important that the largest audience of developers possible adopts and uses the OM, it must be easy to incorporate into applications, and it must not impose undue requirements on an -application's data model. In other words, it should be easy to "hook -into" the object model, and that ability should not have a major impact -on the application data model.
Note: Is the API the only way to obtain values? How does -this integrate with application level SQL queries?
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/10/2000 Bryan Quinn
0.2 Major re-write 08/11/2000 Pete Su
0.3 Draft completed after initial reviews 08/22/2000 Pete Su
0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu
Final edits before freeze 08/24/2000 Pete Su
0.5 Edited for consistency 08/27/2000 Kai Wu
0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su
0.7 Added requirement that knowledge-level objects must be moveable between +application's data model. In other words, it should be easy to "hook +into" the object model, and that ability should not have a major impact +on the application data model.
Note: Is the API the only way to obtain values? How does +this integrate with application level SQL queries?
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/10/2000 Bryan Quinn
0.2 Major re-write 08/11/2000 Pete Su
0.3 Draft completed after initial reviews 08/22/2000 Pete Su
0.4 Edited, updated to conform to requirements template, pending freeze 08/23/2000 Kai Wu
Final edits before freeze 08/24/2000 Pete Su
0.5 Edited for consistency 08/27/2000 Kai Wu
0.6 Put Object ID stuff first, because it makes more sense 08/28/2000 Pete Su
0.7 Added requirement that knowledge-level objects must be moveable between databases. 08/29/2000 Richard Li
0.8 Rewrote intro to match language and concepts in the design document. Also cleaned up usage a bit in the requirements section. Added short vague -requirements on relation types. 09/06/2000 Pete Su
0.9 Edited for ACS 4 Beta release. 09/30/2000 Kai Wu
Prev Home Next
Overview Up Permissions Requirements
docs@openacs.org
View comments on this page at openacs.org +requirements on relation types. 09/06/2000 Pete Su
0.9 Edited for ACS 4 Beta release. 09/30/2000 Kai Wu
Prev Home Next
Overview Up Object Model Design
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.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/objects.html 17 Oct 2010 21:06:08 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/objects.html 11 Dec 2010 23:36:32 -0000 1.50 @@ -1,8 +1,8 @@ - -OpenACS Data Models and the Object System
Prev Chapter 11. Development Reference Next
OpenACS Data Models and the Object System
By Pete Su
+ +OpenACS Data Models and the Object System
Prev Chapter 10. Development Reference Next
OpenACS Data Models and the Object System
By Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Overview
+
Overview
Developing data models in OpenACS 5.6.0 is much like developing data models for OpenACS 3, save for the implementation. As usual, you need to examine how to model the information that the application must store and @@ -25,15 +25,15 @@
Thinking further ahead, we can imagine doing any of the following things with Notes as well: -
Define access control policies on notes.
Attach user comments on notes.
Allow users to define custom fields to store on their notes.
Automatically generate input forms or output displays for notes.
Allow other applications to use notes in ways we don't know of yet.
+
Define access control policies on notes.
Attach user comments on notes.
Allow users to define custom fields to store on their notes.
Automatically generate input forms or output displays for notes.
Allow other applications to use notes in ways we don't know of yet.
In OpenACS, the key to enabling these types of services on your application data is to take advantage of the Object System. The first -question, then, is "Just what are objects, and what do -you use them for anyway?". The short answer: objects are anything +question, then, is "Just what are objects, and what do +you use them for anyway?". The short answer: objects are anything represented in the application's data model that will need to be managed by any central service in OpenACS, or that may be reusable in the context of future applications. Every object in the system is -represented using a row in the acs_objects table. This +represented using a row in the acs_objects table. This table defines all the standard attributes that are stored on every object, including its system-wide unique ID, object type, and some generic auditing columns. @@ -42,22 +42,22 @@ have to write your data model in a way that is slightly more complex than in the ACS 3.x days. What you get for this extra work includes: -
The Permissions System lets you +
The Permissions System lets you track who is allowed to do what to the rows in an application table, and gives you an easy way to enforce - this from Tcl.
Every object has an attribute called context_id + this from Tcl.
Every object has an attribute called context_id that provides a way to trivially specify both the default - permissions for an object, and the intended "scope" of an - object. Just set the context_id to the controlling - object and forget about it.
And most importantly, any future object-level service - from + permissions for an object, and the intended "scope" of an + object. Just set the context_id to the controlling + object and forget about it.
And most importantly, any future object-level service - from a general-comments replacement to personalized ranking - will - become available to your application "for free."
-
How to Use Objects
+ become available to your application "for free."
+
How to Use Objects
Using ACS objects is straightforward: all that's required are a few extra steps in the design of your application data model.
In order to hook our Notes application into the object system, we -make some calls to use our notes table as the basis for a +make some calls to use our notes table as the basis for a new object type. Object types are analogous to classes in programming languages such as C++ and Java. In Java, a class defines a set of attributes that store data and a set of methods @@ -66,21 +66,21 @@ define the programming interface to the data model.
The object type itself is described using data in the -acs_object_types and -acs_attributes tables, which play a role +acs_object_types and +acs_attributes tables, which play a role similar to the data dictionary in Oracle. As in Java, object types can inherit attributes from a parent type, so the type system forms a hierarchy. Unlike Java, Oracle does not support this inheritance transparently, so we have to make sure we add our own bookkeeping code to keep everything consistent. Below you'll find the code needed to describe a -new object type called notes in your +new object type called notes in your system.
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
-First, add an entry to the acs_object_types table with the following PL/SQL call: +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
+First, add an entry to the acs_object_types table with the following PL/SQL call:
begin acs_object_type.create_type ( @@ -96,18 +96,18 @@ show errors;
This PL/SQL call tells the system that we would like to use the table -NOTES as the basis for a new object type called -note. This type is a subtype of the -acs_object type, which means that we want to inherit all +NOTES as the basis for a new object type called +note. This type is a subtype of the +acs_object type, which means that we want to inherit all of the basic attributes of all ACS objects. As mentioned, it will take some work on our part to make this happen, since Oracle can't do it automatically. In general, most basic applications will define types -that are simple subtypes of acs_object. +that are simple subtypes of acs_object.
-Add entries to the acs_attributes table to describe +Add entries to the acs_attributes table to describe the data attributes of the new type. This data can eventually be used to do things like automatically generate user interfaces to manipulate -the notes table, though that functionality isn't yet +the notes table, though that functionality isn't yet available.
declare @@ -133,17 +133,17 @@ show errors;
We can stop here and not bother to register the usual OpenACS 3.x -attributes of creation_user, creation_date -and last_modified, since the object type -acs_object already defines these attributes. Again, -because the new type note is a subtype of -acs_object, it will inherit these attributes, so there is +attributes of creation_user, creation_date +and last_modified, since the object type +acs_object already defines these attributes. Again, +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 +reflect the fact that each row in the notes table represents something that is not only an object of type -note, but also an acs_object. The new table +note, but also an acs_object. The new table definition looks like this:
create table notes ( @@ -153,18 +153,18 @@ body varchar(1024) )
-The usual creation_date and -modified_date columns are absent since they already exist -in acs_objects. Also, note the constraint we have added -to reference the acs_objects table, which makes clear -that since note is a subtype of acs_object, +The usual creation_date and +modified_date columns are absent since they already exist +in acs_objects. Also, note the constraint we have added +to reference the acs_objects table, which makes clear +that since note is a subtype of acs_object, every row in the notes table must have a corresponding row in the -acs_objects table. This is the fundamental means by which +acs_objects table. This is the fundamental means by which we model inheritance; it guarantees that any services that -use the acs_objects table to find objects will +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
+acs_objects. +
Define a package for type specific procedures
The next step is to define a PL/SQL package for your new type, and write some basic procedures to create and delete objects. Here is a package definition for our new type: @@ -196,30 +196,30 @@ calls, since we haven't mentioned them before. These parameters are needed to fill out information that will be stored about the object that's not stored directly in the table you defined. The OpenACS Object -System defines these attributes on the type acs_object +System defines these attributes on the type acs_object since all objects should have these attributes. Internally, there are tables that store this information for you. Most of the data is pretty self-explanatory and reflects attributes that existed in the earlier -OpenACS 3.x data models, with the exception of the context_id +OpenACS 3.x data models, with the exception of the context_id attribute.
-The context_id attribute stores the ID of an object that +The context_id attribute stores the ID of an object that represents the default security domain to which the object belongs. It -is used by the permissions system in +is used by the permissions system in this way: if no permissions are explicitly attached to the object, then the object inherits its permissions from the context. For -example, if I had told you how to use the permissions system to specify that an -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 +example, if I had told you how to use the permissions system to specify that an +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 -acs_objects, before inserting a row into the -notes. Similarly, when we delete a row from -note, we have to be sure to delete the corresponding -acs_object row. +acs_object.new to insert a row into +acs_objects, before inserting a row into the +notes. Similarly, when we delete a row from +note, we have to be sure to delete the corresponding +acs_object row.
create or replace package body note as @@ -272,14 +272,14 @@ / show errors;
-That's pretty much it! As long as you use the note.new -function to create notes, and the note.delete function to +That's pretty much it! As long as you use the note.new +function to create notes, and the note.delete function to delete them, you'll be assured that the relationship each -note has with its corresponding acs_object +note has with its corresponding acs_object is preserved.
The last thing to do is to make a file -ROOT/packages/notes/sql/notes-drop.sql so it's easy to +ROOT/packages/notes/sql/notes-drop.sql so it's easy to drop the data model when, say, you're testing:
begin @@ -290,17 +290,17 @@ drop package note; drop table notes; -
When to Use Objects
+
When to Use Objects
While it is hard to give general design advice without knowing anything about a particular application, you should follow the following rule of thumb when deciding when to hook part of your data model to the object system:
Anything in your data model that needs to be available to general OpenACS services such as user comments, permissions, and so on should be a -subtype of acs_object. In addition, if you want your data +subtype of acs_object. In addition, if you want your data model to take advantage of attributes that exist in some object type -that is a subtype of acs_object, then you should use the +that is a subtype of acs_object, then you should use the object system.
For example, for most applications, you will want to use objects to @@ -310,7 +310,7 @@ kind of design decision is mostly made on an application-by-application basis, but this is a good baseline from which to start. -
Design Guidance
+
Design Guidance
In this section we cover some overall guidelines for designing data models that are meant to be integrated with the OpenACS object system. @@ -319,25 +319,25 @@ models: -
-Never utilize fields in the acs_objects table in +
+Never utilize fields in the acs_objects table in application specific ways. That is, never assign any application-specific semantics to this data. In the notes -application, we use the creation_date and -last_modified fields, but this is OK since we do not +application, we use the creation_date and +last_modified fields, but this is OK since we do not assign any application-specific meaning to these fields. -
+
In particular, never assign any application specific semantics to the -context_id attribute of an object. This field is used for +context_id attribute of an object. This field is used for a very specific purpose by the permissions system, and using this field in any other way whatsoever is guaranteed to make your application act strangely.
As we'll see later, the Notes example will point each note object's -context_id to the package instance in which the note was +context_id to the package instance in which the note was created. The idea will be that in a real site, the administrator would create one package instance for every separate set of Notes (say, one -per user). The instance would "own" all of the notes that it created, +per user). The instance would "own" all of the notes that it created, and the administrator would be able to use the package instance as the basis for access control, which is convenient.
@@ -355,43 +355,43 @@ that the data model is trying to support.
Another less important reason for these two rules is to not introduce -any joins against the acs_objects table in SQL queries in +any joins against the acs_objects table in SQL queries in your application that you do not absolutely need.
In the Notes example, the result of applying these rules is that we -are careful to define our own attribute for owner_id -rather than overloading creation_user from the objects -table. But, since we will probably use creation_date and +are careful to define our own attribute for owner_id +rather than overloading creation_user from the objects +table. But, since we will probably use creation_date and so on for their intended purposes, we don't bother to define our own attributes to store that data again. This will entail joins with -acs_objects but that's OK because it makes the overall +acs_objects but that's OK because it makes the overall data model cleaner. The real lesson is that deciding exactly how and when to use inherited attributes is fairly straightforward, but requires a good amount of thought at design time even for simple applications. -
Summary
+
Summary
Hooking into the OpenACS 5.6.0 object system brings the application developer numerous benefits, and doing it involves only four easy steps: -
+
Describe the a new object type to the system. Most new application -types will be subtypes of the built-in type acs_object. -
+types will be subtypes of the built-in type acs_object. +
Define a table to store application object data. -
+
Define a PL/SQL package to store procedures related to the new -type. You have to define at least a function called new +type. You have to define at least a function called new to create new application objects and a procedure called -delete to delete them. -
+delete to delete them. +
Define a package body that contains the implementations of the PL/SQL procedures defined above. -
+
Try not to write queries in your application that join against -acs_objects. This means you should never use the fields -in acs_objects for application-specific purposes. This is -especially true for the context_id field. +acs_objects. This means you should never use the fields +in acs_objects for application-specific purposes. This is +especially true for the context_id field.

($Id$)
Prev Home Next
OpenACS Packages Up The Request Processor
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v diff -u -N -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 13 Sep 2009 23:54:40 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 11 Dec 2010 23:36:32 -0000 1.27 @@ -1,5 +1,5 @@ - -Overview
Prev Chapter 1. High level information: What is OpenACS? Next
Overview
+ +Overview
Prev Chapter 1. High level information: What is OpenACS? Next
Overview
OpenACS (Open Architecture Community System) is an advanced toolkit for building scalable, community-oriented web applications. If you're thinking of building an @@ -12,10 +12,10 @@ site/application. Through a modular architecture, OpenACS has packages for user/groups management, content management, e-commerce, news, FAQs, calendar, forums, bug - tracking, full-text searching, and much + tracking, full-text searching, and much more.
- OpenACS relies on AOLserver, the + OpenACS relies on AOLserver, the free, multithreaded, scalable, Tcl-enabled, web/application server used by America Online for most of its web sites, and a true ACID-compliant Relational @@ -26,7 +26,7 @@
The OpenACS toolkit is derived from the ArsDigita Community System (ACS). ArsDigita (now part of Red Hat, - Inc.) kindly made their work available under the GPL, + Inc.) kindly made their work available under the GPL, making all of this possible.
The OpenACS project was born when Don Baccus, Ben Adida, and @@ -47,6 +47,6 @@
The OpenACS community would like to hear your comments and can help you in your endeavors with the system. Visit our - web site and feel - free to ask questions or provide feedback. + web site and feel + free to ask questions or provide feedback.
Prev Home Next
Chapter 1. High level information: What is OpenACS? Up OpenACS Release Notes
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v diff -u -N -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 17 Oct 2010 21:06:08 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 11 Dec 2010 23:36:32 -0000 1.27 @@ -1,18 +1,18 @@ - -Unpack the OpenACS tarball
Prev Appendix B. Install additional supporting software Next
Unpack the OpenACS tarball
The OpenACS tarball contains sample configuration files + +Unpack the OpenACS tarball
Prev Appendix B. Install additional supporting software Next
Unpack the OpenACS tarball
The OpenACS tarball contains sample configuration files for some of the packages listed below. In order to access those - files, unpack the tarball now.
[root root]# cd /tmp -[root tmp]# tar xzf openacs-5.6.0.tgz + files, unpack the tarball now.
[root root]# cd /tmp +[root tmp]# tar xzf openacs-5.6.0.tgz cd /tmp -tar xzf openacs-5.6.0.tgz
If you are installing from a different method and just need the configuration files, you can instead get them from CVS:
[root root]# cd /tmp -[root tmp]# cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ +tar xzf openacs-5.6.0.tgz
If you are installing from a different method and just need the configuration files, you can instead get them from CVS:
[root root]# cd /tmp +[root tmp]# cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ cvs checkout: warning: failed to open /root/.cvspass for reading: No such file or directory cvs server: Updating openacs-4/packages/acs-core-docs/www/files U openacs-4/packages/acs-core-docs/www/files/README.TXT (many lines omitted) U openacs-4/packages/acs-core-docs/www/files/template-ini.ini U openacs-4/packages/acs-core-docs/www/files/winnsd.txt -[root tmp]# mv openacs-4 openacs-5.6.0 +[root tmp]# mv openacs-4 openacs-5.6.0 cd /tmp cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ mv openacs-4 openacs-5.0.0a4
Prev Home Next
Appendix B. Install additional supporting software Up Initialize CVS (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v diff -u -N -r1.48 -r1.49 --- openacs-4/packages/acs-core-docs/www/openacs.html 17 Oct 2010 21:06:08 -0000 1.48 +++ openacs-4/packages/acs-core-docs/www/openacs.html 11 Dec 2010 23:36:32 -0000 1.49 @@ -1,8 +1,8 @@ - -Install OpenACS 5.6.0
Prev Chapter 3. Complete Installation Next
Install OpenACS 5.6.0
by Vinod Kurup
+ +Install OpenACS 5.6.0
Prev Chapter 3. Complete Installation Next
Install OpenACS 5.6.0
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Set up a user account for each site.
+
Set up a user account for each site.
AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the command line. It's @@ -15,60 +15,60 @@ for each different service. A service name should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For - example "$OPENACS_SERVICE_NAME" might be the service name for the - $OPENACS_SERVICE_NAME.net + example "$OPENACS_SERVICE_NAME" might be the service name for the + $OPENACS_SERVICE_NAME.net community.
We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put - it in the $OPENACS_SERVICE_NAME group so that it + it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that group. (If you don't know how to do this, type - man usermod. You can type - groups to find out which groups a user + man usermod. You can type + groups to find out which groups a user is a part of)
-[root root]# useradd $OPENACS_SERVICE_NAME +[root root]# useradd $OPENACS_SERVICE_NAME
You also need to set up a group called web.
-[root root]# groupadd web +[root root]# groupadd web
Then change the user to be a part of this group:
-[root root]# usermod -g web $OPENACS_SERVICE_NAME +[root root]# usermod -g web $OPENACS_SERVICE_NAME
FreeBSD creates the user this way:
-[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME -[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash +[root root]# mkdir -p /home/$OPENACS_SERVICE_NAME +[root root]# pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash [root root]# mkdir -p /home/$OPENACS_SERVICE_NAME pw useradd -n $OPENACS_SERVICE_NAME -g web -d /home/$OPENACS_SERVICE_NAME -s /bin/bash -
Set up the file system for one or more OpenACS Sites
For Linux Standard Base compliance and ease of backup, +
Set up the file system for one or more OpenACS Sites
For Linux Standard Base compliance and ease of backup, all of the files in each OpenACS site are stored in a subdirectory of - /var/lib/aolserver, one + /var/lib/aolserver, one subdirectory per site. The first time you install an OpenACS - site on a server, you must create the parent directory and set its permissions:
[root root]# mkdir /var/lib/aolserver -[root root]# chgrp web /var/lib/aolserver -[root root]# chmod 770 /var/lib/aolserver + site on a server, you must create the parent directory and set its permissions:
[root root]# mkdir /var/lib/aolserver +[root root]# chgrp web /var/lib/aolserver +[root root]# chmod 770 /var/lib/aolserver [root root]# mkdir /var/lib/aolserver chgrp web /var/lib/aolserver -chmod 770 /var/lib/aolserver
Installation Option 1: Use automated script
A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation.
Get the install script from CVS. It is located within +chmod 770 /var/lib/aolserver
Installation Option 1: Use automated script
A bash script is available to automate all of the steps for the rest of this section. It requires tclwebtest. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a manual installation.
Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target - location.
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install + location.
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install cvs server: Updating install U install/README U install/TODO ... many lines omitted ... U install/tcl/twt-procs.tcl U install/tcl/user-procs.tcl -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install -[$OPENACS_SERVICE_NAME install]$ emacs install.tcl -
Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.
Run the install script install.sh as root:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit -[root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install +[$OPENACS_SERVICE_NAME install]$ emacs install.tcl +
Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.
Run the install script install.sh as root:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit +[root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh /home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file /home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/ $OPENACS_SERVICE_NAME, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, @@ -80,23 +80,23 @@ admin email : admin@yourserver.net admin password: xxxx ###################################################################### -[root root]#
You can proceed to Section , “Next Steps”.
Installation Option 2: Install from tarball
You should already have downloaded the OpenACS tarball - to the /var/tmp directory. If - not, download the OpenACS +[root root]#
You can proceed to Next Steps.
Installation Option 2: Install from tarball
You should already have downloaded the OpenACS tarball + to the /var/tmp directory. If + not, download the OpenACS tarball and save it in - /var/tmp and proceed:
Unpack the OpenACS tarball and rename it to $OPENACS_SERVICE_NAME. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.
FreeBSD note: Change the period in chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME to a colon: chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME -
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver -[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/openacs-5.6.0.tgz -[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-5.6.0 $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ ls -al + /var/tmp and proceed:
Unpack the OpenACS tarball and rename it to $OPENACS_SERVICE_NAME. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.
FreeBSD note: Change the period in chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME to a colon: chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME +
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /var/tmp/openacs-5.6.0.tgz +[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-5.6.0 $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ ls -al total 3 drwxrwx--- 3 root web 1024 Mar 29 16:41 . drwxr-xr-x 25 root root 1024 Mar 29 16:24 .. drwx------ 7 $OPENACS_SERVICE_NAME web 1024 Jan 6 14:36 $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ exit +[$OPENACS_SERVICE_NAME aolserver]$ exit logout [root root]# su - $OPENACS_SERVICE_NAME @@ -105,43 +105,43 @@ mv openacs-5.6.0 $OPENACS_SERVICE_NAME chmod -R 755 $OPENACS_SERVICE_NAME chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME -exit
Add the Service to CVS (OPTIONAL)
Prepare the database
Prepare Oracle for OpenACS. If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service
+exit
Add the Service to CVS (OPTIONAL)
Prepare the database
Prepare Oracle for OpenACS. If you won't be using Oracle, skip to Prepare PostgreSQL for an OpenACS Service
You should be sure that your user account - (e.g. $OPENACS_SERVICE_NAME) is in the - dba group. -
+ (e.g. $OPENACS_SERVICE_NAME) is in the + dba group. +
Verify membership by typing - groups when you login: + groups when you login:
[$OPENACS_SERVICE_NAME ~]$ groups dba web
If you do not see these groups, take the following action: -
[$OPENACS_SERVICE_NAME ~]$ su - +
[$OPENACS_SERVICE_NAME ~]$ su - Password: ************ -[root ~]# adduser $OPENACS_SERVICE_NAME dba
+[root ~]# adduser $OPENACS_SERVICE_NAME dba
If you get an error about an undefined group, then add that group manually: -
[root ~]# groupadd dba -[root ~]# groupadd web
+
[root ~]# groupadd dba +[root ~]# groupadd web
- Make sure to logout as root when + Make sure to logout as root when you are finished with this step and log back in as your regular user. -
+
Connect to Oracle using - svrmgrl and login: + svrmgrl and login: -
[$OPENACS_SERVICE_NAME ~]$ svrmgrl -SVRMGR> connect internal +
[$OPENACS_SERVICE_NAME ~]$ svrmgrl +SVRMGR> connect internal Connected.
-
+
Determine where the system tablespaces are stored: -
SVRMGR> select file_name from dba_data_files;
+
SVRMGR> select file_name from dba_data_files;
Example results:
/ora8/m01/app/oracle/oradata/ora8/system01.dbf /ora8/m01/app/oracle/oradata/ora8/tools01.dbf @@ -150,180 +150,180 @@ /ora8/m01/app/oracle/oradata/ora8/users01.dbf /ora8/m01/app/oracle/oradata/ora8/indx01.dbf /ora8/m01/app/oracle/oradata/ora8/drsys01.dbf
-
+
Using the above output, you should determine where to store your tablespace. As a general rule, you'll want to store your tablespace on a mount point under the - /ora8 directory that is separate + /ora8 directory that is separate from the Oracle system data files. By default, the Oracle system - is on m01, so we will use - m02. This enables your Oracle + is on m01, so we will use + m02. This enables your Oracle system and database files to be on separate disks for optimized performance. For more information on such a configuration, see - Chapter - 12 of Philip's + Chapter + 12 of Philip's book. For this example, we'll use - /ora8/m02/oradata/ora8/. -
+ /ora8/m02/oradata/ora8/. +
Create the directory for the datafile; to do this, - exit from svrmgrl and login as - root for this step:
-SVRMGR> exit -[$OPENACS_SERVICE_NAME ~]$ su - + exit from svrmgrl and login as + root for this step:
+SVRMGR> exit +[$OPENACS_SERVICE_NAME ~]$ su - Password: ************ -[root ~]# mkdir -p /ora8/m02/oradata/ora8/ -[root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8 -[root ~]# chmod 775 /ora8/m02/oradata/ora8 -[root ~]# exit -[$OPENACS_SERVICE_NAME ~]$
+[root ~]# mkdir -p /ora8/m02/oradata/ora8/ +[root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8 +[root ~]# chmod 775 /ora8/m02/oradata/ora8 +[root ~]# exit +[$OPENACS_SERVICE_NAME ~]$
Create a tablespace for the service. It is important that the - tablespace can autoextend. This + tablespace can autoextend. This allows the tablespace's storage capacity to grow as the size of the data grows. We set the pctincrease to be a very low value so that our extents won't grow geometrically. We do not set it to 0 at the tablespace level because this would affect Oracle's ability to automatically coalesce free space in the tablespace. -
[$OPENACS_SERVICE_NAME ~]$ svrmgrl -SVRMGR> connect internal; -SVRMGR> create tablespace $OPENACS_SERVICE_NAME +
[$OPENACS_SERVICE_NAME ~]$ svrmgrl +SVRMGR> connect internal; +SVRMGR> create tablespace $OPENACS_SERVICE_NAME datafile '/ora8/m02/oradata/ora8/$OPENACS_SERVICE_NAME01.dbf' size 50M autoextend on next 10M maxsize 300M extent management local - uniform size 32K;
+ uniform size 32K;
Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use - $OPENACS_SERVICE_NAMEpassword as our password.
+ $OPENACS_SERVICE_NAMEpassword as our password.
Write down what you specify as service_name - (i.e. $OPENACS_SERVICE_NAME) + (i.e. $OPENACS_SERVICE_NAME) and database_password - (i.e. $OPENACS_SERVICE_NAMEpassword). You + (i.e. $OPENACS_SERVICE_NAMEpassword). You will need this information for configuring exports and AOLserver.
-SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME - temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME; -SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to $OPENACS_SERVICE_NAME; -SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME; -SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME; -SVRMGR> exit;
+SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME + temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME; +SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to $OPENACS_SERVICE_NAME; +SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME; +SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME; +SVRMGR> exit;
Your table space is now ready. In case you are trying to delete a - previous OpenACS installation, consult these commands in Section , “Deleting a tablespace” below. -
+ previous OpenACS installation, consult these commands in Deleting a tablespace below. +
Make sure that you can login to Oracle using your - service_name account:
[$OPENACS_SERVICE_NAME ~]$ sqlplus $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAMEpassword -SQL> select sysdate from dual; + service_name account:
[$OPENACS_SERVICE_NAME ~]$ sqlplus $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAMEpassword +SQL> select sysdate from dual; SYSDATE ---------- 2001-12-20 -SQL> exit;
+SQL> exit;
You should see today's date in a format 'YYYY-MM-DD.' If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in - Section , “Troubleshooting Oracle Dates” -
Prepare PostgreSQL for an OpenACS Service.
PostgreSQL:
Create a user in the database matching the service - name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.
[root root]# su - postgres -[postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME + Troubleshooting Oracle Dates +
Prepare PostgreSQL for an OpenACS Service.
PostgreSQL:
Create a user in the database matching the service + name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine.
[root root]# su - postgres +[postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME CREATE USER -[postgres pgsql]$ exit +[postgres pgsql]$ exit logout -[root root]#
Create a database with the same name as our service name, $OPENACS_SERVICE_NAME. The full pathname for createdb needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME +[root root]#
Create a database with the same name as our service name, $OPENACS_SERVICE_NAME. The full pathname for createdb needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/createdb -E UNICODE $OPENACS_SERVICE_NAME CREATE DATABASE [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ su - $OPENACS_SERVICE_NAME -/usr/local/pgsql/bin/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 +/usr/local/pgsql/bin/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, - you can add > /dev/null - 2>&1 to the end of each crontab - line
Add Full Text Search Support (OPTIONAL)
At this point the database should be ready for installing OpenACS.
Configure an AOLserver Service for OpenACS.
+ you can add > /dev/null + 2>&1 to the end of each crontab + line
Add Full Text Search Support (OPTIONAL)
At this point the database should be ready for installing OpenACS.
Configure an AOLserver Service for OpenACS.
The AOLserver architecture lets you run an arbitrary number of virtual servers. A virtual server is an HTTP service running on a specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, - /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl. - 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 + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl. + 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
- You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines. -
httpport - If you want your - server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.
httpsport - This is the + You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines. +
httpport - If you want your + server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.
httpsport - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 443 to - match the standard.
- address - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.
server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses $OPENACS_SERVICE_NAME. + match the standard.
+ address - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.
server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses $OPENACS_SERVICE_NAME. -
db_name - In almost all cases, +
db_name - In almost all cases, this can be kept as a reference to $server. If for some reason, the tablespace you are using is different than your servername, then you can set it here. You should have a good reason for doing this. -
- servername - This is just a *pretty* name for your server.
user_account - The account that +
+ servername - This is just a *pretty* name for your server.
user_account - The account that will both own OpenACS files and connect to the database (for - Postgresql).
debug - Set to true for a very verbose error log, including many lines for every page view, success or failure.
+ Postgresql).
debug - Set to true for a very verbose error log, including many lines for every page view, success or failure.
AOLserver is very configurable. These settings should get you - started, but for more options, read the AOLserver + started, but for more options, read the AOLserver docs. -
Enable OpenFTS Full Text Search (OPTIONAL)
Install nsopenssl - for SSL support. (OPTIONAL)
Verify AOLserver startup.
+
Enable OpenFTS Full Text Search (OPTIONAL)
Install nsopenssl + for SSL support. (OPTIONAL)
Verify AOLserver startup.
Kill any current running AOLserver processes and start a new - one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run.
If you want to use port 80, there are complications. AOLserver must be root to use system ports such as + one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run.
If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the $OPENACS_SERVICE_NAME user via - grep $OPENACS_SERVICE_NAME - /etc/passwd and then put those numbers into - the command line via -u + grep $OPENACS_SERVICE_NAME + /etc/passwd and then put those numbers into + the command line via -u 501 -g - 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.
If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep - nsd and selectively kill by job number.
[$OPENACS_SERVICE_NAME etc]$ killall nsd + 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments.
If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep + nsd and selectively kill by job number.
[$OPENACS_SERVICE_NAME etc]$ killall nsd nsd: no process killed -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file... -[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.
- Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000
- You should see a page that looks like this. If you imported your files into +[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.
+ Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000
+ You should see a page that looks like this. If you imported your files into cvs, now that you know it worked you can erase the temp - directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig. + directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig.
If you don't see the login page, view your error log - (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) + (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and aolserver failing to start due to permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with - killall nsd. -
Automate - AOLserver keepalive (OPTIONAL)
Configure a Service with the OpenACS + killall nsd. +
Automate + AOLserver keepalive (OPTIONAL)
Configure a Service with the OpenACS Installer. Now that you've got AOLserver up and running, let's install OpenACS 5.6.0. -
+
You should see a page from the webserver titled - OpenACS Installation: - Welcome. You will be warned if your version of + OpenACS Installation: + Welcome. You will be warned if your version of the database driver is out of date, if AOLserver cannot connect to the database, if any modules are missing or out-of-date, or if there are any problems with filesystem permissions on the server side. But if everything is fine, you can click - Next to proceed to load the + Next to proceed to load the OpenACS Kernel data model. -
+
The next page shows the results of loading the OpenACS Kernel data model - be prepared to wait a few minutes as it works. You @@ -334,55 +334,55 @@ Loading package .info files ... this will take a few minutes
This will really take a few minutes. Have faith! Finally, another - Next button will appear at the + Next button will appear at the bottom - click it. -
+
The following page shows the results of loading the core package data models. You should see positive results for each of the previously selected packages, but watch out for any - errors. Eventually, the page will display "Generating secret - tokens" and then "Done"- click - Next. + errors. Eventually, the page will display "Generating secret + tokens" and then "Done"- click + Next. -
+
- You should see a page, "OpenACS Installation: Create - Administrator" with form fields to define the OpenACS site + You should see a page, "OpenACS Installation: Create + Administrator" with form fields to define the OpenACS site administrator. Fill out the fields as appropriate, and click - Create User. + Create User. -
- You should see a page, "OpenACS Installation: Set System - Information" allowing you to name your service. Fill out the - fields as appropriate, and click Set System - Information -
- You'll see the final Installer page, "OpenACS - Installation: Complete." It will tell you that the server is +
+ You should see a page, "OpenACS Installation: Set System + Information" allowing you to name your service. Fill out the + fields as appropriate, and click Set System + Information +
+ You'll see the final Installer page, "OpenACS + Installation: Complete." It will tell you that the server is being restarted; note that unless you already set up a way for - AOLserver to restart itself (ie. inittab or daemontools), + AOLserver to restart itself (ie. inittab or daemontools), you'll need to manually restart your service. -
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl
+
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl
Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS 5.6.0 is now up and running! -
Installation Option 3: Install from CVS
If you want to track fresh code developments inbetween releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: CVS Checkout Instructions. So, instead of tar xzf /var/tmp/openacs-5.6.0.tgz, cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co acs-core.
Next Steps
Use daemontools supervise and svc, or inittab, to automate server startup and shutdown.
Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled - OpenFTS, you can now install the OpenFTS Driver package and - Full Text Search Engine package in the OpenACS service.
This is a good time to make a backup of your service. If this is a - production site, you should set up automatic nightly backups.
If you want traffic reports, set up analog or another log - processing program.
Follow the instruction on the home page to +
Installation Option 3: Install from CVS
If you want to track fresh code developments inbetween releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: CVS Checkout Instructions. So, instead of tar xzf /var/tmp/openacs-5.6.0.tgz, cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co acs-core.
Next Steps
Use daemontools supervise and svc, or inittab, to automate server startup and shutdown.
Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled + OpenFTS, you can now install the OpenFTS Driver package and + Full Text Search Engine package in the OpenACS service.
This is a good time to make a backup of your service. If this is a + production site, you should set up automatic nightly backups.
If you want traffic reports, set up analog or another log + 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 database, because those environmental variables are set by the - wrapper scripts nsd-postgres and nsd-oracle.
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc
Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.
PostgreSQL:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib -export PATH=$PATH:/usr/local/pgsql/bin
Oracle. These environment variables are specific for a local Oracle + wrapper scripts nsd-postgres and nsd-oracle.
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc
Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.
PostgreSQL:
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib +export PATH=$PATH:/usr/local/pgsql/bin
Oracle. These environment variables are specific for a local Oracle installation communicating via IPC. If you are connecting to a remote Oracle installation, you'll need to adjust these appropriately. Also, make sure that the '8.1.7' matches your Oracle version. @@ -393,18 +393,18 @@ export ORACLE_SID=ora8 export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
Test this by logging out and back in as - $OPENACS_SERVICE_NAME and checking the paths.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit + $OPENACS_SERVICE_NAME and checking the paths.
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit logout -[root src]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME ~]$ env -
For PostgreSQL, you should see:
+[root src]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME ~]$ env +
For PostgreSQL, you should see:
LD_LIBRARY_PATH=:/usr/local/pgsql/lib PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\ - /root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin
For Oracle:
ORACLE_BASE=/ora8/m01/app/oracle + /root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin
For Oracle:
ORACLE_BASE=/ora8/m01/app/oracle ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7 PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\ /root/bin:/ora8/m01/app/oracle/product/8.1.7/bin LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib ORACLE_SID=ora8 ORACLE_TERM=vt100 -ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
Test your backup and recovery procedure.
Set up Section , “External uptime validation”.
($Id$)
Prev Home Next
Install AOLserver 4 Up OpenACS Installation Guide for Windows2000
docs@openacs.org
View comments on this page at openacs.org +ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data
Test your backup and recovery procedure.
Set up External uptime validation.
($Id$)
Prev Home Next
Install AOLserver 4 Up OpenACS Installation Guide for Windows2000
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/oracle.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/oracle.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,73 +1,73 @@ - -Install Oracle 8.1.7
Prev Chapter 3. Complete Installation Next
Install Oracle 8.1.7
By Vinod Kurup
+ +Install Oracle 8.1.7
Prev Chapter 3. Complete Installation Next
Install Oracle 8.1.7
By Vinod Kurup
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
If you are installing PostGreSQL instead of Oracle, skip this section.
- OpenACS 5.6.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance. + OpenACS 5.6.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See Andrew Piskorski's Oracle 9i notes for guidance.
- This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T + This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is unsuitable for production systems. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T
This document assumes that you'll be installing Oracle on the same box as AOLserver. For more details on a remote Oracle installation, - see Daryl Biberdorf's document. + see Daryl Biberdorf's document.
- Useful links to find help on how to set up Oracle under Linux are:
Dizwell - Howard - Roger's company - on Oracle on Linux
Werner Puschitz - Oracle on Red Hat Linux
SuSE/Oracle Support matrix
Acquire Oracle
+ Useful links to find help on how to set up Oracle under Linux are:
Dizwell - Howard + Roger's company - on Oracle on Linux
Werner Puschitz - Oracle on Red Hat Linux
SuSE/Oracle Support matrix
Acquire Oracle
Production Oracle systems should run on certified platforms. Follow the - metalink + metalink note 223718.1to find certified platforms. If you don't have - metalink access, take a look at the Oracle on Linux FAQ: Which + metalink access, take a look at the Oracle on Linux FAQ: Which Linux Distributions Are Directly Supported By Oracle?. In summary, free and inexpensive Linux distributions are not certified.
- If you don't have an account at OTN - get one: you can download the Oracle software from the + If you don't have an account at OTN + get one: you can download the Oracle software from the Oracle Downloads page. It is also get the CDs shipped to you for - a nominal fee from the Oracle + a nominal fee from the Oracle Store.
Each Oracle release comes with extensive and usually quite well-written documentation. Your first step should be to thoroughly read the release notes for your operating system and your Oracle version. Find the docs - here:
- Oracle 8i - Release Documentation
- Oracle 9i Release Documentation -
- Oracle + here:
+ Oracle 8i + Release Documentation
+ Oracle 9i Release Documentation +
+ Oracle 10g Release Documentation
It is generally useful to run a particular Oracle version with its latest patchset. At the time of writing these were 8.1.7.4 and 9.2.0.5, both of which are considered to be very stable.
- To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate - patchset by following Andrew's + To be able to download a patchset, you need a (to-pay-for) account on Metalink. You may find the appropriate + patchset by following Andrew's suggestion. -
Things to Keep in Mind
- Oracle is very well-documented software, the online documentation comes with +
Things to Keep in Mind
+ Oracle is very well-documented software, the online documentation comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle within in a few hours. The best starting pointing into Oracle is the - Concepts book. Here's the 8i - version and the 9.2 + Concepts book. Here's the 8i + version and the 9.2 version.
To give you an idea of how configurable Oracle is and how much thought you may need to put into buying the proper hardware and creating a sane - setup, you should thoroughly read Cary Millsap's Configuring - Oracle Server for VLDB and the Optimal + setup, you should thoroughly read Cary Millsap's Configuring + Oracle Server for VLDB and the Optimal Flexible Architecture standard.
Throughout these instructions, we will refer to a number of configurable settings and advise certain defaults. With the exception of passwords, we advise you to follow these defaults unless you know what you are doing. Subsequent documents will expect that you used the defaults, so a change made here will necessitate further changes - later. For a guide to the defaults, please see Section , “Defaults”. + later. For a guide to the defaults, please see Defaults.
In order for OpenACS to work properly you need to set the environment @@ -83,30 +83,30 @@ umask 022
open_cursors = 500
-nls_date_format = "YYYY-MM-DD"
+nls_date_format = "YYYY-MM-DD"
- For additional resources/documentation, please see this thread - and Andrew + For additional resources/documentation, please see this thread + and Andrew Piskorski's mini-guide. -
Pre-Installation Tasks
+
Pre-Installation Tasks
Though Oracle 8.1.7 has an automated installer, we still need to perform several manual, administrative tasks before we can launch it. You must perform all of these steps as the - root user. We recommend entering the - X window system as a normal user and then doing a su - -. This command gives you full root access. + root user. We recommend entering the + X window system as a normal user and then doing a su + -. This command gives you full root access. -
+
Login as a non-root user and start X by typing - startx + startx
[joeuser ~]$ startx
-
+
Open a terminal window type and login as root @@ -115,14 +115,14 @@ Password: *********** [root ~]#
-
+
- Create and setup the oracle - group and oracle account + Create and setup the oracle + group and oracle account
- We need to create a user oracle, + We need to create a user oracle, which is used to install the product, as well as starting and stopping the database. @@ -136,42 +136,42 @@ You will be prompted for the New Password and Confirmation of that password. -
+
Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has - adopted /ora8 as the base + adopted /ora8 as the base directory.
- Note: the Oracle install needs - about 1 GB free on /ora8 to + Note: the Oracle install needs + about 1 GB free on /ora8 to install successfully.
[root ~]# mkdir /ora8 root:/ora8# cd /ora8 root:/ora8# mkdir -p m01 m02 m03/oradata/ora8 root:/ora8# chown -R oracle.dba /ora8 -root:/ora8# exit
+root:/ora8# exit
- Set up the oracle user's + Set up the oracle user's environment -
+
Log in as the user - oracle by typing the + oracle by typing the following:
[joeuser ~]$ su - oracle -Password: ********
+Password: ********
Use a text editor to edit the - .bash_profile file in the - oracle account home + .bash_profile file in the + oracle account home directory.
@@ -180,7 +180,7 @@ You may get this error trying to start emacs:
-Xlib: connection to ":0.0" refused by server +Xlib: connection to ":0.0" refused by server Xlib: Client is not authorized to connect to Server emacs: Cannot connect to X server :0. Check the DISPLAY environment variable or use `-d'. @@ -201,11 +201,11 @@ Try this procedure anytime you get an Xlib connection refused error. -
+
Add the following lines (substituting your Oracle version number as needed) to - .bash_profile: + .bash_profile:
export ORACLE_BASE=/ora8/m01/app/oracle @@ -218,14 +218,14 @@ umask 022
- Save the file by typing CTRL-X - CTRL-S and then exit by typing - CTRL-X - CTRL-C. Alternatively, use the menus. + Save the file by typing CTRL-X + CTRL-S and then exit by typing + CTRL-X + CTRL-C. Alternatively, use the menus.
- Make sure that you do not add + Make sure that you do not add any lines like the following
@@ -236,18 +236,18 @@ OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD dates. -
+
Log out as oracle
-[oracle ~]$ exit
+[oracle ~]$ exit
- Log back in as oracle and double + Log back in as oracle and double check that your environment variables are as intended. The - env command lists all of the + env command lists all of the variables that are set in your environment, and - grep shows you just the lines + grep shows you just the lines you want (those with ORA in it).
@@ -264,57 +264,57 @@ ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data
If not, try adding the files to - ~/.bashrc instead of - .bash_profile. Then logout and + ~/.bashrc instead of + .bash_profile. Then logout and log back in again. Also, be certain you are doing - su - oracle and not just - su oracle. The - - means that - .bashrc and - .bash_profile will be + su - oracle and not just + su oracle. The + - means that + .bashrc and + .bash_profile will be evaluated.
- Make sure that /bin, - /usr/bin, and - /usr/local/bin are in your path + Make sure that /bin, + /usr/bin, and + /usr/local/bin are in your path by typing:
[oracle ~]$ echo $PATH /bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin
If they are not, then add them to the - .bash_profile by changing the + .bash_profile by changing the PATH statement above to - PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin + PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin -
Installing Oracle 8.1.7 Server
- Log in as oracle and +
Installing Oracle 8.1.7 Server
+ Log in as oracle and start X if not already running. Start a new terminal:
[joeuser ~]$ xhost +localhost [joeuser ~]$ su - oracle Password: ********** -[oracle ~]$ export DISPLAY=localhost:0.0
+[oracle ~]$ export DISPLAY=localhost:0.0
- Find the runInstaller script + Find the runInstaller script -
+
If you are installing Oracle from a CD-ROM, it is located in - the install/linux path from + the install/linux path from the cd-rom mount point
[oracle ~]$ su - root [root ~]# mount -t iso9660 /dev/cdrom /mnt/cdrom [root ~]# exit -[oracle ~]$ cd /mnt/cdrom
+[oracle ~]$ cd /mnt/cdrom
If you are installing from the tarball, the install script is - located in the Oracle8iR2 + located in the Oracle8iR2 directory that was created when you expanded the archive.
@@ -327,10 +327,10 @@ doc index.htm install runInstaller stage starterdb
If you don't see - runInstaller, you are in the + runInstaller, you are in the wrong directory. -
+
Run the installer @@ -339,76 +339,76 @@ A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on - "Next" + "Next" -
Note
+
Note
Some people have had trouble with this step on RedHat 7.3 and 8.0. If so, try the following steps before calling - ./runInstaller: + ./runInstaller: -
+
Execute the following command: - /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh + /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh -
+
- Type export LD_ASSUME_KERNEL=2.2.5 + Type export LD_ASSUME_KERNEL=2.2.5 -
+
- The "File Locations" screen in the OUI: + The "File Locations" screen in the OUI: -
+
- "Source" path should have been - prefilled with "(wherever you mounted the - CDROM)/stage/products.jar" + "Source" path should have been + prefilled with "(wherever you mounted the + CDROM)/stage/products.jar" -
+
- "destination" path says - "/ora8/m01/app/oracle/product/8.1.7" + "destination" path says + "/ora8/m01/app/oracle/product/8.1.7"
If the destination is not correct it is because your environment variables are not set properly. Make sure you - logged on as oracle using - su - oracle. If so, edit the - ~/.bash_profile as you - did in Section , “Pre-Installation Tasks” + logged on as oracle using + su - oracle. If so, edit the + ~/.bash_profile as you + did in Pre-Installation Tasks -
+
- Click "Next" (a pop up window will display Loading + Click "Next" (a pop up window will display Loading Product information). -
+
- The "Unix Group Name" screen in the OUI: + The "Unix Group Name" screen in the OUI: -
+
The Unix Group name needs to be set to - 'oinstall' ( we made + 'oinstall' ( we made this Unix group earlier ). -
+
- Click "Next" + Click "Next" -
+
A popup window appears instantly, requesting you to run a script as root: -
+
Debian users need to link - /bin/awk to - /usr/bin/awk before + /bin/awk to + /usr/bin/awk before running the script below
[joueser ~]$ su - -[root ~]# ln -s /usr/bin/awk /bin/awk
+[root ~]# ln -s /usr/bin/awk /bin/awk
Open a new terminal window, then type:
[joeuser ~]$ su - [root ~]# cd /ora8/m01/app/oracle/product/8.1.7 @@ -418,120 +418,120 @@ Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall. [root ~]# mkdir -p /usr/local/java [root ~]# exit -[joeuser ~]$ exit
- Click "Retry" -
- The "Available Products" screen in the OUI: -
- Select "Oracle 8i Enterprise Edition 8.1.7.1.0" -
- Click "Next" -
- The "Installation Types" screen -
- Select the "Custom" installation type. -
- Click "Next" -
- The "Available Product Components" screen -
- In addition to the defaults, make sure that "Oracle SQLJ - 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and - "Linux Documentation 8.1.7.0.0" are also checked. -
- Click "Next" -
+[joeuser ~]$ exit
+ Click "Retry" +
+ The "Available Products" screen in the OUI: +
+ Select "Oracle 8i Enterprise Edition 8.1.7.1.0" +
+ Click "Next" +
+ The "Installation Types" screen +
+ Select the "Custom" installation type. +
+ Click "Next" +
+ The "Available Product Components" screen +
+ In addition to the defaults, make sure that "Oracle SQLJ + 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and + "Linux Documentation 8.1.7.0.0" are also checked. +
+ Click "Next" +
A progress bar will appear for about 1 minute. -
- The "Component Locations" screen in the OUI -
- Click on the "Java Runtime Environment 1.1.8" It +
+ The "Component Locations" screen in the OUI +
+ Click on the "Java Runtime Environment 1.1.8" It should have the path - "/ora8/m01/app/oracle/jre/1.1.8" -
- Click "Next" -
+ "/ora8/m01/app/oracle/jre/1.1.8" +
+ Click "Next" +
A progress bar will appear for about 1 minute. -
- The "Privileged Operation System Groups" screen in the +
+ The "Privileged Operation System Groups" screen in the OUI -
- Enter "dba" for "Database Administrator - (OSDBA) Group" -
- Enter "dba" for the "Database Operator - (OSOPER) Group" -
- Click "Next" -
+
+ Enter "dba" for "Database Administrator + (OSDBA) Group" +
+ Enter "dba" for the "Database Operator + (OSOPER) Group" +
+ Click "Next" +
A progress bar will appear for about 1 minute. -
- The "Authentication Methods" screen -
- Click "Next" -
+
+ The "Authentication Methods" screen +
+ Click "Next" +
- The next screen is "Choose JDK home directory" + The next screen is "Choose JDK home directory" -
+
- Keep the default path: /usr/local/java + Keep the default path: /usr/local/java -
+
- Click "Next" + Click "Next" -
+
- The "Create a Database" screen in the OUI + The "Create a Database" screen in the OUI -
+
- Select "No" as we will do this later, after some + Select "No" as we will do this later, after some important configuration changes. -
+
- Click "Next" + Click "Next" -
+
- The next screen is "Oracle Product Support" + The next screen is "Oracle Product Support" -
+
- TCP should be checked with "Status" listed as + TCP should be checked with "Status" listed as Required -
+
- Click "Next" + Click "Next" -
+
- The "Summary" screen in the OUI + The "Summary" screen in the OUI -
+
- Check the "Space Requirements" section to verify + Check the "Space Requirements" section to verify you have enough disk space for the install. -
- Check that "(144 products)" is in the "New - Installations" section title. -
- Click "Install" -
+
+ Check that "(144 products)" is in the "New + Installations" section title. +
+ Click "Install" +
A progress bar will appear for about 20 - 30 minutes. Now is a good time to take a break. -
- A "Setup Privileges" window will popup towards the +
+ A "Setup Privileges" window will popup towards the end of the installation asking you to run a script as - root -
+ root +
Run the script. Switch to the oracle user first to set the environment appropriately and then do - su to get root privileges, while keeping + su to get root privileges, while keeping the oracle user's enviroment.
[joeuser ~]$ su - oracle @@ -552,7 +552,7 @@ Enter the full pathname of the local bin directory: [/usr/local/bin]: -Press ENTER here to accept default of /usr/local/bin +Press ENTER here to accept default of /usr/local/bin Creating /etc/oratab file... @@ -564,294 +564,294 @@ created by the Oracle Enterprise Manager Intelligent Agent. These files may be found in the directories you use for storing other Net8 log and trace files. - If such files exist, the OEM IA may not restart.
+ If such files exist, the OEM IA may not restart.
Do not follow the instructions on deleting trace and log files, it is not necessary.
[root ~]# exit -[joeuser ~]$ exit
- Go back to the pop-up window and click "OK" -
- The "Configuration Tools" screen in the OUI -
+[joeuser ~]$ exit
+ Go back to the pop-up window and click "OK" +
+ The "Configuration Tools" screen in the OUI +
This window displays the config tools that will automatically be launched. -
- The "Welcome" screen in the "net 8 Configuration - Assistant" -
- Make sure the "Perform Typical installation" is - not selected. -
- Click "Next" -
- The "Directory Service Access" screen in the - "Net 8 Configuration Assistant" -
- Select "No" -
- Click "Next" -
- The "Listener Configuration, Listener Name" screen in - the "Net 8 Configuration Assistant" -
- Accept the default listener name of "LISTENER" -
- Click "Next" -
- The "Listener Configuration, Select - Protocols" screen in the "Net 8 Configuration - Assistant" -
- The only choice in "Select protocols:" should be - "TCP/IP" -
- Click "Next" -
- The "Listener Configuration TCP/IP Protocol" screen in - the "Net 8 Configuration Assistant" -
+
+ The "Welcome" screen in the "net 8 Configuration + Assistant" +
+ Make sure the "Perform Typical installation" is + not selected. +
+ Click "Next" +
+ The "Directory Service Access" screen in the + "Net 8 Configuration Assistant" +
+ Select "No" +
+ Click "Next" +
+ The "Listener Configuration, Listener Name" screen in + the "Net 8 Configuration Assistant" +
+ Accept the default listener name of "LISTENER" +
+ Click "Next" +
+ The "Listener Configuration, Select + Protocols" screen in the "Net 8 Configuration + Assistant" +
+ The only choice in "Select protocols:" should be + "TCP/IP" +
+ Click "Next" +
+ The "Listener Configuration TCP/IP Protocol" screen in + the "Net 8 Configuration Assistant" +
Default Port should be 1521 and selected. -
- Click "Next" -
- The "Listener Configuration, More Listeners" screen in - the "Net 8 Configuration Assistant" -
- Select "No" -
- Click "Next" -
- The "Listener Configuration Done" screen in the - "Net 8 Configuration Assistant" -
- Click "Next" -
- The "Naming Methods Configuration" screen - in the "Net 8 Configuration Assistant" -
- Select "No" -
- Click "Next" -
- The "Done" screen in the "Net 8 Configuration - Assistant" -
- Click "Finish" -
- The "End of Installation" screen in the OUI -
- Click "Exit" -
- Click "Yes" on the confirmation pop up window. -
+
+ Click "Next" +
+ The "Listener Configuration, More Listeners" screen in + the "Net 8 Configuration Assistant" +
+ Select "No" +
+ Click "Next" +
+ The "Listener Configuration Done" screen in the + "Net 8 Configuration Assistant" +
+ Click "Next" +
+ The "Naming Methods Configuration" screen + in the "Net 8 Configuration Assistant" +
+ Select "No" +
+ Click "Next" +
+ The "Done" screen in the "Net 8 Configuration + Assistant" +
+ Click "Finish" +
+ The "End of Installation" screen in the OUI +
+ Click "Exit" +
+ Click "Yes" on the confirmation pop up window. +
The Oracle Universal Installer window should have disappeared!
Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about an hour of non-interactive time, so don't quit yet. -
Creating the First Database
+
Creating the First Database
This step will take you through the steps of creating a customized database. Be warned that this process takes about an hour on a Pentium II with 128 MB of RAM. -
Note
RedHat 7.3 and 8.0 users: Before running dbassist, do the following.
- Download the glibc - patch from Oracle Technet into /var/tmp. -
+
Note
RedHat 7.3 and 8.0 users: Before running dbassist, do the following.
+ Download the glibc + patch from Oracle Technet into /var/tmp. +
cd $ORACLE_HOME -
+
tar xzf /var/tmp/glibc2.1.3-stubs.tgz -
+
./setup_stubs -
+
Make sure you are running X. Open up a terminal and - su to oracle and then run the - dbassist program. + su to oracle and then run the + dbassist program.
[joeuser ~]$ xhost +localhost [joeuser ~]$ su - oracle Password: ********* [oracle ~]$ export DISPLAY=localhost:0.0 -[oracle ~]$ dbassist
- The "Welcome" screen in the Oracle Database +[oracle ~]$ dbassist
+ The "Welcome" screen in the Oracle Database Configuration Agent (ODCA) -
- Select "Create a database" -
- Click "Next" -
- The "Select database type" screen in the ODCA -
- Select "Custom" -
- Click "Next" -
- The "Primary Database Type" window in ODCA -
- Select "Multipurpose" -
- Click "Next" -
- The "concurrent users" screen of the ODCA -
- Select "60" concurrent users. -
- Click "Next" -
- Select "Dedicated Server - Mode", click - "Next" -
+
+ Select "Create a database" +
+ Click "Next" +
+ The "Select database type" screen in the ODCA +
+ Select "Custom" +
+ Click "Next" +
+ The "Primary Database Type" window in ODCA +
+ Select "Multipurpose" +
+ Click "Next" +
+ The "concurrent users" screen of the ODCA +
+ Select "60" concurrent users. +
+ Click "Next" +
+ Select "Dedicated Server + Mode", click + "Next" +
Accept all of the options, and click - Next Oracle Visual + Next Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that everything else is checked. -
- For "Global Database Name", enter - "ora8"; for - "SID", also enter - "ora8" (it should do - this automatically). Click "Change - Character Set and select - UTF8. Click - "Next". -
+
+ For "Global Database Name", enter + "ora8"; for + "SID", also enter + "ora8" (it should do + this automatically). Click "Change + Character Set and select + UTF8. Click + "Next". +
Accept the defaults for the next screen (control file location). Click - "Next" -
- Go to the "temporary" and - "rollback" tabs, and change the Size + "Next" +
+ Go to the "temporary" and + "rollback" tabs, and change the Size (upper-right text box) to - 150MB. Click - "Next" -
+ 150MB. Click + "Next" +
Increase the redo log sizes to - 10000K each. Click - "Next" -
+ 10000K each. Click + "Next" +
Use the default checkpoint interval & timeout. Click - "Next" -
- Increase "Processes" - to 100; - "Block Size" to - 4096 (better for small Linux + "Next" +
+ Increase "Processes" + to 100; + "Block Size" to + 4096 (better for small Linux boxes; use 8192 for a big Solaris machine). -
+
Accept the defaults for the Trace File Directory. Click - "Next" -
- Finally, select "Save information to a shell - script" and click - "Finish" (We're + "Next" +
+ Finally, select "Save information to a shell + script" and click + "Finish" (We're going to examine the contents of this file before creating our database.) -
- Click the "Save" +
+ Click the "Save" button. Oracle will automatically save it to the correct directory and with the correct file name. This will likely be - /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh -
+ /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh +
It will alert you that the script has been saved successfully. -
+
Now we need to customize the database configuration a bit. While - still logged on as oracle, edit + still logged on as oracle, edit the database initialization script (run when the db loads). The scripts are kept in - $ORACLE_HOME/dbs and the name of + $ORACLE_HOME/dbs and the name of the script is usually - initSID.ora + initSID.ora where SID is the SID of your database. Assuming your - $ORACLE_HOME matches our default + $ORACLE_HOME matches our default of - /ora8/m01/app/oracle/product/8.1.7, + /ora8/m01/app/oracle/product/8.1.7, the following will open the file for editing.
-[oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
+[oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora
Add the following line to the end:
-nls_date_format = "YYYY-MM-DD"
- Now find the open_cursors line +nls_date_format = "YYYY-MM-DD"
+ Now find the open_cursors line in the file. If you're using - emacs scroll up to the top of - the buffer and do CTRL-S and - type open_cursors to find the - line. The default is 100. Change - it to 500. + emacs scroll up to the top of + the buffer and do CTRL-S and + type open_cursors to find the + line. The default is 100. Change + it to 500.
-open_cursors = 500
- Save the file. In emacs, do CTRL-X - CTRL-S to save followed by - CTRL-X CTRL-C to exit or use +open_cursors = 500
+ Save the file. In emacs, do CTRL-X + CTRL-S to save followed by + CTRL-X CTRL-C to exit or use the menu. -
+
At this point, you are ready to initiate database creation. We recommend shutting down X to free up some RAM unless you have 256 MB of RAM or more. You can do this quickly by doing a - CRTL-ALT-BACKSPACE, but make + CRTL-ALT-BACKSPACE, but make sure you have saved any files you were editing. You should now be returned to a text shell prompt. If you get sent to a graphical login screen instead, switch to a virtual console by doing - CRTL-ALT-F1. Then login as - oracle. -
+ CRTL-ALT-F1. Then login as + oracle. +
Change to the directory where the database creation script is and run it:
[oracle ~]$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh
In some instances, Oracle will save the file to - /ora8/m01/app/oracle/product/8.1.7/assistants/dbca + /ora8/m01/app/oracle/product/8.1.7/assistants/dbca Try running the script there if your first attempt does not succeed. -
+
Your database will now be built. It will take > 1 hour - no fooling. You will see lots of errors scroll by (like: - "ORA-01432: public synonym to be dropped does not - exist") Fear not, this is normal. + "ORA-01432: public synonym to be dropped does not + exist") Fear not, this is normal.
Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it. -
Acceptance Test
+
Acceptance Test
For this step, open up a terminal and - su to - oracle as usual. You should be + su to + oracle as usual. You should be running X and Netscape (or other web browser) for this phase. -
- You need to download the "Oracle Acceptance Test" file. - It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. - Save the file to /var/tmp -
+
+ You need to download the "Oracle Acceptance Test" file. + It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. + Save the file to /var/tmp +
In the oracle shell, copy the file.
-[oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql
+[oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql
Once you've got the acceptance test file all set, stay in your term and type the following:
[oracle ~]$ sqlplus system/manager
- SQL*Plus should startup. If you get an ORA-01034: - Oracle not Available error, it is because your + SQL*Plus should startup. If you get an ORA-01034: + Oracle not Available error, it is because your Oracle instance is not running. You can manually start it as - the oracle user.
+ the oracle user.
[oracle ~]$ svrmgrl SVRMGR> connect internal -SVRMGR> startup
+SVRMGR> startup
Now that you're into SQL*Plus, change the default passwords - for system, sys, and ctxsys to "alexisahunk" (or to + for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember):
SQL> alter user system identified by alexisahunk; SQL> alter user sys identified by alexisahunk; -SQL> alter user ctxsys identified by alexisahunk;
+SQL> alter user ctxsys identified by alexisahunk;
Verify that your date settings are correct.
SQL> select sysdate from dual;
If you don't see a date that fits the format - YYYY-MM-DD, please read Section , “Troubleshooting Oracle Dates”. -
+ YYYY-MM-DD, please read Troubleshooting Oracle Dates. +
At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes.
@@ -865,76 +865,76 @@ 2000-06-10 SQL>
- Many people encounter an error regarding maximum - key length: + Many people encounter an error regarding maximum + key length:
ERROR at line 1: ORA-01450: maximum key length (758) exceeded
This error occurs if your database block size is wrong and is usually suffered by people trying to load OpenACS into a pre-existing database. Unfortunately, the only solution is to create a new database with a block size of at least - 4096. For instructions on how to - do this, see Section , “Creating the First Database” above. You + 4096. For instructions on how to + do this, see Creating the First Database above. You can set the parameter using the - dbassist program or by setting - the DB_BLOCK_SIZE parameter in + dbassist program or by setting + the DB_BLOCK_SIZE parameter in your database's creation script.
If there were no errors, then consider yourself fortunate. Your Oracle installation is working. -
Automating Startup & Shutdown
+
Automating Startup & Shutdown
You will want to automate the database startup and shutdown process. It's probably best to have Oracle spring to life when you boot up your machine. -
+
Oracle includes a script called - dbstart that can be used to + dbstart that can be used to automatically start the database. Unfortunately, the script shipped in the Linux distribution does not work out of the box. The fix is simple. Follow these directions to apply - it. First, save dbstart to - /var/tmp. Then, as - oracle, do the following: + it. First, save dbstart to + /var/tmp. Then, as + oracle, do the following:
[oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart -[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
+[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart
While you're logged in as - oracle, you should configure the - oratab file to load your + oracle, you should configure the + oratab file to load your database at start. Edit the file - /etc/oratab: -
You will see this line.
+ /etc/oratab: +
You will see this line.
ora8:/ora8/m01/app/oracle/product/8.1.7:N
By the way, if you changed the service name or have multiple databases, the format of this file is:
- service_name:$ORACLE_HOME:Y || N - (for autoload) -
- Change the last letter from "N" to - "Y". This tells Oracle that you want the database + service_name:$ORACLE_HOME:Y || N + (for autoload) +
+ Change the last letter from "N" to + "Y". This tells Oracle that you want the database to start when the machine boots. It should look like this.
-ora8:/ora8/m01/app/oracle/product/8.1.7:Y
+ora8:/ora8/m01/app/oracle/product/8.1.7:Y
Save the file & quit the terminal. -
- You need a script to automate startup and shutdown. Save oracle8i.txt in - /var/tmp. Then login as - root and install the +
+ You need a script to automate startup and shutdown. Save oracle8i.txt in + /var/tmp. Then login as + root and install the script. (Debian users: substitute - /etc/init.d for - /etc/rc.d/init.d throughout + /etc/init.d for + /etc/rc.d/init.d throughout this section)
[oracle ~]$ su - [root ~]# cp /var/tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i [root ~]# chown root.root /etc/rc.d/init.d/oracle8i -[root ~]# chmod 755 /etc/rc.d/init.d/oracle8i
+[root ~]# chmod 755 /etc/rc.d/init.d/oracle8i
Test the script by typing the following commands and checking the - output. (Debian Users: as root, do mkdir - /var/lock/subsys first) + output. (Debian Users: as root, do mkdir + /var/lock/subsys first)
[root ~]# /etc/rc.d/init.d/oracle8i stop Oracle 8i auto start/stop @@ -955,7 +955,7 @@ ORACLE instance shut down. SVRMGR> Server Manager complete. -Database "ora8" shut down. +Database "ora8" shut down. [root ~]# /etc/rc.d/init.d/oracle8i start Oracle 8i auto start/stop @@ -976,17 +976,17 @@ Database opened. SQL> Disconnected -Database "ora8" warm started. +Database "ora8" warm started. -Database "ora8" warm started.
+Database "ora8" warm started.
If it worked, then run these commands to make the startup and shutdown automatic. -
Red Hat users:
+
Red Hat users:
[root ~]# cd /etc/rc.d/init.d/ [root ~]# chkconfig --add oracle8i [root ~]# chkconfig --list oracle8i ; You should see: -oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off
Debian users:
+oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off
Debian users:
[root ~]# update-rc.d oracle8i defaults Adding system startup for /etc/init.d/oracle8i ... /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i @@ -995,7 +995,7 @@ /etc/rc2.d/S20oracle8i -> ../init.d/oracle8i /etc/rc3.d/S20oracle8i -> ../init.d/oracle8i /etc/rc4.d/S20oracle8i -> ../init.d/oracle8i - /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i
SuSE users:
+ /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i
SuSE users:
[root ~]# cd /etc/rc.d/init.d root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i K20oracle8i root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i S20oracle8i @@ -1035,24 +1035,24 @@ Executing /sbin/conf.d/SuSEconfig.tetex... Executing /sbin/conf.d/SuSEconfig.ypclient... Processing index files of all manpages... -Finished.
+Finished.
You also need some scripts to automate startup and shutdown of the Oracle8i listener. The listener is a name server that allows your Oracle programs to talk to local and remote databases using a standard naming convention. It is required for Intermedia Text and full site search.
Download these three scripts into - /var/tmp -
- startlsnr.txt -
- stoplsnr.txt -
- listener8i.txt + /var/tmp +
+ startlsnr.txt +
+ stoplsnr.txt +
+ listener8i.txt
Now issue the following commands (still as - root). + root).
[root ~]# su - oracle [oracle ~]$ cp /var/tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr @@ -1112,8 +1112,8 @@ normally. Login into the database using the listener naming convention.
- sqlplus - username/password/@SID + sqlplus + username/password/@SID
[root ~]# su - oracle [oracle ~]$ sqlplus system/alexisahunk@ora8 @@ -1126,16 +1126,16 @@ SQL> exit [oracle ~]$ exit -[root ~]#
RedHat users:
- Now run chkconfig on the - listener8i script. +[root ~]#
RedHat users:
+ Now run chkconfig on the + listener8i script.
[root ~]# cd /etc/rc.d/init.d/ root:/etc/rc.d/init.d# chkconfig --add listener8i root:/etc/rc.d/init.d# chkconfig --list listener8i -listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off
Debian users:
- Now run update-rc.d on the - listener8i script. +listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off
Debian users:
+ Now run update-rc.d on the + listener8i script.
[root ~]# update-rc.d listener8i defaults 21 19 Adding system startup for /etc/init.d/listener8i ... @@ -1145,7 +1145,7 @@ /etc/rc2.d/S21listener8i -> ../init.d/listener8i /etc/rc3.d/S21listener8i -> ../init.d/listener8i /etc/rc4.d/S21listener8i -> ../init.d/listener8i - /etc/rc5.d/S21listener8i -> ../init.d/listener8i
+ /etc/rc5.d/S21listener8i -> ../init.d/listener8i
Test the automation
As a final test, reboot your computer and make sure Oracle comes @@ -1160,30 +1160,30 @@ SQL> exit
Congratulations, your installation of Oracle 8.1.7 is complete. -
Troubleshooting Oracle Dates
+
Troubleshooting Oracle Dates
Oracle has an internal representation for storing the data based on the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, it uses an Oracle-specific format which isn't copacetic. You want Oracle to use the ANSI-compliant date format which is of form - 'YYYY-MM-DD'. + 'YYYY-MM-DD'.
To fix this, you should include the following line in - $ORACLE_HOME/dbs/initSID.ora + $ORACLE_HOME/dbs/initSID.ora or for the default case, - $ORACLE_HOME/dbs/initora8.ora + $ORACLE_HOME/dbs/initora8.ora
-nls_date_format = "YYYY-MM-DD"
+nls_date_format = "YYYY-MM-DD"
You test whether this solved the problem by firing up - sqlplus and typing: + sqlplus and typing:
SQL> select sysdate from dual;
You should see back a date like - 2000-06-02. If some of the date is - chopped off, i.e. like 2000-06-0, + 2000-06-02. If some of the date is + chopped off, i.e. like 2000-06-0, everything is still fine. The problem here is that - sqlplus is simply truncating the + sqlplus is simply truncating the output. You can fix this by typing:
SQL> column sysdate format a15 @@ -1210,32 +1210,32 @@ Setting this environment variable will override the date setting. Either delete this line and login again or add the following entry to your login scripts after the - nls_lang line: + nls_lang line:
export nls_date_format = 'YYYY-MM-DD'
Log back in again. If adding the - nls_date_format line doesn't - help, you can ask for advice in our OpenACS forums. -
Useful Procedures
+ nls_date_format line doesn't + help, you can ask for advice in our OpenACS forums. +
Useful Procedures
Dropping a tablespace -
+
Run sqlplus as the dba:
-[oracle ~]$ sqlplus system/changeme
+[oracle ~]$ sqlplus system/changeme
To drop a user and all of the tables and data owned by that user:
-SQL> drop user oracle_user_name cascade;
+SQL> drop user oracle_user_name cascade;
To drop the tablespace: This will delete everything in the tablespace overriding any referential integrity constraints. Run this command only if you want to clean out your database entirely.
SQL> drop tablespace table_space_name including contents cascade constraints;
- For more information on Oracle, please consult the documentation. -
Oracle Next Steps
Section , “Creating an appropriate tuning and monitoring environment”
Defaults
We used the following defaults while installing Oracle.
Variable Value Reason
ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.
ORACLE_SERVICE ora8 The service name is a domain-qualified identifier for + For more information on Oracle, please consult the documentation. +
Oracle Next Steps
Creating an appropriate tuning and monitoring environment
Defaults
We used the following defaults while installing Oracle.
Variable Value Reason
ORACLE_HOME /ora8/m01/app/oracle/product/8.1.7 This is the default Oracle installation directory.
ORACLE_SERVICE ora8 The service name is a domain-qualified identifier for your Oracle server.
ORACLE_SID ora8 This is an identifier for your Oracle server.
ORACLE_OWNER oracle The user who owns all of the oracle files.
ORACLE_GROUP dba The special oracle group. Users in the dba group are - authorized to do a connect - internal within - svrmgrl to gain full system + authorized to do a connect + internal within + svrmgrl to gain full system access to the Oracle system.
($Id$)
Prev Home Next
Install a Unix-like system and supporting software Up Install PostgreSQL
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/os-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-install.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/os-install.html 13 Sep 2009 23:54:40 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/os-install.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,24 +1,24 @@ - -Linux Install Guides
Prev Appendix C. Credits Next
Linux Install Guides
+ +Linux Install Guides
Prev Appendix C. Credits Next
Linux Install Guides
Here's a list of some helpful documentation for various OS's -
- Painless Debian +
+ Painless Debian GNU/Linux by Stephen van Egmond -
+
- Official + Official Debian Guide -
+
- RedHat + RedHat -
+
- Mandrake + Mandrake -
+
- SuSE + SuSE
Prev Home Next
Where did this document come from? Up Security Information
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/os-security.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-security.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/os-security.html 13 Sep 2009 23:54:40 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/os-security.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,26 +1,26 @@ - -Security Information
Prev Appendix C. Credits Next
Security Information
+ +Security Information
Prev Appendix C. Credits Next
Security Information
Once you get your OS installed, it's imperative that you secure your - installation. As Jon Griffin repeatedly warns us, "No distribution is - secure out of the box." The Reference Platform implements + installation. As Jon Griffin repeatedly warns us, "No distribution is + secure out of the box." The Reference Platform implements some basic precautions, but security is a process, not a condition. If you are responsible for a computer hooked to the internet, you are responsible for learning some rudiments of security, such as monitoring the state of a computer, maintaining patch levels, and keeping backups. We recommend these resources: -
- Securing and Optimizing Linux - version 2.0 -
- Jon +
+ Securing and Optimizing Linux - version 2.0 +
+ Jon Griffin's notes -
- Linux Administrators +
+ Linux Administrators Security Guide -
- Installation +
+ Installation of a Secure Webserver -
- Bruce - Schneier's Crypto-Gram, especially The - security patch treadmill and Monitoring First.
Prev Home Next
Linux Install Guides Up Resources
docs@openacs.org
View comments on this page at openacs.org +
+ Bruce + Schneier's Crypto-Gram, especially The + security patch treadmill and Monitoring First.
Prev Home Next
Linux Install Guides Up Resources
docs@openacs.org
View comments on this page at openacs.org 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.48 -r1.49 --- openacs-4/packages/acs-core-docs/www/packages.html 17 Oct 2010 21:06:08 -0000 1.48 +++ openacs-4/packages/acs-core-docs/www/packages.html 11 Dec 2010 23:36:32 -0000 1.49 @@ -1,19 +1,19 @@ - -OpenACS Packages
Prev Chapter 11. Development Reference Next
OpenACS Packages
By Pete Su and Bryan Quinn
+ +OpenACS Packages
Prev Chapter 10. Development Reference Next
OpenACS Packages
By Pete Su and Bryan Quinn
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Overview
+
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) 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
+ 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
+
Figure 10.1. Server file layout diagram
ROOT/ bin/ Various executables and scripts for server maintanence. @@ -31,7 +31,7 @@ tcl/ bootstrap code www/ - Pages not in packages (static content, customized pages)
What a Package Looks Like
+ 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 @@ -46,12 +46,12 @@ 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, this tool is called the APM. + removal. In OpenACS 5, this tool is called the APM.
To illustrate the general structure of a package, let's see what the - package for the "notes" application should look like. -
Figure 11.2. Package file layout diagram
+ package for the "notes" application should look like. +
Figure 10.2. Package file layout diagram
ROOT/ +-- packages/ APM Root | @@ -108,113 +108,129 @@ | | +-- *.adp UI Templates | | +-- *-oracle.xql Oracle-specific Queries | | +-- *-postgresql.xql PostgreSQL-specific Queries - +-- 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 + case is ROOT/packages/notes. The following table describes in detail what each of the files up in the diagram contain.
A special note on the - PACKAGE-KEY/www/resources + PACKAGE-KEY/www/resources directory. Files in this directory are available at - http://yourserver/resources/PACKAGE-KEY/... + 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 Type Its Use Naming Convention
Package Specification File The package specification file is an XML file generated and +
Table 10.1. Package files
File Type Its Use Naming Convention
Package Specification File The 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 + 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 package will not be installed correctly. Notice that the script must be under the appropriate directory for the database you are developing your package for (hopefully all OpenACS-supported databases :-)) - sql/<database>/notes-create.sql
Data Model Drop Script Contains the SQL that removes the data model and PL/SQL + + sql/<database>/notes-create.sql +
Data Model Drop Script Contains the SQL that removes the data model and PL/SQL packages generated by the creation script. The name must match the convention below or the package will not be installed correctly. - sql/<database>/notes-drop.sql
Data Model File Any .sql file that does not match the naming convention above + + sql/<database>/notes-drop.sql +
Data Model File Any .sql file that does not match the naming convention above is recognized as a data model file. It is useful to separate the SQL in the creation and drop scripts into several files and then have the scripts source the other data model files. In Oracle this can be done by including @@ filename in the creation or drop - scripts. See the + scripts. See the Oracle FAQ for examples. In PostgreSQL the same is acomplished by including \i filename. - sql/<database>/*.sql
Data Model Upgrade Scripts + + sql/<database>/*.sql +
Data Model Upgrade Scripts Contain changes to the data model between versions. The APM can automatically load the appropriate upgrade scripts when upgrading to a new version of a package. - sql/<database>/upgrade/upgrade-<old>-<new>.sql
+ + sql/<database>/upgrade/upgrade-<old>-<new>.sql +
SQL92 Query Files Files with queries that are supported by all databases. These are usually SQL92 queries. Notice that the .xql filename must match the name of the .tcl file that uses those queries. - + + *.xql -
+ +
Oracle-specific Query Files Files with queries that are Oracle-specific. Notice that the .xql filename must match the name of the .tcl file that uses those queries. - + + *-oracle.xql -
+ +
PostgreSQL-specific Query Files Files with queries that are PostgreSQL-specific. Notice that the .xql filename must match the name of the .tcl file that uses those queries. - + + *-postgresql.xql -
Tcl Library Files + +
Tcl Library Files The Tcl library files include a set of procedures that provide an application programming interface (API) for the package to utilize. - tcl/notes-procs.tcl
Tcl Initialization The initialization files are used to run Tcl procedures that + tcl/notes-procs.tcl
Tcl Initialization The initialization files are used to run Tcl procedures that should only be sourced once on startup. Examples of statements to put here are registered filters or procedures. Tcl initialization files are sourced once on server startup after all of the Tcl library files are sourced. - tcl/notes-init.tcl
Administration UI The administration UI is used to administer the instances of + + tcl/notes-init.tcl +
Administration UI The administration UI is used to administer the instances of the package. For example, the forums administration UI is used to create new forums, moderate postings, and create new - categories for forums postings. www/admin/*
Administration UI Index Page Every package administration UI must have an index page. In - most cases, this is index.tcl but it can be - any file with the name index, such as - index.html or index.adp. www/admin/index.tcl
Regression Tests Every package should have a set of regression tests that + categories for forums postings. www/admin/*
Administration UI Index Page Every package administration UI must have an index page. In + most cases, this is index.tcl but it can be + any file with the name index, such as + index.html or index.adp. www/admin/index.tcl
Regression Tests Every package should have a set of regression tests that verify that it is in working operation. These tests should be able to be run at any time after the package has been installed and report helpful error messages when there is - a fault in the system. www/admin/tests/
Regression Test Index Page The regression test directory must have an index page that + a fault in the system. www/admin/tests/
Regression Test Index Page The 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
Documentation Every package must include a full set of documentation that + as its name is index. www/admin/tests/index.html
Documentation Every 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 Page The documentation directory must include a static HTML file with the name - of index.html. www/doc/index.html
UI Logic Scripts Packages provide a UI for users to access the system. The UI + developer-level documentation where appropriate. www/doc/
Documentation Index Page The documentation directory must include a static HTML file with the name + of index.html. www/doc/index.html
UI Logic Scripts Packages 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 Templates Templates are used to control the presentation of the UI. + presentation by the associated templates. www/*.tcl
UI Templates Templates 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 Page The UI must have an index page composed of a logic script - called index.tcl and a template called - index.adp. www/index.tcl
The APM
+ and prepare them for display to the browser.
www/*.adp
UI Index Page The UI must have an index page composed of a logic script + called index.tcl and a template called + 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: -
Package registration
Automatic installation of packages: loading data models, code - libraries, and so on.
Checking what packages depend on what other packages.
Storing information on the package including ownership and a file +
Package registration
Automatic installation of packages: loading data models, code + libraries, and so on.
Checking what packages depend on what other packages.
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 @@ -237,12 +253,12 @@
We will also discuss how to organize your files and queries so they work with the OpenACS Query Dispatcher. -
Making a Package
+
Making a Package
Here is how you make a package. -
Login as a site-wide administrator on your web service. -
Go to the package manager on your server. The URL is /acs-admin/apm. -
Click on the link /acs-admin/apm/package-add. -
Fill out the form for adding a new package. The form explains what +
Login as a site-wide administrator on your web service. +
Go to the package manager on your server. The URL is /acs-admin/apm. +
Click on the link /acs-admin/apm/package-add. +
Fill out the form for adding a new package. The form explains what everything means, but we'll repeat the important bits here for easy reference: @@ -252,27 +268,27 @@ distinguish it from all the others. It is used as a database key to keep track of the package and as the name of the directory in the file system where all the files related to your package will live. Example - package keys in the current system include: forums, - acs-kernel and so on. For the example application, we - will use the package key notes. + package keys in the current system include: forums, + acs-kernel and so on. For the example application, we + will use the package key notes.
Package Name
This is a short human readable name for your package. For our example, - we will use the name "Notes". + we will use the name "Notes".
Package Plural
If your package name is a nice singular noun, this should be the plural form of it. I assume the plural form is used when multiple instances of the package are used by a single service. We'll talk more about package instances later. Our example apllication doesn't really - have a good plural name. So just make it also be "Notes". + have a good plural name. So just make it also be "Notes".
Package Type
Generally we think of packages as either being applications, meaning that the package is meant primarily for use by end-users, or services meaning that the package is meant to be a reusable - library of code, to be used by other packages. forums is - a good example of an application, while acs-templating is + library of code, to be used by other packages. forums is + a good example of an application, while acs-templating is a good example of a service. Our example is an application, so pick that.
Package URL @@ -288,52 +304,52 @@
Summary and Description
Enter a short summary and longer description of what the Notes - application will do. That is, something like "this application keeps - short textual notes in the database", and so on. + application will do. That is, something like "this application keeps + short textual notes in the database", and so on.
-
Click the button "Create Package". -
At this point, APM will create a directory called - ROOT/packages/notes. -
+
Click the button "Create Package". +
At this point, APM will create a directory called + ROOT/packages/notes. +
The directory that APM created will be empty except for the - notes.info file. Create a file + notes.info file. Create a file called - ROOT/packages/notes/sql/oracle/notes-create.sql. We'll - fill this file with our data model + ROOT/packages/notes/sql/oracle/notes-create.sql. We'll + fill this file with our data model very soon. Create a file called - ROOT/packages/notes/sql/oracle/notes-drop.sql. This + ROOT/packages/notes/sql/oracle/notes-drop.sql. This will contain the instructions to drop the data model. To be complete, you would also create the PostgreSQL versions of these files as well in - ROOT/packages/notes/sql/postgresql/notes-create.sql + ROOT/packages/notes/sql/postgresql/notes-create.sql and - ROOT/packages/notes/sql/postgresql/notes-drop.sql. + ROOT/packages/notes/sql/postgresql/notes-drop.sql.
After you do this, go back to the main APM page. From there, - click the link called "notes" to go to the management - page for the new package. Now click the link called "Manage - file information", then the "Scan the - packages/notes directory for - additional files in this package" link on that page to scan + click the link called "notes" to go to the management + page for the new package. Now click the link called "Manage + file information", then the "Scan the + packages/notes directory for + additional files in this package" link on that page to scan the file system for new files. This will bring you do a page that lists all the files you just added and lets you add them to - the notes package. + the notes package.
- Note that while the .sql files + Note that while the .sql files have been added to the packge, they have not been loaded into the database. For the purposes of development, you have to load the data model by hand, because while OpenACS has automatic mechanisms for loading and reloading - .tcl files for code, it does not + .tcl files for code, it does not do the same thing for data model files. -
Now go back to the main management page for the notes - If your package has parameters, create them using the "Manage - Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, - instantiate, mount)" link.
The new package has been created and installed in the server. At +
Now go back to the main management page for the notes + If your package has parameters, create them using the "Manage + Parameter Information" link. Define package callbacks via the "Tcl Callbacks (install, + instantiate, mount)" link.
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: + this appendix. If so, then you just do this:
% cd ROOT/packages % cvs add notes % cd notes @@ -342,18 +358,18 @@ % cd sql % cvs add *.sql % cd ROOT/packages/notes -% cvs commit -m "add new package for notes" -
+% cvs commit -m "add new package for notes" +
Now you can start developing the package. In addition to writing code, - you should also consider the tasks outlined in the package development tutorial. -
The Site Map and Package Instances
+ you should also consider the tasks outlined in the package development tutorial. +
The Site Map and Package Instances
At this point, you are probably excited to see your new package in action. But, we haven't added any user visible pages yet. By convention, user visible pages go in the - ROOT/packages/notes/www directory. So go there and add a - file called hello.html with some text in it. Now we have + ROOT/packages/notes/www directory. So go there and add a + file called hello.html with some text in it. Now we have to make the user pages visible in the site. Since we didn't put the - pages underneath ROOT/www they will not appear on their + 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. @@ -366,49 +382,49 @@ us to easily map package instances to URLs. As we said before, each instance of an application has its own set of parameters and runs from its own URL within the site. What this means is that even - though all the code for the notes application lives in - ROOT/packages/notes, the application itself can run from + though all the code for the notes application lives in + ROOT/packages/notes, the application itself can run from any number of locations in the site. This allows developers and administrators to build sites that look to the user like a collection of many indedendent applications that actually run on a single shared - code base. The request-processor document shows + code base. The request-processor document shows you how OpenACS figures out which instance of your application was - requested by the user at any given time. The page development tutorial shows you how to use this + requested by the user at any given time. The page development tutorial shows you how to use this information in your user interface.
- In order to make the new notes application visible to + In order to make the new notes application visible to users, we have to mount it in the site map. You do this by going to - the Site Map page, which is by - default available at /acs-admin/site-map. Use the - interface here to add a new sub-folder called notes to - the root of the site, then click "new application" to mount a new - instance of the notes application to the site. Name the - new instance notes-1. + the Site Map page, which is by + default available at /acs-admin/site-map. Use the + interface here to add a new sub-folder called notes to + the root of the site, then click "new application" to mount a new + instance of the notes application to the site. Name the + new instance notes-1.
- Then type this URL into your browser: http://yourserver/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 + happened is that all URLs that start with /notes have been mapped in such a way as to serve content from the directory - ROOT/packages/notes/www. At this point, you can + ROOT/packages/notes/www. At this point, you can experiment with the site map by mounting multiple instances of the not yet written Notes application at various places in the site. In a later document, we'll see how to write your application so that the code can detect from what URL it was invoked. This is the key - to supporting subsites. -
Summary
+ to supporting subsites. +
Summary
The APM performs the following tasks in an OpenACS site: -
+
Manages creation, installation, and removal of packages from the server. Also keeps track of what files belong to which packages. -
+
Manages package upgrades. -
+
Manages information on all package instances in a site. For correctly written application packages, this allows the site administrator to map multiple instances of a package to URLs within a site. -
+
Writes out package distribution files for other people to download and install. We'll cover this later. -
Additional Reading
Package Manager Design
Package Manager Requirements
package development tutorial
($Id$)
Prev Home Next
Chapter 11. Development Reference Up OpenACS Data Models and the Object System
docs@openacs.org
View comments on this page at openacs.org +
Additional Reading
Package Manager Design
Package Manager Requirements
package development tutorial
($Id$)
Prev Home Next
Chapter 10. Development Reference Up OpenACS Data Models and the Object System
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -N -r1.48 -r1.49 --- openacs-4/packages/acs-core-docs/www/parties.html 17 Oct 2010 21:06:08 -0000 1.48 +++ openacs-4/packages/acs-core-docs/www/parties.html 11 Dec 2010 23:36:32 -0000 1.49 @@ -1,8 +1,8 @@ - -Parties in OpenACS
Prev Chapter 11. Development Reference Next
Parties in OpenACS
By Rafael H. Schloming
+ +Parties in OpenACS
Prev Chapter 10. Development Reference Next
Parties in OpenACS
By Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Introduction
While many applications must deal with individuals and many applications +
Introduction
While many applications must deal with individuals and many applications must deal with groups, most applications must deal with individuals or groups. It is often the case with such applications that @@ -11,20 +11,20 @@ practical way to manage both. This concept is so mundane that there is no need to invent special terminology. This -supertype is called a "party".
A classic example of the "party" supertype is evident +supertype is called a "party".
A classic example of the "party" supertype is evident in address books. A typical address book might contain the address of a doctor, grocery store, and friend. The first field in an entry in the address book is not labeled a person or -company, but a "party". -
The Data Model
The parties developer guide begins with +company, but a "party". +
The Data Model
The parties developer guide begins with an introduction to the parties data model, since OpenACS -community applications likely require using it in some way.
Parties
The central table in the parties data model is the parties table itself. +community applications likely require using it in some way.
Parties
The central table in the parties data model is the parties table itself. Every party has exactly one row in this table. Every party has an optional unique email address and an optional url. A party is an acs object, so permissions may be granted and revoked on parties and auditing information is stored in the acs objects table.
-+ create table parties ( party_id not null constraint parties_party_id_fk references @@ -34,54 +34,54 @@ constraint parties_email_un unique, url varchar(200) ); -+ -
The persons and -groups tables extend the -parties table. A row in the persons table represents the +
The persons and +groups tables extend the +parties table. A row in the persons table represents the most generic form of individual modeled. An individual need not be known to the system as a user. A user is a further specialized form of an individual (discussed later). A row in the groups table represents the most generic form of group modeled, where a group is an aggregation of zero or more -individuals.
Persons
If a party is an individual then there will be a row in the persons table -containing first_names and -last_name +individuals.
Persons
If a party is an individual then there will be a row in the persons table +containing first_names and +last_name for that individual. The -primary key of the persons table (person_id) references the primary key of -the parties table (party_id), so that there is a corresponding row in the +primary key of the persons table (person_id) references the primary key of +the parties table (party_id), so that there is a corresponding row in the parties table when there is a row in the persons table.
-create table persons ( +create table persons ( person_id not null constraint persons_person_id_fk references parties (party_id) constraint persons_person_id_pk primary key, first_names varchar(100) not null, last_name varchar(100) not null ); -+ -
Users
The users table is a more -specialized form of persons table. A row -in users table represents an individual that has login access to the +
Users
The users table is a more +specialized form of persons table. A row +in users table represents an individual that has login access to the system. The primary key of the users table references the primary key of the persons table. This guarantees that if there is a row -in users table then there must be a -corresponding row in persons -and parties tables.
Decomposing all the information +in users table then there must be a +corresponding row in persons +and parties tables.
Decomposing all the information associated with a user into the four tables (acs_objects, parties, persons, users) has some immediate benefits. For instance, it is possible to remove access to a user from a live system by removing his entry from the users table, while leaving the rest of his information present (i.e. turning him from a user into a -person).
Wherever possible the OpenACS data model references the persons or -parties table, not the users table. +person).
Wherever possible the OpenACS data model references the persons or +parties table, not the users table. Developers should be careful to only reference the users table in situations where it is clear that the reference is to a user for all cases and not to any other individual for any case.
-create table users ( +create table users ( user_id not null constraint users_user_id_fk references persons (person_id) @@ -106,34 +106,34 @@ password_question varchar(1000), password_answer varchar(1000) ); -+ -
Groups
The final piece of the parties data model is the groups data model. A +
Groups
The final piece of the parties data model is the groups data model. A group is a specialization of a party that represents an aggregation of zero or more other parties. The only extra information directly associated with a group (beyond that in the parties table) is the name of the group:
-create table groups ( +create table groups ( group_id not null constraint groups_group_id_fk references parties (party_id) constraint groups_group_id_pk primary key, group_name varchar(100) not null ); -+
There is another piece to the groups data model that records relations between parties and groups. -
Group Relations
Two types of group relations are represented in the data model: +
Group Relations
Two types of group relations are represented in the data model: membership relations and composite relations. The full range of sophisticated group structures that exist in the real world can be modelled in OpenACS by these two relationship types.
Membership relations represent direct membership relation between parties and groups. A party may be -a "member" of a group. Direct membership relations are +a "member" of a group. Direct membership relations are common in administrative practices, and do not follow basic set theory rules. If A is a member of B, and B is a member of C, A is -not a member of C. Membership relations are not transitive. +not a member of C. Membership relations are not transitive.
Composition relation represents composite relation between two groups. Composite relation is transitive. That is, it works like @@ -149,11 +149,11 @@ group that is a member of Greenpeace. Now, consider a multinational corporation (MC) that has a U.S. division and a Eurasian division. A member of either the U.S. or Eurasian division is automatically a member of the MC. In this -situation the U.S. and Eurasian divisions are "components" of +situation the U.S. and Eurasian divisions are "components" of the MC, i.e., membership is transitive with respect to composition. Furthermore, a member of a European (or other) office of the MC is automatically a member of the MC. -
Group Membership
Group memberships can be created and manipulated using the membership_rel +
Group Membership
Group memberships can be created and manipulated using the membership_rel package. Only one membership object can be created for a given group, party pair.
@@ -166,7 +166,7 @@ member of a household (indirect membership) at a video rental store.
-+ # sql code create or replace package membership_rel as @@ -208,17 +208,17 @@ end membership_rel; / show errors -+ -
Group Composition
Composition relations can be created or destroyed using the +
Group Composition
Composition relations can be created or destroyed using the composition_rel package. The only restriction on compositions is that there cannot be a reference loop, i.e., a group cannot be a component of itself either directly or indirectly. This constraint is maintained for you by the API. So users do not see some random PL/SQL error message, do not give them the option to create a composition relation that would result in a circular reference.
-+ # sql code create or replace package composition_rel as @@ -239,88 +239,88 @@ end composition_rel; / show errors -+ -
Views
The parties data model does a reasonable job of representing many +
Views
The parties data model does a reasonable job of representing many of the situations one is likely to encounter when modeling organizational structures. We still need to be able to efficiently answer questions like -"what members are in this group and all of its components?", and -"of what groups is this party a member either directly or -indirectly?". Composition relations allow you to describe an arbitrary +"what members are in this group and all of its components?", and +"of what groups is this party a member either directly or +indirectly?". Composition relations allow you to describe an arbitrary Directed Acyclic Graph (DAG) between a group and its components. For these reasons the party system provides a bunch of views that take advantage of the internal representation of group relations to answer questions like these -very quickly.
The group_component_map +very quickly.
The group_component_map view returns all the subcomponents of a group including components of -sub components and so forth. The container_id column is the group_id of the -group in which component_id is directly contained. This allows you to easily +sub components and so forth. The container_id column is the group_id of the +group in which component_id is directly contained. This allows you to easily distinguish whether a component is a direct component or an indirect -component. If a component is a direct component then group_id will be equal -to container_id. You can think of this view as having a primary key of -group_id, component_id, and container_id. The rel_id column points to the row -in acs_rels table that contains the relation object that relates component_id to -container_id. The rel_id might be useful for retrieving or updating standard +component. If a component is a direct component then group_id will be equal +to container_id. You can think of this view as having a primary key of +group_id, component_id, and container_id. The rel_id column points to the row +in acs_rels table that contains the relation object that relates component_id to +container_id. The rel_id might be useful for retrieving or updating standard auditing info for the relation.
-create or replace view group_component_map +create or replace view group_component_map as select group_id, component_id, container_id, rel_id ... -+ -
The group_member_map view is similar to group_component_map except for membership relations. +
The group_member_map view is similar to group_component_map except for membership relations. This view returns all membership relations regardless of membership state.
-create or replace view group_member_map +create or replace view group_member_map as select group_id, member_id, container_id, rel_id ... -+ -
The group_approved_member_map -view is the same as group_member_map except +
The group_approved_member_map +view is the same as group_member_map except it only returns entries that relate to approved members.
-create or replace view group_approved_member_map +create or replace view group_approved_member_map as select group_id, member_id, container_id, rel_id ... -+ -
The group_distinct_member_map +
The group_distinct_member_map view is a useful view if you do not care about the distinction between direct membership and indirect membership. It returns all members of a group including members of components --the transitive closure.
-create or replace view group_distinct_member_map +create or replace view group_distinct_member_map as select group_id, member_id ... -+ -
The party_member_map view is the same as group_distinct_member_map, except it includes the +
The party_member_map view is the same as group_distinct_member_map, except it includes the identity mapping. It maps from a party to the fully expanded list of parties represented by that party including the party itself. So if a party is an individual, this view will have exactly one mapping that is from that party to itself. If a view is a group containing three individuals, this view will have four rows for that party, one for each member, and one from the party to itself.
-create or replace view party_member_map +create or replace view party_member_map as select party_id, member_id ... -+ -
The party_approved_member_map view is the same as party_member_map except that when it expands groups, it only +
The party_approved_member_map view is the same as party_member_map except that when it expands groups, it only pays attention to approved members.
-create or replace view party_approved_member_map +create or replace view party_approved_member_map as select party_id, member_id ... -+ -
Extending The Parties Data Model
The parties data model can represent some fairly sophisticated real +
Extending The Parties Data Model
The parties data model can represent some fairly sophisticated real world situations. Still, it would be foolish to assume that this data model is sufficiently efficient for every application. This section describes some -of the more common ways to extend the parties data model.
Specializing Users
Some applications will want to collect more +of the more common ways to extend the parties data model.
Specializing Users
Some applications will want to collect more detailed information for people using the system. If there can be only one such piece of information per user, then it might make sense to create another type of individual that is a further specialization @@ -331,18 +331,18 @@ have a primary key that references the users table, thereby guaranteeing that each row in the chess_club_users table has a corresponding row in each of the users, persons, parties, and acs_objects tables. This child table could then -store any extra information relevant to the Chess Club community.
Specializing Groups
If one were to build an intranet application on top of the party +store any extra information relevant to the Chess Club community.
Specializing Groups
If one were to build an intranet application on top of the party system, it is likely that one would want to take advantage of the systems efficient representation of sophisticated organizational structures, but there would be much more specialized information associated with each group. In this case it would make sense to specialize the group party type into a -company party type in the same manner as Specializing Users.
Specializing Membership Relations
The final portion of the parties data model that is designed to be +company party type in the same manner as Specializing Users.
Specializing Membership Relations
The final portion of the parties data model that is designed to be extended is the membership relationship. Consider the intranet example again. It is likely that a membership in a company would have more information associated with it than a membership in an ordinary group. An obvious example of this would be a salary. It is exactly this need to be able to extend membership relations with mutable pieces of state that drove us to include a single integer primary key in what could be thought of as a pure relation. -Because a membership relation is an ordinary acs object with object identity, it is as easy to extend the +Because a membership relation is an ordinary acs object with object identity, it is as easy to extend the membership relation to store extra information as it is to extend the users -table or the groups table.
($Id$)
Prev Home Next
Writing OpenACS Application Pages Up OpenACS Permissions Tediously Explained
docs@openacs.org
View comments on this page at openacs.org +table or the groups table.
($Id$)
Prev Home Next
Writing OpenACS Application Pages Up Object Identity
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 17 Oct 2010 21:06:08 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,11 +1,11 @@ - -Permissions Design
Prev Chapter 15. Kernel Documentation Next
Permissions Design
By John Prevost and Rafael H. Schloming
+ +Permissions Design
Prev Chapter 14. Kernel Documentation Next
Permissions Design
By John Prevost and Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Essentials
Tcl in packages/acs-kernel
OpenACS 4 Permissions Requirements
-SQL file
ER diagram +
Essentials
Tcl in packages/acs-kernel
OpenACS 4 Permissions Requirements
+SQL file
ER diagram -
Introduction
The goal of the Permissions system is to provide generic means to both +
Introduction
The goal of the Permissions system is to provide generic means to both programmers and site administrators to designate operations (methods) as requiring permissions, and then to check, grant, or revoke permissions via a consistent interface. For example, we might decide that the transaction that @@ -22,119 +22,119 @@ those package objects on which a user has certain permissions.
For site administrators and other authorized users, the Permissions UI provides a means to aggregate the primitive operations (methods) made available by the programmer into logical privileges (like read, write, and -admin) that can be granted and revoked.
Historical Considerations
In earlier versions of the OpenACS, permissions and access control was handled +admin) that can be granted and revoked.
Historical Considerations
In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules -used "roles", while others did not. Other modules did all access +used "roles", while others did not. Other modules did all access control based simply on coded rules regarding who can act on a given database row based on the information in that row.
Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that both programmers and administrators can -readily use.
Competitive Analysis
None available as of 10/2000.
Design Tradeoffs
The core of the permissions data model is quite simple. Unfortunately, the +readily use.
Competitive Analysis
None available as of 10/2000.
Design Tradeoffs
The core of the permissions data model is quite simple. Unfortunately, the hierarchical nature of default permissions entails quite a number of tree queries which could slow the system down. Since every page will have at least one permissions check, a number of views and auxiliary tables (de-normalizations of the data model) have been created to speed up access queries. As a consequence, speed of updates are decreased and requirements -for additional storage space increase.
Data Model Discussion
As described in section V., the core of the permissions data model is +for additional storage space increase.
Data Model Discussion
As described in section V., the core of the permissions data model is simple, though a number of views and auxiliary tables exist to ensure -adequate performance. The core model consists of five tables:
acs_methods +adequate performance. The core model consists of five tables:
acs_methods -
The set of all defined methods.
acs_privileges +
The set of all defined methods.
acs_privileges -
The set of all defined privileges.
acs_privilege_method_rules +
The set of all defined privileges.
acs_privilege_method_rules -
A relation describing the set of methods directly -associated with each privilege.
acs_privilege_hierarchy +
A relation describing the set of methods directly +associated with each privilege.
acs_privilege_hierarchy -
A relation describing which privileges directly -"contain" other privileges.
acs_permissions +
A relation describing which privileges directly +"contain" other privileges.
acs_permissions
A table with one (party, object, privilege) -row for every privilege directly granted on any object in +row for every privilege directly granted on any object in the system - this is a denormalization of -acs_privilege_method_rules and -acs_privilege_hierarchy
There are also a number of views to make it easier to ask specific +acs_privilege_method_rules and +acs_privilege_hierarchy
There are also a number of views to make it easier to ask specific questions about permissions. For example, a number of the above tables -describe "direct" or explicit permissions. Inheritance and default +describe "direct" or explicit permissions. Inheritance and default values can, however, introduce permissions which are not directly specified. (For example, read access on a forum allows read access on all the messages in the forum.)
The following views provide flattened versions of inherited -information:
acs_privilege_method_map +information:
acs_privilege_method_map
Map of privileges to the methods they contain either directly or because -of another privilege which is included (at any depth).
acs_object_grantee_priv_map +of another privilege which is included (at any depth).
acs_object_grantee_priv_map
Relation on (object, party, privilege) for -privileges from acs_privileges) granted directly on the object, or -on the context of the object (at any depth).
acs_object_party_privilege_map +privileges from acs_privileges) granted directly on the object, or +on the context of the object (at any depth).
acs_object_party_privilege_map
Relation on (object, party, privilege) for -privileges directly from acs_object_grantee_priv_map or also because -a party is a member of a group (at any depth).
acs_object_party_method_map +privileges directly from acs_object_grantee_priv_map or also because +a party is a member of a group (at any depth).
acs_object_party_method_map
Relation with every (object, party, method) -tuple implied by the above trees.
In general, only acs_object_party_method_map +tuple implied by the above trees.
In general, only acs_object_party_method_map should be used for queries from other modules. The other views are intermediate steps in building that query.
The data model also includes two simple PL/SQL procedures -(acs_permission.grant_permission and -acs_permission.revoke_permission) for granting and revoking a +(acs_permission.grant_permission and +acs_permission.revoke_permission) for granting and revoking a specific privilege for a specific user on a specific object.
To sum up, the PL/SQL procedures are meant to be used to grant or revoke permissions. The five base tables represent the basic data model of the system, with a set of views provided to convert them into a format suitable for joining to answer specific questions. The exact means by which this transformation takes place should not be depended on, since they may change for efficiency reasons.
The transformations done create a set of default permissions, in -which:
parties get the privileges of any groups they are directly or indirectly -a member of
privileges get associated with the methods of any other privileges they +which:
parties get the privileges of any groups they are directly or indirectly +a member of
privileges get associated with the methods of any other privileges they have taken methods from (at any level) (see -acs_privilege_hierarchy)
objects get access control from direct grants, or inherit permissions -from their context (unless the "don't inherit" flag is -set)
Legal Transactions
There are three essential areas in which all transactions in the -permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and privileges." This +acs_privilege_hierarchy)
objects get access control from direct grants, or inherit permissions +from their context (unless the "don't inherit" flag is +set)
Legal Transactions
There are three essential areas in which all transactions in the +permissions system fall:
Modification of methods and privileges
Modification of permissions
Queries on permissions
"Modification of methods and privileges." This refers to actions that happen mainly at package installation time - a package will create a number of methods for its own use, then associate them with the system's standard privileges, or new privileges which the package has created. The association step might also happen later, if the site-wide -administrator chooses to change permissions policy.
These steps involve directly manipulating the acs_methods, -acs_privileges, and acs_privilege_method_rules tables. A +administrator chooses to change permissions policy.
These steps involve directly manipulating the acs_methods, +acs_privileges, and acs_privilege_method_rules tables. A web page for manipulating these features should be limited to site-wide -administrators.
"Modification of permissions" - involves fairly +administrators.
"Modification of permissions" - involves fairly common operations. Users are typically able to administer permissions for objects they themselves create. The two basic operations here are -"grant" and "revoke". Granting permissions is done via -acs_permissions.grant_permission, and revocation via -acs_permissions.revoke_permission. These directly manipulate the -acs_permissions table.
Web pages for making these changes are available to all users, so they +"grant" and "revoke". Granting permissions is done via +acs_permissions.grant_permission, and revocation via +acs_permissions.revoke_permission. These directly manipulate the +acs_permissions table.
Web pages for making these changes are available to all users, so they should not be in an admin area. In order to grant and revoke permissions on -an object, the user must have the administer_privileges method -permission on that object.
"Queries on permissions" - by far the most +an object, the user must have the administer_privileges method +permission on that object.
"Queries on permissions" - by far the most common operation is querying the permissions database. Several kinds of -questions are commonly asked: First, and most commonly, "Can this party -perform this method on this object?" Two Tcl functions are provided to +questions are commonly asked: First, and most commonly, "Can this party +perform this method on this object?" Two Tcl functions are provided to answer this - one which returns a boolean, the other of which results in an error page. These tcl functions directly access the -acs_object_party_method_map.
The second most commonly asked question occurs when a list of objects is +acs_object_party_method_map.
The second most commonly asked question occurs when a list of objects is being displayed, often in order to provide appropriate UI functionality: -"For this party, what methods are available on these objects?" +"For this party, what methods are available on these objects?" Here, the SQL query needs to filter based on whether the party/user can perform some operation on the object. This is done via a join or sub-select -against acs_object_party_method_map, or by calling the Tcl functions +against acs_object_party_method_map, or by calling the Tcl functions for appropriate methods.
Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. This is done -by querying against acs_permissions.
API
The API to the permissions system consists of a few well-known tables, -plus a pair of PL/SQL procedures and a pair of Tcl functions.
Tables
acs_methods, acs_privileges, and -acs_privilege_method_rules manage the set of permissions in the +by querying against acs_permissions.
API
The API to the permissions system consists of a few well-known tables, +plus a pair of PL/SQL procedures and a pair of Tcl functions.
Tables
acs_methods, acs_privileges, and +acs_privilege_method_rules manage the set of permissions in the system. At installation time, a package will add to these three tables to -introduce new permissions into the system.
The main table for queries is acs_object_party_method_map, which +introduce new permissions into the system.
The main table for queries is acs_object_party_method_map, which contains (object, party, method) triples for all -allowed operations in the system.
Also of interest for queries is acs_permissions, which lists -directly granted privileges. Neither acs_object_party_method_map -(which is a view) nor acs_permissions should be updated -directly.
PL/SQL Procedures
acs_permissions.grant_permission introduces new permissions for +allowed operations in the system.
Also of interest for queries is acs_permissions, which lists +directly granted privileges. Neither acs_object_party_method_map +(which is a view) nor acs_permissions should be updated +directly.
PL/SQL Procedures
acs_permissions.grant_permission introduces new permissions for an object. It should be given an (object, party, privilege) triple, and will always succeed. If the permission is already in the system, no change occurs. The interface for this procedure @@ -144,43 +144,43 @@ grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE ); -
acs_permissions.revoke_permission removes a permission entry +
acs_permissions.revoke_permission removes a permission entry given a triple. It always succeeds--if a permission does not exist, nothing changes. The interface for this procedure is:
procedure revoke_permission ( object_id acs_permissions.object_id%TYPE, grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE ); -
These procedures are defined in -permissions-create.sql
Tcl Procedures
Two tcl procedures provide a simple call for the query, "Can this -user perform this method on this object?" One returns true or false, the +
These procedures are defined in +permissions-create.sql
Tcl Procedures
Two tcl procedures provide a simple call for the query, "Can this +user perform this method on this object?" One returns true or false, the other presents an error page.
To receive a true or false value, Tcl code should call:
ad_permission_p $object_id $object_type $method -user_id $user_id -
If the user_id argument is left out, then the currently logged in +
If the user_id argument is left out, then the currently logged in user is checked. To create an error page, Tcl code should call:
ad_require_permission $object_id $object_type $method -
These procedures are defined in acs-permissions-procs.tcl.
User Interface
All users of the permissions system are the same at the user-interface -level. If you have the administer_privileges method permission on an +
These procedures are defined in acs-permissions-procs.tcl.
User Interface
All users of the permissions system are the same at the user-interface +level. If you have the administer_privileges method permission on an object, then you may edit privileges for that object with the UI.
The UI currently provides a list of all granted permissions on the object. If the user wishes to revoke privileges, she may select a set of grants, choose revoke, confirm their deletion, and be returned to the same page after those privileges have been revoked.
Granting permissions currently (as of 10/2000) works by providing a list of all possible permissions and a list of all parties in the system. (For large sites, some future search mechanism will be necessary.) After choosing -privileges to grant, the user is returned to the "edit privileges for -one object" screen.
If it makes sense, the system will also display a checkbox which the user +privileges to grant, the user is returned to the "edit privileges for +one object" screen.
If it makes sense, the system will also display a checkbox which the user may select to toggle whether permissions are inherited from the object's context.
There are a number of potential future enhancements for the permissions -UI, outlined below.
Configuration/Parameters
There are no configuration options for the permissions system.
Future Improvements/Areas of Likely Change
The most important future changes to the Permissions system are likely to -be in the UI:
There should be a page displaying a list of all objects for which the -current user is allowed to administer privileges.
Users should be able to view the permissions on any object, or perhaps on -objects which they have the "read_permissions" method. This would +UI, outlined below.
Configuration/Parameters
There are no configuration options for the permissions system.
Future Improvements/Areas of Likely Change
The most important future changes to the Permissions system are likely to +be in the UI:
There should be a page displaying a list of all objects for which the +current user is allowed to administer privileges.
Users should be able to view the permissions on any object, or perhaps on +objects which they have the "read_permissions" method. This would allow them to see what grants are affecting their objects through -inheritance.
Authors
System creator +inheritance.
Authors
System creator -
Rafael H. Schloming
System owner +
Rafael H. Schloming
System owner -
Rafael H. Schloming
Documentation author +
Rafael H. Schloming
Documentation author -
John Prevost
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 9/11/2000 John Prevost
0.2 Edited for ACS 4 Beta release 10/04/2000 Kai Wu
Prev Home Next
Permissions Requirements Up Groups Requirements
docs@openacs.org
View comments on this page at openacs.org +
John Prevost
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 9/11/2000 John Prevost
0.2 Edited for ACS 4 Beta release 10/04/2000 Kai Wu
Prev Home Next
Permissions Requirements Up Groups Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 17 Oct 2010 21:06:08 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,11 +1,11 @@ - -Permissions Requirements
Prev Chapter 15. Kernel Documentation Next
Permissions Requirements
By John McClary Prevost
+ +Permissions Requirements
Prev Chapter 14. Kernel Documentation Next
Permissions Requirements
By John McClary Prevost
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Introduction
This document records requirements for the OpenACS 4 Permissions system, a +
Introduction
This document records requirements for the OpenACS 4 Permissions system, a component of the OpenACS 4 Kernel. The Permissions system is meant to unify and -centralize the handling of access and control on a given OpenACS 4 system.
Vision Statement
Any multi-user software system must address the general problem of -permissions, or "who can do what, on what." On web services, which +centralize the handling of access and control on a given OpenACS 4 system.
Vision Statement
Any multi-user software system must address the general problem of +permissions, or "who can do what, on what." On web services, which typically involve large numbers of users belonging to different groups, permissions handling is a critical need: access to content, services, and information generally must be controlled. The OpenACS 4 Permissions system is @@ -14,78 +14,78 @@ manner reduces both cost and risk: cost, in that less code has to be written and maintained for dealing with recurring permissions situations; risk, in that we need not rely on any single programmer's diligence to ensure -access control is implemented and enforced correctly.
Historical Motivations
In earlier versions of the OpenACS, permissions and access control was handled +access control is implemented and enforced correctly.
Historical Motivations
In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules -used "roles", while others did not. Other modules did all access +used "roles", while others did not. Other modules did all access control based simply on coded rules regarding who can act on a given database row based on the information in that row.
Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that both programmers and administrators can -readily use.
System Overview
The OpenACS 4 Permissions system has two main pieces: first, an API for +readily use.
System Overview
The OpenACS 4 Permissions system has two main pieces: first, an API for developers to readily handle access control in their applications. The second piece of the system is a UI meant primarily for (subsite) administrators to grant and revoke permissions to system entities under their control.
Consistency is a key characteristic of the Permissions system - both for a common administrative interface, and easily deployed and maintained access control. The system must be flexible enough to support every access model required in OpenACS applications, but not so flexible that pieces will go unused -or fall outside the common administrative interfaces.
Use Cases and User Scenarios
Terminology
The primary question an access control system must answer is a three-way +or fall outside the common administrative interfaces.
Use Cases and User Scenarios
Terminology
The primary question an access control system must answer is a three-way relation, like that between the parts of most simple sentences. A simple sentence generally has three parts, a subject, an object, and a verb - in the -context of OpenACS Permissions, our simple sentence is, "Can this party -perform this operation on this target?" Definitions:
The subject of the sentence is "party" - a +context of OpenACS Permissions, our simple sentence is, "Can this party +perform this operation on this target?" Definitions:
The subject of the sentence is "party" - a distinguishable actor whose access may be controlled, this special word is used because one person may be represented by several parties, and one party -may represent many users (or no users at all).
The object of the sentence is "target" - this +may represent many users (or no users at all).
The object of the sentence is "target" - this is an entity, or object, that the party wishes to perform some action on. An -entity/object here is anything that can be put under access control.
The verb of the sentence is "operation" - a behavior on the OpenACS +entity/object here is anything that can be put under access control.
The verb of the sentence is "operation" - a behavior on the OpenACS system subject to control, this word is used to represent the fact that a single operation may be part of many larger actions the system wants to -perform. If "foo" is an operation, than we sometimes refer to the -foo "privilege" to mean that a user has the privilege to perform +perform. If "foo" is an operation, than we sometimes refer to the +foo "privilege" to mean that a user has the privilege to perform that operation.
Examples of the essential question addressed by the Permissions system: Can jane@attacker.com delete the web security forum? Can the Boston office (a party) within the VirtuaCorp intranet/website create its own news -instance?
Related Links
OpenACS 4 Permissions Design
Functional Requirements
10.0 Granularity
The system must support access control down to the level of a single +instance?
Related Links
OpenACS 4 Permissions Design
Functional Requirements
10.0 Granularity
The system must support access control down to the level of a single entity (this would imply down to the level of a row in the OpenACS Objects data -model).
20.0 Operations
The system itself must be able to answer the essential permissions -question as well as several derived questions.
20.10 Basic Access Check
The system must be able to answer the question, "May party P perform -operation O on target T?"
20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may -perform operation O on target T?"
20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may -party P perform on target T?"
20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets -may party P perform operation O?"
Behavioral Requirements
40.0 Scale of Privileges
Privileges must be designed with appropriate scope for a given OpenACS -package. Some privileges are of general utility (e.g. "read" and -"write"). Others are of more limited use (e.g. "moderate" +model).
20.0 Operations
The system itself must be able to answer the essential permissions +question as well as several derived questions.
20.10 Basic Access Check
The system must be able to answer the question, "May party P perform +operation O on target T?"
20.20 Allowed Parties Check
The system must be able to answer the question, "Which parties may +perform operation O on target T?"
20.30 Allowed Operations Check
The system must be able to answer the question, "Which operations may +party P perform on target T?"
20.40 Allowed Targets Check
The system must be able to answer the question, "Upon which targets +may party P perform operation O?"
Behavioral Requirements
40.0 Scale of Privileges
Privileges must be designed with appropriate scope for a given OpenACS +package. Some privileges are of general utility (e.g. "read" and +"write"). Others are of more limited use (e.g. "moderate" - applies mainly to a package like forum, where many users are contributing content simultaneously). A package defining its own privileges should do so with moderation, being careful not to overload a privilege like -"read" to mean too many things.
50.0 Aggregation of Operations (Privileges)
For user interface purposes, it can be appropriate to group certain -privileges under others. For example, anyone with the "admin" -privilege may also automatically receive "read", "write", -"delete", etc. privileges.
60.0 Aggregation of Parties (Groups)
The system must allow aggregation of parties. The exact method used for -aggregation will probably be addressed by the OpenACS 4 "Groups" +"read" to mean too many things.
50.0 Aggregation of Operations (Privileges)
For user interface purposes, it can be appropriate to group certain +privileges under others. For example, anyone with the "admin" +privilege may also automatically receive "read", "write", +"delete", etc. privileges.
60.0 Aggregation of Parties (Groups)
The system must allow aggregation of parties. The exact method used for +aggregation will probably be addressed by the OpenACS 4 "Groups" system. Regardless of the exact behavior of aggregate parties, if an aggregate party exists, then access which is granted to the aggregate party -should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from +should be available to all members of that aggregate.
70.0 Scope of Access Control
70.10 Context
There must be a method for objects to receive default access control from some context. For example, if you do not have read access to a forum, you -should not have read access to a message in that forum.
70.20 Overriding
It must be possible to override defaults provided by the context of an -object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they +should not have read access to a message in that forum.
70.20 Overriding
It must be possible to override defaults provided by the context of an +object (as in 70.10), in both a positive and negative manner.
70.20.10 Positive Overriding
It must be possible to allow a party more access to some target than they would get by default. (For example, a user does not have the right to edit any message on a forum. But a user does possibly have the right to edit -their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their +their own messages.)
70.20.20 Negative Overriding
It must be possible to deny a party access to some target that their inherited privileges would have allowed. (For example, a subdirectory in the file-storage might normally have its parent directory as context. It should -be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check +be possible, however, to make a subdirectory private to some group.)
100.0 Efficiency
At least the basic access check (20.10) and the allowed targets check (20.40) must be efficient enough for general use, i.e. scalable under fairly heavy website traffic. It can be expected that almost every page will contain at least one basic access check, and most pages will contain an allowed -targets check (20.40).
In particular, constraining a SELECT to return only rows the -current user has access to should not be much slower than the SELECT -on its own.
120.0 Ease of Use
Since most SQL queries will contain an allowed target check in the where +targets check (20.40).
In particular, constraining a SELECT to return only rows the +current user has access to should not be much slower than the SELECT +on its own.
120.0 Ease of Use
Since most SQL queries will contain an allowed target check in the where clause, whatever mechanism is used to make checks in SQL should be fairly -small and simple.
In particular, constraining a SELECT to return only rows the -current user has access to should not add more than one line to a query.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 8/17/2000 John Prevost
0.2 Revised, updated with new terminology 8/25/2000 John Prevost
0.3 Edited, reformatted to conform to requirements template, pending -freeze. 8/26/2000 Kai Wu
0.4 Edited for ACS 4 Beta release. 10/03/2000 Kai Wu
Prev Home Next
Object Model Requirements Up Permissions Design
docs@openacs.org
View comments on this page at openacs.org +small and simple.
In particular, constraining a SELECT to return only rows the +current user has access to should not add more than one line to a query.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 8/17/2000 John Prevost
0.2 Revised, updated with new terminology 8/25/2000 John Prevost
0.3 Edited, reformatted to conform to requirements template, pending +freeze. 8/26/2000 Kai Wu
0.4 Edited for ACS 4 Beta release. 10/03/2000 Kai Wu
Prev Home Next
Object Model Design Up Permissions Design
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v diff -u -N -r1.47 -r1.48 --- openacs-4/packages/acs-core-docs/www/permissions.html 17 Oct 2010 21:06:08 -0000 1.47 +++ openacs-4/packages/acs-core-docs/www/permissions.html 11 Dec 2010 23:36:32 -0000 1.48 @@ -1,29 +1,29 @@ - -Groups, Context, Permissions
Prev Chapter 11. Development Reference Next
Groups, Context, Permissions
By Pete Su
+ +Groups, Context, Permissions
Prev Chapter 10. Development Reference Next
Groups, Context, Permissions
By Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Overview
+
Overview
The OpenACS 5.6.0 Permissions system allows developers and administrators to set access control policies at the object level, that is, any application or system object represented by a row in the -acs_objects table can be access-controlled via a +acs_objects table can be access-controlled via a PL/SQL or Tcl interface. The permissions system manages a data model that then allows scripts to check permissions using another API call.
Although object level permissions seems appropriate, no developer or administrator wants to explicitly set access control rights for every user and every object on a site. Therefore, OpenACS has two auxiliary mechanisms for making this -easier:
the Groups system allows users to be grouped together -in flexible ways.
the object model defines a notion of +easier:
the Groups system allows users to be grouped together +in flexible ways.
the object model defines a notion of object context, which allows applications to group objects together into larger security domains.
The rest of this document discusses each of these parts, and how they fit together with the permissions system. -
Groups
+
Groups
OpenACS 5.6.0 has an abstraction called a party. Parties have a recursive definition. We can illustrate how it works with the following -simplified data model. First, we define the parties +simplified data model. First, we define the parties table, where each party has an email address and a URL for contact information.
@@ -51,8 +51,8 @@ )
-The users table is also defined in this data model as a -subtype of person. +The users table is also defined in this data model as a +subtype of person.
Finally, we define two relations, one for group membership and one for group composition. @@ -70,11 +70,11 @@ groups.
The full details of the groups data model is beyond the scope of this -tutorial. See Parties in OpenACS or OpenACS 4 Groups Design for more details. -
Permissions
+tutorial. See Parties in OpenACS or OpenACS 4 Groups Design for more details. +
Permissions
NOTE: Much more detailed information about the permissions system and how to use it is available in the - OpenACS Permissions Tediously Explained document. + ??? document.
The permissions data model is a mapping between privileges, parties and objects. Parties and @@ -89,7 +89,7 @@ can define privileges that aggregate some set of privileges together. For example, if we have read, write, create and delete privileges, it might be convenient to combine them into a new privilege -called "admin". Then, when a user is granted "admin" privilege, she is +called "admin". Then, when a user is granted "admin" privilege, she is automatically granted all the child privileges that the privilege contains. The OpenACS 5.6.0 kernel data model defines these privileges: @@ -117,7 +117,7 @@
To give a user permission to perform a particular operation on a particular object you call -acs_permission.grant_permission like this: +acs_permission.grant_permission like this:
# sql code @@ -135,12 +135,12 @@ would become very tedious. OpenACS provides a object contexts as a means for controlling permissions of a large group of objects at the same time. -
Object Context
+
Object Context
In OpenACS 5.6.0, object context is a scoping -mechanism. "Scoping" and "scope" are terms best +mechanism. "Scoping" and "scope" are terms best explained by example: consider some hypothetical rows in the -address_book table: -
... scope user_id group_id ...
... user 123 ...
... group 456 ...
... public ...
+address_book table: +
... scope user_id group_id ...
... user 123 ...
... group 456 ...
... public ...
The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public @@ -153,25 +153,25 @@ another object that represents the security domain to which the object belongs. By convention, if an object A does not have any permissions explicitly attached to it, then the system will look at the -context_id column in acs_objects and check +context_id column in acs_objects and check the context object there for permissions. Two things control the scope -of this search:
the structure of the context hierarchy +of this search:
the structure of the context hierarchy itself, and -
-the value of the security_inherit_p +
+the value of the security_inherit_p flag in each object.
If -security_inherit_p flag is set to 't', then the automatic search +security_inherit_p flag is set to 't', then the automatic search through the context happens, otherwise it does not. You might set this -field to 'f' if you want to override the default +field to 'f' if you want to override the default permissions in a subtree of some context.
For an example of how to use context hierarchy, consider the forums application. With only row-level permissions it is not obvious how to reasonably initialize the access control list when creating a message. At best, we have to explicitly grant various read and write privileges whenever we create a message, which is tedious. A reasonable thing to do is to create an object representing a forum, -and point the context_id field of a new message at the +and point the context_id field of a new message at the forum. Then, suppose we grant every user in the system read-access to this forum. By default, they will automatically have read-access to the new message we just inserted, since the system automatically @@ -183,30 +183,30 @@ hierarchy that matches the structure they need for access control in their application. The following picture shows a typical context hierarchy for a hypothetical site: -
+
The top two contexts in the diagram -are called "magic" numbers, because in some sense, they are created by default by OpenACS -for a specific purpose. The object default_context +are called "magic" numbers, because in some sense, they are created by default by OpenACS +for a specific purpose. The object default_context represents the root of the context hierarchy for the entire site. All permission searches walk up the tree to this point and then stop. If you grant permissions on this object, then by default those permissions will hold for every object in the system, regardless of which subsite they happen to live in. The object -security_context_root has a slightly different role. If +security_context_root has a slightly different role. If some object has no permissions attached to it, and its value for -security_inherit_p is 'f', or -context_id is null, this context is used by default. +security_inherit_p is 'f', or +context_id is null, this context is used by default.
See the package developer tutorials for examples on how to use permissions code. -
Summary
+
Summary
OpenACS 5.6.0 defines three separate mechanisms for specifying access control -in applications.
+in applications.
The Groups data model allows you to define hierarchical organizations of users and groups of users. -
+
The Permissions data model allows you to define a hierarchy of user rights. -
+
The Context hierarchy allows you to define organize default permissions in a hierarchical fashion.
A PL/SQL or Tcl API is 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.48 -r1.49 --- openacs-4/packages/acs-core-docs/www/postgres.html 17 Oct 2010 21:06:08 -0000 1.48 +++ openacs-4/packages/acs-core-docs/www/postgres.html 11 Dec 2010 23:36:32 -0000 1.49 @@ -1,88 +1,88 @@ - -Install PostgreSQL
Prev Chapter 3. Complete Installation Next
Install PostgreSQL
by Vinod Kurup
+ +Install PostgreSQL
Prev Chapter 3. Complete Installation Next
Install PostgreSQL
by Vinod Kurup
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Skip this section if you will run only Oracle.
OpenACS 5.6.0 will run with PostgreSQL 7.3.2, 7.3.3, and 7.3.4 and 7.4.x. 7.4.7 is the recommended version of PostgreSQL.
Special notes for Mac OS X. If you are running Mac OS X prior to 10.3, you should be +
Skip this section if you will run only Oracle.
OpenACS 5.6.0 will run with PostgreSQL 7.3.2, 7.3.3, and 7.3.4 and 7.4.x. 7.4.7 is the recommended version of PostgreSQL.
Special notes for Mac OS X. If you are running Mac OS X prior to 10.3, you should be able to install and use PostGreSQL 7.3.x. Mac OS X 10.3 - requires PostGreSQL 7.4.
Special Notes for Debian.
Debian stable user should install PostGreSQL from source + requires PostGreSQL 7.4.
Special Notes for Debian.
Debian stable user should install PostGreSQL from source as detailed below, or they should use the www.backports.org backport for Postgres to get a more current version. Debian unstable users: the following process has been known to work (but you should double-check that the version of PostGreSQL is 7.3 or above):
For Debian stable users, you can use backports, by adding this line to the /etc/apt/sources.list
- deb http://www.backports.org/debian stable bison postgresql openssl openssh tcl8.4 courier debconf spamassassin tla diff patch neon chkrootkit - -
apt-get install postgresql postgresql-dev postgresql-doc + deb http://www.backports.org/debian stable bison postgresql openssl openssh tcl8.4 courier debconf spamassassin tla diff patch neon chkrootkit + +
apt-get install postgresql postgresql-dev postgresql-doc ln -s /usr/include/postgresql/ /usr/include/pgsql ln -s /var/lib/postgres /usr/local/pgsql ln -s /usr/include/pgsql /usr/local/pgsql/include -su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1"
and proceed to Tune postgres. (OPTIONAL) or to the - next section.
Special Notes for Red Hat. Red Hat users: If you install PostgreSQL 7.3.2 from the Red Hat 9 RPM, you +su postgres -c "/usr/lib/postgresql/bin/createlang plpgsql template1"
and proceed to Tune postgres. (OPTIONAL) or to the + next section.
Special Notes for Red Hat. Red Hat users: If you install PostgreSQL 7.3.2 from the Red Hat 9 RPM, you can skip a few steps. These shell commands add some links for compatibility with the directories from a source-based install; start the service; create a new group for web service users, and modify the postgres user's - environment (more - information):
[root root]# ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib -[root root]# ln -s /var/lib/pgsql /usr/local/pgsql -[root root]# ln -s /etc/init.d/postgresql /etc/init.d/postgres -[root root]# ln -s /usr/bin /usr/local/pgsql/bin -[root root]# service postgresql start + environment (more + information):
[root root]# ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib +[root root]# ln -s /var/lib/pgsql /usr/local/pgsql +[root root]# ln -s /etc/init.d/postgresql /etc/init.d/postgres +[root root]# ln -s /usr/bin /usr/local/pgsql/bin +[root root]# service postgresql start Initializing database: [ OK ] Starting postgresql service: [ OK ] -[root root]# echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile -[root root]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile -[root root]# groupadd web -[root root]# su - postgres +[root root]# echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile +[root root]# echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile +[root root]# groupadd web +[root root]# su - postgres -bash-2.05b$ ln -s /usr/lib/pgsql/ /var/lib/pgsql/lib ln -s /var/lib/pgsql /usr/local/pgsql ln -s /usr/bin /usr/local/pgsql/bin service postgresql start -echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile -echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile +echo "export LD_LIBRARY_PATH=/usr/local/pgsql/lib" >> ~postgres/.bash_profile +echo "export PATH=$PATH:/usr/local/pgsql/bin" >> ~postgres/.bash_profile groupadd web -su - postgres
... and then skip to 8. Something similar may work for other binary packages as well.
Safe approach: install from source
Unpack PostgreSQL 7.4.7. If you have not downloaded the postgresql tarball to - /var/tmp/postgresql-7.4.7.tar.gz, - get it.
[root root]# cd /usr/local/src -[root src]# tar xzf /var/tmp/postgresql-7.4.7.tar.gz +su - postgres
... and then skip to . Something similar may work for other binary packages as well.
Safe approach: install from source
Unpack PostgreSQL 7.4.7. If you have not downloaded the postgresql tarball to + /var/tmp/postgresql-7.4.7.tar.gz, + get it.
[root root]# cd /usr/local/src +[root src]# tar xzf /var/tmp/postgresql-7.4.7.tar.gz [root src]# cd /usr/local/src -tar xzf /var/tmp/postgresql-7.4.7.tar.gz
ALTERNATIVE: Unpack PostgreSQL 7.4.7. If you have not downloaded the postgresql tarball to - /var/tmp/postgresql-7.4.7.tar.bz2, - get it.
[root root]# cd /usr/local/src -[root src]# tar xfj /var/tmp/postgresql-7.4.7.tar.bz2 +tar xzf /var/tmp/postgresql-7.4.7.tar.gz
ALTERNATIVE: Unpack PostgreSQL 7.4.7. If you have not downloaded the postgresql tarball to + /var/tmp/postgresql-7.4.7.tar.bz2, + get it.
[root root]# cd /usr/local/src +[root src]# tar xfj /var/tmp/postgresql-7.4.7.tar.bz2 [root src]# cd /usr/local/src -tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
Install Bison. Only do this if bison --version is smaller than 1.875 and you install PostgreSQL 7.4 from cvs instead of tarball.
[root root]# cd /usr/local/src -[root src]# wget http://ftp.gnu.org/gnu/bison/bison-1.875.tar.gz -[root src]# tar xfz bison-1.875.tar.gz -[root src]# cd bison-1.875 -[root src]# ./configure -[root src]# make install -
Create the Postgres user. +tar xfj /var/tmp/postgresql-7.4.7.tar.bz2
Install Bison. Only do this if bison --version is smaller than 1.875 and you install PostgreSQL 7.4 from cvs instead of tarball.
[root root]# cd /usr/local/src +[root src]# wget http://ftp.gnu.org/gnu/bison/bison-1.875.tar.gz +[root src]# tar xfz bison-1.875.tar.gz +[root src]# cd bison-1.875 +[root src]# ./configure +[root src]# make install +
Create the Postgres user. Create a user and group (if you haven't done so before) for PostgreSQL. This is the account that PostgreSQL will run as since it will not run as root. Since nobody will log in directly as that user, we'll leave the password blank.
Debian users should probably use adduser instead of - useradd. Type man adduser -
[root src]# groupadd web -[root src]# useradd -g web -d /usr/local/pgsql postgres -[root src]# mkdir -p /usr/local/pgsql -[root src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 -[root src]# chmod 750 /usr/local/pgsql + useradd. Type man adduser +
[root src]# groupadd web +[root src]# useradd -g web -d /usr/local/pgsql postgres +[root src]# mkdir -p /usr/local/pgsql +[root src]# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 +[root src]# chmod 750 /usr/local/pgsql [root src]# groupadd web useradd -g web -d /usr/local/pgsql postgres mkdir -p /usr/local/pgsql chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 -chmod 750 /usr/local/pgsql
Mac OS X: Do instead: First make sure the gids and uids below are available (change them if -they are not).To list taken uids and gids:
nireport / /groups name gid | grep "[0123456789][0123456789]" -nireport / /users name uid | grep "[0123456789][0123456789]" -
Now you can install the users
sudo niutil -create / /groups/web +chmod 750 /usr/local/pgsql
Mac OS X: Do instead: First make sure the gids and uids below are available (change them if +they are not).To list taken uids and gids:
nireport / /groups name gid | grep "[0123456789][0123456789]" +nireport / /users name uid | grep "[0123456789][0123456789]" +
Now you can install the users
sudo niutil -create / /groups/web sudo niutil -createprop / /groups/web gid 201 sudo niutil -create / /users/postgres sudo niutil -createprop / /users/postgres gid 201 @@ -93,46 +93,46 @@ sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME uid 201 mkdir -p /usr/local/pgsql chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 -chmod 750 /usr/local/pgsql
FreeBSD users: need to add more parameters. -
[root src]# mkdir -p /usr/local/pgsql -[root src]# pw groupadd -n web -[root src]# pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash -[root src]# chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 -[root src]# chmod -R 750 /usr/local/pgsql +chmod 750 /usr/local/pgsql
FreeBSD users: need to add more parameters. +
[root src]# mkdir -p /usr/local/pgsql +[root src]# pw groupadd -n web +[root src]# pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash +[root src]# chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 +[root src]# chmod -R 750 /usr/local/pgsql [root src]# mkdir -p /usr/local/pgsql pw groupadd -n web pw useradd -n postgres -g web -d /usr/local/pgsql -s /bin/bash chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.7 -chmod -R 750 /usr/local/pgsql
Set up postgres's environment variables. They are necessary for the executable to find its supporting - libraries. Put the following lines into the postgres user's environment.
[root src]# su - postgres -[postgres ~] emacs ~postgres/.bashrc
Paste this line into .bash_profile:
source $HOME/.bashrc
Paste these lines into .bashrc:
export PATH=/usr/local/bin/:$PATH:/usr/local/pgsql/bin +chmod -R 750 /usr/local/pgsql
Set up postgres's environment variables. They are necessary for the executable to find its supporting + libraries. Put the following lines into the postgres user's environment.
[root src]# su - postgres +[postgres ~] emacs ~postgres/.bashrc
Paste this line into .bash_profile:
source $HOME/.bashrc
Paste these lines into .bashrc:
export PATH=/usr/local/bin/:$PATH:/usr/local/pgsql/bin export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib
Test this by logging in as - postgres and checking the - paths; you should see /usr/local/pgsql/bin somewhere in the output (the total output is system-dependent so yours may vary)
[root src]# su - postgres -[postgres pgsql]$ env | grep PATH + postgres and checking the + paths; you should see /usr/local/pgsql/bin somewhere in the output (the total output is system-dependent so yours may vary)
[root src]# su - postgres +[postgres pgsql]$ env | grep PATH LD_LIBRARY_PATH=:/usr/local/pgsql/lib PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:/root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin -[postgres pgsql]$ exit +[postgres pgsql]$ exit
Don't continue unless you see correct output from - env | grep PATH
Compile and install PostgreSQL. - 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 are installing on "OS X" add the flags --with-includes=/sw/include/ --with-libraries=/sw/lib. 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.4.7 -[postgres postgresql-7.4.7]$ ./configure + env | grep PATH
Compile and install PostgreSQL. + 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 are installing on "OS X" add the flags --with-includes=/sw/include/ --with-libraries=/sw/lib. 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.4.7 +[postgres postgresql-7.4.7]$ ./configure creating cache ./config.cache checking host system type... i686-pc-linux-gnu (many lines omitted> linking ./src/makefiles/Makefile.linux to src/Makefile.port linking ./src/backend/port/tas/dummy.s to src/backend/port/tas.s -[postgres postgresql-7.4.7]$ make all +[postgres postgresql-7.4.7]$ make all make -C doc all make[1]: Entering directory `/usr/local/src/postgresql-7.4.7/doc' (many lines omitted) make[1]: Leaving directory `/usr/local/src/postgresql-7.4.7/src' All of PostgreSQL successfully made. Ready to install. -[postgres postgresql-7.4.7]$ make install +[postgres postgresql-7.4.7]$ make install make -C doc install make[1]: Entering directory `/usr/local/src/postgresql-7.4.7/doc' (many lines omitted) @@ -142,30 +142,30 @@ cd /usr/local/src/postgresql-7.4.7 ./configure make all -make install
Start PostgreSQL. - The initdb command initializes the - database. pg_ctl is used to start up +make install
Start PostgreSQL. + The initdb command initializes the + database. pg_ctl is used to start up PostgreSQL. If PostgreSQL is unable to allocate enough memory, see section 11 Tuning PostgreSQL (below). -
[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data -The files belonging to this database system will be owned by user "postgres". +
[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +The files belonging to this database system will be owned by user "postgres". This user must also own the server process. (17 lines omitted) or /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start -[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start +[postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start postmaster successfully started [postgres postgresql-7.4.7]$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start
PostgreSQL errors will be logged in - /usr/local/pgsql/data/server.log -
Install Pl/pgSQL. Set up plpgsq and allow your user to have + /usr/local/pgsql/data/server.log +
Install Pl/pgSQL. Set up plpgsq and allow your user to have access. Plpgsql is a PL/SQL-like language. We add it to template1, which is the template from which all new databases are created. We can verify that it was created - with the createlang command in list mode.
[postgres postgresql-7.4.7]$ createlang plpgsql template1 -[postgres pgsql]$ createlang -l template1 + with the createlang command in list mode.
[postgres postgresql-7.4.7]$ createlang plpgsql template1 +[postgres pgsql]$ createlang -l template1 Procedural languages Name | Trusted? ---------+---------- @@ -174,10 +174,10 @@ [postgres pgsql-7.4.7]$ createlang plpgsql template1 -createlang -l template1
Test PostgreSQL (OPTIONAL). Create a database and try some simple commands. The output should be as shown. -
[postgres pgsql]$ createdb mytestdb +createlang -l template1
Test PostgreSQL (OPTIONAL). Create a database and try some simple commands. The output should be as shown. +
[postgres pgsql]$ createdb mytestdb CREATE DATABASE -[postgres pgsql]$ psql mytestdb +[postgres pgsql]$ psql mytestdb Welcome to psql, the PostgreSQL interactive terminal. Type: \copyright for distribution terms @@ -186,70 +186,70 @@ \g or terminate with semicolon to execute query \q to quit -mytestdb=# select current_timestamp; +mytestdb=# select current_timestamp; timestamptz ------------------------------- 2003-03-07 22:18:29.185413-08 (1 row) -mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql'; +mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql'; CREATE -mytestdb=# select test1(); +mytestdb=# select test1(); test1 ------- 1 (1 row) -mytestdb=# \q -[postgres pgsql]$ dropdb mytestdb +mytestdb=# \q +[postgres pgsql]$ dropdb mytestdb DROP DATABASE -[postgres pgsql]$ exit +[postgres pgsql]$ exit logout -[root src]#
Set PostgreSQL to start on boot. First, we copy the +[root src]#
Set PostgreSQL to start on boot. First, we copy the postgresql.txt init script, which automates startup and shutdown, to the distribution-specific init.d directory. Then we verify that it works. Then we automate it by setting up a bunch of symlinks that ensure that, when the operating system changes runlevels, postgresql goes to the appropriate state. Red Hat and Debian and SuSE each work a little - differently. If you haven't untarred the OpenACS tarball, you will need to do so now to access the postgresql.txt file. -
Red Hat RPM:
The init script is already installed; just turn it on for the appropriate run levels.
[root root]# chkconfig --level 345 postgresql on -[root root]#
Red Hat from source:
[root src]# cp /var/tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql -[root src]# chown root.root /etc/rc.d/init.d/postgresql -[root src]# chmod 755 /etc/rc.d/init.d/postgresql + differently. If you haven't untarred the OpenACS tarball, you will need to do so now to access the postgresql.txt file. +
Red Hat RPM:
The init script is already installed; just turn it on for the appropriate run levels.
[root root]# chkconfig --level 345 postgresql on +[root root]#
Red Hat from source:
[root src]# cp /var/tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql +[root src]# chown root.root /etc/rc.d/init.d/postgresql +[root src]# chmod 755 /etc/rc.d/init.d/postgresql [root src]# cp /var/tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql chown root.root /etc/rc.d/init.d/postgresql -chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root root]# service postgresql stop +chmod 755 /etc/rc.d/init.d/postgresql
Test the script.
[root root]# service postgresql stop Stopping PostgreSQL: ok [root root]#
If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. And turn it back on because we'll use it later. -
[root root]# chkconfig --add postgresql -[root root]# chkconfig --level 345 postgresql on -[root root]# chkconfig --list postgresql +
[root root]# chkconfig --add postgresql +[root root]# chkconfig --level 345 postgresql on +[root root]# chkconfig --list postgresql postgresql 0:off 1:off 2:on 3:on 4:on 5:on 6:off -[root root]# service postgresql start +[root root]# service postgresql start Starting PostgreSQL: ok [root root]# chkconfig --add postgresql chkconfig --level 345 postgresql on chkconfig --list postgresql -service postgresql start
Debian:
[root ~]# cp /var/tmp/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql -[root ~]# chown root.root /etc/init.d/postgresql -[root ~]# chmod 755 /etc/init.d/postgresql +service postgresql start
Debian:
[root ~]# cp /var/tmp/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql +[root ~]# chown root.root /etc/init.d/postgresql +[root ~]# chmod 755 /etc/init.d/postgresql [root ~]# cp /var/tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /etc/init.d/postgresql chown root.root /etc/init.d/postgresql -chmod 755 /etc/init.d/postgresql
Test the script
[root ~]# /etc/init.d/postgresql stop +chmod 755 /etc/init.d/postgresql
Test the script
[root ~]# /etc/init.d/postgresql stop Stopping PostgreSQL: ok [root ~]#
If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown.
-[root ~]# update-rc.d postgresql defaults +[root ~]# update-rc.d postgresql defaults Adding system startup for /etc/init.d/postgresql ... /etc/rc0.d/K20postgresql -> ../init.d/postgresql /etc/rc1.d/K20postgresql -> ../init.d/postgresql @@ -258,73 +258,73 @@ /etc/rc3.d/S20postgresql -> ../init.d/postgresql /etc/rc4.d/S20postgresql -> ../init.d/postgresql /etc/rc5.d/S20postgresql -> ../init.d/postgresql -[root ~]# /etc/init.d/postgresql start +[root ~]# /etc/init.d/postgresql start Starting PostgreSQL: ok -[root ~]#
FreeBSD:
[root ~]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh -[root ~]# chown root:wheel /usr/local/etc/rc.d/postgresql.sh -[root ~]# chmod 755 /usr/local/etc/rc.d/postgresql.sh +[root ~]#
FreeBSD:
[root ~]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh +[root ~]# chown root:wheel /usr/local/etc/rc.d/postgresql.sh +[root ~]# chmod 755 /usr/local/etc/rc.d/postgresql.sh [root ~]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /usr/local/etc/rc.d/postgresql.sh chown root:wheel /usr/local/etc/rc.d/postgresql.sh -chmod 755 /usr/local/etc/rc.d/postgresql.sh
Test the script
[root ~]# /usr/local/etc/rc.d/postgresql.sh stop +chmod 755 /usr/local/etc/rc.d/postgresql.sh
Test the script
[root ~]# /usr/local/etc/rc.d/postgresql.sh stop Stopping PostgreSQL: ok [root ~]#
If PostgreSQL successfully stopped, then turn it back on because we'll use - it later.
[root root]# /usr/local/etc/rc.d/postgresql.sh start + it later.
[root root]# /usr/local/etc/rc.d/postgresql.sh start Starting PostgreSQL: ok [root root]# -/usr/local/etc/rc.d/postgresql.sh start
SuSE:
Note
+/usr/local/etc/rc.d/postgresql.sh start
SuSE:
Note
I have received reports that SuSE 8.0 is different from previous versions. Instead of installing the boot scripts in - /etc/rc.d/init.d/, they should - be placed in /etc/init.d/. If + /etc/rc.d/init.d/, they should + be placed in /etc/init.d/. If you're using SuSE 8.0, delete the - rc.d/ part in each of the + rc.d/ part in each of the following commands. -
[root ~]# cp /var/tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql -[root ~]# chown root.root /etc/rc.d/init.d/postgresql -[root ~]# chmod 755 /etc/rc.d/init.d/postgresql
+
[root ~]# cp /var/tmp/openacs-5.6.0/packages/acs-core-docs/www/files/postgresql.txt /etc/rc.d/init.d/postgresql +[root ~]# chown root.root /etc/rc.d/init.d/postgresql +[root ~]# chmod 755 /etc/rc.d/init.d/postgresql
Test the script. -
[root ~]# /etc/rc.d/init.d/postgresql stop +
[root ~]# /etc/rc.d/init.d/postgresql stop Stopping PostgreSQL: ok
If PostgreSQL successfully stopped, then use the following command to make sure that the script is run appropriately at boot and shutdown. -
[root ~]# cd /etc/rc.d/init.d -root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql K20postgresql -root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql S20postgresql -root:/etc/rc.d/init.d# cp K20postgresql rc2.d -root:/etc/rc.d/init.d# cp S20postgresql rc2.d -root:/etc/rc.d/init.d# cp K20postgresql rc3.d -root:/etc/rc.d/init.d# cp S20postgresql rc3.d -root:/etc/rc.d/init.d# cp K20postgresql rc4.d -root:/etc/rc.d/init.d# cp S20postgresql rc4.d -root:/etc/rc.d/init.d# cp K20postgresql rc5.d -root:/etc/rc.d/init.d# cp S20postgresql rc5.d -root:/etc/rc.d/init.d# rm K20postgresql -root:/etc/rc.d/init.d# rm S20postgresql +
[root ~]# cd /etc/rc.d/init.d +root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql K20postgresql +root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql S20postgresql +root:/etc/rc.d/init.d# cp K20postgresql rc2.d +root:/etc/rc.d/init.d# cp S20postgresql rc2.d +root:/etc/rc.d/init.d# cp K20postgresql rc3.d +root:/etc/rc.d/init.d# cp S20postgresql rc3.d +root:/etc/rc.d/init.d# cp K20postgresql rc4.d +root:/etc/rc.d/init.d# cp S20postgresql rc4.d +root:/etc/rc.d/init.d# cp K20postgresql rc5.d +root:/etc/rc.d/init.d# cp S20postgresql rc5.d +root:/etc/rc.d/init.d# rm K20postgresql +root:/etc/rc.d/init.d# rm S20postgresql root:/etc/rc.d/init.d#
Test configuration. -
root:/etc/rc.d/init.d # cd -root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start +
root:/etc/rc.d/init.d # cd +root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start Starting PostgreSQL: ok -root:~ #
Mac OS X 10.3:
Install the startup script:
cd /System/Library/StartupItems/ -tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz -
Mac OS X 10.4 can use Launchd:
Install the startup script:
cd /Library/LaunchDaemons -cp +root:~ #
Mac OS X 10.3:
Install the startup script:
cd /System/Library/StartupItems/ +tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz +
Mac OS X 10.4 can use Launchd:
Install the startup script:
cd /Library/LaunchDaemons +cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-launchd-item.txt -org.postgresql.PostgreSQL.plist+org.postgresql.PostgreSQL.plist
If postgres does not start automatically on reboot, see what error you get when manually starting it with:
-$ sudo launchctl load /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist -$ sudo launchctl start org.postgresql.PostgreSQL
+$ sudo launchctl load /Library/LaunchDaemons/org.postgresql.PostgreSQL.plist +$ sudo launchctl start org.postgresql.PostgreSQL
From now on, PostgreSQL should start automatically each time you boot up and it should shutdown gracefully each time you shut down. (Note: @@ -333,12 +333,12 @@ start on runlevel 2 unless you alter the above commands a little. This usually isn't a problem as Red Hat defaults to runlevel 3) -
Tune postgres. (OPTIONAL). The default values for PostgreSQL are very conservative; we can safely change some of them and improve performance.
Change the kernel parameter for maximum shared memory - segment size to 128Mb:
[root root]# echo 134217728 >/proc/sys/kernel/shmmax +
Tune postgres. (OPTIONAL). The default values for PostgreSQL are very conservative; we can safely change some of them and improve performance.
Change the kernel parameter for maximum shared memory + segment size to 128Mb:
[root root]# echo 134217728 >/proc/sys/kernel/shmmax [root root]#
Make that change permanent by editing - /etc/sysctl.conf to + /etc/sysctl.conf to add these lines at the end:
# increase shared memory limit for postgres -kernel.shmmax = 134217728
Edit the PostgreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory. These values should improve performance in most cases. (more information)
# Shared Memory Size +kernel.shmmax = 134217728
Edit the PostgreSQL config file, /usr/local/pgsql/data/postgresql.conf, to use more memory. These values should improve performance in most cases. (more information)
# Shared Memory Size # shared_buffers = 15200 # 2*max_connections, min 16 @@ -350,35 +350,35 @@ # Write-ahead log (WAL) # checkpoint_segments = 3 # in logfile segments (16MB each), min 1 -
Restart postgres (service postgresql - restart) or - (/etc/init.d/postgres - restart) so that the changes take effect.
FreeBSD users: See man syctl, man 5 sysctl - and man 5 loader.conf.
Performance tuning resources:
- Managing Kernel Resources +
Restart postgres (service postgresql + restart) or + (/etc/init.d/postgres + restart) so that the changes take effect.
FreeBSD users: See man syctl, man 5 sysctl + and man 5 loader.conf.
Performance tuning resources:
+ Managing Kernel Resources about PostgreSQL shared memory and semaphores with specific operating system notes. -
- Managing Kernel Resources (development version) +
+ Managing Kernel Resources (development version) This information may be experimental. -
- Tuning PostgreSQL for performance
more information about PostgreSQL
+
+ Tuning PostgreSQL for performance
more information about PostgreSQL
- Official PostgreSQL + Official PostgreSQL Docs -
+
- Migrating + Migrating from 7.0 to 7.1 -
+
- techdocs.postgresql.org + techdocs.postgresql.org -
+
- PostgreSQL + PostgreSQL Performance Tuning
($Id$)
Prev Home Next
Install Oracle 8.1.7 Up Install AOLserver 4
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/profile-code.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/profile-code.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/profile-code.html 17 Oct 2010 21:06:08 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/profile-code.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,11 +1,11 @@ - -Profile your code
Prev Chapter 10. Advanced Topics Next
Profile your code
by Jade Rubick
+ +Profile your code
Prev Chapter 9. Advanced Topics Next
Profile your code
by Jade Rubick
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
There are several facilities for profiling your code in OpenACS. The first thing to do is to install the developer-support package and play around with it. But there is also support in the API for profiling your code: - profiling + profiling your code using ds_profile
Prev Home Next
Categories Up Prepare the package for distribution.
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,66 +1,66 @@ - -Programming with AOLserver
Prev Chapter 11. Development Reference Next
Programming with AOLserver
By Michael Yoon, Jon Salz and Lars Pind.
+ +Programming with AOLserver
Prev Chapter 10. Development Reference Next
Programming with AOLserver
By Michael Yoon, Jon Salz and Lars Pind.
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
The global command
+
The global command
When using AOLserver, remember that there are effectively two types of global namespace, not one: -
Server-global: As you'd expect, there is +
Server-global: As you'd expect, there is only one server-global namespace per server, and variables set within it can be accessed by any Tcl code running subsequently, in any of the server's -threads. To set/get server-global variables, use AOLserver 3's nsv API -(which supersedes ns_share from the pre-3.0 API). -
Script-global: Each Tcl script (ADP, Tcl page, +threads. To set/get server-global variables, use AOLserver 3's nsv API +(which supersedes ns_share from the pre-3.0 API). +
Script-global: Each Tcl script (ADP, Tcl page, registered proc, filter, etc.) executing within an AOLserver thread has its own global namespace. Any variable set in the top level of a script is, by definition, script-global, meaning that it is accessible only by subsequent code in the same script and only for the duration of the current script execution.
-The Tcl built-in command global +The Tcl built-in command global accesses script-global, not server-global, variables from within a procedure. This distinction is important to understand in order to use -global correctly when programming AOLserver. +global correctly when programming AOLserver.
Also, AOLserver purges all script-global variables in a thread (i.e., Tcl interpreter) between HTTP requests. If it didn't, that would affect (and complicate) our use of script-global variables dramatically, which would then be better described as thread-global variables. Given -AOLserver's behaviour, however, "script-global" is a more -appropriate term.
Threads and Scheduled Procedures
-ns_schedule_proc and ad_schedule_proc each take a --thread flag to cause a scheduled procedure to run +AOLserver's behaviour, however, "script-global" is a more +appropriate term.
Threads and Scheduled Procedures
+ns_schedule_proc and ad_schedule_proc each take a +-thread flag to cause a scheduled procedure to run asychronously, in its own thread. It almost always seems like a good idea to specify this switch, but there's a problem. -
It turns out that whenever a task scheduled with ns_schedule_proc --thread or ad_schedule_proc -thread t is run, AOLserver +
It turns out that whenever a task scheduled with ns_schedule_proc +-thread or ad_schedule_proc -thread t is run, AOLserver creates a brand new thread and a brand new interpreter, and reinitializes the procedure table (essentially, loads all procedures that were created during server initialization into the new interpreter). This happens every time the task is executed - and it is a very expensive process that should not be taken lightly!
The moral: if you have a lightweight scheduled procedure -which runs frequently, don't use the -thread +which runs frequently, don't use the -thread switch.
Note also that thread is initialized with a copy of what was installed during server startup, so if the procedure table have changed since -startup (e.g. using the APM watch +startup (e.g. using the APM watch facility), that will not be reflected in the scheduled -thread.
Using return
-The return command in Tcl returns control to the caller procedure. +thread.
Using return
+The return command in Tcl returns control to the caller procedure. This definition allows nested procedures to work properly. However, this -definition also means that nested procedures cannot use return to +definition also means that nested procedures cannot use return to end an entire thread. This situation is most common in exception conditions that can be triggered from inside a procedure e.g., a permission denied exception. At this point, the procedure that detects invalid permission wants to write an error message to the user, and completely abort execution of the -caller thread. return doesn't work, because the procedure may be -nested several levels deep. We therefore use ad_script_abort -to abort the remainder of the thread. Note that using return instead -of ad_script_abort may raise some security issues: an attacker could +caller thread. return doesn't work, because the procedure may be +nested several levels deep. We therefore use ad_script_abort +to abort the remainder of the thread. Note that using return instead +of ad_script_abort may raise some security issues: an attacker could call a page that performed some DML statement, pass in some arguments, and get a permission denied error -- but the DML statement would still be -executed because the thread was not stopped. Note that return -code -return can be used in circumstances where the procedure will only be +executed because the thread was not stopped. Note that return -code +return can be used in circumstances where the procedure will only be called from two levels deep. -
Returning More Than One Value From a Function
-Many functions have a single return value. For instance, empty_string_p +
Returning More Than One Value From a Function
+Many functions have a single return value. For instance, empty_string_p returns a number: 1 or 0. Other functions need to return a composite value. For instance, consider a function that looks up a user's name and email address, given an ID. One way to implement this is to return a three-element @@ -75,33 +75,33 @@
AOLserver/Tcl generally has three mechanisms that we like, for returning more than one value from a function. When to use which depends on the circumstances.
Using Arrays and Pass-By-Value
-The one we generally prefer is returning an array -get-formatted list. It has all the nice properties of +The one we generally prefer is returning an array +get-formatted list. It has all the nice properties of pass-by-value, and it uses Tcl arrays, which have good native support.
ad_proc ad_get_user_info { user_id } { db_1row user_info { select first_names, last_name, email from users where user_id = :user_id } return [list \ - name "$first_names $last_name" \ + name "$first_names $last_name" \ email $email \ - namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" \ - emaillink "<a href=\"mailto:$email\">$email</a>"] + namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" \ + emaillink "<a href=\"mailto:$email\">$email</a>"] } array set user_info [ad_get_user_info $user_id] -doc_body_append "$user_info(namelink) ($user_info(emaillink))" +doc_body_append "$user_info(namelink) ($user_info(emaillink))"
You could also have done this by using an array internally and using -array get: +array get:
ad_proc ad_get_user_info { user_id } { db_1row user_info { select first_names, last_name, email from users where user_id = :user_id } - set user_info(name) "$first_names $last_name" + set user_info(name) "$first_names $last_name" set user_info(email) $email - set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" - set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>" + set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" + set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>" return [array get user_info] } @@ -117,7 +117,7 @@ milisecond. The time depends almost completely on the number of entries, and almost not at all on the size of the entries.
You implement pass-by-reference in Tcl by taking the name of an array -as an argument and upvar it. +as an argument and upvar it.
ad_proc ad_get_user_info { @@ -126,30 +126,30 @@ } { upvar $array user_info db_1row user_info { select first_names, last_name, email from users where user_id = :user_id } - set user_info(name) "$first_names $last_name" + set user_info(name) "$first_names $last_name" set user_info(email) $email - set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" - set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>" + set user_info(namelink) "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" + set user_info(emaillink) "<a href=\"mailto:$email\">$email</a>" } ad_get_user_info -array user_info $user_id -doc_body_append "$user_info(namelink) ($user_info(emaillink))" +doc_body_append "$user_info(namelink) ($user_info(emaillink))"
We prefer pass-by-value over pass-by-reference. Pass-by-reference makes the code harder to read and debug, because changing a value in one place has side effects in other places. Especially if have a chain of -upvars through several layers of the call stack, you'll have -a hard time debugging.
Multisets: Using ns_sets and Pass-By-Reference
+upvars through several layers of the call stack, you'll have +a hard time debugging.
Multisets: Using ns_sets and Pass-By-Reference
An array is a type of set, which means you can't have multiple entries with the same key. Data structures that can have multiple entries for the same key are known as a multiset or bag.
If your data can have multiple entries with the same key, -you should use the AOLserver built-in -ns_set. You can also do a case-insensitive lookup on an -ns_set, something you can't easily do on an array. This is +you should use the AOLserver built-in +ns_set. You can also do a case-insensitive lookup on an +ns_set, something you can't easily do on an array. This is especially useful for things like HTTP headers, which happen to have these -exact properties.
You always use pass-by-reference with ns_sets, since they +exact properties.
You always use pass-by-reference with ns_sets, since they don't have any built-in way of generating and reconstructing themselves from a string representation. Instead, you pass the handle to the set.
@@ -158,34 +158,34 @@ user_id } { db_1row user_info { select first_names, last_name, email from users where user_id = :user_id } - ns_set put $set name "$first_names $last_name" + ns_set put $set name "$first_names $last_name" ns_set put $set email $email - ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" - ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>" + ns_set put $set namelink "<a href=\"/shared/community-member?user_id=[ns_urlencode $user_id]\">$first_names $last_name</a>" + ns_set put $set emaillink "<a href=\"mailto:$email\">$email</a>" } set user_info [ns_set create] ad_get_user_info -set $user_info $user_id -doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])" +doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])"
-We don't recommend ns_set as a general mechanism for passing +We don't recommend ns_set as a general mechanism for passing sets (as opposed to multisets) of data. Not only do they inherently use pass-by-reference, which we dis-like, they're also somewhat clumsy to use, since Tcl doesn't have built-in syntactic support for them. -
Consider for example a loop over the entries in a ns_set as +
Consider for example a loop over the entries in a ns_set as compared to an array:
# ns_set variant set size [ns_set size $myset] for { set i 0 } { $i < $size } { incr i } { - puts "[ns_set key $myset $i] = [ns_set value $myset $i]" + puts "[ns_set key $myset $i] = [ns_set value $myset $i]" } # array variant foreach name [array names myarray] { - puts "$myarray($name) = $myarray($name)" + puts "$myarray($name) = $myarray($name)" }
@@ -205,9 +205,9 @@ ]
-ns_sets are designed to be lightweight, so memory consumption -should not be a problem. However, when using ns_set get to +ns_sets are designed to be lightweight, so memory consumption +should not be a problem. However, when using ns_set get to perform lookup by name, they perform a linear lookup, whereas arrays use a -hash table, so ns_sets are slower than arrays when the number of +hash table, so ns_sets are slower than arrays when the number of entries is large.
($Id$)
Prev Home Next
Object Identity Up Using Form Builder: building html forms dynamically
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v diff -u -N -r1.38 -r1.39 --- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 17 Oct 2010 21:06:08 -0000 1.38 +++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 11 Dec 2010 23:36:32 -0000 1.39 @@ -1,9 +1,9 @@ - -Add PSGML commands to emacs init file (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Add PSGML commands to emacs init file (OPTIONAL)
+ +Add PSGML commands to emacs init file (OPTIONAL)
Prev Appendix B. Install additional supporting software Next
Add PSGML commands to emacs init file (OPTIONAL)
If you plan to write or edit any documentation with emacs, install a customized emacs configuration file with DocBook commands in the skeleton directory, so it will be used for all new users. The file also fixes the backspace -> help mis-mapping that often occurs in - terminals.
[root tmp]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs -cp: overwrite `/etc/skel/.emacs'? y -[root tmp]#
Debian users:
apt-get install psgml
Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For debian, apt-get install nxml.
Prev Home Next
Initialize CVS (OPTIONAL) Up Install Daemontools (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org + terminals.
[root tmp]# cp /tmp/openacs-5.6.0/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs +cp: overwrite `/etc/skel/.emacs'? y +[root tmp]#
Debian users:
apt-get install psgml
Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For debian, apt-get install nxml.
Prev Home Next
Initialize CVS (OPTIONAL) Up Install Daemontools (OPTIONAL)
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v diff -u -N -r1.45 -r1.46 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 17 Oct 2010 21:06:08 -0000 1.45 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 11 Dec 2010 23:36:32 -0000 1.46 @@ -1,53 +1,53 @@ - -Using PSGML mode in Emacs
Prev Chapter 13. Documentation Standards Next
Using PSGML mode in Emacs
By David Lutterkort
+ +Using PSGML mode in Emacs
Prev Chapter 12. Documentation Standards Next
Using PSGML mode in Emacs
By David Lutterkort
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Note: nxml mode replaces and/or complements psgml mode. More information.
What it is
PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It +
Note: nxml mode replaces and/or complements psgml mode. More information.
What it is
PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It can parse a DTD and help you insert the right tags in the right place, knows about tags' attributes and can tell you in which contexts a tag can be used. If you give it the right DTD, that is. But even without a DTD, -it can save you some typing since pressing C-c/ will close an open -tag automatically.
Where to get it
Most newer emacsen come with PSGML mode preinstalled. You can find out -whether your emacs has it with the locate-library command. In Emacs, -type M-x locate-library and enter psgml. Emacs will tell +it can save you some typing since pressing C-c/ will close an open +tag automatically.
Where to get it
Most newer emacsen come with PSGML mode preinstalled. You can find out +whether your emacs has it with the locate-library command. In Emacs, +type M-x locate-library and enter psgml. Emacs will tell you if it found it or not.
If you don't have PSGML preinstalled in your Emacs, there are two -things you can do:
On Linux: Get the -psgml rpm from RedHat's -docbook-tools and install it as usual.
On other systems: Get the tarball from the PSGML Website. -Unpack it and follow the install instructions.
Using CATALOG files
The easiest way to teach PSGML mode about a DTD is by adding it to your -own CATALOG. Here is an example of how you can set that up for the -Docbook XML DTD.
Get the Docbook XML DTD -zip archive from docbook.org
Go somewhere in your working directory and do
+things you can do:
On Linux: Get the +psgml rpm from RedHat's +docbook-tools and install it as usual.
On other systems: Get the tarball from the PSGML Website. +Unpack it and follow the install instructions.
Using CATALOG files
The easiest way to teach PSGML mode about a DTD is by adding it to your +own CATALOG. Here is an example of how you can set that up for the +Docbook XML DTD.
Get the Docbook XML DTD +zip archive from docbook.org
Go somewhere in your working directory and do
mkdir -p dtd/docbook-xml cd dtd/docbook-xml unzip -a <docbook XML DTD zip archive> -
Create a file with the name CATALOG in the dtd +
Create a file with the name CATALOG in the dtd directory and put the line
- CATALOG "docbook-xml/docbook.cat" + CATALOG "docbook-xml/docbook.cat"
-in it. By maintaining your own CATALOG, it is easy to add more +in it. By maintaining your own CATALOG, it is easy to add more DTD's without changing your emacs settings. (How about that HTML 4.01 DTD you -always wanted to get from W3C ? The +always wanted to get from W3C ? The DTD is in the zip archives and tarballs available on the site.)
That's it. Now you are ready to tell emacs all about PSGML mode and -that funky CATALOG
What to tell emacs
If you installed PSGML mode in a non-standard location, e.g., somewhere in -your home directory, you need to add this to the load-path by adding -this line to your .emacs file:
- (add-to-list 'load-path "/some/dir/that/contains/psgml.elc") +that funky CATALOG
What to tell emacs
If you installed PSGML mode in a non-standard location, e.g., somewhere in +your home directory, you need to add this to the load-path by adding +this line to your .emacs file:
+ (add-to-list 'load-path "/some/dir/that/contains/psgml.elc") -
To let PSGML mode find your CATALOG and to enable PSGML mode for -all your editing, add these lines to your .emacs:
+
To let PSGML mode find your CATALOG and to enable PSGML mode for +all your editing, add these lines to your .emacs:
(require 'psgml) - (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode)) - (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode)) - (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode)) - (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode)) + (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode)) + (add-to-list 'auto-mode-alist '("\\.adp" . xml-mode)) + (add-to-list 'auto-mode-alist '("\\.xml" . xml-mode)) + (add-to-list 'auto-mode-alist '("\\.xsl" . xml-mode)) - (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG") + (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG")
If you want font-locking and indentation, you can also add these lines -into the .emacs file:
+into the .emacs file:
(setq sgml-markup-faces '((start-tag . font-lock-function-name-face) (end-tag . font-lock-function-name-face) (comment . font-lock-comment-face) @@ -59,28 +59,28 @@ (setq sgml-set-face t) (setq-default sgml-indent-data t) ;; Some convenient key definitions: - (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type) - (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info) - (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity) + (define-key sgml-mode-map "\C-c\C-x\C-e" 'sgml-describe-element-type) + (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info) + (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity) -
What is a DOCTYPE ?
All SGML and XML documents that should conform to a DTD have to declare a -doctype. For the docbook XML, all your .xml files whould start with +
What is a DOCTYPE ?
All SGML and XML documents that should conform to a DTD have to declare a +doctype. For the docbook XML, all your .xml files whould start with the line
- <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd"> + <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd">
If your document is only part of a larger XML document, you can tell PSGML mode about it by appending the following lines to your file. In this case, do not include a DOCTYPE declaration in your file.

Which says that the parent of this document can be found in the file -top.xml, that the element in the parent that will enclose the -current document is a book and that the current file's topmost -element is a sect1.
How to use it
Of course, you should read the emacs texinfo pages that come with PSGML -mode from start to finish. Barring that, here are some handy commands:
Key Command
C-c C-e Insert an element. Uses completion and only lets you insert elements that -are valid
C-c C-a Edit attributes of enclosing element.
C-c C-x C-i Show information about the document's DTD.
C-c C-x C-e Describe element. Shows for one element which elements can be parents, -what its contents can be and lists its attributes.
Further reading
Start with the Section , “OpenACS Documentation Guide”
($Id$)
Prev Home Next
OpenACS Documentation Guide Up Using nXML mode in Emacs
docs@openacs.org
View comments on this page at openacs.org +top.xml, that the element in the parent that will enclose the +current document is a book and that the current file's topmost +element is a sect1.
How to use it
Of course, you should read the emacs texinfo pages that come with PSGML +mode from start to finish. Barring that, here are some handy commands:
Key Command
C-c C-e Insert an element. Uses completion and only lets you insert elements that +are valid
C-c C-a Edit attributes of enclosing element.
C-c C-x C-i Show information about the document's DTD.
C-c C-x C-e Describe element. Shows for one element which elements can be parents, +what its contents can be and lists its attributes.
Further reading
Start with the OpenACS Documentation Guide
($Id$)
Prev Home Next
OpenACS Documentation Guide Up Using nXML mode in Emacs
docs@openacs.org
View comments on this page at openacs.org 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.52 -r1.53 --- openacs-4/packages/acs-core-docs/www/release-notes.html 17 Oct 2010 21:06:08 -0000 1.52 +++ openacs-4/packages/acs-core-docs/www/release-notes.html 11 Dec 2010 23:36:32 -0000 1.53 @@ -1,20 +1,20 @@ - -OpenACS Release Notes
Prev Chapter 1. High level information: What is OpenACS? Next
OpenACS Release Notes
The ChangeLogs include an annotated list of changes (Section , “Changelog (most recent release only)”) since the last release and in the -entire 5.6 release sequence Section , “Changelog for oacs-5-6”.
Release 5.6.0
- Added new package dependency type, "embeds". This is a variant of the - "extends" package dependency type added in OpenACS 5.5.0. It allows one + +OpenACS Release Notes
Prev Chapter 1. High level information: What is OpenACS? Next
OpenACS Release Notes
The ChangeLogs include an annotated list of changes (Changelog (most recent release only)) since the last release and in the +entire 5.6 release sequence Changelog for oacs-5-6.
Release 5.6.0
+ Added new package dependency type, "embeds". This is a variant of the + "extends" package dependency type added in OpenACS 5.5.0. It allows one to write embeddable packages, with scripts made visible in client packages using URLs which include the embedded package's package key. An example - embeddable package might be a rewritten "attachments" package. The current + embeddable package might be a rewritten "attachments" package. The current implementation requires a global instance be mounted, and client packages generate urls to that global instance. Among other things, this leads to the user navigating to the top-level subsite, losing any subsite theming - that might be associated with a community. Using "embeds", a rewritten + that might be associated with a community. Using "embeds", a rewritten package would run in the client package's context, maintaining theming and automatically associating attachments with the client package.
- Added global package parameters - parameters can now have scope "local" or "global", - with "local" being the default.. + Added global package parameters - parameters can now have scope "local" or "global", + with "local" being the default..
Fixes for ns_proxy handling
@@ -29,32 +29,32 @@ Support for 3-chars language codes in acs-lang
Added OOXML mime types in acs-content-repository -
Release 5.5.0
PostgreSQL 8.3 is now fully supported, including the use of the built-in +
Release 5.5.0
PostgreSQL 8.3 is now fully supported, including the use of the built-in standard version of tsearch2.
TinyMCE has been upgraded to 3.2.4.1 with language pack support.
acs-mail-lite now correctly implements rollout support.
- Added new package dependency type, "extends". Implements a weak form of + Added new package dependency type, "extends". Implements a weak form of package inheritance (parameters and, optionally, templates). Multiple inheritance - is supported. For instance, the non-core "layout-managed-subsite" extends the - "acs-subsite" and "layout-manager" packages, resulting in a package that + is supported. For instance, the non-core "layout-managed-subsite" extends the + "acs-subsite" and "layout-manager" packages, resulting in a package that combines the semantics of both.
- Added new package attribute "implements-subsite-p" (default "f"). If true, + Added new package attribute "implements-subsite-p" (default "f"). If true, this package may be mounted as a subsite and is expected to implement subsite semantics. Typically used by packages which extend acs-subsite.
- Added new package attribute "inherit-templates-p" (default "t"). If true, + Added new package attribute "inherit-templates-p" (default "t"). If true, the package inherits templates defined in the packages it extends. This means that the package only needs to specify templates where the UI of an extended package is modified or extended. This greatly reduces the need to fork base packages when one needs to customize it. Rather than modify the package directly, - use "extends" rather than "requires" then rewrite those templates you need to + use "extends" rather than "requires" then rewrite those templates you need to customize.
Added a simple mechanism for defining subsite themes, removing the hard-wired choices implemented in earlier versions of OpenACS. The default theme has been - moved into a new package, "openacs-default-theme". Simplifies the customization + moved into a new package, "openacs-default-theme". Simplifies the customization of the look and feel of OpenACS sites and subsites.
The install xml facility has been enhanced to allow the calling of arbitrary Tcl @@ -67,57 +67,57 @@ before sending the message out, using the recipient locale if set, the site-wide one if not. This will cause message keys (entered as #....# strings) to be replaced with the language text for the chosen locale. -
Release 5.4.2
This is a minor bugfix release. -
Site node caching was removed as doesn't work correctly
Critical issues with search on oracle were fixed
More html strict work etc
Release 5.4.1
This is a minor bugfix release. -
Release 5.4.0
New Templating API added to add scripts, css, etc to the HTML HEAD and BODY +
Release 5.4.2
This is a minor bugfix release. +
Site node caching was removed as doesn't work correctly
Critical issues with search on oracle were fixed
More html strict work etc
Release 5.4.1
This is a minor bugfix release. +
Release 5.4.0
New Templating API added to add scripts, css, etc to the HTML HEAD and BODY sections of the generated HTML document. Please see /packages/acs-templating/tcl/head-procs.tcl or visit the template::head procs in the API browser for details.
Templates have been modified to comply with HTML strict
The Search package's results page has been improved
TinyMCE WYSIWYG support has been added, RTE and HTMLArea support dropped
acs-mail-lite's send has been cleaned up to properly encode content, to handle - file attachments, etc. "complex-send" will disappear from acs-core in a future - release.
The ChangeLogs include an annotated list of changes (Section , “Changelog (most recent release only)”) since the last release and in the -entire 5.6 release sequence Section , “Changelog for oacs-5-6”.
Release 5.3.1
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
New Site and Blank master templates and CSS compatible with the .LRN Zen - work. Compatibility master templates are provided for existing sites.
The ChangeLogs include an annotated list of changes (Section , “Changelog (most recent release only)”) since the last release and in the -entire 5.6 release sequence Section , “Changelog for oacs-5-6”.
Release 5.3.0
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
Release 5.2.0
Bug fixes.
New TIPs implemented.
This release does not include new translations.
Release 5.1.4
Bug fixes.
The missing CR TCL API has been filled in, thanks to Rocael and - his team and Dave Bauer.
This release does not include new translations.
Release 5.1.3
Bug fixes, primarily for .LRN compatibility in support of upcoming .LRN 2.1.0 releases. This release does not include new translations since 5.1.2. -
Release 5.1.2
Translations syncronized with the translation server. + file attachments, etc. "complex-send" will disappear from acs-core in a future + release.
The ChangeLogs include an annotated list of changes (Changelog (most recent release only)) since the last release and in the +entire 5.6 release sequence Changelog for oacs-5-6.
Release 5.3.1
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
New Site and Blank master templates and CSS compatible with the .LRN Zen + work. Compatibility master templates are provided for existing sites.
The ChangeLogs include an annotated list of changes (Changelog (most recent release only)) since the last release and in the +entire 5.6 release sequence Changelog for oacs-5-6.
Release 5.3.0
Bug fixes.
New TIPs implemented.
All Core Automated Tests for Postgres pass.
Release 5.2.0
Bug fixes.
New TIPs implemented.
This release does not include new translations.
Release 5.1.4
Bug fixes.
The missing CR TCL API has been filled in, thanks to Rocael and + his team and Dave Bauer.
This release does not include new translations.
Release 5.1.3
Bug fixes, primarily for .LRN compatibility in support of upcoming .LRN 2.1.0 releases. This release does not include new translations since 5.1.2. +
Release 5.1.2
Translations syncronized with the translation server. Basque and Catalan added. -
For a complete change list, see the Change list since - 5.1.0 in Section , “Changelog for oacs-5-6”.
Release 5.1.1
This is the first release using the newest adjustment to the versioning convention. The OpenACS 5.1.1 tag will apply to OpenACS core as well as to the most recent released version of every package, including .LRN.
Translations syncronized with the translation server. -
Bug +
For a complete change list, see the Change list since + 5.1.0 in Changelog for oacs-5-6.
Release 5.1.1
This is the first release using the newest adjustment to the versioning convention. The OpenACS 5.1.1 tag will apply to OpenACS core as well as to the most recent released version of every package, including .LRN.
Translations syncronized with the translation server. +
Bug 1519 fixed. This involved renaming all catalog files for ch_ZH, TH_TH, AR_EG, AR_LB, ms_my, RO_RO, FA_IR, and HR_HR. If you work with any of those locales, you should do a full catalog export and then import (via - /acs-lang/admin) after + /acs-lang/admin) after upgrading acs-lang. (And, of course, make a backup of both - the files and database before upgrading.)
Other bug fixes since 5.1.0: 1785, - 1793, - and over a dozen additional bug fixes.
For a complete change list, see the Change list since - 5.0.0 in Section , “Changelog for oacs-5-6”.
Release 5.1.0
Lots of little tweaks and fixes
Complete Change list since 5.0.0 in Changelog
Many Bug fixes
Release 5.0.4
New translations, including for .LRN 2.0.2.
Release 5.0.3
Bug fixes: 1560, #1556. Site becomes unresponsive, requires restart
Release 5.0.2
Bug fixes: #1495. Croatian enabled by default, #1496. APM automated install fails if files have spaces in their names, #1494. automated upgrade crashes (halting the upgrade process)
Complete Change list since 5.0.0 in Changelog
File tagging scheme in CVS changed to follow TIP #46: (Approved) Rules for Version Numbering and CVS tagging of Packages
Release 5.0.1
All work on the translation server from 7 Nov 2003 to 7 Feb 2004 is now included in catalogs.
One new function in acs-tcl, util::age_pretty
Complete Change list since 5.0.0 in Changelog
Many documentation updates and doc bug fixes
Release 5.0.0
+ the files and database before upgrading.)
Other bug fixes since 5.1.0: 1785, + 1793, + and over a dozen additional bug fixes.
For a complete change list, see the Change list since + 5.0.0 in Changelog for oacs-5-6.
Release 5.1.0
Lots of little tweaks and fixes
Complete Change list since 5.0.0 in Changelog
Many Bug fixes
Release 5.0.4
New translations, including for .LRN 2.0.2.
Release 5.0.3
Bug fixes: 1560, #1556. Site becomes unresponsive, requires restart
Release 5.0.2
Bug fixes: #1495. Croatian enabled by default, #1496. APM automated install fails if files have spaces in their names, #1494. automated upgrade crashes (halting the upgrade process)
Complete Change list since 5.0.0 in Changelog
File tagging scheme in CVS changed to follow TIP #46: (Approved) Rules for Version Numbering and CVS tagging of Packages
Release 5.0.1
All work on the translation server from 7 Nov 2003 to 7 Feb 2004 is now included in catalogs.
One new function in acs-tcl, util::age_pretty
Complete Change list since 5.0.0 in Changelog
Many documentation updates and doc bug fixes
Release 5.0.0
This is OpenACS 5.0.0. This version contains no known security, data loss, or crashing bugs, nor any bugs judged release blockers. This version has received manual testing. It has passed current automated testing, which is not comprehensive. This release contains work done on the translation server http://translate.openacs.org through 7 Nov 2003.
Please report bugs using our - - Bug Tracker at the OpenACS website. + + Bug Tracker at the OpenACS website.
You may want to begin by reading our installation documentation for - Section , “a Unix-like system”. Note that the Windows documentation is + a Unix-like system. Note that the Windows documentation is not current for OpenACS 5.6.0, but an alternative is to use John - Sequeira's Oasis VM + Sequeira's Oasis VM project.
After installation, the full documentation set can be found by visiting - http://yourserver/doc. + http://yourserver/doc.
New features in this release: -
+
Internationalization support. A message catalog to store translated text, localization of dates, number formatting, timezone conversion, etc. Allows you to serve your users in their language. -
+
External authenticaiton. Integrate with outside user databases through e.g. LDAP, RADIUS, Kerberos, MS Active Directory. @@ -128,7 +128,7 @@ user's identity being completely lost. You can set login to expire after a certain period (e.g. 8 hours, then password must be refreshed), or you can have all issues login cookies expired at once, e.g. if you have left a permanent login cookie on a public machine somewhere. -
+
User interface enhancements. All pages, including site-wide and subsite admin pages, will be @@ -158,43 +158,232 @@ actions on multiple rows with checkboxes, etc. Most of all, it's fast to use, and results in consistently-looking, consistently-behaving, templated tables. -
+
Automated testing. The automated testing framework has been improved significantly, and there are automated tests for a number of packages. -
+
Security enhancements. HTML quoting now happens in the templating system, greatly minimizing the chance that users can sneak malicious HTML into the pages of other users. -
+
Oracle 9i support. -
+
Who's online feature. -
+
Spell checking.
Potential incompatibilities: -
+
With the release of OpenACS 5, PostgreSQL 7.2 is no longer supported. Upgrades are supported from OpenACS 4.6.3 under Oracle or PostgreSQL 7.3. -
+
The undocumented special handling of ~ and +variable+ in - formtemplates, found in packages/acs-templating/resources/*, + formtemplates, found in packages/acs-templating/resources/*, has been removed in favor of using <noparse> and \@variable\@ (the standard templating mechanisms). Locally provided formtemplate styles still using these mechanisms will break. -
+
Serving backup files and files from the CVS directories is turned off by default via the acs-kernel parameter - ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~") -
($Id$)
Release 4.6.3
Release Notes for 4.6.3
Release 4.6.2
Release Notes for 4.6.2
Release 4.6
Release Notes for 4.6
Release 4.5
Release Notes for 4.5
Changelog (most recent release only)
ChangeLog missing
+ ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~") +
($Id$)
Release 4.6.3
Release Notes for 4.6.3
Release 4.6.2
Release Notes for 4.6.2
Release 4.6
Release Notes for 4.6
Release 4.5
Release Notes for 4.5
Changelog (most recent release only)
ChangeLog missing
--> -
Changelog for oacs-5-6
-ChangeLog missing +
Changelog for oacs-5-6
+2009-09-05 21:44 donb + + * packages/acs-content-repository/tcl/apm-callback-procs.tcl: The + after upgrade callback needed a documentation block. + +2009-09-05 16:27 donb + + * packages/: acs-admin/acs-admin.info, + acs-api-browser/acs-api-browser.info, + acs-authentication/acs-authentication.info, + acs-automated-testing/acs-automated-testing.info, + acs-bootstrap-installer/acs-bootstrap-installer.info, + acs-content-repository/acs-content-repository.info, + acs-core-docs/acs-core-docs.info, acs-kernel/acs-kernel.info, + acs-lang/acs-lang.info, acs-mail-lite/acs-mail-lite.info, + acs-messaging/acs-messaging.info, + acs-reference/acs-reference.info, + acs-service-contract/acs-service-contract.info, + acs-subsite/acs-subsite.info, acs-tcl/acs-tcl.info, + acs-templating/acs-templating.info, + acs-translations/acs-translations.info, + intermedia-driver/intermedia-driver.info, + notifications/notifications.info, + openacs-default-theme/openacs-default-theme.info, + ref-timezones/ref-timezones.info, search/search.info, + tsearch2-driver/tsearch2-driver.info: Bumped version number to + 5.5.1b1 in preparation for release. + +2009-09-02 17:32 daveb + + * packages/acs-tcl/tcl/request-processor-procs.tcl: Fix redirect + when ForceHostP is true. Fix redirect to/from HTTP/HTTPS where + full URLs are used. + +2009-08-10 23:40 donb + + * packages/acs-subsite/tcl/: package-procs-oracle.xql, + package-procs-postgresql.xql, package-procs.tcl: + package_exec_plsql didn't work if the sql proc being called has a + parameter named "package_name"... + +2009-08-10 18:35 michaels + + * packages/acs-templating/tcl/richtext-procs.tcl: remove html + security check bypass for admins in the richtext validation per + OCT discussion + +2009-07-29 22:21 donb + + * packages/search/: search.info, tcl/apm-callback-procs.tcl, + tcl/search-init.tcl: Added a package instantiate callback so when + someone mounts "search", the search indexer is correctly started + up without a server restart being required. + +2009-07-24 14:12 victorg + + * packages/acs-templating/: acs-templating.info, + tcl/apm-callback-procs.tcl: Providing upgrade logic for removing + Xinha invalid plugins from the parameter XinhaDefaultPlugins. + +2009-07-22 20:47 emmar + + * packages/acs-subsite/acs-subsite.info: Fix dependencies and their + version + +2009-07-21 22:14 emmar + + * packages/acs-templating/tcl/date-procs.tcl: Localized default + format for date widget + +2009-07-20 21:29 emmar + + * packages/acs-templating/tcl/richtext-procs.tcl: Close LABEL tag + before adding the Format and Spellcheck widgets. This HTML should + be build in the template rather than in the rendering proc. Each + widget should be computed separately. + +2009-07-20 12:24 emmar + + * packages/acs-content-repository/: acs-content-repository.info, + sql/common/mime-type-data.sql, tcl/apm-callback-procs.tcl: + Implements TIP #135 (OOXML formats) + +2009-07-20 09:32 emmar + + * packages/acs-core-docs/www/individual-programs.html: Fix Tcl + version + +2009-07-20 08:42 emmar + + * packages/acs-core-docs/www/xml/install-guide/software.xml: Fix + Tcl version + +2009-07-17 11:48 emmar + + * packages/: acs-admin/acs-admin.info, + acs-api-browser/acs-api-browser.info, + acs-authentication/acs-authentication.info, + acs-automated-testing/acs-automated-testing.info, + acs-bootstrap-installer/acs-bootstrap-installer.info, + acs-content-repository/acs-content-repository.info, + acs-core-docs/acs-core-docs.info, acs-kernel/acs-kernel.info, + acs-lang/acs-lang.info, acs-mail-lite/acs-mail-lite.info, + acs-messaging/acs-messaging.info, + acs-reference/acs-reference.info, + acs-service-contract/acs-service-contract.info, + acs-subsite/acs-subsite.info, acs-tcl/acs-tcl.info, + acs-templating/acs-templating.info, + acs-translations/acs-translations.info, + intermedia-driver/intermedia-driver.info, + notifications/notifications.info, + openacs-default-theme/openacs-default-theme.info, + ref-timezones/ref-timezones.info, search/search.info, + tsearch2-driver/tsearch2-driver.info: Bumped version to 5.5.1d1 + +2009-07-14 11:44 emmar + + * packages/notifications/: + catalog/notifications.en_US.ISO-8859-1.xml, + catalog/notifications.es_ES.ISO-8859-1.xml, + tcl/notification-procs.tcl, www/manage.adp, www/manage.tcl, + www/request-change-frequency.adp, + www/request-change-frequency.tcl, www/request-new.adp, + www/request-new.tcl: Localization (level AA requirement) + +2009-07-14 09:47 emmar + + * packages/acs-subsite/: catalog/acs-subsite.en_US.ISO-8859-1.xml, + catalog/acs-subsite.es_ES.ISO-8859-1.xml, + www/shared/whos-online.adp, www/shared/whos-online.tcl: + Localization + +2009-07-06 11:17 emmar + + * packages/acs-core-docs/www/: database-management.html, + docbook-primer.html, install-next-nightly-vacuum.html, + install-openacs-delete-tablespace.html, + programming-with-aolserver.html, remote-postgres.html, + unix-installation.html: Regenerate HTML files after updating + variables values and the compatibility table + +2009-07-06 11:14 emmar + + * packages/acs-core-docs/www/: acs-admin.html, + acs-package-dev.html, acs-plat-dev.html, aolserver.html, + aolserver4.html, apm-design.html, apm-requirements.html, + automated-backup.html, automated-testing-best-practices.html, + backup-recovery.html, backups-with-cvs.html, + complete-install.html, configuring-configuring-packages.html, + configuring-configuring-permissions.html, + configuring-install-packages.html, + configuring-mounting-packages.html, credits.html, + cvs-guidelines.html, cvs-tips.html, db-api-detailed.html, + db-api.html, dev-guide.html, doc-standards.html, + eng-standards-constraint-naming.html, + eng-standards-filenaming.html, eng-standards-plsql.html, + eng-standards-versioning.html, ext-auth-requirements.html, + filename.html, form-builder.html, groups-design.html, + high-avail.html, how-do-I.html, i18n-convert.html, index.html, + individual-programs.html, install-cvs.html, + install-daemontools.html, install-full-text-search-openfts.html, + install-full-text-search-tsearch2.html, + install-next-add-server.html, install-next-backups.html, + install-openacs-keepalive.html, install-qmail.html, + install-redhat.html, install-steps.html, ix01.html, + kernel-doc.html, mac-installation.html, maint-performance.html, + maintenance-deploy.html, object-identity.html, + object-system-design.html, object-system-requirements.html, + objects.html, openacs-unpack.html, openacs.html, oracle.html, + packages.html, parties.html, + permissions-tediously-explained.html, permissions.html, + postgres.html, psgml-for-emacs.html, psgml-mode.html, + release-notes.html, releasing-openacs-core.html, + request-processor.html, requirements-template.html, + rp-design.html, security-notes.html, snapshot-backup.html, + style-guide.html, subsites.html, templates.html, + tutorial-database.html, tutorial-debug.html, + tutorial-newpackage.html, tutorial-pages.html, tutorial.html, + upgrade-4.5-to-4.6.html, upgrade-openacs-files.html, + upgrade-overview.html, variables.html: Updated with correct + variable values and last changes in the compatibility table + +2009-07-06 11:02 emmar + + * packages/acs-core-docs/www/xml/: variables.ent, + install-guide/compatibility.xml, install-guide/software.xml: + Updated the compatibility table. Set the variables according to + the last final release. Removed unused (and duplicated) file. + +
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/releasing-openacs-core.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html 17 Oct 2010 21:06:08 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html 11 Dec 2010 23:36:32 -0000 1.18 @@ -1,15 +1,15 @@ - -OpenACS Core and .LRN
Prev Chapter 16. Releasing OpenACS Next
OpenACS Core and .LRN
Update Translations. Section , “How to Update the translations”
Rebuild the Changelog. Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS 5.0.2:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME + +OpenACS Core and .LRN
Prev Chapter 15. Releasing OpenACS Next
OpenACS Core and .LRN
Update Translations. How to Update the translations
Rebuild the Changelog. Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS 5.0.2:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME cvs2cl -F oacs-5-0 --delta openacs-5-0-0-final:oacs-5-0 -f ChangeLog -cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent
Update Version Numbers. The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved.
.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.
Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number. -
Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml -
Regenerate all HTML docs
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml -make
Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number
Update version number and release date in all of the +cvs2cl -F oacs-5-0 --delta openacs-5-0-1-final:oacs-5-0 -f ChangeLog-recent
Update Version Numbers. The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved.
.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.
Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number. +
Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml +
Regenerate all HTML docs
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml +make
Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number
Update version number and release date in all of the core packages. Use /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/update-info.sh with the new version number and the release date as arguments. Run it from /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages - ./acs-core-docs/www/files/update-info 5.2.1 2006-01-16
Install a new site using the modified code and verify that the automated tests pass.
Commit changes to CVS
Tag the files in CVS. The steps to this point should have ensured that the head of the current branch contains the full set of code to release. Now we need to tag it as the code to be released.
Check out OpenACS Core. The files must be checked + ./acs-core-docs/www/files/update-info 5.2.1 2006-01-16
Install a new site using the modified code and verify that the automated tests pass.
Commit changes to CVS
Tag the files in CVS. The steps to this point should have ensured that the head of the current branch contains the full set of code to release. Now we need to tag it as the code to be released.
Check out OpenACS Core. The files must be checked out through a cvs account with write access and should be a checkout from the release branch. In this example, we are assuming this is being done as a local user on openacs.org (which make the @@ -18,10 +18,10 @@ mkdir dotlrn-packages cd dotlrn-packages cvs -d /dotlrn-cvsroot checkout -r dotlrn-2-0 dotlrn-all -
Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)
cd /var/tmp/openacs-4 +
Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)
cd /var/tmp/openacs-4 cvs tag -F openacs-5-0-0a1 cvs tag -F openacs-5-0-compat -
Branching
When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, cvs status -v somefile.
cvs tag -b oacs-5-0
If doing .LRN: Since the .LRN packages aren't all in one +
Branching
When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, cvs status -v somefile.
cvs tag -b oacs-5-0
If doing .LRN: Since the .LRN packages aren't all in one module, we iterate through all of the modules. Log in first (cvs login) so that you don't have to log in for each module.
cd /var/tmp/dotlrn-packages @@ -30,15 +30,15 @@
Note that for the compat tag we use the -F flag which will force the tag to the new version (just in case someone has created the tag already on another version). Excercise care when doing this since you don't want to inadvertently move a prior release tag. Also if the tagging goes horribly wrong - for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".
Apply the final tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply done on openacs.org:
cd /var/tmp + for some reason you can delete the tag via "cvs tag -d <symbolic_tag>".
Apply the final tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply done on openacs.org:
cd /var/tmp cvs -d /cvsroot checkout -r openacs-5-1-compat openacs-4 cd openacs-4 -cvs tag openacs-5-1-2-final
Make the tarball(s).
openacs-core.
Go to a new working space and export the tagged files.
mkdir /var/tmp/tarball +cvs tag openacs-5-1-2-final
Make the tarball(s).
openacs-core.
Go to a new working space and export the tagged files.
mkdir /var/tmp/tarball cd /var/tmp/tarball -cvs -d /cvsroot export -r openacs-5-0-0a1 acs-core
Generate the tarball.
cd /var/tmp/tarball +cvs -d /cvsroot export -r openacs-5-0-0a1 acs-core
Generate the tarball.
cd /var/tmp/tarball mv openacs-4 openacs-5.0.0a1 tar cz -f openacs-5.0.0a1.tar.gz openacs-5.0.0a1 -
dotlrn.
Go to a new working space and export the tagged +
dotlrn.
Go to a new working space and export the tagged files. (was getting errors here trying to use -d, so gave up and just moved things from openacs-4 to openacs at the end)
mkdir /var/tmp/dotlrn-tarball @@ -47,14 +47,14 @@ cd /var/tmp/dotlrn-tarball/openacs-4/packages cvs -d /cvsroot export -r openacs-5-0-0a1 dotlrn-prereq cvs -d /dotlrn-cvsroot export -r dotlrn-2-0-0a1 dotlrn-core -
Copy the dotlrn install.xml file, which controls +
Copy the dotlrn install.xml file, which controls which packages are installed on setup, to the root location:
cp /var/tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml \ /var/tmp/dotlrn-tarball/openacs-4 -
Generate the tarball
cd /var/tmp/dotlrn-tarball +
Generate the tarball
cd /var/tmp/dotlrn-tarball mv openacs-4 dotlrn-2.0.0a1 tar cz -f dotlrn-2.0.0a1.tar.gz dotlrn-2.0.0a1 -
Test the new tarball(s). Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass.
Update Web site. Update the different places on OpenACS.org where we track status.
Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones
Home page of openacs.org
Post a new news item
Clean Up. Clean up after yourself.
cd /var/tmp +
Test the new tarball(s). Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass.
Update Web site. Update the different places on OpenACS.org where we track status.
Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones
Home page of openacs.org
Post a new news item
Clean Up. Clean up after yourself.
cd /var/tmp rm -rf tarball dotlrn-tarball dotlrn-packages openacs-5.0.0a1 rm -rf /var/tmp/openacs-4
Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized). @@ -81,7 +81,7 @@ BASE=/var/tmp/release-$OACS_VERSION mkdir $BASE if [ ! -d $BASE ]; then - echo "Failed creating base dir $BASE" + echo "Failed creating base dir $BASE" exit 1 fi @@ -139,4 +139,4 @@ # Clean up after ourselves... cd $BASE && rm -rf dotlrn-tarball tarball openacs-4 dotlrn-packages -
($Id$)
Prev Home Next
Chapter 16. Releasing OpenACS Up How to Update the OpenACS.org repository
docs@openacs.org
View comments on this page at openacs.org +
($Id$)
Prev Home Next
Chapter 15. Releasing OpenACS Up How to Update the OpenACS.org repository
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/releasing-openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs.html,v diff -u -N -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/releasing-openacs.html 17 Oct 2010 21:06:08 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs.html 11 Dec 2010 23:36:32 -0000 1.27 @@ -1,2 +1,2 @@ - -Chapter 16. Releasing OpenACS
Prev Part IV. For OpenACS Platform Developers Next
Chapter 16. Releasing OpenACS
Table of Contents
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
Prev Home Next
External Authentication Requirements Up OpenACS Core and .LRN
docs@openacs.org
View comments on this page at openacs.org + +Chapter 15. Releasing OpenACS
Prev Part IV. For OpenACS Platform Developers Next
Chapter 15. Releasing OpenACS
Table of Contents
OpenACS Core and .LRN
How to Update the OpenACS.org repository
How to package and release an OpenACS Package
How to Update the translations
Prev Home Next
External Authentication Requirements Up OpenACS Core and .LRN
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/releasing-package.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-package.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/releasing-package.html 17 Oct 2010 21:06:08 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/releasing-package.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,5 +1,5 @@ - -How to package and release an OpenACS Package
Prev Chapter 16. Releasing OpenACS Next
How to package and release an OpenACS Package
In this example, we are packaging and releasing myfirstpackage as version 1.0.0, which is compatible with OpenACS 5.0.x.
Update the version number, release date, and package maturity of your package in the APM.
Make sure all changes are committed.
Tag the updated work.:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage + +How to package and release an OpenACS Package
Prev Chapter 15. Releasing OpenACS Next
How to package and release an OpenACS Package
In this example, we are packaging and releasing myfirstpackage as version 1.0.0, which is compatible with OpenACS 5.0.x.
Update the version number, release date, and package maturity of your package in the APM.
Make sure all changes are committed.
Tag the updated work.:
cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage cvs tag myfirstpackages-1-0-0-final cvs tag -F openacs-5-0-compat -
Done. The package will be added to the repository automatically. If the correct version does not show up within 24 hours, ask for help on the OpenACS.org development forum.
Prev Home Next
How to Update the OpenACS.org repository Up How to Update the translations
docs@openacs.org
View comments on this page at openacs.org +
Done. The package will be added to the repository automatically. If the correct version does not show up within 24 hours, ask for help on the OpenACS.org development forum.
Prev Home Next
How to Update the OpenACS.org repository Up How to Update the translations
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/remote-postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/remote-postgres.html 13 Sep 2009 23:54:41 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/remote-postgres.html 11 Dec 2010 23:36:32 -0000 1.11 @@ -1,12 +1,12 @@ - -Running a PostgreSQL database on another server
Prev Chapter 7. Database Management Next
Running a PostgreSQL database on another server
To run a database on a different machine than the + +Running a PostgreSQL database on another server
Prev Chapter 7. Database Management Next
Running a PostgreSQL database on another server
To run a database on a different machine than the webserver requires changes to the database configuration file and access control file, and to the OpenACS service's - configuration file.
Edit the database configuration file, which in a - Reference install is located at /usr/local/pgsql/data/postgresql.conf - and change
#tcpip_socket = false
to
tcpip_socket = true
Change the access control file for the database to + configuration file.
Edit the database configuration file, which in a + Reference install is located at /usr/local/pgsql/data/postgresql.conf + and change
#tcpip_socket = false
to
tcpip_socket = true
Change the access control file for the database to permit specific remote clients to access. Access can be - controlled ... (add notes from forum post)
Change the OpenACS service's configuration file to + controlled ... (add notes from forum post)
Change the OpenACS service's configuration file to point to the remote database. Edit - /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl and change
to
Prev Home Next
Chapter 7. Database Management Up Deleting a tablespace
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/request-processor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/request-processor.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/request-processor.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,44 +1,44 @@ - -The Request Processor
Prev Chapter 11. Development Reference Next
The Request Processor
By Pete Su
+ +The Request Processor
Prev Chapter 10. Development Reference Next
The Request Processor
By Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Overview
+
Overview
This document is a brief introduction to the OpenACS 5.6.0 Request Processor; -more details can be found in the OpenACS 4 Request Processor Design. Here we cover the high level concepts behind the +more details can be found in the OpenACS 4 Request Processor Design. Here we cover the high level concepts behind the system, and implications and usage for the application developer. -
Request Processor
+
Request Processor
The 5.6.0 Request Processor is a global filter and set of Tcl procs that respond to every incoming URL reaching the server. The following diagram summarizes the stages of the request processor assuming a URL -request like http://someserver.com/notes/somepage.adp. +request like http://someserver.com/notes/somepage.adp. -
+

Stage 1: Search Site Map
The first thing the RP does is to map the given URL to the appropriate physical directory in the filesystem, from which to serve content. We -do this by searching the site map data model (touched on in the Packages, and further -discussed in Writing OpenACS Application Pages). This data model maps URLs to objects representing +do this by searching the site map data model (touched on in the Packages, and further +discussed in Writing OpenACS Application Pages). This data model maps URLs to objects representing content, and these objects are typically package instances.
After looking up the appropriate object, the RP stores the URL, the ID of the object it found, and the package and package instance the object belongs to into the environment of the connection. This -environment can be queried using the ad_conn procedure, -which is described in detail in OpenACS 4 Request Processor Design. The page +environment can be queried using the ad_conn procedure, +which is described in detail in OpenACS 4 Request Processor Design. The page development tutorial shows you how to use this interface to make your pages aware of which instance was requested.
Stage 2: Authentication
Next, the Request Processor examines the request for session information. Session information is generally sent from the client -(the user's browser) to the server via cookies. The security/session handler is described in +(the user's browser) to the server via cookies. The security/session handler is described in detail in its own document. It examines the client request and either extracts or sets up new session tokens for the user.
Stage 3: Authorization
Next, the Request Processor checks if the user has appropriate access privileges to the requested part of the site. In OpenACS 5.6.0, access control -is dictated by the permissions system. In -this case, the RP checks if the user has "read" priviledges on the +is dictated by the permissions system. In +this case, the RP checks if the user has "read" priviledges on the object in the site map specified by the URL. This object is typically a package instance, but it could easily be something more granular, such as whehter the user can view a particular piece of content within @@ -47,82 +47,82 @@
Stage 4: URL Processing, File Search
Finally, the Request Processor finds the file we intend to serve, searching the filesystem to locate the actual file that corresponds to -an abstract URL. It searches for files with predefined "magic" -extensions, i.e. files that end with: .html, -.tcl and .adp. +an abstract URL. It searches for files with predefined "magic" +extensions, i.e. files that end with: .html, +.tcl and .adp.
If the RP can't find any matching files with the expected extensions, -it will look for virtual-url-handler files, or .vuh -files. A .vuh file will be executed as if it were a Tcl +it will look for virtual-url-handler files, or .vuh +files. A .vuh file will be executed as if it were a Tcl file, but with the tail end of the URL removed. This allows the code -in the .vuh file to act like a registered procedure for -an entire subtree of the URL namespace. Thus a .vuh file +in the .vuh file to act like a registered procedure for +an entire subtree of the URL namespace. Thus a .vuh file can be thought of as a replacement for filters and registered procs, except that they integrate cleanly and correctly with the RP's URL mapping mechanisms. The details of how to use these files are -described in OpenACS 4 Request Processor Design. +described in OpenACS 4 Request Processor Design.
Once the appropriate file is found, it is either served directly if it's static content, or sent to the template system or the standard Tcl interpreter if it's a dynamic page. -
Basic API
+
Basic API
Once the flow of control reaches a dynamic page, the Request Processor has populated the environment of the request with several pieces of useful information. The RP's environment is accessible through the -ad_conn interface, and the following calls should be +ad_conn interface, and the following calls should be useful to you when developing dynamic pages: -
[ad_conn user_id] +
[ad_conn user_id]
The ID of the user associated with this request. By convention this is zero if there is no user. -
[ad_conn session_id] +
[ad_conn session_id]
The ID of the session associated with this request. -
[ad_conn url] +
[ad_conn url]
The URL associated with the request. -
[ad_conn urlv] +
[ad_conn urlv]
The URL associated with the request, represented as a list instead of a single string. -
[ad_conn file] +
[ad_conn file]
The actual local filesystem path of the file that is being served. -
[ad_conn object_url] +
[ad_conn object_url]
If the URL refers to a site map object, this is the URL to the root of the tree where the object is mounted. -
[ad_conn package_url] +
[ad_conn package_url]
If the URL refers to a package instance, this is the URL to the root of the tree where the package is mounted. -
[ad_conn extra_url] +
[ad_conn extra_url]
If we found the URL in the site map, this is the tail of the URL following the part that matched a site map entry. -
[ad_conn object_id] +
[ad_conn object_id]
If the URL refers to a site map object, this is the ID of that object. -
[ad_conn package_id] +
[ad_conn package_id]
If the URL refers to a package instance, this is the ID of that package instance. -
[ad_conn package_key] +
[ad_conn package_key]
If the URL refers to a package instance, this is the unique key name of the package. -
[ad_conn path_info] +
[ad_conn path_info]
In a .vuh file, path_info is the trailing part of the URL not matched Index: openacs-4/packages/acs-core-docs/www/requirements-template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,8 +1,8 @@ - -System/Application Requirements Template
Prev Chapter 13. Documentation Standards Next
System/Application Requirements Template
By You
+ +System/Application Requirements Template
Prev Chapter 12. Documentation Standards Next
System/Application Requirements Template
By You
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Introduction
+
Introduction
Briefly explain to the reader what this document is for, whether it records the requirements for a new system, a client application, a toolkit subsystem, etc. Remember your audience: fellow programmers, @@ -11,74 +11,74 @@ everywhere, write clearly and precisely; for requirements documentation, write at a level that any intelligent layperson can understand. -
Vision Statement
+
Vision Statement
Very broadly, describe how the system meets a need of a business, group, the OpenACS as a whole, etc. Make sure that technical and non-technical readers alike would understand what the system would do and why it's useful. Whenever applicable, you should explicitly state what the business value of the system is. -
System/Application Overview
+
System/Application Overview
Discuss the high-level breakdown of the components that make up the system. You can go by functional areas, by the main transactions the system allows, etc.
You should also state the context and dependencies of the system here, e.g. if it's an application-level package for OpenACS 4, briefly describe how it uses kernel services, like permissions or subsites. -
Use-cases and User-scenarios
+
Use-cases and User-scenarios
Determine the types or classes of users who would use the system, and what their experience would be like at a high-level. Sketch what their experience would be like and what actions they would take, and how the system would support them. -
Optional: Competitive Analysis
+
Optional: Competitive Analysis
Describe other systems or services that are comparable to what you're building. If applicable, say why your implementation will be superior, where it will match the competition, and where/why it will lack existing best-of-breed capabilities. This section is also in the Design doc, so write about it where you deem most appropriate. -
Related Links
Include all pertinent links to supporting and related material, - such as:
System/Package "coversheet" - where all documentation for this software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one document
Test plan
Competitive system(s)
Requirements
+
Related Links
Include all pertinent links to supporting and related material, + such as:
System/Package "coversheet" - where all documentation for this software is linked off of
Design document
Developer's guide
User's guide
Other-cool-system-related-to-this-one document
Test plan
Competitive system(s)
Requirements
The main course of the document, requirements. Break up the requirements sections (A, B, C, etc.) as needed. Within each section, create a list denominated with unique identifiers that reflect any functional hierarchy present, e.g. 20.5.13. - for the first number, leave generous gaps on the first writing of requirements (e.g. 1, 10, 20, 30, 40, etc.) because you'll want to leave room for any missing key requirements that may arise. -
10.0 A Common Solution
+
10.0 A Common Solution
Programmers and designers should only have to learn a single system that serves as a UI substrate for all the functionally specific modules in the toolkit. -
10.0.1
+
10.0.1
The system should not make any assumptions about how pages should look or function. -
10.0.5
+
10.0.5
Publishers should be able to change the default presentation of any module using a single methodology with minimal exposure to code.
For guidelines writing requirements, take a - look - at the quality standards, along with a good example, such as Package Manager Requirements. + look + at the quality standards, along with a good example, such as Package Manager Requirements.
Besides writing requirements in natural language, consider using the following techniques as needed: -
Pseudocode - a quasi programming language, combining the +
Pseudocode - a quasi programming language, combining the informality of natural language with the strict syntax and control - structures of a programming language.
Finite State Machines - a hypothetical machine that can be in + structures of a programming language.
Finite State Machines - a hypothetical machine that can be in only one of a given number of states at any specific time. Useful to model situations that are rigidly deterministic, that is, any set of - inputs mathematically determines the system outputs.
Decision Trees and Decision Tables - similar to FSMs, but better - suited to handle combinations of inputs.
Flowcharts - easy to draw and understand, suited for event and - decision driven systems. UML is the industry standard here.
Entity-Relationship diagrams - a necessary part of Design + inputs mathematically determines the system outputs.
Decision Trees and Decision Tables - similar to FSMs, but better + suited to handle combinations of inputs.
Flowcharts - easy to draw and understand, suited for event and + decision driven systems. UML is the industry standard here.
Entity-Relationship diagrams - a necessary part of Design documents, sometimes a high-level ER diagram is useful for - requirements as well.
Optional: Implementation Notes
+ requirements as well.
Optional: Implementation Notes
Although in theory coding comes after design, which comes after requirements, we do not, and perhaps should not, always follow such a rigid process (a.k.a. the waterfall lifecyle). Often, there is a pre-existing system or prototype first, and thus you may want to write some thoughts on implementation, for aiding and guiding yourself or other programmers. -
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)
Prev Home Next
Detailed Design Documentation Template Up Chapter 14. Internationalization
docs@openacs.org
View comments on this page at openacs.org +
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.3 Edited further, incorporated feedback from Michael Yoon 9/05/2000 Kai Wu
0.2 Edited 8/22/2000 Kai Wu
0.1 Created 8/21/2000 Josh Finkler, Audrey McLoghlin
($Id$)
Prev Home Next
Using nXML mode in Emacs Up Chapter 13. Internationalization
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -N -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/rp-design.html 17 Oct 2010 21:06:08 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 11 Dec 2010 23:36:32 -0000 1.35 @@ -1,54 +1,54 @@ - -Request Processor Design
Prev Chapter 15. Kernel Documentation Next
Request Processor Design
By Rafael H. Schloming
+ +Request Processor Design
Prev Chapter 14. Kernel Documentation Next
Request Processor Design
By Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Essentials
OpenACS 4 Request Processor Requirements
-/packages/acs-tcl/tcl/request-processor-procs.tcl
-/packages/acs-tcl/tcl/request-processor-init.tcl
-/packages/acs-tcl/tcl/site-nodes-procs.tcl
-/packages/acs-tcl/tcl/site-nodes-init.tcl
-/packages/acs-kernel/sql/site-nodes-create.sql
Introduction
The request processor is the set of procs that responds to every HTTP +
Essentials
OpenACS 4 Request Processor Requirements
+/packages/acs-tcl/tcl/request-processor-procs.tcl
+/packages/acs-tcl/tcl/request-processor-init.tcl
+/packages/acs-tcl/tcl/site-nodes-procs.tcl
+/packages/acs-tcl/tcl/site-nodes-init.tcl
+/packages/acs-kernel/sql/site-nodes-create.sql
Introduction
The request processor is the set of procs that responds to every HTTP request made to the OpenACS. The request processor must authenticate the connecting user, and make sure that he is authorized to perform the given request. If these steps succeed, then the request processor must locate the file that is associated with the specified URL, and serve the content it -provides to the browser.
Related Systems
Package Manager Design
Terminology
-pageroot -- Any directory that contains scripts and/or +provides to the browser.
Related Systems
Package Manager Design
Terminology
+pageroot -- Any directory that contains scripts and/or static files intended to be served in response to HTTP requests. A typical -OpenACS installation is required to serve files from multiple pageroots.
global pageroot -(/var/lib/aolserver/servicename/www) -- Files appearing under +OpenACS installation is required to serve files from multiple pageroots.
global pageroot +(/var/lib/aolserver/servicename/www) -- Files appearing under this pageroot will be served directly off the base url -http://www.servicename.com/
package root -(/var/lib/aolserver/servicename/packages) -- Each subdirectory of +http://www.servicename.com/
package root +(/var/lib/aolserver/servicename/packages) -- Each subdirectory of the package root is a package. A typical OpenACS installation will have several -packages.
package pageroot -(/var/lib/aolserver/servicename/packages/package_key/www) --- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is +packages.
package pageroot +(/var/lib/aolserver/servicename/packages/package_key/www) +-- This is the pageroot for the package_key package.
request environment (ad_conn) -- This is a global namespace containing variables associated with the current -request.
abstract URL -- A URL with no extension that doesn't -directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL +request.
abstract URL -- A URL with no extension that doesn't +directly correspond to a file in the filesystem.
abstract file or abstract path -- A URL that has been translated into a file system path (probably by prepending the appropriate pageroot), but still doesn't have any extension and so does -not directly correspond to a file in the filesystem.
concrete file or concrete path -- A file -or path that actually references something in the filesystem.
System Overview
Package Lookup
One of the first things the request processor must do is to determine +not directly correspond to a file in the filesystem.
concrete file or concrete path -- A file +or path that actually references something in the filesystem.
System Overview
Package Lookup
One of the first things the request processor must do is to determine which package instance a given request references, and based on this information, which pageroot to use when searching for a file to serve. During this process the request processor divides the URL into two pieces. The first portion identifies the package instance. The rest identifies the path into the package pageroot. For example if the news package is mounted on /offices/boston/announcements/, then a request for /offices/boston/announcements/index would be split into the -package_url (/offices/boston/announcements/), and the +package_url (/offices/boston/announcements/), and the abstract (no extension info) file path (index). The request processor must be -able to figure out which package_id is associated with a +able to figure out which package_id is associated with a given package_url, and package mountings must be persistent across server restarts and users must be able to manipulate the mountings on a live site, -therefore this mapping is stored in the database.
Authentication and Authorization
Once the request processor has located both the package_id and concrete -file associated with the request, authentication is performed by the session security system. After authentication has +therefore this mapping is stored in the database.
Authentication and Authorization
Once the request processor has located both the package_id and concrete +file associated with the request, authentication is performed by the session security system. After authentication has been performed the user is authorized to have read access for the given -package by the OpenACS 4 Permissions Design. +package by the OpenACS 4 Permissions Design. If authorization succeeds then the request is served, otherwise it is -aborted.
Concrete File Search
To actually serve a file, the request processor generates an ordered list +aborted.
Concrete File Search
To actually serve a file, the request processor generates an ordered list of abstract paths and searches each path for a concrete file. The first path searched is composed of the package pageroot with the extra portion of the URL appended. The second abstract path consists of the global pageroot with @@ -59,22 +59,22 @@ directory. Files take precedence over directory listings, so an index file in the global pageroot will be served instead of a directory listing in the package pageroot, even though the global pageroot is searched later. If a -file is found at any of the searched locations then it is served.
Virtual URL Handlers
If no file is found during the concrete file search, then the request -processor searches the filesystem for a virtual url handler -(.vuh) file. This file contains normal tcl code, and is in +file is found at any of the searched locations then it is served.
Virtual URL Handlers
If no file is found during the concrete file search, then the request +processor searches the filesystem for a virtual url handler +(.vuh) file. This file contains normal tcl code, and is in fact handled by the same extension handling procedure that handles .tcl files. The only way this file is treated differently is in how the request processor searches for it. When a lookup fails, the request processor generates each valid prefix of all the abstract paths considered in the concrete file search, and searches these prefixes in order from most specific to least specific for a matching .vuh file. If a file is found then the -ad_conn variable path_info is set to the portion of the url +ad_conn variable path_info is set to the portion of the url not matched by the .vuh script, and the script is sourced. This facility is intended to replace the concept of registered procs, since no special distinction is required between sitewide procs and package specific procs when using this facility. It is also much less prone to overlap and confusion than the use of registered procs, especially in an environment with -many packages installed.
Site Nodes
The request processor manages the mappings from URL patterns to package +many packages installed.
Site Nodes
The request processor manages the mappings from URL patterns to package instances with the site_nodes data model. Every row in the site_nodes table represents a fully qualified URL. A package can be mounted on any node in this data model. When the request processor performs a URL lookup, it @@ -87,16 +87,16 @@ performed by starting with the full request URI and successively stripping off the rightmost path components until a match is reached. This way the time required to lookup a URL is proportional to the length of the URL, not to the -number of entries in the mapping.
Request Environment
The request environment is managed by the procedure -ad_conn. Variables can be set and retrieved through use of +number of entries in the mapping.
Request Environment
The request environment is managed by the procedure +ad_conn. Variables can be set and retrieved through use of the ad_conn procedure. The following variables are available for public use. If the ad_conn procedure doesn't recognize a variable being passed to it for a lookup, it tries to get a value using ns_conn. This guarantees that -ad_conn subsumes the functionality of ns_conn.
Request processor
[ad_conn urlv] A list containing each element of the URL
[ad_conn url] The URL associated with the request.
[ad_conn query] The portion of the URL from the ? on (i.e. GET - variables) associated with the request.
[ad_conn file] The filepath including filename of the file being served
[ad_conn request] The number of requests since the server was last started
[ad_conn start_clicks] The system time when the RP starts handling the request

Session System Variables: set in -sec_handler, check security with ad_validate_security_info
[ad_conn session_id] The unique session_id coming from the sequence -sec_id_seq
[ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is -blank
[ad_conn sec_validated] This becomes "secure" when the connection uses SSL

Database API
[ad_conn db,handles] What are the list of handles available to AOL?
[ad_conn db,n_handles_used] How many database handles are currently used?
[ad_conn db,last_used] Which database handle did we use last?
[ad_conn db,transaction_level,$db] Specifies what transaction level we are in
[ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted

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

Packages
[ad_conn package_id] The package_id of the package associated with the URL.
[ad_conn package_url] The URL on which the package is mounted.

Miscellaneous
[ad_conn system_p] If true then the request has been made to one of the special directories +ad_conn subsumes the functionality of ns_conn.
Request processor
[ad_conn urlv] A list containing each element of the URL
[ad_conn url] The URL associated with the request.
[ad_conn query] The portion of the URL from the ? on (i.e. GET + variables) associated with the request.
[ad_conn file] The filepath including filename of the file being served
[ad_conn request] The number of requests since the server was last started
[ad_conn start_clicks] The system time when the RP starts handling the request

Session System Variables: set in +sec_handler, check security with ad_validate_security_info
[ad_conn session_id] The unique session_id coming from the sequence +sec_id_seq
[ad_conn user_id] User_id of a person if the person is logged in. Otherwise, it is +blank
[ad_conn sec_validated] This becomes "secure" when the connection uses SSL

Database API
[ad_conn db,handles] What are the list of handles available to AOL?
[ad_conn db,n_handles_used] How many database handles are currently used?
[ad_conn db,last_used] Which database handle did we use last?
[ad_conn db,transaction_level,$db] Specifies what transaction level we are in
[ad_conn db,db_abort_p,$dbh] Whether the transaction is aborted

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

Packages
[ad_conn package_id] The package_id of the package associated with the URL.
[ad_conn package_url] The URL on which the package is mounted.

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

Documentation
[ad_conn api_page_documentation_mode_p]
Prev Home Next
Request Processor Requirements Up Bootstrapping OpenACS
docs@openacs.org
View comments on this page at openacs.org +authorization has been performed.

Documentation
[ad_conn api_page_documentation_mode_p]
Prev Home Next
Request Processor Requirements Up Documenting Tcl Files: Page Contracts and Libraries
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v diff -u -N -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/rp-requirements.html 17 Oct 2010 21:06:08 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 11 Dec 2010 23:36:32 -0000 1.31 @@ -1,26 +1,26 @@ - -Request Processor Requirements
Prev Chapter 15. Kernel Documentation Next
Request Processor Requirements
By Rafael H. Schloming
+ +Request Processor Requirements
Prev Chapter 14. Kernel Documentation Next
Request Processor Requirements
By Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Introduction
The following is a requirements document for the OpenACS 4.0 request +
Introduction
The following is a requirements document for the OpenACS 4.0 request processor. The major enhancements in the 4.0 version include a more sophisticated directory mapping system that allows package pageroots to be mounted at arbitrary urls, and tighter integration with the database to allow -for flexible user controlled url structures, and subsites.
Vision Statement
Most web servers are designed to serve pages from exactly one static +for flexible user controlled url structures, and subsites.
Vision Statement
Most web servers are designed to serve pages from exactly one static pageroot. This restriction can become cumbersome when trying to build a web -toolkit full of reusable and reconfigurable components.
System Overview
The request processor's functionality can be split into two main -pieces.
Set up the environment in which a server side script expects to run. This -includes things like:
Initialize common variables associated with a request.
Authenticate the connecting party.
Check that the connecting party is authorized to proceed with the -request.
Invoke any filters associated with the request URI.
Determine to which entity the request URI maps, and deliver the content +toolkit full of reusable and reconfigurable components.
System Overview
The request processor's functionality can be split into two main +pieces.
Set up the environment in which a server side script expects to run. This +includes things like:
Initialize common variables associated with a request.
Authenticate the connecting party.
Check that the connecting party is authorized to proceed with the +request.
Invoke any filters associated with the request URI.
Determine to which entity the request URI maps, and deliver the content provided by this entity. If this entity is a proc, then it is invoked. If this entitty is a file then this step involves determining the file type, and the manner in which the file must be processed to produce content appropriate for the connecting party. Eventually this may also require determining the capabilities of the connecting browser and choosing the most appropriate form for the delivered content.
It is essential that any errors that occur during the above steps be -reported to developers in an easily decipherable manner.
Related Links
OpenACS 4 Request Processor Design
Requirements
10.0 Multiple Pageroots
10.10 Pageroots may be combined into one URL space.
10.20 Pageroots may be mounted at more than one location in the URL -space.
20.0 Application Context
20.10 The request processor must be able to determine a primary context +reported to developers in an easily decipherable manner.
Related Links
OpenACS 4 Request Processor Design
Requirements
10.0 Multiple Pageroots
10.10 Pageroots may be combined into one URL space.
10.20 Pageroots may be mounted at more than one location in the URL +space.
20.0 Application Context
20.10 The request processor must be able to determine a primary context or state associated with a pageroot based on it's location within the URL -space.
30.0 Authentication
30.10 The request processor must be able to verify that the connecting -browser actually represents the party it claims to represent.
40.0 Authorization
40.10 The request processor must be able to verify that the party the -connecting browser represents is allowed to make the request.
50.0 Scalability
Prev Home Next
Security Notes Up Request Processor Design
docs@openacs.org
View comments on this page at openacs.org +space.
30.0 Authentication
30.10 The request processor must be able to verify that the connecting +browser actually represents the party it claims to represent.
40.0 Authorization
40.10 The request processor must be able to verify that the party the +connecting browser represents is allowed to make the request.
50.0 Scalability
Prev Home Next
Security Notes Up Request Processor Design
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v diff -u -N -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/security-design.html 17 Oct 2010 21:06:08 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/security-design.html 11 Dec 2010 23:36:32 -0000 1.33 @@ -1,32 +1,32 @@ - -Security Design
Prev Chapter 15. Kernel Documentation Next
Security Design
By Richard Li and Archit Shah
+ +Security Design
Prev Chapter 14. Kernel Documentation Next
Security Design
By Richard Li and Archit Shah
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Essentials
OpenACS 4 Security Requirements
Introduction
+
Essentials
OpenACS 4 Security Requirements
Introduction
This document explains security model design for OpenACS 4. The security system with the OpenACS core must authenticate users in both secure and insecure environments. In addition, this subsystem provides sessions on top of the stateless HTTP protocol. This system also provides session level properties as a generic service to the rest of the OpenACS. -
The atoms used in the implementation:
Cookies: RFC 2109, HTTP +
The atoms used in the implementation:
Cookies: RFC 2109, HTTP State Management Mechanism
Cookies provide client side state. They are used to identify the user. Expiration of cookies is used to demark the end of a session. -
SHA: SHA-1
This secure hash algorithm enables us to digitally sign cookies +
SHA: SHA-1
This secure hash algorithm enables us to digitally sign cookies which guarantee that they have not been tampered with. It is also used to hash passwords. -
SSL with server authentication: SSL v3
SSL provides the client with a guarantee that the server is +
SSL with server authentication: SSL v3
SSL provides the client with a guarantee that the server is actually the server it is advertised as being. It also provides a secure transport. -
Design
Sessions
+
Design
Sessions
A session is defined as a series of clicks in which no two clicks are separated by more than some constant. This constant is the parameter SessionTimeout. Using the expiration time on the signatures of the signed cookies, we can verify when the cookie was issued and determine if two requests are part of the same session. It is important to note that the expiration time set in the cookie protocol is not trusted. Only the time inserted by the signed cookie mechanism is trusted. -
Authentication
+
Authentication
Two levels of access can be granted: insecure and secure. This grant lasts for the remainder of the particular session. Secure authentication tokens are only issued over secured connections. @@ -40,86 +40,86 @@ password can be sniffed from the system, after which the sniffer can apply for a secure authentication token. However, the basic architecture here lays the foundation for a secure system and can be easily adapted to a more secure -authentication system by forcing all logins to occur over HTTPS.
Details
The authentication system issues up to four signed cookies (see below), -with each cookie serving a different purpose. These cookies are:
name value max-age secure?
ad_session_id session_id,user_id SessionTimeout no
ad_user_login user_id Infinity no
ad_user_login_secure user_id,random Infinity yes
ad_secure_token session_id,user_id,random SessionLifetime yes
ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the -previous hit that received a cookie
is valid only for SessionTimeout seconds
is the canonical source for the session ID in ad_conn
ad_user_login
is used for permanent logins
ad_user_login_secure
is used for permanent secure logins
contains random garbage (ns_time) to prevent attack against the secure -hash
ad_secure_token -
is a session-level cookie from the browser's standpoint
its signature expires in SessionLifetime seconds
contains random garbage (ns_time) to prevent attack against the secure -hash
user_id is extraneous
Authentication Process
The Tcl function (sec_handler) is called by the request +authentication system by forcing all logins to occur over HTTPS.
Details
The authentication system issues up to four signed cookies (see below), +with each cookie serving a different purpose. These cookies are:
name value max-age secure?
ad_session_id session_id,user_id SessionTimeout no
ad_user_login user_id Infinity no
ad_user_login_secure user_id,random Infinity yes
ad_secure_token session_id,user_id,random SessionLifetime yes
ad_session_id
reissued on any hit separated by more than SessionRenew seconds from the +previous hit that received a cookie
is valid only for SessionTimeout seconds
is the canonical source for the session ID in ad_conn
ad_user_login
is used for permanent logins
ad_user_login_secure
is used for permanent secure logins
contains random garbage (ns_time) to prevent attack against the secure +hash
ad_secure_token +
is a session-level cookie from the browser's standpoint
its signature expires in SessionLifetime seconds
contains random garbage (ns_time) to prevent attack against the secure +hash
user_id is extraneous
Authentication Process
The Tcl function (sec_handler) is called by the request processor to authenticate the user. It first checks the -ad_session_id cookie. If there is no valid session in progress, -a new session is created with sec_setup_session. If the user -has permanent login cookies (ad_user_login and -ad_user_login_secure), then they are looked at to determine what +ad_session_id cookie. If there is no valid session in progress, +a new session is created with sec_setup_session. If the user +has permanent login cookies (ad_user_login and +ad_user_login_secure), then they are looked at to determine what user the session should be authorized as. Which cookie is examined is determined by whether or not the request is on a secure connection. If neither cookie is present, then a session is created without any -authentication. If the ad_session_id cookie is valid, the -user_id and session_id are pulled from it and put into ad_conn.
Authenticating Secure Connections
Secure connections are authenticated slightly differently. The function -ad_secure_conn_p is used to determine whether or not the URL +authentication. If the ad_session_id cookie is valid, the +user_id and session_id are pulled from it and put into ad_conn.
Authenticating Secure Connections
Secure connections are authenticated slightly differently. The function +ad_secure_conn_p is used to determine whether or not the URL being accessed is requires a secure login. The function simply checks if the -location begins with "https". (This is safe because the location is -set during the server initialization.)
If secure authentication is required, the ad_secure_token +location begins with "https". (This is safe because the location is +set during the server initialization.)
If secure authentication is required, the ad_secure_token cookie is checked to make sure its data matches the data stored in -ad_session_id. This is true for all pages except those that are +ad_session_id. This is true for all pages except those that are part of the login process. On these pages, the user can not yet have received -the appropriate ad_secure_token cookie, so no check against it +the appropriate ad_secure_token cookie, so no check against it is performed. The set of pages that skip that processing are determined by -determined by ad_login_page. Since the -ad_secure_token cookie is a session cookie, it is deleted by the +determined by ad_login_page. Since the +ad_secure_token cookie is a session cookie, it is deleted by the browser when the browser exits. Since an attacker could conceivably store the secure cookie in a replay attack (since expiration date is not validated), the data in the secure cookie is never used to set any data in ad_conn; user_id and session_id is set from the ad_session_id cookie.
It is important to note that the integrity of secure authentication rests -on the two Tcl function ad_secure_conn_p and -ad_login_page. If ad_secure_conn_p is false, secure -authentication is not required. If ad_login_page is false, -secure authentication is not required.
Login Process
The Tcl function ad_user_login does two things. First it +on the two Tcl function ad_secure_conn_p and +ad_login_page. If ad_secure_conn_p is false, secure +authentication is not required. If ad_login_page is false, +secure authentication is not required.
Login Process
The Tcl function ad_user_login does two things. First it performs the appropriate manipulation of the permanent login cookies, and then it updates the current session to reflect the new user_id. The -manipulation of the permanent login cookies is based on 3 factors:
previous login: other user, same user
permanent: was a permanent login requested?
secure: is this a secure connection?
+manipulation of the permanent login cookies is based on 3 factors:
previous login: other user, same user
permanent: was a permanent login requested?
secure: is this a secure connection?
Both the secure and insecure permanent login cookie can have one of three actions taken on it: -
set: cookie with no expiration is set
delete: set to "" with max age of 0, so it is expired -immediately
nothing: if the cookie is present, it remains
+
set: cookie with no expiration is set
delete: set to "" with max age of 0, so it is expired +immediately
nothing: if the cookie is present, it remains
The current state of the permanent login cookies is not taken into account when determining the appropriate action. -
previous login state permanent login requested secure connection action on insecure action on secure
other y y set set
same y y set set
other y n set delete
same y n set nothing
same n y nothing delete
other n y delete delete
other n n delete delete
same n n delete delete
ad_user_login -callssec_setup_session which actually calls -sec_generate_session_id_cookie to generate the +
previous login state permanent login requested secure connection action on insecure action on secure
other y y set set
same y y set set
other y n set delete
same y n set nothing
same n y nothing delete
other n y delete delete
other n n delete delete
same n n delete delete
ad_user_login +callssec_setup_session which actually calls +sec_generate_session_id_cookie to generate the new cookie with refer to the appropriate user_id. If the connection is secure -the ad_secure_token cookie is generated by a -call to sec_generate_secure_token_cookie. This +the ad_secure_token cookie is generated by a +call to sec_generate_secure_token_cookie. This function is only called from -sec_setup_session. Only -sec_handler and -sec_setup_session call -sec_generate_session_id_cookie. +sec_setup_session. Only +sec_handler and +sec_setup_session call +sec_generate_session_id_cookie. -
ad_user_logout logs the user out by deleting all 4 cookies -that are used by the authentication system.
Session Creation
The creation and setup of sessions is handled in -sec_setup_session, which is called either to -create a new session from sec_handler or from -ad_user_login when there is a change in +
ad_user_logout logs the user out by deleting all 4 cookies +that are used by the authentication system.
Session Creation
The creation and setup of sessions is handled in +sec_setup_session, which is called either to +create a new session from sec_handler or from +ad_user_login when there is a change in authorization level. The session management code must do two things: insure that session-level data does not float between users, and update the users table -which has columns for n_sessions, -last_visit, and -second_to_last_visit.
If there is no session already setup on this hit, a new session is -created. This happens when sec_setup_session is -called from sec_handler. If the login is from a +which has columns for n_sessions, +last_visit, and +second_to_last_visit.
If there is no session already setup on this hit, a new session is +created. This happens when sec_setup_session is +called from sec_handler. If the login is from a user to another user, a new session is created, otherwise, the current session is continued, simply with a higher authorization state. This allows for data associated with a session to be carried over when a user logs in.
The users table is updated by -sec_update_user_session_info which is called +sec_update_user_session_info which is called when an existing session is assigned a non-zero user_id, or when a session is -created with a non-zero user_id.
Passwords
ad_user_login assumes a password check has already been +created with a non-zero user_id.
Passwords
ad_user_login assumes a password check has already been performed (this will change in the future). The actual check is done by -ad_check_password. The database stores a salt and a hash of the +ad_check_password. The database stores a salt and a hash of the password concatenated with the salt. Updating the password -(ad_change_password) simply requires getting a new salt +(ad_change_password) simply requires getting a new salt (ns_time) concatenating and rehashing. Both the salt and the hashed password -field are updated.
Performance Enhancements
A session is labeled by a session_id sequence. Creating a session merely +field are updated.
Performance Enhancements
A session is labeled by a session_id sequence. Creating a session merely requires incrementing the session_id sequence. We do two things to improve the performance of this process. First, sequence values are precomputed and cached in the Oracle SGA. In addition, sequence values are incremented by 100 with each @@ -128,41 +128,41 @@ command per thread. This minimizes lock contention for the session ID sequence and also minimizes the number of DB requests, since each thread can allocate 100 sessions before requiring another DB hit. This cache works by keeping two -counters: tcl_max_value and -tcl_current_sequence_id. When -tcl_current_sequence_id is greater than -tcl_max_value a new value is requested from the -db and tcl_max_value is incremented by +counters: tcl_max_value and +tcl_current_sequence_id. When +tcl_current_sequence_id is greater than +tcl_max_value a new value is requested from the +db and tcl_max_value is incremented by 100. This is done on a per-thread basis so that no locking is required.
In addition, two procedures are dynamically generated at startup in -security-init.tcl. These two procedures use -ad_parameter to obtain the constant value of a given parameter; +security-init.tcl. These two procedures use +ad_parameter to obtain the constant value of a given parameter; these values are used to dynamically generate a procedure that returns a constant. This approach avoids (relatively) expensive calls to -ad_parameter in sec_handler. The impact of this +ad_parameter in sec_handler. The impact of this approach is that these parameters cannot be dynamically changed at runtime -and require a server restart.
Session Properties
+and require a server restart.
Session Properties
Session properties are stored in a single table that maps session IDs to named session properties and values. This table is periodically purged. For maximum performance, the table is created with nologging turned on and new extents are allocated in 50MB increments to reduce fragmentation. This table -is swept periodically by sec_sweep_session which removes +is swept periodically by sec_sweep_session which removes sessions whose first hit was more than SessionLifetime seconds (1 week by default) ago. Session properties are removed through that same process with cascading delete. -
Secure Session Properties
Session properties can be set as secure. In this case, -ad_set_client_property will fail if the connection is not -secure. ad_get_client_property will behave as if the property -had not been set if the property was not set securely.
Digital Signatures & Signed Cookies
+
Secure Session Properties
Session properties can be set as secure. In this case, +ad_set_client_property will fail if the connection is not +secure. ad_get_client_property will behave as if the property +had not been set if the property was not set securely.
Digital Signatures & Signed Cookies
Signed cookies are implemented using the generic secure digital signature mechanism. This mechanism guarantees that the user can not tamper with (or construct a value of his choice) without detection. In addition, it provides the optional facility of timing out the signature so it is valid for only a certain period of time. This works by simply including an expiration time as part of the value that is signed. -
The signature produced by ad_sign is the Tcl list of -token_id,expire_time,hash, where hash = +
The signature produced by ad_sign is the Tcl list of +token_id,expire_time,hash, where hash = SHA1(value,token_id,expire_time,secret_token). The secret_token is a forty character randomly generated string that is never sent to any user agent. The scheme consists of one table:
@@ -174,7 +174,7 @@ token_timestamp sysdate ); -
ad_verify_signature takes a value and a signature and +
ad_verify_signature takes a value and a signature and verifies that the signature was generated using that value. It works simply by taking the token_id and expire_time from the signature, and regenerating the hash using the supplied value and the secret_token corresponding to the @@ -186,111 +186,111 @@ signature, RFC 2109 specifies an optional max age that is returned to the client. For most cookies, this max age matches the expiration date of the cookie's signature. The standard specifies that when the max age is not -included, the cookie should be "discarded when the user agent -exits." Because we can not trust the client to do this, we must specify +included, the cookie should be "discarded when the user agent +exits." Because we can not trust the client to do this, we must specify a timeout for the signature. The SessionLifetime parameter is used for this purpose, as it represents the maximum possible lifetime of a single -session.
RFC 2109 specifies this optional "secure" parameter which -mandates that the user-agent use "secure means" to contact the +session.
RFC 2109 specifies this optional "secure" parameter which +mandates that the user-agent use "secure means" to contact the server when transmitting the cookie. If a secure cookie is returned to the client over https, then the cookie will never be transmitted over insecure -means.
Performance
Performance is a key goal of this implementation of signed cookies. To +means.
Performance
Performance is a key goal of this implementation of signed cookies. To maximize performance, we will use the following architecture. At the lowest -level, we will use the secret_tokens table as the canonical set +level, we will use the secret_tokens table as the canonical set of secret tokens. This table is necessary for multiple servers to maintain the same set of secret tokens. At server startup, a random subset of these secret tokens will be loaded into an ns_cache called -secret_tokens. When a new signed cookie is requested, a random +secret_tokens. When a new signed cookie is requested, a random token_id is returned out of the entire set of cached token_ids. In addition, a thread-persistent cache called tcl_secret_tokens is maintained on a per-thread basis.
Thus, the L2 ns_cache functions as a server-wide LRU cache that has a -minimum of 100 tokens in it. The cache has a dual purpose:
LRU cache Note that cache misses will only occur in the +minimum of 100 tokens in it. The cache has a dual purpose:
LRU cache Note that cache misses will only occur in the multiple server case, where a user agent may have a signature guaranteed by a -secret token issued by another server in the cluster.
signature cache Since the cache always maintains a +secret token issued by another server in the cluster.
signature cache Since the cache always maintains a minimum of 100 (set by a parameter) tokens populated at startup, it can be used to provide a random token for signature purposes.
The per-thread cache functions as an L1 cache that indiscriminately caches -all secret tokens. Note that this is not an LRU cache +all secret tokens. Note that this is not an LRU cache because there is no cache eviction policy per se -- the cache is cleared when the thread is destroyed by AOLserver. -
Security
Storing information on a client always presents an additional security +
Security
Storing information on a client always presents an additional security risk.
Since we are only validating the information and not trying to protect it as a secret, we don't use salt. Cryptographic salt is useful if you are -trying to protect information from being read (e.g., hashing passwords).
External SSL
+trying to protect information from being read (e.g., hashing passwords).
External SSL
External SSL mechanisms (firewall, dedicated hardware, etc.) can be used by creating two pools of AOLservers. In one pool the servers should be configured with the location parameter of nssock module set to -"https://yourservername". The servers in the other pool are +"https://yourservername". The servers in the other pool are configured as normal. The external SSL agent should direct SSL queries to the pool of secure servers, and it should direct non-SSL queries to the insecure servers. -
PRNG
+
PRNG
The pseudorandom number generator depends primarily on ns_rand, but is also seeded with ns_time and the number of page requests served since the server was started. The PRNG takes the SHA1(seed,ns_rand,ns_time,requests,clicks), and saves the first 40 bits as the seed for the next call to the PRNG in a thread-persistent global variable. The remaining 120 bits are rehashed to produce 160 bits of output. -
API
Login/Password
-ad_user_login user_id Logs the user in as user +
API
Login/Password
+ad_user_login user_id Logs the user in as user user_id. Optional forever flag determines whether or not permanent cookies are issued. -
ad_user_logout Logs the user out.
ad_check_password user_id password -returns 0 or 1.
ad_change_password user_id new -password
Digital Signatures and Signed Cookies
-ad_sign value Returns the digital signature of this +
ad_user_logout Logs the user out.
ad_check_password user_id password +returns 0 or 1.
ad_change_password user_id new +password
Digital Signatures and Signed Cookies
+ad_sign value Returns the digital signature of this value. Optional parameters allow for the specification of the secret used, the token_id used and the max_age for the signature. -ad_verify_signature value signatureReturns +ad_verify_signature value signatureReturns 1 or 0 indicating whether or not the signature matches the value specified. The secret parameter allows for specification of a different secret token to be used.
-ad_set_signed_cookie name data Sets a -signed cookie name with value data.
ad_get_signed_cookie name Gets the signed cookie +ad_set_signed_cookie name data Sets a +signed cookie name with value data.
ad_get_signed_cookie name Gets the signed cookie name. It raises an error if the cookie has been tampered with, or if -its expiration time has passed.
Session Properties
ad_set_client_property module name -data Sets a session property with name to value +its expiration time has passed.
Session Properties
ad_set_client_property module name +data Sets a session property with name to value data for the module module. The optional secure flag specifies the property should only be set if the client is authorized for -secure access (ad_secure_conn_p is true). There is also an optional -session_id flag to access data from sessions other than the current one.
ad_get_client_property module name -data Gets a session property with name to for the +secure access (ad_secure_conn_p is true). There is also an optional +session_id flag to access data from sessions other than the current one.
ad_get_client_property module name +data Gets a session property with name to for the module module. The optional secure flag specifies the property should only be retrieved if the client is authorized for secure access -(ad_secure_conn_p is true). There is also an optional -session_id flag to access data from sessions other than the current one.
Parameters
-SessionTimeout the maximum time in seconds (default 1200) -between requests that are part of the same session
SessionRenew the time in seconds (default 300) between +(ad_secure_conn_p is true). There is also an optional +session_id flag to access data from sessions other than the current one.
Parameters
+SessionTimeout the maximum time in seconds (default 1200) +between requests that are part of the same session
SessionRenew the time in seconds (default 300) between reissue of the session cookie. The minimum time that can pass after a session cookie is issued and before it is rejected is (SessionTimeout - SessionRenew). This parameter is used so that only one session_id cookie is set on a single page even if there are multiple images that are being -downloaded.
SessionLifetime the maximum possible lifetime of a -session in seconds (default 604800 = 7 days)
NumberOfCachedSecretTokens the number of secret tokens to -cache. (default 100)
Future Improvements
PRNG implementation
+downloaded.
SessionLifetime the maximum possible lifetime of a +session in seconds (default 604800 = 7 days)
NumberOfCachedSecretTokens the number of secret tokens to +cache. (default 100)
Future Improvements
PRNG implementation
The pseudorandom number generator used in the OpenACS is cryptographically weak, -and depends primarily on the randomness of the ns_rand function +and depends primarily on the randomness of the ns_rand function for its randomness. The implementation of the PRNG could be substantially improved. -
ad_user_login
+
ad_user_login
Add a password argument. It is non-optimal to make the default behavior to assume that the password was provided. -
Secret Tokens
+
Secret Tokens
The secret tokens pool is currently static. Ideally, this pool should be changed on a random but regular basis, and the number of secret_tokens increased as the number of users come to the web site.
Since the security of the entire system depends on the secret tokens pool, access to the secret tokens table should be restricted and accessible via a strict PL/SQL API. This can be done by revoking standard SQL permissions on the table for the AOLserver user and giving those permissions to a PL/SQL -package.
Robots
+package.
Robots
Deferring session to creation until the second hit from a browser seems to be a good way of preventing a lot of overhead processing for robots. If we do this, send cookie on first hit to test if cookies are accepted, then actually allocate on second hit. To preserve a record of the first hit of the session, just include any info about that first hit in the probe cookie sent. Look at how usca_p (user session cookie attempted) is used in OpenACS 3.x ecommerce. -
Client properties
+
Client properties
Currently there are only session properties. Because sessions have a maximum life, properties have a maximum life. It would be nice to expand the interface to allow for more persistent properties. In the past, there was a @@ -303,7 +303,7 @@ can be shared between concurrent sessions). The applications should have control over the deletion patterns, but should not be able to ignore the amount of data stored. -
Session information
+
Session information
It would be nice to keep some info about sessions: first hit, last hit, and URLs visited come to mind. Both logging and API for accessing this info would be nice. WimpyPoint is an application that already wants to use this @@ -312,7 +312,7 @@ analyzers (leaving it in server memory for applications to access). Putting it into the database at all is probably too big a hammer. Certainly putting it into the database on every hit is too big a hammer. -
Cookieless Sessions
Two trends drive the requirement for removing cookie dependence. WAP +
Cookieless Sessions
Two trends drive the requirement for removing cookie dependence. WAP browsers that do not have cookies, and publc perceptions of cookies as an invasion of privacy. The rely on the cookies mechanism in HTTP to distinguish one request from the next, and we trust it to force requests from the same @@ -321,31 +321,31 @@ in the URL and get it back on the next hit, the sessions system would continue to work.
Problems that arise: -
URL sharing could be dangerous. If I happen to be browsing Amazon +
URL sharing could be dangerous. If I happen to be browsing Amazon while logged in and I email a friend, he could conceivably receive it and follow it before my session has expired, gaining all of the privileges I -had.
User-entered URLs are harder to handler. If a user is in the middle of +had.
User-entered URLs are harder to handler. If a user is in the middle of a session and then types in the URL of some page, he could be kicked out of his session.
Both of these problems can be mitigated by doing detection of cookie support (see the section on robot detection). To help deal with the first problem, One could also make the restriction that secure sessions are only allowed over -cookied HTTP.
Vulnerability Analysis
+cookied HTTP.
Vulnerability Analysis
This section is not meant to be a comprehensive analysis of the vulnerabilities of the security system. Listed below are possible attack points for the system; these vulnerabilities are currently theoretical in nature. The major cryptographic vulnerability of the system stems from the pseudorandom nature of the random number generators used in the system. -
Cryptographically weak PRNG see -above.
Dependence on sample -SQL command The list of random token that are placed in the secret +
Cryptographically weak PRNG see +above.
Dependence on sample +SQL command The list of random token that are placed in the secret tokens cache is randomly chosen by the Oracle -sample command. This command may not be +sample command. This command may not be entirely random, so predicting the contents of the secret tokens cache may not -be as difficult as someone may anticipate.
Dependence on -ns_rand The actual token that is +be as difficult as someone may anticipate.
Dependence on +ns_rand The actual token that is chosen from the cache to be used is chosen by a call to -ns_rand.
ad_secure_conn_p +ns_rand.
ad_secure_conn_p As discussed above, the security of the secure sessions authentication system is dependent upon this function.
Prev Home Next
Security Requirements Up Security Notes
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/security-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/security-notes.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/security-notes.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,12 +1,12 @@ - -Security Notes
Prev Chapter 15. Kernel Documentation Next
Security Notes
By Richard Li
+ +Security Notes
Prev Chapter 14. Kernel Documentation Next
Security Notes
By Richard Li
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
The security system was designed for security. Thus, decisions requiring trade-offs between ease-of-use and security tend to result in a system that may not be as easy to use but is more secure. -
HTTPS and the sessions system
+
HTTPS and the sessions system
If a user switches to HTTPS after logging into the system via HTTP, the user must obtain a secure token. To insure security, the only way to @@ -21,21 +21,21 @@ issues a secure token, the method of authentication must be as strong as the method of transmission.
If a developer truly does not want such a level of protection, this system can be disabled via source code modification only. This can be accomplished -by commenting out the following lines in the sec_handler -procedure defined in security-procs.tcl:
+by commenting out the following lines in the sec_handler +procedure defined in security-procs.tcl:
if { [ad_secure_conn_p] && ![ad_login_page] } { - set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]] + set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]] if { [empty_string_p $s_token_cookie] || [string compare $s_token_cookie [lindex [sec_get_session_info $session_id] 2]] != 0 } { # token is incorrect or nonexistent, so we force relogin. - ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]" + ad_returnredirect "/register/index?return_url=[ns_urlencode [ad_conn url]?[ad_conn query]]" } }
The source code must also be edited if the user login pages have been moved out of an OpenACS system. This information is contained by the -ad_login_page procedure in security-procs.tcl:
+ad_login_page procedure in security-procs.tcl:
ad_proc -private ad_login_page {} { @@ -44,7 +44,7 @@ } { set url [ad_conn url] - if { [string match "*register/*" $url] || [string match "/index*" $url] } { + if { [string match "*register/*" $url] || [string match "/index*" $url] } { return 1 } @@ -54,5 +54,5 @@
The set of string match expressions in the procedure above should be extended appropriately for other registration pages. This procedure does not use -ad_parameter or regular expressions for performance reasons, as +ad_parameter or regular expressions for performance reasons, as it is called by the request processor.
($Id$)
Prev Home Next
Security Design Up Request Processor Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v diff -u -N -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/security-requirements.html 17 Oct 2010 21:06:08 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/security-requirements.html 11 Dec 2010 23:36:32 -0000 1.33 @@ -1,47 +1,47 @@ - -Security Requirements
Prev Chapter 15. Kernel Documentation Next
Security Requirements
By Richard Li
+ +Security Requirements
Prev Chapter 14. Kernel Documentation Next
Security Requirements
By Richard Li
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Introduction
+
Introduction
This document lists the requirements for the security system for the OpenACS. -
Vision Statement
+
Vision Statement
Virtually all web sites support personalized content based on user identity. The level of personalization may be as simple as displaying the name of the user on certain pages or can be as sophisticated as dynamically recommending sections of site that the user may be interested in based on prior browsing history. In any case, the user's identity must be validated and made available to the rest of the system. In addition, sites such as ecommerce vendors require that the user identity be securely validated. -
Security System Overview
+
Security System Overview
The security system consists of a number of subsystems. -
Signed Cookies
+
Signed Cookies
Cookies play a key role in storing user information. However, since they are stored in plaintext on a user's system, the validity of cookies is an important issue in trusting cookie information. Thus, we want to be able to validate a cookie, but we also want to validate the cookie without a database hit. -
10.0 Guaranteed Tamper Detection Any tampering of cookie -data should be easily detectable by the web server.
10.1 Performance and Scalability Validation and +
10.0 Guaranteed Tamper Detection Any tampering of cookie +data should be easily detectable by the web server.
10.1 Performance and Scalability Validation and verification of the cookie should be easily scalable and should not require a -database query on every hit.
Session Properties
+database query on every hit.
Session Properties
Applications should be able to store session-level properties in a database table. -
11.0 Storage API Session-level data should be accessible -via an API.
11.1 Purge Mechanism An efficient pruning mechanism +
11.0 Storage API Session-level data should be accessible +via an API.
11.1 Purge Mechanism An efficient pruning mechanism should be used to prevent old session level properties from filling up the -table.
Login
+table.
Login
The security system should support the concept of persistent user logins. This persistence takes several forms. -
12.0 Permanent Login Users should be able to maintain a -permanent user login so that they never need to type their password.
12.1 Session Login The security system should support +
12.0 Permanent Login Users should be able to maintain a +permanent user login so that they never need to type their password.
12.1 Session Login The security system should support the concept of a session, with authentication tokens that become invalid -after a certain period of time.
12.2 Session Definition A session is a sequence of +after a certain period of time.
12.2 Session Definition A session is a sequence of clicks by one user from one browser in which no two clicks are separated by -more than some constant (the session timeout).
12.3 Stateless The security system should not require +more than some constant (the session timeout).
12.3 Stateless The security system should not require state that is stored in the server. Required state may reside only in the user request (including cookies), and in the database. A single user should be able to log in to the system even if the user is sent to a different -AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store -passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL +AOLserver for each step of the login process (e.g., by a load balancer).
12.4 Secure The security system should not store +passwords in clear text in the database.
13.0 SSL Hardware The system must work when the SSL processing occurs outside of the web server (in specialized hardware, in a firewall, etc.).
Prev Home Next
OpenACS Internationalization Requirements Up Security Design
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/style-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/style-guide.html,v diff -u -N -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/style-guide.html 17 Oct 2010 21:06:08 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/style-guide.html 11 Dec 2010 23:36:32 -0000 1.26 @@ -1,7 +1,7 @@ - -OpenACS Style Guide
Prev Chapter 12. Engineering Standards Next
OpenACS Style Guide
+ +OpenACS Style Guide
Prev Chapter 11. Engineering Standards Next
OpenACS Style Guide
By Jeff Davis -
Motivation
+
Motivation
Why have coding standards for OpenACS? And if the code works why change it to adhere to some arbitrary rules?
@@ -10,7 +10,7 @@ lines of tcl code, about 460,000 lines of sql (in datamodel scripts and .xql files), about 80,000 lines of markup in .adp files, and about 100,000 lines of documentation. All told, just - about a million lines of "stuff". In terms of logical units + about a million lines of "stuff". In terms of logical units there are about 160 packages, 800 tables, 2,000 stored procedures, about 2,000 functional pages, and about 3,200 tcl procedures. @@ -26,10 +26,10 @@ over a long period by a lot of different people, OpenACS sometimes lacks this basic guessability and in the interest of bringing it into line we have advanced these guidelines. -
Commandments
+
Commandments
Here is a short list of the basic rules code contributed to OpenACS should follow... -
Follow the file naming and the package structure rules. +
Follow the file naming and the package structure rules. Some of the file naming rules are requirements for things to function correctly (for example data model creation scripts and tcl library files must be named properly to be @@ -38,25 +38,25 @@ if ignored won't break anything, but if you follow the rules people will be able to understand your package much more easily. -
Be literate in your programming. +
Be literate in your programming. Use ad_proc, ad_library, and ad_page_contract to provide documentation for your code, use comments on your datamodel, explain what things mean and how they should work. -
Test. +
Test. Write test cases for your API and data model; test negative cases as well as positive; document your tests. Provide tests for bugs which are not yet fixed. Test, Test, Test. -
Use namespaces. +
Use namespaces. For new packages choose a namespace and place all procedures in it and in oracle create packages. -
Follow the constraint naming and the PL/SQL and PL/pgSQL rules. +
Follow the constraint naming and the PL/SQL and PL/pgSQL rules. Naming constraints is important for upgradability and for consistency. Also, named constraints can be immensely helpful in developing good error handling. Following the PL/SQL and PL/pgSQL rules ensure that the procedures created can be handled similarly across both Oracle and PostgreSQL databases. -
Follow the code formatting guidelines. +
Follow the code formatting guidelines. The code base is very large and if things are formatted consistently it is easier to read. Also, if it conforms to the standard it won't be reformatted (which can mask @@ -65,27 +65,29 @@ easier to read and manage and does not force other programmers to decipher what tab settings you had in place in your editor. -
Use the standard APIs. +
Use the standard APIs. Don't reinvent the wheel. Prefer extending an existing core API to creating your own. If something in the core does not meet your particular needs it probably won't meet others as well and fleshing out the core API's makes the toolkit more useful for everyone and more easily extended. -
Make sure your datamodel create/drop scripts work. +
Make sure your datamodel create/drop scripts work. Break the table creation out from the package/stored - procedure creation and use create or - replace where possible so that scripts + procedure creation and use create or + replace where possible so that scripts can be sourced more than once. Make sure your drop script works if data has been inserted (and permissioned and notifications have been attached etc). -
Practice CVS/Bug Tracker Hygiene. +
Practice CVS/Bug Tracker Hygiene. Commit your work. commit with sensible messages and include patch and bug numbers in your commit messages.
Create bug tracker tickets for things you are going to work on yourself (just in case you don't get to it and to act as a pointer for others who might encounter the same problem). -
Solicit code reviews. +
Solicit code reviews. Ask others to look over your code and provide feedback and do the same for others. -
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 12/2003 Jeff Davis
($Id$)
Prev Home Next
Chapter 12. Engineering Standards Up Release Version Numbering
docs@openacs.org
View comments on this page at openacs.org +
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 12/2003 Jeff Davis
($Id$)
Prev Home Next
Chapter 11. Engineering Standards Up + CVS Guidelines +
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v diff -u -N -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/subsites-design.html 17 Oct 2010 21:06:08 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/subsites-design.html 11 Dec 2010 23:36:32 -0000 1.33 @@ -1,10 +1,10 @@ - -Subsites Design Document
Prev Chapter 15. Kernel Documentation Next
Subsites Design Document
By Rafael H. Schloming
+ +Subsites Design Document
Prev Chapter 14. Kernel Documentation Next
Subsites Design Document
By Rafael H. Schloming
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
*Note* This document has not gone through the any of the required QA process yet. It is being tagged as stable due to high -demand.
Essentials
OpenACS 4 Subsites Requirements
Introduction
An OpenACS 4 subsite is a managed suite of applications that work together for +demand.
Essentials
OpenACS 4 Subsites Requirements
Introduction
An OpenACS 4 subsite is a managed suite of applications that work together for a particular user community. This definition covers a very broad range of requirements: from a Geocities style homepage where a user can install whatever available application he wants (e.g. a single user could have their @@ -17,35 +17,35 @@ the Request Processor. Since the design and implementation directly associated with subsites is actually minimal, a discussion of subsites design is, in fact, a discussion of how core OpenACS 4 components implicitly support -subsites as a whole.
Historical Considerations
The subsites problem actually has several quite diverse origins. It was +subsites as a whole.
Historical Considerations
The subsites problem actually has several quite diverse origins. It was originally recognized as a toolkit feature in the form of -"scoping". The basic concept behind scoping was to allow one scoped +"scoping". The basic concept behind scoping was to allow one scoped OpenACS installation to behave as multiple unscoped OpenACS installations so that one OpenACS install could serve multiple communities. Each piece of application data -was tagged with a "scope" consisting of the (user_id, group_id, +was tagged with a "scope" consisting of the (user_id, group_id, scope) triple. In practice the highly denormalized data models that this method uses produced large amounts of very redundant code and in general made -it an extremely cumbersome process to "scopify" a module.
Before the advent of scoping there were several cases of client projects +it an extremely cumbersome process to "scopify" a module.
Before the advent of scoping there were several cases of client projects implementing their own version of scoping in special cases. One example being the wineaccess multi-retailer ecommerce. (Remember the other examples and get details. Archnet?, iluvcamp?)
The requirements of all these different projects vary greatly, but the one consistent theme among all of them is the concept that various areas of the web site have their own private version of a module. Because this theme is so dominant, this is the primary problem that the OpenACS4 implementation of -subsites addresses.
Competitive Analysis
...
Design Tradeoffs
The current implementation of package instances and subsites allows +subsites addresses.
Competitive Analysis
...
Design Tradeoffs
The current implementation of package instances and subsites allows extremely flexible URL configurations. This has the benefit of allowing multiple instances of the same package to be installed in one subsite, but can potentially complicate the process of integrating packages with each other since it is likely people will want packages that live at non standard URLs to operate together. This requirement would cause some packages to have more configuration options than normal since hard-coding the URLs would not -be feasible anymore.
API
This section will cover all the APIs relevant to subsites, and so will -consist of portions of the APIs of several systems.
Packages
The following package is provided for instantiation of packages. The +be feasible anymore.
API
This section will cover all the APIs relevant to subsites, and so will +consist of portions of the APIs of several systems.
Packages
The following package is provided for instantiation of packages. The apm_package.new function can be used to create a package of any type known to the system. The apm_package_types table can be queried for a list of installed packages. (See APM docs for more detail XXX: insert link here)
-create or replace package apm_package +create or replace package apm_package as function new ( @@ -98,9 +98,9 @@ end apm_package; / show errors -+ -
Site Nodes
This data model keeps track of what packages are being served from what +
Site Nodes
This data model keeps track of what packages are being served from what URLs. You can think of this as a kind of rp_register_directory_map on drugs. This table represents a fully hierarchical site map. The directory_p column indicates whether or not the node is a leaf node. The pattern_p column @@ -110,7 +110,7 @@ node URL. The object_id column contains the object mounted on the URL represented by the node. In most cases this will be a package instance.
-create table site_nodes ( +create table site_nodes ( node_id constraint site_nodes_node_id_fk references acs_objects (object_id) constraint site_nodes_node_id_pk @@ -134,11 +134,11 @@ object_id constraint site_nodes_object_id_fk references acs_objects (object_id) ); -+
The following package is provided for creating nodes.
-create or replace package site_node +create or replace package site_node as -- Create a new site node. If you set directory_p to be 'f' then you @@ -179,36 +179,36 @@ end; / show errors -+ -
Request Processor
Once the above APIs are used to create packages and mount them on a +
Request Processor
Once the above APIs are used to create packages and mount them on a specific site node, the following request processor APIs can be used to allow the package to serve content appropriate to the package instance.
-[ad_conn node_id] +[ad_conn node_id] [ad_conn package_id] [ad_conn package_url] [ad_conn subsite_id] [ad_conn subsite_url] -+ -
Data Model Discussion
The subsites implementation doesn't really have it's own data +
Data Model Discussion
The subsites implementation doesn't really have it's own data model, although it depends heavily on the site-nodes data model, and the APM -data model.
User Interface
The primary elements of the subsite user interface consist of the subsite +data model.
User Interface
The primary elements of the subsite user interface consist of the subsite admin pages. These pages are divided up into two areas: Group administration, and the site map. The group administration pages allow a subsite administrator to create and modify groups. The site map pages allow a subsite administrator to install, remove, configure, and control access to packages. The site map interface is the primary point of entry for most of the things a -subsite administrator would want to do.
Configuration/Parameters
...
Future Improvements/Areas of Likely Change
The current subsites implementation addresses the most basic functionality +subsite administrator would want to do.
Configuration/Parameters
...
Future Improvements/Areas of Likely Change
The current subsites implementation addresses the most basic functionality required for subsites. It is likely that as developers begin to use the subsites system for more sophisticated projects, it will become necessary to develop tools to help build tightly integrated packages. The general area -this falls under is "inter-package communication". An actual +this falls under is "inter-package communication". An actual implementation of this could be anything from clever use of configuration parameters to lots of package level introspection. Another area that is -currently underdeveloped is the ability to "tar up" and distribute +currently underdeveloped is the ability to "tar up" and distribute a particular configuration of site nodes/packages. As we build more fundamental applications that can be applied in more general areas, this feature will become more and more in demand since more problems will be -solvable by configuration instead of coding.
Authors
rhs@mit.edu
Prev Home Next
Subsites Requirements Up Package Manager Requirements
docs@openacs.org
View comments on this page at openacs.org +solvable by configuration instead of coding.
Authors
rhs@mit.edu
Prev Home Next
Subsites Requirements Up Package Manager Requirements
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 17 Oct 2010 21:06:08 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 11 Dec 2010 23:36:32 -0000 1.32 @@ -1,31 +1,31 @@ - -Subsites Requirements
Prev Chapter 15. Kernel Documentation Next
Subsites Requirements
By Rafael H. Schloming and Dennis Gregorovic
+ +Subsites Requirements
Prev Chapter 14. Kernel Documentation Next
Subsites Requirements
By Rafael H. Schloming and Dennis Gregorovic
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Introduction
The following is a requirements document for OpenACS 4 Subsites, part of the +
Introduction
The following is a requirements document for OpenACS 4 Subsites, part of the OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve multiple user communities, by enabling the suite of available OpenACS -applications to be customized for defined user communities.
Vision Statement
Many online communities are also collections of discrete subcommunities, +applications to be customized for defined user communities.
Vision Statement
Many online communities are also collections of discrete subcommunities, reflecting real-world relationships. For example, a corporate intranet/extranet website serves both units within the company (e.g., offices, departments, teams, projects) and external parties (e.g., customers, partners, vendors). Subsites enable a single OpenACS instance to provide each -subcommunity with its own "virtual website," by assembling OpenACS +subcommunity with its own "virtual website," by assembling OpenACS packages that together deliver a feature set tailored to the needs of the -subcommunity.
System Overview
The OpenACS subsite system allows a single OpenACS installation to serve multiple +subcommunity.
System Overview
The OpenACS subsite system allows a single OpenACS installation to serve multiple communities. At an implementation level this is primarily accomplished by -having an application "scope" its content to a particular package -instance. The request +having an application "scope" its content to a particular package +instance. The request processor then figures out which package_id a particular URL references -and then provides this information through the ad_conn api ([ad_conn -package_id], [ad_conn package_url]).
The other piece of the subsite system is a subsite package that provides -subsite admins a "control panel" for administering their subsite. +and then provides this information through the ad_conn api ([ad_conn +package_id], [ad_conn package_url]).
The other piece of the subsite system is a subsite package that provides +subsite admins a "control panel" for administering their subsite. This is the same package used to provide all the community core functionality -available at the "main" site which is in fact simply another -subsite.
Use-cases and User-scenarios
The Subsites functionality is intended for use by two different classes of -users:
Package programmers (referred to as 'the programmer') must -develop subcommunity-aware applications.
Site administrators (referred to as 'the administrator') use -subsites to provide tailored "virtual websites" to different +available at the "main" site which is in fact simply another +subsite.
Use-cases and User-scenarios
The Subsites functionality is intended for use by two different classes of +users:
Package programmers (referred to as 'the programmer') must +develop subcommunity-aware applications.
Site administrators (referred to as 'the administrator') use +subsites to provide tailored "virtual websites" to different subcommunities.
Joe Programmer is working on the forum package and wants to make it subsite-aware. Using [ad_conn package_id], Joe adds code that only displays forum messages associated with the current package instance. Joe is happy to @@ -40,18 +40,18 @@ http://www.company.com/offices/boston/forum, and similarly for the Austin office. At this point, the Boston and Austin office admins can customize the configurations for each of their forums, or they can just use the -defaults.
Related Links
OpenACS 4 Subsites Design Document
Test plan (Not available yet)
Requirements: Programmer's API
A subsite API is required for programmers to ensure their packages are -subsite-aware. The following functions should be sufficient for this:
10.10.0 Package creation
The system must provide an API call to create a package, and it must be -possible for the context (to which the package belongs) to be specified.
10.20.0 Package deletion
The system must provide an API call to delete a package and all related -objects in the subsite's context.
10.30.0 Object's package information
Given an object ID, the system must provide an API call to determine the -package (ID) to which the object belongs.
10.40.0 URL from package
Given a package (ID), the system must provide an API call to return the -canonical URL for that package.
10.50.0 Main subsite's package_id
The system must provide an API call to return a package ID corresponding -to the main subsite's package ID (the degenerate subsite).
Requirements: The User Interface
The Programmer's User Interface
There is no programmer's UI, other than the API described above.
The Administrator's User Interface
The UI for administrators is a set of HTML pages that are used to drive +defaults.
Related Links
OpenACS 4 Subsites Design Document
Test plan (Not available yet)
Requirements: Programmer's API
A subsite API is required for programmers to ensure their packages are +subsite-aware. The following functions should be sufficient for this:
10.10.0 Package creation
The system must provide an API call to create a package, and it must be +possible for the context (to which the package belongs) to be specified.
10.20.0 Package deletion
The system must provide an API call to delete a package and all related +objects in the subsite's context.
10.30.0 Object's package information
Given an object ID, the system must provide an API call to determine the +package (ID) to which the object belongs.
10.40.0 URL from package
Given a package (ID), the system must provide an API call to return the +canonical URL for that package.
10.50.0 Main subsite's package_id
The system must provide an API call to return a package ID corresponding +to the main subsite's package ID (the degenerate subsite).
Requirements: The User Interface
The Programmer's User Interface
There is no programmer's UI, other than the API described above.
The Administrator's User Interface
The UI for administrators is a set of HTML pages that are used to drive the underlying API for package instance management (i.e. adding, removing, or altering packages). It is restricted to administrators of the current subsite such that administrators can only manage their own subsites. Of course, -Site-Wide Administrators can manage all subsites.
20.10.0 Package creation
20.10.1 The administrator should be able to create a -package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate -any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no +Site-Wide Administrators can manage all subsites.
20.10.0 Package creation
20.10.1 The administrator should be able to create a +package and make it available at a URL underneath the subsite.
20.20.0 Package deactivation
20.20.1 The administrator should be able to deactivate +any package, causing it to be inaccessible to users.
20.20.5 Deactivating a package makes the package no longer accessible, but it does not remove data created within the context of -that package.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/18/2000 Dennis Gregorovic
0.2 Edited, reviewed 08/29/2000 Kai Wu
Prev Home Next
Groups Design Up Subsites Design Document
docs@openacs.org
View comments on this page at openacs.org +that package.
Revision History
Document Revision # Action Taken, Notes When? By Whom?
0.1 Creation 08/18/2000 Dennis Gregorovic
0.2 Edited, reviewed 08/29/2000 Kai Wu
Prev Home Next
Groups Design Up Subsites Design Document
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/subsites.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v diff -u -N -r1.45 -r1.46 --- openacs-4/packages/acs-core-docs/www/subsites.html 17 Oct 2010 21:06:08 -0000 1.45 +++ openacs-4/packages/acs-core-docs/www/subsites.html 11 Dec 2010 23:36:32 -0000 1.46 @@ -1,8 +1,8 @@ - -Writing OpenACS Application Pages
Prev Chapter 11. Development Reference Next
Writing OpenACS Application Pages
By Rafael H. Schloming and Pete Su
+ +Writing OpenACS Application Pages
Prev Chapter 10. Development Reference Next
Writing OpenACS Application Pages
By Rafael H. Schloming and Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Overview
+
Overview
In this document, we'll examine the user interface pages of the Notes application in more detail, covering two separate aspects of page development in OpenACS. First, we'll talk about the code needed to make @@ -11,8 +11,8 @@ form-based user interfaces in OpenACS. While these seem like unrelated topics, they both come up in the example page that we are going to look at, so it makes sense to address them at the same time. -
Application Instances and Subsites
-As you will recall from the packages tutorial, the Request +
Application Instances and Subsites
+As you will recall from the packages tutorial, the Request Processor (RP) and Package Manager (APM) allow site administrators to define an arbitrary mapping from URLs in the site to objects representing content. These objects may represent single @@ -22,63 +22,63 @@ particular URL. The tutorial also showed how a given URL is translated into a physical file to serve using the site map. We'll repeat this description here, assuming that you have mounted an -instance of Notes at the URL /notes as we did in the packages-example: -
-AOLserver receives your request for the URL /notes/somepage. -
+instance of Notes at the URL /notes as we did in the packages-example: +
+AOLserver receives your request for the URL /notes/somepage. +
This URL is passed to the request processor. -
+
The RP looks up the URL in the site map, and sees that the object -mounted at that location is an instance of the notes +mounted at that location is an instance of the notes application. -
+
The RP asks the package manager where in the file system the Notes package lives. In the standard case, this would be -ROOT/packages/notes. -
+ROOT/packages/notes. +
The RP translates the URL to serve a page relative to the page root of the application, which is -ROOT/packages/notes/www/. Therefore, the page that is -finally served is ROOT/packages/notes/www/hello.html, +ROOT/packages/notes/www/. Therefore, the page that is +finally served is ROOT/packages/notes/www/hello.html, which is what we wanted.
What is missing from this description is a critical fact for application developers: In addition to working out what file to serve, the RP also stores information about which package instance the file belongs to into the AOLserver connection environment. The following -ad_conn interfaces can be used to extract this +ad_conn interfaces can be used to extract this information: -
[ad_conn package_url]
+
[ad_conn package_url]
If the URL refers to a package instance, this is the URL to the root of the tree where the package is mounted. -
[ad_conn package_id]
+
[ad_conn package_id]
If the URL refers to a package instance, this is the ID of that package instance. -
[ad_conn package_key] +
[ad_conn package_key]
If the URL refers to a package instance, this is the unique key name of the package. -
[ad_conn extra_url] +
[ad_conn extra_url]
If we found the URL in the site map, this is the tail of the URL following the part that matched a site map entry.
In the Notes example, we are particularly interested in the -package_id field. If you study the data model and code, -you'll see why. As we said before in the data modeling tutorial, the Notes application points the -context_id of each Note object that it creates to the -package instance that created it. That is, the context_id -corresponds exactly to the package_id that comes in from +package_id field. If you study the data model and code, +you'll see why. As we said before in the data modeling tutorial, the Notes application points the +context_id of each Note object that it creates to the +package instance that created it. That is, the context_id +corresponds exactly to the package_id that comes in from the RP. This is convenient because it allows the administrator and the owner of the package to easily define access control policies for all the notes in a particular instance just my setting permissions on the package instance itself.
The code for adding and editing notes, in -notes/www/add-edit.tcl, shows how this works. At the top -of the page, we extract the package_id and use it to do +notes/www/add-edit.tcl, shows how this works. At the top +of the page, we extract the package_id and use it to do permission checks:
@@ -87,11 +87,11 @@ if {[info exists note_id]} { permission::require_permission -object_id $note_id -privilege write - set context_bar [ad_context_bar "Edit Note"] + set context_bar [ad_context_bar "Edit Note"] } else { permission::require_permission -object_id $note_id -privilege create - set context_bar [ad_context_bar "New Note"] + set context_bar [ad_context_bar "New Note"] }
@@ -100,7 +100,7 @@ for each action.
Later, when we actually create a note, the SQL that we run ensures -that the context_id is set the right way: +that the context_id is set the right way:
db_dml new_note { @@ -124,25 +124,25 @@ without generating a lot of duplicated HTML in your pages. It also encapsulates most of the common logic that we use in dealing with forms, which we'll discuss next. -
Using Forms
+
Using Forms
The forms API is pretty simple: You use calls in the -template::form namespace in your Tcl script to create +template::form namespace in your Tcl script to create form elements. The final template page then picks this stuff up and lays the form out for the user. The form is set up to route submit buttons and whatnot back to the same Tcl script that set up the form, so your Tcl script will also contain the logic needed to process these requests.
So, given this outline, here is a breakdown of how the forms code -works in the add-edit.tcl page. First, we create a form object -called new_note: +works in the add-edit.tcl page. First, we create a form object +called new_note:
template::form create new_note
All the forms related code in this page will refer back to this -object. In addition, the adp part of this page does +object. In addition, the adp part of this page does nothing but display the form object:
@@ -153,7 +153,7 @@ <hr> <center> -<formtemplate id="new_note"></formtemplate> +<formtemplate id="new_note"></formtemplate> </center>
@@ -176,31 +176,31 @@ }
-The if_request call returns true if we are asking the +The if_request call returns true if we are asking the page to render the form for the first time. That is, we are rendering -the form to ask the user for input. The tcl part of a +the form to ask the user for input. The tcl part of a form page can be called in 3 different states: the initial request, the initial submission, and the validated submission. These states reflect the typical logic of a forms based page in OpenACS: -
+
First render the input form. -
+
Next, control passes to a validation page that checks and confirms the inputs. -
+
Finally, control passes to the page that performs the update in the database.
-The rest of the if condition figures out if we are +The rest of the if condition figures out if we are creating a new note or editing an existing note. If -note_id is passed to us from the calling page, we assume +note_id is passed to us from the calling page, we assume that we are editing an existing note. In this case, we do a database query to grab the data for the note so we can populate the form with it.
The next two calls create form elements where the user can insert or edit the title and body of the Note. The interface to -template::element is pretty straightforward. +template::element is pretty straightforward.
Finally, the code at the bottom of the page performs the actual database updates when the form is submitted and validated: @@ -234,7 +234,7 @@ } } - ad_returnredirect "." + ad_returnredirect "." }
@@ -243,7 +243,7 @@ the HTML rendering, input validation and database transaction logic on your behalf. This means that you can write pages without duplicating all of that code in every set of pages that uses forms. -
How it All Fits
+
How it All Fits
To watch all of this work, use the installer to update the Notes package with the new code that you grabbed out of CVS or the package repository, mount an instance of Notes somewhere in your server and @@ -261,7 +261,7 @@ simple, and special purpose application to something that has the potential to be a very useful, general-purpose tool, complete with multi-user features, access control, and centralized administration. -
Summary
+
Summary
In OpenACS 5.6.0, application pages and scripts can be aware of the package instance, or subsite in which they are executing. This is a powerful general purpose mechanism that can be used to structure web services Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/tcl-doc.html 13 Sep 2009 23:54:41 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,8 +1,8 @@ - -Documenting Tcl Files: Page Contracts and Libraries
Prev Chapter 14. Kernel Documentation Next
Documenting Tcl Files: Page Contracts and Libraries
By Jon Salz on 3 July 2000
+ +Documenting Tcl Files: Page Contracts and Libraries
Prev Chapter 14. Kernel Documentation Next
Documenting Tcl Files: Page Contracts and Libraries
By Jon Salz on 3 July 2000
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl
The Big Picture
In versions of the OpenACS prior to 3.4, the standard +
Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl
The Big Picture
In versions of the OpenACS prior to 3.4, the standard place to document Tcl files (both Tcl pages and Tcl library files) was in a comment at the top of the file:
# @@ -12,48 +12,48 @@ # # author's email address, file creation date # -# $Id$ +# $Id$ #
In addition, the inputs expected by a Tcl page (i.e., form variables) would -be enumerated in a call to ad_page_variables, in effect, +be enumerated in a call to ad_page_variables, in effect, documenting the page's argument list.
The problem with these practices is that the documentation is only accessible by reading the source file itself. For this reason, ACS 3.4 introduces a new API for documenting Tcl files and, on top of that, a -web-based user interface for browsing the documentation:
ad_page_contract: Every Tcl page -has a contract that explicitly defines what inputs the page -expects (with more precision than ad_page_variables) and +web-based user interface for browsing the documentation:
ad_page_contract: Every Tcl page +has a contract that explicitly defines what inputs the page +expects (with more precision than ad_page_variables) and incorporates metadata about the page (what used to live in the top-of-page -comment). Like ad_page_variables, ad_page_contract -also sets the specified variables in the context of the Tcl page.
ad_library: To be +comment). Like ad_page_variables, ad_page_contract +also sets the specified variables in the context of the Tcl page.
ad_library: To be called at the top of every library file (i.e., all files in the -/tcl/ directory under the server root and -*-procs.tcl files under /packages/).
+/tcl/ directory under the server root and +*-procs.tcl files under /packages/).
This has the following benefits: -
Facilitates automatic generation of human-readable documentation.
Promotes security, by introducing a standard and automated way to check -inputs to scripts for correctness.
Allows graphical designers to determine easily how to customize -sites' UIs, e.g., what properties are available in templates.
Allows the request processor to be intelligent: a script can specify in +
Facilitates automatic generation of human-readable documentation.
Promotes security, by introducing a standard and automated way to check +inputs to scripts for correctness.
Allows graphical designers to determine easily how to customize +sites' UIs, e.g., what properties are available in templates.
Allows the request processor to be intelligent: a script can specify in its contract which type of abstract document it returns, and the request processor can transform it automatically into something useful to a particular user agent. (Don't worry about this for -now - it's not complete for ACS 3.4.)
ad_page_contract
-Currently ad_page_contract serves mostly as a replacement for -ad_page_variables. Eventually, it will be integrated closely +now - it's not complete for ACS 3.4.)
ad_page_contract
+Currently ad_page_contract serves mostly as a replacement for +ad_page_variables. Eventually, it will be integrated closely with the documents API so that each script's contract will document precisely the set of properties available to graphical designers in templates. (Document API integration is subject to change, so we don't decsribe it here yet; for now, you can just consider -ad_page_contract a newer, better, documented -ad_page_variables.) -
Let's look at an example usage of ad_page_contract:
+ad_page_contract a newer, better, documented +ad_page_variables.) +
Let's look at an example usage of ad_page_contract:
# /packages/acs-kernel/api-doc/www/package-view.tcl ad_page_contract { version_id:integer public_p:optional kind - { format "html" } + { format "html" } } { Shows APIs for a particular package. @@ -71,83 +71,83 @@
Note that: -
By convention, ad_page_contract should be preceded -by a comment line containing the file's path. The comment is on +
By convention, ad_page_contract should be preceded +by a comment line containing the file's path. The comment is on line 1, and the contract starts on line 2. -
ad_page_contract's first argument is -the list of expected arguments from the HTTP query (version_id, -public_p, kind, and format). Like -ad_page_variables, ad_page_contract sets the +
ad_page_contract's first argument is +the list of expected arguments from the HTTP query (version_id, +public_p, kind, and format). Like +ad_page_variables, ad_page_contract sets the corresponding Tcl variables when the page is executed. -
Arguments can have defaults, specified using the same -syntax as in the Tcl proc (a two-element list where the first +
Arguments can have defaults, specified using the same +syntax as in the Tcl proc (a two-element list where the first element is the parameter name and the second argument is the default value). -
Arguments can have flags, specified by following the +
Arguments can have flags, specified by following the name of the query argument with a colon and one or more of the following -strings (separated by commas):
optional: the query argument doesn't +strings (separated by commas):
optional: the query argument doesn't need to be provided; if it's not, the variable for that argument simply won't be set. For instance, if I call the script above without a -public_p in the query, then in the page body [info exists -public_p] will return 0. -
integer: the argument must be an integer -(ad_page_contract will fail and display and error if not). This +public_p in the query, then in the page body [info exists +public_p] will return 0. +
integer: the argument must be an integer +(ad_page_contract will fail and display and error if not). This flag, like the next, is intended to prevent clients from fudging query arguments to trick scripts into executing arbitrary SQL. -
sql_identifier: the argument must be a SQL -identifier (i.e., [string is wordchar $the_query_var] must +
sql_identifier: the argument must be a SQL +identifier (i.e., [string is wordchar $the_query_var] must return true). -
trim: the argument will be [string +
trim: the argument will be [string trim]'ed. -
multiple: the argument may be specified +
multiple: the argument may be specified arbitrarily many times in the query string, and the variable will be set to a list of all those values (or an empty list if it's unspecified). This is -analogous to the -multiple-list flag to -ad_page_variables, and is useful for handling form input -generated by <SELECT MULTIPLE> tags and checkboxes.
For instance, if dest_user_id:multiple is specified in the +analogous to the -multiple-list flag to +ad_page_variables, and is useful for handling form input +generated by <SELECT MULTIPLE> tags and checkboxes.
For instance, if dest_user_id:multiple is specified in the contract, and the query string is
?dest_user_id=913&dest_user_id=891&dest_user_id=9
-then $dest_user_id is set to [list 913 891 9]. +then $dest_user_id is set to [list 913 891 9]. -
array: the argument may be specified +
array: the argument may be specified arbitrarily many times in the query string, with parameter names with -suffixes like _1, _2, _3, etc. The +suffixes like _1, _2, _3, etc. The variable is set to a list of all those values (or an empty list if none are -specified).
For instance, if dest_user_id:array is specified in the +specified).
For instance, if dest_user_id:array is specified in the contract, and the query string is
?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9
-then $dest_user_id is set to [list 913 891 9].
You can provide structured, HTML-formatted documentation for your -contract. Note that format is derived heavily from Javadoc: a +then $dest_user_id is set to [list 913 891 9].
You can provide structured, HTML-formatted documentation for your +contract. Note that format is derived heavily from Javadoc: a general description of the script's functionality, followed optionally by -a series of named attributes tagged by at symbols (@). You are +a series of named attributes tagged by at symbols (@). You are encouraged to provide: -
A description of the functionality of the page. If the description +
A description of the functionality of the page. If the description contains more than one sentence, the first sentence should be a brief summary. -
A @param tag for each allowable query +
A @param tag for each allowable query argument. The format is
@param parameter-name description... -
An @author tag for each author. Specify the -author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the -script was first created.
A @cvs-id tag containing the page's CVS -identification string. Just use $Id: tcl-documentation.html,v 1.2 -2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will +
An @author tag for each author. Specify the +author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the +script was first created.
A @cvs-id tag containing the page's CVS +identification string. Just use $Id: tcl-documentation.html,v 1.2 +2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will substitute an appropriate string when you check the file in.
- These @ tags are optional, but highly recommended!
ad_library
-ad_library provides a replacement for the informal documentation + These @ tags are optional, but highly recommended!
ad_library
+ad_library provides a replacement for the informal documentation (described above) found at the beginning of every Tcl page. Instead of:
@@ -178,11 +178,11 @@
Note that format is derived heavily from Javadoc: a general description of the script's functionality, followed optionally by a series of named -attributes tagged by at symbols (@). HTML formatting is allowed. +attributes tagged by at symbols (@). HTML formatting is allowed. You are encouraged to provide: -
An @author tag for each author. Specify the -author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the -script was first created.
A @cvs-id tag containing the page's CVS -identification string. Just use $Id: tcl-documentation.html,v 1.2 -2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will +
An @author tag for each author. Specify the +author's name, followed his or her email address in parentheses.
A @creation-date tag indicating when the +script was first created.
A @cvs-id tag containing the page's CVS +identification string. Just use $Id: tcl-documentation.html,v 1.2 +2000/09/19 07:22:35 ron Exp $ when creating the file, and CVS will substitute an appropriate string when you check the file in.
($Id$)
Prev Home Next
Request Processor Design Up Bootstrapping OpenACS
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/templates.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/templates.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,8 +1,8 @@ - -Using Templates in OpenACS
Prev Chapter 11. Development Reference Next
Using Templates in OpenACS
By Pete Su
+ +Using Templates in OpenACS
Prev Chapter 10. Development Reference Next
Using Templates in OpenACS
By Pete Su
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Overview
+
Overview
The OpenACS Template System (ATS) is designed to allow developers to cleanly separate application logic from display logic. The intent is to have all of the logic related to @@ -13,12 +13,12 @@ graphic designers to work more independently.
In ATS, you write two files for every user-visible page in the -system. One is a plain .tcl file and the other is a -special .adp file. The .tcl file runs a +system. One is a plain .tcl file and the other is a +special .adp file. The .tcl file runs a script that sets up a set of name/value bindings that we call data -sources. These data sources are generally the results of Tcl and/or database queries +sources. These data sources are generally the results of Tcl and/or database queries or some combination thereof. The template system automatically makes -them available to the .adp file, or the display part of +them available to the .adp file, or the display part of the template, which is written in a combination of HTML, special template related tags, and data source substitutions.
@@ -29,7 +29,7 @@ actually add notes to the database, how to provide a separate instance of the Notes application to every user and how to design appropriate access control policies for the system. -
Entering Notes
+
Entering Notes
In order for the Notes application to be useful, we have to allow users to enter data into the database. Typically, this takes two pages: one that displays a form for data entry, and another page that @@ -39,10 +39,10 @@ the system since we won't be displaying much data, but we'll cover more on that end later.
-The .tcl file for the form entry template is pretty +The .tcl file for the form entry template is pretty simple. Here, the only thing we need from the database is a new ID for the note object to be inserted. Open up a file called -note-add.tcl in the ROOT/packages/notes/www +note-add.tcl in the ROOT/packages/notes/www directory, and put the following code in it:
@@ -69,74 +69,74 @@ where forum_id = :user_id } -set page_title "Add a note for $user_name" -set submit_label "Add" -set target "note-add-2" +set page_title "Add a note for $user_name" +set submit_label "Add" +set target "note-add-2" set note_id [db_nextval acs_object_id_seq] -ad_return_template "note-add" +ad_return_template "note-add"
Some things to note about this code: -
-The procedure ad_page_contract is -always the first thing a .tcl file calls, if it's under +
+The procedure ad_page_contract is +always the first thing a .tcl file calls, if it's under the www/ directory (i.e. not a Tcl library file). It does validation of input values from the HTTP request (i.e. form variables) and in -this case, the -properties clause is used to set up the -data sources that we will ship over to the .adp part of +this case, the -properties clause is used to set up the +data sources that we will ship over to the .adp part of the page. In this case, we only use the simplest possible kind of data -source, called a onevalue, which hold just a single +source, called a onevalue, which hold just a single string value. Later on, we'll see how to use more powerful kinds of data sources for representing multiple rows from an SQL query. You also include overall documentation for the page in the contract, and OpenACS has automatic tools that extract this documentation and make it browsable. -
-After being declared in the ad_page_contract, each +
+After being declared in the ad_page_contract, each property is just a simple Tcl variable. The template system passes the -final value of the variable to the .adp template when the -.tcl file is processed. -
-The call ad_return_template tells the template system -what .adp template page to fetch to display the +final value of the variable to the .adp template when the +.tcl file is processed. +
+The call ad_return_template tells the template system +what .adp template page to fetch to display the properties that have been processed. By default, the template system -will look for a file by the same name as the .tcl file -that just ran, but with an .adp extension. +will look for a file by the same name as the .tcl file +that just ran, but with an .adp extension.
-Next we write the corresponding .adp page. This page +Next we write the corresponding .adp page. This page outputs HTML for the form, and also contains placeholders whose values -are substituted in from the properties set up by the .tcl -file. Create a file called note-add.adp in your editor, +are substituted in from the properties set up by the .tcl +file. Create a file called note-add.adp in your editor, and insert this text:
-<master src="master"> -<property name="title">@page_title@</property> -<property name="context_bar">@context_bar@</property> +<master src="master"> +<property name="title">@page_title@</property> +<property name="context_bar">@context_bar@</property> <form action=@target@> <p>Title: -<input type="text" name="title" value=""> +<input type="text" name="title" value=""> </p> <p>Body: -<input type="text" name="title" value=""> +<input type="text" name="title" value=""> </p> <p> <center> -<input type=submit value="@submit_label@"> +<input type=submit value="@submit_label@"> </center> </p> </form>
The main point to note here is: when you want to substitute a value -into a page, you put the name of the data source between two "@" +into a page, you put the name of the data source between two "@" characters. Another point to note is the use of a master template: Master templates allow you do centralize display code that is used throughout an application in a single file. In this case, we intend to have a master template that does the standard page headers and footers -for us - create the master.adp file, which looks like +for us - create the master.adp file, which looks like this:
@@ -145,29 +145,29 @@ <%= [eval ad_context_bar $context_bar] %> <hr> <slave> -<br clear="all"> +<br clear="all"> <%= [ad_footer] %>
The main subtlety in this code is the inline Tcl code for running procs to build the header, footer, context bar, etc. Also, note the property substitutions that happen here, the values of which are set -up in the <property> tags in the slave page. +up in the <property> tags in the slave page.
After putting all these files into -ROOT/packages/notes/www, you should be able to go to -/notes/ URL for your server and see the input form. -
Summary
+ROOT/packages/notes/www, you should be able to go to +/notes/ URL for your server and see the input form. +
Summary
Templates separate application logic from display logic by requiring the developer to write pages in two stages, one file for database queries and application logic, and another for display. In OpenACS, the -logic part of the page is just a .tcl that sets up +logic part of the page is just a .tcl that sets up data sources that are used by the display part of the page. The -display part of the page is an .adp file with some +display part of the page is an .adp file with some special tags and notations for dealing with display logic and inserting properties into the text of the page. Later on we'll get into templates more deeply, and show how to use database queries as data sources. -
Documentation
-Templating system documentation +
Documentation
+Templating system documentation
($Id$)
Prev Home Next
The OpenACS Database Access API Up Groups, Context, Permissions
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html 17 Oct 2010 21:06:08 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,33 +1,33 @@ - -Admin Pages
Prev Chapter 10. Advanced Topics Next
Admin Pages
+ +Admin Pages
Prev Chapter 9. Advanced Topics Next
Admin Pages
There are at least two flavors of admin user interface: -
Admins use same pages as all other users, except +
Admins use same pages as all other users, except that they are offered admin links and buttons where appropriate. For example, if admins have privilege to bulk-delete items you could provide checkboxes next to every item seen on a list and the Delete Selected button on the bottom of the list. -
Dedicated admin pages. If you want admins to have +
Dedicated admin pages. If you want admins to have access to data that users aren't interested in or aren't allowed to see you will need dedicated admin pages. The conventional place to put those dedicated admin pages is in the - /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin directory. -
[$OPENACS_SERVICE_NAME www]$ mkdir admin
[$OPENACS_SERVICE_NAME www]$ cd admin
+
[$OPENACS_SERVICE_NAME www]$ mkdir admin
[$OPENACS_SERVICE_NAME www]$ cd admin
Even if your application doesn't need any admin pages of its own you will usually need at least one simple page with a bunch of links to existing administration UI such as Category Management or standard Parameters UI. Adding the link to Category Management is described in the section on categories. The listing below adds a link to the Parameters UI of our package. -
[$OPENACS_SERVICE_NAME admin]$ vi index.adp
+
[$OPENACS_SERVICE_NAME admin]$ vi index.adp
<master> -<property name="title">@title;noquote@</property> -<property name="context">@context;noquote@</property> +<property name="title">@title;noquote@</property> +<property name="context">@context;noquote@</property> -<ul class="action-links"> - <li><a href="@parameters_url@" title="Set parameters" class="action_link">Set parameters</a></li> +<ul class="action-links"> + <li><a href="@parameters_url@" title="Set parameters" class="action_link">Set parameters</a></li> </ul> -
[$OPENACS_SERVICE_NAME admin]$ vi index.tcl
+
[$OPENACS_SERVICE_NAME admin]$ vi index.tcl
ad_page_contract {} { } -properties { context_bar @@ -41,25 +41,25 @@ set context [list] -set title "Administration" +set title "Administration" -set parameters_url [export_vars -base "/shared/parameters" { +set parameters_url [export_vars -base "/shared/parameters" { package_id { return_url [ad_return_url] } }]
Now that you have the first admin page it would be nice to have a link to it somewhere in the system so that admins don't have to type in the -/admin every time they need to reach it. You +/admin every time they need to reach it. You could put a static link to the toplevel -index.adp but that might be distracting for +index.adp but that might be distracting for people who are not admins. Besides, some people consider it impolite to first -offer a link and then display a nasty "You don't have permission to access this -page" message. +offer a link and then display a nasty "You don't have permission to access this +page" message.
In order to display the link to the admin page only to users that have admin privileges add the following code near the top of -/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl: +/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl:
set package_id [ad_conn package_id] @@ -68,14 +68,14 @@ -privilege admin -party_id [ad_conn untrusted_user_id]] if { $admin_p } { - set admin_url "admin" + set admin_url "admin" set admin_title Administration }
In -/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp put: +/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp put:
<if @admin_p@ ne nil> - <a href="@admin_url@">@admin_title@</a> + <a href="@admin_url@">@admin_title@</a> </if>
Prev Home Next
Adding Comments Up Categories
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v diff -u -N -r1.33 -r1.34 --- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 17 Oct 2010 21:06:08 -0000 1.33 +++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 11 Dec 2010 23:36:32 -0000 1.34 @@ -1,5 +1,5 @@ - -Chapter 10. Advanced Topics
Prev Part III. For OpenACS Package Developers Next
Chapter 10. Advanced Topics
Table of Contents
Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics
by Joel Aufrecht
+ +Chapter 9. Advanced Topics
Prev Part III. For OpenACS Package Developers Next
Chapter 9. Advanced Topics
Table of Contents
Write the Requirements and Design Specs
Add the new package to CVS
OpenACS Edit This Page Templates
Adding Comments
Admin Pages
Categories
Profile your code
Prepare the package for distribution.
Distributing upgrades of your package
Notifications
Hierarchical data
Using .vuh files for pretty urls
Laying out a page with CSS instead of tables
Sending HTML email from your application
Basic Caching
Scheduled Procedures
Enabling WYSIWYG
Adding in parameters for your package
Writing upgrade scripts
Connect to a second database
Future Topics
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
This tutorial covers topics which are not essential to Index: openacs-4/packages/acs-core-docs/www/tutorial-caching.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-caching.html,v diff -u -N -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/tutorial-caching.html 17 Oct 2010 21:06:08 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/tutorial-caching.html 11 Dec 2010 23:36:32 -0000 1.10 @@ -1,11 +1,11 @@ - -Basic Caching
Prev Chapter 10. Advanced Topics Next
Basic Caching
Based on a post by Dave Bauer.
+ +Basic Caching
Prev Chapter 9. Advanced Topics Next
Basic Caching
Based on a post by Dave Bauer.
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Caching using the database API is described in the database API tutorial.
Caching using util_memoize
Implement your proc as my_proc_not_cached
Create a version of your proc called my_proc which wraps the non-cached version in the caching mechanism. In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on. The wrapper also uses the list command, to ensure that the arguments get passed correctly and to prevent commands passed in as arguments from being executed.
ad_proc my_proc {-foo} { +
Caching using the database API is described in the database API tutorial.
Caching using util_memoize
Implement your proc as my_proc_not_cached
Create a version of your proc called my_proc which wraps the non-cached version in the caching mechanism. In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on. The wrapper also uses the list command, to ensure that the arguments get passed correctly and to prevent commands passed in as arguments from being executed.
ad_proc my_proc {-foo} { Get a cached version of my_proc. } { return [util_memoize [list my_proc_not_cached -foo $foo]] -}
In your code, always call my_proc. There will be a seperate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached seperately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.
- The cached material will of course become obsolete over time. There are two ways to handle this.
Timed Expiration: pass in max_age to util_memoize. If the content is older than max_age, it will be re-generated.
- Direct Flushing. In any proc which invalidates the cached content, call util_memoize_flush my_proc_not_cached args.
If you are correctly flushing the cached value, then it will need to be reloaded. You may wish to pre-load it, so that the loading delay does not impact users. If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it. Or, you can call (and discard) it immediately after flushing it.
Prev Home Next
Sending HTML email from your application Up Scheduled Procedures
docs@openacs.org
View comments on this page at openacs.org +}
In your code, always call my_proc. There will be a seperate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached seperately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.
+ The cached material will of course become obsolete over time. There are two ways to handle this.
Timed Expiration: pass in max_age to util_memoize. If the content is older than max_age, it will be re-generated.
+ Direct Flushing. In any proc which invalidates the cached content, call util_memoize_flush my_proc_not_cached args.
If you are correctly flushing the cached value, then it will need to be reloaded. You may wish to pre-load it, so that the loading delay does not impact users. If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it. Or, you can call (and discard) it immediately after flushing it.
Prev Home Next
Sending HTML email from your application Up Scheduled Procedures
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-categories.html 17 Oct 2010 21:06:08 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-categories.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,13 +1,13 @@ - -Categories
Prev Chapter 10. Advanced Topics Next
Categories
extended by Nima Mazloumi
+ +Categories
Prev Chapter 9. Advanced Topics Next
Categories
extended by Nima Mazloumi
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
You can associate any ACS Object with one or more categories. In this tutorial we'll show how to equip your application with user interface to take advantage of the Categories service.
We'll start by installing the Categories service. Go to - /acs/admin and install it. This step + /acs/admin and install it. This step won't be necessary for the users of your applications because you'll create a dependency with the Package Manager which will take care that the Categories service always gets installed when your application gets @@ -16,7 +16,7 @@ Now that we have installed the Categories service we can proceed to modifying our application so that it can take advantage of it. We'll do it in three steps: -
+
The Categories service provides a mechanism to associate one or more category trees that are relevant to your application. One example of such tree is a tree of @@ -29,39 +29,39 @@
The way to achieve this is is to provide a link to the Category Management pages. Add the following snippet to your - /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl file:
- set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }] + set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }]
and the following snippet to your - /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp file:
- <a href="@category_map_url@"<#categories.Site_wide_Categories#</a> -
The link created by the above code (category_map_url) + <a href="@category_map_url@"<#categories.Site_wide_Categories#</a> +
The link created by the above code (category_map_url) will take the admin to the generic admin UI where he can pick category trees that make sense for this application. The same UI also includes facilities to build and edit category trees. Notice that the only parameter in this example is - package_id so that category trees + package_id so that category trees will be associated with the object identified by this - package_id. The categorization + package_id. The categorization service is actually more general than that: instead of - package_id you could use an ID of - some other object that serves as a "container" in your application. + package_id you could use an ID of + some other object that serves as a "container" in your application. For example, if your discussion forums application supports multiple - forums you would use forum_id to + forums you would use forum_id to associate category trees with just that one forum rather than the entire application instance. -
+
Once the category trees have been selected users need a way to categorize items. The easiest way to do this is by adding the - category widget type of the - form builder to note-edit.tcl. - To achieve this we'll need to use the -extend - switch to the ad_form command. Here's the "meat" of the - note-edit.tcl page:
+ category widget type of the + form builder to note-edit.tcl. + To achieve this we'll need to use the -extend + switch to the ad_form command. Here's the "meat" of the + note-edit.tcl page:
#extend the form to support categories set package_id [ad_conn package_id] @@ -72,117 +72,117 @@ } -new_data { .... category::map_object -remove_old -object_id $item_id $category_ids - db_dml insert_asc_named_object "insert into acs_named_objects (object_id, object_name, package_id) values ( :item_id, :title, :package_id)" + db_dml insert_asc_named_object "insert into acs_named_objects (object_id, object_name, package_id) values ( :item_id, :title, :package_id)" } -edit_data { .... - db_dml update_asc_named_object "update acs_named_objects set object_name = :title, package_id = :package_id where object_id = :item_id" + db_dml update_asc_named_object "update acs_named_objects set object_name = :title, package_id = :package_id where object_id = :item_id" category::map_object -remove_old -object_id $item_id $category_ids } -after_submit { - ad_returnredirect "." + ad_returnredirect "." ad_script_abort } -
While the category::ad_form::add_widgets proc is taking +
While the category::ad_form::add_widgets proc is taking care to extend your form with associated categories you need to ensure that your items are mapped to the corresponding category object yourself. Also since the categories package knows nothing from - your objects you have to keep the acs_named_objects table updated with + your objects you have to keep the acs_named_objects table updated with any changes taking place. We use the items title so that they are listed in the categories browser by title.
Make sure that you also delete these entries if your item is delete. Add this to your corresponding delete page:
- db_dml delete_named_object "delete from acs_named_objects where object_id = :item_id" -
note-edit.tcl requires a -note_id to determine which record + db_dml delete_named_object "delete from acs_named_objects where object_id = :item_id" +
note-edit.tcl requires a +note_id to determine which record should be deleted. It also looks for a confirmation variable, which should initially be absert. If it is absent, we create a form to allow the user to confirm the deletion. Note that in -entry-edit.tcl we used ad_form to access the Form Template +entry-edit.tcl we used ad_form to access the Form Template commands; here, we call them directly because we don't need the extra features of ad_form. The form calls itself, but with hidden variables carrying both -note_id and -confirm_p. If confirm_p is present, +note_id and +confirm_p. If confirm_p is present, we delete the record, set redirection back to the index, and abort -script execution.
The database commands:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?> +script execution.
The database commands:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql
<?xml version="1.0"?> <queryset> - <fullquery name="do_delete"> + <fullquery name="do_delete"> <querytext> select samplenote__delete(:note_id) </querytext> </fullquery> - <fullquery name="get_name"> + <fullquery name="get_name"> <querytext> select samplenote__name(:note_id) </querytext> </fullquery> -</queryset>
And the adp page:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.adp
<master> -<property name="title">@title@</property> -<property name="context">{@title@}</property> +</queryset>
And the adp page:
[$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.adp
<master> +<property name="title">@title@</property> +<property name="context">{@title@}</property> <h2>@title@</h2> -<formtemplate id="note-del-confirm"></formtemplate> +<formtemplate id="note-del-confirm"></formtemplate> </form>
The ADP is very simple. The -formtemplate tag outputs the HTML +formtemplate tag outputs the HTML form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few - samplenotes.
We will now make categories optional on package instance level and + samplenotes.
We will now make categories optional on package instance level and also add a configuration page to allow the package admin to enable/disable categories for his package. -
Go to the APM and create a number parameter with the name "EnableCategoriesP" - and the default value "0".
Add the following lines to your index.tcl:
+
Go to the APM and create a number parameter with the name "EnableCategoriesP" + and the default value "0".
Add the following lines to your index.tcl:
set return_url [ns_conn url] - set use_categories_p [parameter::get -parameter "EnableCategoriesP"] + set use_categories_p [parameter::get -parameter "EnableCategoriesP"]
Change your to this:
<a href=configure?<%=[export_url_vars return_url]%>>Configure</a> <if @use_categories_p@> - <a href="@category_map_url@"<#categories.Site_wide_Categories#</a> + <a href="@category_map_url@"<#categories.Site_wide_Categories#</a> </if>
Now create a configure page
ad_page_contract { This page allows an admin to change the categories usage mode. } { - {return_url ""} + {return_url ""} } - set title "Configure category mode" + set title "Configure category mode" set context [list $title] - set use_categories_p [parameter::get -parameter "EnableCategoriesP"] + set use_categories_p [parameter::get -parameter "EnableCategoriesP"] ad_form -name categories_mode -form { {enabled_p:text(radio) - {label "Enable Categories"} + {label "Enable Categories"} {options {{Yes 1} {No 0}}} {value $use_categories_p} } {return_url:text(hidden) {value $return_url}} - {submit:text(submit) {label "Set Mode"}} + {submit:text(submit) {label "Set Mode"}} } -on_submit { - parameter::set_value -parameter "EnableCategoriesP" -value $enabled_p + parameter::set_value -parameter "EnableCategoriesP" -value $enabled_p if {![empty_string_p $return_url]} { ns_returnredirect $return_url } }
and add this to its corresponding ADP page
<master> - <property name="title">@title@</property> - <property name="context">@context@</property> + <property name="title">@title@</property> + <property name="context">@context@</property> - <formtemplate id="categories_mode"></formtemplate> + <formtemplate id="categories_mode"></formtemplate>
Reference this page from your admin page
#TCL: set return_url [ad_conn url] #ADP: <a href=configure?<%=[export_url_vars return_url]%>>Configure</a> -
Change the note-edit.tcl:
+
Change the note-edit.tcl:
# Use Categories? - set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] + set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] if { $use_categories_p == 1 } { # YOUR NEW FORM DEFINITION } else { # YOUR OLD FORM DEFINITION } -
You can filter your notes using categories. The below example does not support multiple +
You can filter your notes using categories. The below example does not support multiple filters and displays a category in a flat format.
The first step is to - define the optional parameter category_id for - index.tcl:
+ define the optional parameter category_id for + index.tcl:
ad_page_contract { YOUR TEXT } { @@ -191,18 +191,18 @@ }
Now you have to check whether categories are enabled or not. If this is the case and a category id is passed you need to extend your sql select query to support filtering. One - way would be to extend the mfp::note::get proc to - support two more swiches -where_clause and - -from_clause.
- set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] + way would be to extend the mfp::note::get proc to + support two more swiches -where_clause and + -from_clause.
+ set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] if { $use_categories_p == 1 && [exists_and_not_null category_id] } { - set from_clause "category_object_map com, acs_named_objects nam" - set_where_clause "com.object_id = qa.entry_id and + set from_clause "category_object_map com, acs_named_objects nam" + set_where_clause "com.object_id = qa.entry_id and nam.package_id = :package_id and com.object_id = nam.object_id and - com.category_id = :category_id" + com.category_id = :category_id" ... @@ -224,14 +224,14 @@ if { ![empty_string_p $category_id] } { set category_name [category::get_name $category_id] if { [empty_string_p $category_name] } { - ad_return_exception_page 404 "No such category" "Site-wide \ - Category with ID $category_id doesn't exist" + ad_return_exception_page 404 "No such category" "Site-wide \ + Category with ID $category_id doesn't exist" return } # Show Category in context bar append context_base_url /cat/$category_id lappend context [list $context_base_url $category_name] - set type "all" + set type "all" } # Cut the URL off the last item in the context bar @@ -251,20 +251,20 @@ }
and to the corresponding index ADP page:
<if @use_categories_p@> - <multiple name="categories"> + <multiple name="categories"> <h2>@categories.tree_name@ - <group column="tree_id"> - <a href="@package_url@cat/@categories.category_id@?@YOURPARAMS@&category_id=@categories.category_id@">@categories.category_name@ + <group column="tree_id"> + <a href="@package_url@cat/@categories.category_id@?@YOURPARAMS@&category_id=@categories.category_id@">@categories.category_name@ </group> </multiple> - <a href="@package_url@view?@YOURPARAMS@">All Items</if> -
Finally you need a an index.vuh in your - www folder to rewrite the URLs correctly, Section , “Using .vuh files for pretty urls”:
+ <a href="@package_url@view?@YOURPARAMS@">All Items</if> +
Finally you need a an index.vuh in your + www folder to rewrite the URLs correctly, Using .vuh files for pretty urls:
set url /[ad_conn extra_url] if {[regexp {^/+cat/+([^/]+)/*} $url \ ignore_whole category_id]} { rp_form_put category_id $category_id } - rp_internal_redirect "/packages/YOURPACKAGE/www/index" + rp_internal_redirect "/packages/YOURPACKAGE/www/index"
Now when ever the user select a category only notes that belong to this category are displayed.
Prev Home Next
Admin Pages Up Profile your code
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-comments.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-comments.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-comments.html 17 Oct 2010 21:06:08 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-comments.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,14 +1,14 @@ - -Adding Comments
Prev Chapter 10. Advanced Topics Next
Adding Comments
You can track comments for any ACS Object. Here we'll track + +Adding Comments
Prev Chapter 9. Advanced Topics Next
Adding Comments
You can track comments for any ACS Object. Here we'll track comments for notes. On the note-edit.tcl/adp pair, which is used to display individual notes, we want to put a link to add comments at the bottom of the screen. If there are any comments, we want to show them.
First, we need to generate a url for adding comments. In note-edit.tcl:
- set comment_add_url "[general_comments_package_url]comment-add?[export_vars { + set comment_add_url "[general_comments_package_url]comment-add?[export_vars { { object_id $note_id } { object_name $title } - { return_url "[ad_conn url]?[ad_conn query]"} - }]" + { return_url "[ad_conn url]?[ad_conn query]"} + }]"
This calls a global, public tcl function that the general_comments package registered, to get its url. You then embed in that url the id of the note and its title, and set the @@ -19,5 +19,5 @@ show the contents of the comments, instead of just the fact that there are comments. Then you pass the note id, which is also the acs_object id.
We put our two new variables in the note-edit.adp - page.
<a href="@comment_add_url@">Add a comment</a> + page.
<a href="@comment_add_url@">Add a comment</a> @comments_html@
Prev Home Next
OpenACS Edit This Page Templates Up Admin Pages
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.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html 17 Oct 2010 21:06:08 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html 11 Dec 2010 23:36:32 -0000 1.11 @@ -1,32 +1,32 @@ - -Laying out a page with CSS instead of tables
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
Prev Chapter 9. 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%"> + <td valign="top" width="50%"> + <table class="element" border=0 cellpadding="0" cellspacing="0" width="100%"> <tr> - <td colspan=3 class="element-header-text"> + <td colspan=3 class="element-header-text"> <bold>Groups</bold> </td> </tr> <tr> - <td colspan=3 class="dark-line" height="0"><img src="/resources/acs-subsite/spacer.gif"></td></tr> + <td colspan=3 class="dark-line" height="0"><img src="/resources/acs-subsite/spacer.gif"></td></tr> <tr> - <td class="light-line" width="1"> - <img src="/resources/acs-subsite/spacer.gif" width="1"> + <td class="light-line" width="1"> + <img src="/resources/acs-subsite/spacer.gif" width="1"> </td> - <td class="element-text" width="100%"> - <table cellspacing="0" cellpadding="0" class="element-content" width="100%"> + <td class="element-text" width="100%"> + <table cellspacing="0" cellpadding="0" class="element-content" width="100%"> <tr> <td> - <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%"> + <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"> - <div class="portlet-wrap-shadow"> - <div class="portlet-wrap-bl"> - <div class="portlet-wrap-tr"> - <div class="portlet"> + 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"> + <div class="portlet"> <h2>Groups</h2> <ul> <li> - <a href="#">Class MBA 101</a>
If the CSS is removed from the file, it looks somewhat different:
Prev Home Next
Using .vuh files for pretty urls Up Sending HTML email from your application
docs@openacs.org
View comments on this page at openacs.org + <a href="#">Class MBA 101</a>
If the CSS is removed from the file, it looks somewhat different:
Prev Home Next
Using .vuh files for pretty urls Up Sending HTML email from your application
docs@openacs.org
View comments on this page at openacs.org 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.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 17 Oct 2010 21:06:08 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 11 Dec 2010 23:36:32 -0000 1.25 @@ -1,22 +1,22 @@ - -Add the new package to CVS
Prev Chapter 10. Advanced Topics Next
Add the new package to CVS
Before you do any more work, make sure that your work is - protected by putting it all into cvs. The cvs - add command is not recursive, so you'll have to - traverse the directory tree manually and add as you go. (More on - CVS)
[$OPENACS_SERVICE_NAME xml]$ cd .. -[$OPENACS_SERVICE_NAME doc]$ cd .. -[$OPENACS_SERVICE_NAME www]$ cd .. -[$OPENACS_SERVICE_NAME myfirstpackage]$ cd .. -[$OPENACS_SERVICE_NAME packages]$ cvs add myfirstpackage/ + +Add the new package to CVS
Prev Chapter 9. Advanced Topics Next
Add the new package to CVS
Before you do any more work, make sure that your work is + protected by putting it all into cvs. The cvs + add command is not recursive, so you'll have to + traverse the directory tree manually and add as you go. (More on + CVS)
[$OPENACS_SERVICE_NAME xml]$ cd .. +[$OPENACS_SERVICE_NAME doc]$ cd .. +[$OPENACS_SERVICE_NAME www]$ cd .. +[$OPENACS_SERVICE_NAME myfirstpackage]$ cd .. +[$OPENACS_SERVICE_NAME packages]$ cvs add myfirstpackage/ Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage added to the repository -[$OPENACS_SERVICE_NAME packages]$ cd myfirstpackage/ -[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs add www +[$OPENACS_SERVICE_NAME packages]$ cd myfirstpackage/ +[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs add www Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www added to the repository -[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www -[$OPENACS_SERVICE_NAME www]$ cvs add doc +[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www +[$OPENACS_SERVICE_NAME www]$ cvs add doc Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc added to the repository -[$OPENACS_SERVICE_NAME www]$ cd doc -[$OPENACS_SERVICE_NAME doc]$ cvs add * +[$OPENACS_SERVICE_NAME www]$ cd doc +[$OPENACS_SERVICE_NAME doc]$ cvs add * cvs add: cannot add special file `CVS'; skipping cvs add: scheduling file `admin-guide.html' for addition cvs add: scheduling file `bi01.html' for addition @@ -41,13 +41,13 @@ cvs add: scheduling file `user-interface.png' for addition Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc/xml added to the repository cvs add: use 'cvs commit' to add these files permanently -[$OPENACS_SERVICE_NAME doc]$ cd xml -[$OPENACS_SERVICE_NAME xml]$ cvs add Makefile index.xml +[$OPENACS_SERVICE_NAME doc]$ cd xml +[$OPENACS_SERVICE_NAME xml]$ cvs add Makefile index.xml cvs add: scheduling file `Makefile' for addition cvs add: scheduling file `index.xml' for addition cvs add: use 'cvs commit' to add these files permanently -[$OPENACS_SERVICE_NAME xml]$ cd ../../.. -[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs commit -m "new package" +[$OPENACS_SERVICE_NAME xml]$ cd ../../.. +[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs commit -m "new package" cvs commit: Examining . cvs commit: Examining www cvs commit: Examining www/doc @@ -59,4 +59,4 @@ initial revision: 1.1 done (many lines omitted) -[$OPENACS_SERVICE_NAME myfirstpackage]$
Figure 10.1. Upgrading a local CVS repository
Prev Home Next
Write the Requirements and Design Specs Up OpenACS Edit This Page Templates
docs@openacs.org
View comments on this page at openacs.org +[$OPENACS_SERVICE_NAME myfirstpackage]$
Figure 9.1. Upgrading a local CVS repository

Prev Home Next
Write the Requirements and Design Specs Up OpenACS Edit This Page Templates
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.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/tutorial-database.html 17 Oct 2010 21:06:08 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/tutorial-database.html 11 Dec 2010 23:36:32 -0000 1.42 @@ -1,44 +1,44 @@ - -Setting Up Database Objects
Prev Chapter 9. Development Tutorial Next
Setting Up Database Objects
by Joel Aufrecht
+ +Setting Up Database Objects
Prev Chapter 8. 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 - myfirstpackage/sql/ directory. All +
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 - myfirstpackage/sql/postgresql directory. + the myfirstpackage/sql/oracle or + myfirstpackage/sql/postgresql directory. Packages can support Oracle, PostgreSQL, or both. In this tutorial, we will be working with PostgreSQL
The first file will be - myfirstpackage-create.sql. The + myfirstpackage-create.sql. The package manager requires a file with the name - packagekey-create.sql, + packagekey-create.sql, which it will run automatically when the package in installed. This file should create all tables and views.
Our package is going to store all of its information in - one table. It takes more than just a CREATE - TABLE command, however, because we want to + one table. It takes more than just a CREATE + TABLE command, however, because we want to integrate our table with the OpenACS system. By making each record in our table an OpenACS object, we gain access to the permissions system and to services that integrate with OpenACS - objects, such as general-comments and - notification. The cost is + objects, such as general-comments and + notification. The cost is that our table creation code must include several functions, stored procedures, and is complicated (even for simple tables).
There are many kinds of OpenACS objects in the system. (You - can see them with the psql code: select object_type from - acs_object_types;.) One such object is the + can see them with the psql code: select object_type from + acs_object_types;.) One such object is the content_item, which is part of the content repository system. To use it, we will make our data objects children of the content_revision object, which is a child of content_item. Not only will we gain the benefits of both OpenACS Objects and content objects, we can also use some content - repository functions to simplify our database creation. (More - information about ACS Objects. More information about the + repository functions to simplify our database creation. (More + information about ACS Objects. More information about the Content Repository.) -
Figure 9.2. Tutorial Data Model
The top of each sql file has some +
Figure 8.2. Tutorial Data Model

The top of each sql file has some standard comments, including doc tags such as - @author which will be picked up + @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 + $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 8.3. The Database Creation Script
-- creation script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ @@ -56,13 +56,13 @@ -- necessary to work around limitation of content repository: select content_folder__register_content_type(-100,'mfp_note','t'); -
The creation script calls a function in PL/pgSQL (PL/pgSQL is a procedural language extention to sql), - content_type__create_type, which +

The creation script calls a function in PL/pgSQL (PL/pgSQL is a procedural language extention to sql), + content_type__create_type, which in turn creates the necessary database changes to support our data - object. Notice the use of "mfp." This is derived from "My - First Package" and ensures that our object is unlikely to conflict + 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 8.4. Database Deletion Script
-- drop script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ @@ -74,19 +74,19 @@ 't', 't' ); -
(like the creation script the drop script calls a PL/pgSQL function: content_type__drop_type
Run the create script manually to add your tables and functions.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql +

(like the creation script the drop script calls a PL/pgSQL function: content_type__drop_type
Run the create script manually to add your tables and functions.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql psql:myfirstpackage-create.sql:15: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'mfp_notes_pkey' for table 'mfp_notes' psql:myfirstpackage-create.sql:15: NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s) content_type__create_type --------------------------- 0 (1 row) -[$OPENACS_SERVICE_NAME postgresql]$
If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.
Once you get the same output as shown above, test the drop script:
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql +[$OPENACS_SERVICE_NAME postgresql]$
If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.
Once you get the same output as shown above, test the drop script:
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-drop.sql content_type__drop_type ------------------------- 0 (1 row) -[$OPENACS_SERVICE_NAME postgresql]$
Once both scripts are working without errors, run the create script one last time and proceed.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql
Prev Home Next
Creating an Application Package Up Creating Web Pages
docs@openacs.org
View comments on this page at openacs.org +[$OPENACS_SERVICE_NAME postgresql]$
Once both scripts are working without errors, run the create script one last time and proceed.
[$OPENACS_SERVICE_NAME postgresql]$ psql service0 -f myfirstpackage-create.sql
Prev Home Next
Creating an Application Package Up Creating Web Pages
docs@openacs.org
View comments on this page at openacs.org 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.40 -r1.41 --- openacs-4/packages/acs-core-docs/www/tutorial-debug.html 17 Oct 2010 21:06:08 -0000 1.40 +++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html 11 Dec 2010 23:36:32 -0000 1.41 @@ -1,49 +1,49 @@ - -Debugging and Automated Testing
Prev Chapter 9. Development Tutorial Next
Debugging and Automated Testing
by Joel Aufrecht
+ +Debugging and Automated Testing
Prev Chapter 8. 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 - in and out.
PostgreSQL. You can work directly with the database to do debugging + in and out.
PostgreSQL. You can work directly with the database to do debugging steps like looking directly at tables and testing stored procedures. Start emacs. Type - M-x sql-postgres. Press enter for - server name and use $OPENACS_SERVICE_NAME for + M-x sql-postgres. Press enter for + server name and use $OPENACS_SERVICE_NAME for database name. You can use C-(up arrow) and C-(down arrow) for command history. -
Hint: "Parse error near *" usually means that an xql file +
Hint: "Parse error near *" usually means that an xql file wasn't recognized, because the tcl file is choking on the *SQL* - placeholder that it falls back on.
Watching the server log.
To set up real-time monitoring of the AOLserver error - log, type
less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log
+ placeholder that it falls back on.
Watching the server log.
To set up real-time monitoring of the AOLserver error + log, type
less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log

F to show new log entries in real time (like tail -f)
C-c to stop and F to start it up again.
G goes to the end.
? searches backward
/ searches forward.

-
Manual testing
Make a list of basic tests to make sure it works
Test Num Action Expected Result
001 Browse to the index page while not logged in and - while one or more notes exist. No edit or delete or add links should appear.
002 Browse to the index page while logged in. An Edit +
Manual testing
Make a list of basic tests to make sure it works
Test Num Action Expected Result
001 Browse to the index page while not logged in and + while one or more notes exist. No edit or delete or add links should appear.
002 Browse to the index page while logged in. An Edit link should appear. Click on it. Fill out the form and - click Submit. The text added in the form should be visible on the - index page.
API-001 Invoke mfp::note::create with a specific word as the title. Proc should return an object id.
API-002 Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title.
API-003 Given the object id from API-001, invoke mfp::note::delete. Proc should return 0 for success.
Other things to test: try to delete someone else's + click Submit.
The text added in the form should be visible on the + index page.
API-001 Invoke mfp::note::create with a specific word as the title. Proc should return an object id.
API-002 Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title.
API-003 Given the object id from API-001, invoke mfp::note::delete. Proc should return 0 for success.
Other things to test: try to delete someone else's note. Try to delete your own note. Edit your own note. - Search for a note.
Write automated tests
by Simon Carstensen and Joel Aufrecht
+ Search for a note.
Write automated tests
by Simon Carstensen and Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
+
It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it.
Create the directory that will contain the test - script and edit the script file. The directory location and file name are standards which are recognized by the automated testing package:
[$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 -[$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl
Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file:
ad_library { + 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 +[$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl
Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file:
ad_library { ... }
To create a test case you call -aa_register_case test_case_name.. +aa_register_case test_case_name.. Once you've created the test case you start writing the needed logic. -We'll use the tutorial package, "myfirstpackage," as an example. -Let's say you just wrote an API for adding and deleting notes in the +We'll use the tutorial package, "myfirstpackage," as an example. +Let's say you just wrote an API for adding and deleting notes in the notes packages and wanted to test that. You'd probably want to write a test that first creates a note, then verifies that it was inserted, then perhaps deletes it again, and finally verifies that it is @@ -54,7 +54,7 @@ call to aa_run_with_teardown which basically means that all the inserts, deletes, and updates will be rolled back once the test has been executed. A very useful feature. Instead of inserting bogus data -like: set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
set name [ad_generate_random_string] +like: set name "Simon", I tend to generate a random script in order avoid inserting a value that's already in the database:
set name [ad_generate_random_string]
Here's how the test case looks so far:
aa_register_case mfp_basic_test { My test } { @@ -65,10 +65,10 @@ } }
Now let's look at the actual test code. That's the code that -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."
+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. } @@ -84,15 +84,15 @@ -test_code { 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] + aa_true "Note add succeeded" [exists_and_not_null new_id] mfp::note::get -item_id $new_id -array note_array - aa_true "Note contains correct title" [string equal $note_array(title) $name] + aa_true "Note contains correct title" [string equal $note_array(title) $name] mfp::note::delete -item_id $new_id set get_again [catch {mfp::note::get -item_id $new_id -array note_array}] - aa_false "After deleting a note, retrieving it fails" [expr {$get_again == 0}] + aa_false "After deleting a note, retrieving it fails" [expr {$get_again == 0}] } } @@ -109,15 +109,15 @@ set name {-Bad [BAD] \077 { $Bad}} append name [ad_generate_random_string] set new_id [mfp::note::add -title $name] - aa_true "Note add succeeded" [exists_and_not_null new_id] + aa_true "Note add succeeded" [exists_and_not_null new_id] mfp::note::get -item_id $new_id -array note_array - aa_true "Note contains correct title" [string equal $note_array(title) $name] - aa_log "Title is $name" + aa_true "Note contains correct title" [string equal $note_array(title) $name] + aa_log "Title is $name" mfp::note::delete -item_id $new_id set get_again [catch {mfp::note::get -item_id $new_id -array note_array}] - aa_false "After deleting a note, retrieving it fails" [expr {$get_again == 0}] + aa_false "After deleting a note, retrieving it fails" [expr {$get_again == 0}] } } @@ -160,9 +160,9 @@ # Request note-edit page set package_uri [apm_package_url_from_key myfirstpackage] - set edit_uri "${package_uri}note-edit" - aa_log "[twt::server_url]$edit_uri" - twt::do_request "[twt::server_url]$edit_uri" + set edit_uri "${package_uri}note-edit" + aa_log "[twt::server_url]$edit_uri" + twt::do_request "[twt::server_url]$edit_uri" # Submit a new note @@ -177,8 +177,8 @@ # Request index page and verify that note is in listing tclwebtest::do_request $package_uri - aa_true "New note with title \"$note_title\" is found in index page" \ - [string match "*${note_title}*" [tclwebtest::response body]] + aa_true "New note with title \"$note_title\" is found in index page" \ + [string match "*${note_title}*" [tclwebtest::response body]] #------------------------------------------------------------- # Delete Note @@ -191,27 +191,27 @@ # 3) screen-scrape for the ID # all options are problematic. We'll do #1 in this example: - set note_id [db_string get_note_id_from_name " + set note_id [db_string get_note_id_from_name " select item_id from cr_items where name = :note_title and content_type = 'mfp_note' - " -default 0] + " -default 0] - aa_log "Deleting note with id $note_id" + aa_log "Deleting note with id $note_id" - set delete_uri "${package_uri}note-delete?item_id=${note_id}" + set delete_uri "${package_uri}note-delete?item_id=${note_id}" twt::do_request $delete_uri # Request index page and verify that note is in listing tclwebtest::do_request $package_uri - aa_true "Note with title \"$note_title\" is not found in index page after deletion." \ - ![string match "*${note_title}*" [tclwebtest::response body]] + aa_true "Note with title \"$note_title\" is not found in index page after deletion." \ + ![string match "*${note_title}*" [tclwebtest::response body]] } -teardown_code { twt::user::delete -user_id $user_id } } -
See also Section , “Automated Testing”.
Prev Home Next
Creating Web Pages Up Chapter 10. Advanced Topics
docs@openacs.org
View comments on this page at openacs.org +
See also Automated Testing.
Prev Home Next
Creating Web Pages Up Chapter 9. Advanced Topics
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.html,v diff -u -N -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 17 Oct 2010 21:06:08 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 11 Dec 2010 23:36:32 -0000 1.25 @@ -1,11 +1,11 @@ - -Prepare the package for distribution.
Prev Chapter 10. Advanced Topics Next
Prepare the package for distribution.
Browse to the package manager. Click on - tutorialapp.
Click on Generate a distribution file + +Prepare the package for distribution.
Prev Chapter 9. Advanced Topics Next
Prepare the package for distribution.
Browse to the package manager. Click on + tutorialapp.
Click on Generate a distribution file for this package from the - filesystem. + filesystem.
Click on the file size - (37.1KB) - after the label Distribution - File: and save the file to - /var/tmp.
-
Package development guidelines
Prev Home Next
Profile your code Up Distributing upgrades of your package
docs@openacs.org
View comments on this page at openacs.org + (37.1KB) + after the label Distribution + File: and save the file to + /var/tmp.
+
Package development guidelines
Prev Home Next
Profile your code Up Distributing upgrades of your package
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html 17 Oct 2010 21:06:08 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,17 +1,17 @@ - -OpenACS Edit This Page Templates
Prev Chapter 10. Advanced Topics Next
OpenACS Edit This Page Templates
by Nick Carroll
+ +OpenACS Edit This Page Templates
Prev Chapter 9. Advanced Topics Next
OpenACS Edit This Page Templates
by Nick Carroll
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Goals
Learn about the OpenACS templating system.
Learn about subsites and site-map administration.
Introduction
+
Goals
Learn about the OpenACS templating system.
Learn about subsites and site-map administration.
Introduction
The OpenACS templating system allows you to give your site a consistent look and feel. It also promotes code maintainability in the presentation layer, by allowing presentation components to be reused across multiple pages. If you need to change the layout for some reason, then you only need to make that change in one location, instead of across many files.
In this problem set you will familiarise yourself with the templating system in openacs. This will be achieved through customising an existing edit-this-page application template.
Before proceeding, it is strongly advised to read the templating documentation on your openacs installation (http://localhost:8000/doc/acs-templating). The documentation lists the special tags available for ADP files. -
Exercise 1: Create a Subsite
Create a subsite called pset3.
A subsite is simply a directory or subdirectory mounted at the end of your domain name. This can be done in one of two places:
http://localhost:8000/admin/site-map
or the subsite admin form on the main site, which is available when you login to your OpenACS installation.
Exercise 2: Checkout and Install edit-this-page (ETP)
Checkout ETP from CVS:
cd ~/openacs/packages +
Exercise 1: Create a Subsite
Create a subsite called pset3.
A subsite is simply a directory or subdirectory mounted at the end of your domain name. This can be done in one of two places:
http://localhost:8000/admin/site-map
or the subsite admin form on the main site, which is available when you login to your OpenACS installation.
Exercise 2: Checkout and Install edit-this-page (ETP)
Checkout ETP from CVS:
cd ~/openacs/packages cvs -d:pserver:anonymous@openacs.org:/cvsroot login - cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page
Go to the package manager at http://yoursite/acs-admin/apm. And install the new package: edit-this-page.
Or use the "Add Application" form available on the Main site.
Change ETP Application
Work out how to change the ETP application.
Investigate each of the available ETP templates:
Default
News
FAQ
Exercise 4: Create a New ETP Template
Browse the files for each of the above ETP templates at:
cd ~/openacs/packages/edit-this-page/templates
Use the article template as the basis of our new col2 template.
cp article-content.adp col2-content.adp + cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page
Go to the package manager at http://yoursite/acs-admin/apm. And install the new package: edit-this-page.
Or use the "Add Application" form available on the Main site.
Change ETP Application
Work out how to change the ETP application.
Investigate each of the available ETP templates:
Default
News
FAQ
Exercise 4: Create a New ETP Template
Browse the files for each of the above ETP templates at:
cd ~/openacs/packages/edit-this-page/templates
Use the article template as the basis of our new col2 template.
cp article-content.adp col2-content.adp cp article-content.tcl col2-content.tcl cp article-index.adp col2-index.adp - cp article-index.tcl col2-index.tcl
The template should provide us with the following ETP layout:
Table 10.1. table showing ETP layout
Header
Sidebar Main Content Pane
The "Main Content" pane should contain the editable content that ETP provides.
The "Header" should display the title of the page that you set in ETP.
The "Sidebar" should display the extlinks that you add as a content item in ETP.
Exercise 5: Register the col2 Template with ETP
Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.
cd ~/openacs/packages/edit-this-page/tcl - emacs etp-custom-init.tcl
Use the function etp::define_application to register your template with ETP
Uncomment the "asc" definition
Set allow_extlinks to true, the rest should be false.
Restart your server for the changes to take effect.
Exercise 6: Configure ETP to use the col2 Template
Configure your ETP instance at /lab4/index to use the col2 template.
Create external links to link to other mounted ETP instances.
Check that your external links show up in the sidebar when you view your ETP application using the col2 template.
Who Wrote This and When
This problem set was originally written by Nick Carroll in August 2004 for the University of Sydney Course EBUS5002.
This material is copyright 2004 by Nick Carroll. It may be copied, reused, and modified, provided credit is given to the original author.
($Id$)
Prev Home Next
Add the new package to CVS Up Adding Comments
docs@openacs.org
View comments on this page at openacs.org + cp article-index.tcl col2-index.tcl
The template should provide us with the following ETP layout:
Table 9.1. table showing ETP layout
Header
Sidebar Main Content Pane

The "Main Content" pane should contain the editable content that ETP provides.
The "Header" should display the title of the page that you set in ETP.
The "Sidebar" should display the extlinks that you add as a content item in ETP.
Exercise 5: Register the col2 Template with ETP
Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.
cd ~/openacs/packages/edit-this-page/tcl + emacs etp-custom-init.tcl
Use the function etp::define_application to register your template with ETP
Uncomment the "asc" definition
Set allow_extlinks to true, the rest should be false.
Restart your server for the changes to take effect.
Exercise 6: Configure ETP to use the col2 Template
Configure your ETP instance at /lab4/index to use the col2 template.
Create external links to link to other mounted ETP instances.
Check that your external links show up in the sidebar when you view your ETP application using the col2 template.
Who Wrote This and When
This problem set was originally written by Nick Carroll in August 2004 for the University of Sydney Course EBUS5002.
This material is copyright 2004 by Nick Carroll. It may be copied, reused, and modified, provided credit is given to the original author.
($Id$)
Prev Home Next
Add the new package to CVS Up Adding Comments
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html 17 Oct 2010 21:06:08 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html 11 Dec 2010 23:36:32 -0000 1.16 @@ -1,7 +1,7 @@ - -Future Topics
Prev Chapter 10. Advanced Topics Next
Future Topics
How to enforce security so that users can't - change other users records
How to use the content management tables so that - ... what?
How to change the default stylesheets for Form - Builder HTML forms.
How to make your package searchable with OpenFTS/Oracle
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
More on ad_form - data validation, other stuff. - (plan to draw from Jon Griffin's doc)
partialquery in xql
How to use the html/text entry widget to get the - "does this look right" confirm page
APM package dependencies
See also the OpenACS Programming FAQ
Prev Home Next
Connect to a second database Up Chapter 11. Development Reference
docs@openacs.org
View comments on this page at openacs.org + +Future Topics
Prev Chapter 9. Advanced Topics Next
Future Topics
How to enforce security so that users can't + change other users records
How to use the content management tables so that + ... what?
How to change the default stylesheets for Form + Builder HTML forms.
How to make your package searchable with OpenFTS/Oracle
How to prepare pagelets for inclusion in other pages
How and when to put procedures in a tcl procedure library
More on ad_form - data validation, other stuff. + (plan to draw from Jon Griffin's doc)
partialquery in xql
How to use the html/text entry widget to get the + "does this look right" confirm page
APM package dependencies
See also the OpenACS Programming FAQ
Prev Home Next
Connect to a second database Up Chapter 10. Development Reference
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html,v diff -u -N -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html 17 Oct 2010 21:06:08 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html 11 Dec 2010 23:36:32 -0000 1.10 @@ -1,22 +1,22 @@ - -Hierarchical data
Prev Chapter 10. Advanced Topics Next
Hierarchical data
by Jade Rubick + +Hierarchical data
Prev Chapter 9. Advanced Topics Next
Hierarchical data
by Jade Rubick with help from many people in the OpenACS community
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
One of the nice things about using the OpenACS object system is that it has a built-in facility for tracking hierarchical data in an efficient way. The algorithm behind this is called - tree_sortkey.
Any time your tables are subclasses of the acs_objects + tree_sortkey.
Any time your tables are subclasses of the acs_objects table, then you automatically get the ability to structure them hierarchically. The way you do this is currently via the - context_id column of + context_id column of acs_objects (Note that there is talk of adding in a - parent_id column instead, because - the use of context_id has been + parent_id column instead, because + the use of context_id has been ambiguous in the past). So when you want to build your hierarchy, simply set the context_id values. Then, when you want to make hierarchical queries, you can do them as follows:
- db_multirow categories blog_categories " + db_multirow categories blog_categories " SELECT c.*, o.context_id, @@ -27,9 +27,9 @@ WHERE c.category_id = o.object_id ORDER BY - o.tree_sortkey" + o.tree_sortkey"
Note the use of the - tree_level() function, which + tree_level() function, which gives you the level, starting from 1, 2, 3...
Here's an example, pulling all of the children for a given parent:
SELECT @@ -48,8 +48,8 @@ want the parent's tree_level to start with 0, you'll want the subtraction in there. This is a reason you'll commonly see magic numbers in tree_sortkey SQL queries, like - tree_level(children.tree_sortkey) - - 4. That is basically an incorrect way to do it, + tree_level(children.tree_sortkey) - + 4. That is basically an incorrect way to do it, and subtracting the parent's tree_level is the preferred method.
This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:
SELECT subtree.*, @@ -60,9 +60,9 @@ subtree.tree_sortkey between parent.tree_sortkey and tree_right(parent.tree_sortkey) and parent.key = :the_parent_key;
If you are using the Content Repository, you get a similar - facility, but the parent_id + facility, but the parent_id column is already there. Note you can do joins with - tree_sortkey:
+ tree_sortkey:
SELECT p.item_id, repeat(:indent_pattern, (tree_level(p.tree_sortkey) - 5)* :indent_factor) as indent, @@ -71,9 +71,9 @@ FROM pm_projectsx p, cr_items i WHERE p.project_id = i.live_revision ORDER BY i.tree_sortkey -
This rather long thread explains How - tree_sortkeys work and this paper describes - the technique for tree_sortkeys, although the OpenACS +
This rather long thread explains How + tree_sortkeys work and this paper describes + the technique for tree_sortkeys, although the OpenACS implementation has a few differences in the implementation, to make it work for many languages and the LIKE construct in Postgres. 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.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/tutorial-html-email.html 17 Oct 2010 21:06:08 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/tutorial-html-email.html 11 Dec 2010 23:36:32 -0000 1.10 @@ -1,22 +1,22 @@ - -Sending HTML email from your application
Prev Chapter 10. Advanced Topics Next
Sending HTML email from your application
by Jade Rubick
+ +Sending HTML email from your application
Prev Chapter 9. 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 subject "my subject" - set message "<b>Bold</b> not bold" + set message "<b>Bold</b> not bold" - set from_addr "me@myemail.com" + set from_addr "me@myemail.com" - set to_addr "me@myemail.com" + set to_addr "me@myemail.com" # the from to html closes any open tags. set message_html [ad_html_text_convert -from html -to html $message] # some mailers chop off the last few characters. - append message_html " " + append message_html " " set message_text [ad_html_text_convert -from html -to text $message] set message_data [build_mime_message $message_text $message_html] 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.40 -r1.41 --- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 17 Oct 2010 21:06:08 -0000 1.40 +++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 11 Dec 2010 23:36:32 -0000 1.41 @@ -1,12 +1,12 @@ - -Creating an Application Package
Prev Chapter 9. Development Tutorial Next
Creating an Application Package
by Joel Aufrecht
+ +Creating an Application Package
Prev Chapter 8. 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 with user interface is called an application; a package which provides functions to other packages and has no direct interface, a - service. A package can be installed, upgraded, and + service. A package can be installed, upgraded, and removed. It communicates with other packages through an API. This chapter walks you through the minimum steps to create a useful package, including writing documentation, setting up database tables and procedures, writing web pages, debugging, and automatic regression testing. @@ -18,59 +18,59 @@ 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 - OpenACS. If you don't have this, see Chapter 2, Installation Overview. -
Example files, which are included in the +
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.6.0 distribution. -
Figure 9.1. Assumptions in this section
Fully qualified domain name of your server yourserver.test
URL of your server http://yourserver.test:8000
Name of development account $OPENACS_SERVICE_NAME
New Package key myfirstpackage
Use the APM to initialize a new package
We use the ACS Package Manager (APM) to add, remove, and +
Figure 8.1. Assumptions in this section
Fully qualified domain name of your server yourserver.test
URL of your server http://yourserver.test:8000
Name of development account $OPENACS_SERVICE_NAME
New Package key myfirstpackage

Use the APM to initialize a new package
We use the ACS Package Manager (APM) to add, remove, and upgrade packages. It handles package meta-data, such as lists of files that belong in the package. Each package is uniquely identified by a package key. To start developing a new package, use the APM to create an empty package with our new package key, myfirstpackage. This will create the initial directories, meta-information files, and database - entries for a new package. (More info on APM) -
Browse to - http://yourserver:8000/acs-admin/apm. -
Click Create a New Package.
Fill in the fields listed below. Ignore the rest (and leave the check boxes alone). + entries for a new package. (More info on APM) +
Browse to + http://yourserver:8000/acs-admin/apm. +
Click Create a New Package.
Fill in the fields listed below. Ignore the rest (and leave the check boxes alone). (Some will change automatically. Don't mess with those.) -
- Package Key: - myfirstpackage
- Package Name: - My First Package -
- Package Plural: - My First Package
- Package Type: - Application -
- Initial Version: - 0.1d -
Summary: - This is my first package. +
+ Package Key: + myfirstpackage
+ Package Name: + My First Package +
+ Package Plural: + My First Package
+ Package Type: + Application +
+ Initial Version: + 0.1d +
Summary: + This is my first package.
At the bottom, click - Create Package. + Create Package.
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. More on the structure of - packages).
Add an Application Instance to the Server
In order to see your work in progress, you must create a + /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. More on the structure of + packages).
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 - instance of the application. (More on applications and nodes)
You can have instances of a package on one site, each with a + instance of the application. (More on applications and nodes)
You can have instances of a package on one site, each with a different URL and different permissions, all sharing the same code and tables. This requires that a package be developed package-aware. You'll see how to do that - in this tutorial.
Browse to -http://yourserver.test:8000/admin/applications/application-add/.
Choose "My First Package" from the list and click OK (the other fields are optional).
By mounting the package, we've caused all requests to - http://yourserver.test:8000/myfirstpackage - 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 + in this tutorial.
Browse to +http://yourserver.test:8000/admin/applications/application-add/.
Choose "My First Package" from the list and click OK (the other fields are optional).
By mounting the package, we've caused all requests to + http://yourserver.test:8000/myfirstpackage + 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 cp note-list.* ../../../../myfirstpackage/lib/ cp myfirstpackage-*sql ../../../../myfirstpackage/sql/postgresql/ cp myfirstpackage-procs.tcl ../../../../myfirstpackage/tcl/test/ -cp note-procs.tcl ../../../../myfirstpackage/tcl/
After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.
Prev Home Next
Chapter 9. Development Tutorial Up Setting Up Database Objects
docs@openacs.org
View comments on this page at openacs.org +cp note-procs.tcl ../../../../myfirstpackage/tcl/
After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.
Prev Home Next
Chapter 8. Development Tutorial Up Setting Up Database Objects
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 17 Oct 2010 21:06:08 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,5 +1,5 @@ - -Notifications
Prev Chapter 10. Advanced Topics Next
Notifications
by David Bell and Simon Carstensen
+ +Notifications
Prev Chapter 9. Advanced Topics Next
Notifications
by David Bell and Simon Carstensen
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
The notifications package allows you to send notifications through any @@ -174,9 +174,9 @@ -notif_text $new_content
This code is placed in the tcl procedure that creates blog entries, right after the entry gets created in the code. The - $blog(package_id) is the OpenACS + $blog(package_id) is the OpenACS object_id of the Weblogger instance to which the entry has been - posted to and the $new_content is + posted to and the $new_content is the content of the entry. This example uses the package_id for the object_id, which results in setting up notifications for all changes for blogger entries in this package. However, if you @@ -185,7 +185,7 @@ you can look at it for an example.
The final step is to setup the notification subscription process. In this example we want to let a user find out when a new entry has been posted to the blog. To do this we put a link on the blog that allows them to subscribe to notifications of new - entries. The notifications/requests-new page is very handy in this situation.
Such a link can be created using the notification::display::request_widget + entries. The notifications/requests-new page is very handy in this situation.
Such a link can be created using the notification::display::request_widget proc:
set notification_chunk [notification::display::request_widget \ -type lars_blogger_notif \ @@ -196,10 +196,10 @@
which will return something like
- You may <a href="/notifications/request-new?...">request notification</a> for Weblogger.
+ You may <a href="/notifications/request-new?...">request notification</a> for Weblogger.
- which can be readily put on the blog index page. The pretty_name - parameter is what appears at the end of the text returned (i.e. "... request notification</a> for pretty_name"), - The url parameter should be set to the address we want the user + which can be readily put on the blog index page. The pretty_name + parameter is what appears at the end of the text returned (i.e. "... request notification</a> for pretty_name"), + The url parameter should be set to the address we want the user to be redirected to after they have finished the subscription process.
This should be all you need to implement a notification system. For more examples look at the forums package.
Prev Home Next
Distributing upgrades of your package Up Hierarchical data
docs@openacs.org
View comments on this page at openacs.org 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.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/tutorial-pages.html 17 Oct 2010 21:06:08 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html 11 Dec 2010 23:36:32 -0000 1.42 @@ -1,51 +1,51 @@ - -Creating Web Pages
Prev Chapter 9. Development Tutorial Next
Creating Web Pages
by Joel Aufrecht
+ +Creating Web Pages
Prev Chapter 8. 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/tutorial/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
Build the "Index" page
Each user-visible page in your package has, typically, - three parts. The tcl file +
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/tutorial/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 8.5. 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 check permissions, invoke the database queries, and modify - variables, and the adp page - holds html. The -postgres.xql - and -oracle.xql files contains + variables, and the adp page + holds html. The -postgres.xql + and -oracle.xql files contains database-specific SQL. The default page in any directory is - index, so we'll build that - first, starting with the tcl file:
[$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www -[$OPENACS_SERVICE_NAME www]$ emacs index.tcl
Paste this into the file.
ad_page_contract { + index, so we'll build that + first, starting with the tcl file:
[$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www +[$OPENACS_SERVICE_NAME www]$ emacs index.tcl
Paste this into the file.
ad_page_contract { This is the main page for the package. It displays all of the Notes and provides links to edit them and to create new Notes. @author Your Name (you@example.com) @cvs-id $Id$ } set page_title [ad_conn instance_name] -set context [list]
Now index.adp:
<master> - <property name="title">@page_title;noquote@</property> - <property name="context">@context;noquote@</property> -<include src="/packages/myfirstpackage/lib/note-list">
The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib -[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib -[$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
template::list::create \ +set context [list]
Now index.adp:
<master> + <property name="title">@page_title;noquote@</property> + <property name="context">@context;noquote@</property> +<include src="/packages/myfirstpackage/lib/note-list">
The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.
[$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib +[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib +[$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl
template::list::create \ -name notes \ -multirow notes \ - -actions { "Add a Note" note-edit} \ + -actions { "Add a Note" note-edit} \ -elements { edit { link_url_col edit_url display_template { - <img src="/resources/acs-subsite/Edit16.gif" width="16" height="16" border="0"> + <img src="/resources/acs-subsite/Edit16.gif" width="16" height="16" border="0"> } sub_class narrow } title { - label "Title" + label "Title" } delete { link_url_col delete_url display_template { - <img src="/resources/acs-subsite/Delete16.gif" width="16" height="16" border="0"> + <img src="/resources/acs-subsite/Delete16.gif" width="16" height="16" border="0"> } sub_class narrow } @@ -62,11 +62,11 @@ mfp_notesx n where n.revision_id = ci.live_revision } { - set edit_url [export_vars -base "note-edit" {item_id}] - set delete_url [export_vars -base "note-delete" {item_id}] - }
[$OPENACS_SERVICE_NAME lib]$ emacs note-list.adp
<listtemplate name="notes"></listtemplate>
You can test your work by viewing the page.
Create the add/edit page. If note_id is passed in, - it display that note, and can change to edit mode if appropriate. Otherwise, it presents a form for adding notes.
[$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www -[$OPENACS_SERVICE_NAME www]$ emacs note-edit.tcl
ad_page_contract { + set edit_url [export_vars -base "note-edit" {item_id}] + set delete_url [export_vars -base "note-delete" {item_id}] + }
[$OPENACS_SERVICE_NAME lib]$ emacs note-list.adp
<listtemplate name="notes"></listtemplate>
You can test your work by viewing the page.
Create the add/edit page. If note_id is passed in, + it display that note, and can change to edit mode if appropriate. Otherwise, it presents a form for adding notes.
[$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www +[$OPENACS_SERVICE_NAME www]$ emacs note-edit.tcl
ad_page_contract { This is the view-edit page for notes. @author Your Name (you@example.com) @@ -83,7 +83,7 @@ } -new_request { auth::require_login permission::require_permission -object_id [ad_conn package_id] -privilege create - set page_title "Add a Note" + set page_title "Add a Note" set context [list $page_title] } -edit_request { auth::require_login @@ -94,7 +94,7 @@ set title $note_array(title) - set page_title "Edit a Note" + set page_title "Edit a Note" set context [list $page_title] } -new_data { mfp::note::add \ @@ -104,15 +104,15 @@ -item_id $item_id \ -title $title } -after_submit { - ad_returnredirect "." + ad_returnredirect "." ad_script_abort -}
[$OPENACS_SERVICE_NAME www]$ emacs note-edit.adp
<master> - <property name="title">@page_title;noquote@</property> - <property name="context">@context;noquote@</property> - <property name="focus">note.title</property> +}
[$OPENACS_SERVICE_NAME www]$ emacs note-edit.adp
<master> + <property name="title">@page_title;noquote@</property> + <property name="context">@context;noquote@</property> + <property name="focus">note.title</property> -<formtemplate id="note"></formtemplate>
And the delete page. Since it has no UI, there is only a - tcl page, and no adp page.
[$OPENACS_SERVICE_NAME www]$ emacs note-delete.tcl
ad_page_contract { +<formtemplate id="note"></formtemplate>
And the delete page. Since it has no UI, there is only a + tcl page, and no adp page.
[$OPENACS_SERVICE_NAME www]$ emacs note-delete.tcl
ad_page_contract { This deletes a note @author Your Name (you@example.com) @@ -127,7 +127,7 @@ set title [item::get_title $item_id] mfp::note::delete -item_id $item_id -ad_returnredirect "." +ad_returnredirect "." # stop running this code, since we're redirecting abort
Prev Home Next
Setting Up Database Objects Up Debugging and Automated Testing
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-parameters.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-parameters.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/tutorial-parameters.html 17 Oct 2010 21:06:08 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/tutorial-parameters.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,5 +1,5 @@ - -Adding in parameters for your package
Prev Chapter 10. Advanced Topics Next
Adding in parameters for your package
Each instance of a package can have paramaters associated + +Adding in parameters for your package
Prev Chapter 9. Advanced Topics Next
Adding in parameters for your package
Each instance of a package can have paramaters associated with it. These are like preferences, and they can be set by the administrator for each application to change the behavior of your application.
To add parameters for your package, go to the Automatic Index: openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html 17 Oct 2010 21:06:08 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html 11 Dec 2010 23:36:32 -0000 1.9 @@ -1,7 +1,7 @@ - -Scheduled Procedures
Prev Chapter 10. Advanced Topics Next
Scheduled Procedures
Put this proc in a file /packages/myfirstpackage/tcl/scheduled-init.tcl. Files in /tcl with the -init.tcl ending are sourced on server startup. This one executes my_proc every 60 seconds:
ad_schedule_proc 60 myfirstpackage::my_proc + +Scheduled Procedures
Prev Chapter 9. Advanced Topics Next
Scheduled Procedures
Put this proc in a file /packages/myfirstpackage/tcl/scheduled-init.tcl. Files in /tcl with the -init.tcl ending are sourced on server startup. This one executes my_proc every 60 seconds:
ad_schedule_proc 60 myfirstpackage::my_proc
This executes once a day, at midnight:
ad_schedule_proc \ -schedule_proc ns_schedule_daily \ [list 0 0] \ myfirstpackage::my_proc -
See ad_schedule_proc for more information.
Prev Home Next
Basic Caching Up Enabling WYSIWYG
docs@openacs.org
View comments on this page at openacs.org +
See ad_schedule_proc for more information.
Prev Home Next
Basic Caching Up Enabling WYSIWYG
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-second-database.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-second-database.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/tutorial-second-database.html 17 Oct 2010 21:06:08 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/tutorial-second-database.html 11 Dec 2010 23:36:32 -0000 1.9 @@ -1,14 +1,14 @@ - -Connect to a second database
Prev Chapter 10. Advanced Topics Next
Connect to a second database
It is possible to use the OpenACS TCL database API with + +Connect to a second database
Prev Chapter 9. Advanced Topics Next
Connect to a second database
It is possible to use the OpenACS TCL database API with other databases. In this example, the OpenACS site uses a PostGre database, and accesses another PostGre database called - legacy.
Modify config.tcl to accomodate the legacy database, and to + legacy.
Modify config.tcl to accomodate the legacy database, and to ensure that the legacy database is not used for standard OpenACS queries:
ns_section ns/db/pools -ns_param pool1 "Pool 1" -ns_param pool2 "Pool 2" -ns_param pool3 "Pool 3" -ns_param legacy "Legacy" +ns_param pool1 "Pool 1" +ns_param pool2 "Pool 2" +ns_param pool3 "Pool 3" +ns_param legacy "Legacy" ns_section ns/db/pool/pool1 #Unchanged from default @@ -18,7 +18,7 @@ ns_param verbose $debug ns_param extendedtableinfo true ns_param logsqlerrors $debug -if { $database == "oracle" } { +if { $database == "oracle" } { ns_param driver ora8 ns_param datasource {} ns_param user $db_name @@ -27,7 +27,7 @@ ns_param driver postgres ns_param datasource ${db_host}:${db_port}:${db_name} ns_param user $db_user - ns_param password "" + ns_param password "" } ns_section ns/db/pool/pool2 @@ -56,14 +56,14 @@ ns_section ns/server/${server}/acs/database ns_param database_names [list main legacy] ns_param pools_main [list pool1 pool2 pool3] -ns_param pools_legacy [list legacy]
To use the legacy database, use the - <code>-dbn</code> flag for any of the - <code>db_</code> API calls. For - example, suppose there is a table called "foo" in the legacy - system, with a field "bar". List "bar" for all records with +ns_param pools_legacy [list legacy]
To use the legacy database, use the + -dbn flag for any of the + db_ API calls. For + example, suppose there is a table called "foo" in the legacy + system, with a field "bar". List "bar" for all records with this tcl file:
db_foreach -dbn legacy get_bar_query { select bar from foo limit 10 } { - ns_write "<br/>$bar" + ns_write "<br/>$bar" }
Prev Home Next
Writing upgrade scripts Up Future Topics
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-specs.html 17 Oct 2010 21:06:08 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-specs.html 11 Dec 2010 23:36:32 -0000 1.13 @@ -1,39 +1,39 @@ - -Write the Requirements and Design Specs
Prev Chapter 10. Advanced Topics Next
Write the Requirements and Design Specs
Before you get started you should make yourself familiar with + +Write the Requirements and Design Specs
Prev Chapter 9. Advanced Topics Next
Write the Requirements and Design Specs
Before you get started you should make yourself familiar with the tags that are used to write your documentation. For tips on - editing SGML files in emacs, see Section , “OpenACS Documentation Guide”.
It's time to document. For the tutorial we'll use + editing SGML files in emacs, see OpenACS Documentation Guide.
It's time to document. For the tutorial we'll use pre-written documentation. When creating a package from scratch, start by copying the documentation template from - /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml + /var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml to - myfirstpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the + myfirstpackage/www/docs/xml/index.xml.
You then edit that file with emacs to write the requirements and design sections, generate the html, and start coding. Store any supporting files, like page maps or schema - diagrams, in the www/doc/xml + diagrams, in the www/doc/xml directory, and store png or jpg versions of supporting files in the - www/doc directory.
For this tutorial, you should instead install the + www/doc directory.
For this tutorial, you should instead install the pre-written documentation files for the tutorial app. Log in as $OPENACS_SERVICE_NAME, create the standard - directories, and copy the prepared documentation:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/ -[$OPENACS_SERVICE_NAME myfirstpackage]$ mkdir -p www/doc/xml -[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www/doc/xml -[$OPENACS_SERVICE_NAME xml]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* . + directories, and copy the prepared documentation:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/ +[$OPENACS_SERVICE_NAME myfirstpackage]$ mkdir -p www/doc/xml +[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www/doc/xml +[$OPENACS_SERVICE_NAME xml]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* . [$OPENACS_SERVICE_NAME xml]$
OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the tags you use indicate meaning, not intended appearance. The style sheet will determine appearance. You will edit the text in an xml file, and then process the file - into html for reading.
Open the file index.xml + into html for reading.
Open the file index.xml in emacs. Examine the file. Find the version history (look for the tag - <revhistory>). Add a + <revhistory>). Add a new record to the document version history. Look for the - <authorgroup> tag and + <authorgroup> tag and add yourself as a second author. Save and exit.
Process the xml file to create html documentation. The html documentation, including supporting files such as pictures, - is stored in the www/docs/ + is stored in the www/docs/ directory. A Makefile is provided to generate html from the xml, and copy all of the supporting files. If Docbook is set up correctly, all you need - to do is:
[$OPENACS_SERVICE_NAME xml]$ make + to do is:
[$OPENACS_SERVICE_NAME xml]$ make cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml Writing requirements-introduction.html for chapter(requirements-introduction) Writing requirements-overview.html for chapter(requirements-overview) @@ -50,4 +50,4 @@ Writing bi01.html for bibliography Writing index.html for book [$OPENACS_SERVICE_NAME xml]$
Verify that the documentation was generated and reflects - your changes by browsing to http://yoursite:8000/myfirstpackage/doc
Prev Home Next
Chapter 10. Advanced Topics Up Add the new package to CVS
docs@openacs.org
View comments on this page at openacs.org + your changes by browsing to http://yoursite:8000/myfirstpackage/doc
Prev Home Next
Chapter 9. Advanced Topics Up Add the new package to CVS
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html 17 Oct 2010 21:06:08 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,5 +1,5 @@ - -Writing upgrade scripts
Prev Chapter 10. Advanced Topics Next
Writing upgrade scripts
by Jade Rubick
+ +Writing upgrade scripts
Prev Chapter 9. Advanced Topics Next
Writing upgrade scripts
by Jade Rubick
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
If your package changes its data model, you have to write an @@ -13,6 +13,6 @@ model changes are more serious and fundamental changes than the program .tcl files.
Now use the APM to create a new package version 1.0b2. Commit all your changes, tag the release - (Section , “Distributing upgrades of your package”), + (Distributing upgrades of your package), and both new installations and upgrades will be taken care of.
Prev Home Next
Adding in parameters for your package Up Connect to a second database
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html 17 Oct 2010 21:06:08 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,17 +1,17 @@ - -Distributing upgrades of your package
Prev Chapter 10. Advanced Topics Next
Distributing upgrades of your package
by Jade Rubick
+ +Distributing upgrades of your package
Prev Chapter 9. Advanced Topics Next
Distributing upgrades of your package
by Jade Rubick
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
The OpenACS Package Repository builds a list of packages that can be installed on OpenACS installations, and can be used by administrators to update their packages. If you are a package developer, there are a couple of steps you need to take in order to release a new version of your package.
For the sake of this example, let's assume you are the - package owner of the notes + package owner of the notes package. It is currently at version 1.5, and you are planning on releasing version 1.6. It is also located in OpenACS's CVS.
To release your package:
cd /path/to/notes -cvs commit -m "Update package to version 1.6." +cvs commit -m "Update package to version 1.6." cvs tag notes-1-6-final cvs tag -F openacs-5-1-compat
Of course, make sure you write upgrade scripts - (Section , “Writing upgrade scripts”)
Prev Home Next
Prepare the package for distribution. Up Notifications
docs@openacs.org
View comments on this page at openacs.org + (Writing upgrade scripts)
Prev Home Next
Prepare the package for distribution. Up Notifications
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.html,v diff -u -N -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 17 Oct 2010 21:06:08 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 11 Dec 2010 23:36:32 -0000 1.17 @@ -1,6 +1,6 @@ - -Using .vuh files for pretty urls
Prev Chapter 10. Advanced Topics Next
Using .vuh files for pretty urls
.Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of note-edit?item_id=495, we can use note/495. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www -[$OPENACS_SERVICE_NAME www]$ emacs note.vuh + +Using .vuh files for pretty urls
Prev Chapter 9. Advanced Topics Next
Using .vuh files for pretty urls
.Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of note-edit?item_id=495, we can use note/495. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh:
[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www +[$OPENACS_SERVICE_NAME www]$ emacs note.vuh
Paste this into the file:
# Transform requests of type: a/b # into this internal request: A?c=b # for example, note/495 > note-edit?item_id=496 @@ -15,10 +15,10 @@ rp_form_put item_id $request -set internal_path "/packages/[ad_conn package_key]/www/note-edit" +set internal_path "/packages/[ad_conn package_key]/www/note-edit" rp_internal_redirect $internal_path -
We parse the incoming request and treat everything after the final / as the item id. Note that this simple redirection will lose any additional query parameters passed in. Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id.
We use rp_form_put to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh).
Next, modify note-list so that its link is of the new form.:
[$OPENACS_SERVICE_NAME www]$ emacs ../lib/note-edit.tcl
+
We parse the incoming request and treat everything after the final / as the item id. Note that this simple redirection will lose any additional query parameters passed in. Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id.
We use rp_form_put to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh).
Next, modify note-list so that its link is of the new form.:
[$OPENACS_SERVICE_NAME www]$ emacs ../lib/note-edit.tcl
db_multirow \ -extend { edit_url @@ -30,8 +30,8 @@ mfp_notesx n where n.revision_id = ci.live_revision } { - set edit_url [export_vars -base "note/$item_id"] - set delete_url [export_vars -base "note-delete" {item_id}] + set edit_url [export_vars -base "note/$item_id"] + set delete_url [export_vars -base "note-delete" {item_id}] }
You may also need to change some of the links in your package. Commonly, you would use ad_conn package_url to build the Index: openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html,v diff -u -N -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html 17 Oct 2010 21:06:08 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html 11 Dec 2010 23:36:32 -0000 1.8 @@ -1,95 +1,95 @@ - -Enabling WYSIWYG
Prev Chapter 10. Advanced Topics Next
Enabling WYSIWYG
by Nima Mazloumi
+ +Enabling WYSIWYG
Prev Chapter 9. Advanced Topics Next
Enabling WYSIWYG
by Nima Mazloumi
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
Most of the forms in OpenACS are created using the form builder, see Section , “Using Form Builder: building html forms dynamically”. For detailed information on the - API take a look here.
The following section shows how you can modify your form to allow WYSIWYG functionalities.
Convert your page to use <code>ad_form</code> (some changes but worth it)
Here an examples. From:
+
Most of the forms in OpenACS are created using the form builder, see Using Form Builder: building html forms dynamically. For detailed information on the + API take a look here.
The following section shows how you can modify your form to allow WYSIWYG functionalities.
Convert your page to use ad_form (some changes but worth it)
Here an examples. From:
template::form create my_form - template::element create my_form my_form_id -label "The ID" -datatype integer -widget hidden - template::element create my_form my_input_field_1 -html { size 30 } -label "Label 1" -datatype text -optional - template::element create my_form my_input_field_2 -label "Label 2" -datatype text -help_text "Some Help" -after_html {<a name="#">Anchor</a>} + template::element create my_form my_form_id -label "The ID" -datatype integer -widget hidden + template::element create my_form my_input_field_1 -html { size 30 } -label "Label 1" -datatype text -optional + template::element create my_form my_input_field_2 -label "Label 2" -datatype text -help_text "Some Help" -after_html {<a name="#">Anchor</a>}
To:
ad_form -name my_form -form { my_form_id:key(acs_object_id_seq) {my_input_field_1:text,optional - {label "Label 1"} + {label "Label 1"} {html {size 30}}} {my_input_field_2:text - {label "Label 2"} - {help_text "Some Help"} + {label "Label 2"} + {help_text "Some Help"} {after_html - {<a name="#">Anchor</a>}}} + {<a name="#">Anchor</a>}}} } ... -
Warning
You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
Convert your textarea widget to a richtext widget and enable htmlarea.
The <code>htmlarea_p</code>-flag can be used to prevent +
Warning
You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.
Convert your textarea widget to a richtext widget and enable htmlarea.
The htmlarea_p-flag can be used to prevent WYSIWYG functionality. Defaults to true if left away.
From:
{my_input_field_2:text
To:
{my_input_field_2:richtext(richtext) - {htmlarea_p "t"} + {htmlarea_p "t"}
The richtext widget presents a list with two elements: text and content type. - To learn more on existing content types search in Google for "MIME-TYPES" or - take a look at the <code>cr_mime_types</code> table.
Make sure that both values are passed as a list to your - <code>ad_form</code> or you will have problems + To learn more on existing content types search in Google for "MIME-TYPES" or + take a look at the cr_mime_types table.
Make sure that both values are passed as a list to your + ad_form or you will have problems displaying the content or handling the data manipulation correctly.
Depending on the data model of your package you either support a content format - or don't. If you don't you can assume <code>"text/html"</code> or - <code>"text/richtext"</code> or <code>"text/enhanced"</code>.
The relevant parts in your <code>ad_form</code> definition are the - switches <code>-new_data</code>, <code>-edit_data</code>, - <code>-on_request</code> and <code>-on_submit</code>.
To allow your data to display correctly you need to add an <code>-on_request</code> block. - If you have the format stored in the database pass this as well else use <code>"text/html"</code>:
- set my_input_field_2 [template::util::richtext::create $my_input_field_2 "text/html"] + or don't. If you don't you can assume "text/html" or + "text/richtext" or "text/enhanced".
The relevant parts in your ad_form definition are the + switches -new_data, -edit_data, + -on_request and -on_submit.
To allow your data to display correctly you need to add an -on_request block. + If you have the format stored in the database pass this as well else use "text/html":
+ set my_input_field_2 [template::util::richtext::create $my_input_field_2 "text/html"]
Now make sure that your SQL queries that do the data manipulation retrieve the correct value. - If you simply use <code>my_input_field_2</code> you will store a list. - Thus you need to add an <code>-on_submit</code> block:
+ If you simply use my_input_field_2 you will store a list. + Thus you need to add an -on_submit block:
set my_input_field_2 [ template::util::richtext::get_property contents $my_input_field_2] set format [ template::util::richtext::get_property format $my_input_field_2] #This is optional -
Now the correct values for <code>my_input_field_2</code> and - <code>format</code> are passed to the <code>-new_data</code> and - <code>-edit_data</code> blocks which don't need to get touched.
To make HTMLArea optional per package instance define a string parameter - <code>UseWysiwygP</code> which defaults <code>0</code> for your +
Now the correct values for my_input_field_2 and + format are passed to the -new_data and + -edit_data blocks which don't need to get touched.
To make HTMLArea optional per package instance define a string parameter + UseWysiwygP which defaults 0 for your package using the APM.
In your edit page make the following changes
# Is WYSIWYG enabled? - set use_wysiwyg_p [parameter::get -parameter "UseWysiwygP" -default "f"] + set use_wysiwyg_p [parameter::get -parameter "UseWysiwygP" -default "f"] ... {htmlarea_p $use_wysiwyg_p} -
The <code>-on_request</code> switch should set this value for your form.
+
The -on_request switch should set this value for your form.
set htmlarea_p $use_wysiwyg_p
All you need now is a configuration page where the user can change this setting. Create a - <code>configure.tcl</code> file:
+ configure.tcl file:
ad_page_contract { This page allows a faq admin to change the UseWysiwygP setting } { - {return_url ""} + {return_url ""} } - set title "Should we support WYSIWYG?" + set title "Should we support WYSIWYG?" set context [list $title] set use_wysiwyg_p ad_form -name categories_mode -form { {enabled_p:text(radio) - {label "Enable WYSIWYG"} + {label "Enable WYSIWYG"} {options {{Yes t} {No f}}} {value $use_wysiwyg_p} } {return_url:text(hidden) {value $return_url}} - {submit:text(submit) {label "Change"}} + {submit:text(submit) {label "Change"}} } -on_submit { - parameter::set_value -parameter "UseWysiwygP" -value $enabled_p + parameter::set_value -parameter "UseWysiwygP" -value $enabled_p if {![empty_string_p $return_url]} { ns_returnredirect $return_url } }
In the corresponding ADP file write
<master> - <property name="title">@title@</property> - <property name="context">@context@</property> + <property name="title">@title@</property> + <property name="context">@context@</property> - <formtemplate id="categories_mode"></formtemplate> + <formtemplate id="categories_mode"></formtemplate>
And finally reference this page from your admin page
#TCL: set return_url [ad_conn url] Index: openacs-4/packages/acs-core-docs/www/tutorial.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial.html,v diff -u -N -r1.22 -r1.23 --- openacs-4/packages/acs-core-docs/www/tutorial.html 17 Oct 2010 21:06:08 -0000 1.22 +++ openacs-4/packages/acs-core-docs/www/tutorial.html 11 Dec 2010 23:36:32 -0000 1.23 @@ -1,2 +1,2 @@ - -Chapter 9. Development Tutorial
Prev Part III. For OpenACS Package Developers Next
Chapter 9. Development Tutorial
Table of Contents
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
Prev Home Next
Part III. For OpenACS Package Developers Up Creating an Application Package
docs@openacs.org
View comments on this page at openacs.org + +Chapter 8. Development Tutorial
Prev Part III. For OpenACS Package Developers Next
Chapter 8. Development Tutorial
Table of Contents
Creating an Application Package
Setting Up Database Objects
Creating Web Pages
Debugging and Automated Testing
Prev Home Next
Part III. For OpenACS Package Developers Up Creating an Application Package
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/unix-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/unix-installation.html,v diff -u -N -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/unix-installation.html 13 Sep 2009 23:54:41 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/unix-installation.html 11 Dec 2010 23:36:32 -0000 1.31 @@ -1,8 +1,8 @@ - -Install a Unix-like system and supporting software
Prev Chapter 3. Complete Installation Next
Install a Unix-like system and supporting software
by Joel Aufrecht
+ +Install a Unix-like system and supporting software
Prev Chapter 3. Complete Installation Next
Install a Unix-like system and supporting software
by Joel Aufrecht
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
a Unix-like system
You will need a computer running a unix-like system with the following software installed:
tdom
tcl --if you plan to use the OpenACS installation script
gmake and the compile and build environment.
BSD Note
BSD users: in most places in these instructions, gmake will work better than make. (more +
a Unix-like system
You will need a computer running a unix-like system with the following software installed:
tdom
tcl --if you plan to use the OpenACS installation script
gmake and the compile and build environment.
BSD Note
BSD users: in most places in these instructions, gmake will work better than make. (more information on FreeBSD installation). Also, fetch is a native replacement for wget.
Note: Instructions for installing tDOM and threaded tcl are included with the AOLserver4 installation instructions, - if these are not yet installed.
The following programs may be useful or required for some configurations. They are included in most distributions:
emacs
cvs (and initialize it)
ImageMagick (used by some packages for server side image manipulation)
Aspell (more information on spell-checking)
DocBook and supporting software (and install emacs keybindings for DocBook SGML)
daemontools (install from source)
a Mail Transport Agent, such as exim or sendmail (or install qmail from source)
In order to cut and paste the example code into your shell, you must first do Setting a global shell variable for cut and paste.
To install a machine to the specifications of the Reference Platform, do the - walkthrough of the Red Hat 8.0 Install for OpenACS.
($Id$)
Prev Home Next
Chapter 3. Complete Installation Up Install Oracle 8.1.7
docs@openacs.org
View comments on this page at openacs.org + if these are not yet installed.
The following programs may be useful or required for some configurations. They are included in most distributions:
emacs
cvs (and initialize it)
ImageMagick (used by some packages for server side image manipulation)
Aspell (more information on spell-checking)
DocBook and supporting software (and install emacs keybindings for DocBook SGML)
daemontools (install from source)
a Mail Transport Agent, such as exim or sendmail (or install qmail from source)
In order to cut and paste the example code into your shell, you must first do Setting a global shell variable for cut and paste.
To install a machine to the specifications of the Reference Platform, do the + walkthrough of the Red Hat 8.0 Install for OpenACS.
($Id$)
Prev Home Next
Chapter 3. Complete Installation Up Install Oracle 8.1.7
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/update-repository.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-repository.html,v diff -u -N -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/update-repository.html 17 Oct 2010 21:06:08 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/update-repository.html 11 Dec 2010 23:36:32 -0000 1.16 @@ -1,25 +1,25 @@ - -How to Update the OpenACS.org repository
Prev Chapter 16. Releasing OpenACS Next
How to Update the OpenACS.org repository
+ +How to Update the OpenACS.org repository
Prev Chapter 15. Releasing OpenACS Next
How to Update the OpenACS.org repository
Setup a local OpenACS server running 5.0 or better. -
- Edit packages/acs-admin/www/apm/build-repository.tcl and adjust the Configuration Settings.
+
+ Edit packages/acs-admin/www/apm/build-repository.tcl and adjust the Configuration Settings.
Request /acs-admin/apm/build-repository on your new server. -
+
The page will find all branches in the cvs repository labeled oacs-x-y, and build a repository channel for each of those branches where x>=5 (so not for 4.6 and earlier). It will also build a channel for HEAD, which will be named after what you set in 'head_channel' above. -
+
For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout. -
- The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "[acs_root_dir]/www/repository/". -
+
+ The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "[acs_root_dir]/www/repository/". +
If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there.
This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script. Since the page circumvents security checks for ease of use, the entire site is limited to local requests. The script is called daily with a cron job.
#!/bin/sh #set -x STATUS=`wget --output-document - http://127.0.0.1:8002/build-repository.tcl | grep DONE | wc -l` -if [ $STATUS -eq "1" ] +if [ $STATUS -eq "1" ] then rm -rf /web/openacs.org/www/repository.old mv /web/openacs.org/www/repository /web/openacs.org/www/repository.old Index: openacs-4/packages/acs-core-docs/www/update-translations.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-translations.html,v diff -u -N -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/update-translations.html 17 Oct 2010 21:06:08 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/update-translations.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,5 +1,5 @@ - -How to Update the translations
Prev Chapter 16. Releasing OpenACS Next
How to Update the translations
Identify any new locales that have been created. + +How to Update the translations
Prev Chapter 15. Releasing OpenACS Next
How to Update the translations
Identify any new locales that have been created. For each new locale, check the parameters, especially that the locale is in the format [two-letter code for language, lower-case]_[TWO-LETTER CODE FOR COUNTRY, @@ -10,10 +10,10 @@ values ('fa_IR', 'Farsi (IR)', 'fa', 'IR', 'FARSI', 'IRAN', 'AL24UTFFSS', 'windows-1256', 't', 'f');
Put this command into the following four files. For the upgrade files, the correct file name will depend on the - exact version.
/packages/acs-lang/sql/postgresql/ad-locales.sql
/packages/acs-lang/sql/postgresql/upgrade/upgrade-current-version.sql
/packages/acs-lang/sql/oracle/ad-locales.sql
/packages/acs-lang/sql/oracle/upgrade/upgrade-current-version.sql
Make a backup of the production database. Restore it as a new database. For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.
Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1. Copy over any local settings - usually, /etc/config.tcl and /etc/daemontools/run and modify appropriately. Also, copy over several translation-server-only files: + exact version.
/packages/acs-lang/sql/postgresql/ad-locales.sql
/packages/acs-lang/sql/postgresql/upgrade/upgrade-current-version.sql
/packages/acs-lang/sql/oracle/ad-locales.sql
/packages/acs-lang/sql/oracle/upgrade/upgrade-current-version.sql
Make a backup of the production database. Restore it as a new database. For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.
Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1. Copy over any local settings - usually, /etc/config.tcl and /etc/daemontools/run and modify appropriately. Also, copy over several translation-server-only files:
...TBD
-
Shut down the production site and put up a notice (no procedure on how to do this yet.)
Start the new site, and upgrade it.
Go to ACS Lang admin page and click "Import All Messages"
Resolve conflicts, if any, on the provided page. -
Back on the admin page, click the export link. If there are conflicts, the messages will be exported anyway and any errors will be shown in the web interface.
Commit the message catalogs to cvs.
From the packages dir, run the acs-lang/bin/check-catalog.sh script. (This checks for keys no longer in use and some other things. Until it is rolled into the UI, do it manually and check the results and take whatever steps you can intuit you should do.) -
CVS commit the catalog files. Done
If everything went well, reconfigure the new site to take over the role of the old site (/etc/config.tcl and /etc/daemontools/run). Otherwise, bring the old site back up while investigating problems, and then repeat. +
Shut down the production site and put up a notice (no procedure on how to do this yet.)
Start the new site, and upgrade it.
Go to ACS Lang admin page and click "Import All Messages"
Resolve conflicts, if any, on the provided page. +
Back on the admin page, click the export link. If there are conflicts, the messages will be exported anyway and any errors will be shown in the web interface.
Commit the message catalogs to cvs.
From the packages dir, run the acs-lang/bin/check-catalog.sh script. (This checks for keys no longer in use and some other things. Until it is rolled into the UI, do it manually and check the results and take whatever steps you can intuit you should do.) +
CVS commit the catalog files. Done
If everything went well, reconfigure the new site to take over the role of the old site (/etc/config.tcl and /etc/daemontools/run). Otherwise, bring the old site back up while investigating problems, and then repeat.
Prev Home Next
How to package and release an OpenACS Package Up Index
docs@openacs.org
View comments on this page at openacs.org 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.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html 17 Oct 2010 21:06:08 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html 11 Dec 2010 23:36:32 -0000 1.25 @@ -1,12 +1,12 @@ - -Upgrading 4.5 or higher to 4.6.3
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.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See Bug #632
A computer with OpenACS 4.5.
OpenACS 4.6 tarball or CVS checkout/export.
Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2
Make a Backup. Back up the database and file system (see Section , “Manual backup and recovery”).
OPTIONAL: Upgrade OpenFTS. Section , “Upgrading OpenFTS from 0.2 to 0.3.2”
+ +Upgrading 4.5 or higher to 4.6.3
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.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See Bug #632
A computer with OpenACS 4.5.
OpenACS 4.6 tarball or CVS checkout/export.
Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2
Make a Backup. Back up the database and file system (see ???).
OPTIONAL: Upgrade OpenFTS. Upgrading OpenFTS from 0.2 to 0.3.2
Stop the server -
[root root]# svc -d /service/$OPENACS_SERVICE_NAME
Upgrade the file system. Section , “Upgrading the OpenACS files”
- Start the server -
[root root]# svc -u /service/$OPENACS_SERVICE_NAME
Use APM to upgrade the database.
Browse to the package manager, http://yourserver/acs-admin/apm.
Click Install packages.
Select the packages you want to install. This should +
[root root]# svc -d /service/$OPENACS_SERVICE_NAME
Upgrade the file system. Upgrading the OpenACS files
+ Start the server +
[root root]# svc -u /service/$OPENACS_SERVICE_NAME
Use APM to upgrade the database.
Browse to the package manager, http://yourserver/acs-admin/apm.
Click Install packages.
Select the packages you want to install. This should be everything that says - upgrade, plus any new + upgrade, plus any new packages you want. It's safest to upgrade the kernel by itself, and then come back and upgrade the rest of the - desired packages in a second pass.
On the next screen, click Install Packages
When prompted, restart the server:
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.6.0.
Rollback. If anything goes wrong, roll back to the backup snapshot.
Prev Home Next
Overview Up Upgrading OpenACS 4.6.3 to 5.0
docs@openacs.org
View comments on this page at openacs.org + desired packages in a second pass.
On the next screen, click Install Packages
When prompted, restart the server:
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm.
Check that the kernel upgrade worked by clicking All and making sure that acs-kernel version is 5.6.0.
Rollback. If anything goes wrong, roll back to the backup snapshot.
Prev Home Next
Overview Up Upgrading OpenACS 4.6.3 to 5.0
docs@openacs.org
View comments on this page at openacs.org 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.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html 17 Oct 2010 21:06:08 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,12 +1,12 @@ - -Upgrading OpenACS 4.6.3 to 5.0
Prev Chapter 5. Upgrading Next
Upgrading OpenACS 4.6.3 to 5.0
Oracle. This forum posting documents - + +Upgrading OpenACS 4.6.3 to 5.0
Prev Chapter 5. Upgrading Next
Upgrading OpenACS 4.6.3 to 5.0
Oracle. This forum posting documents + how to upgrade an Oracle installation from OpenACS 4.6.3 to 5 . -
PostGreSQL. You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See Upgrade PostGreSQL to 7.3; Table 2.2 -
Back up the database and file system.
Upgrade the file system for packages/acs-kernel. Section , “Upgrading the OpenACS files”
Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade
- Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME. Run the scripts in this order (order is tentative, not verified): +
PostGreSQL. You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See Upgrade PostGreSQL to 7.3; Table 2.2. Version Compatibility Matrix +
Back up the database and file system.
Upgrade the file system for packages/acs-kernel. Upgrading the OpenACS files
Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade
+ Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME. Run the scripts in this order (order is tentative, not verified):
psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME psql -f upgrade-4.6.4-4.6.5.sql $OPENACS_SERVICE_NAME psql -f upgrade-4.6.5-4.6.6.sql $OPENACS_SERVICE_NAME @@ -20,26 +20,26 @@ psql -f upgrade-5.0.0a4-5.0.0a5.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0.0b1-5.0.0b2.sql $OPENACS_SERVICE_NAME psql -f upgrade-5.0.0b2-5.0.0b3.sql $OPENACS_SERVICE_NAME -psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME
Upgrade ACS Service Contracts manually:
[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade +psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME
Upgrade ACS Service Contracts manually:
[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade psql -f upgrade-4.7d2-4.7d3.sql $OPENACS_SERVICE_NAME -
Load acs-authentication data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME
Load acs-lang data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
if {![apm_package_installed_p acs-lang]} { +
Load acs-authentication data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME
Load acs-lang data model.
psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME
(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing:
if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang [acs_root_dir]/packages/acs-lang/acs-lang.info -lang::catalog::import -locales [list "en_US"] +lang::catalog::import -locales [list "en_US"] } if {![apm_package_installed_p acs-authentication]} { apm_package_install -enable [acs_root_dir]/packages/acs-authentication/acs-authentication.info -apm_parameter_register "UsePasswordWidgetForUsername" \ -"Should we hide what the user types in the username +apm_parameter_register "UsePasswordWidgetForUsername" \ +"Should we hide what the user types in the username field, the way we do with the password field? Set this to 1 if you are using sensitive information -such as social security number for username." \ +such as social security number for username." \ acs-kernel 0 number \ security 1 1 parameter::set_value -package_id [ad_acs_kernel_id] -parameter UsePasswordWidgetForUsername -value 0 -}
If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database. -
Upgrade other packages via the APM
- See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results, OpenACS 5.0 Upgrade Experiences.
+}
If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database. +
Upgrade other packages via the APM
+ See also these forum posts: Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results, OpenACS 5.0 Upgrade Experiences.
There are a few things you might want to do once you've upgraded. First, the acs-kernel parameters need to be set to allow HREF and IMG tags, if you want users who can edit HTML 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.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html 13 Sep 2009 23:54:41 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html 11 Dec 2010 23:36:32 -0000 1.15 @@ -1,2 +1,2 @@ - -Upgrading an OpenACS 5.0.0 or greater installation
Prev Chapter 5. Upgrading Next
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading a stock site. If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
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:
Upgrade the file system for all packages in use. Section , “Upgrading the OpenACS files”
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
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 an OpenACS 5.0.0 or greater installation
Prev Chapter 5. Upgrading Next
Upgrading an OpenACS 5.0.0 or greater installation
Upgrading a stock site. If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from OpenACS Repository"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
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:
Upgrade the file system for all packages in use. Upgrading the OpenACS files
Go to /acs-admin/install/ and click "Upgrade Your System" in "Install from local file system"
Select all of the packages you want to upgrade and proceed
After upgrade is complete, restart the server as indicated.
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.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html 17 Oct 2010 21:06:08 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html 11 Dec 2010 23:36:32 -0000 1.25 @@ -1,6 +1,6 @@ - -Upgrading the OpenACS files
Prev Chapter 5. Upgrading Next
Upgrading the OpenACS files
Chosing a Method to Upgrade your Files
OpenACS is distributed in many different ways: -
as a collection of files
as one big tarball
via CVS
via automatic download from within the APM + +Upgrading the OpenACS files
Prev Chapter 5. Upgrading Next
Upgrading the OpenACS files
Chosing a Method to Upgrade your Files
OpenACS is distributed in many different ways: +
as a collection of files
as one big tarball
via CVS
via automatic download from within the APM (package manager)

Upgrades work by first changing the file system (via any of the previous methods), and then using the APM to scan the @@ -10,29 +10,29 @@ using the last method, you can skip this page. This page describes whether or not you need to be upgrading using this page or not: - Section , “Upgrading an OpenACS 5.0.0 or greater installation” -
Methods of upgrading OpenACS files
Upgrading files for a site which is not in a CVS repository. Unpack the tarball into a new directory and copy its + Upgrading an OpenACS 5.0.0 or greater installation +
Methods of upgrading OpenACS files
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. Or just 'install software', select remote repository, and upgrade your files - from there.
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver -[$OPENACS_SERVICE_NAME web]$ tar xzf /var/tmp/openacs-5-1.tar.gz -[$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4 -[$OPENACS_SERVICE_NAME openacs-upgrade]$ exit + from there.
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME web]$ tar xzf /var/tmp/openacs-5-1.tar.gz +[$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4 +[$OPENACS_SERVICE_NAME openacs-upgrade]$ exit [root root]# su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver tar xzf /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 -exit
- Upgrading files for a site in a private CVS repository +exit
+ Upgrading files for a site in a private CVS repository
Many OpenACS site developers operate their own CVS repository to keep track of local customizations. In this section, we describe how to upgrade your local CVS repository with the latest OpenACS version, without overriding your own local customizations.
This diagram explains the basic idea. However, the labels are incorrect. Step 1(a) has been removed, and Step - 1(b) should be labelled Step 1.
Figure 5.2. Upgrading a local CVS repository
Step 0: Set up a working CVS checkout. To get your OpenACS code into your local CVS + 1(b) should be labelled Step 1.
Figure 5.2. Upgrading a local CVS repository

Step 0: Set up a working CVS checkout. To get your OpenACS code into your local CVS repository, you will set up a working CVS checkout of OpenACS. When you want to update your site, you'll update the working CVS checkout, import those changes @@ -47,69 +47,69 @@ using OpenACS 5.1,x, you will need a 5.1 checkout. That will be good for 5.1, 5.11, 5.12, and so on. But when you want to upgrade to OpenACS 5.2, you'll need to check out another - 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. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has openacs-5-1-compat.
You will want to separately check out all the + 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. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has openacs-5-1-compat.
You will want to separately check out all the packages you are using. -
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver -[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core -[$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages -[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... -[$OPENACS_SERVICE_NAME aolserver]$ cd ../.. -[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
Make sure your working CVS checkout doesn't have +
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core +[$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages +[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... +[$OPENACS_SERVICE_NAME aolserver]$ cd ../.. +[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1
Make sure your working CVS checkout doesn't have the entire CVS tree from OpenACS. A good way to check this is if it has a contrib directory. If it does, you probably checked out the entire tree. You might want to start over, remove your working CVS checkout, and try again. -
Step 1: Import new OpenACS code. -
Update CVS. Update your local CVS working checkout (unless - you just set it up).
[root root]# su - $OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 -[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd ChangeLog *.txt bin etc tcl www packages/*
Update 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/packages/openacs-5-1 -[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagename
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 -
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 +
Step 1: Import new OpenACS code. +
Update CVS. Update your local CVS working checkout (unless + you just set it up).
[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 +[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd ChangeLog *.txt bin etc tcl www packages/*
Update 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/packages/openacs-5-1 +[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -Pd packagename
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 +
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. This section should be - improved to use tags instead of the keyword yesterday!
[$OPENACS_SERVICE_NAME openacs-5.1]$ cd /var/lib/aolserver -[$OPENACS_SERVICE_NAME tmp]$ rm -rf $OPENACS_SERVICE_NAME-upgrade -[$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade -[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d $OPENACS_SERVICE_NAME-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 + improved to use tags instead of the keyword yesterday!
[$OPENACS_SERVICE_NAME openacs-5.1]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME tmp]$ rm -rf $OPENACS_SERVICE_NAME-upgrade +[$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade +[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d $OPENACS_SERVICE_NAME-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 (CVS feedback here)
The file /var/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 + command M-x sort-lines (you may have to click Ctrl-space at the beginning of the file, and go to the end, and then try 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_SERVICE_NAME-upgrade -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-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_SERVICE_NAME-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd + to your local tree.
[$OPENACS_SERVICE_NAME tmp]$ cd $OPENACS_SERVICE_NAME-upgrade +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME-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_SERVICE_NAME-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 +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]#
- Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org) -
[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd + Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org) +
[$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:
Declare a freeze on new cvs updates - ie, you cannot run cvs update - on the production site
+[$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:
Declare a freeze on new cvs updates - ie, you cannot run cvs update + on the production site
Make a manual backup of the production site in addition to the - automated backups
Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of - ETP, blogger, and other applications) into a "vendor branch" of the - $OPENACS_SERVICE_NAME CVS tree, as described in "Upgrading a local CVS repository", step 1, above. + automated backups
Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of + ETP, blogger, and other applications) into a "vendor branch" of the + $OPENACS_SERVICE_NAME CVS tree, as described in "Upgrading a local CVS repository", step 1, above. As soon as we do this, any cvs update command on production might bring new code onto the production site, which - would be bad.
Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working tree).
+ would be bad.
Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working tree).
Manually resolve any conflicts in the working upgrade tree -
Use the upgrade script and a recent backup of the production database, to ake +
Use the upgrade script and a recent backup of the production database, to ake a new upgraded database called $OPENACS_SERVICE_NAME-upgrade. Now we have a new website called $OPENACS_SERVICE_NAME-upgrade. -
+
Test the $OPENACS_SERVICE_NAME-upgrade site -
If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade.
Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page.
Repeat the upgrade with the most recent database
Test the that the new site is functional. If so, change the upgraded site to respond to +
If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade.
Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page.
Repeat the upgrade with the most recent database
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 an OpenACS 5.0.0 or greater installation 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.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/upgrade-overview.html 17 Oct 2010 21:06:08 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html 11 Dec 2010 23:36:32 -0000 1.25 @@ -1,7 +1,7 @@ - -Overview
Prev Chapter 5. Upgrading Next
Overview
Starting with Version 4.5, all OpenACS core packages support + +Overview
Prev Chapter 5. Upgrading Next
Overview
Starting with Version 4.5, all OpenACS core packages support automatic upgrade. That means that, if you have OpenACS 4.5 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:
Browse to the Installer.
Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server. After restarting the server again, the upgrade is complete.
Figure 5.1. Upgrading with the APM
It's always a good idea to precede an upgrade attempt with a snapshot backup.
Table 5.1. Assumptions in this section
name of OpenACS user $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:
Browse to the Installer.
Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.
The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server. After restarting the server again, the upgrade is complete.
Figure 5.1. Upgrading with the APM

It's always a good idea to precede an upgrade attempt with a snapshot backup.
Table 5.1. Assumptions in this section
name of OpenACS user $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-supporting.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.html,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 17 Oct 2010 21:06:08 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 11 Dec 2010 23:36:32 -0000 1.18 @@ -1,6 +1,6 @@ - -Upgrading Platform components
Prev Chapter 5. Upgrading Next
Upgrading Platform components
Upgrading OpenFTS from 0.2 to 0.3.2
OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.
Uninstall the old OpenFTS Engine from the $OPENACS_SERVICE_NAME database.
Browse to http://yourserver/openfts. -
Click Administration.
Click Drop OpenFTS Engine
Build and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.)
cd /usr/local/src/ + +Upgrading Platform components
Prev Chapter 5. Upgrading Next
Upgrading Platform components
Upgrading OpenFTS from 0.2 to 0.3.2
OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.
Uninstall the old OpenFTS Engine from the $OPENACS_SERVICE_NAME database.
Browse to http://yourserver/openfts. +
Click Administration.
Click Drop OpenFTS Engine
Build and install the new OpenFTS driver and supporting tcl procedures. (This section of shell code is not fully documented; please exercise care.)
cd /usr/local/src/ tar xzf /var/tmp/Search-OpenFTS-tcl-0.3.2.tar.gz chown -R root.root Search-OpenFTS-tcl-0.3.2/ cd Search-OpenFTS-tcl-0.3.2/ @@ -18,22 +18,22 @@ cd tsearch/ make make install - exit
In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.
[root root]# su - $OPENACS_SERVICE_NAME - [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql + exit
In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.
[root root]# su - $OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql CREATE CREATE - [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql + [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql BEGIN CREATE (~30 more lines) - [$OPENACS_SERVICE_NAME dev]$ exit + [$OPENACS_SERVICE_NAME dev]$ exit [root root]# su - $OPENACS_SERVICE_NAME psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql -exit
OPTIONAL: Install the new OpenFTS Engine. If you want to upgrade the OpenFTS Engine, do these +exit
OPTIONAL: Install the new OpenFTS Engine. If you want to upgrade the OpenFTS Engine, do these steps. (You must have already upgraded the OpenFTS driver to - 0.3.2.)
Browse to http://yourserver/admin/site-map
On the openfts line, click on set parameters.
Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/
Click Set Parameters
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Browse to http://yourserver/openfts
Click Administration.
Click Initialize OpenFTS Engine
Upgrading from PostGreSQL 7.2 to 7.3
An OpenACS database created in PostGreSQL 7.2 will not + 0.3.2.)
Browse to http://yourserver/admin/site-map
On the openfts line, click on set parameters.
Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/
Click Set Parameters
[root root]# restart-aolserver $OPENACS_SERVICE_NAME
Browse to http://yourserver/openfts
Click Administration.
Click Initialize OpenFTS Engine
Upgrading from PostGreSQL 7.2 to 7.3
An OpenACS database created in PostGreSQL 7.2 will not work correctly in PostGreSQL 7.3. This is because 7.2 truncates function names to 31 characters, but 7.3 does not. This does not cause problems in 7.2, because truncation occurs both at @@ -43,12 +43,12 @@ are not, and so they don't match. Also some functions use casting commands that no longer work in 7.3 and these functions must be recreated.
- To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example:
Back up the database as per PostgreSQL.
Run the upgrade script on the backup file.
[root root]# su - $OPENACS_SERVICE_NAME - [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin - [$OPENACS_SERVICE_NAME bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ + To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example:
Back up the database as per ???.
Run the upgrade script on the backup file.
[root root]# su - $OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin + [$OPENACS_SERVICE_NAME bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ - /var/lib/aolserver/$OPENACS_SERVICE_NAME+ /var/lib/aolserver/$OPENACS_SERVICE_NAME ================================================================== looking for function acs_object__check_object_ancest in oacs grep result: /var/lib/aolserver/aufrecht-dev/packages/acs-kernel/sql/postgresql/acs-objects-create.sql:create function acs_object__check_object_ancestors (integer,integer,integer) @@ -57,23 +57,23 @@ (many lines omitted) [$OPENACS_SERVICE_NAME bin]$ -
Use perl to replace timestamp with timestamptz in the dump file. See example perl code in step two in /contrib/misc/upgrade_4.6_to_5.0.sh
Create a new user for PostgreSQL 7.3.x, as per the +
Use perl to replace timestamp with timestamptz in the dump file. See example perl code in step two in /contrib/misc/upgrade_4.6_to_5.0.sh
Create a new user for PostgreSQL 7.3.x, as per the Postgres installation guide. Keep in mind that your installation location is different, and your startup script (/etc/init.d/postgres73 should be named differently. You might even need to edit that file to make the paths - correct). You'll also need to add export - PGPORT=5434 to the .bashrc and/or + correct). You'll also need to add export + PGPORT=5434 to the .bashrc and/or .bash_profile for the postgres73 user. -
Install PostgreSQL 7.3.x. Note that you PostgreSQL +
Install PostgreSQL 7.3.x. Note that you PostgreSQL must listen on a different port in order to work correctly, so you'll need to edit the configuration file (/usr/local/pgsql73/data/postgresql.conf) and change the port (to 5433, say). create a second postgres user to differentiate between the two postgres installs. When you do ./configure, you'll need to include --prefix=$HOME to ensure that it is installed in the - postgres73 user's home directory.
Change the path in + postgres73 user's home directory.
Change the path in $OPENACS_SERVICE_NAME's .bashrc or .bash_profile (or both) files to reflect the new postgres73 - user directory. Also add in the PGPORT.
Restore the database from dump as per the recovery instructions.
Prev Home Next
Upgrading the OpenACS files Up Chapter 6. Production Environments
docs@openacs.org
View comments on this page at openacs.org + user directory. Also add in the PGPORT.
Restore the database from dump as per the recovery instructions.
Prev Home Next
Upgrading the OpenACS files Up Chapter 6. Production Environments
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/upgrade.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v diff -u -N -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/upgrade.html 13 Sep 2009 23:54:41 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/upgrade.html 11 Dec 2010 23:36:32 -0000 1.28 @@ -1,5 +1,5 @@ - -Chapter 5. Upgrading
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 an OpenACS 5.0.0 or greater installation
Upgrading the OpenACS files
Upgrading Platform components
by Joel Aufrecht
+ +Chapter 5. Upgrading
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 an OpenACS 5.0.0 or greater installation
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/uptime.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/uptime.html,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/uptime.html 13 Sep 2009 23:54:41 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/uptime.html 11 Dec 2010 23:36:32 -0000 1.12 @@ -1,2 +1,2 @@ - -External uptime validation
Prev Chapter 6. Production Environments Next
External uptime validation
The OpenACS uptime site can monitor your site and send you an email whenever your site fails to respond. If you test the url http://yourserver.test/SYSTEM/dbtest.tcl, you should get back the string success.
Prev Home Next
Set up Log Analysis Reports Up Diagnosing Performance Problems
docs@openacs.org
View comments on this page at openacs.org + +External uptime validation
Prev Chapter 6. Production Environments Next
External uptime validation
The OpenACS uptime site can monitor your site and send you an email whenever your site fails to respond. If you test the url http://yourserver.test/SYSTEM/dbtest.tcl, you should get back the string success.
Prev Home Next
Set up Log Analysis Reports Up Diagnosing Performance Problems
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/variables.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v diff -u -N -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/variables.html 17 Oct 2010 21:06:08 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/variables.html 11 Dec 2010 23:36:32 -0000 1.28 @@ -1,15 +1,15 @@ - -Variables
Prev Chapter 12. Engineering Standards Next
Variables
Date and Time Variables
($Id$)
By joel@aufrecht.org
+ +Variables
Prev Chapter 11. Engineering Standards Next
Variables
Date and Time Variables
($Id$)
By joel@aufrecht.org
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff.
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 11.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, ... ... } { set mydate_ansi [lc_time_system_to_conn $mydate_ansi] - set mydate_pretty [lc_time_fmt $mydate_ansi "%x %X"] + set mydate_pretty [lc_time_fmt $mydate_ansi "%x %X"] } -
Prev Home Next
PL/SQL Standards Up Automated Testing
docs@openacs.org
View comments on this page at openacs.org +

Prev Home Next
PL/SQL Standards Up Automated Testing
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v diff -u -N -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/win2k-installation.html 17 Oct 2010 21:06:08 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/win2k-installation.html 11 Dec 2010 23:36:32 -0000 1.47 @@ -1,253 +1,253 @@ - -OpenACS Installation Guide for Windows2000
Prev Chapter 3. Complete Installation Next
OpenACS Installation Guide for Windows2000
by Matthew Burke and Curtis Galloway
+ +OpenACS Installation Guide for Windows2000
Prev Chapter 3. Complete Installation Next
OpenACS Installation Guide for Windows2000
by Matthew Burke and Curtis Galloway
OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -
NOTE: These instructions were +
NOTE: These instructions were valid for ACS v4, but have not been tested with OpenACS and the ArsDigita binary distributions are no longer available. Currently (10/2003), the best option to get OpenACS 5.6.0 running on Windows - is to use VMware and John - Sequeira's Oasis VM + is to use VMware and John + Sequeira's Oasis VM distribution -
Source: http://openacs.org/projects/openacs/download
Bug reports: http://openacs.org/bugtracker/openacs
Philosophy: http://photo.net/wtr/thebook/community +
Source: http://openacs.org/projects/openacs/download
Bug reports: http://openacs.org/bugtracker/openacs
Philosophy: http://photo.net/wtr/thebook/community (the community chapter of Philip and Alex's Guide to Web - Publishing)
Technical background: http://photo.net/wtr/thebook/
Overview
+ Publishing)
Technical background: http://photo.net/wtr/thebook/
Overview
With the recent release of a win32 version of AOLserver, it is now possible to run the OpenACS on Windows2000 and Windows98. This document explains the steps necessary to get the OpenACS installed and running on your machine.
Note:
We do not recommend running a production server on Windows98. But the platform is more than sufficient for working - the problem sets and + the problem sets and for getting a feel for the OpenACS.
You'll need to use the ArsDigita binary distribution of AOLserver for the Win32 platform, which contains patches for several problems we - have come across in the default AOLserver binary distribution. See the ArsDigita AOLserver 3 distribution page for - details.
You can download the binary distribution from the ArsDigita download page - under "ArsDigita AOLserver 3 Binary Distribution for Win32." + have come across in the default AOLserver binary distribution. See the ArsDigita AOLserver 3 distribution page for + details.
You can download the binary distribution from the ArsDigita download page + under "ArsDigita AOLserver 3 Binary Distribution for Win32." Please read the release notes in the distribution for configuration notes - specific to the version you are downloading.
Prerequisites
Windows 2000 or Windows 98
WinZip or any tool that can - extract gzipped/tarred archives.
zsh (free; - included in the binary distribution). If this link is broken try http://www.zsh.org.
Oracle 8 relational database - management system
AOLserver (free)
+ specific to the version you are downloading.
Prerequisites
Windows 2000 or Windows 98
WinZip or any tool that can + extract gzipped/tarred archives.
zsh (free; + included in the binary distribution). If this link is broken try http://www.zsh.org.
Oracle 8 relational database + management system
AOLserver (free)
Oracle driver for AOLserver (free)
It is helpful if you have Oracle interMedia Text for full-text searches. We're also trying to make our system work with the PLS System, - available free from http://www.pls.com. -
Although the zsh shell is the only command-line tool + available free from http://www.pls.com. +
Although the zsh shell is the only command-line tool required to install the OpenACS, if you are a UNIX person used to typing - ls instead of dir you'll get along much - better with the Cygwin toolkit from RedHat (available at http://sourceware.cygnus.com/cygwin). + ls instead of dir you'll get along much + better with the Cygwin toolkit from RedHat (available at http://sourceware.cygnus.com/cygwin). This is a development library and set of tools that gives you a very UNIX-like environment under Windows. In particular, it includes - bash, gzip and tar, which you can - use to perform the OpenACS installation instead of WinZip and zsh.
Your Oracle installation
- When you install Oracle, a good rule of thumb is "every default - setting is wrong." We will not discuss Oracle configuration here + bash, gzip and tar, which you can + use to perform the OpenACS installation instead of WinZip and zsh.
Your Oracle installation
+ When you install Oracle, a good rule of thumb is "every default + setting is wrong." We will not discuss Oracle configuration here except to mention that the OpenACS requires Oracle's NLS_DATE_FORMAT parameter be set to 'YYYY-MM-DD'. Fixing this depends on whether Oracle Administration Assistant for Windows NT (yes, that's Windows
NT
) will run on your machine or not (in some cases, it will complain about Microsoft Managment - Console not being installed).
If it runs on your machine, proceed as follows:
Run Oracle Administration Assistant for Windows NT
Navigate using the Explorer-style control in the left panel and - select the Oracle Home for the database you wish to use.
Bring up its properties dialog and add a parameter NLS_DATE_FORMAT + Console not being installed).
If it runs on your machine, proceed as follows:
Run Oracle Administration Assistant for Windows NT
Navigate using the Explorer-style control in the left panel and + select the Oracle Home for the database you wish to use.
Bring up its properties dialog and add a parameter NLS_DATE_FORMAT with value 'YYYY-MM-DD' (without the - quotes)
Verify the date format by logging into the database using SQL Plus - and run the following query: select sysdate from - dual;
Otherwise you will need to perform a little registry surgery as - follows:
Run regedit and navigate down the registry keys to - HKEY_LOCAL_MACHINE\Software\ORACLE.
- Choose the appropriate subtree; this will be HOME0 if + quotes)
Verify the date format by logging into the database using SQL Plus + and run the following query: select sysdate from + dual;
Otherwise you will need to perform a little registry surgery as + follows:
Run regedit and navigate down the registry keys to + HKEY_LOCAL_MACHINE\Software\ORACLE.
+ Choose the appropriate subtree; this will be HOME0 if you only have on einstallation of Oracle.
If you are an Oracle achiever and have more than one Oracle - installation on your machine, you will see HOME0, HOME1, - HOME2, etc. Choose the subtree that corresponds to the + installation on your machine, you will see HOME0, HOME1, + HOME2, etc. Choose the subtree that corresponds to the Oracle installtion you wish to use with the OpenACS.
-
If the NLS_DATE_FORMAT key is already present, +
If the NLS_DATE_FORMAT key is already present, double-click on its value and change it to 'YYYY-MM-DD' (without the quotes). If the key does not - exist, choose Edit->New->String Value from the menu - and type NLS_DATE_FORMAT for the name of the new value to - create it. Then double-click on the empty value to change it.
Verify the date format by logging into the database using SQL Plus - and run the following query: select sysdate from - dual;
For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips - or search the OpenACS forums. One other note: the "nuke a user" admin page and - Intermedia won't run unless you set open_cursors = 500 - for your database.
The ArsDigita binary installation
- Extract the ArsDigita AOLserver distribution onto the C: - drive into the default aol30 directory. You can install it + exist, choose Edit->New->String Value from the menu + and type NLS_DATE_FORMAT for the name of the new value to + create it. Then double-click on the empty value to change it.
Verify the date format by logging into the database using SQL Plus + and run the following query: select sysdate from + dual;
For more information on Oracle configuration look at http://photo.net/wtr/oracle-tips + or search the OpenACS forums. One other note: the "nuke a user" admin page and + Intermedia won't run unless you set open_cursors = 500 + for your database.
The ArsDigita binary installation
+ Extract the ArsDigita AOLserver distribution onto the C: + drive into the default aol30 directory. You can install it on any drive, but it will make your life easier if you keep the AOLserver binary and your OpenACS instance on the same drive. For the rest of these - instructions, we'll assume that you used drive C:. -
Untar the OpenACS
- We recommend rooting webserver content in c:\web. Since most + instructions, we'll assume that you used drive C:. +
Untar the OpenACS
+ We recommend rooting webserver content in c:\web. Since most servers these days are expected to run multiple services from multiple IP - addresses, each server gets a subdirectory from c:\web. For - example, http://scorecard.org would be rooted at - c:\web\scorecard on one of our machines and if - http://jobdirect.com were on the same box then it would be - at c:\web\jobdirect. + addresses, each server gets a subdirectory from c:\web. For + example, http://scorecard.org would be rooted at + c:\web\scorecard on one of our machines and if + http://jobdirect.com were on the same box then it would be + at c:\web\jobdirect.
For the sake of argument, we're going to assume that your service - is called "yourdomain", is going to be at - http://yourdomain.com and is rooted at - c:\web\yourdomain in the Windows 2000 file system. Note that + is called "yourdomain", is going to be at + http://yourdomain.com and is rooted at + c:\web\yourdomain in the Windows 2000 file system. Note that you'll find our definitions files starting out with - "yourdomain.com".
download the OpenACS (see above) into - c:\temp\acs.tar.gz
use WinZip (or equivalent) to extract the files to - c:\web\yourdomain
- You'll now find that c:\web\yourdomain\www contains the - document root and c:\web\yourdomain\tcl contains Tcl scripts + "yourdomain.com".
download the OpenACS (see above) into + c:\temp\acs.tar.gz
use WinZip (or equivalent) to extract the files to + c:\web\yourdomain
+ You'll now find that c:\web\yourdomain\www contains the + document root and c:\web\yourdomain\tcl contains Tcl scripts that are loaded when the AOLserver starts up. -
Feeding Oracle the Data Model
+
Feeding Oracle the Data Model
The entire server will behave in an unhappy manner if it connects to Oracle and finds that, for example, the users table does not exist. Thus you need to connect to Oracle as whatever user the AOLserver will connect as, and feed Oracle the table definitions. -
- load the states, country_codes and - counties tables using the load-geo-tables - shell script in the c:\web\yourdomain\www\install +
+ load the states, country_codes and + counties tables using the load-geo-tables + shell script in the c:\web\yourdomain\www\install directory. You will need to open a console window and run
zsh load-geo-tables foo/foopassword
- You most likely will see a slew of "Commit point reached . . . - " messages. This does not indicate a problem. + You most likely will see a slew of "Commit point reached . . . + " messages. This does not indicate a problem. -
- cd to c:\web\yourdomain\www\doc\sql and feed Oracle the +
+ cd to c:\web\yourdomain\www\doc\sql and feed Oracle the .sql files that you find there. There is a meta-loader file, load-data-model.sql, that includes the other files in the proper order. To use it, open a console window and run
sqlplus foo/foopassword < load-data-model.sql -
+
If you have interMedia installed, while still in - c:\web\yourdomain\www\doc\sql, run + c:\web\yourdomain\www\doc\sql, run
zsh load-site-wide-search foo foopassword ctxsys-password
- Note that there's no slash between foo and - foopassword here. The third argument, - ctxsys-password, is the password for interMedia + Note that there's no slash between foo and + foopassword here. The third argument, + ctxsys-password, is the password for interMedia Text's special ctxsys user. -
Configuring AOLserver
You will need two configuration files. The first is a Tcl file with +
Configuring AOLserver
You will need two configuration files. The first is a Tcl file with configuration information for AOLserver. This should be called - yourdomain and should be located in - c:\aolserve3_0. The second is an .ini file that configures - the OpenACS and is discussed below. Note that pathnames in - yourdomain must use forward slashes rather than the Windows - back slashes. This is also true for the .ini file.
The following items must be defined in yourdomain:
three database pools: main, subquery, and log. They must be named - as such. The default pool will be "main".
the auxconfig directory which contains the .ini file: - c:\web\yourdomain\parameters
the pageroot: c:\web\yourdomain\www
the directory containing the TclLibrary: - c:\web\yourdomain\tcl
- You can use our template file as a starting + yourdomain and should be located in + c:\aolserve3_0. The second is an .ini file that configures + the OpenACS and is discussed below. Note that pathnames in + yourdomain must use forward slashes rather than the Windows + back slashes. This is also true for the .ini file.
The following items must be defined in yourdomain:
three database pools: main, subquery, and log. They must be named + as such. The default pool will be "main".
the auxconfig directory which contains the .ini file: + c:\web\yourdomain\parameters
the pageroot: c:\web\yourdomain\www
the directory containing the TclLibrary: + c:\web\yourdomain\tcl
+ You can use our template file as a starting point (you'll need to save this file with a rather than .txt extension). -
Configuring OpenACS itself
+
Configuring OpenACS itself
If you want a system that works, go to - c:\web\yourdomain\parameters and copy ad.ini to - yourdomain.ini (or any other name different from - ad.ini). You don't actually have to delete - ad.ini. -
Each section of yourdomain.ini has a hardcoded - "yourservername" in the name (e.g. - [ns/server/yourservername/acs]). This means that the OpenACS + c:\web\yourdomain\parameters and copy ad.ini to + yourdomain.ini (or any other name different from + ad.ini). You don't actually have to delete + ad.ini. +
Each section of yourdomain.ini has a hardcoded + "yourservername" in the name (e.g. + [ns/server/yourservername/acs]). This means that the OpenACS will ignore your configuration settings unless your AOLserver name - happens to be "yourservername". Therefore you must go through - yourdomain.ini and change "yourservername" to + happens to be "yourservername". Therefore you must go through + yourdomain.ini and change "yourservername" to whatever you're calling this particular AOLserver (look at the - server name in the nsd file for a reference).
Unless you want pages that advertise a community called - "Yourdomain Network" owned by - "webmaster@yourdomain.com", you'll probably want to edit - the text of yourdomain.ini to change system-wide parameters. + server name in the nsd file for a reference).
Unless you want pages that advertise a community called + "Yourdomain Network" owned by + "webmaster@yourdomain.com", you'll probably want to edit + the text of yourdomain.ini to change system-wide parameters. If you want to see how some of these are used, a good place to look is - c:\web\yourdomain\tcl\ad-defs. The Tcl function, - ad_parameter, is used to grab parameter values from the .ini - file.
Starting the Service
+ c:\web\yourdomain\tcl\ad-defs. The Tcl function, + ad_parameter, is used to grab parameter values from the .ini + file.
Starting the Service
Now you're ready to start things up. Before installing as a Windows service, you might want to test the setup for configuration errors. Open - up a console window and go to c:\aol30. Then run + up a console window and go to c:\aol30. Then run
bin\nsd -ft yourdomain.tcl
This will print all the AOLserver messages to the console so you can see them.
Try to connect to your new server with a web browser. If you see the - message "Error in serving group pages", you probably forgot to - copy the ad.ini file in c:\web\yourdomain\parameters If + message "Error in serving group pages", you probably forgot to + copy the ad.ini file in c:\web\yourdomain\parameters If everything seems ok, you can kill the server with Control-c and then issue the following command to install as a Windows service:
bin\nsd -I -s yourdomain -t yourdomain.tcl
You can now configure error recovery and other Windows aspects of the service from the Services control panel. If you make further changes to - yourdomain or yourdomain.ini you should stop + yourdomain or yourdomain.ini you should stop and start the service from the Services control panel. -
Configuring Permissions
+
Configuring Permissions
Now, you need to protect the proper administration directories of the OpenACS. You decide the policy although we recommend requiring the admin directories be accessible only via an SSL connection. Here are the directories to consider protecting: -
/doc (or at least /doc/sql/ since some AOLserver configurations - will allow a user to execute SQL files)
/admin
any private admin dirs for a module you might have written that are - not underneath the /admin directory
Adding Yourself as a User and Making Yourself a Sysadmin
+
/doc (or at least /doc/sql/ since some AOLserver configurations + will allow a user to execute SQL files)
/admin
any private admin dirs for a module you might have written that are + not underneath the /admin directory
Adding Yourself as a User and Making Yourself a Sysadmin
OpenACS will define two users: system and anonymous. It will also define a user group of system administrators. You'll want to add yourself as a user (at /register/ ) and then add yourself as as member of the site-wide administration group. Start by logging out as yourself and logging in as the system user (email of - "system"). Change the system user's password. Visit the - https://yourservername.com/admin/ug/ directory and add your + "system"). Change the system user's password. Visit the + https://yourservername.com/admin/ug/ directory and add your personal user as a site-wide administrator. Now you're bootstrapped!
If you do not know what the system user's password is connect to Oracle using SQL Plus and run the following query:
select password from users where last_name = 'system'; -
Closing Down Access
- The OpenACS ships with a user named "anonymous" (email - "anonymous") to serve as a content owner. If you're +
Closing Down Access
+ The OpenACS ships with a user named "anonymous" (email + "anonymous") to serve as a content owner. If you're operating a restricted-access site, make sure to change the anonymous user's password. In recent versions of the OpenACS you cannot log into - "anonymous" because the account does not have a valid user + "anonymous" because the account does not have a valid user state. Log in as a sysadmin and change the anonymous user's password - from https://yourservername/admin/users. You should read the - documentation for user registration and + from https://yourservername/admin/users. You should read the + documentation for user registration and access control and decide what the appropriate user state is for anonymous on your site. -
Where to Find What
+
Where to Find What
A few pointers: -
the /register directory contains the login and registration +
the /register directory contains the login and registration scripts. You can easily redirect someone to /register/index to have - them login or register.
the /pvt directory is for user-specific pages. They can only be - accessed by people who have logged in.
Making sure that it works
- Run the acceptance tests in /doc/acceptance-test -
Running Multiple Instances of the OpenACS
+ them login or register.
the /pvt directory is for user-specific pages. They can only be + accessed by people who have logged in.
Making sure that it works
+ Run the acceptance tests in /doc/acceptance-test +
Running Multiple Instances of the OpenACS
You can run multiple instances of the OpenACS on a physical machine but they must each be set up as a separate Windows service. Each instance of the OpenACS must have its own: -
Oracle tablespace and a user account with the appropriate +
Oracle tablespace and a user account with the appropriate permissions on that tablespace. Each of these tablespaces must have the - OpenACS data model loaded.
file with the appropriate settings including server name, - auxconfig, ipaddress, and port.
Copy of the acs files in an appropriate directory under - c:\web.
Suppose you wish to run two services: lintcollectors.com and - iguanasdirect.com. You would need the following: -
an Oracle tablespace, lintcollectors with a user - lintcollectors and password secretlint
an Oracle tablespace, iguanasdirect with a user - iguanasdirect and password secretiguanas
For each of these tablespaces/users you would load the OpenACS data model as - described above. Then in c:\aolserver3_0 - create files for each service, i.e. lintcollectors and - iguanasdirect. These files would point to their respective - pageroots, c:\web\lintcollectors\www and - c:\web\iguanasdirect\www; their respective auxconfigdirs, - c:\web\lintcollectors\parameters and - c:\web\iguanasdirect\parameters; etc. In the respective - auxconfigdirs would be the files lintcollectors.ini and - iguanasdirect.ini. -
Now open a console window and go to c:\aol30. You'll + OpenACS data model loaded.
file with the appropriate settings including server name, + auxconfig, ipaddress, and port.
Copy of the acs files in an appropriate directory under + c:\web.
Suppose you wish to run two services: lintcollectors.com and + iguanasdirect.com. You would need the following: +
an Oracle tablespace, lintcollectors with a user + lintcollectors and password secretlint
an Oracle tablespace, iguanasdirect with a user + iguanasdirect and password secretiguanas
For each of these tablespaces/users you would load the OpenACS data model as + described above. Then in c:\aolserver3_0 + create files for each service, i.e. lintcollectors and + iguanasdirect. These files would point to their respective + pageroots, c:\web\lintcollectors\www and + c:\web\iguanasdirect\www; their respective auxconfigdirs, + c:\web\lintcollectors\parameters and + c:\web\iguanasdirect\parameters; etc. In the respective + auxconfigdirs would be the files lintcollectors.ini and + iguanasdirect.ini. +
Now open a console window and go to c:\aol30. You'll start up the two services as follows:
bin\nsd -I -s lintcollectors -t lintcollectors.tcl bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl
In the services control panel you should see two services: - AOLserver-lintcollectors and - AOLserver-iguanasdirect. + AOLserver-lintcollectors and + AOLserver-iguanasdirect.
($Id$)
Prev Home Next
Install OpenACS 5.6.0 Up OpenACS Installation Guide for Mac OS X
docs@openacs.org
View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml,v diff -u -N -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 17 Jul 2006 05:38:37 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/i18n.xml 11 Dec 2010 23:36:32 -0000 1.26 @@ -493,14 +493,14 @@ - + You will now be walked through all of the selected adp pages. The UI shows you the intended changes and lets you edit or cancel them key by key. - + @@ -699,7 +699,7 @@ 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: @@ -937,13 +937,13 @@ - + While in Translator mode, a list of all message keys appears at the bottom of each page. - + @@ -954,7 +954,7 @@ - + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml,v diff -u -N -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml 5 Aug 2006 05:18:21 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/permissions.xml 11 Dec 2010 23:36:32 -0000 1.17 @@ -323,7 +323,7 @@
- +
Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml 17 Jul 2006 05:38:37 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/rp.xml 11 Dec 2010 23:36:32 -0000 1.12 @@ -31,7 +31,7 @@ - + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v diff -u -N -r1.48 -r1.49 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 12 Jul 2009 01:08:30 -0000 1.48 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 11 Dec 2010 23:36:32 -0000 1.49 @@ -147,7 +147,7 @@ Upgrading a local CVS repository - + @@ -1249,7 +1249,7 @@ .LRN home page with table-based layout - + A sample of the HTML code (full source) @@ -1281,7 +1281,7 @@ .LRN Home with CSS-based layout - + A sample of the HTML code (full source) @@ -1297,7 +1297,7 @@ If the CSS is removed from the file, it looks somewhat different: - + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml,v diff -u -N -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml 17 Jul 2006 07:38:45 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml 11 Dec 2010 23:36:32 -0000 1.18 @@ -48,7 +48,7 @@ Tutorial Data Model - + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml,v diff -u -N -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml 17 Jul 2006 08:02:50 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml 11 Dec 2010 23:36:32 -0000 1.19 @@ -25,7 +25,7 @@ Page Map - + Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v diff -u -N -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 17 Jul 2006 08:02:50 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 11 Dec 2010 23:36:32 -0000 1.20 @@ -17,7 +17,7 @@ The intended page map - + Index: openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml,v diff -u -N -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 17 Jul 2006 05:38:37 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/xml/engineering-standards/docbook-primer.xml 11 Dec 2010 23:36:32 -0000 1.14 @@ -1238,10 +1238,10 @@ <mediaobject> <imageobject> - <imagedata fileref="../images/rp-flow.gif" format="GIF" align="center"/> + <imagedata fileref="images/rp-flow.gif" format="GIF" align="center"/> </imageobject> <imageobject> - <imagedata fileref="../images/rp-flow.eps" format="EPS" align="center"/> + <imagedata fileref="images/rp-flow.eps" format="EPS" align="center"/> </imageobject> <textobject> <phrase>This is an image of the flow in the Request Processor</phrase> Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml,v diff -u -N -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml 17 Jul 2006 05:38:37 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml 11 Dec 2010 23:36:32 -0000 1.12 @@ -226,7 +226,7 @@ Site Templates - + @@ -286,7 +286,7 @@ Granting Permissions - + @@ -298,7 +298,7 @@ Granting Permissions in 5.0 - + Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml,v diff -u -N -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml 17 Jul 2006 05:38:37 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml 11 Dec 2010 23:36:32 -0000 1.30 @@ -367,7 +367,7 @@ Multiple-server configuration - + @@ -499,23 +499,23 @@ Simple A/B Deployment - Step 1 - +
Simple A/B Deployment - Step 2 - +

Simple A/B Deployment - Step 3 - +
@@ -526,23 +526,23 @@ Complex A/B Deployment - Step 1 - +
Complex A/B Deployment - Step 2 - +

Complex A/B Deployment - Step 3 - +
@@ -727,7 +727,7 @@ Query Analysis example - + Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml,v diff -u -N -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml 17 Jul 2006 05:38:38 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml 11 Dec 2010 23:36:32 -0000 1.17 @@ -24,7 +24,7 @@ Backup and Recovery Strategy - + Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml,v diff -u -N -r1.39 -r1.40 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 17 Jul 2006 05:38:38 -0000 1.39 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 11 Dec 2010 23:36:32 -0000 1.40 @@ -45,7 +45,7 @@ Upgrading with the APM - + @@ -393,7 +393,7 @@ Upgrading a local CVS repository - + Index: openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml,v diff -u -N -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml 17 Jul 2006 05:38:38 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/apm-design.xml 11 Dec 2010 23:36:32 -0000 1.10 @@ -206,7 +206,7 @@ - + Index: openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml,v diff -u -N -r1.3 -r1.4 --- openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml 17 Jul 2006 05:38:38 -0000 1.3 +++ openacs-4/packages/acs-core-docs/www/xml/kernel/ext-auth.xml 11 Dec 2010 23:36:32 -0000 1.4 @@ -83,7 +83,7 @@ Conceptual Pictures Authentication: - + Account Management (NO PICTURE YET)

Prev	Appendix B. Install additional supporting software	Next

Prev	Appendix B. Install additional supporting software	Next

Prev	Appendix B. Install additional supporting software	Next

Prev	Appendix B. Install additional supporting software	Next

Prev	Chapter 3. Complete Installation	Next

Prev	Chapter 3. Complete Installation	Next

Administrator's Guide

Part II. Administrator's Guide

For OpenACS Package Developers

Part III. For OpenACS Package Developers

For OpenACS Platform Developers

Part IV. For OpenACS Platform Developers

Install Analog web file analyzer

Install Analog web file analyzer

Set up Log Analysis Reports

Set up Log Analysis Reports

Install AOLserver 3.3oacs1

Install AOLserver 3.3oacs1

Install AOLserver 4

Install AOLserver 4

Package Manager Design

Package Manager Design

Essentials

Introduction

Essentials

Introduction

Historical Considerations

Historical Considerations

Competitive Analysis

Competitive Analysis

Design Tradeoffs

Design Tradeoffs

API

API

Data Model Discussion

Data Model Discussion

User Interface

User Interface

Configuration/Parameters

Configuration/Parameters

Future Improvements/Areas of Likely Change

Future Improvements/Areas of Likely Change

Authors

Revision History

Authors

Revision History

Package Manager Requirements

Package Manager Requirements

Introduction

Introduction

Vision Statement

Vision Statement

System Overview

System Overview

Use-cases and User-scenarios

Use-cases and User-scenarios

Related Links

Requirements: Data Model

Related Links

Requirements: Data Model

Requirements: API

Requirements: API

Requirements: Security

Requirements: Security

Requirements: The User Interface

Requirements: The User Interface

Requirements: The Developer's Interface

Requirements: The Developer's Interface

Requirements: The Site-Wide Administrator's Interface

Requirements: The Site-Wide Administrator's Interface

Requirements: The Sub-Site Administrator's Interface

Requirements: The Sub-Site Administrator's Interface

Implementation notes

Implementation notes

Revision History

Revision History

Automated Testing

Automated Testing

Bootstrapping OpenACS

Bootstrapping OpenACS

The Big Picture

The Big Picture

The Startup Process

The Startup Process

Chapter 3. Complete Installation

Chapter 3. Complete Installation

CVS Guidelines -
Prev Chapter 11. Engineering Standards Next
- CVS Guidelines -
($Id$)
+

+ Each OpenACS package (i.e., directory in `openacs-4/packages/`) is also aliased as a module of the same name. +

The Bell Tolls for `set_variables_after_query`

The Bell Tolls for `set_variables_after_query`