Part�II.�Administrator's Guide

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

Prev		Next

Prev		Next

Prev		Next

Prev	Chapter�6.�Production Environments	Next

Prev	Chapter�6.�Production Environments	Next

Prev	Chapter�10.�Advanced Topics	Next

Prev	Chapter�10.�Advanced Topics	Next

Appendix�D.�Using CVS with an OpenACS Site

By Joel Aufrecht

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

Prev	Part�III.�For OpenACS Package Developers	Next

Appendix�D.�Using CVS with an OpenACS Site

By Joel Aufrecht

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

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

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

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

[root root]# mkdir /cvsroot/service0
 [root root]# chown service0.service0 /cvsroot/service0
@@ -59,4 +59,4 @@
 su - service0
 cd /var/lib/aolserver
 cvs checkout service0
-exit

If the service starts correctly, come back and remove the temporary copy of the uploaded files.

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

docs@openacs.org

View comments on this page at openacs.org +exit

If the service starts correctly, come back and remove the temporary copy of the uploaded files.

Prev	Home	Next
Translator's Guide	Up	Part�IV.�For OpenACS Platform Developers

docs@openacs.org

View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -N -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 4 Mar 2004 14:09:21 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 22 Mar 2004 11:50:28 -0000 1.33 @@ -36,7 +36,7 @@ In order to separate content and presentation, all OpenACS documentation will be marked up to conform to the DocBook XML DTD - + This enables us to publish in a variety of formats and relieves each contributor of the burden of presentation, freeing him to focus on content and sharing knowledge. @@ -57,7 +57,7 @@ list of elements and use more exotic features in your documents. The list is made up of SGML-elements but basically the same elements are valid in the XML DTD as long as you remember to: - +

Always close your tags with corresponding end-tags and to not use other tag minimization @@ -106,7 +106,7 @@ The documentation for each package will make up a little "book" that is structured like this - examples are emphasized: - +
```
     book                        : Docs for one package - templating
@@ -130,20 +130,20 @@
       sources of these DocBook documents
       to get an idea of how they are tied together.
     
```

Headlines, Sections

- + Given that your job starts at the sect1-level, all your documents should open with a <sect1>-tag and end with the corresponding </sect1>.

- + You need to feed every <sect1> two attributes. The first attribute, id, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about links in the section called “Links”). The value of id has to be unique throughout the book you're making since the id's in your sect1's will turn into filenames when the book is parsed into HTML.

- + The other attribute is xreflabel. The value of this is the text that will appear as the link when referring to this sect1.

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

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

Code

- + For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we will use the tag <computeroutput>. @@ -177,12 +177,12 @@ <programlisting> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically.

Links

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

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

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

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

Put this in your XML:

+	  
Check out how I link to a subsection of the Developer's Guide:
Put this in your XML:
 - Find information about creating a package in
 <xref linkend="packages-making-a-package"></xref>.
 
And the output is:
@@ -206,7 +206,7 @@
 	    packages-looks, the
 	    parser will try its best to explain where the link takes you.

2. Linking outside the documentation

- + If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different @@ -227,7 +227,7 @@ do it, so if you want to start converting your documents right away, start out with the ones without graphics ;)

- + To insert a graphic we use the elements <mediaobject>, <imageobject>, @@ -253,7 +253,7 @@ Put your graphics in a separate directory ("images") and link to them only with relative paths.

Lists

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

1. How to make an <ul>: Making an unordered list is pretty much like doing the same thing in HTML - if you close your <li>, that is. The only differences are that each list item has to be wrapped in something more, such as @@ -298,7 +298,7 @@ </variablelist>

Tables

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

Emphasis

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

Index: openacs-4/packages/acs-core-docs/www/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.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 4 Mar 2004 14:09:22 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 22 Mar 2004 11:50:28 -0000 1.21 @@ -1,4 +1,4 @@ -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�15.�Kernel Documentation	Next

External Authentication Requirements

Vision

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

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

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

Conceptual Pictures

Authentication:

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

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

Login

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

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

Account Management (NO PICTURE YET)

Batch Synchronization (NO PICTURE YET)

Requirements

New API

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

Login

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

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

Each user in OpenACS will belong to exactly one authority, which can either be the "local" OpenACS users table, in which case the Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/form-builder.html 4 Mar 2004 14:09:22 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 22 Mar 2004 11:50:28 -0000 1.11 @@ -1,4 +1,4 @@ -Using HTML Forms

Prev	Chapter�11.�Development Reference	Next

Using HTML Forms

Overview

Multi-part Elements

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

SELECT elements

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

set foo_options [db_list_of_lists foo_option_list "
+Using HTML FormsPrev Chapter�11.�Development Reference  Next
Using HTML Forms
Overview
Multi-part Elements
Some elements have more than one choice, or can submit more than one value.
SELECT elements
Creating the form element.�Populate a list of lists with values for the option list.
set foo_options [db_list_of_lists foo_option_list "
     select foo,
            foo_id
       from foos
@@ -10,5 +10,5 @@
     }
This will result in a single name/value pair coming back in the submitted form.  Handle this within the same ad_form structure, in the -new_data and -edit_data.  In the example, it is available as $foo
See also the 
         W3C spec for "The SELECT, OPTGROUP, and OPTION elements".
         
Common Errors
Here are some common errors and what to do when you
-    encounter them:
Error when selecting values
This generally happens when there is an error in your
+    encounter them:
Error when selecting values
This generally happens when there is an error in your
           query.
($Id$)
Prev Home  Next
Programming with AOLserver Up  Chapter�12.�Engineering Standards
docs@openacs.org
View comments on this page at openacs.org
Index: openacs-4/packages/acs-core-docs/www/high-avail.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.html,v
diff -u -N -r1.5 -r1.6
--- openacs-4/packages/acs-core-docs/www/high-avail.html	4 Mar 2004 14:09:22 -0000	1.5
+++ openacs-4/packages/acs-core-docs/www/high-avail.html	22 Mar 2004 11:50:28 -0000	1.6
@@ -1 +1 @@
-High Availability/High Performance ConfigurationsPrev Chapter�6.�Production Environments  Next
High Availability/High Performance Configurations
See also the section called “Running a PostgreSQL database on another server”.
Figure�6.1.�Multiple-server configuration
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 ConfigurationsPrev Chapter�6.�Production Environments  Next
High Availability/High Performance Configurations
See also the section called “Running a PostgreSQL database on another server”.
Figure�6.1.�Multiple-server configuration
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/i18n-convert.html
===================================================================
RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.html,v
diff -u -N -r1.4 -r1.5
--- openacs-4/packages/acs-core-docs/www/i18n-convert.html	4 Mar 2004 14:09:22 -0000	1.4
+++ openacs-4/packages/acs-core-docs/www/i18n-convert.html	22 Mar 2004 11:50:28 -0000	1.5
@@ -1,13 +1,140 @@
-Internationalizing Existing PackagesPrev Chapter�14.�Internationalization  Next
Internationalizing Existing Packages
Internationalize Message text in ADP and TCL
Acs-lang includes tools to automate some
-        internationalization.  From
-        /acs-admin/apm/, select a
+How to Internationalize a Package
Prev Chapter�14.�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
+      URLCharset to utf-8 in your AOLserver config file (use the etc/config.tcl
+      template file).  This is the default for OpenACS 5.1 and later. For sites running on Oracle you need to make
+      sure that AOLserver is running with the NLS_LANG environment
+      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
         package and then click on
         Internationalization, then
         Convert ADP, Tcl, and SQL files to using the
-        message catalog..
Internationalize Package Parameters with visible messages

+        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.
Note
The automatic process 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 temporory message tag:
  <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent,
+    when this wizard is completed and casting begins.#>
+  </p>
Note
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>
+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">
+
+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
+be automatically assigned to a case and role when the simulation
+begins.
+
+</if>
+<else>
+
+Select which case to join, or create a new case for
+yourself.  If you do not select a case to join, you will
+be automatically assigned to a case when the simulation
+begins.
+
+</else>

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.

Prev	Chapter�6.�Production Environments	Next

Prev	Chapter�6.�Production Environments	Next

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:

ad_page_contract {
+    List of messages for a case
+} {
+    case_id:integer
+    role_id:integer
+}
+
+set workflow_id [simulation::case::get_element -case_id $case_id -element workflow_id]
+set simulation_name [simulation::template::get_element -workflow_id $workflow_id -element pretty_name]
+workflow::role::get -role_id $role_id -array role_array
+simulation::case::get -case_id $case_id -array case_array
+
+set title "Messages for $role_array(pretty_name) in $case_array(label)"
+set context [list [list . "SimPlay"] [list [export_vars -base case-admin { case_id }] 
+             "Administer $case_array(label)"] "Messages for $role_array(pretty_name)"]
+
+set user_id [ad_conn user_id]

... and here is the same file after temporary message tags have been manually added:

ad_page_contract {
+    List of messages for a case
+} {
+    case_id:integer
+    role_id:integer
+}
+
+set workflow_id [simulation::case::get_element -case_id $case_id -element
+workflow_id]
+set simulation_name [simulation::template::get_element -workflow_id
+$workflow_id -element pretty_name]
+workflow::role::get -role_id $role_id -array role_array
+simulation::case::get -case_id $case_id -array case_array
+
+# Variables used by I18N messages (array variables not currently
+supported)
+set role_pretty_name $role_array(pretty_name)
+set case_pretty_name $case_array(label)
+set title <#case_admin_page_title Messages for %role_pretty_name% in
+%case_pretty_name%#>
+set context [list [list . <#_ SimPlay#>] [list [export_vars -base
+case-admin { case_id }] <#_ Administer %case_pretty_name%#>] <#_ Messages
+for %role_pretty_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:

ad_page_contract {
+    List of messages for a case
+} {
+    case_id:integer
+    role_id:integer
+}
+
+set workflow_id [simulation::case::get_element -case_id $case_id -element
+workflow_id]
+set simulation_name [simulation::template::get_element -workflow_id
+$workflow_id -element pretty_name]
+workflow::role::get -role_id $role_id -array role_array
+simulation::case::get -case_id $case_id -array case_array
+
+# Variables used by I18N messages (array variables not currently
+supported)
+set role_pretty_name $role_array(pretty_name)
+set case_pretty_name $case_array(label)
+set title [_ simulation.case_admin_page_title]
+set context [list [list . [_ simulation.SimPlay]] [list [export_vars
+-base case-admin { case_id }] [_ simulation.lt_Administer_case_prett]] [_
+simulation.lt_Messages_for_role_pre]]
+
+set user_id [ad_conn user_id]

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" *
+    
```
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"]
```

Prev	Home	Next
Introduction to Developing Internationalized Packages	Up	Design Notes

docs@openacs.org

View comments on this page at openacs.org +

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.� + 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 + message lookups in adp and info files are on the format + \#package_key.message_key\#, and that message lookups in tcl files + 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. +

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.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-design.html 24 Feb 2004 17:42:24 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-design.html 22 Mar 2004 11:50:28 -0000 1.3 @@ -1,2 +1,2 @@ -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 -found, then that locale is offered instead.

Prev	Home	Next
Internationalizing Existing Packages	Up	Appendix�D.�Using CVS with an OpenACS Site

docs@openacs.org

View comments on this page at openacs.org +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

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.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.html 4 Mar 2004 14:09:22 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.html 22 Mar 2004 11:50:28 -0000 1.5 @@ -1,4 +1,4 @@ -Introduction to Developing Internationalized Packages

Prev	Chapter�14.�Internationalization	Next

Introduction to Developing Internationalized Packages

+How Internationalization/Localization works in OpenACS

Prev	Chapter�14.�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 @@ -12,27 +12,17 @@ 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 an internationalized + packages is that all user-visible text in the code of an internationalized package are coded as "message keys." The message keys correspond to a message catalog, which contains versions of the - text for each available language. Both script files - (ADP/TCL) and APM parameters are affected. + text for each available language. Script files (.adp and .tcl and .vuh), database files (.sql), and APM parameters are affected. +

Other differences include: all dates read or written to the database must use internationalized functions. All displayed dates must use internationalized functions. All displayed numbers must use internationalized functions. -

AOLserver Configuration for Multilingual Sites

- 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 - URLCharset to utf-8 in your AOLserver config file (use the etc/config.tcl - template file). This is the default for OpenACS 5.1 and later. For sites running on Oracle you need to make - sure that AOLserver is running with the NLS_LANG environment - 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). -

Using the Message Catalog

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.

Localizable text must be handled in ADP files, in TCL files, and in APM Parameters. OpenACS provides two approaches, message keys and localized ADP files. For ADP pages which are mostly @@ -42,7 +32,7 @@ which are static and mostly text, it may be easier to create a new ADP page for each language. In this case, the pages are distinguished by a file naming convention. -

Separate Templates for each Locale

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

Message Keys in Template Files (ADP Files)

Separate Templates for each Locale

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 @@ -97,17 +87,13 @@ \#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. -
+
- 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 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])]
@@ -116,16 +102,20 @@ context bars, and form labels and options. Many times the texts are enclosed in double quotes. The following is an example of grep commands 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 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 text in page titles and context bars - 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 text in double quotes +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 text in page titles and context bars +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 '<#' + + You may mark up translatable text in TCL library files and TCL pages with temporary tags on the <#key text#> syntax. If you have a sentence or paragraph of text with @@ -154,47 +144,43 @@ 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] - +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 '\{.*<#' - # Check if you've forgotten space between default key and text in message tags (should return nothing) - 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 - + +# 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 '\{.*<#' + +# Check if you've forgotten space between default key and text in message tags (should return nothing) +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 + 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 replace the temporary tags with calls to the message lookup procedure. -

`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 - message lookups in adp and info files are on the format - \#package_key.message_key\#, and that message lookups in tcl files - 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. -

`APM Parameters`

+

`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 + and readable at + lang::system::timezone.. When + retrieved from the database and displayed, dates and times must + be localized to the user's locale. +

`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, @@ -220,41 +206,4 @@

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

`Dates, Times, and Numbers`

- 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 - and readable at - lang::system::timezone.. When - retrieved from the database and displayed, dates and times must - be localized to the user's locale. -

- Get the date in ANSI format from the database (YYYY-MM-DD - HH24:MI:SS; the time portion is optional). By convention, - we identify dates in ansi format by ending the column name - with _ansi. - Example:
```
select to_char(posting_date, 'YYYY-MM-DD HH24:MI:SS') as posting_date_ansi
-  from table
-
```
- Use the Tcl command lc_time_fmt to format the - date in "pretty" format. Several standard formats localize automatically: -
- - %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). -
```
set posting_date_pretty [lc_time_fmt $posting_date_ansi "%q"]
```
- Use the *_pretty version in your ADP page. -

- To internationalize numbers, use lc_numeric $value, which formats the number using the appropriate decimal point and thousand separator for the locale. -

`Internationalizing Forms`

When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.

Prev	Home	Next
Translator's Guide	Up	Internationalizing Existing Packages

docs@openacs.org

View comments on this page at openacs.org +

Prev	Home	Next
	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.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-overview.html 24 Feb 2004 17:42:24 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.html 22 Mar 2004 11:50:28 -0000 1.3 @@ -1 +1 @@ -Prev Chapter�14.�Internationalization Next Table�14.1.�Internationalization and Localization 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 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 Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten. Site Administrators Prev Home Next Chapter�14.�Internationalization Up Translator's Guide docs@openacs.org View comments on this page at openacs.org +Prev Chapter�14.�Internationalization Next Table�14.1.�Internationalization and Localization 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 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 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 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.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-translators.html 24 Feb 2004 17:42:24 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.html 22 Mar 2004 11:50:28 -0000 1.3 @@ -1 +1 @@ -Translator's GuidePrev 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. Prev Home Next Up Introduction to Developing Internationalized Packages docs@openacs.org View comments on this page at openacs.org +Translator's GuidePrev 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. 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.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/i18n.html 24 Feb 2004 17:42:24 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/i18n.html 22 Mar 2004 11:50:28 -0000 1.21 @@ -1,4 +1,4 @@ -Chapter�14.�InternationalizationPrev Part�III.�For OpenACS Package Developers Next Chapter�14.�Internationalization Table of Contents Translator's Guide Introduction to Developing Internationalized Packages Internationalizing Existing Packages Design Notes +Chapter�14.�Internationalization Prev Part�III.�For OpenACS Package Developers Next Chapter�14.�Internationalization Table of Contents How Internationalization/Localization works in OpenACS How to Internationalize a Package Design Notes Translator's Guide By Peter Marklund and Lars Pind 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.33 -r1.34 --- openacs-4/packages/acs-core-docs/www/index.html 4 Mar 2004 14:09:22 -0000 1.33 +++ openacs-4/packages/acs-core-docs/www/index.html 22 Mar 2004 11:50:28 -0000 1.34 @@ -1 +1 @@ -OpenACS Core Documentation Next OpenACS Core Documentation Table of Contents I. OpenACS For Everyone 1. High level information: What is OpenACS? Overview OpenACS Release Notes II. Administrator's Guide 2. Installation Overview Basic Steps Prerequisite Software 3. Complete Installation Install a Unix-like system and supporting software Install Oracle 8.1.7 Install PostgreSQL Install AOLserver 4 Install OpenACS 5.1.0d2 OpenACS Installation Guide for Windows2000 OpenACS Installation Guide for Mac OS X 4. Configuring a new OpenACS Site How Do I? 5. Upgrading Overview Upgrading 4.5 or higher to 4.6.3 Upgrading OpenACS 4.6.3 to 5.0 Upgrading 5.0.0 to 5.0.x Upgrading the OpenACS files Upgrading Platform components 6. Production Environments Starting and Stopping an OpenACS instance. AOLserver keepalive with inittab Running multiple services on one machine High Availability/High Performance Configurations Staged Deployment for Production Networks Installing SSL Support Set up Log Analysis Reports External uptime validation Diagnosing Performance Problems 7. Database Management Running a PostgreSQL database on another server Deleting a tablespace Vacuum Postgres nightly 8. Backup and Recovery Backup Strategy Manual backup and recovery Automated Backup Using CVS for backup-recovery A. Install Red Hat 8/9 B. Install additional supporting software Unpack the OpenACS tarball Initialize CVS (OPTIONAL) Add PSGML commands to emacs init file (OPTIONAL) Install Daemontools (OPTIONAL) Install qmail (OPTIONAL) Install Analog web file analyzer Install nspam Install Full Text Search Install nsopenssl Install tclwebtest. Install PHP for use in AOLserver Install Squirrelmail for use as a webmail system for OpenACS Install AOLserver 3.3oacs1 A. Credits Where did this document come from? Linux Install Guides Security Information Resources III. For OpenACS Package Developers 1. Development Tutorial Creating a Package Setting Up Database Objects Creating Web Pages Debugging and Automated Testing 2. Advanced Topics Write the Requirements and Design Specs Add the new package to CVS Adding Comments Admin Pages Categories Categories Prepare the package for distribution. Notifications Using .vuh files for pretty urls 3. Development Reference OpenACS Packages OpenACS Data Models and the Object System The Request Processor The OpenACS Database Access API Using Templates in OpenACS Groups, Context, Permissions Writing OpenACS Application Pages Parties in OpenACS OpenACS Permissions Tediously Explained Object Identity Programming with AOLserver Using HTML Forms 4. Engineering Standards OpenACS Style Guide Release Version Numbering Constraint naming standard ACS File Naming and Formatting Standards PL/SQL Standards Variables Automated Testing 5. Documentation Standards OpenACS Documentation Guide Using PSGML mode in Emacs Using nXML mode in Emacs Detailed Design Documentation Template System/Application Requirements Template 6. Internationalization Translator's Guide Introduction to Developing Internationalized Packages Internationalizing Existing Packages Design Notes B. Using CVS with an OpenACS Site IV. For OpenACS Platform Developers 7. Kernel Documentation Overview Object Model Requirements Object Model Design Permissions Requirements Permissions Design Groups Requirements Groups Design Subsites Requirements Subsites Design Document Package Manager Requirements Package Manager Design Database Access API OpenACS Internationalization Requirements Security Requirements Security Design Security Notes Request Processor Requirements Request Processor Design Documenting Tcl Files: Page Contracts and Libraries Bootstrapping OpenACS External Authentication Requirements 8. Releasing OpenACS OpenACS Core and .LRN How to Update the OpenACS.org repository How to package and release an OpenACS Package How to Update the translations Index List of Figures 4.1. Site Templates 5.1. Upgrading with the APM 5.2. Upgrading a local CVS repository 6.1. Multiple-server configuration 6.2. Simple A/B Deployment - Step 1 6.3. Simple A/B Deployment - Step 2 6.4. Simple A/B Deployment - Step 3 6.5. Complex A/B Deployment - Step 1 6.6. Complex A/B Deployment - Step 2 6.7. Complex A/B Deployment - Step 3 6.8. Query Analysis example 8.1. Backup and Recovery Strategy 1.1. Assumptions in this section 1.2. Tutorial Data Model 1.3. Database Creation Script - master create file 1.4. Database deletion script 1.5. Page Map 2.1. Upgrading a local CVS repository List of Tables 2.1. Default directories for a standard install 2.2. Version Compatibility Matrix 5.1. Assumptions in this section 6.1. How it Works 3.1. Context Hierarchy Example 3.2. acs_objects example data 6.1. Internationalization and Localization List of Examples 4.1. Getting datetime from the database ANSI-style Next Part�I.�OpenACS For Everyone docs@openacs.org View comments on this page at openacs.org +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.1.0d2 OpenACS Installation Guide for Windows2000 OpenACS Installation Guide for Mac OS X 4. Configuring a new OpenACS Site How Do I? 5. Upgrading Overview Upgrading 4.5 or higher to 4.6.3 Upgrading OpenACS 4.6.3 to 5.0 Upgrading 5.0.0 to 5.0.x Upgrading the OpenACS files Upgrading Platform components 6. Production Environments Starting and Stopping an OpenACS instance. AOLserver keepalive with inittab Running multiple services on one machine High Availability/High Performance Configurations Staged Deployment for Production Networks Installing SSL Support for an OpenACS service Set up Log Analysis Reports External uptime validation Diagnosing Performance Problems 7. Database Management Running a PostgreSQL database on another server Deleting a tablespace Vacuum Postgres nightly 8. Backup and Recovery Backup Strategy Manual backup and recovery Automated Backup Using CVS for backup-recovery A. Install Red Hat 8/9 B. Install additional supporting software Unpack the OpenACS tarball Initialize CVS (OPTIONAL) Add PSGML commands to emacs init file (OPTIONAL) Install Daemontools (OPTIONAL) Install qmail (OPTIONAL) Install Analog web file analyzer Install nspam Install Full Text Search Install nsopenssl Install tclwebtest. Install PHP for use in AOLserver Install Squirrelmail for use as a webmail system for OpenACS Install AOLserver 3.3oacs1 A. Credits Where did this document come from? Linux Install Guides Security Information Resources III. For OpenACS Package Developers 1. Development Tutorial Creating a Package Setting Up Database Objects Creating Web Pages Debugging and Automated Testing 2. Advanced Topics Write the Requirements and Design Specs Add the new package to CVS Adding Comments Admin Pages Categories Categories Prepare the package for distribution. Notifications Using .vuh files for pretty urls 3. Development Reference OpenACS Packages OpenACS Data Models and the Object System The Request Processor The OpenACS Database Access API Using Templates in OpenACS Groups, Context, Permissions Writing OpenACS Application Pages Parties in OpenACS OpenACS Permissions Tediously Explained Object Identity Programming with AOLserver Using HTML Forms 4. Engineering Standards OpenACS Style Guide Release Version Numbering Constraint naming standard ACS File Naming and Formatting Standards PL/SQL Standards Variables Automated Testing 5. Documentation Standards OpenACS Documentation Guide Using PSGML mode in Emacs Using nXML mode in Emacs Detailed Design Documentation Template System/Application Requirements Template 6. Internationalization How Internationalization/Localization works in OpenACS How to Internationalize a Package Design Notes Translator's Guide B. Using CVS with an OpenACS Site IV. For OpenACS Platform Developers 7. Kernel Documentation Overview Object Model Requirements Object Model Design Permissions Requirements Permissions Design Groups Requirements Groups Design Subsites Requirements Subsites Design Document Package Manager Requirements Package Manager Design Database Access API OpenACS Internationalization Requirements Security Requirements Security Design Security Notes Request Processor Requirements Request Processor Design Documenting Tcl Files: Page Contracts and Libraries Bootstrapping OpenACS External Authentication Requirements 8. Releasing OpenACS OpenACS Core and .LRN How to Update the OpenACS.org repository How to package and release an OpenACS Package How to Update the translations Index List of Figures 4.1. Site Templates 4.2. Granting Permissions 4.3. Granting Permissions in 5.0 5.1. Upgrading with the APM 5.2. Upgrading a local CVS repository 6.1. Multiple-server configuration 6.2. Simple A/B Deployment - Step 1 6.3. Simple A/B Deployment - Step 2 6.4. Simple A/B Deployment - Step 3 6.5. Complex A/B Deployment - Step 1 6.6. Complex A/B Deployment - Step 2 6.7. Complex A/B Deployment - Step 3 6.8. Query Analysis example 8.1. Backup and Recovery Strategy 1.1. Assumptions in this section 1.2. Tutorial Data Model 1.3. Database Creation Script - master create file 1.4. Database deletion script 1.5. Page Map 2.1. Upgrading a local CVS repository List of Tables 2.1. Default directories for a standard install 2.2. Version Compatibility Matrix 5.1. Assumptions in this section 6.1. How it Works 3.1. Context Hierarchy Example 3.2. acs_objects example data 6.1. Internationalization and Localization List of Examples 4.1. Getting datetime from the database ANSI-style Next Part�I.�OpenACS For Everyone docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -N -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 4 Mar 2004 14:09:22 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 22 Mar 2004 11:50:29 -0000 1.22 @@ -1,4 +1,4 @@ -Initialize CVS (OPTIONAL)Prev Appendix�B.�Install additional supporting software Next Initialize CVS (OPTIONAL) CVS is a source control system. Create and initialize a +Initialize CVS (OPTIONAL) Prev Appendix�B.�Install additional supporting software Next Initialize CVS (OPTIONAL) CVS is a source control system. Create and initialize a directory for a local cvs repository. [root tmp]# mkdir /cvsroot [root tmp]# cvs -d /cvsroot init [root tmp]# Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v diff -u -N -r1.22 -r1.23 --- openacs-4/packages/acs-core-docs/www/install-daemontools.html 4 Mar 2004 14:09:22 -0000 1.22 +++ openacs-4/packages/acs-core-docs/www/install-daemontools.html 22 Mar 2004 11:50:29 -0000 1.23 @@ -3,7 +3,7 @@ installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services. Install Daemontools download daemontools and install it. Red Hat 8 [root root]# mkdir -p /package + services. Install Daemontools download daemontools and install it. Red Hat 8 [root root]# mkdir -p /package [root root]# chmod 1755 /package/ [root root]# cd /package/ [root package]# tar xzf /tmp/daemontools-0.76.tar.gz Index: openacs-4/packages/acs-core-docs/www/install-full-text-search.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/Attic/install-full-text-search.html,v diff -u -N -r1.20 -r1.21 --- openacs-4/packages/acs-core-docs/www/install-full-text-search.html 4 Mar 2004 14:09:22 -0000 1.20 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search.html 22 Mar 2004 11:50:29 -0000 1.21 @@ -1,7 +1,7 @@ Install Full Text SearchPrev Appendix�B.�Install additional supporting software Next Install Full Text Search By Joel Aufrecht and Malte Sussdorff OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Install OpenFTS module If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and + Install OpenFTS module If you want full text search, and you are running PostgreSQL, install this module to support FTS. Do this step after you have installed both PostgreSQL and AOLserver. You will need the openfts tarball in /tmp. Install Tsearch. This is a PostgreSQL module that OpenFTS requires. [root root]# su - postgres @@ -76,7 +76,7 @@ make su postgres make install -exit Install OpenFTS prerequisites in PostgreSQL instance If you are installing Full Text Search, add required +exit Install OpenFTS prerequisites in PostgreSQL instance If you are installing Full Text Search, add required packages to the new database. (In order for full text search to work, you must also install the PostgreSQL OpenFTS module and prerequisites.) [service0 service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -N -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 18 Feb 2004 14:43:02 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 22 Mar 2004 11:50:29 -0000 1.13 @@ -59,4 +59,4 @@ ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7 - To enable SSL support in your server, make sure your config.tcl file has a section on "OpenSSL 3 with AOLserver4". If your ports for SSL are priviledged (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 to the nsd call). Prev Home Next Install Full Text Search Up Install tclwebtest. docs@openacs.org View comments on this page at openacs.org + SSL support must be enabled seperately in each OpenACS server (Generate ssl certificates. If your ports for SSL are priviledged (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 to the nsd call). Prev Home Next Install Full Text Search Up Install tclwebtest. docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html,v diff -u -N -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 4 Mar 2004 14:09:22 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 22 Mar 2004 11:50:29 -0000 1.6 @@ -62,6 +62,6 @@ 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 + Table�6.1.�How it Works Program Invoked by this program ... ... using this file Where to find errors Log goes to Use these commands to control it svscanboot init /etc/inittab ps -auxw | grep readproctitle n/a � aolserver supervise (a child of svscanboot) /service/service0/run /var/lib/aolserver/service0/log/error.log /var/lib/aolserver/service0/log/service0.log svc -k /service/service0 postgresql Redhat init scripts during boot /etc/init.d/postgresql /usr/local/pgsql/data/server.log � service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian) Prev Home Next Chapter�6.�Production Environments Up AOLserver keepalive with inittab docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/install-qmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v diff -u -N -r1.22 -r1.23 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 4 Mar 2004 14:09:22 -0000 1.22 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 22 Mar 2004 11:50:29 -0000 1.23 @@ -29,7 +29,7 @@ tcpserver: usage: tcpserver [ -1UXpPhHrRoOdDqQv ] [ -c limit ] [ -x rules.cdb ] [ -B banner ] [ -g gid ] [ -u uid ] [ -b backlog ] [ -l localname ] [ -t timeout ] host port program [root ucspi-tcp-0.88]# - + (I'm not sure if this next step is 100% necessary, but when I skip it I get problems. If you get the error 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail command, which pipes a command to the sendmail executable. Or, in our @@ -43,7 +43,7 @@ send outgoing mail. [root ucspi-tcp-0.88]# cp /tmp/openacs-5.1.0d2/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.1.0d2/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp Install Qmail.� Download qmail, +tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp Install Qmail.� Download qmail, set up the standard supporting users and build the binaries: [root root]# cd /usr/local/src [root src]# wget http://www.qmail.org/netqmail-1.04.tar.gz [root src]# tar xzf netqmail-1.04.tar.gz @@ -102,7 +102,7 @@ cd netqmail-1.04 ./collate.sh cd netqmail-1.04 -make setup check Replace sendmail with qmail's wrapper. [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail +make setup check Replace sendmail with qmail's wrapper. [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail [root qmail-1.03]# ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail [root qmail-1.03]# rm -f /usr/bin/sendmail /usr/sbin/sendmail @@ -124,7 +124,7 @@ cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root chmod 644 ~alias/.qmail* /var/qmail/bin/maildirmake ~alias/Maildir/ -chown -R alias.nofiles /var/qmail/alias/Maildir Configure qmail to use the Maildir delivery format +chown -R alias.nofiles /var/qmail/alias/Maildir Configure qmail to use the Maildir delivery format (instead of mbox), and install a version of the qmail startup script modified to use Maildir. [root alias]# echo "./Maildir" > /var/qmail/bin/.qmail [root alias]# cp /tmp/openacs-5.1.0d2/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc [root alias]# chmod 755 /var/qmail/rc Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -N -r1.22 -r1.23 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 4 Mar 2004 14:09:22 -0000 1.22 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 22 Mar 2004 11:50:29 -0000 1.23 @@ -26,7 +26,7 @@ Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - + (Wherever you see the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're @@ -54,7 +54,7 @@ Review (and modify if needed) the partitions created and click Next On the pop-up window asking "Are you sure you want to do this?" click Yes - IF YOU ARE WIPING YOUR HARD DRIVE. Click Next on the boot loader screen Configure Networking. + IF YOU ARE WIPING YOUR HARD DRIVE. Click Next on the boot loader screen Configure Networking. Again, if you know what you're doing, do this step yourself, being sure to note the firewall holes. Otherwise, follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address. DHCP is a system by which a computer that @@ -75,7 +75,7 @@ Mail (SMTP). In the Other ports box, enter 443, 8000, 8443. Click Next. -Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up. Select any additional languages you want the +Port 443 is for https (http over ssl), and 8000 and 8443 are http and https access to the development server we'll be setting up. Select any additional languages you want the computer to support and then click Next Choose your time zone and click Next. Type in a root password, twice. On the Package selection page, we're going to @@ -87,13 +87,13 @@ risk that's still screened by the firewall, or a resource hog. Just don't install a database or web server, because that would conflict with the database and web server we'll install later. - check Editors (this installs emacs), click Details next to Text-based Internet, check lynx, and click OK; check Authoring and Publishing (this installs docbook), uncheck Server Configuration Tools, uncheck Web Server, uncheck Windows File Server, check SQL Database Server (this installs PostgreSQL), check Development Tools (this installs gmake and other build tools), uncheck Administration Tools, and uncheck Printing Support. At the bottom, check Select Individual Packages and click Next We need to fine-tune the exact list of packages. + check Editors (this installs emacs), click Details next to Text-based Internet, check lynx, and click OK; check Authoring and Publishing (this installs docbook), uncheck Server Configuration Tools, uncheck Web Server, uncheck Windows File Server, check SQL Database Server (this installs PostgreSQL), check Development Tools (this installs gmake and other build tools), uncheck Administration Tools, and uncheck Printing Support. At the bottom, check Select Individual Packages and click Next We need to fine-tune the exact list of packages. The same rules apply as in the last step - you can add more stuff, but you shouldn't remove anything the guide adds. We're going to go through all the packages in one big list, so select Flat View and wait. In a minute, a -list of packages will appear. uncheck apmd (monitors power, not very useful for servers), check ImageMagick (required for the photo-album packages, uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon), check mutt (a mail program that reads Maildir), uncheck nfs-utils (nfs is a major security risk), uncheck pam-devel (I don't remember why, but we don't want this), uncheck portmap, uncheck postfix (this is an MTA, but we're going to install qmail later), check postgresql-devel, uncheck rsh (rsh is a security hole), uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later), check tcl (we need tcl), and uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp). Click Next Red Hat isn't completely happy with the combination +list of packages will appear. uncheck apmd (monitors power, not very useful for servers), check ImageMagick (required for the photo-album packages, uncheckisdn4k-utils (unless you are using isdn, this installs a useless daemon), check mutt (a mail program that reads Maildir), uncheck nfs-utils (nfs is a major security risk), uncheck pam-devel (I don't remember why, but we don't want this), uncheck portmap, uncheck postfix (this is an MTA, but we're going to install qmail later), check postgresql-devel, uncheck rsh (rsh is a security hole), uncheck sendmail (sendmail is an insecure MTA; we're going to install qmail instead later), check tcl (we need tcl), and uncheck xinetd (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp). Click Next Red Hat isn't completely happy with the combination of packages we've selected, and wants to satisfy some dependencies. Don't let it. On the next screen, choose Ignore Package @@ -119,7 +119,7 @@ upgrading all of that. Since you are upgrading the kernel, reboot after this step. Lock down SSH - + SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming 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.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-ssl.html 20 Feb 2004 15:13:41 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-ssl.html 22 Mar 2004 11:50:29 -0000 1.3 @@ -1,7 +1,4 @@ -Installing SSL Support Prev Chapter�6.�Production Environments Next Installing SSL Support nsopenssl is an open-sounce module for AOLserver which - adds support for the ssl encryption layer. To use it, you - must install the software, create or purchase certificates, - and configure your OpenACS instance to use it. Uncomment this line from config.tcl. #ns_param nsopenssl ${bindir}/nsopenssl.so +Installing SSL Support for an OpenACS servicePrev 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. [service0 etc]$ mkdir /var/lib/aolserver/service0/etc/certs [service0 etc]$ chmod 700 /var/lib/aolserver/service0/etc/certs [service0 etc]$ 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.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/install-steps.html 4 Mar 2004 14:09:22 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/install-steps.html 22 Mar 2004 11:50:29 -0000 1.16 @@ -37,7 +37,7 @@ su - service0 svc -d /service/service0 dropdb service0 -createdb service0 Paths and Users Table�2.1.�Default directories for a standard install Fully qualified domain name of your server yourserver.test name of administrative access account remadmin OpenACS service service0 OpenACS service account service0 OpenACS database name service0 Root of OpenACS service file tree (SERVERROOT) /var/lib/aolserver/service0 Location of source code tarballs for new software /tmp The OpenACS tarball contains some files which +createdb service0Paths and Users Table�2.1.�Default directories for a standard install Fully qualified domain name of your server yourserver.test name of administrative access account remadmin OpenACS service service0 OpenACS service account service0 OpenACS database name service0 Root of OpenACS service file tree (SERVERROOT) /var/lib/aolserver/service0 Location of source code tarballs for new software /tmp The OpenACS tarball contains some files which are useful while setting up other software. Those files are located at: /tmp/openacs-5.1.0d2/packages/acs-core-docs/www/files Database backup directory /var/lib/aolserver/service0/database-backup Service config files /var/lib/aolserver/service0/etc Service log files /var/lib/aolserver/service0/log Compile directory /usr/local/src PostgreSQL directory /usr/local/pgsql AOLserver directory /usr/local/aolserver None of these locations are set in stone - they're simply 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.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/ix01.html 4 Mar 2004 14:09:22 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/ix01.html 22 Mar 2004 11:50:29 -0000 1.11 @@ -1,2 +1,2 @@ -Index Prev Index A AOLserver configuration, Installation Option 2: Install from tarball Automated tests, Write automated tests C computeroutput code, Code cvs initializing, Initialize CVS (OPTIONAL) setup, Using CVS with an OpenACS Site D daemontools installation, Install Daemontools (OPTIONAL) docbook installation, Install Red Hat 8/9 DocBook DTD, Why DocBook? emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL) Document structure, Document Structure E emacs installation, Install Red Hat 8/9 emphasis bold, italics, Emphasis F full text search installation, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance G Graphics Images, Graphics I informaltable table, Tables L language installation, Install Red Hat 8/9 Linking, Links lists, Lists O OpenACS Package, What a Package Looks Like P photo-album installation (see ImageMagick) Postgres Vacuuming, Installation Option 2: Install from tarball Q qmail installation, Install qmail (OPTIONAL) Maildir, Install qmail (OPTIONAL) rcpthosts error message, Install qmail (OPTIONAL) S sect1, Headlines, Sections sect2, Headlines, Sections Sections Headlines, Headlines, Sections security definition, Install Red Hat 8/9 firewall, Install Red Hat 8/9 sendmail removing, Install qmail (OPTIONAL) service0, Paths and Users ssh, Install Red Hat 8/9 T The publish point for new packages should be +IndexPrev Index A AOLserver configuration, Installation Option 2: Install from tarball Automated tests, Write automated tests C computeroutput code, Code cvs initializing, Initialize CVS (OPTIONAL) setup, Using CVS with an OpenACS Site D daemontools installation, Install Daemontools (OPTIONAL) docbook installation, Install Red Hat 8/9 DocBook DTD, Why DocBook? emacs configuration for, Add PSGML commands to emacs init file (OPTIONAL) Document structure, Document Structure E emacs installation, Install Red Hat 8/9 emphasis bold, italics, Emphasis F full text search installation, Install OpenFTS module, Install OpenFTS prerequisites in PostgreSQL instance G Graphics Images, Graphics I informaltable table, Tables L language installation, Install Red Hat 8/9 Linking, Links lists, Lists O OpenACS Package, What a Package Looks Like P photo-album installation (see ImageMagick) Postgres Vacuuming, Installation Option 2: Install from tarball Q qmail installation, Install qmail (OPTIONAL) Maildir, Install qmail (OPTIONAL) rcpthosts error message, Install qmail (OPTIONAL) S sect1, Headlines, Sections sect2, Headlines, Sections Sections Headlines, Headlines, Sections security definition, Install Red Hat 8/9 firewall, Install Red Hat 8/9 sendmail removing, Install qmail (OPTIONAL) service0, Paths and Users ssh, Install Red Hat 8/9 T The publish point for new packages should be fixed., Prepare the package for distribution. U ulink, Links Unicode in PostgreSQL, Install PostgreSQL upgrade OpenACS 4.5 to 4.6.x Linux/Unix, Upgrading 4.5 or higher to 4.6.3 X XML guidelines, Why DocBook? xref linkend, Links xreflabel, Headlines, Sections Prev Home How to Update the translations Up docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/maint-performance.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/maint-performance.html 4 Mar 2004 14:09:22 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/maint-performance.html 22 Mar 2004 11:50:29 -0000 1.11 @@ -1,7 +1,7 @@ Diagnosing Performance ProblemsPrev Chapter�6.�Production Environments Next Diagnosing Performance Problems Did performance problems happen overnight, or did they sneak up on you? Any clue what caused the performance problems (e.g. loading 20K users into .LRN) Is the file system out of space? Is the machine swapping to disk constantly? Isolating and solving database problems. Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see the section called “Vacuum Postgres nightly”. For Oracle, use exec dbms_stats.gather_schema_stats('SCHEMA_NAME') (Andrew Piskorski's Oracle notes). You can track the exact amount of time each database query on a page takes: Go to Main Site : Site-Wide Administration : Install Software Click on "Install New Application" in "Install from OpenACS Repository" Choose "ACS Developer Support"> After install is complete, restart the server. Browse to Developer Support, which is automatically mounted at /ds. - Turn on Database statistics Browse directly to a slow page and click "Request Information" at the bottom of the page. This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took. Figure�6.8.�Query Analysis example Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process. Log in to SQL*Plus as the admin: [service0 ~]$ svrmgrl + Turn on Database statistics Browse directly to a slow page and click "Request Information" at the bottom of the page. This should return a list of database queries on the page, including the exact query (so it can be cut-paste into psql or oracle) and the time each query took. Figure�6.8.�Query Analysis example Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process. Log in to SQL*Plus as the admin: [service0 ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production 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.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 4 Mar 2004 14:09:22 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 22 Mar 2004 11:50:29 -0000 1.6 @@ -1,7 +1,7 @@ -Staged Deployment for Production NetworksPrev Chapter�6.�Production Environments Next Staged Deployment for Production Networks By Joel Aufrecht +Staged Deployment for Production NetworksPrev Chapter�6.�Production Environments Next Staged Deployment for Production Networks By Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - This section describes minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT) Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested. Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly. Deployment with CVS With this method, we control the files on a site via CVS. In this example, there is one development site and one production site. The only way files should move between the two is via cvs. The production site could run "HEAD" from cvs (raw example from chat log:) + This section describes minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT) Control: You know for sure that the change you are making is the change that you intend to make and is the change that you tested. Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly. Deployment with CVS With this method, we control the files on a site via CVS. In this example, there is one development site and one production site. The only way files should move between the two is via cvs. The production site could run "HEAD" from cvs (raw example from chat log:) 1) change the file on dev as desired 2) test the new file 3) commit the file: @@ -17,4 +17,4 @@ the stuff in -m "foo" is a comment visible only from within cvs commands 4) update the file on production: cd /web/foo-prod/www -cvs up index.adp The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.' So a better method is to use a tag. This guarantees that, at any time in the future, you can retrieve exactly the same set of code. This is useful for both of the characteristics of safe change deployment. For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code. For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems. .... example of using tags to follow ... A/B Deployment The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site. This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly. It does not, by itself, guarantee the entire control chain. You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more. Those additional measures typically take the form of source control tags and system version numbers. The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside. This approach can has limitations. If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle. It also requires extra steps if the database will be affected. Simple A/B Deployment: Database is not changed Figure�6.2.�Simple A/B Deployment - Step 1 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 docs@openacs.org View comments on this page at openacs.org +cvs up index.adp The drawback to using HEAD as the live code is that you cannot commit new work on the development server without erasing the definition of 'working production code.' So a better method is to use a tag. This guarantees that, at any time in the future, you can retrieve exactly the same set of code. This is useful for both of the characteristics of safe change deployment. For control, you can use tags to define a body of code, test that code, and then know that what you are deploying is exactly that code. For rollback, you can use return to the last working tag if the new tag (or new, untagged changes) cause problems. .... example of using tags to follow ... A/B Deployment The approach taken in this section is to always create a new service with the desired changes, running in parallel with the existing site. This guarantees control, at least at the final step of the process: you know what changes you are about to make because you can see them directly. It does not, by itself, guarantee the entire control chain. You need additional measures to make sure that the change you are making is exactly and completely the change you intended to make and tested previously, and nothing more. Those additional measures typically take the form of source control tags and system version numbers. The parallel-server approach also guarantees rollback because the original working service is not touched; it is merely set aside. This approach can has limitations. If the database or file system regularly receiving new data, you must interrupt this function or risk losing data in the shuffle. It also requires extra steps if the database will be affected. Simple A/B Deployment: Database is not changed Figure�6.2.�Simple A/B Deployment - Step 1 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.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 4 Mar 2004 14:09:22 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 22 Mar 2004 11:50:29 -0000 1.24 @@ -1,4 +1,4 @@ -Chapter�6.�Production EnvironmentsPrev Part�II.�Administrator's Guide Next Chapter�6.�Production Environments Table of Contents Starting and Stopping an OpenACS instance. AOLserver keepalive with inittab Running multiple services on one machine High Availability/High Performance Configurations Staged Deployment for Production Networks Installing SSL Support Set up Log Analysis Reports External uptime validation Diagnosing Performance Problems By Joel Aufrecht +Chapter�6.�Production EnvironmentsPrev Part�II.�Administrator's Guide Next Chapter�6.�Production Environments Table of Contents Starting and Stopping an OpenACS instance. AOLserver keepalive with inittab Running multiple services on one machine High Availability/High Performance Configurations Staged Deployment for Production Networks Installing SSL Support 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. Maintenance tasks, optional software, and alternate configurations for AOLserver. ($Id$) Prev Home Next Upgrading Platform components Up Starting and Stopping an OpenACS instance. docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -N -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/objects.html 4 Mar 2004 14:09:22 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/objects.html 22 Mar 2004 11:50:29 -0000 1.33 @@ -78,7 +78,7 @@ Fire up your text editor and open the ROOT/packages/notes/sql/oracle/notes-create.sql (ROOT/packages/notes/sql/postgresql/notes-create.sql for the PG version) file created when we created the package. Then, do the following: - Describe the new type to the type system + Describe the new type to the type system First, add an entry to the acs_object_types table with the following PL/SQL call: begin @@ -138,7 +138,7 @@ because the new type note is a subtype of acs_object, it will inherit these attributes, so there is no need for us to define them. - Define a table in which to store your objects + Define a table in which to store your objects The next thing we do is make a small modification to the data model to reflect the fact that each row in the notes table represents something that is not only an object of type @@ -163,7 +163,7 @@ use the acs_objects table to find objects will transparently find any objects that are instances of any subtype of acs_objects. - Define a package for type specific procedures + Define a package for type specific procedures The next step is to define a PL/SQL package for your new type, and write some basic procedures to create and delete objects. Here is a package definition for our new type: @@ -211,7 +211,7 @@ object OBJ was "read only", then any other object that used OBJ as its context would also be "read only" by default. We'll talk about this more later. - Define a package body for type specific procedures + Define a package body for type specific procedures The PL/SQL package body contains the implementations of the procedures defined above. The only subtle thing going on here is that we must use acs_object.new to insert a row into Index: openacs-4/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v diff -u -N -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/openacs.html 4 Mar 2004 14:09:22 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/openacs.html 22 Mar 2004 11:50:29 -0000 1.32 @@ -220,15 +220,15 @@ CREATE DATABASE [service0 service0]$ su - service0 -createdb -E UNICODE service0 Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day. [service0 service0]$ export EDITOR=emacs;crontab -e Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information. 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0 +createdb -E UNICODE service0 Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day. [service0 service0]$ export EDITOR=emacs;crontab -e Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information. 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0 0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0 Add Full Text Search Support (OPTIONAL) At this point the database should be ready for installing OpenACS. Configure an AOLserver Service for OpenACS.� The AOLserver architecture lets you run an arbitrary number of virtual servers. A virtual server is an HTTP service running on a specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, /var/lib/aolserver/service0/etc/config.tcl. - Open it in an editor to adjust the parameters. [root root]# su - service0 + Open it in an editor to adjust the parameters. [root root]# su - service0 [service0 service0]$ cd /var/lib/aolserver/service0/etc [service0 etc]$ emacs config.tcl @@ -252,7 +252,7 @@ AOLserver is very configurable. These settings should get you started, but for more options, read the AOLserver docs. - Enable OpenFTS Full Text Search (OPTIONAL) Install nsopenssl + Enable OpenFTS Full Text Search (OPTIONAL) Install nsopenssl for SSL support. (OPTIONAL) Verify AOLserver startup.� Kill any current running AOLserver processes and start a new one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/service0/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 Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -N -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 4 Mar 2004 14:09:22 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 22 Mar 2004 11:50:30 -0000 1.26 @@ -100,7 +100,7 @@ Context Hierarchy Suppose objects A, B, ..., and F form the following hierarchy. - Table�11.1.�Context Hierarchy Example A + Table�11.1.�Context Hierarchy Example A object_id=10 B object_id=20 @@ -116,7 +116,7 @@ This can be represented in the acs_objects table by the following entries: - Table�11.2.�acs_objects example data object_id context_id 20 10 30 10 40 20 50 20 60 30 + Table�11.2.�acs_objects example data object_id context_id 20 10 30 10 40 20 50 20 60 30 The first entry tells us that object 20 is the descendant of object 10, and the third entry shows that object 40 is the descendant of object 20. By running a CONNECT BY query, Index: openacs-4/packages/acs-core-docs/www/postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v diff -u -N -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/postgres.html 4 Mar 2004 14:09:22 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/postgres.html 22 Mar 2004 11:50:30 -0000 1.31 @@ -100,7 +100,7 @@ Change to the postgres user and run ./configure to set the compilation options automatically. This is the point at which you can configure PostgreSQL in various ways. For example, if you want to enable - Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help. + Unicode support, add the flags --enable-locale and --enable-multibyte. If you want to see what the other possibilities are, run ./configure --help. On debian woody (stable, 3.0), do ./configure --without-readline --without-zlib. [root src]# su - postgres [postgres pgsql]$ cd /usr/local/src/postgresql-7.3.4 [postgres postgresql-7.3.4]$ ./configure --with-includes=/sw/include/ --with-libraries=/sw/lib --enable-locale --enable-multibyte \ Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v diff -u -N -r1.22 -r1.23 --- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 4 Mar 2004 14:09:22 -0000 1.22 +++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 22 Mar 2004 11:50:30 -0000 1.23 @@ -1,4 +1,4 @@ -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 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.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/release-notes.html 4 Mar 2004 14:09:22 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/release-notes.html 22 Mar 2004 11:50:30 -0000 1.36 @@ -95,4 +95,4 @@ Serving backup files and files from the CVS directories is turned off by default via the acs-kernel parameter ExcludedFiles in section request-processor (The variable provides a string match glob list of files and is defaulted to "*/CVS/* *~") - ($Id$) Version 4.6.3 Release Notes for 4.6.3 Version 4.6.2 Release Notes for 4.6.2 Version 4.6 Release Notes for 4.6 Version 4.5 Release Notes for 4.5 Prev Home Next Overview Up Part�II.�Administrator's Guide docs@openacs.org View comments on this page at openacs.org + ($Id$) Version 4.6.3 Release Notes for 4.6.3 Version 4.6.2 Release Notes for 4.6.2 Version 4.6 Release Notes for 4.6 Version 4.5 Release Notes for 4.5 Prev Home Next Overview Up Part�II.�Administrator's Guide docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/rp-design.html 27 Feb 2004 11:20:52 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 22 Mar 2004 11:50:30 -0000 1.24 @@ -91,7 +91,8 @@ 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 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 +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. 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.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 4 Mar 2004 14:09:22 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 22 Mar 2004 11:50:30 -0000 1.7 @@ -58,4 +58,4 @@ initial revision: 1.1 done (many lines omitted) -[service0 myfirstpackage]$Figure�10.1.�Upgrading a local CVS repository Prev Home Next Write the Requirements and Design Specs Up Adding Comments docs@openacs.org View comments on this page at openacs.org +[service0 myfirstpackage]$Figure�10.1.�Upgrading a local CVS repository Prev Home Next Write the Requirements and Design Specs Up Adding Comments docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/tutorial-database.html 4 Mar 2004 14:09:22 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/tutorial-database.html 22 Mar 2004 11:50:30 -0000 1.24 @@ -1,7 +1,7 @@ Setting Up Database ObjectsPrev Chapter�9.�Development Tutorial Next Setting Up Database Objects by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Code the data model We create all database objects with scripts in the + Code the data model We create all database objects with scripts in the myfirstpackage/sql/ directory. All database scripts are database-specific and are thus in either the myfirstpackage/sql/oracle or @@ -31,13 +31,13 @@ repository functions to simplify our database creation. (More information about ACS Objects. More information about the Content Repository.) - Figure�9.2.�Tutorial Data Model The top of each sql file has some + Figure�9.2.�Tutorial Data Model The top of each sql file has some standard comments, including doc tags such as @author which will be picked up by the API browser. The string $Id$ will automatically be expanded when the file is checked in to cvs. [service0 ~]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/sql/postgresql -[service0 postgresql]$ emacs myfirstpackage-create.sql Paste this into the file and save and close. Figure�9.3.�Database Creation Script - master create file -- creation script +[service0 postgresql]$ emacs myfirstpackage-create.sql Paste this into the file and save and close. Figure�9.3.�Database Creation Script - master create file -- creation script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ @@ -62,7 +62,7 @@ First Package," ensures that our object is unlikely to conflict with objects from other packages. Create a database file to drop everything if the package is uninstalled. -[service0 postgresql]$ emacs myfirstpackage-drop.sql Figure�9.4.�Database deletion script -- drop script +[service0 postgresql]$ emacs myfirstpackage-drop.sql Figure�9.4.�Database deletion script -- drop script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v diff -u -N -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/tutorial-debug.html 4 Mar 2004 14:09:22 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html 22 Mar 2004 11:50:30 -0000 1.24 @@ -1,7 +1,7 @@ Debugging and Automated TestingPrev Chapter�9.�Development Tutorial Next Debugging and Automated Testing by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Debugging Developer Support.�The Developer Support package adds several goodies: debug + Debugging Developer Support.�The Developer Support package adds several goodies: debug information for every page; the ability to log comments to the page instead of the error log, and fast user switching so that you can test pages as anonymous and as dummy users without logging @@ -22,16 +22,16 @@ ?�searches�backward� /�searches�forward.� �� - Manual testing Make a list of basic tests to make sure it works Test Num Action Expected Result 001 Browse to the index page while not logged in and + Manual testing Make a list of basic tests to make sure it works Test Num Action Expected Result 001 Browse to the index page while not logged in and while one or more notes exist. No edit or delete or add links should appear. 002 Browse to the index page while logged in. An Edit link should appear. Click on it. Fill out the form and click Submit. The text added in the form should be visible on the index page. API-001 Invoke mfp::note::create with a specific word as the title. Proc should return an object id. API-002 Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title. API-003 Given the object id from API-001, invoke mfp::note::delete. Proc should return 0 for success. Other things to test: try to delete someone else's note. Try to delete your own note. Edit your own note. - Search for a note. Write automated tests by Simon Carstensen and Joel Aufrecht + Search for a note. Write automated tests by Simon Carstensen and Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - + It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it. Create the directory that will contain the test script and edit the script file. The directory location and file name are standards which are recognized by the automated testing package: [service0 www]$ mkdir /var/lib/aolserver/service0/packages/myfirstpackage/tcl/test [service0 www]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/tcl/test 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.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 4 Mar 2004 14:09:22 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 22 Mar 2004 11:50:31 -0000 1.7 @@ -6,5 +6,5 @@ (37.1KB) after the label Distribution File: and save the file to - /tmp. + /tmp. Prev Home Next Categories Up Notifications docs@openacs.org View comments on this page at openacs.org Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v diff -u -N -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 4 Mar 2004 14:09:22 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 22 Mar 2004 11:50:31 -0000 1.25 @@ -1,7 +1,7 @@ Creating a PackagePrev Chapter�9.�Development Tutorial Next Creating a Package by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - The intended page map Overview To start developing new code in OpenACS, we build a new + The intended page map Overview To start developing new code in OpenACS, we build a new package. A package is a a discrete collection of web pages, tcl code, and database tables and procedures. A package with user interface is called an application; a package which provides @@ -21,11 +21,11 @@ In this tutorial, we will make an application package for displaying a list of text notes. - Before you begin You will need: A computer with a working installation of + Before you begin You will need: A computer with a working installation of OpenACS. If you don't have this, see Chapter�2, Installation Overview. Example files, which are included in the standard OpenACS 5.1.0d2 distribution. - Figure�9.1.�Assumptions in this section Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key myfirstpackage Use the APM to initialize a new package We use the ACS Package Manager (APM) to add, remove, and + Figure�9.1.�Assumptions in this section Fully qualified domain name of your server yourserver.test URL of your server http://yourserver.test:8000 Name of development account service0 New Package key myfirstpackage Use the APM to initialize a new package We use the ACS Package Manager (APM) to add, remove, and upgrade packages. It handles package meta-data, such as lists of files that belong in the package. Each package is uniquely identified by a package key. To start developing a new @@ -54,7 +54,7 @@ This creates a package rooted at /var/lib/aolserver/service0/packages/myfirstpackage. This is the "home directory" of our new package, and all - files in the package will be within this directory. Mount the package in the site map In order to see your work in progress, you must create a + files in the package will be within this directory. Mount the package in the site map In order to see your work in progress, you must create a map between the URL space of incoming requests and the package. You do this by mounting the package in the Site Map. This creates a link between the incoming URL and an 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.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 18 Feb 2004 14:43:03 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 22 Mar 2004 11:50:31 -0000 1.3 @@ -72,6 +72,95 @@ select inline_0(); drop function inline_0(); + You also need a drop script. This is untested for + comptability with the above script. + -- @author gwong@orchardlabs.com,ben@openforce.biz + -- @creation-date 2002-05-16 + -- + -- This code is newly concocted by Ben, but with significant concepts and code + -- lifted from Gilbert's UBB forums. Thanks Orchard Labs. + -- Lars and Jade in turn lifted this from gwong and ben. + +create function inline_0 () +returns integer as ' +declare + row record; +begin + for row in select nt.type_id + from notification_types nt + where nt.short_name in (''lars_blogger_notif_type'',''lars_blogger_notif'') + loop + perform notification_type__delete(row.type_id); + end loop; + + return null; +end;' language 'plpgsql'; + +select inline_0(); +drop function inline_0 (); + +-- +-- Service contract drop stuff was missing - Roberto Mello +-- + +create function inline_0() returns integer as ' +declare + impl_id integer; + v_foo integer; +begin + + -- the notification type impl + impl_id := acs_sc_impl__get_id ( + ''NotificationType'', -- impl_contract_name + ''lars_blogger_notif_type'' -- impl_name + ); + + PERFORM acs_sc_binding__delete ( + ''NotificationType'', + ''lars_blogger_notif_type'' + ); + + v_foo := acs_sc_impl_alias__delete ( + ''NotificationType'', -- impl_contract_name + ''lars_blogger_notif_type'', -- impl_name + ''GetURL'' -- impl_operation_name + ); + + v_foo := acs_sc_impl_alias__delete ( + ''NotificationType'', -- impl_contract_name + ''lars_blogger_notif_type'', -- impl_name + ''ProcessReply'' -- impl_operation_name + ); + + select into v_foo type_id + from notification_types + where sc_impl_id = impl_id + and short_name = ''lars_blogger_notif''; + + perform notification_type__delete (v_foo); + + delete from notification_types_intervals + where type_id = v_foo + and interval_id in ( + select interval_id + from notification_intervals + where name in (''instant'',''hourly'',''daily'') + ); + + delete from notification_types_del_methods + where type_id = v_foo + and delivery_method_id in ( + select delivery_method_id + from notification_delivery_methods + where short_name in (''email'') + ); + + return (0); +end; +' language 'plpgsql'; + +select inline_0(); +drop function inline_0(); The next step is to setup our notification creation. A new notification must be added to the notification table for each blog entry added. We do this using the notification::new procedure @@ -82,10 +171,17 @@ -response_id $blog(entry_id) \ -notif_subject $blog(title) \ -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 object_id of the Weblogger instance to which the entry has been posted to - and the $new_content is the content of the entry. The final step is to setup the notification subscription process. In this + 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 + object_id of the Weblogger instance to which the entry has been + 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 + instead used the blog_entry_id or something like that, you could + set up per-item notifications. The forums packages does this -- + 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 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.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/tutorial-pages.html 4 Mar 2004 14:09:22 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html 22 Mar 2004 11:50:31 -0000 1.24 @@ -1,8 +1,8 @@ Creating Web Pages Prev Chapter�9.�Development Tutorial Next Creating Web Pages by Joel Aufrecht OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. - Install some API As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files: - cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/service0/packages/myfirstpackage/tcl/ To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage". 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, + Install some API As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files: + cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/service0/packages/myfirstpackage/tcl/ To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage". 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 holds the procedural logic for the page, including TCL and database-independent SQL code, and does things like Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.html,v diff -u -N -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 18 Feb 2004 14:43:03 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 22 Mar 2004 11:50:31 -0000 1.3 @@ -32,4 +32,8 @@ set edit_url [export_vars -base "note/$item_id"] set delete_url [export_vars -base "note-delete" {item_id}] } - Prev Home Next Notifications Up docs@openacs.org View comments on this page at openacs.org +You may also need to change some of the links in your + package. Commonly, you would use ad_conn package_url to build the + URL. Otherwise, some of your links may be relative to the virtual + directory (note/) instead of the actual directory that the note is + being served from Prev Home Next Notifications Up 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.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html 4 Mar 2004 14:13:05 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html 22 Mar 2004 11:50:31 -0000 1.9 @@ -1,4 +1,4 @@ -Upgrading 4.5 or higher to 4.6.3Prev Chapter�5.�Upgrading Next Upgrading 4.5 or higher to 4.6.3 The required platform for OpenACS 4.6 is the same as +Upgrading 4.5 or higher to 4.6.3 Prev Chapter�5.�Upgrading Next Upgrading 4.5 or higher to 4.6.3 The required platform for OpenACS 4.6 is the same as 4.5, with the exception of OpenFTS. OpenACS 4.6 and later require OpenFTS 0.3.2 for full text search on PostGreSQL. If you have OpenFTS 0.2, you'll need to upgrade. If upgrading from 4.2, you need to manually run acs-kernel/sql/postgres/upgrade-4.2-4.5.sql. See Bug #632 A computer with OpenACS 4.5. OpenACS 4.6 tarball or CVS checkout/export. Required for Full Text Search on PostgreSQL: OpenFTS 0.3.2 Make a Backup.�Back up the database and file system (see the section called “Manual backup and recovery”). OPTIONAL: Upgrade OpenFTS.�the section called “Upgrading OpenFTS from 0.2 to 0.3.2” Stop the server [root root]# svc -d /service/service0 Upgrade the file system.�the section called “Upgrading the OpenACS files” 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.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html 4 Mar 2004 14:13:05 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html 22 Mar 2004 11:50:31 -0000 1.2 @@ -1 +1 @@ -Upgrading 5.0.0 to 5.0.x Prev Chapter�5.�Upgrading Next Upgrading 5.0.0 to 5.0.x Upgrading a stock site.�If you have no custom code, and your site is not in a CVS repository, upgrade with these steps: 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 no custom code, and your site is not in a CVS repository, upgrade with these steps: Upgrade the file system for all packages in use.�the section called “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 5.0.0 to 5.0.xPrev Chapter�5.�Upgrading Next Upgrading 5.0.0 to 5.0.x Upgrading a stock site.�If you have no custom code, and your site is not in a CVS repository, upgrade with these steps: 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.�the section called “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-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.html,v diff -u -N -r1.8 -r1.9 --- openacs-4/packages/acs-core-docs/www/upgrade-overview.html 4 Mar 2004 14:09:22 -0000 1.8 +++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html 22 Mar 2004 11:50:31 -0000 1.9 @@ -3,4 +3,4 @@ or better, you should always be able to upgrade all of your core packages automatically. If you haven't changed anything, no manual intervention should be required. If you are running - OpenACS prior to 4.5, upgrading will require manual effort. If all of these conditions are true: Your OpenACS Core is 5.0.0 or later You do not keep your OpenACS site in a local CVS repository You do not have any custom code then you can upgrade automatically using the automated installer in the OpenACS Package Manager (APM), and you can probably skip the rest of this chapter. To upgrade directly from the OpenACS repository using the APM: Browse to the Installer. Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade. The APM will download the requested packages from OpenACS.org, install the files on your hard drive, run any appropriate database upgrade scripts, and prompt you to restart the server. After restarting the server again, the upgrade is complete. Figure�5.1.�Upgrading with the APM It's always a good idea to precede an upgrade attempt with a snapshot backup. Table�5.1.�Assumptions in this section name of OpenACS user service0 OpenACS server name service0 Root of OpenACS file tree /var/lib/aolserver/service0 Database backup directory /var/lib/aolserver/service0/database-backup Prev Home Next Chapter�5.�Upgrading Up Upgrading 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 service0 OpenACS server name service0 Root of OpenACS file tree /var/lib/aolserver/service0 Database backup directory /var/lib/aolserver/service0/database-backup Prev Home Next Chapter�5.�Upgrading Up Upgrading 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.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 4 Mar 2004 14:09:22 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 22 Mar 2004 11:50:31 -0000 1.7 @@ -28,9 +28,9 @@ [service0 dev]$ exit [root root]# su - service0 - psql service0 -f /usr/local/pgsql/share/contrib/openfts.sql - psql service0 -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql - exitOPTIONAL: Install the new OpenFTS Engine.�If you want to upgrade the OpenFTS Engine, do these +psql service0 -f /usr/local/pgsql/share/contrib/openfts.sql +psql service0 -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 steps. (You must have already upgraded the OpenFTS driver to 0.3.2.) Browse to http://yourserver/admin/site-map On the openfts line, click on set parameters. Change the value of openfts_tcl_src_path from /usr/local/src/Search-OpenFTS-tcl-0.2/ to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ Click Set Parameters [root root]# restart-aolserver service0 Browse to http://yourserver/openfts Click Administration. Click Initialize OpenFTS Engine Upgrading from PostGreSQL 7.2 to 7.3 An OpenACS database created in PostGreSQL 7.2 will not work correctly in PostGreSQL 7.3. This is because 7.2 truncates @@ -60,7 +60,10 @@ 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) + 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 + .bash_profile for the postgres73 user. 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 @@ -72,4 +75,4 @@ postgres73 user's home directory. Change the path in service0's .bashrc or .bash_profile (or both) files to reflect the new postgres73 - user directory. 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/variables.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v diff -u -N -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/variables.html 4 Mar 2004 14:09:22 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/variables.html 22 Mar 2004 11:50:31 -0000 1.11 @@ -3,7 +3,7 @@ by OpenACS documentation staff. Date and Time Variables Starting with OpenACS 5.0 and the introduction of acs-lang, we recommend retrieving date/time information from the database in - ANSI format and then using lc_time_fmt to format it for display. Example�12.1.�Getting datetime from the database ANSI-style db_multirow -extend { mydate_pretty } { + ANSI format and then using lc_time_fmt to format it for display. Example�12.1.�Getting datetime from the database ANSI-style db_multirow -extend { mydate_pretty } { select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi, ... ... Index: openacs-4/packages/acs-core-docs/www/images/i18n-1.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/i18n-1.png,v diff -u -N Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/i18n-2.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/i18n-2.png,v diff -u -N Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/i18n-3.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/i18n-3.png,v diff -u -N Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/production.dia =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/production.dia,v diff -u -N -r1.1 -r1.2 Binary files differ Index: openacs-4/packages/acs-core-docs/www/images/upgrade-cvs.png =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/images/upgrade-cvs.png,v diff -u -N -r1.1 -r1.2 Binary files differ

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