Index: openacs-4/packages/acs-core-docs/www/acs-admin.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/acs-admin.adp 7 Aug 2017 23:47:48 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/acs-admin.adp 8 Nov 2017 09:42:09 -0000 1.3 @@ -79,8 +79,7 @@ (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2">Install Full Text Search -using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-openfts">Install Full Text Search -using OpenFTS (deprecated see tsearch2)</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl">Install +using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail">Install Index: openacs-4/packages/acs-core-docs/www/acs-admin.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-admin.html,v diff -u -r1.46 -r1.47 --- openacs-4/packages/acs-core-docs/www/acs-admin.html 7 Aug 2017 23:47:48 -0000 1.46 +++ openacs-4/packages/acs-core-docs/www/acs-admin.html 8 Nov 2017 09:42:09 -0000 1.47 @@ -1,2 +1,25 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part II. Administrator's Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="release-notes.html" title="OpenACS Release Notes"><link rel="next" href="install-overview.html" title="Chapter 2. Installation Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="acs-admin"></a>Part II. Administrator's Guide</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="install-overview.html">2. Installation Overview</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-steps.html">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs.html">Prerequisite Software</a></span></dt></dl></dd><dt><span class="chapter"><a href="complete-install.html">3. Complete Installation</a></span></dt><dd><dl><dt><span class="sect1"><a href="unix-installation.html">Install a Unix-like system and supporting software</a></span></dt><dt><span class="sect1"><a href="oracle.html">Install Oracle 8.1.7</a></span></dt><dt><span class="sect1"><a href="postgres.html">Install PostgreSQL</a></span></dt><dt><span class="sect1"><a href="aolserver4.html">Install AOLserver 4</a></span></dt><dt><span class="sect1"><a href="openacs.html">Install OpenACS 5.9.0</a></span></dt><dt><span class="sect1"><a href="win2k-installation.html">OpenACS Installation Guide for Windows</a></span></dt><dt><span class="sect1"><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></span></dt></dl></dd><dt><span class="chapter"><a href="configuring-new-site.html">4. Configuring a new OpenACS Site</a></span></dt><dd><dl><dt><span class="sect1"><a href="configuring-install-packages.html">Installing OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-mounting-packages.html">Mounting OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-packages.html">Configuring an OpenACS package</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-permissions.html">Setting Permissions on an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I.html">How Do I?</a></span></dt></dl></dd><dt><span class="chapter"><a href="upgrade.html">5. Upgrading</a></span></dt><dd><dl><dt><span class="sect1"><a href="upgrade-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></span></dt><dt><span class="sect1"><a href="upgrade-4.6.3-to-5.html">Upgrading OpenACS 4.6.3 to 5.0</a></span></dt><dt><span class="sect1"><a href="upgrade-5-0-dot.html">Upgrading an OpenACS 5.0.0 or greater installation</a></span></dt><dt><span class="sect1"><a href="upgrade-openacs-files.html">Upgrading the OpenACS files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting.html">Upgrading Platform components</a></span></dt></dl></dd><dt><span class="chapter"><a href="maintenance-web.html">6. Production Environments</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-openacs-keepalive.html">Starting and Stopping an OpenACS instance.</a></span></dt><dt><span class="sect1"><a href="install-openacs-inittab.html">AOLserver keepalive with inittab</a></span></dt><dt><span class="sect1"><a href="install-next-add-server.html">Running multiple services on one machine</a></span></dt><dt><span class="sect1"><a href="high-avail.html">High Availability/High Performance Configurations</a></span></dt><dt><span class="sect1"><a href="maintenance-deploy.html">Staged Deployment for Production Networks</a></span></dt><dt><span class="sect1"><a href="install-ssl.html">Installing SSL Support for an OpenACS service</a></span></dt><dt><span class="sect1"><a href="analog-setup.html">Set up Log Analysis Reports</a></span></dt><dt><span class="sect1"><a href="uptime.html">External uptime validation</a></span></dt><dt><span class="sect1"><a href="maint-performance.html">Diagnosing Performance Problems</a></span></dt></dl></dd><dt><span class="chapter"><a href="database-management.html">7. Database Management</a></span></dt><dd><dl><dt><span class="sect1"><a href="remote-postgres.html">Running a PostgreSQL database on another server</a></span></dt><dt><span class="sect1"><a href="install-openacs-delete-tablespace.html">Deleting a tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum.html">Vacuum Postgres nightly</a></span></dt></dl></dd><dt><span class="chapter"><a href="backup-recovery.html">8. Backup and Recovery</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-next-backups.html">Backup Strategy</a></span></dt><dt><span class="sect1"><a href="snapshot-backup.html">Manual backup and recovery</a></span></dt><dt><span class="sect1"><a href="automated-backup.html">Automated Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs.html">Using CVS for backup-recovery</a></span></dt></dl></dd><dt><span class="appendix"><a href="install-redhat.html">A. Install Red Hat 8/9</a></span></dt><dt><span class="appendix"><a href="install-more-software.html">B. Install additional supporting software</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></span></dt><dt><span class="sect1"><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-qmail.html">Install qmail (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install.html">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam.html">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2.html">Install Full Text Search using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-openfts.html">Install Full Text Search using OpenFTS (deprecated see tsearch2)</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl.html">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest.html">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php.html">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail.html">Install Squirrelmail for use as a webmail system for OpenACS</a></span></dt><dt><span class="sect1"><a href="install-pam-radius.html">Install PAM Radius for use as external authentication</a></span></dt><dt><span class="sect1"><a href="install-ldap-radius.html">Install LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver.html">Install AOLserver 3.3oacs1</a></span></dt></dl></dd><dt><span class="appendix"><a href="credits.html">C. Credits</a></span></dt><dd><dl><dt><span class="section"><a href="install-origins.html">Where did this document come from?</a></span></dt><dt><span class="section"><a href="os-install.html">Linux Install Guides</a></span></dt><dt><span class="section"><a href="os-security.html">Security Information</a></span></dt><dt><span class="section"><a href="install-resources.html">Resources</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Release Notes </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 2. Installation Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part II. Administrator's Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="release-notes.html" title="OpenACS Release Notes"><link rel="next" href="install-overview.html" title="Chapter 2. Installation Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="acs-admin"></a>Part II. Administrator's Guide</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="install-overview.html">2. Installation Overview</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-steps.html">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs.html">Prerequisite Software</a></span></dt></dl></dd><dt><span class="chapter"><a href="complete-install.html">3. Complete Installation</a></span></dt><dd><dl><dt><span class="sect1"><a href="unix-installation.html">Install a Unix-like system and supporting software</a></span></dt><dt><span class="sect1"><a href="oracle.html">Install Oracle 8.1.7</a></span></dt><dt><span class="sect1"><a href="postgres.html">Install PostgreSQL</a></span></dt><dt><span class="sect1"><a href="aolserver4.html">Install AOLserver 4</a></span></dt><dt><span class="sect1"><a href="openacs.html">Install OpenACS 5.9.0</a></span></dt><dt><span class="sect1"><a href="win2k-installation.html">OpenACS Installation Guide for Windows</a></span></dt><dt><span class="sect1"><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></span></dt></dl></dd><dt><span class="chapter"><a href="configuring-new-site.html">4. Configuring a new OpenACS Site</a></span></dt><dd><dl><dt><span class="sect1"><a href="configuring-install-packages.html">Installing OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-mounting-packages.html">Mounting OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-packages.html">Configuring an OpenACS package</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-permissions.html">Setting Permissions on an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I.html">How Do I?</a></span></dt></dl></dd><dt><span class="chapter"><a href="upgrade.html">5. Upgrading</a></span></dt><dd><dl><dt><span class="sect1"><a href="upgrade-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></span></dt><dt><span class="sect1"><a href="upgrade-4.6.3-to-5.html">Upgrading OpenACS 4.6.3 to 5.0</a></span></dt><dt><span class="sect1"><a href="upgrade-5-0-dot.html">Upgrading an OpenACS 5.0.0 or greater installation</a></span></dt><dt><span class="sect1"><a href="upgrade-openacs-files.html">Upgrading the OpenACS files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting.html">Upgrading Platform components</a></span></dt></dl></dd><dt><span class="chapter"><a href="maintenance-web.html">6. Production Environments</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-openacs-keepalive.html">Starting and Stopping an OpenACS instance.</a></span></dt><dt><span class="sect1"><a href="install-openacs-inittab.html">AOLserver keepalive with inittab</a></span></dt><dt><span class="sect1"><a href="install-next-add-server.html">Running multiple services on one machine</a></span></dt><dt><span class="sect1"><a href="high-avail.html">High Availability/High Performance Configurations</a></span></dt><dt><span class="sect1"><a href="maintenance-deploy.html">Staged Deployment for Production Networks</a></span></dt><dt><span class="sect1"><a href="install-ssl.html">Installing SSL Support for an OpenACS service</a></span></dt><dt><span class="sect1"><a href="analog-setup.html">Set up Log Analysis Reports</a></span></dt><dt><span class="sect1"><a href="uptime.html">External uptime validation</a></span></dt><dt><span class="sect1"><a href="maint-performance.html">Diagnosing Performance Problems</a></span></dt></dl></dd><dt><span class="chapter"><a href="database-management.html">7. Database Management</a></span></dt><dd><dl><dt><span class="sect1"><a href="remote-postgres.html">Running a PostgreSQL database on another server</a></span></dt><dt><span class="sect1"><a href="install-openacs-delete-tablespace.html">Deleting a tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum.html">Vacuum Postgres nightly</a></span></dt></dl></dd><dt><span class="chapter"><a href="backup-recovery.html">8. Backup and Recovery</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-next-backups.html">Backup Strategy</a></span></dt><dt><span class="sect1"><a href="snapshot-backup.html">Manual backup and recovery</a></span></dt><dt><span class="sect1"><a href="automated-backup.html">Automated Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs.html">Using CVS for backup-recovery</a></span></dt></dl></dd><dt><span class="appendix"><a href="install-redhat.html">A. Install Red Hat 8/9</a></span></dt><dt><span class="appendix"><a href="install-more-software.html">B. Install additional supporting software</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></span></dt><dt><span class="sect1"><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-qmail.html">Install qmail (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install.html">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam.html">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2.html">Install Full Text Search using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl.html">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest.html">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php.html">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail.html">Install Squirrelmail for use as a webmail system for OpenACS</a></span></dt><dt><span class="sect1"><a href="install-pam-radius.html">Install PAM Radius for use as external authentication</a></span></dt><dt><span class="sect1"><a href="install-ldap-radius.html">Install LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver.html">Install AOLserver 3.3oacs1</a></span></dt></dl></dd><dt><span class="appendix"><a href="credits.html">C. Credits</a></span></dt><dd><dl><dt><span class="section"><a href="install-origins.html">Where did this document come from?</a></span></dt><dt><span class="section"><a href="os-install.html">Linux Install Guides</a></span></dt><dt><span class="section"><a href="os-security.html">Security Information</a></span></dt><dt><span class="section"><a href="install-resources.html">Resources</a></span></dt></dl></dd></dl></div> + + + + + + + + + + + + + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="release-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-overview.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Release Notes </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 2. Installation Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/acs-package-dev.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-package-dev.html,v diff -u -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/acs-package-dev.html 7 Aug 2017 23:47:48 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/acs-package-dev.html 8 Nov 2017 09:42:09 -0000 1.35 @@ -1,5 +1,24 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part III. For OpenACS Package Developers</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="install-resources.html" title="Resources"><link rel="next" href="tutorial.html" title="Chapter 9. Development Tutorial"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-resources.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="acs-package-dev"></a>Part III. For OpenACS Package Developers</h1></div></div></div><div class="partintro"><div></div><p>Tutorials and reference material for creating new OpenACS packages. - </p><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="tutorial.html">9. Development Tutorial</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-newpackage.html">Creating an Application Package</a></span></dt><dt><span class="sect1"><a href="tutorial-database.html">Setting Up Database Objects</a></span></dt><dt><span class="sect1"><a href="tutorial-pages.html">Creating Web Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-debug.html">Debugging and Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="tutorial-advanced.html">10. Advanced Topics</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-specs.html">Write the Requirements and Design Specs</a></span></dt><dt><span class="sect1"><a href="tutorial-cvs.html">Add the new package to CVS</a></span></dt><dt><span class="sect1"><a href="tutorial-etp-templates.html">OpenACS Edit This Page Templates</a></span></dt><dt><span class="sect1"><a href="tutorial-comments.html">Adding Comments</a></span></dt><dt><span class="sect1"><a href="tutorial-admin-pages.html">Admin Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-categories.html">Categories</a></span></dt><dt><span class="sect1"><a href="profile-code.html">Profile your code</a></span></dt><dt><span class="sect1"><a href="tutorial-distribute.html">Prepare the package for distribution.</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrades.html">Distributing upgrades of your package</a></span></dt><dt><span class="sect1"><a href="tutorial-notifications.html">Notifications</a></span></dt><dt><span class="sect1"><a href="tutorial-hierarchical.html">Hierarchical data</a></span></dt><dt><span class="sect1"><a href="tutorial-vuh.html">Using .vuh files for pretty urls</a></span></dt><dt><span class="sect1"><a href="tutorial-css-layout.html">Laying out a page with CSS instead of tables</a></span></dt><dt><span class="sect1"><a href="tutorial-html-email.html">Sending HTML email from your application</a></span></dt><dt><span class="sect1"><a href="tutorial-caching.html">Basic Caching</a></span></dt><dt><span class="sect1"><a href="tutorial-schedule-procs.html">Scheduled Procedures</a></span></dt><dt><span class="sect1"><a href="tutorial-wysiwyg-editor.html">Enabling WYSIWYG</a></span></dt><dt><span class="sect1"><a href="tutorial-parameters.html">Adding in parameters for your package</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrade-scripts.html">Writing upgrade scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database.html">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics.html">Future Topics</a></span></dt></dl></dd><dt><span class="chapter"><a href="dev-guide.html">11. Development Reference</a></span></dt><dd><dl><dt><span class="sect1"><a href="packages.html">OpenACS Packages</a></span></dt><dt><span class="sect1"><a href="objects.html">OpenACS Data Models and the Object System</a></span></dt><dt><span class="sect1"><a href="request-processor.html">The Request Processor</a></span></dt><dt><span class="sect1"><a href="db-api.html">The OpenACS Database Access API</a></span></dt><dt><span class="sect1"><a href="templates.html">Using Templates in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions.html">Groups, Context, Permissions</a></span></dt><dt><span class="sect1"><a href="subsites.html">Writing OpenACS Application Pages</a></span></dt><dt><span class="sect1"><a href="parties.html">Parties in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a></span></dt><dt><span class="sect1"><a href="object-identity.html">Object Identity</a></span></dt><dt><span class="sect1"><a href="programming-with-aolserver.html">Programming with AOLserver</a></span></dt><dt><span class="sect1"><a href="form-builder.html">Using Form Builder: building html forms dynamically</a></span></dt></dl></dd><dt><span class="chapter"><a href="eng-standards.html">12. Engineering Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="style-guide.html">OpenACS Style Guide</a></span></dt><dt><span class="sect1"><a href="cvs-guidelines.html"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part III. For OpenACS Package Developers</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="install-resources.html" title="Resources"><link rel="next" href="tutorial.html" title="Chapter 9. Development Tutorial"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-resources.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="acs-package-dev"></a>Part III. For OpenACS Package Developers</h1></div></div></div> + + <div class="partintro"><div></div> + <p>Tutorials and reference material for creating new OpenACS packages. + </p> + <div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="tutorial.html">9. Development Tutorial</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-newpackage.html">Creating an Application Package</a></span></dt><dt><span class="sect1"><a href="tutorial-database.html">Setting Up Database Objects</a></span></dt><dt><span class="sect1"><a href="tutorial-pages.html">Creating Web Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-debug.html">Debugging and Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="tutorial-advanced.html">10. Advanced Topics</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-specs.html">Write the Requirements and Design Specs</a></span></dt><dt><span class="sect1"><a href="tutorial-cvs.html">Add the new package to CVS</a></span></dt><dt><span class="sect1"><a href="tutorial-etp-templates.html">OpenACS Edit This Page Templates</a></span></dt><dt><span class="sect1"><a href="tutorial-comments.html">Adding Comments</a></span></dt><dt><span class="sect1"><a href="tutorial-admin-pages.html">Admin Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-categories.html">Categories</a></span></dt><dt><span class="sect1"><a href="profile-code.html">Profile your code</a></span></dt><dt><span class="sect1"><a href="tutorial-distribute.html">Prepare the package for distribution.</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrades.html">Distributing upgrades of your package</a></span></dt><dt><span class="sect1"><a href="tutorial-notifications.html">Notifications</a></span></dt><dt><span class="sect1"><a href="tutorial-hierarchical.html">Hierarchical data</a></span></dt><dt><span class="sect1"><a href="tutorial-vuh.html">Using .vuh files for pretty urls</a></span></dt><dt><span class="sect1"><a href="tutorial-css-layout.html">Laying out a page with CSS instead of tables</a></span></dt><dt><span class="sect1"><a href="tutorial-html-email.html">Sending HTML email from your application</a></span></dt><dt><span class="sect1"><a href="tutorial-caching.html">Basic Caching</a></span></dt><dt><span class="sect1"><a href="tutorial-schedule-procs.html">Scheduled Procedures</a></span></dt><dt><span class="sect1"><a href="tutorial-wysiwyg-editor.html">Enabling WYSIWYG</a></span></dt><dt><span class="sect1"><a href="tutorial-parameters.html">Adding in parameters for your package</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrade-scripts.html">Writing upgrade scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database.html">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics.html">Future Topics</a></span></dt></dl></dd><dt><span class="chapter"><a href="dev-guide.html">11. Development Reference</a></span></dt><dd><dl><dt><span class="sect1"><a href="packages.html">OpenACS Packages</a></span></dt><dt><span class="sect1"><a href="objects.html">OpenACS Data Models and the Object System</a></span></dt><dt><span class="sect1"><a href="request-processor.html">The Request Processor</a></span></dt><dt><span class="sect1"><a href="db-api.html">The OpenACS Database Access API</a></span></dt><dt><span class="sect1"><a href="templates.html">Using Templates in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions.html">Groups, Context, Permissions</a></span></dt><dt><span class="sect1"><a href="subsites.html">Writing OpenACS Application Pages</a></span></dt><dt><span class="sect1"><a href="parties.html">Parties in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a></span></dt><dt><span class="sect1"><a href="object-identity.html">Object Identity</a></span></dt><dt><span class="sect1"><a href="programming-with-aolserver.html">Programming with AOLserver</a></span></dt><dt><span class="sect1"><a href="form-builder.html">Using Form Builder: building html forms dynamically</a></span></dt></dl></dd><dt><span class="chapter"><a href="eng-standards.html">12. Engineering Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="style-guide.html">OpenACS Style Guide</a></span></dt><dt><span class="sect1"><a href="cvs-guidelines.html"> CVS Guidelines - </a></span></dt><dt><span class="sect1"><a href="eng-standards-versioning.html">Release Version Numbering</a></span></dt><dt><span class="sect1"><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></span></dt><dt><span class="sect1"><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></span></dt><dt><span class="sect1"><a href="eng-standards-plsql.html">PL/SQL Standards</a></span></dt><dt><span class="sect1"><a href="variables.html">Variables</a></span></dt><dt><span class="sect1"><a href="automated-testing-best-practices.html">Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="doc-standards.html">13. Documentation Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="docbook-primer.html">OpenACS Documentation Guide</a></span></dt><dt><span class="sect1"><a href="psgml-mode.html">Using PSGML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="nxml-mode.html">Using nXML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="filename.html">Detailed Design Documentation Template</a></span></dt><dt><span class="sect1"><a href="requirements-template.html">System/Application Requirements Template</a></span></dt></dl></dd><dt><span class="chapter"><a href="i18n.html">14. Internationalization</a></span></dt><dd><dl><dt><span class="sect1"><a href="i18n-overview.html">Internationalization and Localization Overview</a></span></dt><dt><span class="sect1"><a href="i18n-introduction.html">How Internationalization/Localization works in OpenACS</a></span></dt><dt><span class="sect1"><a href="i18n-convert.html">How to Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design.html">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators.html">Translator's Guide</a></span></dt></dl></dd><dt><span class="appendix"><a href="cvs-tips.html">D. Using CVS with an OpenACS Site</a></span></dt></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-resources.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr><tr><td width="40%" align="left">Resources </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 9. Development Tutorial</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </a></span></dt><dt><span class="sect1"><a href="eng-standards-versioning.html">Release Version Numbering</a></span></dt><dt><span class="sect1"><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></span></dt><dt><span class="sect1"><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></span></dt><dt><span class="sect1"><a href="eng-standards-plsql.html">PL/SQL Standards</a></span></dt><dt><span class="sect1"><a href="variables.html">Variables</a></span></dt><dt><span class="sect1"><a href="automated-testing-best-practices.html">Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="doc-standards.html">13. Documentation Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="docbook-primer.html">OpenACS Documentation Guide</a></span></dt><dt><span class="sect1"><a href="psgml-mode.html">Using PSGML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="nxml-mode.html">Using nXML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="filename.html">Detailed Design Documentation Template</a></span></dt><dt><span class="sect1"><a href="requirements-template.html">System/Application Requirements Template</a></span></dt></dl></dd><dt><span class="chapter"><a href="i18n.html">14. Internationalization</a></span></dt><dd><dl><dt><span class="sect1"><a href="i18n-overview.html">Internationalization and Localization Overview</a></span></dt><dt><span class="sect1"><a href="i18n-introduction.html">How Internationalization/Localization works in OpenACS</a></span></dt><dt><span class="sect1"><a href="i18n-convert.html">How to Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design.html">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators.html">Translator's Guide</a></span></dt></dl></dd><dt><span class="appendix"><a href="cvs-tips.html">D. Using CVS with an OpenACS Site</a></span></dt></dl></div></div> + + + + + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-resources.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial.html">Next</a></td></tr><tr><td width="40%" align="left">Resources </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 9. Development Tutorial</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/acs-plat-dev.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/acs-plat-dev.html,v diff -u -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/acs-plat-dev.html 7 Aug 2017 23:47:49 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/acs-plat-dev.html 8 Nov 2017 09:42:09 -0000 1.33 @@ -1,2 +1,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part IV. For OpenACS Platform Developers</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="cvs-tips.html" title="Appendix D. Using CVS with an OpenACS Site"><link rel="next" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="acs-plat-dev"></a>Part IV. For OpenACS Platform Developers</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="kernel-doc.html">15. Kernel Documentation</a></span></dt><dd><dl><dt><span class="sect1"><a href="kernel-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="object-system-requirements.html">Object Model Requirements</a></span></dt><dt><span class="sect1"><a href="object-system-design.html">Object Model Design</a></span></dt><dt><span class="sect1"><a href="permissions-requirements.html">Permissions Requirements</a></span></dt><dt><span class="sect1"><a href="permissions-design.html">Permissions Design</a></span></dt><dt><span class="sect1"><a href="groups-requirements.html">Groups Requirements</a></span></dt><dt><span class="sect1"><a href="groups-design.html">Groups Design</a></span></dt><dt><span class="sect1"><a href="subsites-requirements.html">Subsites Requirements</a></span></dt><dt><span class="sect1"><a href="subsites-design.html">Subsites Design Document</a></span></dt><dt><span class="sect1"><a href="apm-requirements.html">Package Manager Requirements</a></span></dt><dt><span class="sect1"><a href="apm-design.html">Package Manager Design</a></span></dt><dt><span class="sect1"><a href="db-api-detailed.html">Database Access API</a></span></dt><dt><span class="sect1"><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></span></dt><dt><span class="sect1"><a href="security-requirements.html">Security Requirements</a></span></dt><dt><span class="sect1"><a href="security-design.html">Security Design</a></span></dt><dt><span class="sect1"><a href="security-notes.html">Security Notes</a></span></dt><dt><span class="sect1"><a href="rp-requirements.html">Request Processor Requirements</a></span></dt><dt><span class="sect1"><a href="rp-design.html">Request Processor Design</a></span></dt><dt><span class="sect1"><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></span></dt><dt><span class="sect1"><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></span></dt><dt><span class="sect1"><a href="ext-auth-requirements.html">External Authentication Requirements</a></span></dt></dl></dd><dt><span class="chapter"><a href="releasing-openacs.html">16. Releasing OpenACS</a></span></dt><dd><dl><dt><span class="section"><a href="releasing-openacs-core.html">OpenACS Core and .LRN</a></span></dt><dt><span class="section"><a href="update-repository.html">How to Update the OpenACS.org repository</a></span></dt><dt><span class="section"><a href="releasing-package.html">How to package and release an OpenACS Package</a></span></dt><dt><span class="section"><a href="update-translations.html">How to Update the translations</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix D. Using CVS with an OpenACS Site </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 15. Kernel Documentation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part IV. For OpenACS Platform Developers</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="cvs-tips.html" title="Appendix D. Using CVS with an OpenACS Site"><link rel="next" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="acs-plat-dev"></a>Part IV. For OpenACS Platform Developers</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="kernel-doc.html">15. Kernel Documentation</a></span></dt><dd><dl><dt><span class="sect1"><a href="kernel-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="object-system-requirements.html">Object Model Requirements</a></span></dt><dt><span class="sect1"><a href="object-system-design.html">Object Model Design</a></span></dt><dt><span class="sect1"><a href="permissions-requirements.html">Permissions Requirements</a></span></dt><dt><span class="sect1"><a href="permissions-design.html">Permissions Design</a></span></dt><dt><span class="sect1"><a href="groups-requirements.html">Groups Requirements</a></span></dt><dt><span class="sect1"><a href="groups-design.html">Groups Design</a></span></dt><dt><span class="sect1"><a href="subsites-requirements.html">Subsites Requirements</a></span></dt><dt><span class="sect1"><a href="subsites-design.html">Subsites Design Document</a></span></dt><dt><span class="sect1"><a href="apm-requirements.html">Package Manager Requirements</a></span></dt><dt><span class="sect1"><a href="apm-design.html">Package Manager Design</a></span></dt><dt><span class="sect1"><a href="db-api-detailed.html">Database Access API</a></span></dt><dt><span class="sect1"><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></span></dt><dt><span class="sect1"><a href="security-requirements.html">Security Requirements</a></span></dt><dt><span class="sect1"><a href="security-design.html">Security Design</a></span></dt><dt><span class="sect1"><a href="security-notes.html">Security Notes</a></span></dt><dt><span class="sect1"><a href="rp-requirements.html">Request Processor Requirements</a></span></dt><dt><span class="sect1"><a href="rp-design.html">Request Processor Design</a></span></dt><dt><span class="sect1"><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></span></dt><dt><span class="sect1"><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></span></dt><dt><span class="sect1"><a href="ext-auth-requirements.html">External Authentication Requirements</a></span></dt></dl></dd><dt><span class="chapter"><a href="releasing-openacs.html">16. Releasing OpenACS</a></span></dt><dd><dl><dt><span class="section"><a href="releasing-openacs-core.html">OpenACS Core and .LRN</a></span></dt><dt><span class="section"><a href="update-repository.html">How to Update the OpenACS.org repository</a></span></dt><dt><span class="section"><a href="releasing-package.html">How to package and release an OpenACS Package</a></span></dt><dt><span class="section"><a href="update-translations.html">How to Update the translations</a></span></dt></dl></dd></dl></div> + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-tips.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-doc.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix D. Using CVS with an OpenACS Site </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 15. Kernel Documentation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/analog-install.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-install.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/analog-install.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/analog-install.adp 8 Nov 2017 09:42:09 -0000 1.3 @@ -25,12 +25,12 @@ [root analog-5.32]# <strong class="userinput"><code>cd ..</code></strong> [root src]#<strong class="userinput"><code> mv analog-5.32 /usr/share/</code></strong> [root src]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src tar xzf /tmp/analog-5.32.tar.gz cd analog-5.32 make cd .. -mv analog-5.32 /usr/share/</span></span> +mv analog-5.32 /usr/share/</span> </pre><p>See also <a class="xref" href="analog-setup" title="Set up Log Analysis Reports">the section called “Set up Log Analysis Reports”</a> Index: openacs-4/packages/acs-core-docs/www/analog-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-install.html,v diff -u -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/analog-install.html 7 Aug 2017 23:47:49 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/analog-install.html 8 Nov 2017 09:42:09 -0000 1.25 @@ -1,6 +1,9 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Analog web file analyzer</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-qmail.html" title="Install qmail (OPTIONAL)"><link rel="next" href="install-nspam.html" title="Install nspam"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-nspam.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="analog-install"></a>Install Analog web file analyzer</h2></div></div></div><p>Download the Analog <a class="link" href="individual-programs.html#analog-download" title="Analog 5.32 or newer, OPTIONAL">source tarball</a> in -<code class="computeroutput">/tmp</code>. Unpack, compile, and install analog.</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Analog web file analyzer</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-qmail.html" title="Install qmail (OPTIONAL)"><link rel="next" href="install-nspam.html" title="Install nspam"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-nspam.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="analog-install"></a>Install Analog web file analyzer</h2></div></div></div> + + <p>Download the Analog <a class="link" href="individual-programs.html#analog-download" title="Analog 5.32 or newer, OPTIONAL">source tarball</a> in +<code class="computeroutput">/tmp</code>. Unpack, compile, and install analog.</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>tar xzf /tmp/analog-5.32.tar.gz</code></strong> [root src]# <strong class="userinput"><code>cd analog-5.32</code></strong> [root analog-5.32]# <strong class="userinput"><code>make</code></strong> @@ -13,9 +16,11 @@ [root analog-5.32]# <strong class="userinput"><code>cd ..</code></strong> [root src]#<strong class="userinput"><code> mv analog-5.32 /usr/share/</code></strong> [root src]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src tar xzf /tmp/analog-5.32.tar.gz cd analog-5.32 make cd .. -mv analog-5.32 /usr/share/</span></span></pre><p>See also <a class="xref" href="analog-setup.html" title="Set up Log Analysis Reports">the section called “Set up Log Analysis Reports”</a></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-nspam.html">Next</a></td></tr><tr><td width="40%" align="left">Install qmail (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install nspam</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +mv analog-5.32 /usr/share/</span></pre> + <p>See also <a class="xref" href="analog-setup.html" title="Set up Log Analysis Reports">the section called “Set up Log Analysis Reports”</a></p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-qmail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-nspam.html">Next</a></td></tr><tr><td width="40%" align="left">Install qmail (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install nspam</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/analog-setup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-setup.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/analog-setup.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/analog-setup.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -19,12 +19,12 @@ [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>mkdir www/log</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cp -r /usr/share/analog-5.32/images www/log/</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <span class="action"><span class="action"> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <span class="action"> su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver/$OPENACS_SERVICE_NAME cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg mkdir www/log -cp -r /usr/share/analog-5.32/images www/log/</span></span> +cp -r /usr/share/analog-5.32/images www/log/</span> </pre><p>Edit <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg</code> and change the variable in <code class="computeroutput">HOSTNAME "[my organisation]"</code> to reflect your website title. @@ -53,12 +53,12 @@ </pre><p>Put this into the file:</p><pre class="programlisting"> #!/bin/sh -/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/analog.cfg +/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/analog.cfg </pre><pre class="screen"> [root root]# <strong class="userinput"><code>chmod 755 /etc/cron.daily/analog</code></strong> </pre><p>Test it by running the script.</p><pre class="screen"> [root root]# <strong class="userinput"><code>sh /etc/cron.daily/analog</code></strong> -</pre><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>/log/traffic.html</code> +</pre><p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver.test</code></em>/log/traffic.html</code> </p> </li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/analog-setup.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/analog-setup.html,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/analog-setup.html 7 Aug 2017 23:47:49 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/analog-setup.html 8 Nov 2017 09:42:10 -0000 1.17 @@ -1,32 +1,53 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Set up Log Analysis Reports</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-ssl.html" title="Installing SSL Support for an OpenACS service"><link rel="next" href="uptime.html" title="External uptime validation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-ssl.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="uptime.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="analog-setup"></a>Set up Log Analysis Reports</h2></div></div></div><p>Analog is a program with processes webserver access logs, +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Set up Log Analysis Reports</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-ssl.html" title="Installing SSL Support for an OpenACS service"><link rel="next" href="uptime.html" title="External uptime validation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-ssl.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="uptime.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="analog-setup"></a>Set up Log Analysis Reports</h2></div></div></div> + + + <p>Analog is a program with processes webserver access logs, performs DNS lookup, and outputs HTML reports. Analog should <a class="link" href="analog-install.html" title="Install Analog web file analyzer">already be installed.</a> A modified configuration file is included in - the OpenACS tarball.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><pre class="screen">[root src]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> + the OpenACS tarball.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <pre class="screen">[root src]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>mkdir www/log</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cp -r /usr/share/analog-5.32/images www/log/</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <span class="action"><span class="action"> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <span class="action"> su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver/$OPENACS_SERVICE_NAME cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg mkdir www/log -cp -r /usr/share/analog-5.32/images www/log/</span></span></pre><p>Edit +cp -r /usr/share/analog-5.32/images www/log/</span></pre> + <p>Edit <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg</code> and change the variable in <code class="computeroutput">HOSTNAME "[my organisation]"</code> to reflect your website title. If you don't want the traffic log to be publicly visible, change <code class="computeroutput">OUTFILE /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.html</code> to use a private -directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.</p></li><li class="listitem"><p>Run it.</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg</code></strong> +directory. You'll also need to edit all instances of service0 to your $OPENACS_SERVICE_NAME.</p> + </li><li class="listitem"> + <p>Run it.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg</code></strong> /usr/share/analog-5.32/analog: analog version 5.32/Unix /usr/share/analog-5.32/analog: Warning F: Failed to open DNS input file /home/$OPENACS_SERVICE_NAME/dnscache: ignoring it (For help on all errors and warnings, see docs/errors.html) /usr/share/analog-5.32/analog: Warning R: Turning off empty Search Word Report -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre><p>Verify that it works by browing to <code class="computeroutput">http://yourserver.test:8000/log/traffic.html</code></p></li><li class="listitem"><p>Automate this by creating a file in - <code class="computeroutput">/etc/cron.daily</code>.</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre> + <p>Verify that it works by browing to <code class="computeroutput">http://yourserver.test:8000/log/traffic.html</code></p> + </li><li class="listitem"> + <p>Automate this by creating a file in + <code class="computeroutput">/etc/cron.daily</code>.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> logout -[root root]# <strong class="userinput"><code>emacs /etc/cron.daily/analog</code></strong></pre><p>Put this into the file:</p><pre class="programlisting">#!/bin/sh +[root root]# <strong class="userinput"><code>emacs /etc/cron.daily/analog</code></strong></pre> + <p>Put this into the file:</p> + <pre class="programlisting">#!/bin/sh -/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/analog.cfg</pre><pre class="screen">[root root]# <strong class="userinput"><code>chmod 755 /etc/cron.daily/analog</code></strong></pre><p>Test it by running the script.</p><pre class="screen">[root root]# <strong class="userinput"><code>sh /etc/cron.daily/analog</code></strong></pre><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>/log/traffic.html</code></p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-ssl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="uptime.html">Next</a></td></tr><tr><td width="40%" align="left">Installing SSL Support for an OpenACS service </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> External uptime validation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +/usr/share/analog-5.32/analog -G -g/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/analog.cfg</pre> + <pre class="screen">[root root]# <strong class="userinput"><code>chmod 755 /etc/cron.daily/analog</code></strong></pre> + <p>Test it by running the script.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>sh /etc/cron.daily/analog</code></strong></pre> + <p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver.test</code></em>/log/traffic.html</code></p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-ssl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="uptime.html">Next</a></td></tr><tr><td width="40%" align="left">Installing SSL Support for an OpenACS service </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> External uptime validation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/aolserver.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/aolserver.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/aolserver.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,20 +10,17 @@ rightLink="credits" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="aolserver" id="aolserver"></a>Install AOLserver 3.3oacs1</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>We recommend the use of <a class="link" href="aolserver4" title="Install AOLserver 4">AOLserver 4.0.1</a> or later. These +<a name="aolserver" id="aolserver"></a>Install AOLserver 3.3oacs1</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> +</span></p><span style="color: red"></authorblurb></span><p>We recommend the use of <a class="link" href="aolserver4" title="Install AOLserver 4">AOLserver 4.0.1</a> or later. These instructions are retained as a resource.</p><p>Debian users: we do not recommend installing Debian packages for Aolserver or Postgres. Several people have reported problems while trying to install using apt-get instead of from source. If you have the time to debug these and submit what you did, that's great, but if not, you should stick to installing from source.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> <a name="aolserver-tarball" id="aolserver-tarball"></a><p> -<strong>Unpack the Aolserver -tarball. </strong>Download the <a class="link" href="individual-programs">aolserver tarball</a> +<strong>Unpack the Aolserver tarball. </strong> +Download the <a class="link" href="individual-programs">aolserver tarball</a> and unpack it.</p><pre class="screen"> [root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz</code></strong> @@ -39,16 +36,16 @@ 15:39:05 (66.56 KB/s) - `aolserver3.3oacs1.tar.gz' saved [3858074/3858074] [root src]# <strong class="userinput"><code>tar xzf aolserver3.3oacs1.tar.gz</code></strong> [root src]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz -tar xzf aolserver3.3oacs1.tar.gz</span></span> +tar xzf aolserver3.3oacs1.tar.gz</span> </pre><p>This section also relies on some OpenACS files, which you can get with <a class="xref" href="openacs-unpack" title="Unpack the OpenACS tarball">the section called “Unpack the OpenACS tarball”</a>.</p> </li><li class="listitem"> <a name="install-aolserver-compile" id="install-aolserver-compile"></a><p> -<strong>Compile AOLserver. </strong>Compile and +<strong>Compile AOLserver. </strong> Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.</p><pre class="screen"> @@ -57,9 +54,9 @@ [root aolserver]# <strong class="userinput"><code>./conf-clean</code></strong> cat: BUILD-MODULES: No such file or directory Done. -[root aolserver]#<span class="action"><span class="action">mkdir -p /usr/local/aolserver +[root aolserver]#<span class="action">mkdir -p /usr/local/aolserver cd /usr/local/src/aolserver -./conf-clean</span></span> +./conf-clean</span> </pre><p>If you are using Oracle, edit <code class="computeroutput">conf-db</code> and change <code class="computeroutput">postgresql</code> to <code class="computeroutput">oracle</code>, or to the word <code class="computeroutput">both</code> if you want both drivers installed. In order to get nsoracle to compile, you may need to su - oracle, and then su (without the -) root to set the environment variables @@ -113,7 +110,7 @@ </li><li class="listitem"> <a name="aolserver-db-wrapper" id="aolserver-db-wrapper"></a><p> <strong>Add a database-specific wrapper -script. </strong>This script sets database environment +script. </strong> This script sets database environment variables before starting AOLserver; this allows the AOLserver instance can communicate with the database. There is one script each for Oracle and PostgreSQL. They don't conflict, so if you @@ -124,25 +121,25 @@ [root bin]# <strong class="userinput"><code>cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</code></strong> [root bin]# <strong class="userinput"><code>chmod 750 nsd-oracle</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle -chmod 750 nsd-oracle</span></span> +chmod 750 nsd-oracle</span> </pre> </li><li class="listitem"> <p>PostgreSQL</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> [root bin]# <strong class="userinput"><code>cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</code></strong> [root bin]# <strong class="userinput"><code>chmod 755 nsd-postgres</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres -chmod 755 nsd-postgres</span></span> +chmod 755 nsd-postgres</span> </pre> </li> </ul></div> </li><li class="listitem"> <a name="install-tdom" id="install-tdom"></a><p> -<strong>Install tDOM. </strong>Download the +<strong>Install tDOM. </strong> Download the <a class="link" href="individual-programs">tDOM tarball</a>, unpack it, adjust the configuration file to match our patched distribution of aolserver, and compile it.</p><pre class="screen"> @@ -162,10 +159,10 @@ [root src]# <strong class="userinput"><code>tar xzf tDOM-0.7.8.tar.gz</code></strong> [root src]# <strong class="userinput"><code>cd tDOM-0.7.8/unix</code></strong> [root unix]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz tar xzf tDOM-0.7.8.tar.gz -cd tDOM-0.7.8/unix</span></span> +cd tDOM-0.7.8/unix</span> </pre><p>Edit the file CONFIG and change this section:</p><pre class="programlisting"> # ---------------------------------------------------- # aolsrc="/usr/src/aolserver-3.4" @@ -196,19 +193,19 @@ [root bin]# <strong class="userinput"><code>ln -s libtdom0.7.8.so libtdom.so</code></strong> [root bin]# -<span class="action"><span class="action">sh CONFIG +<span class="action">sh CONFIG make cp libtdom0.7.8.so /usr/local/aolserver/bin/ cd /usr/local/aolserver/bin -ln -s libtdom0.7.8.so libtdom.so</span></span> +ln -s libtdom0.7.8.so libtdom.so</span> </pre> </li><li class="listitem"><p> <a class="link" href="install-nsopenssl" title="Install nsopenssl">Install nsopenssl</a> (OPTIONAL)</p></li><li class="listitem"><p> -<a class="link" href="install-full-text-search-openfts" title="Install OpenFTS module">Install Full Text Search with OpenFTS</a> -(OPTIONAL)</p></li><li class="listitem"><p> +<a class="link" href="">Install Full Text Search with +OpenFTS</a> (OPTIONAL)</p></li><li class="listitem"><p> <a class="link" href="install-nspam" title="Install nspam">Install nspam</a> (OPTIONAL)</p></li><li class="listitem"> <a name="install-aolserver-permissions" id="install-aolserver-permissions"></a><p> -<strong>Test AOLserver. </strong>In order to test +<strong>Test AOLserver. </strong> In order to test AOLserver, we'll run it using the sample-config.tcl file provided in the AOLserver distribution, under the nobody user and <code class="computeroutput">web</code> group. The @@ -229,11 +226,11 @@ -rw-r--r-- 1 root root 7320 Mar 31 2001 sample-config.tcl drwxrwsr-x 3 root web 4096 Mar 8 10:31 servers [root aolserver]# -<span class="action"><span class="action"> +<span class="action"> cd /usr/local/aolserver chown -R root.web log servers chmod -R g+w log servers -ls -l</span></span> +ls -l</span> </pre><p>Note: AOLserver4.x does not include a default start page, so we create one for this test. Type <strong class="userinput"><code>echo "Welcome to AOLserver" > @@ -277,7 +274,7 @@ alive</a> section.</p> </li><li class="listitem"> <a name="install-aolserver-troubleshooting" id="install-aolserver-troubleshooting"></a><p> -<strong>Troubleshooting. </strong>If you can't +<strong>Troubleshooting. </strong> If you can't view the welcome page, it's likely there's a problem with your server configuration. Start by viewing your AOLserver log, which is in <code class="computeroutput">/usr/local/aolserver/log/server.log</code>. You @@ -303,8 +300,8 @@ </li><li class="listitem"><p> <a class="link" href="analog-install" title="Install Analog web file analyzer">Install Analog</a> web file analyzer. (OPTIONAL)</p></li> -</ol></div><div class="cvstag">($‌Id: aolserver.xml,v 1.22.14.2 2017/04/22 -17:18:48 gustafn Exp $)</div> +</ol></div><p><span class="cvstag">($‌Id: aolserver.xml,v 1.23 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="install-ldap-radius" leftLabel="Prev" leftTitle="Install LDAP for use as external Index: openacs-4/packages/acs-core-docs/www/aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver.html,v diff -u -r1.53 -r1.54 --- openacs-4/packages/acs-core-docs/www/aolserver.html 7 Aug 2017 23:47:49 -0000 1.53 +++ openacs-4/packages/acs-core-docs/www/aolserver.html 8 Nov 2017 09:42:10 -0000 1.54 @@ -1,15 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install AOLserver 3.3oacs1</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-ldap-radius.html" title="Install LDAP for use as external authentication"><link rel="next" href="credits.html" title="Appendix C. Credits"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-ldap-radius.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aolserver"></a>Install AOLserver 3.3oacs1</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>We recommend the use of <a class="link" href="aolserver4.html" title="Install AOLserver 4">AOLserver 4.0.1</a> or later. These instructions are retained as a resource.</p><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install AOLserver 3.3oacs1</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-ldap-radius.html" title="Install LDAP for use as external authentication"><link rel="next" href="credits.html" title="Appendix C. Credits"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-ldap-radius.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aolserver"></a>Install AOLserver 3.3oacs1</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> + </authorblurb></span> + + <p>We recommend the use of <a class="link" href="aolserver4.html" title="Install AOLserver 4">AOLserver 4.0.1</a> or later. These instructions are retained as a resource.</p> + <p> Debian users: we do not recommend installing Debian packages for Aolserver or Postgres. Several people have reported problems while trying to install using apt-get instead of from source. If you have the time to debug these and submit what you did, that's great, but if not, you should stick to installing from source. - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a name="aolserver-tarball"></a><p><b>Unpack the Aolserver tarball. </b>Download the <a class="link" href="individual-programs.html#source-aolserver">aolserver tarball</a> and unpack it.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a name="aolserver-tarball"></a> + <p> + <b>Unpack the Aolserver tarball. </b> + Download the <a class="link" href="individual-programs.html#source-aolserver">aolserver tarball</a> and unpack it. + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz</code></strong> --15:38:08-- http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz => `aolserver3.3oacs1.tar.gz' @@ -23,16 +35,24 @@ 15:39:05 (66.56 KB/s) - `aolserver3.3oacs1.tar.gz' saved [3858074/3858074] [root src]# <strong class="userinput"><code>tar xzf aolserver3.3oacs1.tar.gz</code></strong> [root src]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz -tar xzf aolserver3.3oacs1.tar.gz</span></span></pre><p>This section also relies on some OpenACS files, which you can get with <a class="xref" href="openacs-unpack.html" title="Unpack the OpenACS tarball">the section called “Unpack the OpenACS tarball”</a>.</p></li><li class="listitem"><a name="install-aolserver-compile"></a><p><b>Compile AOLserver. </b>Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored.</p><pre class="screen">root@yourserver root]# <strong class="userinput"><code>mkdir -p /usr/local/aolserver</code></strong> +tar xzf aolserver3.3oacs1.tar.gz</span></pre> + <p>This section also relies on some OpenACS files, which you can get with <a class="xref" href="openacs-unpack.html" title="Unpack the OpenACS tarball">the section called “Unpack the OpenACS tarball”</a>.</p> + </li><li class="listitem"><a name="install-aolserver-compile"></a> + <p> + <b>Compile AOLserver. </b> + Compile and install AOLserver. First, prepare the installation directory and the source code. The message about BUILD-MODULES can be ignored. + </p> + <pre class="screen">root@yourserver root]# <strong class="userinput"><code>mkdir -p /usr/local/aolserver</code></strong> [root root]# <strong class="userinput"><code>cd /usr/local/src/aolserver</code></strong> [root aolserver]# <strong class="userinput"><code>./conf-clean</code></strong> cat: BUILD-MODULES: No such file or directory Done. -[root aolserver]#<span class="action"><span class="action">mkdir -p /usr/local/aolserver +[root aolserver]#<span class="action">mkdir -p /usr/local/aolserver cd /usr/local/src/aolserver -./conf-clean</span></span></pre><p> +./conf-clean</span></pre> + <p> If you are using Oracle, edit <code class="computeroutput">conf-db</code> and change <code class="computeroutput">postgresql</code> to @@ -41,21 +61,29 @@ installed. In order to get nsoracle to compile, you may need to su - oracle, and then su (without the -) root to set the environment variables properly. - </p><p><code class="computeroutput">conf-inst</code> should contain the + </p> + + <p><code class="computeroutput">conf-inst</code> should contain the location where AOLserver is to be installed. Overwrite the - tarball's default value with our default value, <code class="computeroutput">/usr/local/aolserver</code>:</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>echo "/usr/local/aolserver" > conf-inst</code></strong> -[root aolserver]#</pre><p><code class="computeroutput">conf-make</code> should contain the + tarball's default value with our default value, <code class="computeroutput">/usr/local/aolserver</code>:</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>echo "/usr/local/aolserver" > conf-inst</code></strong> +[root aolserver]#</pre> + + <p><code class="computeroutput">conf-make</code> should contain the name of the GNU Make command on your system. It defaults to - <code class="computeroutput">gmake</code>. Debian users: <code class="computeroutput"><strong class="userinput"><code>ln -s /usr/bin/make /usr/bin/gmake</code></strong></code>.</p><p>Set an environment variable that the nspostgres driver + <code class="computeroutput">gmake</code>. Debian users: <code class="computeroutput"><strong class="userinput"><code>ln -s /usr/bin/make /usr/bin/gmake</code></strong></code>.</p> + <p>Set an environment variable that the nspostgres driver Makefile needs to compile correctly and run <code class="computeroutput">conf</code>, which compiles AOLserver, the default modules, and the database driver, and - installs them.</p><p>Debian users, see + installs them.</p> + <p>Debian users, see warning above, but if you do use apt-get for AOLserver 3.3+ad13 and postgresql from apt-get may need to make these symlinks: <code class="computeroutput">ln -s /usr/include/postgresql/ /usr/include/pgsql</code> - and <code class="computeroutput">ln -s /usr/lib/postgresql /usr/local/pgsql</code>)</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>export POSTGRES=/usr/local/pgsql; ./conf</code></strong> + and <code class="computeroutput">ln -s /usr/lib/postgresql /usr/local/pgsql</code>)</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>export POSTGRES=/usr/local/pgsql; ./conf</code></strong> Building in /usr/local/aolserver with the following modules: AOLserver @@ -76,27 +104,47 @@ Creating ... ================================================================== Done Building Sat Mar 8 10:31:35 PST 2003 -[root aolserver]# </pre><p> - This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in <code class="computeroutput">/usr/local/src/aolserver/log</code>. If you run into problems running AOLserver, check these files for build errors.</p></li><li class="listitem"><a name="aolserver-db-wrapper"></a><p><b>Add a database-specific wrapper script. </b>This script +[root aolserver]# </pre> + + <p> + This takes about 5 minutes. It builds aolserver, several modules, and the database driver. (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so). All of the results are logged to files in <code class="computeroutput">/usr/local/src/aolserver/log</code>. If you run into problems running AOLserver, check these files for build errors.</p> + </li><li class="listitem"><a name="aolserver-db-wrapper"></a> + <p> + <b>Add a database-specific wrapper script. </b> +This script sets database environment variables before starting AOLserver; this allows the AOLserver instance can communicate with the database. There is one script each for Oracle and PostgreSQL. They don't conflict, so if you plan - to use both databases, install both.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Oracle</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> + to use both databases, install both. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Oracle</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> [root bin]# <strong class="userinput"><code>cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</code></strong> [root bin]# <strong class="userinput"><code>chmod 750 nsd-oracle</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle -chmod 750 nsd-oracle</span></span></pre></li><li class="listitem"><p>PostgreSQL</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> +chmod 750 nsd-oracle</span></pre> + </li><li class="listitem"> + <p>PostgreSQL</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> [root bin]# <strong class="userinput"><code>cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</code></strong> [root bin]# <strong class="userinput"><code>chmod 755 nsd-postgres</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres -chmod 755 nsd-postgres</span></span></pre></li></ul></div></li><li class="listitem"><a name="install-tdom"></a><p><b>Install tDOM. </b>Download the <a class="link" href="individual-programs.html#source-tdom">tDOM +chmod 755 nsd-postgres</span></pre> + </li></ul></div> + </li><li class="listitem"><a name="install-tdom"></a> + <p> + <b>Install tDOM. </b> + Download the <a class="link" href="individual-programs.html#source-tdom">tDOM tarball</a>, unpack it, adjust the configuration file to match our patched - distribution of aolserver, and compile it.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> + distribution of aolserver, and compile it. + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz</code></strong> --16:40:58-- http://www.tdom.org/tDOM-0.7.8.tar.gz => `tDOM-0.7.8.tar.gz' @@ -112,18 +160,24 @@ [root src]# <strong class="userinput"><code>tar xzf tDOM-0.7.8.tar.gz</code></strong> [root src]# <strong class="userinput"><code>cd tDOM-0.7.8/unix</code></strong> [root unix]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz tar xzf tDOM-0.7.8.tar.gz -cd tDOM-0.7.8/unix</span></span> </pre><p>Edit the file CONFIG and change this section:</p><pre class="programlisting"># ---------------------------------------------------- +cd tDOM-0.7.8/unix</span> </pre> + <p>Edit the file CONFIG and change this section:</p> +<pre class="programlisting"># ---------------------------------------------------- # aolsrc="/usr/src/aolserver-3.4" # ../configure --enable-threads --disable-tdomalloc \ # --with-aolserver=$aolsrc \ -# --with-tcl=$aolsrc/tcl8.3.4/unix </pre><p>to</p><pre class="programlisting"># ---------------------------------------------------- +# --with-tcl=$aolsrc/tcl8.3.4/unix </pre> +<p>to</p> +<pre class="programlisting"># ---------------------------------------------------- aolsrc="/usr/local/src/aolserver/aolserver" ../configure --enable-threads --disable-tdomalloc \ --with-aolserver=$aolsrc \ - --with-tcl=$aolsrc/tcl8.3.2/unix</pre><p>And configure and compile:</p><pre class="screen">[root unix]# <strong class="userinput"><code>sh CONFIG</code></strong> + --with-tcl=$aolsrc/tcl8.3.2/unix</pre> + <p>And configure and compile:</p> + <pre class="screen">[root unix]# <strong class="userinput"><code>sh CONFIG</code></strong> creating cache ./config.cache checking for memmove... yes <span class="emphasis"><em>(many lines omitted)</em></span> @@ -140,20 +194,32 @@ [root bin]# <strong class="userinput"><code>ln -s libtdom0.7.8.so libtdom.so</code></strong> [root bin]# -<span class="action"><span class="action">sh CONFIG +<span class="action">sh CONFIG make cp libtdom0.7.8.so /usr/local/aolserver/bin/ cd /usr/local/aolserver/bin -ln -s libtdom0.7.8.so libtdom.so</span></span></pre></li><li class="listitem"><p><a class="link" href="install-nsopenssl.html" title="Install nsopenssl">Install nsopenssl</a> - (OPTIONAL)</p></li><li class="listitem"><p><a class="link" href="install-full-text-search-openfts.html#install-openfts" title="Install OpenFTS module">Install Full Text Search with OpenFTS</a> (OPTIONAL)</p></li><li class="listitem"><p><a class="link" href="install-nspam.html" title="Install nspam">Install nspam</a> (OPTIONAL)</p></li><li class="listitem"><a name="install-aolserver-permissions"></a><p><b>Test AOLserver. </b>In order to test AOLserver, we'll run it using the +ln -s libtdom0.7.8.so libtdom.so</span></pre> + </li><li class="listitem"> + <p><a class="link" href="install-nsopenssl.html" title="Install nsopenssl">Install nsopenssl</a> + (OPTIONAL)</p> + </li><li class="listitem"> + <p><a class="link" href="">Install Full Text Search with OpenFTS</a> (OPTIONAL)</p> + </li><li class="listitem"> + <p><a class="link" href="install-nspam.html" title="Install nspam">Install nspam</a> (OPTIONAL)</p> + </li><li class="listitem"><a name="install-aolserver-permissions"></a> + <p> + <b>Test AOLserver. </b> + In order to test AOLserver, we'll run it using the sample-config.tcl file provided in the AOLserver distribution, under the nobody user and <code class="computeroutput">web</code> group. The sample-config.tcl configuration writes to the default log locations, so we need to give it permission to do so or it will fail. Grant the <code class="computeroutput">web</code> group permission to write to <code class="computeroutput">/usr/local/aolserver/log</code> and - <code class="computeroutput">/usr/local/aolserver/servers</code>.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/aolserver</code></strong> + <code class="computeroutput">/usr/local/aolserver/servers</code>. + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/aolserver</code></strong> [root aolserver]# <strong class="userinput"><code>chown -R root.web log servers</code></strong> [root aolserver]# <strong class="userinput"><code>chmod -R g+w log servers</code></strong> [root aolserver]# <strong class="userinput"><code>ls -l</code></strong> @@ -166,24 +232,33 @@ -rw-r--r-- 1 root root 7320 Mar 31 2001 sample-config.tcl drwxrwsr-x 3 root web 4096 Mar 8 10:31 servers [root aolserver]# -<span class="action"><span class="action"> +<span class="action"> cd /usr/local/aolserver chown -R root.web log servers chmod -R g+w log servers -ls -l</span></span></pre><p>Note: AOLserver4.x does not include a default start page, so we create one for this test. Type +ls -l</span></pre> + + <p>Note: AOLserver4.x does not include a default start page, so we create one for this test. Type <strong class="userinput"><code>echo "Welcome to AOLserver" > /usr/local/aolserver40r8/servers/server1/pages/index.html</code></strong> - </p><p>Now, we'll run a quick test to ensure AOLserver is running + </p> + <p>Now, we'll run a quick test to ensure AOLserver is running correctly. We'll use the sample config file provided with AOLserver. This file will attempt to guess your IP address and hostname. It will then start up the server at port 8000 of that - IP address.</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>./bin/nsd -t sample-config.tcl -u nobody -g web</code></strong> + IP address.</p> + + <pre class="screen">[root aolserver]# <strong class="userinput"><code>./bin/nsd -t sample-config.tcl -u nobody -g web</code></strong> [root aolserver]# [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: starting to read config file... [08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nsssl not loaded -- key/cert files do not exist. [08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nscp not loaded -- user/password is not set. [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading -config file.</pre><p>The first warning, about nsssl, can be ignored. We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet. The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load. We don't plan to use it and can ignore that error as well. Any other warning or error is unexpected and probably a problem.</p><p> +config file.</pre> + <p>The first warning, about nsssl, can be ignored. We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet. The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load. We don't plan to use it and can ignore that error as well. Any other warning or error is unexpected and probably a problem.</p> + + <p> + Test to see if AOLserver is working by starting <code class="computeroutput">Mozilla</code> or <code class="computeroutput">Lynx</code> <span class="emphasis"><em>on the same @@ -192,53 +267,86 @@ didn't guess your hostname or ip correctly, you'll get a false negative test. - </p><pre class="screen">[root aolserver]# <strong class="userinput"><code>lynx localhost:8000</code></strong></pre><p> + </p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>lynx localhost:8000</code></strong></pre> + + <p> + You should see a "Welcome to AOLserver" page. If this doesn't work, try going to <code class="computeroutput">http://127.0.0.1:8000/</code>. If this still doesn't work, check out the <a class="xref" href="aolserver.html#install-aolserver-troubleshooting">Troubleshooting AOLserver</a> section below. Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address. - </p><p>Shutdown the test server:</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>killall nsd</code></strong> -[root aolserver]#</pre><p> + </p> + <p>Shutdown the test server:</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>killall nsd</code></strong> +[root aolserver]#</pre> + + <p> + The <code class="computeroutput">killall</code> command will kill all processes with the name <code class="computeroutput">nsd</code>, but clearly this is not a good tool to use for managing your services in general. We cover this topic in the <a class="xref" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance.">Keep AOLserver alive</a> section. - </p></li><li class="listitem"><a name="install-aolserver-troubleshooting"></a><p><b>Troubleshooting. </b>If you can't view the welcome page, it's likely there's a + </p> + </li><li class="listitem"><a name="install-aolserver-troubleshooting"></a> + <p> + <b>Troubleshooting. </b> + If you can't view the welcome page, it's likely there's a problem with your server configuration. Start by viewing your AOLserver log, which is in <code class="computeroutput">/usr/local/aolserver/log/server.log</code>. You should also try to find lines of the form: - </p><pre class="screen"> + + </p> + <pre class="screen"> [01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) -[01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: accepting connections</pre><p> +[01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: accepting connections</pre> + <p> + If you can find these lines, try entering the URL the server is listening on. If you cannot find these lines, there must be an error somewhere in the file. Search for lines beginning with the word <code class="computeroutput">Error</code> instead of <code class="computeroutput">Notice</code>. - </p><p> + </p> + <p> + The <code class="computeroutput">sample-config.tcl</code> file grabs your address and hostname from your OS settings. - </p><pre class="screen"> + </p> + + <pre class="screen"> set hostname [ns_info hostname] -set address [ns_info address]</pre><p> +set address [ns_info address]</pre> + <p> + If you get an error that nssock can't get the requested address, you can set these manually. If you type 0.0.0.0, AOLserver will try to listen on all available addresses. <span class="emphasis"><em>Note</em></span>: <code class="computeroutput">ns_info address</code> doesn't appear to be supported in current versions of AOLserver. - </p><pre class="screen"> + </p> + + <pre class="screen"> set hostname [ns_info hostname] #set address [ns_info address] -set address 0.0.0.0</pre></li><li class="listitem"><p><a class="link" href="analog-install.html" title="Install Analog web file analyzer">Install - Analog</a> web file analyzer. (OPTIONAL)</p></li></ol></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-ldap-radius.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr><tr><td width="40%" align="left">Install LDAP for use as external authentication </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Appendix C. Credits</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +set address 0.0.0.0</pre> + + </li><li class="listitem"> + <p><a class="link" href="analog-install.html" title="Install Analog web file analyzer">Install + Analog</a> web file analyzer. (OPTIONAL)</p> + </li></ol></div> + + <p><span class="cvstag">($Id$)</span></p> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-ldap-radius.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="credits.html">Next</a></td></tr><tr><td width="40%" align="left">Install LDAP for use as external authentication </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Appendix C. Credits</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/aolserver4.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver4.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/aolserver4.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/aolserver4.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,39 +9,37 @@ rightLink="openacs" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="aolserver4" id="aolserver4"></a>Install AOLserver 4</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:sussdorff\@sussdorff.de" target="_top">Malte Sussdorff</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="orderedlist"><ol class="orderedlist" type="1"> +<a name="aolserver4" id="aolserver4"></a>Install AOLserver 4</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:sussdorff\@sussdorff.de" target="_top">Malte +Sussdorff</a> +</span></p><span style="color: red"></authorblurb></span><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> <p> <strong>Check suitability of previously installed -TCL. </strong>Start Tcl (type <strong class="userinput"><code>tclsh</code></strong> or find it using +TCL. </strong> Start Tcl (type <strong class="userinput"><code>tclsh</code></strong> or find it using <strong class="userinput"><code>which tclsh</code></strong>).</p><pre class="screen"> [root root]% <strong class="userinput"><code>info exists tcl_platform(threaded)</code></strong> 1 [root root]% <strong class="userinput"><code>info patchlevel</code></strong> 8.4.7 [root root]% -<span class="action"><span class="action">tclsh +<span class="action">tclsh info exists tcl_platform(threaded) info patchlevel -</span></span> +</span> </pre><p>If the first command returns anything other than <code class="computeroutput">1</code>, then Tcl is not threaded. If Tcl is threaded and the version is 8.4 or higher, then installing Tcl from source is optional.</p><p> <a name="tcl-download" id="tcl-download"></a><strong>Retrieve -Tcl 8.4 (or higher). </strong>Download and install Tcl +Tcl 8.4 (or higher). </strong> Download and install Tcl 8.4 from source</p><p>Note for Debian users: you can apt-get install tcl8.4-dev if you have the right version (stable users will need to add tcl8.4 to their sources.list file as described on the <a class="link" href="postgres" title="Install PostgreSQL">Install Postgres</a> page). You'll have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you try to find the Tcl libraries, however.</p><p>If you have not installed Tcl already, download the latest Tcl version from Sourceforge</p><p> -<span class="bold"><strong>Debian:</strong></span><code class="computeroutput"><span class="action"><span class="action">apt-get -install tcl8.4 tcl8.4-dev</span></span></code> and proceed to the -next step. In that step, replace <code class="computeroutput">--with-tcl=/usr/local/lib/</code> with +<span class="bold"><strong>Debian:</strong></span><code class="computeroutput"><span class="action">apt-get install tcl8.4 +tcl8.4-dev</span></code> and proceed to the next step. In that +step, replace <code class="computeroutput">--with-tcl=/usr/local/lib/</code> with <code class="computeroutput">--with-tcl=/usr/lib/tcl8.4</code>.</p><p>Remember that you have to be root if you want to follow these instructions. On Mac OS X type <strong class="userinput"><code>sudo su -</code></strong> to become root.</p><p>Alternatively use <strong class="userinput"><code>curl -L @@ -54,16 +52,16 @@ [root unix]# <strong class="userinput"><code>./configure --enable-threads</code></strong> [root unix]# <strong class="userinput"><code>make install</code></strong> [root root]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz tar xfz tcl8.4.9-src.tar.gz cd tcl8.4.9/unix ./configure --enable-threads -make install</span></span> +make install</span> </pre> </li><li class="listitem"> <a name="aolserver4-download" id="aolserver4-download"></a><p> -<strong>Retrieve AOLserver. </strong>Download the +<strong>Retrieve AOLserver. </strong> Download the AOLserver from CVS.</p><pre class="screen"> [root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>mkdir aolserver40r10</code></strong> @@ -78,7 +76,7 @@ [root aolserver]# <strong class="userinput"><code>tar xvfz tDOM-0.7.8.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>cvs -z3 -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</code></strong> [root root]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src mkdir aolserver40r10 cd aolserver40r10 cvs -z3 -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/aolserver co -r aolserver_v40_r10 AOLserver @@ -88,20 +86,20 @@ cvs -z3 -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle wget http://www.tdom.org/files/tDOM-0.8.0.tar.gz tar xvfz tDOM-0.8.0.tar.gz -cvs -z3 -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</span></span> +cvs -z3 -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</span> </pre> </li><li class="listitem"> <a name="aolserver4-install" id="aolserver4-install"></a><p> <strong>Configure, compile and install -AOLserver. </strong>Many people need to run more than +AOLserver. </strong> Many people need to run more than one version of AOLserver in parallel. This section accommodates future upgrades by installing AOLserver 4 in <code class="computeroutput">/usr/local/aolserver40r9</code>.</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver40r10/aolserver</code></strong> [root aolserver]# <strong class="userinput"><code>./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/</code></strong> -[root aolserver]# <strong class="userinput"><code>make install</code></strong><span class="action"><span class="action">cd /usr/local/src/aolserver40r10/aolserver +[root aolserver]# <strong class="userinput"><code>make install</code></strong><span class="action">cd /usr/local/src/aolserver40r10/aolserver ./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/ make install -</span></span> +</span> </pre><p>If you are using gcc 4 or later, see <a class="ulink" href="http://openacs.org/forums/message-view?message_id=309814" target="_top">http://openacs.org/forums/message-view?message_id=309814</a> </p><p>If this is the only version of AOLserver in use, or is the default version, create a symlink. If not, then be sure to use @@ -115,15 +113,12 @@ <a name="aolserver4-modules-install" id="aolserver4-modules-install"></a><p><strong>Configure, compile and install the modules. </strong></p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> -<p> -<a name="aolserver4-nscache-install" id="aolserver4-nscache-install"></a>Install nscache</p><pre class="screen"> +<p>Install nscache</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver40r10/nscache</code></strong> [root nscache]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong> </pre> </li><li class="listitem"> -<p> -<a name="aolserver4-nsoracle-install" id="aolserver4-nsoracle-install"></a>Install nsoracle (if you want to -use Oracle)</p><pre class="screen"> +<p>Install nsoracle (if you want to use Oracle)</p><pre class="screen"> [root nscache]# <strong class="userinput"><code>cd ../nsoracle</code></strong> [root nsoracle]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong> </pre><p>OpenACS looks for the Oracle driver at @@ -132,9 +127,7 @@ (<strong class="userinput"><code>ln -s nsoracle.so ora8.so</code></strong>) to fix it.</p> </li><li class="listitem"> -<p> -<a name="aolserver4-nspostgres-install" id="aolserver4-nspostgres-install"></a>Install nspostgres (if you want -to use Postgres)</p><pre class="screen"> +<p>Install nspostgres (if you want to use Postgres)</p><pre class="screen"> [root nscache]# <strong class="userinput"><code>cd ../nspostgres</code></strong> [root nspostgres]# <strong class="userinput"><code>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib:/usr/local/aolserver/lib</code></strong> [root nspostgres]# <strong class="userinput"><code>make install POSTGRES=LSB ACS=1 INST=/usr/local/aolserver AOLSERVER=/usr/local/aolserver</code></strong> @@ -155,8 +148,7 @@ MODLIBS = -L$(PGLIB) -lpq <span class="bold"><strong>-lnsdb</strong></span> </pre> </li><li class="listitem"> -<p> -<a name="aolserver4-nssha1-install" id="aolserver4-nssha1-install"></a>Install nssha1</p><pre class="screen"> +<p>Install nssha1</p><pre class="screen"> [root nspostgres]# <strong class="userinput"><code>cd ../nssha1</code></strong> </pre><p>Now install nssha1:</p><pre class="screen"> [root nssha1]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong> @@ -166,8 +158,7 @@ <span class="bold"><strong>//</strong></span> typedef unsigned char u_int8_t; </pre> </li><li class="listitem"> -<p> -<a name="aolserver4-tdom-install" id="aolserver4-tdom-install"></a>Install tDOM</p><pre class="screen"> +<p>Install tDOM</p><pre class="screen"> [root nssha1]# <strong class="userinput"><code>cd ../tDOM-0.8.0/unix</code></strong> </pre><p>Edit the <code class="computeroutput">CONFIG</code> file. Uncomment the instructions meant for AOLserver 4, but edit it to @@ -180,8 +171,7 @@ [root unix]# <strong class="userinput"><code>make install</code></strong> </pre> </li><li class="listitem"> -<p> -<a name="aolserver4-tcllib-install" id="aolserver4-tcllib-install"></a>Install TCLLIB</p><pre class="screen"> +<p>Install TCLLIB</p><pre class="screen"> [root nssha1]# <strong class="userinput"><code>cd ../tcllib</code></strong> </pre><p>Configure and compile TCLLIB</p><pre class="screen"> [root unix]# <strong class="userinput"><code>./configure -prefix=/usr/local/aolserver40r10</code></strong> @@ -192,7 +182,7 @@ </li><li class="listitem"> <a name="aolserver4-db-wrapper" id="aolserver4-db-wrapper"></a><p> <strong>Add a database-specific wrapper -script. </strong>This script sets database environment +script. </strong> This script sets database environment variables before starting AOLserver; this allows the AOLserver instance to communicate with the database. There is one script for Oracle and one for PostgreSQL. They do not conflict. If you plan to @@ -208,34 +198,35 @@ [root bin]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</code></strong> [root bin]# <strong class="userinput"><code>chmod 750 nsd-oracle</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle -chmod 750 nsd-oracle</span></span> +chmod 750 nsd-oracle</span> </pre> </li><li class="listitem"> <p>PostgreSQL</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> [root bin]# <strong class="userinput"><code>cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</code></strong> [root bin]# <strong class="userinput"><code>chmod 755 nsd-postgres</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres -chmod 755 nsd-postgres</span></span> +chmod 755 nsd-postgres</span> </pre> </li> </ul></div><p>You may need to edit these scripts if you are not using /usr/local/aolserver as the directory of Aolserver4.</p> </li><li class="listitem"><p> -<strong>Change startup script -(optional). </strong>If you want to run AOLserver on a -port below 1024 (normally, for a webserver you will use 80), you -will have to change the <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/daemontools/run</code> +<strong>Change startup script (optional). </strong> +If you want to run AOLserver on a port below 1024 (normally, for a +webserver you will use 80), you will have to change the +<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/etc/daemontools/run</code> script according to the documentation found there (namely: Add the --b <span class="replaceable"><span class="replaceable">yourip:yourport</span></span> switch)</p></li><li class="listitem"><p> +-b <em class="replaceable"><code>yourip:yourport</code></em> +switch)</p></li><li class="listitem"><p> <a class="link" href="aolserver">Test AOLserver</a>.</p></li> -</ol></div><div class="cvstag">($‌Id: aolserver4.xml,v 1.31.2.3 2017/04/22 -17:18:48 gustafn Exp $)</div> +</ol></div><p><span class="cvstag">($‌Id: aolserver4.xml,v 1.32 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="postgres" leftLabel="Prev" leftTitle="Install PostgreSQL" Index: openacs-4/packages/acs-core-docs/www/aolserver4.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/aolserver4.html,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/aolserver4.html 7 Aug 2017 23:47:49 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/aolserver4.html 8 Nov 2017 09:42:10 -0000 1.29 @@ -1,43 +1,70 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install AOLserver 4</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="postgres.html" title="Install PostgreSQL"><link rel="next" href="openacs.html" title="Install OpenACS 5.9.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aolserver4"></a>Install AOLserver 4</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:sussdorff@sussdorff.de" target="_top">Malte Sussdorff</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Check suitability of previously installed TCL. </b>Start Tcl (type <strong class="userinput"><code>tclsh</code></strong> or find it using <strong class="userinput"><code>which tclsh</code></strong>). - </p><pre class="screen">[root root]% <strong class="userinput"><code>info exists tcl_platform(threaded)</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install AOLserver 4</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="postgres.html" title="Install PostgreSQL"><link rel="next" href="openacs.html" title="Install OpenACS 5.9.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="aolserver4"></a>Install AOLserver 4</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:sussdorff@sussdorff.de" target="_top">Malte Sussdorff</a></p> + </authorblurb></span> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Check suitability of previously installed TCL. </b> + Start Tcl (type <strong class="userinput"><code>tclsh</code></strong> or find it using <strong class="userinput"><code>which tclsh</code></strong>). + + </p> + <pre class="screen">[root root]% <strong class="userinput"><code>info exists tcl_platform(threaded)</code></strong> 1 [root root]% <strong class="userinput"><code>info patchlevel</code></strong> 8.4.7 [root root]% -<span class="action"><span class="action">tclsh +<span class="action">tclsh info exists tcl_platform(threaded) info patchlevel -</span></span></pre><p>If the first command returns anything other than <code class="computeroutput">1</code>, +</span></pre> + <p>If the first command returns anything other than <code class="computeroutput">1</code>, then Tcl is not threaded. If Tcl is threaded and the version is 8.4 or higher, then installing Tcl from source is optional. - </p><p><a name="tcl-download"></a><b>Retrieve Tcl 8.4 (or higher). </b>Download and install Tcl 8.4 from source</p><p>Note for Debian users: you can apt-get install + </p> + <p><a name="tcl-download"></a> + <b>Retrieve Tcl 8.4 (or higher). </b> + Download and install Tcl 8.4 from source + </p> + <p>Note for Debian users: you can apt-get install tcl8.4-dev if you have the right version (stable users will need to add tcl8.4 to their sources.list file as described on the <a class="link" href="postgres.html" title="Install PostgreSQL">Install Postgres</a> page). You'll have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you - try to find the Tcl libraries, however.</p><p>If you have not installed Tcl already, download the latest Tcl version from Sourceforge</p><p><span class="bold"><strong>Debian:</strong></span> - <code class="computeroutput"><span class="action"><span class="action">apt-get install - tcl8.4 tcl8.4-dev</span></span></code> and proceed to + try to find the Tcl libraries, however.</p> + + <p>If you have not installed Tcl already, download the latest Tcl version from Sourceforge</p> + <p><span class="bold"><strong>Debian:</strong></span> + <code class="computeroutput"><span class="action">apt-get install + tcl8.4 tcl8.4-dev</span></code> and proceed to the next step. In that step, replace <code class="computeroutput">--with-tcl=/usr/local/lib/</code> with - <code class="computeroutput">--with-tcl=/usr/lib/tcl8.4</code>.</p><p>Remember that you have to be root if you want to follow these instructions. On Mac OS X type <strong class="userinput"><code>sudo su -</code></strong> to become root.</p><p>Alternatively use <strong class="userinput"><code>curl -L -O</code></strong> instead of <strong class="userinput"><code>wget</code></strong> (especially on Mac OS X).</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> + <code class="computeroutput">--with-tcl=/usr/lib/tcl8.4</code>.</p> + <p>Remember that you have to be root if you want to follow these instructions. On Mac OS X type <strong class="userinput"><code>sudo su -</code></strong> to become root.</p> + <p>Alternatively use <strong class="userinput"><code>curl -L -O</code></strong> instead of <strong class="userinput"><code>wget</code></strong> (especially on Mac OS X).</p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz</code></strong> [root src]# <strong class="userinput"><code>tar xfz tcl8.4.9-src.tar.gz</code></strong> [root src]# <strong class="userinput"><code>cd tcl8.4.9/unix</code></strong> [root unix]# <strong class="userinput"><code>./configure --enable-threads</code></strong> [root unix]# <strong class="userinput"><code>make install</code></strong> [root root]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz tar xfz tcl8.4.9-src.tar.gz cd tcl8.4.9/unix ./configure --enable-threads -make install</span></span> - </pre></li><li class="listitem"><a name="aolserver4-download"></a><p><b>Retrieve AOLserver. </b>Download the AOLserver from CVS.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> +make install</span> + </pre> + </li><li class="listitem"><a name="aolserver4-download"></a> + <p> + <b>Retrieve AOLserver. </b> + Download the AOLserver from CVS. + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>mkdir aolserver40r10</code></strong> [root src]# <strong class="userinput"><code>cd aolserver40r10</code></strong> [root aolserver]# <strong class="userinput"><code>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login</code></strong> @@ -50,7 +77,7 @@ [root aolserver]# <strong class="userinput"><code>tar xvfz tDOM-0.7.8.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</code></strong> [root root]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src mkdir aolserver40r10 cd aolserver40r10 cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r aolserver_v40_r10 AOLserver @@ -60,32 +87,91 @@ cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle wget http://www.tdom.org/files/tDOM-0.8.0.tar.gz tar xvfz tDOM-0.8.0.tar.gz -cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</span></span></pre></li><li class="listitem"><a name="aolserver4-install"></a><p><b>Configure, compile and install AOLserver. </b>Many people need to run more than one version of AOLserver in parallel. This section accommodates future upgrades by installing AOLserver 4 in <code class="computeroutput">/usr/local/aolserver40r9</code>.</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver40r10/aolserver</code></strong> +cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</span></pre> + </li><li class="listitem"><a name="aolserver4-install"></a> + <p> + <b>Configure, compile and install AOLserver. </b> + Many people need to run more than one version of AOLserver in parallel. This section accommodates future upgrades by installing AOLserver 4 in <code class="computeroutput">/usr/local/aolserver40r9</code>. + </p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver40r10/aolserver</code></strong> [root aolserver]# <strong class="userinput"><code>./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/</code></strong> [root aolserver]# <strong class="userinput"><code>make install</code></strong> -<span class="action"><span class="action">cd /usr/local/src/aolserver40r10/aolserver +<span class="action">cd /usr/local/src/aolserver40r10/aolserver ./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/ make install -</span></span></pre><p>If you are using gcc 4 or later, see <a class="ulink" href="http://openacs.org/forums/message-view?message_id=309814" target="_top">http://openacs.org/forums/message-view?message_id=309814</a></p><p>If this is the only version of AOLserver in use, or is the default version, create a symlink. If not, then be sure to use <code class="computeroutput">/usr/local/aolserver40r10</code> instead of <code class="computeroutput">/usr/local/aolserver</code> in the steps below and check both scripts and makefiles to ensure they use the correct path.</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>ln -s /usr/local/aolserver40r10 /usr/local/aolserver</code></strong></pre></li><li class="listitem"><a name="aolserver4-modules-install"></a><p><b>Configure, compile and install the modules. </b> - </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p><a name="aolserver4-nscache-install"></a>Install nscache</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver40r10/nscache</code></strong> -[root nscache]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong></pre></li><li class="listitem"><p><a name="aolserver4-nsoracle-install"></a>Install nsoracle (if you want to use Oracle)</p><pre class="screen">[root nscache]# <strong class="userinput"><code>cd ../nsoracle</code></strong> -[root nsoracle]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong></pre><p>OpenACS looks for the Oracle driver at +</span></pre> + <p>If you are using gcc 4 or later, see <a class="ulink" href="http://openacs.org/forums/message-view?message_id=309814" target="_top">http://openacs.org/forums/message-view?message_id=309814</a></p> + <p>If this is the only version of AOLserver in use, or is the default version, create a symlink. If not, then be sure to use <code class="computeroutput">/usr/local/aolserver40r10</code> instead of <code class="computeroutput">/usr/local/aolserver</code> in the steps below and check both scripts and makefiles to ensure they use the correct path.</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>ln -s /usr/local/aolserver40r10 /usr/local/aolserver</code></strong></pre> + </li><li class="listitem"><a name="aolserver4-modules-install"></a> + <p> + <b>Configure, compile and install the modules. </b> + + </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Install nscache</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver40r10/nscache</code></strong> +[root nscache]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong></pre> + </li><li class="listitem"> + <p>Install nsoracle (if you want to use Oracle)</p> + <pre class="screen">[root nscache]# <strong class="userinput"><code>cd ../nsoracle</code></strong> +[root nsoracle]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong></pre> + + <p>OpenACS looks for the Oracle driver at /usr/local/aolserver/bin/ora8.so, but some versions of nsoracle may create nsoracle.so instead. In that case, you - can symlink (<strong class="userinput"><code>ln -s nsoracle.so ora8.so</code></strong>) to fix it. </p></li><li class="listitem"><p><a name="aolserver4-nspostgres-install"></a>Install nspostgres (if you want to use Postgres)</p><pre class="screen">[root nscache]# <strong class="userinput"><code>cd ../nspostgres</code></strong> + can symlink (<strong class="userinput"><code>ln -s nsoracle.so ora8.so</code></strong>) to fix it. </p> + </li><li class="listitem"> + <p>Install nspostgres (if you want to use Postgres)</p> + <pre class="screen">[root nscache]# <strong class="userinput"><code>cd ../nspostgres</code></strong> [root nspostgres]# <strong class="userinput"><code>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib:/usr/local/aolserver/lib</code></strong> [root nspostgres]# <strong class="userinput"><code>make install POSTGRES=LSB ACS=1 INST=/usr/local/aolserver AOLSERVER=/usr/local/aolserver</code></strong> - </pre><p>If you get errors like:</p><pre class="programlisting">nspostgres.c: In function `Ns_PgTableList': -nspostgres.c:679: warning: passing arg 3 of `Tcl_DStringAppend' as signed due to prototype</pre><p>then PostGreSQL is probably not in the standard location. The location of PostGreSQL is very dependent on which method was used to install it. To correct the problem, replace <code class="computeroutput">LSB</code> with the path to the path to your PostGreSQL installation. Often this is <code class="computeroutput">/usr/local/pgsql</code>.</p><p>You can use the + </pre> + <p>If you get errors like:</p> + <pre class="programlisting">nspostgres.c: In function `Ns_PgTableList': +nspostgres.c:679: warning: passing arg 3 of `Tcl_DStringAppend' as signed due to prototype</pre> + <p>then PostGreSQL is probably not in the standard location. The location of PostGreSQL is very dependent on which method was used to install it. To correct the problem, replace <code class="computeroutput">LSB</code> with the path to the path to your PostGreSQL installation. Often this is <code class="computeroutput">/usr/local/pgsql</code>.</p> + + <p>You can use the <code class="computeroutput">ldd</code> command to verify that all libraries are linked in: <strong class="userinput"><code>ldd /usr/local/src/aolserver40r10/nspostgres/nspostgres.so</code></strong> - </p><p>If you run into problems with libpq.a do the following (and repeat the step above)</p><pre class="screen">[root nspostgres]# <strong class="userinput"><code>ranlib /usr/local/pgsql/lib/libpq.a</code></strong></pre><p>If you run into problems with the linker, edit the Makefile. Add <code class="computeroutput">-lnsdb</code> to the <code class="computeroutput">MODLIBS</code> var.</p><pre class="programlisting">MODLIBS = -L$(PGLIB) -lpq <span class="bold"><strong>-lnsdb</strong></span></pre></li><li class="listitem"><p><a name="aolserver4-nssha1-install"></a>Install nssha1</p><pre class="screen">[root nspostgres]# <strong class="userinput"><code>cd ../nssha1</code></strong></pre><p>Now install nssha1:</p><pre class="screen">[root nssha1]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong></pre><p>If the make fails you will have to edit nssha1.c. Comment out the following 2 lines (lines 139-140): </p><pre class="programlisting"><span class="bold"><strong>//</strong></span> typedef unsigned int u_int32_t; -<span class="bold"><strong>//</strong></span> typedef unsigned char u_int8_t;</pre></li><li class="listitem"><p><a name="aolserver4-tdom-install"></a>Install tDOM</p><pre class="screen">[root nssha1]# <strong class="userinput"><code>cd ../tDOM-0.8.0/unix</code></strong></pre><p>Edit the <code class="computeroutput">CONFIG</code> file. Uncomment the instructions meant for AOLserver 4, but edit it to look like this:</p><pre class="screen">../configure --enable-threads --disable-tdomalloc - --prefix=/usr/local/aolserver --with-tcl=/usr/local/lib</pre><p>Note that the location of the Tcl library may vary on different platforms (e.g. for Debian 3.0: --with-tcl=/usr/lib/tcl8.4)</p><p>Now you can compile and configure tDOM</p><pre class="screen">[root unix]# <strong class="userinput"><code>sh CONFIG</code></strong> -[root unix]# <strong class="userinput"><code>make install</code></strong></pre></li><li class="listitem"><p><a name="aolserver4-tcllib-install"></a>Install TCLLIB</p><pre class="screen">[root nssha1]# <strong class="userinput"><code>cd ../tcllib</code></strong></pre><p>Configure and compile TCLLIB</p><pre class="screen">[root unix]# <strong class="userinput"><code>./configure -prefix=/usr/local/aolserver40r10</code></strong> -[root unix]# <strong class="userinput"><code>make install</code></strong></pre></li></ol></div><p> - </p></li><li class="listitem"><a name="aolserver4-db-wrapper"></a><p><b>Add a database-specific wrapper script. </b>This script + </p> + + <p>If you run into problems with libpq.a do the following (and repeat the step above)</p> + <pre class="screen">[root nspostgres]# <strong class="userinput"><code>ranlib /usr/local/pgsql/lib/libpq.a</code></strong></pre> + <p>If you run into problems with the linker, edit the Makefile. Add <code class="computeroutput">-lnsdb</code> to the <code class="computeroutput">MODLIBS</code> var.</p> + <pre class="programlisting">MODLIBS = -L$(PGLIB) -lpq <span class="bold"><strong>-lnsdb</strong></span></pre> + </li><li class="listitem"> + <p>Install nssha1</p> + <pre class="screen">[root nspostgres]# <strong class="userinput"><code>cd ../nssha1</code></strong></pre> + <p>Now install nssha1:</p> + <pre class="screen">[root nssha1]# <strong class="userinput"><code>make install AOLSERVER=/usr/local/aolserver</code></strong></pre> + <p>If the make fails you will have to edit nssha1.c. Comment out the following 2 lines (lines 139-140): </p> + <pre class="programlisting"><span class="bold"><strong>//</strong></span> typedef unsigned int u_int32_t; +<span class="bold"><strong>//</strong></span> typedef unsigned char u_int8_t;</pre> + </li><li class="listitem"> + <p>Install tDOM</p> + <pre class="screen">[root nssha1]# <strong class="userinput"><code>cd ../tDOM-0.8.0/unix</code></strong></pre> + <p>Edit the <code class="computeroutput">CONFIG</code> file. Uncomment the instructions meant for AOLserver 4, but edit it to look like this:</p> + <pre class="screen">../configure --enable-threads --disable-tdomalloc + --prefix=/usr/local/aolserver --with-tcl=/usr/local/lib</pre> + <p>Note that the location of the Tcl library may vary on different platforms (e.g. for Debian 3.0: --with-tcl=/usr/lib/tcl8.4)</p> + <p>Now you can compile and configure tDOM</p> + <pre class="screen">[root unix]# <strong class="userinput"><code>sh CONFIG</code></strong> +[root unix]# <strong class="userinput"><code>make install</code></strong></pre> + </li><li class="listitem"> + <p>Install TCLLIB</p> + <pre class="screen">[root nssha1]# <strong class="userinput"><code>cd ../tcllib</code></strong></pre> + <p>Configure and compile TCLLIB</p> + <pre class="screen">[root unix]# <strong class="userinput"><code>./configure -prefix=/usr/local/aolserver40r10</code></strong> +[root unix]# <strong class="userinput"><code>make install</code></strong></pre> + </li></ol></div><p> + + </p> + </li><li class="listitem"><a name="aolserver4-db-wrapper"></a> + <p> + <b>Add a database-specific wrapper script. </b> +This script sets database environment variables before starting AOLserver; this allows the AOLserver instance to communicate with the database. There is one script for @@ -99,17 +185,35 @@ OpenACS code, but don't forget to come back. (Note to maintainers: this should be moved to the next page and integrated into the text there) - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Oracle</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Oracle</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> [root bin]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</code></strong> [root bin]# <strong class="userinput"><code>chmod 750 nsd-oracle</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle -chmod 750 nsd-oracle</span></span></pre></li><li class="listitem"><p>PostgreSQL</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> +chmod 750 nsd-oracle</span></pre> + </li><li class="listitem"> + <p>PostgreSQL</p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/aolserver/bin</code></strong> [root bin]# <strong class="userinput"><code>cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</code></strong> [root bin]# <strong class="userinput"><code>chmod 755 nsd-postgres</code></strong> [root bin]# -<span class="action"><span class="action">cd /usr/local/aolserver/bin +<span class="action">cd /usr/local/aolserver/bin cp /var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres -chmod 755 nsd-postgres</span></span></pre></li></ul></div><p>You may need to edit these scripts if you are not using - /usr/local/aolserver as the directory of Aolserver4.</p></li><li class="listitem"><p><b>Change startup script (optional). </b>If you want to run AOLserver on a port below 1024 (normally, for a webserver you will use 80), you will have to change the <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/etc/daemontools/run</code> script according to the documentation found there (namely: Add the -b <span class="replaceable"><span class="replaceable">yourip:yourport</span></span> switch)</p></li><li class="listitem"><p><a class="link" href="aolserver.html#install-aolserver-permissions">Test AOLserver</a>.</p></li></ol></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Install PostgreSQL </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install OpenACS 5.9.0</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +chmod 755 nsd-postgres</span></pre> + </li></ul></div> + <p>You may need to edit these scripts if you are not using + /usr/local/aolserver as the directory of Aolserver4.</p> + </li><li class="listitem"> + <p> + <b>Change startup script (optional). </b> + If you want to run AOLserver on a port below 1024 (normally, for a webserver you will use 80), you will have to change the <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/etc/daemontools/run</code> script according to the documentation found there (namely: Add the -b <em class="replaceable"><code>yourip:yourport</code></em> switch)</p> + </li><li class="listitem"> + <p><a class="link" href="aolserver.html#install-aolserver-permissions">Test AOLserver</a>.</p> + </li></ol></div> + <p><span class="cvstag">($Id$)</span></p> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Install PostgreSQL </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install OpenACS 5.9.0</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/apm-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/apm-design.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/apm-design.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="db-api-detailed" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="apm-design" id="apm-design"></a>Package Manager Design</h2></div></div></div><div class="authorblurb"> -<p>By Bryan Quinn</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="apm-design" id="apm-design"></a>Package Manager Design</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Bryan Quinn</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="apm-design-essentials" id="apm-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p><a class="ulink" href="/acs-admin/apm" target="_top">OpenACS Index: openacs-4/packages/acs-core-docs/www/apm-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-design.html,v diff -u -r1.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/apm-design.html 7 Aug 2017 23:47:49 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/apm-design.html 8 Nov 2017 09:42:10 -0000 1.42 @@ -1,12 +1,35 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Package Manager Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="apm-requirements.html" title="Package Manager Requirements"><link rel="next" href="db-api-detailed.html" title="Database Access API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apm-design"></a>Package Manager Design</h2></div></div></div><div class="authorblurb"><p>By Bryan Quinn</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="/acs-admin/apm" target="_top">OpenACS Administrator directory</a></p></li><li class="listitem"><p><a class="xref" href="apm-requirements.html" title="Package Manager Requirements">Package Manager Requirements</a></p></li><li class="listitem"><p><a class="xref" href="packages.html" title="OpenACS Packages">Packages</a></p></li><li class="listitem"><p><a class="ulink" href="../images/apm.pdf" target="_top">ER diagram</a></p></li><li class="listitem"><p>Tcl API </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages%2facs%2dtcl%2ftcl%2fapm%2dprocs%2etcl" target="_top"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Package Manager Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="apm-requirements.html" title="Package Manager Requirements"><link rel="next" href="db-api-detailed.html" title="Database Access API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apm-design"></a>Package Manager Design</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Bryan Quinn</p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-essentials"></a>Essentials</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="/acs-admin/apm" target="_top">OpenACS Administrator directory</a></p></li><li class="listitem"><p><a class="xref" href="apm-requirements.html" title="Package Manager Requirements">Package Manager Requirements</a></p></li><li class="listitem"><p><a class="xref" href="packages.html" title="OpenACS Packages">Packages</a></p></li><li class="listitem"><p><a class="ulink" href="../images/apm.pdf" target="_top">ER diagram</a></p></li><li class="listitem"><p>Tcl API </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages%2facs%2dtcl%2ftcl%2fapm%2dprocs%2etcl" target="_top"> apm-procs.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages%2facs%2dtcl%2ftcl%2fapm%2dinstall%2dprocs%2etcl" target="_top"> apm-install-procs.tcl</a> (Supports installation of packages)</p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages%2facs%2dbootstrap%2dinstaller%2ftcl%2f30%2dapm%2dload%2dprocs%2etcl" target="_top"> 30-apm-load-procs.tcl</a> (Bootstraps APM for server startup)</p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages%2facs%2dadmin%2ftcl%2fapm%2dadmin%2dprocs%2etcl" target="_top"> -apm-admin-procs.tcl</a> (Supports APM UI)</p></li></ul></div></li><li class="listitem"><p>PL/SQL file </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=apm-create.sql&package_key=acs-kernel" target="_top">apm-create.sql</a></p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-intro"></a>Introduction</h3></div></div></div><p> +apm-admin-procs.tcl</a> (Supports APM UI)</p></li></ul></div> +</li><li class="listitem"><p>PL/SQL file </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=apm-create.sql&package_key=acs-kernel" target="_top">apm-create.sql</a></p></li></ul></div> +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-intro"></a>Introduction</h3></div></div></div> + + +<p> In general terms, a <span class="strong"><strong>package</strong></span> is a unit of software that serves a single well-defined purpose. That purpose may be to provide a service directly to one or more classes of end-user, (e.g., discussion forums @@ -15,7 +38,9 @@ an application programming interface (API) for storing and querying access control rules, or an API for scheduling email alerts). Thus, packages fall into one of two categories: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>OpenACS Applications:</strong></span> a "program or group of programs +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>OpenACS Applications:</strong></span> a "program or group of programs designed for end users" (the <a class="ulink" href="http://www.pcwebopaedia.com/TERM/a/application.html" target="_top">Webopedia definition</a>); also known as <span class="emphasis"><em>modules</em></span>, for historical reasons. Examples of applications include <a class="ulink" href="/doc/forums" target="_top">Forums</a> and <a class="ulink" href="/doc/news" target="_top">News</a>. @@ -25,11 +50,15 @@ Examples of services include the <a class="ulink" href="/doc/acs-content-repository" target="_top">OpenACS Content Repository</a>, the <a class="ulink" href="/doc/acs-templating" target="_top">OpenACS Templating System</a>, and the <a class="link" href="kernel-doc.html" title="Chapter 15. Kernel Documentation">OpenACS Kernel</a>, which includes -APM.</p></li></ul></div><p>An installation of the OpenACS includes the OpenACS Kernel, some services that +APM.</p></li></ul></div> + +<p>An installation of the OpenACS includes the OpenACS Kernel, some services that extend the kernel's functionality, and some applications intended for end-users. Packages function as individual pieces of <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a>. A subsite can contain multiple application and service instances that provide the end-user with capabilities -and content customized to the particular subsite.</p><p>This architecture supports the growth of collaborative commerce. For +and content customized to the particular subsite.</p> + +<p>This architecture supports the growth of collaborative commerce. For example, Jane User starts a forum focusing on the merits of View Cameras by creating an instance of the Forum application for her personal subsite on an OpenACS Installation. Jack User discovers Jane's forum and includes a link to @@ -41,30 +70,52 @@ view cameras and a portal application that links to reliable camera models and resellers. Any subsite enabled package that is added to the OpenACS installation through APM is another potential package instance that can -become part of Jane's View Camera subsite.</p><p>The APM provides an architecture for packaging software, making instances +become part of Jane's View Camera subsite.</p> + +<p>The APM provides an architecture for packaging software, making instances of that software available to subsites, specifying configuration parameters -for each instance, and managing the creation and release of new packages.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-hist-considerations"></a>Historical Considerations</h3></div></div></div><p> +for each instance, and managing the creation and release of new packages.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-hist-considerations"></a>Historical Considerations</h3></div></div></div> + + +<p> Prior to ACS 3.3, all packages were lumped together into one monolithic distribution without explicit boundaries; the only way to ascertain what comprised a given package was to look at the top of the corresponding documentation page, where, by convention, the package developer would specify where to find: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>the data model</p></li><li class="listitem"><p>the Tcl procedures</p></li><li class="listitem"><p>the user-accessible pages</p></li><li class="listitem"><p>the administration pages</p></li></ul></div><p>Experience has shown us that this lack of explicit boundaries causes a -number of maintainability problems for pre-3.3 installations:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Package interfaces were not guaranteed to be stable in any formal way, so +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>the data model</p></li><li class="listitem"><p>the Tcl procedures</p></li><li class="listitem"><p>the user-accessible pages</p></li><li class="listitem"><p>the administration pages</p></li></ul></div> + +<p>Experience has shown us that this lack of explicit boundaries causes a +number of maintainability problems for pre-3.3 installations:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Package interfaces were not guaranteed to be stable in any formal way, so a change in the interface of one package would often break dependent packages (which we would only discover through manual regression testing). In this context, any of the following could constitute an interface change: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>renaming a file or directory that appears in a URL</p></li><li class="listitem"><p>changing what form variables are expected as input by a page</p></li><li class="listitem"><p>changing a procedural abstraction, e.g., a PL/SQL or Java stored +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>renaming a file or directory that appears in a URL</p></li><li class="listitem"><p>changing what form variables are expected as input by a page</p></li><li class="listitem"><p>changing a procedural abstraction, e.g., a PL/SQL or Java stored procedure or a Tcl procedure</p></li><li class="listitem"><p>changing a functional abstraction, e.g., a database view or a PL/SQL or -Java stored function</p></li><li class="listitem"><p>changing the data model</p></li></ul></div><p>This last point is especially important. In most cases, changing the data +Java stored function</p></li><li class="listitem"><p>changing the data model</p></li></ul></div> + +<p>This last point is especially important. In most cases, changing the data model should <span class="emphasis"><em>not</em></span> affect dependent packages. Rather, the package interface should provide a level of abstraction above the data model (as well as the rest of the package implementation). Then, users of the package can take advantage of implementation improvements that don't affect the interface (e.g., faster performance from intelligent denormalization of the data model), without having to worry that code outside the package will now -break.</p></li><li class="listitem"><p>A typical ACS-backed site only uses a few of the modules included in the +break.</p> + + +</li><li class="listitem"><p>A typical ACS-backed site only uses a few of the modules included in the distribution, yet there was no well-understood way to pick only what you needed when installing the ACS, or even to uninstall what you didn't need, post-installation. Unwanted code had to be removed manually. @@ -81,52 +132,133 @@ the ACS with their own packages. Along the same lines, ArsDigita programmers working on client projects had no standard way to keep custom development cleanly separated from ACS code. Consequently, upgrading an already installed -ACS was an error-prone and time-consuming process.</p></li></ol></div><p>Consistent use of the APM format and tools will go a long way toward +ACS was an error-prone and time-consuming process.</p></li></ol></div> + +<p>Consistent use of the APM format and tools will go a long way toward solving the maintainability problems listed above. Moreover, APM is the substrate that will enable us to establish a central package repository, where developers will be able publish their -packages for other OpenACS users to download and install.</p><p>For a simple illustration of the difference between ACS without APM +packages for other OpenACS users to download and install.</p> + +<p>For a simple illustration of the difference between ACS without APM (pre-3.3) and ACS with APM (3.3 and beyond), consider a hypothetical ACS installation that uses only two of the thirty-odd modules available circa ACS -3.2 (say, bboard and e-commerce):</p><div class="mediaobject" align="center"><img src="images/acs-without-apm-vs-with-apm.png" align="middle"></div><p>APM itself is part of a package, the <span class="strong"><strong>OpenACS Kernel</strong></span>, an OpenACS -service that is the only mandatory component of an OpenACS installation.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-competitors"></a>Competitive Analysis</h3></div></div></div><p>The OpenACS is a platform for web-based application software, and any software +3.2 (say, bboard and e-commerce):</p> + + + +<div class="mediaobject" align="center"><img src="images/acs-without-apm-vs-with-apm.png" align="middle"></div> + + + +<p>APM itself is part of a package, the <span class="strong"><strong>OpenACS Kernel</strong></span>, an OpenACS +service that is the only mandatory component of an OpenACS installation.</p> + + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-competitors"></a>Competitive Analysis</h3></div></div></div> + + + +<p>The OpenACS is a platform for web-based application software, and any software platform has the potential to develop problems like those described above. Fortunately, there are many precedents for systematic solutions, -including:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="http://www.debian.org/" target="_top">Debian GNU/Linux</a> and the <a class="ulink" href="https://www.debian.org/doc/manuals/maint-guide/" target="_top">Debian +including:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="http://www.debian.org/" target="_top">Debian GNU/Linux</a> and the <a class="ulink" href="https://www.debian.org/doc/manuals/maint-guide/" target="_top">Debian Packaging manual</a></p></li><li class="listitem"><p><a class="ulink" href="http://www.freebsd.org/" target="_top">FreeBSD</a> has <a class="ulink" href="http://www.freebsd.org/handbook/ports.html" target="_top">the Ports -collection</a></p></li><li class="listitem"><p><a class="ulink" href="http://www.redhat.com/" target="_top">Red Hat Linux</a> has <a class="ulink" href="https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/ch-rpm.html" target="_top">the Red Hat Package Manager (RPM)</a></p></li></ul></div><p>Borrowing from all of the above, OpenACS 3.3 introduces its own package -management system, the OpenACS Package Manager (APM), which consists of:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>a standard format for APM packages</strong></span> (also called -"OpenACS packages"), including: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>version numbering, independent of any other package and the OpenACS as a -whole</p></li><li class="listitem"><p>specification of the package interface</p></li><li class="listitem"><p>specification of dependencies on other packages (if any)</p></li><li class="listitem"><p>attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>web-based tools for package management:</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>obtaining packages from a remote distribution point</p></li><li class="listitem"><p>installing packages, if and only if: </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>all prerequisite packages are installed</p></li><li class="listitem"><p>no conflicts will be created by the installation</p></li></ol></div></li><li class="listitem"><p>configuring packages (obsoleting the monolithic OpenACS configuration -file)</p></li><li class="listitem"><p>upgrading packages, without clobbering local modifications</p></li><li class="listitem"><p>uninstalling unwanted packages</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>a registry of installed packages</strong></span>, database-backed and +collection</a></p></li><li class="listitem"><p><a class="ulink" href="http://www.redhat.com/" target="_top">Red Hat Linux</a> has <a class="ulink" href="https://access.redhat.com/documentation/en-US/Red_Hat_Enterprise_Linux/5/html/Deployment_Guide/ch-rpm.html" target="_top">the Red Hat Package Manager (RPM)</a></p></li></ul></div> + +<p>Borrowing from all of the above, OpenACS 3.3 introduces its own package +management system, the OpenACS Package Manager (APM), which consists of:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>a standard format for APM packages</strong></span> (also called +"OpenACS packages"), including: </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>version numbering, independent of any other package and the OpenACS as a +whole</p></li><li class="listitem"><p>specification of the package interface</p></li><li class="listitem"><p>specification of dependencies on other packages (if any)</p></li><li class="listitem"><p>attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div> + + +</li><li class="listitem"><p><span class="strong"><strong>web-based tools for package management:</strong></span> </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>obtaining packages from a remote distribution point</p></li><li class="listitem"><p>installing packages, if and only if: </p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>all prerequisite packages are installed</p></li><li class="listitem"><p>no conflicts will be created by the installation</p></li></ol></div> +</li><li class="listitem"><p>configuring packages (obsoleting the monolithic OpenACS configuration +file)</p></li><li class="listitem"><p>upgrading packages, without clobbering local modifications</p></li><li class="listitem"><p>uninstalling unwanted packages</p></li></ul></div> + + +</li><li class="listitem"><p><span class="strong"><strong>a registry of installed packages</strong></span>, database-backed and integrated with filesystem-based version control -</p></li><li class="listitem"><p><span class="strong"><strong>web-based tools for package development:</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>creating new packages locally</p></li><li class="listitem"><p>releasing new versions of locally-created packages</p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div><p> +</p></li><li class="listitem"><p><span class="strong"><strong>web-based tools for package development:</strong></span> </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>creating new packages locally</p></li><li class="listitem"><p>releasing new versions of locally-created packages</p></li></ul></div> +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div> + + +<p> The design chosen for APM was meant to satisfy the following constraints: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The process of authoring a package must be as simple as possible.</p></li><li class="listitem"><p>Strict conventions must be established that provide a set of canonical +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The process of authoring a package must be as simple as possible.</p></li><li class="listitem"><p>Strict conventions must be established that provide a set of canonical locations and names for files and patterns, for OpenACS application development.</p></li><li class="listitem"><p>The processes of installing, upgrading, and using packages must be straightforward and accessible through a web-based UI.</p></li><li class="listitem"><p>Package instances must be able to have subsite-specific content available -at an easily configurable URL.</p></li></ul></div><p>All of these requirements were met, but at the cost of development +at an easily configurable URL.</p></li></ul></div> + +<p>All of these requirements were met, but at the cost of development simplicity. As <a class="xref" href="packages.html" title="OpenACS Packages">Packages</a> demonstrates, a set of strict directory conventions are required in order for a package to use APM. This contrasts with the apparent simplicity available to developers of the OpenACS 3.3 system. However, while the system has become more complex for developers to build packages, this complexity is easily managed and is compensated for by additional -capabilities.</p><p>For example, to make a new application available to the system, a -developer must:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Create the necessary files to support the data model, Tcl API, and UI +capabilities.</p> + +<p>For example, to make a new application available to the system, a +developer must:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Create the necessary files to support the data model, Tcl API, and UI pages.</p></li><li class="listitem"><p>Put the files in the correct locations for APM to be aware of them.</p></li><li class="listitem"><p>Use APM to create a new package and enable it.</p></li><li class="listitem"><p>Use the Site Map facility to create an instance of the package, mount it -on an appropriate URL, and set parameters for that particular instance.</p></li></ol></div><p>While this is complex, especially to a new OpenACS developer, the +on an appropriate URL, and set parameters for that particular instance.</p></li></ol></div> + +<p>While this is complex, especially to a new OpenACS developer, the documentation walks the developer through each of these steps. Moreover, from following these steps, the package can be subsite specific, available to subsites across the system, and be available for distribution to other OpenACS -installations without doing a monolithic upgrade or reinstall.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-api"></a>API</h3></div></div></div><p>The APM is composed of systems for accomplishing a set of package-related +installations without doing a monolithic upgrade or reinstall.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-api"></a>API</h3></div></div></div> + + + +<p>The APM is composed of systems for accomplishing a set of package-related tasks. Each of these tasks comprise a feature area that has an API, data -model, and a UI:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authoring a Package</p></li><li class="listitem"><p>Maintaining Multiple Versions of a Package</p></li><li class="listitem"><p>Creating Instances of the Package</p></li><li class="listitem"><p>Specifying Configuration Parameters for each Instance</p></li></ul></div><p><span class="strong"><strong>Authoring a Package</strong></span></p><p>Full instructions on how to prepare an OpenACS package are available in <a class="xref" href="packages.html" title="OpenACS Packages">Packages</a>. The API here can be invoked manually by a package's data model +model, and a UI:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authoring a Package</p></li><li class="listitem"><p>Maintaining Multiple Versions of a Package</p></li><li class="listitem"><p>Creating Instances of the Package</p></li><li class="listitem"><p>Specifying Configuration Parameters for each Instance</p></li></ul></div> + + + +<p><span class="strong"><strong>Authoring a Package</strong></span></p> + +<p>Full instructions on how to prepare an OpenACS package are available in <a class="xref" href="packages.html" title="OpenACS Packages">Packages</a>. The API here can be invoked manually by a package's data model creation script, but need not to be used. This API is part of the <a class="ulink" href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM" target="_top">APM PL/SQL -package</a>.</p><pre class="programlisting"> +package</a>.</p> + + +<pre class="programlisting"> + -- Informs the APM that this application is available for use. procedure register_application ( package_key in apm_package_types.package_key%TYPE, @@ -141,37 +273,66 @@ default null ); -</pre><p>The procedure above registers an OpenACS application in the APM. It creates a +</pre> + + +<p>The procedure above registers an OpenACS application in the APM. It creates a new OpenACS object and stores information about the package, such as its name, in the APM data model. There is an analogous procedure for OpenACS services, called -<code class="computeroutput">apm.register_service</code>.</p><p>To remove an application from the system, there are the calls +<code class="computeroutput">apm.register_service</code>.</p> + +<p>To remove an application from the system, there are the calls <code class="computeroutput">apm.unregister_application</code> and -<code class="computeroutput">apm.unregister_service</code>.</p><pre class="programlisting"> +<code class="computeroutput">apm.unregister_service</code>.</p> + + +<pre class="programlisting"> + -- Remove the application from the system. procedure unregister_application ( package_key in apm_package_types.package_key%TYPE, -- Delete all objects associated with this application. cascade_p in char default 'f' ); -</pre><p>Use the <code class="computeroutput">cascade_p</code> only if you want to completely remove the -package from the OpenACS.</p><p>In order to determine if a particular package exists in the system, use +</pre> + + +<p>Use the <code class="computeroutput">cascade_p</code> only if you want to completely remove the +package from the OpenACS.</p> + +<p>In order to determine if a particular package exists in the system, use the <code class="computeroutput">register_p</code> predicate. It returns 1 if the specified -<code class="computeroutput">package_key</code> exists in the system, 0 otherwise.</p><pre class="programlisting"> +<code class="computeroutput">package_key</code> exists in the system, 0 otherwise.</p> + + +<pre class="programlisting"> + function register_p ( package_key in apm_package_types.package_key%TYPE ) return integer; -</pre><p><span class="strong"><strong>Maintaining Multiple Versions of a Package</strong></span></p><p>While the package authoring API provides a means for registering a +</pre> + + +<p><span class="strong"><strong>Maintaining Multiple Versions of a Package</strong></span></p> + +<p>While the package authoring API provides a means for registering a package, some information about a package is version dependent. For example, between versions, the owner of a package, its vendor, its URI, and its dependency information may change. The API for package versions allows this information to be specified. All of these APIs are part of the <a class="ulink" href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM%5fPACKAGE%5fVERSION" target="_top"> -<code class="computeroutput">apm_package_version</code> PL/SQL package</a>.</p><p>To create a new package version, use the -<code class="computeroutput">apm_package_version.new</code> constructor function.</p><pre class="programlisting"> +<code class="computeroutput">apm_package_version</code> PL/SQL package</a>.</p> +<p>To create a new package version, use the +<code class="computeroutput">apm_package_version.new</code> constructor function.</p> + + + +<pre class="programlisting"> + function new ( version_id in apm_package_versions.version_id%TYPE default null, @@ -191,27 +352,61 @@ default 'f' ) return apm_package_versions.version_id%TYPE; -</pre><p>In order to use this function, an existing <code class="computeroutput">package_key</code> must +</pre> + + +<p>In order to use this function, an existing <code class="computeroutput">package_key</code> must be specified. The <code class="computeroutput">version_name</code> parameter must follow a strict -convention:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A major version number</p></li><li class="listitem"><p>at least one minor version number. Although any number of minor version +convention:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A major version number</p></li><li class="listitem"><p>at least one minor version number. Although any number of minor version numbers may be included, three minor version numbers is sufficient and is the -convention of software developers.</p></li><li class="listitem"><p>One of the following: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The letter <code class="computeroutput">d</code>, indicating a development-only version</p></li><li class="listitem"><p>The letter <code class="computeroutput">a</code>, indicating an alpha release</p></li><li class="listitem"><p>The letter <code class="computeroutput">b</code>, indicating a beta release</p></li><li class="listitem"><p>No letter at all, indicating a final production release</p></li></ul></div></li></ol></div><p>In addition, the letters <code class="computeroutput">d</code>, <code class="computeroutput">a</code>, and +convention of software developers.</p></li><li class="listitem"><p>One of the following: </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The letter <code class="computeroutput">d</code>, indicating a development-only version</p></li><li class="listitem"><p>The letter <code class="computeroutput">a</code>, indicating an alpha release</p></li><li class="listitem"><p>The letter <code class="computeroutput">b</code>, indicating a beta release</p></li><li class="listitem"><p>No letter at all, indicating a final production release</p></li></ul></div> +</li></ol></div> + +<p>In addition, the letters <code class="computeroutput">d</code>, <code class="computeroutput">a</code>, and <code class="computeroutput">b</code> may be followed by another integer, indicating a version -within the release.</p><p>For those who like regular expressions:</p><pre class="programlisting"> +within the release.</p> +<p>For those who like regular expressions:</p> + + + +<pre class="programlisting"> + version_number := ^[0-9]+((\.[0-9]+)+((d|a|b|)[0-9]?)?)$ -</pre><p>So the following is a valid progression for version numbers:</p><div class="blockquote"><blockquote class="blockquote"><p><code class="computeroutput">0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1, -1.1</code></p></blockquote></div><p>To delete a given version of a package, use the -<code class="computeroutput">apm_package_version.delete</code> procedure:</p><pre class="programlisting"> +</pre> + +<p>So the following is a valid progression for version numbers:</p> + +<div class="blockquote"><blockquote class="blockquote"><p><code class="computeroutput">0.9d, 0.9d1, 0.9a1, 0.9b1, 0.9b2, 0.9, 1.0, 1.0.1, 1.1b1, +1.1</code></p></blockquote></div> + +<p>To delete a given version of a package, use the +<code class="computeroutput">apm_package_version.delete</code> procedure:</p> + + + +<pre class="programlisting"> + procedure delete ( package_id in apm_packages.package_id%TYPE ); -</pre><p>After creating a version, it is possible to edit the information -associated with it using <code class="computeroutput">apm_package_version.edit</code>.</p><pre class="programlisting"> +</pre> + +<p>After creating a version, it is possible to edit the information +associated with it using <code class="computeroutput">apm_package_version.edit</code>.</p> + + + +<pre class="programlisting"> + function edit ( new_version_id in apm_package_versions.version_id%TYPE default null, @@ -231,10 +426,17 @@ default 'f' ) return apm_package_versions.version_id%TYPE; -</pre><p>Versions can be enabled or disabled. Enabling a version instructs APM to +</pre> + + +<p>Versions can be enabled or disabled. Enabling a version instructs APM to source the package's libraries on startup and to make the package -available to the OpenACS.</p><pre class="programlisting"> +available to the OpenACS.</p> + + +<pre class="programlisting"> + procedure enable ( version_id in apm_package_versions.version_id%TYPE ); @@ -243,9 +445,15 @@ version_id in apm_package_versions.version_id%TYPE ); -</pre><p>Files associated with a version can be added and removed. The path is +</pre> + + +<p>Files associated with a version can be added and removed. The path is relative to the <span class="strong"><strong>package-root</strong></span> which is -<code class="computeroutput">acs-server-root/packages/package-key</code>.</p><pre class="programlisting"> +<code class="computeroutput">acs-server-root/packages/package-key</code>.</p> + + +<pre class="programlisting"> -- Add a file to the indicated version. function add_file( file_id in apm_package_files.file_id%TYPE @@ -260,11 +468,17 @@ version_id in apm_package_versions.version_id%TYPE, path in apm_package_files.path%TYPE ); -</pre><p>Package versions need to indicate that they provide interfaces for other +</pre> + +<p>Package versions need to indicate that they provide interfaces for other software. An interface is an API that other packages can access and utilize. Interfaces are identified as a URI and a version name, that comply with the -specification of a version name for package URIs.</p><pre class="programlisting"> +specification of a version name for package URIs.</p> + + +<pre class="programlisting"> + -- Add an interface provided by this version. function add_interface( interface_id in apm_package_dependencies.dependency_id%TYPE @@ -285,10 +499,17 @@ version_id in apm_package_versions.version_id%TYPE ); -</pre><p>The primary use of interfaces is for other packages to specify required +</pre> + + +<p>The primary use of interfaces is for other packages to specify required interfaces, known as dependencies. A package cannot be correctly installed -unless all of its dependencies have been satisfied.</p><pre class="programlisting"> +unless all of its dependencies have been satisfied.</p> + + +<pre class="programlisting"> + -- Add a requirement for this version. A requirement is some interface that this -- version depends on. function add_dependency( @@ -310,9 +531,16 @@ version_id in apm_package_versions.version_id%TYPE ); -</pre><p>As new versions of packages are created, it is necessary to compare their -version names. These two functions assist in that task.</p><pre class="programlisting"> +</pre> + +<p>As new versions of packages are created, it is necessary to compare their +version names. These two functions assist in that task.</p> + + + +<pre class="programlisting"> + -- Given a version_name (e.g. 3.2a), return -- something that can be lexicographically sorted. function sortable_version_name ( @@ -326,10 +554,19 @@ version_name_two in apm_package_versions.version_name%TYPE ) return integer; -</pre><p><span class="strong"><strong>Creating Instances of a Package</strong></span></p><p>Once a package is registered in the system, it is possible to create +</pre> + + +<p><span class="strong"><strong>Creating Instances of a Package</strong></span></p> + +<p>Once a package is registered in the system, it is possible to create instances of it. Each instance can maintain its own content and -parameters.</p><pre class="programlisting"> +parameters.</p> + + +<pre class="programlisting"> + create or replace package apm_application as @@ -351,11 +588,18 @@ ); end apm_application; -</pre><p>Just creating a package instance is not sufficient for it to be served +</pre> + + +<p>Just creating a package instance is not sufficient for it to be served from the web server. A corresponding site node must be created for it. As an example, here is how the <a class="ulink" href="/api-doc" target="_top">OpenACS API Documentation</a> service -makes itself available on the OpenACS main site:</p><pre class="programlisting"> +makes itself available on the OpenACS main site:</p> + + +<pre class="programlisting"> + declare api_doc_id integer; begin @@ -381,17 +625,28 @@ show errors -</pre><p><span class="strong"><strong>Specifying Configuration Parameters for each Instance</strong></span></p><p>A parameter is a setting that can be changed on a package instance basis. +</pre> + + +<p><span class="strong"><strong>Specifying Configuration Parameters for each Instance</strong></span></p> + +<p>A parameter is a setting that can be changed on a package instance basis. Parameters are registered on each <code class="computeroutput">package_key</code>, and the values are associated with each instance. Parameters can have default values and can be of type 'string' or 'number.' There is support with this API for setting a number of minimum and maximum values for each parameter, but for most instances, the minimum and maximum should be 1. It is useful to allow or require multiple values for packages that need to store multiple pieces of information under one parameter. Default values are automatically -set when instances are created, but can be changed for each instance.</p><p>All of the functions below are in the <a class="ulink" href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM" target="_top">APM PL/SQL -package</a>.</p><pre class="programlisting"> +set when instances are created, but can be changed for each instance.</p> +<p>All of the functions below are in the <a class="ulink" href="/api-doc/plsql-subprogram-one?type=PACKAGE&name=APM" target="_top">APM PL/SQL +package</a>.</p> + + + +<pre class="programlisting"> + -- Indicate to APM that a parameter is available to the system. function register_parameter ( parameter_id in apm_parameters.parameter_id%TYPE @@ -436,9 +691,16 @@ default null ); -</pre><p>The following functions are used to associate values with parameters and -instances:</p><pre class="programlisting"> +</pre> + +<p>The following functions are used to associate values with parameters and +instances:</p> + + + +<pre class="programlisting"> + -- Return the value of this parameter for a specific package and parameter. function get_value ( parameter_id in apm_parameter_values.parameter_id%TYPE, @@ -463,18 +725,33 @@ attr_value in apm_parameter_values.attr_value%TYPE ); -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-data-model"></a>Data Model Discussion</h3></div></div></div><p>The central piece of the data model is the <code class="computeroutput">apm_package_types</code> +</pre> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-data-model"></a>Data Model Discussion</h3></div></div></div> + + + +<p>The central piece of the data model is the <code class="computeroutput">apm_package_types</code> table where each package is registered. When a new application or service is installed on an OpenACS instance, a corresponding row in this table is inserted with information about the type of package, e.g. if the <a class="ulink" href="/doc/forum" target="_top">forum package</a> is installed on your OpenACS server, a row in <code class="computeroutput">apm_package_types</code> will be created, noting that it's an -application package type.</p><p>The <code class="computeroutput">apm_packages</code> table is used to contain information about +application package type.</p> + +<p>The <code class="computeroutput">apm_packages</code> table is used to contain information about the <span class="emphasis"><em>instances</em></span> of packages currently created in the system. The <code class="computeroutput">package_key</code> column references the <code class="computeroutput">apm_package_types</code> table to ensure that no package instance can be created for a type that does -not exist.</p><p>The <code class="computeroutput">apm_package_versions</code> table contains information specific +not exist.</p> + +<p>The <code class="computeroutput">apm_package_versions</code> table contains information specific to a particular version of a package. Several tables reference this one to -provide further information about the particular version:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">apm_package_owners</code> +provide further information about the particular version:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">apm_package_owners</code> Stores information about the owners of a particular version of a package. @@ -484,7 +761,11 @@ </p></li><li class="listitem"><p><code class="computeroutput">apm_package_dependencies</code> Stores information about what interfaces the package provides and -requires.</p></li></ul></div><p>Parameter information is maintained through two tables:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">apm_parameters</code> +requires.</p></li></ul></div> + +<p>Parameter information is maintained through two tables:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">apm_parameters</code> This table contains the definition of each of the parameters for a package. @@ -493,8 +774,12 @@ instances. -</p></li></ul></div><p>A number of views are available for obtaining information about packages -registered in the APM.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">apm_package_version_info</code> +</p></li></ul></div> + +<p>A number of views are available for obtaining information about packages +registered in the APM.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">apm_package_version_info</code> Provides information about all of the versions in the system with information available from the <code class="computeroutput">apm_package_types</code> table. @@ -504,15 +789,35 @@ </p></li><li class="listitem"><p><code class="computeroutput">apm_file_info</code> - Provides a public interface for querying file information.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-ui"></a>User Interface</h3></div></div></div><p>The <a class="ulink" href="/acs-admin/apm" target="_top">APM's user interface</a> is part of the + Provides a public interface for querying file information.</p></li></ul></div> + + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-ui"></a>User Interface</h3></div></div></div> + + + +<p>The <a class="ulink" href="/acs-admin/apm" target="_top">APM's user interface</a> is part of the <a class="ulink" href="/acs-admin" target="_top">OpenACS Administration Service</a>. The UI is the primary point of contact with APM by developers and administrators. It is part of OpenACS Administration, because only the site-wide administrator should be able to access it. Thus in order to develop a package, the developer must be granted -site-wide administration.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-config"></a>Configuration/Parameters</h3></div></div></div><p>APM has two parameters for configuring how it interacts with the UNIX +site-wide administration.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-config"></a>Configuration/Parameters</h3></div></div></div> + + + +<p>APM has two parameters for configuring how it interacts with the UNIX filesystem, accessible via the <a class="ulink" href="/admin/site-map/" target="_top">Site Map admin</a> page. These parameters need not be changed under most circumstances, but may -need to be tweaked for Windows compatibility.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>GzipExecutableDirectory</strong></span> +need to be tweaked for Windows compatibility.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>GzipExecutableDirectory</strong></span> This directory points to where the <code class="computeroutput">gunzip</code> program can be found for uncompressing <code class="computeroutput">gzip</code> archives. This is needed for the installation of <code class="computeroutput">.apm</code> files which are simply <code class="computeroutput">gzip</code>ed @@ -521,24 +826,60 @@ </p></li><li class="listitem"><p><span class="strong"><strong>InfoFilePermissionsMode</strong></span> This sets the default UNIX permissions used when creating files using the -APM. Default is 775.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div><p>APM has been in production since OpenACS 3.3, and as of version 4.0 offers a +APM. Default is 775.</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div> + + + +<p>APM has been in production since OpenACS 3.3, and as of version 4.0 offers a stable set of features. One major feature planned is integration with the OpenACS Package Repository for automatic dependency satisfaction. When a user tries to install a package that depends on other packages, the APM will contact the package repository, determine what packages depend on it, and offer the user a chance to download and install them all. This improvement offers value to -end users by facilitating the extension of their OpenACS systems.</p><p>Architecturally, minor improvements to the data model and the +end users by facilitating the extension of their OpenACS systems.</p> + +<p>Architecturally, minor improvements to the data model and the specification file are planned to increase modularity. The current implementation puts all package specification information in a single file. This approach has certain advantages, such as centralization, but splitting this information into several files allows for flexible extensions to the APM -architecture over time.</p><p>APM packages currently lack provisions to verify security information. +architecture over time.</p> + +<p>APM packages currently lack provisions to verify security information. There are plans to add MD5 time stamps and PGP signatures to packages to enable secure authentication of packages. These steps are necessary for APM to be usable as a scalable method to distribute packages on multiple -repositories worldwide.</p><p>Another anticipated change is to split the APM UI into separate systems +repositories worldwide.</p> + +<p>Another anticipated change is to split the APM UI into separate systems for authoring, maintaining, and installing packages. The current UI presents all of this functionality in one interface and it can be confusing from a -usability perspective.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-authors"></a>Authors</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd +usability perspective.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-authors"></a>Authors</h3></div></div></div> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>System creator: Bryan Quinn, Jon Salz, Michael Yoon, Lars Pind, Todd Nightingale.</p></li><li class="listitem"><p>System owner: Bryan Quinn</p></li><li class="listitem"><p>Documentation author: Bryan Quinn, building from earlier versions by Jon -Salz, Michael Yoon, and Lars Pind.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/25/2000</td><td>Bryan Quinn</td></tr><tr><td>0.8</td><td>Ready for QA</td><td>9/29/2000</td><td>Bryan Quinn</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release</td><td>10/02/2000</td><td>Kai Wu</td></tr><tr><td>1.0</td><td>Edited for OpenACS 4.5 Beta release</td><td>03/02/2002</td><td>Roberto Mello</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr><tr><td width="40%" align="left">Package Manager Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Database Access API</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +Salz, Michael Yoon, and Lars Pind.</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-design-rev-history"></a>Revision History</h3></div></div></div> + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/25/2000</td><td>Bryan Quinn</td></tr><tr><td>0.8</td><td>Ready for QA</td><td>9/29/2000</td><td>Bryan Quinn</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release</td><td>10/02/2000</td><td>Kai Wu</td></tr><tr><td>1.0</td><td>Edited for OpenACS 4.5 Beta release</td><td>03/02/2002</td><td>Roberto Mello</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api-detailed.html">Next</a></td></tr><tr><td width="40%" align="left">Package Manager Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Database Access API</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/apm-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/apm-requirements.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="apm-design" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="apm-requirements" id="apm-requirements"></a>Package Manager Requirements</h2></div></div></div><div class="authorblurb"> -<p>By Bryan Quinn and Todd Nightingale</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="apm-requirements" id="apm-requirements"></a>Package Manager Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Bryan Quinn and Todd +Nightingale</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="apm-requirements-intro" id="apm-requirements-intro"></a>Introduction</h3></div></div></div><p>The following is a requirements document for the OpenACS Package Manager (APM), version 4.0 (APM4). APM4 offers a superset of APM Index: openacs-4/packages/acs-core-docs/www/apm-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/apm-requirements.html,v diff -u -r1.37 -r1.38 --- openacs-4/packages/acs-core-docs/www/apm-requirements.html 7 Aug 2017 23:47:49 -0000 1.37 +++ openacs-4/packages/acs-core-docs/www/apm-requirements.html 8 Nov 2017 09:42:10 -0000 1.38 @@ -1,18 +1,40 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Package Manager Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="subsites-design.html" title="Subsites Design Document"><link rel="next" href="apm-design.html" title="Package Manager Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apm-requirements"></a>Package Manager Requirements</h2></div></div></div><div class="authorblurb"><p>By Bryan Quinn and Todd Nightingale</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-intro"></a>Introduction</h3></div></div></div><p>The following is a requirements document for the OpenACS Package Manager +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Package Manager Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="subsites-design.html" title="Subsites Design Document"><link rel="next" href="apm-design.html" title="Package Manager Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="apm-requirements"></a>Package Manager Requirements</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By Bryan Quinn and Todd Nightingale</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-intro"></a>Introduction</h3></div></div></div> + + + +<p>The following is a requirements document for the OpenACS Package Manager (APM), version 4.0 (APM4). APM4 offers a superset of APM v3.3 functionality -with the following specific enhancements:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A public procedural API. (v 3.3 only has web-based UI)</p></li><li class="listitem"><p>Support for dependency checking.</p></li><li class="listitem"><p>Support for compound packages (to support installation chaining).</p></li><li class="listitem"><p>Support for on-line parameter setting.</p></li><li class="listitem"><p>Support for sub-site level configuration (requires revised parameter +with the following specific enhancements:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A public procedural API. (v 3.3 only has web-based UI)</p></li><li class="listitem"><p>Support for dependency checking.</p></li><li class="listitem"><p>Support for compound packages (to support installation chaining).</p></li><li class="listitem"><p>Support for on-line parameter setting.</p></li><li class="listitem"><p>Support for sub-site level configuration (requires revised parameter and /admin pages at sub-site level; deprecation of site-wide parameter -file).</p></li></ul></div><p>To differentiate these new requirements from the requirements of version +file).</p></li></ul></div> + +<p>To differentiate these new requirements from the requirements of version 3.3, all requirements new in v4 are prefaced with the number -<span class="strong"><strong>4</strong></span>.</p><p>We gratefully acknowledge the authors of APM 3 for their original design +<span class="strong"><strong>4</strong></span>.</p> + +<p>We gratefully acknowledge the authors of APM 3 for their original design documentation which suggested these features, as well as the influence of the design and open-source implementation of the Red Hat Package manager, the Debian packaging system, and PERL's CPAN in the development of the ideas -behind this document.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-vision"></a>Vision Statement</h3></div></div></div><p>A typical website will tend to offer its users a number of web-based +behind this document.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-vision"></a>Vision Statement</h3></div></div></div> + + + +<p>A typical website will tend to offer its users a number of web-based services or applications, e.g. a bulletin board, calendaring, classified ads, etc. A website may also have underlying subsystems, such as a permissions system, content management system, etc. For such applications and subsystem @@ -23,30 +45,75 @@ disturbance to the rest of the system. This allows site owners to steadily offer users new and improved services, and also allows programmers to quickly and easily distribute their OpenACS components in a standardized manner to other -OpenACS sites.</p><p>In general terms, a package is a unit of software that serves a single +OpenACS sites.</p> + +<p>In general terms, a package is a unit of software that serves a single well-defined purpose. The OpenACS Package Manager (APM) provides a mechanism for packaging, installing, and configuring OpenACS software in a consistent, -user-friendly, and subsite-aware manner.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-system-overview"></a>System Overview</h3></div></div></div><p> +user-friendly, and subsite-aware manner.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-system-overview"></a>System Overview</h3></div></div></div> + + +<p> The OpenACS Package Manager (APM) consists of: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>A standard format for APM packages</strong></span> including: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Version numbering, independent of any other package and the OpenACS as a -whole</p></li><li class="listitem"><p>Specification of the package interface</p></li><li class="listitem"><p>Specification of dependencies on other packages (if any)</p></li><li class="listitem"><p>Attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>Web-based tools for package management:</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Obtaining packages from a remote distribution point</p></li><li class="listitem"><p>Installing packages, if and only if: </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>All prerequisite packages are installed</p></li><li class="listitem"><p>No conflicts will be created by the installation</p></li></ol></div></li><li class="listitem"><p>Configuring packages (obsoleting the monolithic OpenACS configuration -file)</p></li><li class="listitem"><p>Upgrading packages, without clobbering local modifications</p></li><li class="listitem"><p>Uninstalling unwanted packages</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>A registry of installed packages</strong></span>, database-backed and +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>A standard format for APM packages</strong></span> including: </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Version numbering, independent of any other package and the OpenACS as a +whole</p></li><li class="listitem"><p>Specification of the package interface</p></li><li class="listitem"><p>Specification of dependencies on other packages (if any)</p></li><li class="listitem"><p>Attribution (who wrote it) and ownership (who maintains it)</p></li></ul></div> + + +</li><li class="listitem"><p><span class="strong"><strong>Web-based tools for package management:</strong></span> </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Obtaining packages from a remote distribution point</p></li><li class="listitem"><p>Installing packages, if and only if: </p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>All prerequisite packages are installed</p></li><li class="listitem"><p>No conflicts will be created by the installation</p></li></ol></div> +</li><li class="listitem"><p>Configuring packages (obsoleting the monolithic OpenACS configuration +file)</p></li><li class="listitem"><p>Upgrading packages, without clobbering local modifications</p></li><li class="listitem"><p>Uninstalling unwanted packages</p></li></ul></div> + + +</li><li class="listitem"><p><span class="strong"><strong>A registry of installed packages</strong></span>, database-backed and integrated with file system-based version control -</p></li><li class="listitem"><p><span class="strong"><strong>Web-based tools for package development:</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Creating new packages locally</p></li><li class="listitem"><p>Releasing new versions of locally-created packages</p></li><li class="listitem"><p>Uploading packages to a global package repository on the web</p></li><li class="listitem"><p>Use of these tools should be safe, i.e. installing or removing a package -should never break an OpenACS installation</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>Web-based tools for package configuration:</strong></span> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>The ability to change package parameter values on-line through a simple +</p></li><li class="listitem"><p><span class="strong"><strong>Web-based tools for package development:</strong></span> </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Creating new packages locally</p></li><li class="listitem"><p>Releasing new versions of locally-created packages</p></li><li class="listitem"><p>Uploading packages to a global package repository on the web</p></li><li class="listitem"><p>Use of these tools should be safe, i.e. installing or removing a package +should never break an OpenACS installation</p></li></ul></div> + + +</li><li class="listitem"><p><span class="strong"><strong>Web-based tools for package configuration:</strong></span> </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>The ability to change package parameter values on-line through a simple web interface.</p></li><li class="listitem"><p>A new ad_parameter which does not require a monolithic site-wide parameter's file or server restarts for changes to take effect.</p></li><li class="listitem"><p>The ability to manage multiple package instances at the sub-site -level.</p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div></div><p> +level.</p></li></ul></div> +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div></div> + + +<p> The APM is intended for the following classes of users, which may or may not -overlap: </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>Developers</strong></span> (referred to as 'the developer') use +overlap: </p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>Developers</strong></span> (referred to as 'the developer') use the APM to create a software package for distribution and use the procedural API for direct control of the APM system.</p></li><li class="listitem"><p><span class="strong"><strong>Site-wide administrators</strong></span> (referred to as 'the administrator') use the APM to install packages for their OpenACS instance, and optionally make them available to sub-sites.</p></li><li class="listitem"><p><span class="strong"><strong>Sub-site administrators</strong></span> (referred to as 'the sub-admin') use an administration interface to configure and enable -packages for their sub-site.</p></li></ol></div><p><span class="strong"><strong>Initial Package Development</strong></span></p><p><span class="strong"><strong>David Developer</strong></span> writes a piece of software used to do +packages for their sub-site.</p></li></ol></div> + +<p><span class="strong"><strong>Initial Package Development</strong></span></p> + +<p><span class="strong"><strong>David Developer</strong></span> writes a piece of software used to do knowledge management (km) for the OpenACS. He distributes his data model, procedure code, UI pages, and his documentation according to the APM specification. He splits the documentation and the code into sub-packages, @@ -57,7 +124,11 @@ sub-site level, David configures this option in the package. When the package development is complete, David uses the APM developer UI to construct a distribution file. He assigns it a version number, 1.0, and makes the package -available for download at the OpenACS package repository.</p><p><span class="strong"><strong>Initial Package Installation</strong></span></p><p><span class="strong"><strong>Annie Admin</strong></span> learns of David's KM system by browsing +available for download at the OpenACS package repository.</p> + +<p><span class="strong"><strong>Initial Package Installation</strong></span></p> + +<p><span class="strong"><strong>Annie Admin</strong></span> learns of David's KM system by browsing the OpenACS package repository. Annie Admin uses the APM administrator UI on her system. She selects to install a package from a URL and types the URL displayed on the system. The APM automatically downloads the package. The @@ -68,160 +139,376 @@ toolkit. Annie confirms this option. After successfully installing Jim's toolkit, Annie proceeds to install David's KM system. The data model is loaded and all of the files necessary for the software are installed. Because -installation was successful, the package is available for use.</p><p>Since the package is available for use, its initialization routines are +installation was successful, the package is available for use.</p> + +<p>Since the package is available for use, its initialization routines are set to run automatically on server startup. Annie is warned that since there are initialization routines, she must restart the server for the package to -be ready for use. Annie restarts the server.</p><p><span class="strong"><strong>Initial Subsite Use of Package</strong></span></p><p>Annie Admin decides to make the KM module available only to a particular +be ready for use. Annie restarts the server.</p> + +<p><span class="strong"><strong>Initial Subsite Use of Package</strong></span></p> + +<p>Annie Admin decides to make the KM module available only to a particular sub-site type on her OpenACS system, and not others. She specifies this option -using the Sub-site type UI (not part of APM).</p><p>Annie Admin notifies <span class="strong"><strong>Sally SubAdmin</strong></span> by e-mail that a new +using the Sub-site type UI (not part of APM).</p> + +<p>Annie Admin notifies <span class="strong"><strong>Sally SubAdmin</strong></span> by e-mail that a new package is now available for use. Sally goes to her sub-site /admin page and sees that a new entry, KM, is available. Sally clicks on it and finds links to the installed KM documentation and to the web based configuration utility. Then, Sally configures the package using an automatically generated web interface and enables KM for use on her sub-site. After some initial use of the package, Sally decides to change some parameters using the SubAdmin UI. -These changes take effect immediately, without any server restarts.</p><p><span class="strong"><strong>Upgrade Process</strong></span></p><p>Sally SubAdmin finds a bug in the KM system and sends a report to David +These changes take effect immediately, without any server restarts.</p> + +<p><span class="strong"><strong>Upgrade Process</strong></span></p> + +<p>Sally SubAdmin finds a bug in the KM system and sends a report to David Developer. David reads the bug report and verifies that the bugs are present in the current version. Because the bugs are present in the shared procedure file, David assigns a watch to the file. David makes the necessary modifications to the source code and saves the file. Because a watch was assigned to the file, the APM automatically reloads the updated code. David tests the program and confirms that the bug is fixed. He increments the minor version number and makes km v 1.1 available for download at the -repository.</p><p>Sally SubAdmin asks Annie Administrator to upgrade the package using the +repository.</p> + +<p>Sally SubAdmin asks Annie Administrator to upgrade the package using the APM UI. This upgrade supersedes the old version of KM at the site-wide level. Once Annie upgrades the package, the new version starts working immediately -in Sally's sub-site.</p><p><span class="strong"><strong>Procedural API</strong></span></p><p><span class="strong"><strong>Danielle Developer</strong></span> wants her software to perform +in Sally's sub-site.</p> + +<p><span class="strong"><strong>Procedural API</strong></span></p> + +<p><span class="strong"><strong>Danielle Developer</strong></span> wants her software to perform different actions depending on what version of another package is installed. She uses the APM procedural API to check if KM version 1.0 is installed or version 1.1. Based on the results of this procedural call, the software -exhibits different behavior.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-links"></a>Related Links</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="apm-design" target="_top">APM 3.3 Design document</a></p></li><li class="listitem"><p><a class="ulink" href="packages" target="_top">Five minute guide to packaging a module</a></p></li><li class="listitem"><p><a class="ulink" href="subsites-requirements" target="_top">Sub-sites</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-data-model"></a>Requirements: Data Model</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.500.0 Package Identification</strong></span> -(All of these items are entered by the developer using the developer UI.) </p><p><span class="strong"><strong>4.500.1</strong></span> A human readable package key that is guaranteed +exhibits different behavior.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-links"></a>Related Links</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="apm-design" target="_top">APM 3.3 Design document</a></p></li><li class="listitem"><p><a class="ulink" href="packages" target="_top">Five minute guide to packaging a module</a></p></li><li class="listitem"><p><a class="ulink" href="subsites-requirements" target="_top">Sub-sites</a></p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-data-model"></a>Requirements: Data Model</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.500.0 Package Identification</strong></span> +(All of these items are entered by the developer using the developer UI.) </p> + +<p><span class="strong"><strong>4.500.1</strong></span> A human readable package key that is guaranteed to be unique to the local OpenACS site must be maintained by the APM. For -example, "apm."</p><p><span class="strong"><strong>4.500.5</strong></span> A package id (primary key) that is guaranteed to +example, "apm."</p> + +<p><span class="strong"><strong>4.500.5</strong></span> A package id (primary key) that is guaranteed to be unique to the local site must be maintained by the APM. For example, -"25."</p><p><span class="strong"><strong>4.500.10</strong></span> A package URL that is guaranteed to be unique +"25."</p> + +<p><span class="strong"><strong>4.500.10</strong></span> A package URL that is guaranteed to be unique across all sites must be maintained by the APM. The package URL should point to a server that allows download of the latest version of the package. For example, "http://openacs.org/software." </p></li><li class="listitem"><p><span class="strong"><strong>4.505.0 Version Identification</strong></span> - (All of these items are entered by the developer using the developer UI.) </p><p><span class="strong"><strong>4.505.1</strong></span> A version id (primary key) that is guaranteed to -be unique to the local site must be maintained by the APM.</p><p><span class="strong"><strong>4.505.5</strong></span> A version URL that is guaranteed to be unique + (All of these items are entered by the developer using the developer UI.) </p> + +<p><span class="strong"><strong>4.505.1</strong></span> A version id (primary key) that is guaranteed to +be unique to the local site must be maintained by the APM.</p> + +<p><span class="strong"><strong>4.505.5</strong></span> A version URL that is guaranteed to be unique across all sites must be maintained by the APM. The version URL should point to a server that allows download of a specific version of the package. -</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-api"></a>Requirements: API</h3></div></div></div><p>The API for APM v3 is explicitly a private API. However, it would be +</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-api"></a>Requirements: API</h3></div></div></div> + + + +<p>The API for APM v3 is explicitly a private API. However, it would be useful to obtain information from the APM through a procedural API. Implementing the API specified below is quite easy given that there are pages -that already do all of the below in raw SQL.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.400.0 Packages Status Predicates</strong></span> </p><p><span class="strong"><strong>4.400.1</strong></span> Given defining information such as a package URL, +that already do all of the below in raw SQL.</p> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.400.0 Packages Status Predicates</strong></span> </p> + +<p><span class="strong"><strong>4.400.1</strong></span> Given defining information such as a package URL, the APM API can return the status of the package on the local OpenACS -instance.</p></li><li class="listitem"><p><span class="strong"><strong>4.405.0 Package Information Procedures</strong></span> </p><p><span class="strong"><strong>4.405.1</strong></span> The APM API can return information for any +instance.</p> + + + +</li><li class="listitem"><p><span class="strong"><strong>4.405.0 Package Information Procedures</strong></span> </p> + +<p><span class="strong"><strong>4.405.1</strong></span> The APM API can return information for any locally installed packages, including the version number, paths and files, -and package key.</p></li><li class="listitem"><p><span class="strong"><strong>4.410.0 Sub-site Procedures</strong></span> </p><p><span class="strong"><strong>4.410.1</strong></span> After a package has been installed at the +and package key.</p> + + +</li><li class="listitem"><p><span class="strong"><strong>4.410.0 Sub-site Procedures</strong></span> </p> + +<p><span class="strong"><strong>4.410.1</strong></span> After a package has been installed at the site-wide level, the system API will provide means to check for package -presence, creation, enabling, disabling, and destruction on a subsite.</p></li><li class="listitem"><p><span class="strong"><strong>4.415.0 Parameter Values (replaces ad_parameter)</strong></span> </p><p><span class="strong"><strong>4.415.1</strong></span> The system API shall allow subsite parameters for +presence, creation, enabling, disabling, and destruction on a subsite.</p> + + +</li><li class="listitem"><p><span class="strong"><strong>4.415.0 Parameter Values (replaces ad_parameter)</strong></span> </p> + +<p><span class="strong"><strong>4.415.1</strong></span> The system API shall allow subsite parameters for an installed package to be set by either site-wide administrators or sub-site admins. The subsite parameter can be set to be non-persistent (but default is to survive server restarts). The subsite parameter can also be set to only -take effect after a server restart (default is immediate).</p><p><span class="strong"><strong>4.415.5</strong></span> Parameters for a given subsite and package can be -returned by the system API.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-security"></a>Requirements: Security</h3></div></div></div><p> +take effect after a server restart (default is immediate).</p> + +<p><span class="strong"><strong>4.415.5</strong></span> Parameters for a given subsite and package can be +returned by the system API.</p> + + +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-security"></a>Requirements: Security</h3></div></div></div> + + +<p> Provisions will be made to assure that packages are securely -identified.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.600.1</strong></span> Each package will have a PGP signature and there +identified.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.600.1</strong></span> Each package will have a PGP signature and there will be MD5 time stamps for each file within the package. </p></li><li class="listitem"><p><span class="strong"><strong>4.600.5</strong></span> The APM will provide a facility to validate both -the PGP signature and MD5 stamps information before a package install.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-ui"></a>Requirements: The User Interface</h3></div></div></div><p>The user interface is a set of HTML pages that are used to drive the +the PGP signature and MD5 stamps information before a package install.</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-ui"></a>Requirements: The User Interface</h3></div></div></div> + + + +<p>The user interface is a set of HTML pages that are used to drive the underlying API. It is restricted to site-wide administrators because the -actions taken here can dramatically affect the state of the running OpenACS.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-dev-interface"></a>Requirements: The Developer's Interface</h3></div></div></div><p>The intent of the developer's interface is to enable the developer to +actions taken here can dramatically affect the state of the running OpenACS.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-dev-interface"></a>Requirements: The Developer's Interface</h3></div></div></div> + + + +<p>The intent of the developer's interface is to enable the developer to construct and maintain APM packages. It will be possible to disable the developer's interface for production sites to help reduce the chance of site failure; much of the functionality here can have cascading effects -throughout the OpenACS and should not be used on a production site.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>10.0 Define a package.</strong></span></p><p>The developer must be able to create a new package by specifying some +throughout the OpenACS and should not be used on a production site.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>10.0 Define a package.</strong></span></p> +<p>The developer must be able to create a new package by specifying some identifying information for the package. This includes a package name, a -package key, version information, owner information, and a canonical URL.</p><p><span class="strong"><strong>10.1</strong></span> The APM must maintain the state of all locally -generated packages.</p><p><span class="strong"><strong>10.50</strong></span> If the developer fails to provide the required -information, the package cannot be created.</p><p><span class="strong"><strong>10.55</strong></span> All of the package information should be editable -after creation, except for the package key.</p><p><span class="strong"><strong>4.10.60</strong></span> The package creator must specify whether the +package key, version information, owner information, and a canonical URL.</p> + +<p><span class="strong"><strong>10.1</strong></span> The APM must maintain the state of all locally +generated packages.</p> + +<p><span class="strong"><strong>10.50</strong></span> If the developer fails to provide the required +information, the package cannot be created.</p> + +<p><span class="strong"><strong>10.55</strong></span> All of the package information should be editable +after creation, except for the package key.</p> + +<p><span class="strong"><strong>4.10.60</strong></span> The package creator must specify whether the package is capable of being used in sub-sites, or if only a single, global -instance of the package is permitted.</p><p><span class="strong"><strong>4.10.65</strong></span> If the developer fails to provide unique +instance of the package is permitted.</p> + +<p><span class="strong"><strong>4.10.65</strong></span> If the developer fails to provide unique information for unique fields specified in the data model requirements, the -package cannot be created.</p></li><li class="listitem"><p><span class="strong"><strong>20.0 Add files to a package</strong></span> </p><p><span class="strong"><strong>20.1</strong></span> The developer must be able to add files to the +package cannot be created.</p> + +</li><li class="listitem"><p><span class="strong"><strong>20.0 Add files to a package</strong></span> </p> + +<p><span class="strong"><strong>20.1</strong></span> The developer must be able to add files to the package. This is done by copying the files into the package directory in the host OS's file system. Files can be added at any point after package -creation.</p><p><span class="strong"><strong>20.3</strong></span> Once a package has been versioned and distributed, +creation.</p> + +<p><span class="strong"><strong>20.3</strong></span> Once a package has been versioned and distributed, no new files should be added to the package without incrementing the version -number.</p><p><span class="strong"><strong>20.5</strong></span> The APM's UI should facilitate the process of +number.</p> + +<p><span class="strong"><strong>20.5</strong></span> The APM's UI should facilitate the process of adding new files, by scanning the file system for new files automatically, -and allowing the developer to confirm adding them.</p><p><span class="strong"><strong>20.10</strong></span> The developer cannot add files to a given package -via the UI that do not exist in the file system already.</p><p><span class="strong"><strong>20.15</strong></span> Package file structure must follow a specified +and allowing the developer to confirm adding them.</p> + +<p><span class="strong"><strong>20.10</strong></span> The developer cannot add files to a given package +via the UI that do not exist in the file system already.</p> + +<p><span class="strong"><strong>20.15</strong></span> Package file structure must follow a specified convention. Please see the <a class="link" href="apm-design.html" title="Package Manager Design">design -document</a> for what we do currently.</p></li><li class="listitem"><p><span class="strong"><strong>30.0 Remove files from a package</strong></span></p><p>The developer must be able to remove files from a package. This can be -done in two ways.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="strong"><strong>30.1</strong></span> Access the APM UI, browse the file list, and remove -files.</p><p><span class="strong"><strong>30.1.1</strong></span>If a file is removed from the package list, but not -from the file system, an error should be generated at package load time.</p></li><li class="listitem"><p><span class="strong"><strong>30.5</strong></span> Remove the file from file system. </p><p><span class="strong"><strong>30.5.1</strong></span> The APM UI should take note of the fact that the +document</a> for what we do currently.</p> +</li><li class="listitem"><p><span class="strong"><strong>30.0 Remove files from a package</strong></span></p> +<p>The developer must be able to remove files from a package. This can be +done in two ways.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="strong"><strong>30.1</strong></span> Access the APM UI, browse the file list, and remove +files.</p> + +<p><span class="strong"><strong>30.1.1</strong></span>If a file is removed from the package list, but not +from the file system, an error should be generated at package load time.</p> +</li><li class="listitem"><p><span class="strong"><strong>30.5</strong></span> Remove the file from file system. </p> + +<p><span class="strong"><strong>30.5.1</strong></span> The APM UI should take note of the fact that the file is gone and offer the developer an option to confirm the file's deletion. -</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>40.0 Modify files in a package</strong></span>. </p><p><span class="strong"><strong>40.1</strong></span> The developer should be able to modify files in the -file system. The APM UI should not interfere with this.</p><p><span class="strong"><strong>40.5</strong></span> However, if the developer modifies files containing +</p></li></ul></div> + + +</li><li class="listitem"><p><span class="strong"><strong>40.0 Modify files in a package</strong></span>. </p> + +<p><span class="strong"><strong>40.1</strong></span> The developer should be able to modify files in the +file system. The APM UI should not interfere with this.</p> + +<p><span class="strong"><strong>40.5</strong></span> However, if the developer modifies files containing procedural definitions, APM UI should allow a means to <span class="strong"><strong>watch</strong></span> those files and automatically reload them if changed. See requirement 50.0 -for more detail.</p><p><span class="strong"><strong>40.10</strong></span> Also, although a change in files implies that the +for more detail.</p> + +<p><span class="strong"><strong>40.10</strong></span> Also, although a change in files implies that the package distribution file is out of date, it is the developer's -responsibility to update it.</p></li><li class="listitem"><p><span class="strong"><strong>4.45.0 Manage Package Dependency Information</strong></span>. </p><p><span class="strong"><strong>4.45.1</strong></span> The developer should be able to specify which -interfaces the package requires.</p><p><span class="strong"><strong>4.45.5</strong></span> The developer should be able to specify which -interfaces the package provides.</p><p><span class="strong"><strong>4.45.10</strong></span> Circular dependencies are not allowed.</p></li><li class="listitem"><p><span class="strong"><strong>50.0 Watch a file</strong></span> </p><p><span class="strong"><strong>4.50.1</strong></span> The developer should be able to assign a watch to -any Tcl procedure file, whether in /packages or /tcl.</p><p><span class="strong"><strong>50.5</strong></span> If a watched file is locally modified, then it will +responsibility to update it.</p> +</li><li class="listitem"><p><span class="strong"><strong>4.45.0 Manage Package Dependency Information</strong></span>. </p> + +<p><span class="strong"><strong>4.45.1</strong></span> The developer should be able to specify which +interfaces the package requires.</p> + +<p><span class="strong"><strong>4.45.5</strong></span> The developer should be able to specify which +interfaces the package provides.</p> + +<p><span class="strong"><strong>4.45.10</strong></span> Circular dependencies are not allowed.</p> + +</li><li class="listitem"><p><span class="strong"><strong>50.0 Watch a file</strong></span> </p> + +<p><span class="strong"><strong>4.50.1</strong></span> The developer should be able to assign a watch to +any Tcl procedure file, whether in /packages or /tcl.</p> + +<p><span class="strong"><strong>50.5</strong></span> If a watched file is locally modified, then it will be automatically reloaded, thus allowing for any changes made to take affect -immediately.</p><p><span class="strong"><strong>4.50.10</strong></span> The setting of a watch should be persistent +immediately.</p> + +<p><span class="strong"><strong>4.50.10</strong></span> The setting of a watch should be persistent across server restarts. -</p></li><li class="listitem"><p><span class="strong"><strong>60.0 Display an XML package specification</strong></span> </p><p><span class="strong"><strong>60.1</strong></span> The developer should be able to view the XML package +</p></li><li class="listitem"><p><span class="strong"><strong>60.0 Display an XML package specification</strong></span> </p> + +<p><span class="strong"><strong>60.1</strong></span> The developer should be able to view the XML package specification that encodes all package information. </p></li><li class="listitem"><p><span class="strong"><strong>70.0 Write an XML package specification to the file -system</strong></span> </p><p><span class="strong"><strong>70.1</strong></span> The developer should be able to write an up-to-date -XML specification to disk.</p><p><span class="strong"><strong>70.5</strong></span> The developer should be able to request the current -XML specification for all installed, locally generated packages.</p></li><li class="listitem"><p><span class="strong"><strong>130.0 Distribution file generation</strong></span> </p><p><span class="strong"><strong>130.1</strong></span> The developer should be able to generate a .APM -distribution file for the package with just one click.</p><p><span class="strong"><strong>130.5</strong></span> Generating a distribution file implies doing an +system</strong></span> </p> + +<p><span class="strong"><strong>70.1</strong></span> The developer should be able to write an up-to-date +XML specification to disk.</p> + +<p><span class="strong"><strong>70.5</strong></span> The developer should be able to request the current +XML specification for all installed, locally generated packages.</p> +</li><li class="listitem"><p><span class="strong"><strong>130.0 Distribution file generation</strong></span> </p> + +<p><span class="strong"><strong>130.1</strong></span> The developer should be able to generate a .APM +distribution file for the package with just one click.</p> + +<p><span class="strong"><strong>130.5</strong></span> Generating a distribution file implies doing an "up-to-date" check on all of the files. If any of the files have changed since package installation, then a new version of the package is created. -</p></li><li class="listitem"><p><span class="strong"><strong>140.0 Access CVS information</strong></span> </p><p><span class="strong"><strong>140.1</strong></span> The developer should be able to determine the CVS +</p></li><li class="listitem"><p><span class="strong"><strong>140.0 Access CVS information</strong></span> </p> + +<p><span class="strong"><strong>140.1</strong></span> The developer should be able to determine the CVS status of a package, or all packages, with a single click. -</p></li><li class="listitem"><p><span class="strong"><strong>4.400.0 Compound Package Construction</strong></span> </p><p><span class="strong"><strong>4.400.1</strong></span> The developer can include .APM packages +</p></li><li class="listitem"><p><span class="strong"><strong>4.400.0 Compound Package Construction</strong></span> </p> + +<p><span class="strong"><strong>4.400.1</strong></span> The developer can include .APM packages (sub-packages) within a package (the compound package) like any other -file.</p><p><span class="strong"><strong>4.400.5</strong></span> The recommended usage for this feature is to +file.</p> + +<p><span class="strong"><strong>4.400.5</strong></span> The recommended usage for this feature is to allow for separation of optional and required components from the installation as well as better organization of files once installed. For example, all documentation for the community-core can be packages as <code class="computeroutput">community-core-doc.apm</code>. It is legal to include sub-packages with dependencies that are not satisfied by the packages in the compound package, but this is discouraged. In such a case, the sub-package should really be a -separate package that is required by the compound package.</p><p><span class="strong"><strong>4.400.10</strong></span> If a sub-package is required for the +separate package that is required by the compound package.</p> + +<p><span class="strong"><strong>4.400.10</strong></span> If a sub-package is required for the installation of the compound package, the compound package should have a -registered dependency on the sub-package.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-admin-interface"></a>Requirements: The Site-Wide Administrator's Interface</h3></div></div></div><p>The requirement of the administrator's interface is to enable the +registered dependency on the sub-package.</p> +</li></ul></div> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-admin-interface"></a>Requirements: The Site-Wide Administrator's Interface</h3></div></div></div> + + + +<p>The requirement of the administrator's interface is to enable the administrator to install, enable, upgrade, disable, deinstall, and delete -packages.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>80.0 Package Enable/Disable</strong></span> </p><p><span class="strong"><strong>4.80.1</strong></span> The administrator should be able mark an installed +packages.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>80.0 Package Enable/Disable</strong></span> </p> + +<p><span class="strong"><strong>4.80.1</strong></span> The administrator should be able mark an installed package as enabled. This means that the package is activated and its functionality is delivered through the Request Processor. As of OpenACS 4, this -is done through the sub-site system.</p><p><span class="strong"><strong>4.80.5</strong></span> Moreover, the administrator must be able to +is done through the sub-site system.</p> + +<p><span class="strong"><strong>4.80.5</strong></span> Moreover, the administrator must be able to disable a package, thereby removing the functionality provided to a sub-site. As of OpenACS 4, this is done through the sub-site system. -</p></li><li class="listitem"><p><span class="strong"><strong>90.0 Package Install</strong></span> </p><p><span class="strong"><strong>90.1</strong></span> The administrator must be able to install new -packages either from locally maintained .APM files or from URLs.</p><p><span class="strong"><strong>90.5</strong></span> In the case of an URL, the APM transparently +</p></li><li class="listitem"><p><span class="strong"><strong>90.0 Package Install</strong></span> </p> + +<p><span class="strong"><strong>90.1</strong></span> The administrator must be able to install new +packages either from locally maintained .APM files or from URLs.</p> + +<p><span class="strong"><strong>90.5</strong></span> In the case of an URL, the APM transparently downloads the APM file off the web, proceeds with a file based installation, -and then optionally removes the .APM file just downloaded.</p><p><span class="strong"><strong>90.10.1</strong></span> If .APM files are present in a package, then it -is considered a compound package (use 4.410.0).</p><p><span class="strong"><strong>90.15.0</strong></span> Installation requires these steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>90.15.1</strong></span>The package dependencies are scanned. If some +and then optionally removes the .APM file just downloaded.</p> + +<p><span class="strong"><strong>90.10.1</strong></span> If .APM files are present in a package, then it +is considered a compound package (use 4.410.0).</p> + +<p><span class="strong"><strong>90.15.0</strong></span> Installation requires these steps:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>90.15.1</strong></span>The package dependencies are scanned. If some dependencies are not present, the system warns the administrator that installation cannot proceed until those packages are installed.</p></li><li class="listitem"><p><span class="strong"><strong>90.15.2</strong></span> Assuming all dependencies are present, APM extracts the contents of the APM file into the /packages directory.</p></li><li class="listitem"><p><span class="strong"><strong>90.15.3</strong></span> The administrator is offered the option of importing directly into CVS.</p></li><li class="listitem"><p><span class="strong"><strong>90.15.4</strong></span> The administrator is given a list of data model scripts found in the package and can select which ones to be executed.</p></li><li class="listitem"><p><span class="strong"><strong>90.15.5</strong></span> If no errors are recorded during this process, -the package is enabled.</p></li></ol></div></li><li class="listitem"><p><span class="strong"><strong>4.410.0 Compound package Install</strong></span> </p><p><span class="strong"><strong>4.410.1</strong></span> If .APM files are present in a package, then it -is considered a compound package.</p><p><span class="strong"><strong>4.410.5.0</strong></span> Installation of a compound package proceeds -according to the following sequence:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>4.410.5.1</strong></span> Identify the set of all sub-packages within +the package is enabled.</p></li></ol></div> + + +</li><li class="listitem"><p><span class="strong"><strong>4.410.0 Compound package Install</strong></span> </p> + +<p><span class="strong"><strong>4.410.1</strong></span> If .APM files are present in a package, then it +is considered a compound package.</p> + +<p><span class="strong"><strong>4.410.5.0</strong></span> Installation of a compound package proceeds +according to the following sequence:</p> + + + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>4.410.5.1</strong></span> Identify the set of all sub-packages within the compound package by scanning for all files with .APM.</p></li><li class="listitem"><p><span class="strong"><strong>4.410.5.2</strong></span> Identify which sub-packages are required by checking the dependencies of the compound package. If there dependencies not satisfied by the current system or the packages included with the compound @@ -237,59 +524,151 @@ the installation of a required sub-package, then the installation of the compound package is also a failure.</p></li><li class="listitem"><p><span class="strong"><strong>4.410.5.6</strong></span> Any attempt to install a compound package in the future involves a choice presented to the admin of installing any -uninstalled sub-packages.</p></li></ol></div></li><li class="listitem"><p><span class="strong"><strong>4.420.0 Recovering from failed package installation</strong></span></p><p><span class="strong"><strong>4.420.1</strong></span> If any error is generated during package +uninstalled sub-packages.</p></li></ol></div> + + +</li><li class="listitem"><p><span class="strong"><strong>4.420.0 Recovering from failed package installation</strong></span></p> + + +<p><span class="strong"><strong>4.420.1</strong></span> If any error is generated during package installation, the package is not considered installed. To recover from this -failure, the package should be selected for installation again.</p></li><li class="listitem"><p><span class="strong"><strong>100.0 Version Upgrade</strong></span> </p><p><span class="strong"><strong>100.1</strong></span> The administrator can upgrade to a new version of a -package. This entails</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>100.1.1</strong></span> Running any necessary and included upgrade +failure, the package should be selected for installation again.</p> +</li><li class="listitem"><p><span class="strong"><strong>100.0 Version Upgrade</strong></span> </p> + +<p><span class="strong"><strong>100.1</strong></span> The administrator can upgrade to a new version of a +package. This entails</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>100.1.1</strong></span> Running any necessary and included upgrade scripts.</p></li><li class="listitem"><p><span class="strong"><strong>100.1.5</strong></span> Replacing any old files with new versions.</p></li><li class="listitem"><p><span class="strong"><strong>100.1.10</strong></span> Marking the old version of the package as 'superseded' and disabling it.</p></li><li class="listitem"><p><span class="strong"><strong>100.1.15</strong></span> Assuming no errors from above, the new package -is enabled.</p></li></ol></div></li><li class="listitem"><p><span class="strong"><strong>110.0 Package Deinstall</strong></span> </p><p><span class="strong"><strong>110.1</strong></span> The administrator must be able to deinstall a -package that has already been installed. Deinstallation entails:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>110.1.1</strong></span> Running any data model scripts necessary to drop +is enabled.</p></li></ol></div> + + +</li><li class="listitem"><p><span class="strong"><strong>110.0 Package Deinstall</strong></span> </p> + +<p><span class="strong"><strong>110.1</strong></span> The administrator must be able to deinstall a +package that has already been installed. Deinstallation entails:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>110.1.1</strong></span> Running any data model scripts necessary to drop the package.</p></li><li class="listitem"><p><span class="strong"><strong>110.1.5</strong></span> Moving all of the files into a separate location in the file system from the installed packages.</p></li><li class="listitem"><p><span class="strong"><strong>4.110.1.10</strong></span> If the package is a compound package, then the administrator must confirm removing all sub-packages. Optionally, some -sub-packages can be kept.</p></li></ol></div><p><span class="strong"><strong>110.5</strong></span> Deinstalled packages can be re-installed at a later -date.</p><p><span class="strong"><strong>4.110.10</strong></span> If deinstalling a package or any of its +sub-packages can be kept.</p></li></ol></div> + +<p><span class="strong"><strong>110.5</strong></span> Deinstalled packages can be re-installed at a later +date.</p> + +<p><span class="strong"><strong>4.110.10</strong></span> If deinstalling a package or any of its sub-packages breaks a dependency, then deinstallation cannot proceed until -the package registering the dependency is removed.</p></li><li class="listitem"><p><span class="strong"><strong>120.0 Package Deletion</strong></span> </p><p><span class="strong"><strong>120.1</strong></span> The administrator should be able to completely +the package registering the dependency is removed.</p> + + +</li><li class="listitem"><p><span class="strong"><strong>120.0 Package Deletion</strong></span> </p> + +<p><span class="strong"><strong>120.1</strong></span> The administrator should be able to completely erase all records of the package. This involves removing all instances of the -package, all related database tables and content.</p><p><span class="strong"><strong>120.5</strong></span> This option can only be used if all package +package, all related database tables and content.</p> + + + +<p><span class="strong"><strong>120.5</strong></span> This option can only be used if all package instances are deleted or marked as disabled. This is purposefully cumbersome because deleting all instances of a package can have far-sweeping -consequences throughout a site and should almost never be done.</p></li><li class="listitem"><p><span class="strong"><strong>150.0 Scan for new or modified packages</strong></span> </p><p><span class="strong"><strong>150.1</strong></span> The administrator should be able to scan the file -system for any changes made in any of the installed package files.</p><p><span class="strong"><strong>150.5</strong></span> The administrator should be able to scan the file +consequences throughout a site and should almost never be done.</p> + +</li><li class="listitem"><p><span class="strong"><strong>150.0 Scan for new or modified packages</strong></span> </p> + +<p><span class="strong"><strong>150.1</strong></span> The administrator should be able to scan the file +system for any changes made in any of the installed package files.</p> + +<p><span class="strong"><strong>150.5</strong></span> The administrator should be able to scan the file system for any newly installed packages. -</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-sub-admin-intf"></a>Requirements: The Sub-Site Administrator's Interface</h3></div></div></div><p> +</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-sub-admin-intf"></a>Requirements: The Sub-Site Administrator's Interface</h3></div></div></div> + + +<p> If the developer is in charge of creating packages and the administrator for installing them, then the sub-site administrator is responsible for configuring and enabling packages. In order for a package to be available for a sub-site it must be associated with the sub-site's type specification. This interface is part of the sub-site /admin interface. -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.300</strong></span> Creating a package instance. </p><p><span class="strong"><strong>4.300.1</strong></span> From the sub-site /admin interface, there should +</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>4.300</strong></span> Creating a package instance. </p> + +<p><span class="strong"><strong>4.300.1</strong></span> From the sub-site /admin interface, there should be an option to view all packages available in the system as well as an -option to add a package to the subsite.</p><p><span class="strong"><strong>4.300.5</strong></span> From the "add" option, the sub-admin +option to add a package to the subsite.</p> + +<p><span class="strong"><strong>4.300.5</strong></span> From the "add" option, the sub-admin can select from a list of packages registered as available in the sub-site -type to which the sub-site belongs.</p><p><span class="strong"><strong>4.300.19</strong></span> Once a package instance is added, it is -available on the list of the subsite's available packages.</p></li><li class="listitem"><p><span class="strong"><strong>4.305</strong></span> Configuring a package instance. </p><p><span class="strong"><strong>4.305.1</strong></span> An automatic web interface that lists all -parameters with current values must be available.</p><p><span class="strong"><strong>4.305.5</strong></span> Changing the values for the parameters is -accomplished simply by submitting an HTML form.</p></li><li class="listitem"><p><span class="strong"><strong>4.310</strong></span> Enabling a package instance. </p><p><span class="strong"><strong>4.310.1</strong></span> The sub-admin should be able to enable a package +type to which the sub-site belongs.</p> + +<p><span class="strong"><strong>4.300.19</strong></span> Once a package instance is added, it is +available on the list of the subsite's available packages.</p> +</li><li class="listitem"><p><span class="strong"><strong>4.305</strong></span> Configuring a package instance. </p> + +<p><span class="strong"><strong>4.305.1</strong></span> An automatic web interface that lists all +parameters with current values must be available.</p> + +<p><span class="strong"><strong>4.305.5</strong></span> Changing the values for the parameters is +accomplished simply by submitting an HTML form.</p> +</li><li class="listitem"><p><span class="strong"><strong>4.310</strong></span> Enabling a package instance. </p> + +<p><span class="strong"><strong>4.310.1</strong></span> The sub-admin should be able to enable a package with a single click. Enabling a package means that the OpenACS will serve its URLs properly. -</p></li><li class="listitem"><p><span class="strong"><strong>4.315</strong></span> Disabling a package instance. </p><p><span class="strong"><strong>4.315.1</strong></span> The sub-admin should be able to disable a package +</p></li><li class="listitem"><p><span class="strong"><strong>4.315</strong></span> Disabling a package instance. </p> + +<p><span class="strong"><strong>4.315.1</strong></span> The sub-admin should be able to disable a package with a single click. Disabling a package means that the OpenACS will no longer -serve those URLs.</p></li><li class="listitem"><p><span class="strong"><strong>4.320</strong></span> Deleting a package instance. </p><p><span class="strong"><strong>4.320.1</strong></span> Deleting a package instance involves deleting not +serve those URLs.</p> +</li><li class="listitem"><p><span class="strong"><strong>4.320</strong></span> Deleting a package instance. </p> + +<p><span class="strong"><strong>4.320.1</strong></span> Deleting a package instance involves deleting not only the package instance, but any and all content associated with it. It is questionable whether this option should even be available due to its drastic consequences. Reviewer comments appreciated. -</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-implementation"></a>Implementation notes</h3></div></div></div><p>Despite the fact that requirements are meant to be design/implementation +</p></li></ul></div> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-implementation"></a>Implementation notes</h3></div></div></div> + + + +<p>Despite the fact that requirements are meant to be design/implementation neutral, the following thoughts were in our head when specifying these requirements. You must be familiar with the new object design for this to be -comprehensible.</p><p>When a package is installed system-wide, a corresponding acs_object_type +comprehensible.</p> + +<p>When a package is installed system-wide, a corresponding acs_object_type is created for it. All parameters registered for the package are registered -for that acs_object_type.</p><p>When a package instance is created, it is an acs_object. Its parameters +for that acs_object_type.</p> + +<p>When a package instance is created, it is an acs_object. Its parameters are set using the acs_attribute_values table. The automatic web interface for setting package parameters should be one and the same with the interface for setting acs object attribute values. Consequently, the implementation of -these features should be quite straightforward.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/10/2000</td><td>Bryan Quinn, Todd Nightingale</td></tr><tr><td> </td><td>Reviewed</td><td>8/11/2000</td><td>John Prevost, Mark Thomas, and Pete Su</td></tr><tr><td>0.2</td><td>Revised and updated</td><td>8/12/2000</td><td>Bryan Quinn</td></tr><tr><td>0.3</td><td>Reviewed, revised, and updated - conforms to requirements template.</td><td>8/18/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Minor edits before ACS 4 Beta.</td><td>9/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr><tr><td width="40%" align="left">Subsites Design Document </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Package Manager Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +these features should be quite straightforward.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="apm-requirements-rev-history"></a>Revision History</h3></div></div></div> + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/10/2000</td><td>Bryan Quinn, Todd Nightingale</td></tr><tr><td> </td><td>Reviewed</td><td>8/11/2000</td><td>John Prevost, Mark Thomas, and Pete Su</td></tr><tr><td>0.2</td><td>Revised and updated</td><td>8/12/2000</td><td>Bryan Quinn</td></tr><tr><td>0.3</td><td>Reviewed, revised, and updated - conforms to requirements template.</td><td>8/18/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Minor edits before ACS 4 Beta.</td><td>9/30/2000</td><td>Kai Wu</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-design.html">Next</a></td></tr><tr><td width="40%" align="left">Subsites Design Document </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Package Manager Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/automated-backup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-backup.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/automated-backup.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/automated-backup.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -11,13 +11,13 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="automated-backup" id="automated-backup"></a>Automated Backup</h2></div></div></div><p>The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in -<code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup</code> -and then backs up all of <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code> -to a single zip file, and then copies that zip file to another +<code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup</code> +and then backs up all of <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</code> to a +single zip file, and then copies that zip file to another computer.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Make sure that the manual backup process described above -works.</p></li><li class="listitem"><p>Customize the default backup script. Edit <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/backup.sh</code> +works.</p></li><li class="listitem"><p>Customize the default backup script. Edit <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/backup.sh</code> with your specific parameters.</p></li><li class="listitem"> <p>Make sure the file is executable:</p><pre class="programlisting"> chmod +x backup.sh @@ -26,7 +26,7 @@ <p>Set this file to run automatically by adding a line to root's crontab. (Typically, with <code class="computeroutput">export EDITOR=emacs; crontab -e</code>.) This example runs the backup script at 1:30 am every day.</p><pre class="programlisting"> -30 1 * * * sh /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/backup.sh +30 1 * * * sh /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/backup.sh </pre> </li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/automated-backup.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-backup.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/automated-backup.html 7 Aug 2017 23:47:49 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/automated-backup.html 8 Nov 2017 09:42:10 -0000 1.15 @@ -1,4 +1,19 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Automated Backup</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="snapshot-backup.html" title="Manual backup and recovery"><link rel="next" href="backups-with-cvs.html" title="Using CVS for backup-recovery"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="snapshot-backup.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="backups-with-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="automated-backup"></a>Automated Backup</h2></div></div></div><p>The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup</code> and then backs up all of <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> to a single zip file, and then copies that zip file to another computer.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Make sure that the manual backup process described above works.</p></li><li class="listitem"><p>Customize the default backup script. Edit <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/backup.sh</code> with your specific parameters.</p></li><li class="listitem"><p> - Make sure the file is executable:</p><pre class="programlisting">chmod +x backup.sh</pre></li><li class="listitem"><p> - Set this file to run automatically by adding a line to root's crontab. (Typically, with <code class="computeroutput">export EDITOR=emacs; crontab -e</code>.) This example runs the backup script at 1:30 am every day.</p><pre class="programlisting">30 1 * * * sh /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/backup.sh</pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="snapshot-backup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="backups-with-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Manual backup and recovery </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Using CVS for backup-recovery</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Automated Backup</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="snapshot-backup.html" title="Manual backup and recovery"><link rel="next" href="backups-with-cvs.html" title="Using CVS for backup-recovery"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="snapshot-backup.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="backups-with-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="automated-backup"></a>Automated Backup</h2></div></div></div> + + <p>The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup</code> and then backs up all of <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> to a single zip file, and then copies that zip file to another computer.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Make sure that the manual backup process described above works.</p> + </li><li class="listitem"> + <p>Customize the default backup script. Edit <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/backup.sh</code> with your specific parameters.</p> + </li><li class="listitem"> + <p> + Make sure the file is executable:</p> +<pre class="programlisting">chmod +x backup.sh</pre> + </li><li class="listitem"> + <p> + Set this file to run automatically by adding a line to root's crontab. (Typically, with <code class="computeroutput">export EDITOR=emacs; crontab -e</code>.) This example runs the backup script at 1:30 am every day.</p> + <pre class="programlisting">30 1 * * * sh /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/backup.sh</pre> + </li></ol></div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="snapshot-backup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="backups-with-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Manual backup and recovery </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Using CVS for backup-recovery</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="doc-standards" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="automated-testing-best-practices" id="automated-testing-best-practices"></a>Automated Testing</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:davis\@xarg.net" target="_top">Jeff Davis</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Best practices in writing OpenACS automated tests</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +<a name="automated-testing-best-practices" id="automated-testing-best-practices"></a>Automated Testing</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:davis\@xarg.net" target="_top">Jeff Davis</a> +</span></p><span style="color: red"></authorblurb></span><p>Best practices in writing OpenACS automated tests</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p> <strong>Special characters in Tcl. </strong> Try strings starting with a <code class="computeroutput">-Bad</code> @@ -24,7 +21,7 @@ <code class="computeroutput">-Bad [BAD] \077 { $Bad</code> should be valid user input, should pass through the system unaltered, and if it isn't that's a bug.</p></li><li class="listitem"><p> -<strong>Quoting issues. </strong>Put some html in +<strong>Quoting issues. </strong> Put some html in plain text fields and make sure the result is properly quoted anywhere it shows up (I use "<b>bold</b>" usually). Look out especially for quoting errors in the context bar @@ -37,7 +34,7 @@ from various sources if it's text it should be properly quoted and we should not rely on input validation to prevent XSS security holes.)</p></li><li class="listitem"><p> -<strong>Whitespace input. </strong>Check that +<strong>Whitespace input. </strong> Check that whitespace is not considered valid input for a field if it does not make sense. For example, the subject of a forum post is used to construct a link and if it is " " it will have a link of @@ -51,8 +48,8 @@ <strong>Duplicate names. </strong> Make sure that if a duplicate name is entered that there is a reasonable error rather than a server error. Check for insert, move, copy, and rename.</p></li> -</ul></div><div class="cvstag">($‌Id: auto-testing.xml,v 1.3.14.1 2016/06/23 -08:32:46 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: auto-testing.xml,v 1.4 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="variables" leftLabel="Prev" leftTitle="Variables" Index: openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html,v diff -u -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html 7 Aug 2017 23:47:49 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/automated-testing-best-practices.html 8 Nov 2017 09:42:10 -0000 1.30 @@ -1,10 +1,23 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Automated Testing</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="variables.html" title="Variables"><link rel="next" href="doc-standards.html" title="Chapter 13. Documentation Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="variables.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="doc-standards.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="automated-testing-best-practices"></a>Automated Testing</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:davis@xarg.net" target="_top">Jeff Davis</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Best practices in writing OpenACS automated tests</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Special characters in Tcl. </b> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Automated Testing</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="variables.html" title="Variables"><link rel="next" href="doc-standards.html" title="Chapter 13. Documentation Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="variables.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="doc-standards.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="automated-testing-best-practices"></a>Automated Testing</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="mailto:davis@xarg.net" target="_top">Jeff Davis</a></p> +</authorblurb></span> + + <p>Best practices in writing OpenACS automated tests</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Special characters in Tcl. </b> + Try strings starting with a <code class="computeroutput">-Bad</code> and strings containing <code class="computeroutput">[BAD]</code>, <code class="computeroutput">{</code>, <code class="computeroutput">\077</code>, and <code class="computeroutput">$Bad</code>. For user input, <code class="computeroutput">[BAD]</code> should never be evaluated, <code class="computeroutput">\077</code> should not be turned into a <code class="computeroutput">?</code> and <code class="computeroutput">$Bad</code> should not be interpolated. The string <code class="computeroutput">-Bad [BAD] \077 { $Bad</code> should be valid user input, should pass through the system unaltered, and if it isn't that's a bug. -</p></li><li class="listitem"><p><b>Quoting issues. </b>Put some html in plain text fields and make sure the result is + + </p> + </li><li class="listitem"> + <p> + <b>Quoting issues. </b> + Put some html in plain text fields and make sure the result is properly quoted anywhere it shows up (I use "<b>bold</b>" usually). Look out especially for quoting errors in the context bar and in round trips via an edit form. For fields that disallow html @@ -13,16 +26,38 @@ should be considered an error but given that data for text fields can come from various sources if it's text it should be properly quoted and we should not rely on input validation to prevent XSS security -holes.)</p></li><li class="listitem"><p><b>Whitespace input. </b>Check that whitespace is not considered valid input for a field +holes.) + </p> + </li><li class="listitem"> + <p> + <b>Whitespace input. </b> + Check that whitespace is not considered valid input for a field if it does not make sense. For example, the subject of a forum post is used to construct a link and if it is " " it will have a link of <code class="computeroutput"><a href="..."> </a></code> which would not be clickable if whitespace was allowed as a valid input. -</p></li><li class="listitem"><p><b>Doubleclick. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Doubleclick. </b> + Make sure that if you submit a form, use the back button, and submit again that the behavior is reasonable (correct behavior depends on what the form is for, but a server error is not reasonable). -</p></li><li class="listitem"><p><b>Duplicate names. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Duplicate names. </b> + Make sure that if a duplicate name is entered that there is a reasonable error rather than a server error. Check for insert, move, copy, and rename. -</p></li></ul></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="variables.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="doc-standards.html">Next</a></td></tr><tr><td width="40%" align="left">Variables </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Chapter 13. Documentation Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + + </p> + </li></ul></div> + + +<p><span class="cvstag">($Id$)</span></p> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="variables.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="doc-standards.html">Next</a></td></tr><tr><td width="40%" align="left">Variables </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Chapter 13. Documentation Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/backup-recovery.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/backup-recovery.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -20,22 +20,20 @@ Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs">Using CVS for backup-recovery</a></span></dt> </dl> -</div><div class="authorblurb"> -<div class="cvstag">($‌Id: recovery.xml,v 1.17.6.3 2017/04/21 -15:07:53 gustafn Exp $)</div><p>By <a class="ulink" href="mailto:dhogaza\@pacifier.com" target="_top">Don Baccus</a> with additions by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> +</div><span style="color: red"><authorblurb></span><p><span style="color: red"><span class="cvstag">($‌Id: +recovery.xml,v 1.18 2017/08/07 23:47:55 gustafn Exp +$)</span></span></p><p>By <a class="ulink" href="mailto:dhogaza\@pacifier.com" target="_top">Don Baccus</a> with additions by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> </p><p>We will cover some basic backup and recovery strategies. These are intended to be robust but simple enough to set up. For a large scale production site you would probably need to create your own backup strategies (in particular full dumps from oracle, while easy to set up, are far from the best solution).</p><p>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).</p><div class="figure"> -<a name="idp140592101131768" id="idp140592101131768"></a><p class="title"><strong>Figure 8.1. Backup +<a name="idp140623175809992" id="idp140623175809992"></a><p class="title"><strong>Figure 8.1. Backup and Recovery Strategy</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/backup.png" align="middle" alt="Backup and Recovery Strategy"></div></div> </div><p><br class="figure-break"></p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div> -</div> +</authorblurb></div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="install-next-nightly-vacuum" leftLabel="Prev" leftTitle="Vacuum Postgres nightly" rightLink="install-next-backups" rightLabel="Next" rightTitle="Backup Strategy" Index: openacs-4/packages/acs-core-docs/www/backup-recovery.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backup-recovery.html,v diff -u -r1.44 -r1.45 --- openacs-4/packages/acs-core-docs/www/backup-recovery.html 7 Aug 2017 23:47:49 -0000 1.44 +++ openacs-4/packages/acs-core-docs/www/backup-recovery.html 8 Nov 2017 09:42:10 -0000 1.45 @@ -1,13 +1,33 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 8. Backup and Recovery</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="install-next-nightly-vacuum.html" title="Vacuum Postgres nightly"><link rel="next" href="install-next-backups.html" title="Backup Strategy"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-next-nightly-vacuum.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-next-backups.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="backup-recovery"></a>Chapter 8. Backup and Recovery</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="install-next-backups.html">Backup Strategy</a></span></dt><dt><span class="sect1"><a href="snapshot-backup.html">Manual backup and recovery</a></span></dt><dt><span class="sect1"><a href="automated-backup.html">Automated Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs.html">Using CVS for backup-recovery</a></span></dt></dl></div><div class="authorblurb"><div class="cvstag">($Id$)</div><p>By <a class="ulink" href="mailto:dhogaza@pacifier.com" target="_top">Don Baccus</a> with additions - by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p><p>We will cover some basic backup and recovery strategies. These are intended to +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 8. Backup and Recovery</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="install-next-nightly-vacuum.html" title="Vacuum Postgres nightly"><link rel="next" href="install-next-backups.html" title="Backup Strategy"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-next-nightly-vacuum.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-next-backups.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="backup-recovery"></a>Chapter 8. Backup and Recovery</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="install-next-backups.html">Backup Strategy</a></span></dt><dt><span class="sect1"><a href="snapshot-backup.html">Manual backup and recovery</a></span></dt><dt><span class="sect1"><a href="automated-backup.html">Automated Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs.html">Using CVS for backup-recovery</a></span></dt></dl></div> + + <span style="color: red"><authorblurb> + <p><span class="cvstag">($Id$)</span></p> + + <p>By <a class="ulink" href="mailto:dhogaza@pacifier.com" target="_top">Don Baccus</a> with additions + by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + <p>We will cover some basic backup and recovery strategies. These are intended to be robust but simple enough to set up. For a large scale production site you would probably need to create your own backup strategies (in particular full dumps from oracle, while easy to set up, are far from the best solution). - </p><p>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).</p><p> - </p><div class="figure"><a name="idp140592101131768"></a><p class="title"><b>Figure 8.1. Backup and Recovery Strategy</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/backup.png" align="middle" alt="Backup and Recovery Strategy"></div></div></div><p><br class="figure-break"> + </p> + + <p>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).</p> + <p> + </p><div class="figure"><a name="idp140623175809992"></a><p class="title"><b>Figure 8.1. Backup and Recovery Strategy</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/backup.png" align="middle" alt="Backup and Recovery Strategy"></div> + </div></div><p><br class="figure-break"> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-next-nightly-vacuum.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-next-backups.html">Next</a></td></tr><tr><td width="40%" align="left">Vacuum Postgres nightly </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Backup Strategy</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </authorblurb></span> + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-next-nightly-vacuum.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-next-backups.html">Next</a></td></tr><tr><td width="40%" align="left">Vacuum Postgres nightly </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Backup Strategy</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/backups-with-cvs.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -19,7 +19,7 @@ <code class="filename">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</code> directory is not included in cvs and you may want to add it.</p><pre class="screen"> [root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs commit -m "last-minute commits before upgrade to 4.6"</code></strong> cvs commit: Examining . @@ -32,19 +32,19 @@ (many lines omitted) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> [root root]# -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<span class="action">su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cvs commit -m "last-minute commits before upgrade to 4.6" cvs tag before_upgrade_to_4_6 -exit</span></span> +exit</span> </pre><p>To restore files from a cvs tag such as the one used above:</p><pre class="screen"> [root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs up -r current</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong><span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -cvs up -r current</span></span> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong><span class="action">su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +cvs up -r current</span> </pre> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/backups-with-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/backups-with-cvs.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/backups-with-cvs.html 7 Aug 2017 23:47:49 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/backups-with-cvs.html 8 Nov 2017 09:42:10 -0000 1.15 @@ -1,12 +1,16 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using CVS for backup-recovery</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="automated-backup.html" title="Automated Backup"><link rel="next" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="automated-backup.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="install-redhat.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backups-with-cvs"></a>Using CVS for backup-recovery</h2></div></div></div><p>CVS-only backup is often appropriate for development sites. If you are already using CVS and your data is not important, you probably don't +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using CVS for backup-recovery</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="automated-backup.html" title="Automated Backup"><link rel="next" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="automated-backup.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="install-redhat.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="backups-with-cvs"></a>Using CVS for backup-recovery</h2></div></div></div> + + <p>CVS-only backup is often appropriate for development sites. If you are already using CVS and your data is not important, you probably don't need to do anything to back up your files. Just make sure that your current work is checked into the system. You can then roll back based on date - note the current system time, down to the minute. For maximum safety, you can apply a tag to your current - files. You will still need to back up your database.</p><p> Note that, if you did the CVS options in this document, the <code class="filename">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</code> directory is not included in cvs and you may want to add it.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + files. You will still need to back up your database.</p> + <p> Note that, if you did the CVS options in this document, the <code class="filename">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</code> directory is not included in cvs and you may want to add it.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs commit -m "last-minute commits before upgrade to 4.6"</code></strong> cvs commit: Examining . cvs commit: Examining bin @@ -18,14 +22,18 @@ (many lines omitted) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> [root root]# -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<span class="action">su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cvs commit -m "last-minute commits before upgrade to 4.6" cvs tag before_upgrade_to_4_6 -exit</span></span></pre><p>To restore files from a cvs tag such as the one used above:</p><pre class="screen">[root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +exit</span></pre> + <p>To restore files from a cvs tag such as the one used above:</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs up -r current</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -cvs up -r current</span></span></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="automated-backup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-redhat.html">Next</a></td></tr><tr><td width="40%" align="left">Automated Backup </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Appendix A. Install Red Hat 8/9</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<span class="action">su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +cvs up -r current</span></pre> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="automated-backup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-redhat.html">Next</a></td></tr><tr><td width="40%" align="left">Automated Backup </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Appendix A. Install Red Hat 8/9</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="ext-auth-requirements" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="bootstrap-acs" id="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:jsalz\@mit.edu" target="_top">Jon Salz</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"><li class="listitem"><p>Tcl code: /tcl/0-acs-init.tcl and +<a name="bootstrap-acs" id="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:jsalz\@mit.edu" target="_top">Jon Salz</a> +</span></p><span style="color: red"></authorblurb></span><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"><li class="listitem"><p>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</p></li></ul></div><p>This document describes the startup (bootstrapping) process for an AOLserver running OpenACS.</p><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -103,8 +100,8 @@ </ol></div><p>At this point, <code class="computeroutput">bootstrap.tcl</code> is done executing. AOLserver proceeds to source the remaining files in the <code class="computeroutput">/tcl</code> directory (i.e., -unpackaged libraries) and begins listening for connections.</p><div class="cvstag">($‌Id: bootstrap-acs.xml,v 1.7 2006/07/17 -05:38:38 torbenb Exp $)</div> +unpackaged libraries) and begins listening for connections.</p><p><span class="cvstag">($‌Id: bootstrap-acs.xml,v 1.7 2006/07/17 +05:38:38 torbenb Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/bootstrap-acs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/bootstrap-acs.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 7 Aug 2017 23:47:49 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/bootstrap-acs.html 8 Nov 2017 09:42:10 -0000 1.51 @@ -1,39 +1,68 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Bootstrapping OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="next" href="ext-auth-requirements.html" title="External Authentication Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</p></li></ul></div><p>This document describes the startup (bootstrapping) process for an AOLserver +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Bootstrapping OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"><link rel="next" href="ext-auth-requirements.html" title="External Authentication Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="bootstrap-acs"></a>Bootstrapping OpenACS</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> </p> +</authorblurb></span> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl code: /tcl/0-acs-init.tcl and /packages/acs-kernel/bootstrap.tcl</p></li></ul></div> + +<p>This document describes the startup (bootstrapping) process for an AOLserver running OpenACS. -</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="bootstrap-acs-bigpicture"></a>The Big Picture</h3></div></div></div><p> +</p> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="bootstrap-acs-bigpicture"></a>The Big Picture</h3></div></div></div> + + +<p> Before OpenACS 3.3, the OpenACS startup process was extremely simple: after AOLserver performed its internal initialization (reading the configuration file, loading shared libraries and module code, etc.) it scanned through the Tcl library directory (generally <code class="computeroutput">/var/lib/aolserver/</code><span class="emphasis"><em><code class="computeroutput">yourservername</code></em></span><code class="computeroutput">/tcl</code>), sourcing each file in sequence. -</p><p>While this overall structure for initialization is still intact, package +</p> + +<p>While this overall structure for initialization is still intact, package management has thrown a wrench into the works - there are a few extra things -to do during initialization, most notably:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Examine the OpenACS file tree for files that should not be present in OpenACS +to do during initialization, most notably:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Examine the OpenACS file tree for files that should not be present in OpenACS (i.e., that were once part of the OpenACS distribution but have since been removed).</p></li><li class="listitem"><p>Scan the <code class="computeroutput">/packages</code> directory for new packages.</p></li><li class="listitem"><p>Initialize enabled packages by sourcing their <code class="computeroutput">*-procs.tcl</code> -and <code class="computeroutput">*-init.tcl</code> files.</p></li></ul></div><p> +and <code class="computeroutput">*-init.tcl</code> files.</p></li></ul></div> + +<p> This document examines in detail each of the steps involved in AOLserver/OpenACS startup. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="bootstrap-acs-startup-process"></a>The Startup Process</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="bootstrap-acs-startup-process"></a>The Startup Process</h3></div></div></div> + + +<p> As soon as the <code class="computeroutput">nsd</code> daemon is executed by the <code class="computeroutput">init</code> process (or otherwise), AOLserver reads its configuration file and <code class="computeroutput">chroot</code>s itself if necessary. It then loads shared libraries indicated in the <code class="computeroutput">.ini</code> file (e.g., the Oracle driver and <code class="computeroutput">nssock</code>), and sources Tcl module files (generally in <code class="computeroutput">/home/aol30/modules/tcl</code>). This step is, and has always been, the same for all AOLservers, regardless of whether they are running OpenACS. -</p><p>Next AOLserver sources, in lexicographical order, each file in the +</p> + +<p>Next AOLserver sources, in lexicographical order, each file in the <code class="computeroutput">/tcl</code> directory. The first such file is <code class="computeroutput">0-acs-init.tcl</code>, which doesn't do much directly except to determine the OpenACS path root (e.g., <code class="computeroutput">/var/lib/aolserver/</code><span class="emphasis"><em><code class="computeroutput">yourservername</code></em></span>) by trimming the final component from the path to the Tcl library directory (<code class="computeroutput">/var/lib/aolserver/</code><span class="emphasis"><em><code class="computeroutput">yourservername</code></em></span><code class="computeroutput">/tcl</code>). But <code class="computeroutput">0-acs-init.tcl</code>'s has an important function, namely sourcing -<code class="computeroutput">/packages/acs-core/bootstrap.tcl</code>, which does the following:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>Initialize some NSVs used by the core</strong></span>. These NSVs are +<code class="computeroutput">/packages/acs-core/bootstrap.tcl</code>, which does the following:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>Initialize some NSVs used by the core</strong></span>. These NSVs are documented in <code class="computeroutput">/packages/acs-core/apm-procs.tcl</code> - no need to worry about them unless you're an OpenACS core hacker. @@ -82,8 +111,16 @@ </p></li><li class="listitem"><p><span class="strong"><strong>Verify that the core has been properly initialized</strong></span> by checking for the existence of an NSV created by the request processor initialization code. If it's not present, the server won't be -operational, so we log an error.</p></li></ol></div><p> +operational, so we log an error.</p></li></ol></div> + +<p> At this point, <code class="computeroutput">bootstrap.tcl</code> is done executing. AOLserver proceeds to source the remaining files in the <code class="computeroutput">/tcl</code> directory (i.e., unpackaged libraries) and begins listening for connections. -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Documenting Tcl Files: Page Contracts and Libraries </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> External Authentication Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + + + +<p><span class="cvstag">($Id$)</span></p> +</div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tcl-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ext-auth-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Documenting Tcl Files: Page Contracts and Libraries </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> External Authentication Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/complete-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/complete-install.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/complete-install.html 7 Aug 2017 23:47:49 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/complete-install.html 8 Nov 2017 09:42:10 -0000 1.27 @@ -1,2 +1,16 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 3. Complete Installation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="individual-programs.html" title="Prerequisite Software"><link rel="next" href="unix-installation.html" title="Install a Unix-like system and supporting software"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="unix-installation.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="complete-install"></a>Chapter 3. Complete Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="unix-installation.html">Install a Unix-like system and supporting software</a></span></dt><dt><span class="sect1"><a href="oracle.html">Install Oracle 8.1.7</a></span></dt><dt><span class="sect1"><a href="postgres.html">Install PostgreSQL</a></span></dt><dt><span class="sect1"><a href="aolserver4.html">Install AOLserver 4</a></span></dt><dt><span class="sect1"><a href="openacs.html">Install OpenACS 5.9.0</a></span></dt><dt><span class="sect1"><a href="win2k-installation.html">OpenACS Installation Guide for Windows</a></span></dt><dt><span class="sect1"><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="unix-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Prerequisite Software </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Install a Unix-like system and supporting software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 3. Complete Installation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="individual-programs.html" title="Prerequisite Software"><link rel="next" href="unix-installation.html" title="Install a Unix-like system and supporting software"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="unix-installation.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="complete-install"></a>Chapter 3. Complete Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="unix-installation.html">Install a Unix-like system and supporting software</a></span></dt><dt><span class="sect1"><a href="oracle.html">Install Oracle 8.1.7</a></span></dt><dt><span class="sect1"><a href="postgres.html">Install PostgreSQL</a></span></dt><dt><span class="sect1"><a href="aolserver4.html">Install AOLserver 4</a></span></dt><dt><span class="sect1"><a href="openacs.html">Install OpenACS 5.9.0</a></span></dt><dt><span class="sect1"><a href="win2k-installation.html">OpenACS Installation Guide for Windows</a></span></dt><dt><span class="sect1"><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></span></dt></dl></div> + + + + + + + + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="individual-programs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="unix-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Prerequisite Software </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Install a Unix-like system and supporting software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -11,13 +11,10 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="configuring-configuring-packages" id="configuring-configuring-packages"></a>Configuring an OpenACS -package</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +package</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104638184" id="idp140592104638184"></a>Configuring an OpenACS package</h3></div></div></div><p>After you've installed and mounted your package, you can +<a name="idp140623160110936" id="idp140623160110936"></a>Configuring an OpenACS package</h3></div></div></div><p>After you've installed and mounted your package, you can configure each instance to act as you would like.</p><p>This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Parameters' Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.html 7 Aug 2017 23:47:49 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-packages.html 8 Nov 2017 09:42:10 -0000 1.12 @@ -1,10 +1,18 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Configuring an OpenACS package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-mounting-packages.html" title="Mounting OpenACS packages"><link rel="next" href="configuring-configuring-permissions.html" title="Setting Permissions on an OpenACS package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-mounting-packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="configuring-configuring-permissions.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-configuring-packages"></a>Configuring an OpenACS package</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104638184"></a>Configuring an OpenACS package</h3></div></div></div><p>After you've installed and mounted your package, you can - configure each instance to act as you would like. </p><p>This is done from the Applications page. Log in, go to the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Configuring an OpenACS package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-mounting-packages.html" title="Mounting OpenACS packages"><link rel="next" href="configuring-configuring-permissions.html" title="Setting Permissions on an OpenACS package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-mounting-packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="configuring-configuring-permissions.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-configuring-packages"></a>Configuring an OpenACS package</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623160110936"></a>Configuring an OpenACS package</h3></div></div></div> + + <p>After you've installed and mounted your package, you can + configure each instance to act as you would like. </p> + + <p>This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Parameters' link, you will see a list of parameters that you can change for - this application.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-mounting-packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-configuring-permissions.html">Next</a></td></tr><tr><td width="40%" align="left">Mounting OpenACS packages </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Setting Permissions on an OpenACS package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + this application.</p> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-mounting-packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-configuring-permissions.html">Next</a></td></tr><tr><td width="40%" align="left">Mounting OpenACS packages </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Setting Permissions on an OpenACS package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -11,13 +11,10 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="configuring-configuring-permissions" id="configuring-configuring-permissions"></a>Setting Permissions on an -OpenACS package</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +OpenACS package</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104642200" id="idp140592104642200"></a>Setting Permission on an OpenACS +<a name="idp140623159761448" id="idp140623159761448"></a>Setting Permission on an OpenACS package</h3></div></div></div><p>After you've installed and mounted your package, you can configure each instance to act as you would like.</p><p>This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and Index: openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html 7 Aug 2017 23:47:49 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/configuring-configuring-permissions.html 8 Nov 2017 09:42:10 -0000 1.12 @@ -1,16 +1,29 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Setting Permissions on an OpenACS package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-configuring-packages.html" title="Configuring an OpenACS package"><link rel="next" href="how-do-I.html" title="How Do I?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-configuring-packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="how-do-I.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-configuring-permissions"></a>Setting Permissions on an OpenACS package</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104642200"></a>Setting Permission on an OpenACS package</h3></div></div></div><p>After you've installed and mounted your package, you can - configure each instance to act as you would like. </p><p>This is done from the Applications page. Log in, go to the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Setting Permissions on an OpenACS package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-configuring-packages.html" title="Configuring an OpenACS package"><link rel="next" href="how-do-I.html" title="How Do I?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-configuring-packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="how-do-I.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-configuring-permissions"></a>Setting Permissions on an OpenACS package</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623159761448"></a>Setting Permission on an OpenACS package</h3></div></div></div> + + <p>After you've installed and mounted your package, you can + configure each instance to act as you would like. </p> + + <p>This is done from the Applications page. Log in, go to the Admin or Control Panel, click on the subsite the application is in, and click on Applications. If you click on the 'Permissions' link, you will see and be able to set the permissions for that - application. </p><p>Each application may have different behavior for what Read + application. </p> + + <p>Each application may have different behavior for what Read Create Write and Admin permissions mean, but generally the permissions are straightforward. If you find the behavior is not what you expect after setting permissions, you can post a bug in - the OpenACS bugtracker.</p><p>'The Public' refers to users to the website who are not + the OpenACS bugtracker.</p> + + <p>'The Public' refers to users to the website who are not logged in. 'Registered Users' are people who have registered for - the site. </p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-configuring-packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="how-do-I.html">Next</a></td></tr><tr><td width="40%" align="left">Configuring an OpenACS package </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> How Do I?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + the site. </p> + + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-configuring-packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="how-do-I.html">Next</a></td></tr><tr><td width="40%" align="left">Configuring an OpenACS package </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> How Do I?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/configuring-install-packages.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,13 +10,10 @@ rightLink="configuring-mounting-packages" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="configuring-install-packages" id="configuring-install-packages"></a>Installing OpenACS packages</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="configuring-install-packages" id="configuring-install-packages"></a>Installing OpenACS packages</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592099246776" id="idp140592099246776"></a>Installing OpenACS packages</h3></div></div></div><p>An OpenACS package extends your website and lets it do things it +<a name="idp140623159809704" id="idp140623159809704"></a>Installing OpenACS packages</h3></div></div></div><p>An OpenACS package extends your website and lets it do things it wasn't able to do before. You can have a weblog, a forums, a calendar, or even do sophisticated project-management via your website.</p><p>After you've installed OpenACS, you can congratulate Index: openacs-4/packages/acs-core-docs/www/configuring-install-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-install-packages.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/configuring-install-packages.html 7 Aug 2017 23:47:49 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/configuring-install-packages.html 8 Nov 2017 09:42:10 -0000 1.12 @@ -1,29 +1,50 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing OpenACS packages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="next" href="configuring-mounting-packages.html" title="Mounting OpenACS packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-new-site.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="configuring-mounting-packages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-install-packages"></a>Installing OpenACS packages</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592099246776"></a>Installing OpenACS packages</h3></div></div></div><p>An OpenACS package extends your website and lets it do +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing OpenACS packages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="next" href="configuring-mounting-packages.html" title="Mounting OpenACS packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-new-site.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="configuring-mounting-packages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-install-packages"></a>Installing OpenACS packages</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623159809704"></a>Installing OpenACS packages</h3></div></div></div> + + + <p>An OpenACS package extends your website and lets it do things it wasn't able to do before. You can have a weblog, a forums, a calendar, or even do sophisticated project-management - via your website.</p><p>After you've installed OpenACS, you can congratulate + via your website.</p> + + <p>After you've installed OpenACS, you can congratulate yourself for a job well done. Then, you'll probably want to - install a couple of packages.</p><p>To install packages, you have to be an administrator on + install a couple of packages.</p> + + <p>To install packages, you have to be an administrator on the OpenACS webserver. Log in, and you'll see a link to Admin or the Control Panel. Click on that, then click on 'Install software'. Packages are sometimes also referred to as - applications or software.</p><p>At this point, you'll need to determine whether or not + applications or software.</p> + + <p>At this point, you'll need to determine whether or not you're able to install from the repository, or whether you - should install from local files.</p><p>Basically, if you have a local CVS repository, or have + should install from local files.</p> + + <p>Basically, if you have a local CVS repository, or have custom code, you need to install from 'Local Files'. Otherwise, - you can install from the OpenACS repository</p><p>If you want to install new packages, click on 'Install + you can install from the OpenACS repository</p> + + <p>If you want to install new packages, click on 'Install from Repository' or 'Install from Local'. Select the package, and click 'Install checked applications'. The system will check to make sure you have all necessary packages that the package you want depends on. If you're installing from Local Files, and you are missing any packages, you may have to add the packages your desired package depends on: <a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a> - </p><p>If you run into any errors at all, check your + </p> + + <p>If you run into any errors at all, check your /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log file, and - post your error on the OpenACS forums</p><p>Once the package has been installed, then you will need to - 'mount' the package. The next section handles that.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-new-site.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-mounting-packages.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 4. Configuring a new OpenACS Site </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Mounting OpenACS packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + post your error on the OpenACS forums</p> + + <p>Once the package has been installed, then you will need to + 'mount' the package. The next section handles that.</p> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-new-site.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-mounting-packages.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 4. Configuring a new OpenACS Site </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Mounting OpenACS packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,13 +10,10 @@ rightLink="configuring-configuring-packages" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="configuring-mounting-packages" id="configuring-mounting-packages"></a>Mounting OpenACS packages</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="configuring-mounting-packages" id="configuring-mounting-packages"></a>Mounting OpenACS packages</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104632200" id="idp140592104632200"></a>Mounting OpenACS packages</h3></div></div></div><p>After you've installed your packages, you have to +<a name="idp140623178113768" id="idp140623178113768"></a>Mounting OpenACS packages</h3></div></div></div><p>After you've installed your packages, you have to 'mount' them in order to make them appear on your website.</p><p>Make sure you are logged in, and then click on the 'Admin' or 'Control Panel' link to get to the Index: openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html 7 Aug 2017 23:47:49 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/configuring-mounting-packages.html 8 Nov 2017 09:42:10 -0000 1.12 @@ -1,21 +1,39 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Mounting OpenACS packages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-install-packages.html" title="Installing OpenACS packages"><link rel="next" href="configuring-configuring-packages.html" title="Configuring an OpenACS package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-install-packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="configuring-configuring-packages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-mounting-packages"></a>Mounting OpenACS packages</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104632200"></a>Mounting OpenACS packages</h3></div></div></div><p>After you've installed your packages, you have to 'mount' - them in order to make them appear on your website.</p><p>Make sure you are logged in, and then click on the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Mounting OpenACS packages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-install-packages.html" title="Installing OpenACS packages"><link rel="next" href="configuring-configuring-packages.html" title="Configuring an OpenACS package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-install-packages.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="configuring-configuring-packages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-mounting-packages"></a>Mounting OpenACS packages</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178113768"></a>Mounting OpenACS packages</h3></div></div></div> + + + <p>After you've installed your packages, you have to 'mount' + them in order to make them appear on your website.</p> + + <p>Make sure you are logged in, and then click on the 'Admin' or 'Control Panel' link to get to the Site-Wide Administration page (at /acs-admin). Click on the subsite you'd - like the application to be available at.</p><p>Subsites are a way of dividing your website into logical + like the application to be available at.</p> + + <p>Subsites are a way of dividing your website into logical chunks. Often they represent different groups of users, or parts - of an organization. </p><p>Now click on 'Applications' (applications are the same + of an organization. </p> + + <p>Now click on 'Applications' (applications are the same thing as packages). You'll see a list of Applications and the URLs that each is located at. To mount a new application, you click on 'Add application', enter the Application, title (application name), and URL (URL folder name), and you're - done.</p><p>Test it out now. The URL is based on a combination of the + done.</p> + + <p>Test it out now. The URL is based on a combination of the subsite URL and the application URL. So if you installed a package in the Main Subsite at the URL calendar, it will be available at http://www.yoursite.com/calendar. If you installed it at a subsite that has a URL intranet, then it would be - located at http://www.yoursite.com/intranet/calendar.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-install-packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-configuring-packages.html">Next</a></td></tr><tr><td width="40%" align="left">Installing OpenACS packages </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Configuring an OpenACS package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + located at http://www.yoursite.com/intranet/calendar.</p> + + + </div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-install-packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-configuring-packages.html">Next</a></td></tr><tr><td width="40%" align="left">Installing OpenACS packages </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Configuring an OpenACS package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/configuring-new-site.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-new-site.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/configuring-new-site.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/configuring-new-site.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -21,11 +21,9 @@ an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I">How Do I?</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>In this chapter, <span class="strong"><strong>Configuring</strong></span> refers to making +</div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><p>In this chapter, <span class="strong"><strong>Configuring</strong></span> refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. <span class="strong"><strong>Customizing</strong></span> refers to Index: openacs-4/packages/acs-core-docs/www/configuring-new-site.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/configuring-new-site.html,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/configuring-new-site.html 7 Aug 2017 23:47:49 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/configuring-new-site.html 8 Nov 2017 09:42:10 -0000 1.17 @@ -1,5 +1,22 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 4. Configuring a new OpenACS Site</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"><link rel="next" href="configuring-install-packages.html" title="Installing OpenACS packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="configuring-install-packages.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="configuring-new-site"></a>Chapter 4. Configuring a new OpenACS Site</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="configuring-install-packages.html">Installing OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-mounting-packages.html">Mounting OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-packages.html">Configuring an OpenACS package</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-permissions.html">Setting Permissions on an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I.html">How Do I?</a></span></dt></dl></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>In this chapter, <span class="strong"><strong>Configuring</strong></span> refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. <span class="strong"><strong>Customizing</strong></span> refers to changes that touch the file system, and require some planning if easy upgradability is to be maintained.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-install-packages.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Mac OS X </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Installing OpenACS packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 4. Configuring a new OpenACS Site</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"><link rel="next" href="configuring-install-packages.html" title="Installing OpenACS packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="configuring-install-packages.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="configuring-new-site"></a>Chapter 4. Configuring a new OpenACS Site</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="configuring-install-packages.html">Installing OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-mounting-packages.html">Mounting OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-packages.html">Configuring an OpenACS package</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-permissions.html">Setting Permissions on an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I.html">How Do I?</a></span></dt></dl></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <p>In this chapter, <span class="strong"><strong>Configuring</strong></span> refers to making changes to a new OpenACS site through the web interface. In crude terms, these changes happen in the database, and are upgrade-safe. <span class="strong"><strong>Customizing</strong></span> refers to changes that touch the file system, and require some planning if easy upgradability is to be maintained.</p> + + + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="mac-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-install-packages.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Mac OS X </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Installing OpenACS packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/credits.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/credits.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/credits.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/credits.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -16,11 +16,8 @@ Guides</a></span></dt><dt><span class="section"><a href="os-security">Security Information</a></span></dt><dt><span class="section"><a href="install-resources">Resources</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p> +</div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> +</span></p><span style="color: red"></authorblurb></span><p> <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> put together the January 2002 version of this guide from many sources of information.</p><p> <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> updated the document starting in March @@ -44,8 +41,8 @@ Malte Sussdorff, Stan Kaufman and Pascal Scheffers.</p><p> <span class="strong"><strong>All questions and comments</strong></span> regarding this guide should be posted on -the <a class="ulink" href="http://openacs.org/forums/" target="_top">OpenACS forums</a>.</p><div class="cvstag">($‌Id: credits.xml,v 1.12.14.5 2017/06/18 -09:08:36 gustafn Exp $)</div> +the <a class="ulink" href="http://openacs.org/forums/" target="_top">OpenACS forums</a>.</p><p><span class="cvstag">($‌Id: credits.xml,v 1.13 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="aolserver" leftLabel="Prev" leftTitle="Install AOLserver 3.3oacs1" Index: openacs-4/packages/acs-core-docs/www/credits.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/credits.html,v diff -u -r1.47 -r1.48 --- openacs-4/packages/acs-core-docs/www/credits.html 7 Aug 2017 23:47:49 -0000 1.47 +++ openacs-4/packages/acs-core-docs/www/credits.html 8 Nov 2017 09:42:10 -0000 1.48 @@ -1,19 +1,29 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix C. Credits</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="aolserver.html" title="Install AOLserver 3.3oacs1"><link rel="next" href="install-origins.html" title="Where did this document come from?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-origins.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="credits"></a>Appendix C. Credits</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="install-origins.html">Where did this document come from?</a></span></dt><dt><span class="section"><a href="os-install.html">Linux Install Guides</a></span></dt><dt><span class="section"><a href="os-security.html">Security Information</a></span></dt><dt><span class="section"><a href="install-resources.html">Resources</a></span></dt></dl></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p><a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a> put +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix C. Credits</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="aolserver.html" title="Install AOLserver 3.3oacs1"><link rel="next" href="install-origins.html" title="Where did this document come from?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-origins.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="credits"></a>Appendix C. Credits</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="install-origins.html">Where did this document come from?</a></span></dt><dt><span class="section"><a href="os-install.html">Linux Install Guides</a></span></dt><dt><span class="section"><a href="os-security.html">Security Information</a></span></dt><dt><span class="section"><a href="install-resources.html">Resources</a></span></dt></dl></div> + + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> + </authorblurb></span> + + <p><a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a> put together the January 2002 version of this guide from many sources of - information.</p><p><a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a> - updated the document starting in March 2003.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + information.</p> + + <p><a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a> + updated the document starting in March 2003.</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <a class="ulink" href="http://openacs.org/doc/openacs/install/" target="_top">OpenACS 3.x Installation Guide</a> </p></li><li class="listitem"><p> <a class="ulink" href="https://web.archive.org/web/20011204174701/http://www.orchardlabs.com:80/freebsd/" target="_top">Gilbert Wong's FreeBSD installation guide</a> </p></li><li class="listitem"><p> <a class="ulink" href="http://www.kurup.com/acs/openacs-4.html" target="_top">My own Brief OpenACS4 installation guide</a> - </p></li></ul></div><p> + </p></li></ul></div> + + <p> Acknowledgments for versions of the above documents go (in no particular order) to Bryan Quinn, Adam Farkas, Brian Stein, Doug Hoffman, Ravi Jasuja, Hiro Iwashima, Ryan Lee, Jonathan Goler, Audrey @@ -24,13 +34,28 @@ Richard Li, Jon Griffin, Roberto Mello, Gilbert Wong, Don Baccus, Ben Adida, Michael Cleverly, Janne Blonqvist, Jonathan Ellis, Janine Sisk, Jade Rubick, Chris Hardy, Jonathan Marsden, Vinod Kurup, Charles Hall, - Tom Jackson and Karl Lehenbauer.</p><p> + Tom Jackson and Karl Lehenbauer.</p> + + <p> Several people have helped with this document, including Torben Brosten, Don Baccus, Roberto Mello, Talli Somekh, Dave Bauer, Jim Lynch, Jon Griffin, Daryl Biberdorf, Bjorn Thor Jonsson, Jade Rubick, Fred Yankowski, Dan Chak, Sebastiano Pilla, Reuven Lerner, Malte Sussdorff, Stan Kaufman and Pascal Scheffers. - </p><p> + </p> + + <p> <span class="strong"><strong>All questions and comments</strong></span> regarding this guide should be posted on the <a class="ulink" href="http://openacs.org/forums/" target="_top">OpenACS forums</a>. - </p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-origins.html">Next</a></td></tr><tr><td width="40%" align="left">Install AOLserver 3.3oacs1 </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Where did this document come from?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + <p><span class="cvstag">($Id$)</span></p> + + + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-origins.html">Next</a></td></tr><tr><td width="40%" align="left">Install AOLserver 3.3oacs1 </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Where did this document come from?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,16 +9,15 @@ rightLink="eng-standards-versioning" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="cvs-guidelines" id="cvs-guidelines"></a> CVS Guidelines</h2></div></div></div><div class="authorblurb"> -<div class="cvstag">($‌Id: cvs.xml,v 1.6.14.6 2017/06/17 08:29:28 -gustafn Exp $)</div><p>By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, +<a name="cvs-guidelines" id="cvs-guidelines"></a> CVS Guidelines</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red"><span class="cvstag">($‌Id: cvs.xml,v +1.7 2017/08/07 23:47:54 gustafn Exp $)</span></span></p><p>By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, and Jade Rubick.</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +</authorblurb> +<div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="using-cvs-with-openacs" id="using-cvs-with-openacs"></a>Using CVS with OpenACS</h3></div></div></div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118797960" id="idp140592118797960"></a>Getting Started</h4></div></div></div><p>All OpenACS code is available anonymously. To get code +<a name="idp140623176779576" id="idp140623176779576"></a>Getting Started</h4></div></div></div><p>All OpenACS code is available anonymously. To get code anonymously, use the parameter <code class="computeroutput">-d:pserver:anonymous\@cvs.openacs.org:/cvsroot</code> immediately after <code class="computeroutput">cvs</code> in a cvs command to check out or export code.</p><p>If you are an OpenACS developer, you should check out code so @@ -44,8 +43,8 @@ cvs command. To avoid this, set up ssh certificate authentication for your OpenACS account. (<a class="ulink" href="https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server" target="_top">More information</a>)</p><p>You may want to set some more default actions for CVS usage. To do so, create the file <code class="computeroutput">~/.cvsrc</code> -with the contents:</p><pre class="screen"><span class="action"><span class="action">cvs -z6 -cvs -q</span></span></pre><p> +with the contents:</p><pre class="screen"><span class="action">cvs -z6 +cvs -q</span></pre><p> <code class="computeroutput">-z6</code> speeds up cvs access over the network quite a bit by enabling compressed connection by default. <code class="computeroutput">-q</code> suppresses some @@ -54,25 +53,25 @@ <div class="titlepage"><div><div><p class="title"></p></div></div></div><p>Administrator Note: These are the steps to grant CVS commit rights to a user:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> -<p>Create the user's account. On cvs.openacs.org:</p><pre class="screen"><span class="action"><span class="action">sudo bash -/usr/sbin/useradd -c "<span class="replaceable"><span class="replaceable">Real Name</span></span>" -G cvs -p <span class="replaceable"><span class="replaceable">passwd</span></span><span class="replaceable"><span class="replaceable">username</span></span> -/usr/sbin/usermod -G cvs,<span class="replaceable"><span class="replaceable">username</span></span><span class="replaceable"><span class="replaceable">username</span></span> -</span></span></pre> +<p>Create the user's account. On cvs.openacs.org:</p><pre class="screen"><span class="action">sudo bash +/usr/sbin/useradd -c "<em class="replaceable"><code>Real Name</code></em>" -G cvs -p <em class="replaceable"><code>passwd</code></em><em class="replaceable"><code>username</code></em> +/usr/sbin/usermod -G cvs,<em class="replaceable"><code>username</code></em><em class="replaceable"><code>username</code></em> +</span></pre> </li><li class="listitem"> <p>Grant cvs access to the user account. On any machine, in a -temporary directory:</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT +temporary directory:</p><pre class="screen"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT cd CVSROOT -emacs avail</span></span></pre><p>Add an avail line of the form:</p><pre class="programlisting"> -avail|<span class="replaceable"><span class="replaceable">username</span></span>|openacs-4 -</pre><pre class="screen"><span class="action"><span class="action">cvs commit -m "added commit on X for username" avail</span></span></pre> +emacs avail</span></pre><p>Add an avail line of the form:</p><pre class="programlisting"> +avail|<em class="replaceable"><code>username</code></em>|openacs-4 +</pre><pre class="screen"><span class="action">cvs commit -m "added commit on X for username" avail</span></pre> </li> </ol></div> </div><div class="sidebar"> <div class="titlepage"><div><div><p class="title"></p></div></div></div><p>Branimir suggests an additional level of abstraction. If you put</p><pre class="programlisting"> Host cvs-server HostName cvs.openacs.org - User <span class="replaceable"><span class="replaceable">yournamehere</span></span> + User <em class="replaceable"><code>yournamehere</code></em> </pre><p>into your <code class="computeroutput">~/.ssh/config</code> file, then you can use <code class="computeroutput">-d :ext:cvs-server:/cvsroot</code> instead of <code class="computeroutput">-d :ext:cvs.openacs.org:/cvsroot</code>. You can @@ -81,43 +80,43 @@ </div> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118827320" id="idp140592118827320"></a>Checkout for Package Development</h4></div></div></div><p>If you are actively developing a non-core package, you should +<a name="idp140623176779832" id="idp140623176779832"></a>Checkout for Package Development</h4></div></div></div><p>If you are actively developing a non-core package, you should work from the latest core release branch. Currently this is oacs-5-9. This ensures that you are working on top of a stable OpenACS core, but still allows you to commit feature changes to -non-core packages. To check out all packages,</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-9 openacs-4</span></span></pre><p>If you work in the directories created with this command, all of +non-core packages. To check out all packages,</p><pre class="screen"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-9 openacs-4</span></pre><p>If you work in the directories created with this command, all of your cvs updates and commits will be confined to the oacs-5-9 branch. Your work will be merged back to HEAD for you with each release.</p><p>Because the entire openacs-4 directory is large, you may want to use only acs-core plus some specific modules. To do this, check out -core first:</p><pre class="screen"><span class="action"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-9 checkout acs-core</span></span></pre><p>Then add modules as needed:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages -cvs up -d <span class="replaceable"><span class="replaceable">packagename</span></span> -</span></span></pre><p>... where <span class="replaceable"><span class="replaceable">packagename</span></span> is the name of the package -you want. Visit the <a class="ulink" href="http://openacs.org/packages" target="_top">Package Inventory</a> -and <a class="ulink" href="http://openacs.org/projects/openacs/packages/" target="_top">Package maintainers and status</a> for a list of available +core first:</p><pre class="screen"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-9 checkout acs-core</span></pre><p>Then add modules as needed:</p><pre class="screen"><span class="action">cd /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages +cvs up -d <em class="replaceable"><code>packagename</code></em> +</span></pre><p>... where <em class="replaceable"><code>packagename</code></em> +is the name of the package you want. Visit the <a class="ulink" href="http://openacs.org/packages" target="_top">Package +Inventory</a> and <a class="ulink" href="http://openacs.org/projects/openacs/packages/" target="_top">Package maintainers and status</a> for a list of available packages and their current state.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118836152" id="idp140592118836152"></a>Checkout for Core Development</h4></div></div></div><p>If you are actively developing packages in the OpenACS Core, +<a name="idp140623176821048" id="idp140623176821048"></a>Checkout for Core Development</h4></div></div></div><p>If you are actively developing packages in the OpenACS Core, work from the HEAD branch. HEAD is used for active development of the next version of core OpenACS. It may be very buggy; it may not even install correctly. Do not use this branch for development of non-core features unless your work depends on some of the HEAD core work. To check out HEAD, omit the <code class="computeroutput">-r</code> tag.</p><p>To check out HEAD for development, which requires an OpenACS -developer account:</p><pre class="screen"><span class="action"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre><p>To check out HEAD anonymously:</p><pre class="screen"><span class="action"><span class="action">cvs -d:pserver:anonymous\@cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre> +developer account:</p><pre class="screen"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></pre><p>To check out HEAD anonymously:</p><pre class="screen"><span class="action">cvs -d:pserver:anonymous\@cvs.openacs.org:/cvsroot checkout acs-core</span></pre> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118841528" id="idp140592118841528"></a>Checkout .LRN</h4></div></div></div><p>.LRN consists of a given version OpenACS core, plus a set of +<a name="idp140623176826632" id="idp140623176826632"></a>Checkout .LRN</h4></div></div></div><p>.LRN consists of a given version OpenACS core, plus a set of packages. These are collectively packages together to form a distribution of .LRN. F .LRN 2.0.0 sits on top of OpenACS 5.0.0. .LRN also uses an OpenACS install.xml file during installation; this file is distributed within the dotlrn package and must be moved. To get a development checkout of .LRN in the subdirectory -<code class="literal">dotlrn</code>:</p><pre class="screen"><span class="action"><span class="action">cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 acs-core +<code class="literal">dotlrn</code>:</p><pre class="screen"><span class="action">cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 acs-core mv openacs-4 dotlrn cd dotlrn/packages cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 dotlrn-all -mv dotlrn/install.xml ..</span></span></pre> +mv dotlrn/install.xml ..</span></pre> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="working-with-cvs" id="working-with-cvs"></a>Working with CVS</h4></div></div></div><p>Once you have a checkout you can use some commands to track what @@ -132,7 +131,7 @@ <div class="titlepage"><div><div><h3 class="title"> <a name="openacs-cvs-concepts" id="openacs-cvs-concepts"></a>OpenACS CVS Concepts</h3></div></div></div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118849288" id="idp140592118849288"></a>Modules</h4></div></div></div><p>All OpenACS code resides within a single CVS module, +<a name="idp140623176834888" id="idp140623176834888"></a>Modules</h4></div></div></div><p>All OpenACS code resides within a single CVS module, <code class="computeroutput">openacs-4</code>. (The openacs-4 directory contains code for all versions of OpenACS 4 and later, and .LRN 1 and later.) Checking out this module retrieves all @@ -169,54 +168,49 @@ module of the same name.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118857720" id="idp140592118857720"></a> Tags and Branches</h4></div></div></div><p>Tags and Branches look similar in commands, but behave +<a name="idp140623176843880" id="idp140623176843880"></a> Tags and Branches</h4></div></div></div><p>Tags and Branches look similar in commands, but behave differently. A tag is a fixed point on a branch. Check out a tag to get a specific version of OpenACS. Check out a branch to get the most current code for that major-minor version (e.g., 5.0.x or 5.1.x). You can only commit to a branch, not a tag, so check out a branch if you will be working on the code.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p> -<code class="computeroutput">openacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code> -tags mark final releases of OpenACS. This tag is applied to the -acs-core files for an OpenACS core release, and to the latest -released versions of all other packages at the time of release. -Example: <code class="computeroutput">openacs-5-0-4-final</code>.</p></li><li class="listitem"><p> -<code class="computeroutput">dotlrn-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code> -tags mark final releases of .LRN. These tags apply only to .LRN -packages. Example: <code class="computeroutput">dotlrn-2-0-1-final</code> +<code class="computeroutput">openacs-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-<em class="replaceable"><code>z</code></em>-final</code> tags mark final +releases of OpenACS. This tag is applied to the acs-core files for +an OpenACS core release, and to the latest released versions of all +other packages at the time of release. Example: <code class="computeroutput">openacs-5-0-4-final</code>.</p></li><li class="listitem"><p> +<code class="computeroutput">dotlrn-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-<em class="replaceable"><code>z</code></em>-final</code> tags mark final +releases of .LRN. These tags apply only to .LRN packages. Example: +<code class="computeroutput">dotlrn-2-0-1-final</code> </p></li><li class="listitem"><p> <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">packagename</span></span>-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code> -tags apply to releases of individual packages. For example, -<code class="computeroutput">calendar-2-0-0-final</code> is a tag -that will retrieve only the files in the calendar 2.0.0 release. It -applies only to the calendar package. All non-core, non-dotlrn -packages should have a tag of this style, based on the package -name. Many packages have not been re-released since the new naming -convention was adopted and so don't have a tag of this -type.</p></li><li class="listitem"> +<em class="replaceable"><code>packagename</code></em>-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-<em class="replaceable"><code>z</code></em>-final</code> tags apply to +releases of individual packages. For example, <code class="computeroutput">calendar-2-0-0-final</code> is a tag that will +retrieve only the files in the calendar 2.0.0 release. It applies +only to the calendar package. All non-core, non-dotlrn packages +should have a tag of this style, based on the package name. Many +packages have not been re-released since the new naming convention +was adopted and so don't have a tag of this type.</p></li><li class="listitem"> <p> -<code class="computeroutput">openacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-compat</code> -tags point to the most recent released version of OpenACS -<span class="replaceable"><span class="replaceable">X</span></span>.<span class="replaceable"><span class="replaceable">Y</span></span>. It is -similar to openacs-x-y-z-compat, except that it will always get the -most recent dot-release of Core and the most recent compatible, -released version of all other packages. All of the other tag styles -should be static, but -compat tags may change over time. If you -want version 5.0.4 exactly, use the openacs-5-0-4-final tag. If you -want the best newest released code in the 5.0.x release series and -you want to upgrade within 5.0.x later, use the compat tag.</p><p>For example, if you check out the entire tree with -r +<code class="computeroutput">openacs-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-compat</code> tags point to the +most recent released version of OpenACS <em class="replaceable"><code>X</code></em>.<em class="replaceable"><code>Y</code></em>. It is similar to +openacs-x-y-z-compat, except that it will always get the most +recent dot-release of Core and the most recent compatible, released +version of all other packages. All of the other tag styles should +be static, but -compat tags may change over time. If you want +version 5.0.4 exactly, use the openacs-5-0-4-final tag. If you want +the best newest released code in the 5.0.x release series and you +want to upgrade within 5.0.x later, use the compat tag.</p><p>For example, if you check out the entire tree with -r openacs-5-0-compat, you might get version 5.0.4 of each OpenACS core package, version 2.0.1 of calendar, version 2.0.3 of each .LRN package, etc. If you update the checkout two months later, you might get version 5.0.5 of all OpenACS core packages and version 2.1 of calendar.</p> </li><li class="listitem"> -<p>oacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span> is a -<span class="emphasis"><em>branch,</em></span> , not a tag. All -core packages in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) -are also on the oacs-5-0 branch. Similarly, OpenACS core packages -for 5.1.0 are on the oacs-5-1 branch.</p><p>These branches are used for two purposes. OpenACS Core packages +<p>oacs-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em> is a <span class="emphasis"><em>branch,</em></span> , not a tag. All core packages +in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) are also on +the oacs-5-0 branch. Similarly, OpenACS core packages for 5.1.0 are +on the oacs-5-1 branch.</p><p>These branches are used for two purposes. OpenACS Core packages on these branches are being tidied up for release. Only bug fixes, not new features, should be added to core packages on release branches. For all other packages, release branches are the @@ -242,7 +236,7 @@ “Installation Option 2: Install from tarball”</a>. Continue setting up the site as described there.</p></li><li class="listitem"><p>Fix bugs and add features.</p></li><li class="listitem"> -<p>Commit that file (or files):</p><pre class="screen"><span class="action"><span class="action">cvs commit -m "what I did and why" filename</span></span></pre><p>Because this occurs in your personal checkout and not an +<p>Commit that file (or files):</p><pre class="screen"><span class="action">cvs commit -m "what I did and why" filename</span></pre><p>Because this occurs in your personal checkout and not an anonymous one, this commit automagically moves back upstream to the Mother Ship repository at cvs.openacs.org. The names of the changed files, and your comments, are sent to a mailing list for OpenACS @@ -256,18 +250,18 @@ approval and to get a module alias created.</p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> <p>Check out acs-core on the HEAD branch. (Weird things happen if -you add files to a branch but not to HEAD):</p><pre class="screen"><span class="action"><span class="action">cd /tmp -cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre><p>Copy your package directory from your working directory to this -directory. Make sure not to copy any CVS directories.</p><pre class="screen"><span class="action"><span class="action">cp -r /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> /tmp/openacs-4/packages</span></span></pre><p>Import the package into the cvs.openacs.org cvs repository:</p><pre class="screen"><span class="action"><span class="action">cd /tmp/openacs-4/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> -cvs import -m "Initial import of <span class="replaceable"><span class="replaceable">newpackage</span></span>" openacs-4/packages/newpackage <span class="replaceable"><span class="replaceable">myname</span></span><span class="replaceable"><span class="replaceable">newpackage-0-1d</span></span> -</span></span></pre> +you add files to a branch but not to HEAD):</p><pre class="screen"><span class="action">cd /tmp +cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></pre><p>Copy your package directory from your working directory to this +directory. Make sure not to copy any CVS directories.</p><pre class="screen"><span class="action">cp -r /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages/<em class="replaceable"><code>newpackage</code></em> /tmp/openacs-4/packages</span></pre><p>Import the package into the cvs.openacs.org cvs repository:</p><pre class="screen"><span class="action">cd /tmp/openacs-4/packages/<em class="replaceable"><code>newpackage</code></em> +cvs import -m "Initial import of <em class="replaceable"><code>newpackage</code></em>" openacs-4/packages/newpackage <em class="replaceable"><code>myname</code></em><em class="replaceable"><code>newpackage-0-1d</code></em> +</span></pre> </li><li class="listitem"> <p>Add the new package to the modules file. (An administrator has -to do this step.) On any machine, in a temporary directory:</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT +to do this step.) On any machine, in a temporary directory:</p><pre class="screen"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT cd CVSROOT -emacs modules</span></span></pre><p>Add a line of the form:</p><pre class="programlisting"> -<span class="replaceable"><span class="replaceable">photo-album-portlet</span></span> openacs-4/packages/<span class="replaceable"><span class="replaceable">photo-album-portlet</span></span> -</pre><p>Commit the change:</p><pre class="screen"><span class="action"><span class="action">cvs commit -m "added alias for package <span class="replaceable"><span class="replaceable">newpackage</span></span>" modules</span></span></pre><p>This should print something like:</p><div class="literallayout"><p>cvs commit: Examining .<br> +emacs modules</span></pre><p>Add a line of the form:</p><pre class="programlisting"> +<em class="replaceable"><code>photo-album-portlet</code></em> openacs-4/packages/<em class="replaceable"><code>photo-album-portlet</code></em> +</pre><p>Commit the change:</p><pre class="screen"><span class="action">cvs commit -m "added alias for package <em class="replaceable"><code>newpackage</code></em>" modules</span></pre><p>This should print something like:</p><div class="literallayout"><p>cvs commit: Examining .<br> **** Access allowed: Personal Karma exceeds Environmental Karma.<br> Checking in modules;<br> @@ -282,8 +276,8 @@ package development on the latest release branch that your code is compatible with. So, after completing the import, you may want to branch your package:</p><pre class="programlisting"> -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> -cvs tag -b <span class="replaceable"><span class="replaceable">oacs-5-1</span></span> +cd /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages/<em class="replaceable"><code>newpackage</code></em> +cvs tag -b <em class="replaceable"><code>oacs-5-1</code></em> </pre> </li><li class="listitem"><p>See <a class="xref" href="releasing-package" title="How to package and release an OpenACS Package">the section called “How to package and release an OpenACS @@ -297,7 +291,7 @@ <code class="computeroutput">/packages</code>. This must be done by an OpenACS administrator. On cvs.openacs.org:</p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"><pre class="programlisting"> -cp -r /cvsroot/openacs-4/contrib/packages/<span class="replaceable"><span class="replaceable">package0</span></span> /cvsroot/openacs-4/packages +cp -r /cvsroot/openacs-4/contrib/packages/<em class="replaceable"><code>package0</code></em> /cvsroot/openacs-4/packages </pre></li><li class="listitem"><p>Update the modules file as described above.</p></li><li class="listitem"><p>Remove the directory from cvs in the old location using <code class="computeroutput">cvs rm</code>. One approach <code class="computeroutput">for file in `find | grep -v CVS`; do @@ -415,7 +409,7 @@ </ol></div> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118962952" id="idp140592118962952"></a> Informal Guidelines</h4></div></div></div><p>Informal guidelines which may be obsolete in places and should +<a name="idp140623174806760" id="idp140623174806760"></a> Informal Guidelines</h4></div></div></div><p>Informal guidelines which may be obsolete in places and should be reviewed:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Before committing to cvs you must submit a bug report and patch to the <a class="ulink" href="http://openacs.org/bugtracker/openacs" target="_top">OpenACS bug Index: openacs-4/packages/acs-core-docs/www/cvs-guidelines.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-guidelines.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/cvs-guidelines.html 7 Aug 2017 23:47:49 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/cvs-guidelines.html 8 Nov 2017 09:42:10 -0000 1.12 @@ -1,16 +1,24 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>CVS Guidelines</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="style-guide.html" title="OpenACS Style Guide"><link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="style-guide.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cvs-guidelines"></a> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>CVS Guidelines</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="style-guide.html" title="OpenACS Style Guide"><link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="style-guide.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cvs-guidelines"></a> CVS Guidelines - </h2></div></div></div><div class="authorblurb"><div class="cvstag">($Id$)</div><p> + </h2></div></div></div> + +<span style="color: red"><authorblurb> + <p><span class="cvstag">($Id$)</span></p> + <p> By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, and Jade Rubick. </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="using-cvs-with-openacs"></a>Using CVS with OpenACS</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118797960"></a>Getting Started</h4></div></div></div><p> +</authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="using-cvs-with-openacs"></a>Using CVS with OpenACS</h3></div></div></div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176779576"></a>Getting Started</h4></div></div></div> + + <p> All OpenACS code is available anonymously. To get code anonymously, use the parameter <code class="computeroutput">-d:pserver:anonymous@cvs.openacs.org:/cvsroot</code> immediately after <code class="computeroutput">cvs</code> in a cvs command to check out or export code. - </p><p> + </p> + <p> If you are an OpenACS developer, you should check out code so that you or any other developer can commit it. To do this, use the parameter @@ -22,7 +30,9 @@ you are logged in as "foobar" it will try to check out and commit as if you had specified <code class="computeroutput">:ext:foobar@cvs.openacs.org:/cvsroot</code>. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts. - </p><p> + </p> + + <p> OpenACS.org supports non-anonymous cvs access only over ssh, so you must have <code class="computeroutput">CVS_RSH=ssh</code> in your environment. (Typically this is accomplished by putting @@ -31,71 +41,143 @@ account name does not match your cvs.openacs.org account name, create a file <code class="computeroutput">~/.ssh/config</code> with an entry like: - </p><pre class="programlisting">Host cvs.openacs.org + </p> + <pre class="programlisting">Host cvs.openacs.org User joel -</pre><p> +</pre> + <p> With this setup, you will be asked for your password with each cvs command. To avoid this, set up ssh certificate authentication for your OpenACS account. (<a class="ulink" href="https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server" target="_top">More information</a>) - </p><p> + </p> + + <p> You may want to set some more default actions for CVS usage. To do so, create the file <code class="computeroutput">~/.cvsrc</code> with the contents: - </p><pre class="screen"><span class="action"><span class="action">cvs -z6 -cvs -q</span></span></pre><p><code class="computeroutput">-z6</code> speeds up cvs access over the network quite a bit by enabling compressed - connection by default. <code class="computeroutput">-q</code> suppresses some verbose output from commands. For example, it makes the output of <code class="computeroutput">cvs up</code> much easier to read.</p><div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div><p>Administrator Note: These are the steps to grant CVS commit rights to a user:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Create the user's account. On cvs.openacs.org:</p><pre class="screen"><span class="action"><span class="action">sudo bash -/usr/sbin/useradd -c "<span class="replaceable"><span class="replaceable">Real Name</span></span>" -G cvs -p <span class="replaceable"><span class="replaceable">passwd</span></span> <span class="replaceable"><span class="replaceable">username</span></span> -/usr/sbin/usermod -G cvs,<span class="replaceable"><span class="replaceable">username</span></span> <span class="replaceable"><span class="replaceable">username</span></span> - </span></span></pre></li><li class="listitem"><p>Grant cvs access to the user account. On any machine, + </p> + <pre class="screen"><span class="action">cvs -z6 +cvs -q</span></pre> + <p><code class="computeroutput">-z6</code> speeds up cvs access over the network quite a bit by enabling compressed + connection by default. <code class="computeroutput">-q</code> suppresses some verbose output from commands. For example, it makes the output of <code class="computeroutput">cvs up</code> much easier to read.</p> + <div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> + <p>Administrator Note: These are the steps to grant CVS commit rights to a user:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Create the user's account. On cvs.openacs.org:</p> + <pre class="screen"><span class="action">sudo bash +/usr/sbin/useradd -c "<em class="replaceable"><code>Real Name</code></em>" -G cvs -p <em class="replaceable"><code>passwd</code></em> <em class="replaceable"><code>username</code></em> +/usr/sbin/usermod -G cvs,<em class="replaceable"><code>username</code></em> <em class="replaceable"><code>username</code></em> + </span></pre> + </li><li class="listitem"> + <p>Grant cvs access to the user account. On any machine, in a temporary directory: - </p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT + </p> + <pre class="screen"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT cd CVSROOT -emacs avail</span></span></pre><p>Add an avail line of the form:</p><pre class="programlisting">avail|<span class="replaceable"><span class="replaceable">username</span></span>|openacs-4</pre><pre class="screen"><span class="action"><span class="action">cvs commit -m "added commit on X for username" avail</span></span></pre></li></ol></div></div><div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div><p>Branimir suggests an additional level of abstraction. If you put</p><pre class="programlisting">Host cvs-server +emacs avail</span></pre> + <p>Add an avail line of the form:</p> + <pre class="programlisting">avail|<em class="replaceable"><code>username</code></em>|openacs-4</pre> + <pre class="screen"><span class="action">cvs commit -m "added commit on X for username" avail</span></pre> + </li></ol></div> + </div> + <div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> + <p>Branimir suggests an additional level of abstraction. If you put</p> + <pre class="programlisting">Host cvs-server HostName cvs.openacs.org - User <span class="replaceable"><span class="replaceable">yournamehere</span></span></pre><p>into your <code class="computeroutput">~/.ssh/config</code> file, then you can use <code class="computeroutput">-d :ext:cvs-server:/cvsroot</code> instead of <code class="computeroutput">-d :ext:cvs.openacs.org:/cvsroot</code>. You can then change the definition of <code class="computeroutput">cvs-server</code> by changing one file instead of editing hundreds of <code class="computeroutput">CVSROOT/Repository</code> files.</p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118827320"></a>Checkout for Package Development</h4></div></div></div><p>If you are actively developing a non-core package, you + User <em class="replaceable"><code>yournamehere</code></em></pre> + <p>into your <code class="computeroutput">~/.ssh/config</code> file, then you can use <code class="computeroutput">-d :ext:cvs-server:/cvsroot</code> instead of <code class="computeroutput">-d :ext:cvs.openacs.org:/cvsroot</code>. You can then change the definition of <code class="computeroutput">cvs-server</code> by changing one file instead of editing hundreds of <code class="computeroutput">CVSROOT/Repository</code> files.</p> + </div> + + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176779832"></a>Checkout for Package Development</h4></div></div></div> + + <p>If you are actively developing a non-core package, you should work from the latest core release branch. Currently this is oacs-5-9. This ensures that you are working on top of a stable OpenACS core, but still allows you to commit feature - changes to non-core packages. To check out all packages,</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-9 openacs-4</span></span></pre><p>If you work in the directories created with this command, all of your + changes to non-core packages. To check out all packages,</p> + <pre class="screen"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-9 openacs-4</span></pre> + <p>If you work in the directories created with this command, all of your cvs updates and commits will be confined to the oacs-5-9 branch. Your work will be merged back to HEAD for you - with each release.</p><p>Because the entire openacs-4 directory is large, you may + with each release.</p> + + <p>Because the entire openacs-4 directory is large, you may want to use only acs-core plus some specific modules. To do - this, check out core first:</p><pre class="screen"><span class="action"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-9 checkout acs-core</span></span></pre><p>Then add modules as needed:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages -cvs up -d <span class="replaceable"><span class="replaceable">packagename</span></span></span></span></pre><p>... where <span class="replaceable"><span class="replaceable">packagename</span></span> is the + this, check out core first:</p> + <pre class="screen"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-9 checkout acs-core</span></pre> + <p>Then add modules as needed:</p> + <pre class="screen"><span class="action">cd /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages +cvs up -d <em class="replaceable"><code>packagename</code></em></span></pre> + + <p>... where <em class="replaceable"><code>packagename</code></em> is the name of the package you want. Visit the <a class="ulink" href="http://openacs.org/packages" target="_top"> Package Inventory</a> and <a class="ulink" href="http://openacs.org/projects/openacs/packages/" target="_top">Package maintainers and status</a> for a list of available packages and their current state. - </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118836152"></a>Checkout for Core Development</h4></div></div></div><p>If you are actively developing packages in the OpenACS + </p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176821048"></a>Checkout for Core Development</h4></div></div></div> + + <p>If you are actively developing packages in the OpenACS Core, work from the HEAD branch. HEAD is used for active development of the next version of core OpenACS. It may be very buggy; it may not even install correctly. Do not use this branch for development of non-core features unless your work depends on some of the HEAD core work. To check out HEAD, omit the - <code class="computeroutput">-r</code> tag.</p><p></p><p>To check out HEAD for development, which requires an OpenACS developer account:</p><pre class="screen"><span class="action"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre><p>To check out HEAD anonymously:</p><pre class="screen"><span class="action"><span class="action">cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118841528"></a>Checkout .LRN</h4></div></div></div><p> + <code class="computeroutput">-r</code> tag.</p> + <p></p> + <p>To check out HEAD for development, which requires an OpenACS developer account:</p> + <pre class="screen"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></pre> + <p>To check out HEAD anonymously:</p> + <pre class="screen"><span class="action">cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core</span></pre> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176826632"></a>Checkout .LRN</h4></div></div></div> + + <p> .LRN consists of a given version OpenACS core, plus a set of packages. These are collectively packages together to form a distribution of .LRN. F .LRN 2.0.0 sits on top of OpenACS 5.0.0. .LRN also uses an OpenACS install.xml file during installation; this file is distributed within the dotlrn package and must be moved. To get a development checkout of .LRN in the subdirectory <code class="literal">dotlrn</code>: - </p><pre class="screen"><span class="action"><span class="action">cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 acs-core + </p> + <pre class="screen"><span class="action">cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 acs-core mv openacs-4 dotlrn cd dotlrn/packages cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 dotlrn-all -mv dotlrn/install.xml ..</span></span></pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="working-with-cvs"></a>Working with CVS</h4></div></div></div><p> +mv dotlrn/install.xml ..</span></pre> + </div> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="working-with-cvs"></a>Working with CVS</h4></div></div></div> + + <p> Once you have a checkout you can use some commands to track what has changed since you checked out your copy. <code class="computeroutput">cvs -n update</code> does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS. - </p><p>To update your files, use <code class="computeroutput">cvs update</code>. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="openacs-cvs-concepts"></a>OpenACS CVS Concepts</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118849288"></a>Modules</h4></div></div></div><p> - All OpenACS code resides within a single CVS module, <code class="computeroutput">openacs-4</code>. (The openacs-4 directory contains code for all versions of OpenACS 4 and later, and .LRN 1 and later.) Checking out this module retrieves all OpenACS code of any type. For convenience, subsets of <code class="computeroutput">openacs-4</code> are repackaged as smaller modules.</p><p> + </p> + <p>To update your files, use <code class="computeroutput">cvs update</code>. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.</p> + </div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="openacs-cvs-concepts"></a>OpenACS CVS Concepts</h3></div></div></div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176834888"></a>Modules</h4></div></div></div> + + <p> + All OpenACS code resides within a single CVS module, <code class="computeroutput">openacs-4</code>. (The openacs-4 directory contains code for all versions of OpenACS 4 and later, and .LRN 1 and later.) Checking out this module retrieves all OpenACS code of any type. For convenience, subsets of <code class="computeroutput">openacs-4</code> are repackaged as smaller modules.</p> + + <p> <code class="computeroutput">acs-core</code> contains only critical common packages. It does not have any user applications, such as forums, bug-tracker, calendar, or ecommerce. These can be added at any time. - </p><p>The complete list of core packages is:</p><pre class="programlisting">acs-admin + </p> + <p>The complete list of core packages is:</p> +<pre class="programlisting">acs-admin acs-api-browser acs-authentication acs-automated-testing @@ -111,121 +193,232 @@ acs-subsite acs-tcl acs-templating -ref-timezones search</pre><p> +ref-timezones search</pre> + + <p> <code class="computeroutput">dotlrn-all</code> contains the packages required, in combination with acs-core, to run the .LRN system. - </p><p> + </p> + + <p> <code class="computeroutput">project-manager-all</code> contains the packages required, in combination with acs-core, to run the project-manager package. - </p><p> + </p> + + <p> Each OpenACS package (i.e., directory in <code class="computeroutput">openacs-4/packages/</code>) is also aliased as a module of the same name. - </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118857720"></a> + </p> + + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176843880"></a> Tags and Branches - </h4></div></div></div><p> + </h4></div></div></div> + + <p> Tags and Branches look similar in commands, but behave differently. A tag is a fixed point on a branch. Check out a tag to get a specific version of OpenACS. Check out a branch to get the most current code for that major-minor version (e.g., 5.0.x or 5.1.x). You can only commit to a branch, not a tag, so check out - a branch if you will be working on the code. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">openacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code> + a branch if you will be working on the code. </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><code class="computeroutput">openacs-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-<em class="replaceable"><code>z</code></em>-final</code> tags mark final releases of OpenACS. This tag is applied to the acs-core files for an OpenACS core release, and to the latest released versions of all other packages at the time of release. Example: <code class="computeroutput">openacs-5-0-4-final</code>. - </p></li><li class="listitem"><p><code class="computeroutput">dotlrn-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code> + </p> + </li><li class="listitem"> + <p><code class="computeroutput">dotlrn-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-<em class="replaceable"><code>z</code></em>-final</code> tags mark final releases of .LRN. These tags apply only to .LRN packages. Example: <code class="computeroutput">dotlrn-2-0-1-final</code> - </p></li><li class="listitem"><p><code class="computeroutput"><span class="replaceable"><span class="replaceable">packagename</span></span>-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code> + </p> + </li><li class="listitem"> + <p><code class="computeroutput"><em class="replaceable"><code>packagename</code></em>-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-<em class="replaceable"><code>z</code></em>-final</code> tags apply to releases of individual packages. For example, <code class="computeroutput">calendar-2-0-0-final</code> is a tag that will retrieve only the files in the calendar 2.0.0 release. It applies only to the calendar package. All non-core, non-dotlrn packages should have a tag of this style, based on the package name. Many packages have not been re-released since the new naming convention was adopted and so don't have a tag of this type. - </p></li><li class="listitem"><p><code class="computeroutput">openacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-compat</code> tags point to the most recent released version of OpenACS <span class="replaceable"><span class="replaceable">X</span></span>.<span class="replaceable"><span class="replaceable">Y</span></span>. + </p> + </li><li class="listitem"> + <p><code class="computeroutput">openacs-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em>-compat</code> tags point to the most recent released version of OpenACS <em class="replaceable"><code>X</code></em>.<em class="replaceable"><code>Y</code></em>. It is similar to openacs-x-y-z-compat, except that it will always get the most recent dot-release of Core and the most recent compatible, released version of all other packages. All of the other tag styles should be static, but -compat tags may change over time. If you want version 5.0.4 exactly, use the openacs-5-0-4-final tag. If you want the best newest released code in the 5.0.x release series and you want to upgrade within 5.0.x later, use the compat tag. - </p><p> + </p> + <p> For example, if you check out the entire tree with -r openacs-5-0-compat, you might get version 5.0.4 of each OpenACS core package, version 2.0.1 of calendar, version 2.0.3 of each .LRN package, etc. If you update the checkout two months later, you might get version 5.0.5 of all OpenACS core packages and version 2.1 of calendar. - </p></li><li class="listitem"><p>oacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span> is a <span class="emphasis"><em>branch, </em></span>, not a tag. All core packages in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) are also on the oacs-5-0 branch. Similarly, OpenACS core packages for 5.1.0 are on the oacs-5-1 branch.</p><p>These branches are used for two purposes. OpenACS + </p> + </li><li class="listitem"> + <p>oacs-<em class="replaceable"><code>x</code></em>-<em class="replaceable"><code>y</code></em> is a <span class="emphasis"><em>branch, </em></span>, not a tag. All core packages in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) are also on the oacs-5-0 branch. Similarly, OpenACS core packages for 5.1.0 are on the oacs-5-1 branch.</p> + <p>These branches are used for two purposes. OpenACS Core packages on these branches are being tidied up for release. Only bug fixes, not new features, should be added to core packages on release branches. For all other packages, release branches are the recommended location for development. For example, if you are working on calendar, which is compatible with OpenACS 5.0 but not - 5.1, work on the oacs-5-0 branch.</p></li><li class="listitem"><p><code class="computeroutput">HEAD</code> is a branch used - for development of core packages.</p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="contributing-code"></a>Contributing code back to OpenACS</h3></div></div></div><p>There are three main ways to contribute code to OpenACS:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>To contribute a small fix, if you do not have a developer account, submit a <a class="ulink" href="http://openacs.org/bugtracker/openacs/patch-submission-instructions.htm" target="_top">patch</a>.</p></li><li class="listitem"><p>If you are making many changes, or would like to become a direct contributor, send mail to <a class="ulink" href="mailto:oct@openacs.org" target="_top">the Core Team</a> asking for commit rights. You can then commit code directly to the repository:</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Use one of the checkout methods described above to get files to your system. This takes the place of steps 1 and 2 in <a class="xref" href="openacs.html#install-from-tarball" title="Installation Option 2: Install from tarball">the section called “Installation Option 2: Install from tarball”</a>. Continue setting up the site as described there.</p></li><li class="listitem"><p>Fix bugs and add features.</p></li><li class="listitem"><p> - Commit that file (or files): </p><pre class="screen"><span class="action"><span class="action">cvs commit -m "what I did and why" filename</span></span></pre><p> + 5.1, work on the oacs-5-0 branch.</p> + </li><li class="listitem"> + <p><code class="computeroutput">HEAD</code> is a branch used + for development of core packages.</p> + </li></ul></div> + </div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="contributing-code"></a>Contributing code back to OpenACS</h3></div></div></div> + + <p>There are three main ways to contribute code to OpenACS:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>To contribute a small fix, if you do not have a developer account, submit a <a class="ulink" href="http://openacs.org/bugtracker/openacs/patch-submission-instructions.htm" target="_top">patch</a>.</p> + </li><li class="listitem"> + <p>If you are making many changes, or would like to become a direct contributor, send mail to <a class="ulink" href="mailto:oct@openacs.org" target="_top">the Core Team</a> asking for commit rights. You can then commit code directly to the repository:</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Use one of the checkout methods described above to get files to your system. This takes the place of steps 1 and 2 in <a class="xref" href="openacs.html#install-from-tarball" title="Installation Option 2: Install from tarball">the section called “Installation Option 2: Install from tarball”</a>. Continue setting up the site as described there.</p> + </li><li class="listitem"> + <p>Fix bugs and add features.</p> + </li><li class="listitem"> + <p> + Commit that file (or files): </p> + <pre class="screen"><span class="action">cvs commit -m "what I did and why" filename</span></pre> + <p> Because this occurs in your personal checkout and not an anonymous one, this commit automagically moves back upstream to the Mother Ship repository at cvs.openacs.org. The names of the changed files, and your comments, are sent to a mailing list for OpenACS developers. A Core Team developer may review or roll back your changes if necessary. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Confirm via the <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/" target="_top"> OpenACS CVS browser </a> that your changes are where you intended them to be. - </p></li></ol></div></li><li class="listitem"><p>Add a new package. Contact the <a class="ulink" href="mailto:oct@openacs.org" target="_top">Core Team</a> to get approval and to get a module alias created.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> - Check out acs-core on the HEAD branch. (Weird things happen if you add files to a branch but not to HEAD):</p><pre class="screen"><span class="action"><span class="action">cd /tmp -cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre><p>Copy your package directory from your working directory to this directory. Make sure not to copy any CVS directories.</p><pre class="screen"><span class="action"><span class="action">cp -r /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> /tmp/openacs-4/packages</span></span></pre><p>Import the package into the cvs.openacs.org cvs repository:</p><pre class="screen"><span class="action"><span class="action">cd /tmp/openacs-4/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> -cvs import -m "Initial import of <span class="replaceable"><span class="replaceable">newpackage</span></span>" openacs-4/packages/newpackage <span class="replaceable"><span class="replaceable">myname</span></span> <span class="replaceable"><span class="replaceable">newpackage-0-1d</span></span></span></span></pre></li><li class="listitem"><p>Add the new package to the modules file. (An administrator has to do this step.) On any machine, in a temporary directory:</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT + </p> + </li></ol></div> + </li><li class="listitem"> + <p>Add a new package. Contact the <a class="ulink" href="mailto:oct@openacs.org" target="_top">Core Team</a> to get approval and to get a module alias created.</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p> + Check out acs-core on the HEAD branch. (Weird things happen if you add files to a branch but not to HEAD):</p> + <pre class="screen"><span class="action">cd /tmp +cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></pre> + <p>Copy your package directory from your working directory to this directory. Make sure not to copy any CVS directories.</p> + <pre class="screen"><span class="action">cp -r /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages/<em class="replaceable"><code>newpackage</code></em> /tmp/openacs-4/packages</span></pre> + <p>Import the package into the cvs.openacs.org cvs repository:</p> + <pre class="screen"><span class="action">cd /tmp/openacs-4/packages/<em class="replaceable"><code>newpackage</code></em> +cvs import -m "Initial import of <em class="replaceable"><code>newpackage</code></em>" openacs-4/packages/newpackage <em class="replaceable"><code>myname</code></em> <em class="replaceable"><code>newpackage-0-1d</code></em></span></pre> + </li><li class="listitem"> + <p>Add the new package to the modules file. (An administrator has to do this step.) On any machine, in a temporary directory:</p> + <pre class="screen"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT cd CVSROOT -emacs modules</span></span></pre><p>Add a line of the form:</p><pre class="programlisting"><span class="replaceable"><span class="replaceable">photo-album-portlet</span></span> openacs-4/packages/<span class="replaceable"><span class="replaceable">photo-album-portlet</span></span></pre><p>Commit the change:</p><pre class="screen"><span class="action"><span class="action">cvs commit -m "added alias for package <span class="replaceable"><span class="replaceable">newpackage</span></span>" modules</span></span></pre><p>This should print something like:</p><div class="literallayout"><p>cvs commit: Examining .<br> +emacs modules</span></pre> + <p>Add a line of the form:</p> + <pre class="programlisting"><em class="replaceable"><code>photo-album-portlet</code></em> openacs-4/packages/<em class="replaceable"><code>photo-album-portlet</code></em></pre> + <p>Commit the change:</p> + <pre class="screen"><span class="action">cvs commit -m "added alias for package <em class="replaceable"><code>newpackage</code></em>" modules</span></pre> + <p>This should print something like:</p> + <div class="literallayout"><p>cvs commit: Examining .<br> **** Access allowed: Personal Karma exceeds Environmental Karma.<br> Checking in modules;<br> /cvsroot/CVSROOT/modules,v <-- modules<br> new revision: 1.94; previous revision: 1.93<br> done<br> -cvs commit: Rebuilding administrative file database</p></div></li><li class="listitem"><p>Although you should add your package on HEAD, you should do package development on the latest release branch that your code is compatible with. So, after completing the import, you may want to branch your package:</p><pre class="programlisting">cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> -cvs tag -b <span class="replaceable"><span class="replaceable">oacs-5-1</span></span></pre></li><li class="listitem"><p>See <a class="xref" href="releasing-package.html" title="How to package and release an OpenACS Package">the section called “How to package and release an OpenACS Package”</a></p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Some packages are already in cvs at <code class="computeroutput">openacs-4/contrib/packages</code>. Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the <code class="computeroutput">contrib</code> directory un-necessary. If you are working on a <code class="computeroutput">contrib</code> package, you should move it to <code class="computeroutput">/packages</code>. This must be done by an OpenACS administrator. On cvs.openacs.org:</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><pre class="programlisting">cp -r /cvsroot/openacs-4/contrib/packages/<span class="replaceable"><span class="replaceable">package0</span></span> /cvsroot/openacs-4/packages</pre></li><li class="listitem"><p>Update the modules file as described above.</p></li><li class="listitem"><p>Remove the directory from cvs in the old location using <code class="computeroutput">cvs rm</code>. One approach <code class="computeroutput">for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done</code></p></li></ol></div></div></li></ol></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Commit_Rules"></a> +cvs commit: Rebuilding administrative file database</p></div> + </li><li class="listitem"> + <p>Although you should add your package on HEAD, you should do package development on the latest release branch that your code is compatible with. So, after completing the import, you may want to branch your package:</p> + <pre class="programlisting">cd /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages/<em class="replaceable"><code>newpackage</code></em> +cvs tag -b <em class="replaceable"><code>oacs-5-1</code></em></pre> + </li><li class="listitem"> + <p>See <a class="xref" href="releasing-package.html" title="How to package and release an OpenACS Package">the section called “How to package and release an OpenACS Package”</a></p> + </li></ol></div> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + <p>Some packages are already in cvs at <code class="computeroutput">openacs-4/contrib/packages</code>. Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the <code class="computeroutput">contrib</code> directory un-necessary. If you are working on a <code class="computeroutput">contrib</code> package, you should move it to <code class="computeroutput">/packages</code>. This must be done by an OpenACS administrator. On cvs.openacs.org:</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <pre class="programlisting">cp -r /cvsroot/openacs-4/contrib/packages/<em class="replaceable"><code>package0</code></em> /cvsroot/openacs-4/packages</pre> + </li><li class="listitem"> + <p>Update the modules file as described above.</p> + </li><li class="listitem"> + <p>Remove the directory from cvs in the old location using <code class="computeroutput">cvs rm</code>. One approach <code class="computeroutput">for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done</code></p> + </li></ol></div> + </div> + </li></ol></div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Commit_Rules"></a> Rules for Committing Code to the OpenACS repository - </h4></div></div></div><p> + </h4></div></div></div> + + <p> CVS commit procedures are governed by <a class="ulink" href="http://openacs.org/forums/message-view?message_id=185506" target="_top"> TIP (Technical Improvement Proposal) #61: Guidelines for CVS committers </a> - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> Which branch? - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> For core packages, new features should always be committed on HEAD, not to release branches. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> For core packages, bug fixes should be committed on the current release branch whenever applicable. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> For non-core packages, developers should work on a checkout of the release branch of the lastest release. For example, if OpenACS 5.1.0 is released, developers should work on the oacs-5-1 branch. When oacs-5-2 is branched, developers should continue working on oacs-5-1 until OpenACS 5.2.0 is actually released. - </p><p> + </p> + <p> <span class="emphasis"><em> - Reason: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.</em></span></p></li><li class="listitem"><p> + Reason: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.</em></span></p> + </li><li class="listitem"> + <p> The current release branch is merged back to HEAD after each dot release. - </p></li></ol></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </li><li class="listitem"> + <p> New packages should be created in the <code class="computeroutput"> /packages </code> directory and the maturity flag in the .info file should be zero. This is a change from previous policy, where new packages went to /contrib/packages) - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Code - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> Only GPL code and material should be committed to the OpenACS CVS repository (cvs.openacs.org) - </p></li><li class="listitem"><p>Do not mix formatting changes with code changes. Instead, make a formatting-only change which does not affect the logic, and say so in the commit comment. Then, make the logic change in a separate commit. <span class="emphasis"><em>Reason: This makes auditing and merging code much easier.</em></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p>Do not mix formatting changes with code changes. Instead, make a formatting-only change which does not affect the logic, and say so in the commit comment. Then, make the logic change in a separate commit. <span class="emphasis"><em>Reason: This makes auditing and merging code much easier.</em></span> + </p> + </li><li class="listitem"> + <p> Database upgrade scripts should only span one release increment, and should follow <a class="ulink" href="http://openacs.org/doc/current/eng-standards-versioning.html#naming-upgrade-scripts" target="_top"> Naming Database Upgrade Scripts </a> . - </p><p> + </p> + <p> <span class="emphasis"><em>Reason: If an upgrade script ends with the final release number, then if a problem is found in a release candidate it cannot be addressed with another upgrade script. E.g., the last planned @@ -234,61 +427,102 @@ that using rc1 instead of b1 would be nice, because that's the convention with release codes in cvs, but the package manager doesn't support rc tags.</em></span> - </p></li><li class="listitem"><p> + </p> + + </li><li class="listitem"> + <p> Database upgrade scripts should never go to the release version, e.g., should always have a letter suffix such as d1 or b1. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> CVS commit messages should be intelligible in the context of Changelogs. They should not refer to the files or versions. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> CVS commit messages and code comments should refer to bug, tip, or patch number if appropriate, in the format "resolves bug 11", "resolves bugs 11, resolves bug 22". "implements tip 42", "implements tip 42, implements tip 50", "applies patch 456 by User Name", "applies patch 456 by User Name, applies patch 523 by ...". - </p></li></ol></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </li><li class="listitem"> + <p> When to TIP - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> A TIP is a Techical Improvement Proposal ( <a class="ulink" href="http://openacs.org/forums/message-view?message_id=115576" target="_top"> more information </a> ). A proposed change must be approved by TIP if: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> It changes the core data model, or - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> It will change the behavior of any core package in a way that affects existing code (typically, by changing public API), or - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> It is a non-backwards-compatible change to any core or standard package. - </p></li></ol></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </li><li class="listitem"> + <p> A proposed change need not be TIPped if: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> it adds a new function to a core package in a way that: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> does not change the backwards-compatibility of public API functions. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> does not change the data model - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> has no negative impact on performance - </p></li></ol></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </li><li class="listitem"> + <p> it changes private API, or - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> it is a change to a non-core, non-standard package - </p></li></ol></div></li></ol></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </li></ol></div> + </li><li class="listitem"> + <p> Tags - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> When a package is released in final form, the developer shall tag it "packagename-x-y-z-final" and "openacs-x-y-compat". x-y should correspond to the current branch. If the package is compatible with several different core versions, several compat tags should be applied. - </p><p> + </p> + <p> <span class="emphasis"><em>Reason 1: The packagename tag is a permanent, static tag that allows for future comparison. The compat tag is a floating tag which is used by the repository generator to determine @@ -299,10 +533,13 @@ identify packages which have been released since the last core release.Reason 3: The compat tag or something similar is required to make Rule 6 possible.</em></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> When OpenACS core is released, the openacs-x-y-z-final tag shall be applied to all compat packages. - </p><p> + </p> + <p> <span class="emphasis"><em> Reason: This allows OpenACS developers who are creating extensively customized sites to branch from a tag which is stable, @@ -311,17 +548,26 @@ needed, and provides a common ancestor between the fork and the OpenACS code so that patches can be generated. </em></span> - </p></li></ol></div><p> + </p> + </li></ol></div> + <p> For example, adding a new API function wouldn't require a TIP. Changing an existing API function by adding an optional new flag which defaults to no-effect wouldn't require a TIP. Added a new mandatory flag to an existing function would require a TIP. - </p></li></ol></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118962952"></a> + </p> + </li></ol></div> + </div> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623174806760"></a> Informal Guidelines - </h4></div></div></div><p> + </h4></div></div></div> + + <p> Informal guidelines which may be obsolete in places and should be reviewed: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Before committing to cvs you must submit a bug report and patch to the <a class="ulink" href="http://openacs.org/bugtracker/openacs" target="_top"> @@ -336,28 +582,40 @@ </a> committing in a package they are maintaining and for members of the core team. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> If you are committing a bug fix you need to coordinate with the package maintainer. If you are a maintainer then coordinate with any fellow maintainers. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> If you are to commit a new feature, an architecture change, or a refactoring, you must coordinate with the OpenACS core team first. Also, such changes should have a discussion in the forums to allow for feedback from the whole community. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> If you are changing the data model you *must* provide an upgrade script and bump up the version number of the package. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Consider any upgradability ramifications of your change. Avoid changing the contract and behaviour of Tcl procedures. If you want to build a new and clean API consider deprecating the old proc and making it invoke the new one. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Never rush to commit something. Before committing double check with cvs diff what exactly you are committing. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Always accompany a commit with a brief but informative comment. If your commit is related to bug number N and/or patch number P, indicate this in the commit comment by including "bug N" @@ -366,15 +624,21 @@ you are committing a patch that closes a missing HTML tag, then an appropriate comment could be "Fixing bug 321 by applying patch 134. Added missing h3 HTML close tag". - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Commit one cohesive bug fix or feature change at a time. Don't put a bunch of unrelated changes into one commit. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Before you throw out or change a piece of code that you don't fully understand, use cvs annotate and cvs log on the file to see who wrote the code and why. Consider contacting the author. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Test your change before committing. Use the OpenACS package acs-automated-testing to test Tcl procedures and the tool @@ -383,33 +647,62 @@ </a> to test pages - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Keep code simple, adhere to conventions, and use comments liberally. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> In general, treat the code with respect, at the same time, never stop questioning what you see. The code can always be improved, just make sure you change the code in a careful and systematic fashion. - </p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="cvs-resources"></a>Additional Resources for CVS</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + </li></ul></div> + </div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="cvs-resources"></a>Additional Resources for CVS</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> The <a class="ulink" href="http://cvs.openacs.org/" target="_top"> OpenACS cvs web browser</a> is a useful tools in understanding what is happening with the code. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> There is general information about CVS at <a class="ulink" href="http://www.nongnu.org/cvs/" target="_top"> nongnu.org </a>. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="http://web.mit.edu/gnu/doc/html/cvs_20.html" target="_top">cvs manual</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="http://cvsbook.red-bean.com/cvsbook.html" target="_top">Open Source Development with CVS, 3rd Edition</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="http://www.piskorski.com/docs/cvs-conventions.html" target="_top">Piskorski's cvs refs</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="http://openacs.org/doc/current/backups-with-cvs.html" target="_top">backup with cvs</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="http://openacs.org/forums/message-view?message_id=178551" target="_top">merging 2 file heirarchies with cvs</a> - </p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="style-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Style Guide </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Release Version Numbering</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li></ul></div> + + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="style-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Style Guide </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Release Version Numbering</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/cvs-tips.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-tips.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/cvs-tips.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/cvs-tips.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -13,35 +13,31 @@ <div class="appendix"> <div class="titlepage"><div><div><h2 class="title"> <a name="cvs-tips" id="cvs-tips"></a>Appendix D. Using CVS with -an OpenACS Site</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p> -<a name="cvs-service-import" id="cvs-service-import"></a><strong>Add the Service to CVS - -OPTIONAL. </strong><a class="indexterm" name="idp140592106625944" id="idp140592106625944"></a>These steps take -an existing OpenACS directory and add it to a <a class="link" href="install-cvs" title="Initialize CVS (OPTIONAL)">CVS -repository</a>.</p><div class="orderedlist"><ol class="orderedlist" type="1"> +an OpenACS Site</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><p> +<a name="cvs-service-import" id="cvs-service-import"></a><strong>Add the Service to CVS - OPTIONAL. </strong><a class="indexterm" name="idp140623162542472" id="idp140623162542472"></a> These steps take an existing OpenACS +directory and add it to a <a class="link" href="install-cvs" title="Initialize CVS (OPTIONAL)">CVS repository</a>.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> <p>Create and set permissions on a subdirectory in the local cvs repository.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>mkdir /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>mkdir /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[root root]#<strong class="userinput"><code> chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</span></span> /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]#<strong class="userinput"><code> chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</code></em> /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [root root]# -<span class="action"><span class="action">mkdir /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</span></span> /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</span></span> +<span class="action">mkdir /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</code></em> /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</span> </pre> </li><li class="listitem"> <p>Add the repository location to the user environment. On some systems, you may get better results with .bash_profile instead of .bashrc.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> emacs .bashrc</code></strong> -</pre><p>Put this string into <code class="computeroutput">/home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/.bashrc</code>:</p><pre class="programlisting"> +</pre><p>Put this string into <code class="computeroutput">/home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/.bashrc</code>:</p><pre class="programlisting"> export CVSROOT=/cvsroot </pre><pre class="screen"> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> @@ -53,60 +49,60 @@ <p>Import all files into cvs. In order to work on files with source control, the files must be checked out from cvs. So we will import, move aside, and then check out all of the files. In the cvs import -command, <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> refers to -the cvs repository to use; it uses the CVSROOT plus this string, -i.e. <code class="computeroutput">/cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +command, <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> refers +to the cvs repository to use; it uses the CVSROOT plus this string, +i.e. <code class="computeroutput">/cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code>. "OpenACS" is the vendor tag, and "oacs-5-9-0-final" is the release tag. These tags will be useful in upgrading and branching. -m sets the version comment.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs import -m "initial install" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS oacs-5-9-0-final</code></strong> -N <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/license.txt -N <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/readme.txt +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs import -m "initial install" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> OpenACS oacs-5-9-0-final</code></strong> +N <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/license.txt +N <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/readme.txt <span class="emphasis"><em>(many lines omitted)</em></span> -N <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/SYSTEM/flush-memoized-statement.tcl +N <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/SYSTEM/flush-memoized-statement.tcl No conflicts created by this import [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]# -<span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -cvs import -m "initial install" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS oacs-5-9-0-final -exit</span></span> +<span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +cvs import -m "initial install" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> OpenACS oacs-5-9-0-final +exit</span> </pre><p>Move the original directory to a temporary location, and check out the cvs repository in its place.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>mv /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/tmp</code></strong> -[root root]# <strong class="userinput"><code>mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>mv /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/tmp</code></strong> +[root root]# <strong class="userinput"><code>mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[root root]# <strong class="userinput"><code>chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs checkout <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs checkout <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -cvs checkout: Updating <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -U <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/license.txt +cvs checkout: Updating <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +U <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/license.txt <span class="emphasis"><em>(many lines omitted)</em></span> -U <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/SYSTEM/dbtest.tcl -U <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/SYSTEM/flush-memoized-statement.tcl +U <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/SYSTEM/dbtest.tcl +U <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/SYSTEM/flush-memoized-statement.tcl [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>exit</code></strong> logout [root root]# -<span class="action"><span class="action">mv /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/tmp -mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<span class="action">mv /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/tmp +mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cd /var/lib/aolserver -cvs checkout <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -exit</span></span> +cvs checkout <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +exit</span> </pre> </li><li class="listitem"><p>If the service starts correctly, come back and remove the temporary copy of the uploaded files.</p></li> Index: openacs-4/packages/acs-core-docs/www/cvs-tips.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-tips.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/cvs-tips.html 7 Aug 2017 23:47:49 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/cvs-tips.html 8 Nov 2017 09:42:10 -0000 1.36 @@ -1,63 +1,89 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix D. Using CVS with an OpenACS Site</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="i18n-translators.html" title="Translator's Guide"><link rel="next" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-translators.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="cvs-tips"></a>Appendix D. Using CVS with an OpenACS Site</h2></div></div></div><div class="authorblurb"><p> By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p><a name="cvs-service-import"></a><b>Add the Service to CVS - OPTIONAL. </b><a class="indexterm" name="idp140592106625944"></a>These steps take an existing OpenACS directory and add +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix D. Using CVS with an OpenACS Site</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="i18n-translators.html" title="Translator's Guide"><link rel="next" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-translators.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="cvs-tips"></a>Appendix D. Using CVS with an OpenACS Site</h2></div></div></div> + + + <span style="color: red"><authorblurb> +<p> By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + <p><a name="cvs-service-import"></a> + <b>Add the Service to CVS - OPTIONAL. </b> + <a class="indexterm" name="idp140623162542472"></a> + These steps take an existing OpenACS directory and add it to a <a class="link" href="install-cvs.html" title="Initialize CVS (OPTIONAL)">CVS - repository</a>.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Create and set permissions on a subdirectory in the local cvs repository.</p><pre class="screen">[root root]# <strong class="userinput"><code>mkdir /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[root root]#<strong class="userinput"><code> chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</span></span> /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + repository</a>. + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Create and set permissions on a subdirectory in the local cvs repository.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mkdir /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[root root]#<strong class="userinput"><code> chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</code></em> /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [root root]# -<span class="action"><span class="action">mkdir /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</span></span> /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></span></span></pre></li><li class="listitem"><p>Add the repository location to the user environment. On some systems, you may get better results with .bash_profile instead of .bashrc.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> emacs .bashrc</code></strong></pre><p>Put this string into <code class="computeroutput">/home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/.bashrc</code>:</p><pre class="programlisting">export CVSROOT=/cvsroot</pre><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> +<span class="action">mkdir /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME</code></em> /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></span></pre> + </li><li class="listitem"> + <p>Add the repository location to the user environment. On some systems, you may get better results with .bash_profile instead of .bashrc.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> emacs .bashrc</code></strong></pre> + <p>Put this string into <code class="computeroutput">/home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/.bashrc</code>:</p> + <pre class="programlisting">export CVSROOT=/cvsroot</pre> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> logout -[root root]#</pre></li><li class="listitem"><p>Import all files into cvs. In order to work on +[root root]#</pre> + </li><li class="listitem"> + <p>Import all files into cvs. In order to work on files with source control, the files must be checked out from cvs. So we will import, move aside, and then check out all of the files. In the cvs import command, - <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> + <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> refers to the cvs repository to use; it uses the CVSROOT plus this string, i.e. - <code class="computeroutput">/cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code>. + <code class="computeroutput">/cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code>. "OpenACS" is the vendor tag, and "oacs-5-9-0-final" is the release tag. These tags will be useful in upgrading and - branching. -m sets the version comment.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs import -m "initial install" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS oacs-5-9-0-final</code></strong> -N <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/license.txt -N <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/readme.txt + branching. -m sets the version comment.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs import -m "initial install" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> OpenACS oacs-5-9-0-final</code></strong> +N <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/license.txt +N <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/readme.txt <span class="emphasis"><em>(many lines omitted)</em></span> -N <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/SYSTEM/flush-memoized-statement.tcl +N <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/SYSTEM/flush-memoized-statement.tcl No conflicts created by this import [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]# -<span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -cvs import -m "initial install" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS oacs-5-9-0-final -exit</span></span></pre><p>Move the original directory to a temporary location, and check out the cvs repository in its place.</p><pre class="screen">[root root]# <strong class="userinput"><code>mv /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/tmp</code></strong> -[root root]# <strong class="userinput"><code>mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[root root]# <strong class="userinput"><code>chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +<span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +cvs import -m "initial install" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> OpenACS oacs-5-9-0-final +exit</span></pre> + <p>Move the original directory to a temporary location, and check out the cvs repository in its place.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mv /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/tmp</code></strong> +[root root]# <strong class="userinput"><code>mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[root root]# <strong class="userinput"><code>chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs checkout <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -cvs checkout: Updating <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -U <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/license.txt +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs checkout <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +cvs checkout: Updating <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +U <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/license.txt <span class="emphasis"><em>(many lines omitted)</em></span> -U <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/SYSTEM/dbtest.tcl -U <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/SYSTEM/flush-memoized-statement.tcl +U <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/SYSTEM/dbtest.tcl +U <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/SYSTEM/flush-memoized-statement.tcl [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>exit</code></strong> logout [root root]# -<span class="action"><span class="action">mv /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/tmp -mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<span class="action">mv /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/tmp +mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cd /var/lib/aolserver -cvs checkout <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -exit</span></span></pre></li><li class="listitem"><p> If the service starts correctly, come back and remove the temporary copy of the uploaded files.</p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-translators.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Translator's Guide </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Part IV. For OpenACS Platform Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +cvs checkout <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +exit</span></pre> + </li><li class="listitem"> + <p> If the service starts correctly, come back and remove the temporary copy of the uploaded files.</p> + </li></ol></div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-translators.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-plat-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Translator's Guide </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Part IV. For OpenACS Platform Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/database-management.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/database-management.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/database-management.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/database-management.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -19,11 +19,9 @@ tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum">Vacuum Postgres nightly</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div> +</div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="maint-performance" leftLabel="Prev" leftTitle="Diagnosing Performance Problems" Index: openacs-4/packages/acs-core-docs/www/database-management.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/database-management.html,v diff -u -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/database-management.html 7 Aug 2017 23:47:49 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/database-management.html 8 Nov 2017 09:42:10 -0000 1.33 @@ -1,5 +1,14 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 7. Database Management</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="maint-performance.html" title="Diagnosing Performance Problems"><link rel="next" href="remote-postgres.html" title="Running a PostgreSQL database on another server"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maint-performance.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="remote-postgres.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="database-management"></a>Chapter 7. Database Management</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="remote-postgres.html">Running a PostgreSQL database on another server</a></span></dt><dt><span class="sect1"><a href="install-openacs-delete-tablespace.html">Deleting a tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum.html">Vacuum Postgres nightly</a></span></dt></dl></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maint-performance.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="remote-postgres.html">Next</a></td></tr><tr><td width="40%" align="left">Diagnosing Performance Problems </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Running a PostgreSQL database on another server</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 7. Database Management</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="maint-performance.html" title="Diagnosing Performance Problems"><link rel="next" href="remote-postgres.html" title="Running a PostgreSQL database on another server"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maint-performance.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="remote-postgres.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="database-management"></a>Chapter 7. Database Management</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="remote-postgres.html">Running a PostgreSQL database on another server</a></span></dt><dt><span class="sect1"><a href="install-openacs-delete-tablespace.html">Deleting a tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum.html">Vacuum Postgres nightly</a></span></dt></dl></div> + + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maint-performance.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="remote-postgres.html">Next</a></td></tr><tr><td width="40%" align="left">Diagnosing Performance Problems </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Running a PostgreSQL database on another server</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/db-api-detailed.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/db-api-detailed.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="i18n-requirements" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="db-api-detailed" id="db-api-detailed"></a>Database Access API</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:jsalz\@mit.edu" target="_top">Jon Salz</a>. Revised and expanded by Roberto Mello (rmello -at fslc dot usu dot edu), July 2002.</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +<a name="db-api-detailed" id="db-api-detailed"></a>Database Access API</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:jsalz\@mit.edu" target="_top">Jon Salz</a>. Revised and +expanded by Roberto Mello (rmello at fslc dot usu dot edu), July +2002.</span></p><span style="color: red"></authorblurb></span><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li><li class="listitem"><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li> </ul></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -585,13 +583,13 @@ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span> </pre><p>Performs the SQL query <code class="computeroutput">sql</code>, saving results in variables of the form <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:1</code>, <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:2</code>, etc, setting +<em class="replaceable"><code>var_name</code></em>:1</code>, <code class="computeroutput"> +<em class="replaceable"><code>var_name</code></em>:2</code>, etc, setting <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:rowcount</code> to the total -number of rows, and setting <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:columns</code> to a list of -column names.</p><p>Each row also has a column, rownum, automatically added and set +<em class="replaceable"><code>var_name</code></em>:rowcount</code> to the +total number of rows, and setting <code class="computeroutput"> +<em class="replaceable"><code>var_name</code></em>:columns</code> to a list +of column names.</p><p>Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column.</p><p>If the <code class="computeroutput">-local</code> is passed, the @@ -604,7 +602,7 @@ all the columns from the SQL query will be set as local variables in that code. Any changes made to these local variables will be copied back into the multirow.</p><p>You may also add additional, computed columns to the multirow, -using the <code class="computeroutput">-extend { <span class="replaceable"><span class="replaceable">col_1</span></span><span class="replaceable"><span class="replaceable">col_2</span></span> ... }</code> switch. This is +using the <code class="computeroutput">-extend { <em class="replaceable"><code>col_1</code></em><em class="replaceable"><code>col_2</code></em> ... }</code> switch. This is useful for things like constructing a URL for the object retrieved by the query.</p><p>If you're constructing your multirow through multiple queries with the same set of columns, but with different rows, you @@ -703,8 +701,8 @@ script and should never be referenced directly by user code. Returns the current rdbms type and version.</p> </dd> -</dl></div><div class="cvstag">($‌Id: db-api.xml,v 1.11.2.3 2017/04/21 15:07:53 -gustafn Exp $)</div> +</dl></div><p><span class="cvstag">($‌Id: db-api.xml,v 1.12 2017/08/07 23:47:55 +gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/db-api-detailed.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api-detailed.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/db-api-detailed.html 7 Aug 2017 23:47:49 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/db-api-detailed.html 8 Nov 2017 09:42:10 -0000 1.50 @@ -1,14 +1,29 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Database Access API</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="apm-design.html" title="Package Manager Design"><link rel="next" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-api-detailed"></a>Database Access API</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>. Revised and expanded by Roberto Mello (rmello at fslc dot usu dot edu), July 2002. </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li><li class="listitem"><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-bigpicture"></a>The Big Picture</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Database Access API</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="apm-design.html" title="Package Manager Design"><link rel="next" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-api-detailed"></a>Database Access API</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a>. Revised and expanded by Roberto Mello (rmello at fslc dot usu dot edu), July 2002. </p> +</authorblurb></span> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl procedures: /packages/acs-kernel/10-database-procs.tcl</p></li><li class="listitem"><p>Tcl initialization: /packages/acs-kernel/database-init.tcl</p></li></ul></div> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-bigpicture"></a>The Big Picture</h3></div></div></div> + + +<p> One of OpenACS's great strengths is that code written for it is very close to the database. It is very easy to interact with the database from anywhere within OpenACS. Our goal is to develop a coherent API for database access which makes this even easier. -</p><p>There were four significant problems with the way OpenACS previously used the -database (i.e., directly through the <code class="computeroutput">ns_db</code> interface):</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>Handle management</strong></span>. We required code to pass database +</p> + +<p>There were four significant problems with the way OpenACS previously used the +database (i.e., directly through the <code class="computeroutput">ns_db</code> interface):</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="strong"><strong>Handle management</strong></span>. We required code to pass database handles around, and for routines which needed to perform database access but didn't receive a database handle as input, it was difficult to know from which of the three "magic pools" (main, subquery, and log) to @@ -20,8 +35,12 @@ <code class="computeroutput">end transaction</code> means "commit the current transaction and turn auto-commit mode on." Thus if transactional code needed to call a routine which needed to operate transactionally, the semantics were -non-obvious. Consider: </p><pre class="programlisting"> +non-obvious. Consider: </p> + + +<pre class="programlisting"> + proc foo { db args } { db_transaction { ... @@ -34,7 +53,10 @@ db_dml unused {insert into greeble(bork) values(50)} } -</pre><p> +</pre> + + +<p> This would insert greeble #33 and do all the stuff in <code class="computeroutput">foo</code> transactionally, but the <code class="computeroutput">end transaction</code> in <code class="computeroutput">foo</code> would actually cause a commit, and greeble #50 would later be inserted in @@ -54,81 +76,129 @@ write code supporting various different databases (dynamically using the appropriate dialect based on the type of database being used, e.g., using <code class="computeroutput">DECODE</code> on Oracle and <code class="computeroutput">CASE ... WHEN</code> on -Postgres).</p></li></ol></div><p> +Postgres).</p></li></ol></div> + +<p> The Database Access API addresses the first three problems by: -</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>making use of database handles transparent</p></li><li class="listitem"><p>wrapping common database operations (including transaction management) in -Tcl control structures (this is, after all, what Tcl is good at!)</p></li></ol></div><p> +</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>making use of database handles transparent</p></li><li class="listitem"><p>wrapping common database operations (including transaction management) in +Tcl control structures (this is, after all, what Tcl is good at!)</p></li></ol></div> + +<p> It lays the groundwork for addressing the fourth problem by assigning each SQL statement a logical name. In a future version of the OpenACS Core, this API will translate logical statement names into actual SQL, based on the type of database in use. (To smooth the learning curve, we provide a facility for writing SQL inline for a "default SQL dialect", which we assume to be Oracle for now.) -</p><p>To be clear, SQL abstraction is <span class="emphasis"><em>not</em></span> fully implemented in OpenACS +</p> + +<p>To be clear, SQL abstraction is <span class="emphasis"><em>not</em></span> fully implemented in OpenACS 3.3.1. The statement names supplied to each call are not used by the API at all. The API's design for SQL abstraction is in fact incomplete; -unresolved issues include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>how to add <code class="computeroutput">WHERE</code> clause criteria dynamically</p></li><li class="listitem"><p>how to build a dynamic <code class="computeroutput">ORDER BY</code> clause (Ben Adida has a +unresolved issues include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>how to add <code class="computeroutput">WHERE</code> clause criteria dynamically</p></li><li class="listitem"><p>how to build a dynamic <code class="computeroutput">ORDER BY</code> clause (Ben Adida has a proposed solution for this)</p></li><li class="listitem"><p>how to define a statement's formal interface (i.e., what bind variables it expects, what columns its <code class="computeroutput">SELECT</code> clause must contain if it's a query) without actually implementing the statement in a -specific SQL dialect</p></li></ul></div><p> +specific SQL dialect</p></li></ul></div> + +<p> So why is the incremental change of adding statement naming to the API worth the effort? It is worth the effort because we know that giving each SQL statement a logical name will be required by the complete SQL abstraction design. Therefore, we know that the effort will not be wasted, and taking advantage of the new support for bind variables will already require code that uses 3.3.0 version of the API to be updated. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-set-var-aft-query"></a>The Bell Tolls for <code class="computeroutput">set_variables_after_query</code></h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-set-var-aft-query"></a>The Bell Tolls for <code class="computeroutput">set_variables_after_query</code></h3></div></div></div> + + + +<p> <code class="computeroutput">set_variables_after_query</code> is gone! (Well, it's still there, but you'll never need to use it.) The new API routines set local variables automatically. For instance: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + db_1row select_names "select first_names, last_name from users where user_id = [ad_conn user_id]" doc_body_append "Hello, $first_names $last_name!" -</pre><p> +</pre> + +<p> Like <code class="computeroutput">ns_db 1row</code>, this will bomb if the query doesn't return any rows (no such user exists). If this isn't what you want, you can write: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + if { [db_0or1row select_names "select first_names, last_name from users where user_id = [ad_conn user_id]"] } { doc_body_append "Hello, $first_names $last_name!" } else { # Executed if the query returns no rows. doc_body_append "There's no such user!" } -</pre><p> +</pre> + + +<p> Selecting a bunch of rows is a lot prettier now: - </p><pre class="programlisting"> + </p> +<pre class="programlisting"> + db_foreach select_names "select first_names, last_name from users" { doc_body_append "Say hi to $first_names $last_name for me!<br>" } -</pre><p> +</pre> + +<p> That's right, <code class="computeroutput">db_foreach</code> is now like <code class="computeroutput">ns_db select</code> plus a <code class="computeroutput">while</code> loop plus <code class="computeroutput">set_variables_after_query</code> plus an <code class="computeroutput">if</code> statement (containing code to be executed if no rows are returned). - </p><pre class="programlisting"> + </p> +<pre class="programlisting"> + db_foreach select_names "select first_names, last_name from users where last_name like 'S%'" { doc_body_append "Say hi to $first_names $last_name for me!<br>" } if_no_rows { doc_body_append "There aren't any users with last names beginnings with S!" } -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-handles"></a>Handle Management</h3></div></div></div><p> +</pre> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-handles"></a>Handle Management</h3></div></div></div> + + +<p> The new API keeps track of which handles are in use, and automatically allocates new handles when they are necessary (e.g., to perform subqueries while a select is active). For example: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + doc_body_append "<ul>" db_foreach select_names "select first_names, last_name, user_id from users" { # Automatically allocated a database handle from the main pool. @@ -146,79 +216,132 @@ doc_body_append "</ul>" db_release_unused_handles -</pre><p> +</pre> + +<p> A new handle isn't actually allocated and released for every selection, of course - as a performance optimization, the API keeps old handles around until <code class="computeroutput">db_release_unused_handles</code> is invoked (or the script terminates). -</p><p>Note that there is no analogue to <code class="computeroutput">ns_db gethandle</code> - the -handle is always automatically allocated the first time it's needed.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-bindvars"></a>Bind Variables</h3></div></div></div><p><span class="strong"><strong>Introduction</strong></span></p><p> +</p> + +<p>Note that there is no analogue to <code class="computeroutput">ns_db gethandle</code> - the +handle is always automatically allocated the first time it's needed.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-bindvars"></a>Bind Variables</h3></div></div></div> + + + +<p><span class="strong"><strong>Introduction</strong></span></p> + +<p> Most SQL statements require that the code invoking the statement pass along data associated with that statement, usually obtained from the user. For instance, in order to delete a WimpyPoint presentation, a Tcl script might use the SQL statement -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + delete from wp_presentations where presentation_id = <span class="emphasis"><em>some_presentation_id</em></span> -</pre><p> +</pre> + +<p> where <span class="emphasis"><em><code class="computeroutput">some_presentation_id</code></em></span> is a number which is a valid presentation ID of the presentation I want to delete. It's easy to write code handling situations like this since SQL statements can include <span class="strong"><strong>bind variables</strong></span>, which represent placeholders for actual data. A bind variable is specified as a colon followed by an identifier, so the statement above can be coded as: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + db_dml presentation_delete { delete from wp_presentations where presentation_id = :some_presentation_id } -</pre><p> +</pre> + + +<p> When this SQL statement is invoked, the value for the bind variable <code class="computeroutput">:some_presentation_id</code> is pulled from the Tcl variable <code class="computeroutput">$some_presentation_id</code> (in the caller's environment). Note that bind variables are not limited to one per statement; you can use an arbitrary number, and each will pull from the correspondingly named Tcl variable. (Alternatively, you can also specify an list or <code class="computeroutput">ns_set</code> providing bind variables' values; see <span class="emphasis"><em>Usage</em></span>.) -</p><p>The value of a bind variable is taken literally by the database driver, so +</p> + +<p>The value of a bind variable is taken literally by the database driver, so there is never any need to put single-quotes around the value for a bind variable, or to use <code class="computeroutput">db_quote</code> to escape single-quotes contained -in the value. The following works fine, despite the apostrophe:</p><pre class="programlisting"> +in the value. The following works fine, despite the apostrophe:</p> + + +<pre class="programlisting"> + set exclamation "That's all, folks!" db_dml exclamation_insert { insert into exclamations(exclamation) values(:exclamation) } -</pre><p>Note that you can use a bind variable in a SQL statement only where you +</pre> + + +<p>Note that you can use a bind variable in a SQL statement only where you could use a literal (a number or single-quoted string). Bind variables cannot be placeholders for things like SQL keywords, table names, or column names, so the following will not work, even if <code class="computeroutput">$table_name</code> is set -properly:</p><pre class="programlisting"> +properly:</p> + + +<pre class="programlisting"> + select * from :table_name -</pre><p><span class="strong"><strong>Why Bind Variables Are Useful</strong></span></p><p> +</pre> + + +<p><span class="strong"><strong>Why Bind Variables Are Useful</strong></span></p> + +<p> Why bother with bind variables at all - why not just write the Tcl statement above like this: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + db_dml presentation_delete " delete from wp_presentations where presentation_id = $some_presentation_id " -</pre><p> +</pre> + +<p> (Note the use of double-quotes to allow the variable reference to <code class="computeroutput">$some_presentation_id</code> to be interpolated in.) This will work, but consider the case where some devious user causes <code class="computeroutput">some_presentation_id</code> to be set to something like <code class="computeroutput">'3 or 1 = 1'</code>, which would result in the following statement being executed: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + delete from wp_presentations where presentation_id = 3 or 1 = 1 -</pre><p> +</pre> + +<p> This deletes every presentation in the database! Using bind variables eliminates this gaping security hole: since bind variable values are taken literally. Oracle will attempt to delete presentations whose presentation ID @@ -228,16 +351,27 @@ always considers the values of bind variables to be literals, it becomes more difficult for users to perform URL surgery to trick scripts into running dangerous queries and DML. -</p><p><span class="strong"><strong>Usage</strong></span></p><p>Every <code class="computeroutput">db_*</code> command accepting a SQL command as an argument -supports bind variables. You can either</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>specify the <code class="computeroutput">-bind</code> switch to provide a set with bind variable +</p> + +<p><span class="strong"><strong>Usage</strong></span></p> + +<p>Every <code class="computeroutput">db_*</code> command accepting a SQL command as an argument +supports bind variables. You can either</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>specify the <code class="computeroutput">-bind</code> switch to provide a set with bind variable values, or</p></li><li class="listitem"><p>specify the <code class="computeroutput">-bind</code> switch to explicitly provide a list of bind variable names and values, or</p></li><li class="listitem"><p>not specify a bind variable list at all, in which case Tcl variables are -used as bind variables.</p></li></ul></div><p> +used as bind variables.</p></li></ul></div> + +<p> The default behavior (i.e., if the <code class="computeroutput">-bind</code> switch is omitted) is that these procedures expect to find local variables that correspond in name to the referenced bind variables, e.g.: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + set user_id 123456 set role "administrator" @@ -252,12 +386,20 @@ # of "administrator" } -</pre><p> +</pre> + +<p> The value of the local Tcl variable <code class="computeroutput">user_id</code> (123456) is bound to the <code class="computeroutput">user_id</code> bind variable. -</p><p>The <code class="computeroutput">-bind</code> switch can takes the name of an <code class="computeroutput">ns_set</code> -containing keys for each bind variable named in the query, e.g.:</p><pre class="programlisting"> +</p> +<p>The <code class="computeroutput">-bind</code> switch can takes the name of an <code class="computeroutput">ns_set</code> +containing keys for each bind variable named in the query, e.g.:</p> + + + +<pre class="programlisting"> + set bind_vars [ns_set create] ns_set put $bind_vars user_id 123456 ns_set put $bind_vars role "administrator" @@ -273,11 +415,16 @@ # of "administrator" } -</pre><p> +</pre> + +<p> Alternatively, as an argument to <code class="computeroutput">-bind</code> you can specify a list of alternating name/value pairs for bind variables: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + db_foreach user_group_memberships_by_role { select g.group_id, g.group_name from user_groups g, user_group_map map @@ -289,19 +436,32 @@ # of "administrator" } -</pre><p><span class="strong"><strong><a name="kernel.dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</strong></span></p><p> +</pre> + + +<p><span class="strong"><strong><a name="kernel.dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</strong></span></p> + +<p> When processing a DML statement, Oracle coerces empty strings into <code class="computeroutput">null</code>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the <code class="computeroutput">WHERE</code> clause of a query, i.e. <code class="computeroutput">col = ''</code> and <code class="computeroutput">col is null</code> are not equivalent.) -</p><p>As a result, when using bind variables, the only way to make Oracle set a +</p> + +<p>As a result, when using bind variables, the only way to make Oracle set a column value to <code class="computeroutput">null</code> is to set the corresponding bind variable to the empty string, since a bind variable whose value is the string "null" will be interpreted as the literal string -"null".</p><p>These Oracle quirks complicate the process of writing clear and abstract -DML difficult. Here is an example that illustrates why:</p><pre class="programlisting"> +"null".</p> +<p>These Oracle quirks complicate the process of writing clear and abstract +DML difficult. Here is an example that illustrates why:</p> + + + +<pre class="programlisting"> + # # Given the table: # @@ -320,40 +480,71 @@ # null, because Oracle has coerced the empty string (even for the # numeric column "bar") into null in both cases -</pre><p> +</pre> + +<p> Since databases other than Oracle do not coerce empty strings into <code class="computeroutput">null</code>, this code has different semantics depending on the underlying database (i.e., the row that gets inserted may not have null as its column values), which defeats the purpose of SQL abstraction. -</p><p>Therefore, the Database Access API provides a database-independent way to +</p> + +<p>Therefore, the Database Access API provides a database-independent way to represent <code class="computeroutput">null</code> (instead of the Oracle-specific idiom of the -empty string): <span class="strong"><strong><code class="computeroutput">db_null</code></strong></span>.</p><p>Use it instead of the empty string whenever you want to set a column value -explicitly to <code class="computeroutput">null</code>, e.g.:</p><pre class="programlisting"> +empty string): <span class="strong"><strong><code class="computeroutput">db_null</code></strong></span>.</p> +<p>Use it instead of the empty string whenever you want to set a column value +explicitly to <code class="computeroutput">null</code>, e.g.:</p> + + + +<pre class="programlisting"> + set bar [db_null] set baz [db_null] db_dml foo_create {insert into foo(bar, baz) values(:bar, :baz)} # # sets the values for both the "bar" and "baz" columns to null -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-sql-abstraction"></a>SQL Abstraction</h3></div></div></div><p> +</pre> + + + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-sql-abstraction"></a>SQL Abstraction</h3></div></div></div> + + +<p> We now require that each SQL statement be assigned a logical name for the statement that is unique to the procedure or page in which it is defined. This is so that (eventually) we can implement logically named statements with alternative SQL for non-Oracle databases (e.g., Postgres). More on this later. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-placing-values"></a>Placing Column Values in Arrays and Sets</h3></div></div></div><p> +</p> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-detailed-placing-values"></a>Placing Column Values in Arrays and Sets</h3></div></div></div> + + +<p> Normally, <code class="computeroutput">db_foreach</code>, <code class="computeroutput">db_0or1row</code>, and <code class="computeroutput">db_1row</code> places the results of queries in Tcl variables, so you can say: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + db_foreach users_select "select first_names, last_name from users" { doc_body_append "<li>$first_names $last_name\n" } -</pre><p> +</pre> + +<p> However, sometimes this is not sufficient: you may need to examine the rows returned, to dynamically determine the set of columns returned by the query, or to avoid collisions with existing variables. You can use the @@ -362,8 +553,11 @@ instruct the database routines to place the results in a Tcl array or <code class="computeroutput">ns_set</code>, respectively, where the keys are the column names and the values are the column values. For example: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + db_foreach users_select "select first_names, last_name from users" -column_set columns { # Now $columns is an ns_set. doc_body_append "<li>" @@ -372,112 +566,187 @@ } } -</pre><p> +</pre> + +<p> will write something like: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>first_names is Jon. last_name is Salz.</p></li><li class="listitem"><p>first_names is Lars. last_name is Pind.</p></li><li class="listitem"><p>first_names is Michael. last_name is Yoon.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dp-api-detailed-api"></a>API</h3></div></div></div><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>first_names is Jon. last_name is Salz.</p></li><li class="listitem"><p>first_names is Lars. last_name is Pind.</p></li><li class="listitem"><p>first_names is Michael. last_name is Yoon.</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dp-api-detailed-api"></a>API</h3></div></div></div> + + +<p> Note that you never have to use <code class="computeroutput">ns_db</code> anymore (including <code class="computeroutput">ns_db gethandle</code>)! Just start doing stuff, and (if you want) call <code class="computeroutput">db_release_unused_handles</code> when you're done as a hint to release the database handle. -</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_null"></a>db_null</code></strong></span> +</p> -</span></dt><dd><pre class="programlisting"> +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_null"></a>db_null</code></strong></span> + +</span></dt><dd> + +<pre class="programlisting"> <span class="strong"><strong><code class="computeroutput">db_null</code></strong></span> -</pre><p>Returns a value which can be used in a bind variable to represent the SQL +</pre> + +<p>Returns a value which can be used in a bind variable to represent the SQL value <code class="computeroutput">null</code>. See <a class="link" href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and Bind Variables</a> above.</p></dd><dt><span class="term"> <span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_foreach"></a>db_foreach</code></strong></span> -</span></dt><dd><pre class="programlisting"> +</span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_foreach</strong></span> <span class="emphasis"><em>statement-name sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] \ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span> -</pre><p>Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>, executing +</pre> + +<p>Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>, executing <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span> once for each row with variables set to column values (or a set or array populated if <code class="computeroutput">-column_array</code> or <code class="computeroutput">column_set</code> is specified). If the query returns no rows, executes -<span class="emphasis"><em><code class="computeroutput">if_no_rows_block</code></em></span> (if provided). </p><p>Example:</p><pre class="programlisting"> +<span class="emphasis"><em><code class="computeroutput">if_no_rows_block</code></em></span> (if provided). </p> +<p>Example:</p> + + + +<pre class="programlisting"> + db_foreach select_foo "select foo, bar from greeble" { doc_body_append "<li>foo=$foo; bar=$bar\n" } if_no_rows { doc_body_append "<li>There are no greebles in the database.\n" } -</pre><p> +</pre> + +<p> The code block may contain <code class="computeroutput">break</code> statements (which terminate the loop and flush the database handle) and <code class="computeroutput">continue</code> statements -(which continue to the next row of the loop). </p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_1row"></a>db_1row</code></strong></span></span></dt><dd><pre class="programlisting"> +(which continue to the next row of the loop). </p> + +</dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_1row"></a>db_1row</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_1row</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] -</pre><p>Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>, setting variables to -column values. Raises an error if the query does not return exactly 1 row. </p><p>Example:</p><pre class="programlisting"> +</pre> +<p>Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>, setting variables to +column values. Raises an error if the query does not return exactly 1 row. </p> + +<p>Example:</p> + + + +<pre class="programlisting"> + db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id" # Bombs if there's no such greeble! # Now $foo and $bar are set. -</pre></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_0or1row"></a>db_0or1row</code></strong></span> </span></dt><dd><pre class="programlisting"> +</pre> + +</dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_0or1row"></a>db_0or1row</code></strong></span> </span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_0or1row</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] -</pre><p>Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If a row is returned, +</pre> + +<p>Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If a row is returned, sets variables to column values and returns 1. If no rows are returned, -returns 0. If more than one row is returned, throws an error. </p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_string"></a>db_string</code></strong></span> </span></dt><dd><pre class="programlisting"> +returns 0. If more than one row is returned, throws an error. </p> + +</dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_string"></a>db_string</code></strong></span> </span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_string</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -default <span class="emphasis"><em>default</em></span> ] [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] -</pre><p>Returns the first column of the result of SQL query +</pre> + +<p>Returns the first column of the result of SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If <span class="emphasis"><em><code class="computeroutput">sql</code></em></span> doesn't return a row, returns <span class="emphasis"><em><code class="computeroutput">default</code></em></span> (or throws an error if <span class="emphasis"><em><code class="computeroutput">default</code></em></span> is unspecified). Analogous to <code class="computeroutput">database_to_tcl_string</code> and <code class="computeroutput">database_to_tcl_string_or_null</code>. -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_nextval"></a>db_nextval</code></strong></span> </span></dt><dd><pre class="programlisting"> +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_nextval"></a>db_nextval</code></strong></span> </span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_nextval</strong></span> <span class="emphasis"><em>sequence-name</em></span> -</pre><p>Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a +</pre> + +<p>Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a SQL statement like <code class="computeroutput">SELECT</code> <span class="emphasis"><em><code class="computeroutput">sequence-name</code></em></span><code class="computeroutput">.nextval FROM DUAL</code>). If sequence pooling is enabled for the sequence, transparently uses a value from the pool if available to save a round-trip to the database. -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_list"></a>db_list</code></strong></span></span></dt><dd><pre class="programlisting"> +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_list"></a>db_list</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_list</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] -</pre><p>Returns a Tcl list of the values in the first column of the result of SQL +</pre> + +<p>Returns a Tcl list of the values in the first column of the result of SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If <span class="emphasis"><em><code class="computeroutput">sql</code></em></span> doesn't return any rows, returns an empty list. Analogous to <code class="computeroutput">database_to_tcl_list</code>. -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_list_of_lists"></a>db_list_of_lists</code></strong></span></span></dt><dd><pre class="programlisting"> +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_list_of_lists"></a>db_list_of_lists</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_list_of_lists</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] -</pre><p>Returns a Tcl list, each element of which is a list of all column values +</pre> + +<p>Returns a Tcl list, each element of which is a list of all column values in a row of the result of SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If <span class="emphasis"><em><code class="computeroutput">sql</code></em></span> doesn't return any rows, returns an empty list. (Analogous to <code class="computeroutput">database_to_tcl_list_list</code>.) -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_list_of_ns_sets"></a>db_list_of_ns_sets</code></strong></span></span></dt><dd><pre class="programlisting"> +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_list_of_ns_sets"></a>db_list_of_ns_sets</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_list_of_ns_sets</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] -</pre><p> +</pre> + <p> Returns a list of ns_sets with the values of each column of each row returned by the <code class="computeroutput">sql</code> query specified. - </p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_dml"></a>db_dml</code></strong></span></span></dt><dd><pre class="programlisting"> + </p> + </dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_dml"></a>db_dml</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_dml</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \ [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -blobs <span class="emphasis"><em>blob_list</em></span> | -clobs <span class="emphasis"><em>clob_list</em></span> | -blob_files <span class="emphasis"><em>blob_file_list</em></span> | -clob_files <span class="emphasis"><em>clob_file_list</em></span> ] -</pre><p>Performs the DML or DDL statement <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL +</pre> + +<p>Performs the DML or DDL statement <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. </p> + +<p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL should return <span class="emphasis"><em>n</em></span> blobs or clobs into the bind variables <code class="computeroutput">:1</code>, <code class="computeroutput">:2</code>, ... :<span class="emphasis"><em><code class="computeroutput">n</code></em></span>. <span class="emphasis"><em><code class="computeroutput">blobs</code></em></span> or <span class="emphasis"><em><code class="computeroutput">clobs</code></em></span>, if specified, should be a list of individual BLOBs or CLOBs to insert; <span class="emphasis"><em><code class="computeroutput">blob_files</code></em></span> or <span class="emphasis"><em><code class="computeroutput">clob_files</code></em></span>, if specified, should be a list of <span class="emphasis"><em>paths to files</em></span> containing the data to insert. Only one of <code class="computeroutput">-blobs</code>, <code class="computeroutput">-clobs</code>, -<code class="computeroutput">-blob_files</code>, and <code class="computeroutput">-clob_files</code> may be provided.</p><p>Example:</p><pre class="programlisting"> +<code class="computeroutput">-blob_files</code>, and <code class="computeroutput">-clob_files</code> may be provided.</p> +<p>Example:</p> + + + +<pre class="programlisting"> + db_dml insert_photos { insert photos(photo_id, image, thumbnail_image) values(photo_id_seq.nextval, empty_blob(), empty_blob()) returning image, thumbnail_image into :1, :2 } -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"] -</pre><p> +</pre> + + +<p> This inserts a new row into the <code class="computeroutput">photos</code> table, with the contents of the files <code class="computeroutput">/var/tmp/the_photo</code> and <code class="computeroutput">/var/tmp/the_thumbnail</code> in the <code class="computeroutput">image</code> and @@ -488,28 +757,46 @@ <span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_write_clob"></a>db_write_clob</code></strong></span>, <span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_write_blob"></a>db_write_blob</code></strong></span>, <span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_blob_get_file"></a>db_blob_get_file</code></strong></span> -</span></dt><dd><pre class="programlisting"> +</span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_write_clob</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] <span class="strong"><strong>db_write_blob</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] <span class="strong"><strong>db_blob_get_file</strong></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] -</pre><p>Analogous to <code class="computeroutput">ns_ora write_clob/write_blob/blob_get_file</code>. +</pre> +<p>Analogous to <code class="computeroutput">ns_ora write_clob/write_blob/blob_get_file</code>. -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_release_unused_handles"></a>db_release_unused_handles</code></strong></span></span></dt><dd><pre class="programlisting"> + +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_release_unused_handles"></a>db_release_unused_handles</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_release_unused_handles</strong></span> -</pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_transaction"></a>db_transaction</code></strong></span></span></dt><dd><pre class="programlisting"> +</pre> + +<p>Releases any allocated, unused database handles. </p> + +</dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_transaction"></a>db_transaction</code></strong></span></span></dt><dd> + +<pre class="programlisting"> <span class="strong"><strong>db_transaction</strong></span> <span class="emphasis"><em>code_block</em></span> [ on_error { <span class="emphasis"><em>code_block</em></span> } ] -</pre><p>Executes <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span> transactionally. Nested +</pre> + +<p>Executes <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span> transactionally. Nested transactions are supported (<code class="computeroutput">end transaction</code> is transparently <code class="computeroutput">ns_db dml</code>'ed when the outermost transaction completes). The <code class="computeroutput">db_abort_transaction</code> command can be used to abort all levels of transactions. It is possible to specify an optional <code class="computeroutput">on_error</code> code block that will be executed if some code in <span class="emphasis"><em>code_block</em></span> throws an exception. The variable <code class="computeroutput">errmsg</code> will be bound in that scope. -If there is no <code class="computeroutput">on_error</code> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting"> +If there is no <code class="computeroutput">on_error</code> code, any errors will be propagated. </p> +<p>Example:</p> + + + +<pre class="programlisting"> + proc replace_the_foo { col } { db_transaction { db_dml delete {delete from foo} @@ -537,85 +824,125 @@ print_the_foo ; # Writes out "foo is 8" -</pre></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_abort_transaction"></a>db_abort_transaction</code></strong></span> -</span></dt><dd><pre class="programlisting"> +</pre> + +</dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_abort_transaction"></a>db_abort_transaction</code></strong></span> +</span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_abort_transaction</strong></span> -</pre><p>Aborts all levels of a transaction. That is if this is called within +</pre> + +<p>Aborts all levels of a transaction. That is if this is called within several nested transactions, all of them are terminated. Use this instead of <code class="computeroutput">db_dml "abort" "abort transaction"</code>. -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_multirow"></a>db_multirow</code></strong></span></span></dt><dd><pre class="programlisting"> +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_multirow"></a>db_multirow</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_multirow</strong></span> [ -local ] [ -append ] [ -extend <span class="emphasis"><em>column_list</em></span> ] \ <span class="emphasis"><em>var-name</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \ [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span> -</pre><p> +</pre> + + <p> Performs the SQL query <code class="computeroutput">sql</code>, saving results in variables of the form - <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:1</code>, <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:2</code>, etc, - setting <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:rowcount</code> to the total number - of rows, and setting <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:columns</code> to a + <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:1</code>, <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:2</code>, etc, + setting <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:rowcount</code> to the total number + of rows, and setting <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:columns</code> to a list of column names. - </p><p> + </p> + + <p> Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column. - </p><p> + </p> + + <p> If the <code class="computeroutput">-local</code> is passed, the variables defined by db_multirow will be set locally (useful if you're compiling dynamic templates in a function or similar situations). - </p><p> + </p> + + <p> You may supply a code block, which will be executed for each row in the loop. This is very useful if you need to make computations that are better done in Tcl than in SQL, for example using ns_urlencode or ad_quotehtml, etc. When the Tcl code is executed, all the columns from the SQL query will be set as local variables in that code. Any changes made to these local variables will be copied back into the multirow. - </p><p> + </p> + + <p> You may also add additional, computed columns to the multirow, using the - <code class="computeroutput">-extend { <span class="replaceable"><span class="replaceable">col_1</span></span> <span class="replaceable"><span class="replaceable">col_2</span></span> ... }</code> switch. This is + <code class="computeroutput">-extend { <em class="replaceable"><code>col_1</code></em> <em class="replaceable"><code>col_2</code></em> ... }</code> switch. This is useful for things like constructing a URL for the object retrieved by the query. - </p><p> + </p> + + <p> If you're constructing your multirow through multiple queries with the same set of columns, but with different rows, you can use the <code class="computeroutput">-append</code> switch. This causes the rows returned by this query to be appended to the rows already in the multirow, instead of starting a clean multirow, as is the normal behavior. The columns must match the columns in the original multirow, or an error will be thrown. - </p><p> + </p> + + <p> Your code block may call <code class="computeroutput">continue</code> in order to skip a row and not include it in the multirow. Or you can call <code class="computeroutput">break</code> to skip this row and quit looping. - </p><p> + </p> + <p> + Notice the nonstandard numbering (everything else in Tcl starts at 0); the reason is that the graphics designer, a non programmer, may wish to work with row numbers. - </p><p> + </p> + + <p> Example: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> db_multirow -extend { user_url } users users_query { select user_id first_names, last_name, email from cc_users } { set user_url [acs_community_member_url -user_id $user_id] } - </pre></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_resultrows"></a>db_resultrows</code></strong></span></span></dt><dd><pre class="programlisting"> + </pre> + </dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_resultrows"></a>db_resultrows</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_resultrows</strong></span> -</pre><p>Returns the number of rows affected or returned by the previous +</pre> + + <p>Returns the number of rows affected or returned by the previous statement. -</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_with_handle"></a>db_with_handle</code></strong></span></span></dt><dd><pre class="programlisting"> +</p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="kernel.dbapi_db_with_handle"></a>db_with_handle</code></strong></span></span></dt><dd> +<pre class="programlisting"> <span class="strong"><strong>db_with_handle</strong></span> <span class="emphasis"><em>var</em></span> <span class="emphasis"><em>code_block</em></span> -</pre><p>Places a database handle into the variable <span class="emphasis"><em><code class="computeroutput">var</code></em></span> and +</pre> + + +<p>Places a database handle into the variable <span class="emphasis"><em><code class="computeroutput">var</code></em></span> and executes <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span>. This is useful when you don't want to have to use the new API (<code class="computeroutput">db_foreach</code>, -<code class="computeroutput">db_1row</code>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting"> +<code class="computeroutput">db_1row</code>, etc.), but need to use database handles explicitly. </p> +<p>Example:</p> + + + +<pre class="programlisting"> + proc lookup_the_foo { foo } { db_with_handle db { return [db_string unused "select ..."] @@ -632,100 +959,132 @@ } } -</pre></dd><dt><span class="term"> +</pre> + +</dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_name"></a>db_name </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong> <code class="computeroutput">db_name</code> </strong></span> - </pre><p> + </pre> + <p> Returns the name of the database, as returned by the driver. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_type"></a>db_type </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong> <code class="computeroutput">db_type</code> </strong></span> - </pre><p> + </pre> + <p> Returns the RDBMS type (i.e. oracle, postgresql) this OpenACS installation is using. The nsv ad_database_type is set up during the bootstrap process. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_compatible_rdbms_p"></a>db_compatible_rdbms_p </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_compatible_rdbms_p</strong></span> db_type - </pre><p> + </pre> + <p> Returns 1 if the given db_type is compatible with the current RDBMS. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_package_supports_rdbms_p"></a>db_package_supports_rdbms_p </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_package_supports_rdbms_p</strong></span> db_type_list - </pre><p> + </pre> + <p> Returns 1 if db_type_list contains the current RDMBS type. A package intended to run with a given RDBMS must note this in it's package info file regardless of whether or not it actually uses the database. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_legacy_package_p"></a>db_legacy_package_p </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_legacy_package_p</strong></span> db_type_list - </pre><p> + </pre> + <p> Returns 1 if the package is a legacy package. We can only tell for certain if it explicitly supports Oracle 8.1.6 rather than the OpenACS more general oracle. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_version"></a>db_version </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_version</strong></span> - </pre><p> + </pre> + <p> Returns the RDBMS version (i.e. 8.1.6 is a recent Oracle version; 7.1 a recent PostgreSQL version. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_current_rdbms"></a>db_current_rdbms </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_current_rdbms</strong></span> - </pre><p> + </pre> + <p> Returns the current rdbms type and version. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <span class="strong"><strong> <code class="computeroutput"> <a name="kernel.dbapi_db_known_database_types"></a>db_known_database_types </code> </strong></span> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_known_database_types</strong></span> - </pre><p> + </pre> + <p> Returns a list of three-element lists describing the database engines known to OpenACS. Each sublist contains the internal database name (used in file paths, etc), the driver name, and a "pretty name" to be used in selection forms displayed to the user. - </p><p> + </p> + <p> The nsv containing the list is initialized by the bootstrap script and should never be referenced directly by user code. Returns the current rdbms type and version. - </p></dd></dl></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Package Manager Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS Internationalization Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </dd></dl></div> + + +<p><span class="cvstag">($Id$)</span></p> +</div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="apm-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Package Manager Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> OpenACS Internationalization Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/db-api.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/db-api.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/db-api.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -290,13 +290,13 @@ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span> </pre><p>Performs the SQL query <code class="computeroutput">sql</code>, saving results in variables of the form <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:1</code>, <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:2</code>, etc, setting +<em class="replaceable"><code>var_name</code></em>:1</code>, <code class="computeroutput"> +<em class="replaceable"><code>var_name</code></em>:2</code>, etc, setting <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:rowcount</code> to the total -number of rows, and setting <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">var_name</span></span>:columns</code> to a list of -column names.</p><p>Each row also has a column, rownum, automatically added and set +<em class="replaceable"><code>var_name</code></em>:rowcount</code> to the +total number of rows, and setting <code class="computeroutput"> +<em class="replaceable"><code>var_name</code></em>:columns</code> to a list +of column names.</p><p>Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column.</p><p>If the <code class="computeroutput">-local</code> is passed, the @@ -309,7 +309,7 @@ all the columns from the SQL query will be set as local variables in that code. Any changes made to these local variables will be copied back into the multirow.</p><p>You may also add additional, computed columns to the multirow, -using the <code class="computeroutput">-extend { <span class="replaceable"><span class="replaceable">col_1</span></span><span class="replaceable"><span class="replaceable">col_2</span></span> ... }</code> switch. This is +using the <code class="computeroutput">-extend { <em class="replaceable"><code>col_1</code></em><em class="replaceable"><code>col_2</code></em> ... }</code> switch. This is useful for things like constructing a URL for the object retrieved by the query.</p><p>If you're constructing your multirow through multiple queries with the same set of columns, but with different rows, you @@ -602,8 +602,8 @@ </pre> </dd> -</dl></div><div class="cvstag">($‌Id: db-api.xml,v 1.13.8.4 2017/04/21 15:07:52 -gustafn Exp $)</div> +</dl></div><p><span class="cvstag">($‌Id: db-api.xml,v 1.14 2017/08/07 23:47:54 +gustafn Exp $)</span></p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="db-api-caching" id="db-api-caching"></a>Caching Database API Results</h3></div></div></div><p>The database API allows for direct caching of query results. Index: openacs-4/packages/acs-core-docs/www/db-api.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/db-api.html,v diff -u -r1.51 -r1.52 --- openacs-4/packages/acs-core-docs/www/db-api.html 7 Aug 2017 23:47:49 -0000 1.51 +++ openacs-4/packages/acs-core-docs/www/db-api.html 8 Nov 2017 09:42:10 -0000 1.52 @@ -1,20 +1,36 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>The OpenACS Database Access API</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="request-processor.html" title="The Request Processor"><link rel="next" href="templates.html" title="Using Templates in OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-api"></a>The OpenACS Database Access API</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>The OpenACS Database Access API</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="request-processor.html" title="The Request Processor"><link rel="next" href="templates.html" title="Using Templates in OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="db-api"></a>The OpenACS Database Access API</h2></div></div></div> + + + <p> By Pete Su and Jon Salz. Modified by Roberto Mello. - </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-overview"></a>Overview</h3></div></div></div><p> + </p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-overview"></a>Overview</h3></div></div></div> + + <p> One of OpenACS's great strengths is that code written for it is very close to the database. It is very easy to interact with the database from anywhere within OpenACS, and we have a coherent API for database access which makes this even easier. - </p><p> + </p> + + <p> More detailed information about the DB api is available at <a class="xref" href="db-api-detailed.html" title="Database Access API">Database Access API</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-examples"></a>DB API Examples</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-examples"></a>DB API Examples</h3></div></div></div> + + <p> The OpenACS database API is meant to save developers from making common mistakes and to provide a more structured syntax for specifying database operations, including transactions. Here's an example of the API. - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> set count 0 set tcl_var "foo" set sql { @@ -32,13 +48,18 @@ foreach row $rows { call_some_proc $foo $bar $baz } -}</pre><p> +}</pre> + + <p> There are several things to note here: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> No explicit code for grabbing and releasing handles. Usage of the Database API implicitly deals with all handle management issues. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The <code class="computeroutput">db_transaction</code> command makes the scope of a transaction clear; <code class="computeroutput">db_transaction</code> takes the @@ -48,35 +69,57 @@ a second db handle since the transaction is only valid for one handle (thats why we build up a list of returned values and call a second proc outside the db_foreach loop). - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The command <code class="computeroutput">db_foreach</code> writes our old while loop for us. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Every SQL query has a name, which is used in conjunction with .XQL files to support multiple databases. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Finally and most importantly, there API implements bind variables, which we will cover next. - </p></li></ol></div><p> + </p> + </li></ol></div><p> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-bindvariables"></a>Bind Variables</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-bindvariables"></a>Bind Variables</h3></div></div></div> + + <p> Bind variables are placeholders for literal values in an SQL query being sent to the server. In the old way, data was generally passed to directly to the DB backend, via Tcl string interpolation. In the example above, the query would look like: - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> select foo, bar, baz from some_table, some_other_table where some_table.id=some_other_table.id -and some_table.condition_p = '$foo'</pre><p> +and some_table.condition_p = '$foo'</pre> + + <p> There are a few problems with this: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> If the value of $foo is a huge string, then we waste a lot of time in the database server doing useless parsing. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Second, if the literal value contains characters like single quotes, we have to be careful to properly escape them, because not quoting them will lead to surprising errors. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Third, no type checking occurs on the literal value. Finally, if the Tcl variable is passed in or between web forms or otherwise subject to external modification, @@ -87,7 +130,8 @@ called <span class="emphasis"><em>SQL smuggling</em></span>, can be very damaging - entire tables can be exposed or have their contents deleted, for example. - </p><p> + </p> + <p> Another very important reason for using bind variables is performance. Oracle can cache previously parsed queries. If there are values in the where clause, that is how the query @@ -99,14 +143,19 @@ the statement are exactly the same. This will improve the query cache considerably, which can make the server much more efficient. - </p></li></ol></div><p> + </p> + </li></ol></div> + + <p> What the DB API (in conjuntion with the database drivers implemented for aolserver) do is send the SQL statement to the server for parsing, then <span class="emphasis"><em>bind</em></span> values to the variables and sends those values along separately as a second step. This separate binding step is where the term <span class="emphasis"><em>bind variable</em></span> comes from. - </p><p> + </p> + + <p> This split has several advantages. First, type checking happens on the literal. If the column we are comparing against holds numbers, and we send a string, we get a nice error. Second, @@ -117,46 +166,73 @@ variables easy to use by hooking them smoothly into the Tcl runtime so you simply provide :tclvar and the value of $tclvar is sent to the backend to actually execute the query. - </p><p> + </p> + + <p> The database API parses the query and pulls out all the bind variable specifications and replaces them with generic placeholders. It then automatically pulls the values of the named Tcl vars out of the runtime environment of the script, and passes them to the database. - </p><p> + </p> + + <p> Note that while this looks like a simple syntactic change, it really is very different from how interpolated text queries work. You use bind variables to replace what would otherwise be a literal value in a query, and Tcl style string interpolation does not happen. So you cannot do something like: - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> set table "baz" set condition "where foo = bar" db_foreach my_query { select :table from some_table where :condition } - </pre><p> + </pre> + + + <p> SQL will not allow a literal to occur where we've put the bind variables, so the query is syntactically incorrect. You have to remember that while the bind variable syntax looks similar to variable interpolation in Tcl, It is <span class="emphasis"><em>not the same thing at all</em></span>. - </p><p> + </p> + + <p> Finally, the DB API has several different styles for passing bind variable values to queries. In general, use the style presented here because it is the most convenient. - </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="db-api-bind-vars-usage"></a>Usage</h4></div></div></div><p>Every <code class="computeroutput">db_*</code> command accepting a SQL command as an argument - supports bind variables. You can either</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="db-api-bind-vars-usage"></a>Usage</h4></div></div></div> + + + <p>Every <code class="computeroutput">db_*</code> command accepting a SQL command as an argument + supports bind variables. You can either</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Specify the <code class="computeroutput">-bind</code> switch to provide a set with bind variable values, or - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Specify the <code class="computeroutput">-bind</code> switch to explicitly provide a list of bind variable names and values, or - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Not specify a bind variable list at all, in which case Tcl variables are used as bind variables. - </p></li></ul></div><p> + </p> + </li></ul></div> + + <p> The default behavior (i.e., if the <code class="computeroutput">-bind</code> switch is omitted) is that these procedures expect to find local variables that correspond in name to the referenced bind variables, e.g.: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> set user_id 123456 set role "administrator" @@ -172,12 +248,18 @@ # of "administrator" } - </pre><p> + </pre> + + <p> The value of the local Tcl variable <code class="computeroutput">user_id</code> (123456) is bound to the <code class="computeroutput">user_id</code> bind variable. - </p><p>The <code class="computeroutput">-bind</code> switch can takes the name of an <code class="computeroutput">ns_set</code> - containing keys for each bind variable named in the query, e.g.:</p><pre class="programlisting"> + </p> + <p>The <code class="computeroutput">-bind</code> switch can takes the name of an <code class="computeroutput">ns_set</code> + containing keys for each bind variable named in the query, e.g.:</p> + + <pre class="programlisting"> + set bind_vars [ns_set create] ns_set put $bind_vars user_id 123456 ns_set put $bind_vars role "administrator" @@ -193,10 +275,14 @@ # of "administrator" } - </pre><p> + </pre> + + <p> Alternatively, as an argument to <code class="computeroutput">-bind</code> you can specify a list of alternating name/value pairs for bind variables: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> db_foreach user_group_memberships_by_role { select g.group_id, g.group_name @@ -209,19 +295,31 @@ # of "administrator" } - </pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</h4></div></div></div><p> + </pre> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="dbapi_nulls_and_bind_vars"></a>Nulls and Bind Variables</h4></div></div></div> + + + <p> When processing a DML statement, Oracle coerces empty strings into <code class="computeroutput">null</code>. (This coercion does <span class="emphasis"><em>not</em></span> occur in the <code class="computeroutput">WHERE</code> clause of a query, i.e. <code class="computeroutput">col = ''</code> and <code class="computeroutput">col is null</code> are not equivalent.) - </p><p>As a result, when using bind variables, the only way to make Oracle set a + </p> + + <p>As a result, when using bind variables, the only way to make Oracle set a column value to <code class="computeroutput">null</code> is to set the corresponding bind variable to the empty string, since a bind variable whose value is the string "null" will be interpreted as the literal string - "null".</p><p>These Oracle quirks complicate the process of writing clear and abstract - DML difficult. Here is an example that illustrates why:</p><pre class="programlisting"> + "null".</p> + <p>These Oracle quirks complicate the process of writing clear and abstract + DML difficult. Here is an example that illustrates why:</p> + + <pre class="programlisting"> + # # Given the table: # @@ -240,20 +338,36 @@ # null, because Oracle has coerced the empty string (even for the # numeric column "bar") into null in both cases - </pre><p> + </pre> + + <p> Since databases other than Oracle do not coerce empty strings into <code class="computeroutput">null</code>, this code has different semantics depending on the underlying database (i.e., the row that gets inserted may not have null as its column values), which defeats the purpose of SQL abstraction. - </p><p>Therefore, the Database Access API provides a database-independent way to + </p> + + <p>Therefore, the Database Access API provides a database-independent way to represent <code class="computeroutput">null</code> (instead of the Oracle-specific idiom of the - empty string): <code class="computeroutput">db_null</code>.</p><p>Use it instead of the empty string whenever you want to set a column value - explicitly to <code class="computeroutput">null</code>, e.g.:</p><pre class="programlisting">set bar [db_null] + empty string): <code class="computeroutput">db_null</code>.</p> + + <p>Use it instead of the empty string whenever you want to set a column value + explicitly to <code class="computeroutput">null</code>, e.g.:</p> + + <pre class="programlisting">set bar [db_null] set baz [db_null] db_dml foo_create "insert into foo(bar, baz) values(:bar, :baz)" # -# sets the values for both the "bar" and "baz" columns to null</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-pooling"></a>Sequence Pooling</h3></div></div></div><p> +# sets the values for both the "bar" and "baz" columns to null</pre> + </div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-pooling"></a>Sequence Pooling</h3></div></div></div> + + + <p> The database library can transparently maintain pools of sequence values, so that each request for a new sequence value (using <code class="computeroutput">db_nextval</code>) does not incur a roundtrip to the server. For instance, this functionality is @@ -262,19 +376,27 @@ functionality for a particular sequence, register the sequence to be pooled, either using the <code class="computeroutput">db_register_pooled_sequence</code> procedure at server startup time, or by including a configuration parameter of the form - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> PoolSequence.<span class="emphasis"><em>sequence_name_seq</em></span>=<span class="emphasis"><em>count</em></span> - </pre><p> + </pre> + + <p> in <span class="emphasis"><em>any</em></span> configuration section in the <code class="computeroutput">yourservername.ini</code> file, e.g., - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [ns/server/<span class="emphasis"><em>yourservername</em></span>/acs/security] PoolSequence.sec_id_seq=20 - </pre><p> + </pre> + + <p> The database library will allocate this number of sequence values at server startup. It will periodically scan pools and allocate new values for sequences which are less than half-full. (This normally occurs every 60 @@ -284,88 +406,129 @@ <span class="emphasis"><em><code class="computeroutput">yourservername</code></em></span> <code class="computeroutput">/acs/database]</code> configuration section.) - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-basicapi"></a>Basic API</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-basicapi"></a>Basic API</h3></div></div></div> + + <p> The Database API has several functions that wrap familiar parts of the AOLserver database API. - </p><p> + </p> + + <p> Note that you never have to use <code class="computeroutput">ns_db</code> anymore (including <code class="computeroutput">ns_db gethandle</code>)! Just start doing stuff, and (if you want) call <code class="computeroutput">db_release_unused_handles</code> when you're done as a hint to release the database handle. - </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> + </p> + + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_abort_transaction"></a>db_abort_transaction </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_abort_transaction - </pre><p>Aborts all levels of a transaction. That is if this is called within + </pre> + + <p>Aborts all levels of a transaction. That is if this is called within several nested transactions, all of them are terminated. Use this instead of <code class="computeroutput">db_dml "abort" "abort transaction"</code>. - </p></dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="devguide.dbapi_db_multirow"></a>db_multirow</code></strong></span></span></dt><dd><pre class="programlisting"> + </p> + </dd><dt><span class="term"><span class="strong"><strong><code class="computeroutput"><a name="devguide.dbapi_db_multirow"></a>db_multirow</code></strong></span></span></dt><dd> + <pre class="programlisting"> <span class="strong"><strong>db_multirow</strong></span> [ -local ] [ -append ] [ -extend <span class="emphasis"><em>column_list</em></span> ] \ <span class="emphasis"><em>var-name</em></span> <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \ [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span> - </pre><p> + </pre> + + <p> Performs the SQL query <code class="computeroutput">sql</code>, saving results in variables of the form - <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:1</code>, <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:2</code>, etc, - setting <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:rowcount</code> to the total number - of rows, and setting <code class="computeroutput"><span class="replaceable"><span class="replaceable">var_name</span></span>:columns</code> to a + <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:1</code>, <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:2</code>, etc, + setting <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:rowcount</code> to the total number + of rows, and setting <code class="computeroutput"><em class="replaceable"><code>var_name</code></em>:columns</code> to a list of column names. - </p><p> + </p> + + <p> Each row also has a column, rownum, automatically added and set to the row number, starting with 1. Note that this will override any column in the SQL statement named 'rownum', also if you're using the Oracle rownum pseudo-column. - </p><p> + </p> + + <p> If the <code class="computeroutput">-local</code> is passed, the variables defined by db_multirow will be set locally (useful if you're compiling dynamic templates in a function or similar situations). - </p><p> + </p> + + <p> You may supply a code block, which will be executed for each row in the loop. This is very useful if you need to make computations that are better done in Tcl than in SQL, for example using ns_urlencode or ad_quotehtml, etc. When the Tcl code is executed, all the columns from the SQL query will be set as local variables in that code. Any changes made to these local variables will be copied back into the multirow. - </p><p> + </p> + + <p> You may also add additional, computed columns to the multirow, using the - <code class="computeroutput">-extend { <span class="replaceable"><span class="replaceable">col_1</span></span> <span class="replaceable"><span class="replaceable">col_2</span></span> ... }</code> switch. This is + <code class="computeroutput">-extend { <em class="replaceable"><code>col_1</code></em> <em class="replaceable"><code>col_2</code></em> ... }</code> switch. This is useful for things like constructing a URL for the object retrieved by the query. - </p><p> + </p> + + <p> If you're constructing your multirow through multiple queries with the same set of columns, but with different rows, you can use the <code class="computeroutput">-append</code> switch. This causes the rows returned by this query to be appended to the rows already in the multirow, instead of starting a clean multirow, as is the normal behavior. The columns must match the columns in the original multirow, or an error will be thrown. - </p><p> + </p> + + <p> Your code block may call <code class="computeroutput">continue</code> in order to skip a row and not include it in the multirow. Or you can call <code class="computeroutput">break</code> to skip this row and quit looping. - </p><p> + </p> + + <p> Notice the nonstandard numbering (everything else in Tcl starts at 0); the reason is that the graphics designer, a non programmer, may wish to work with row numbers. - </p><p> + </p> + + <p> Example: - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> db_multirow -extend { user_url } users users_query { select user_id first_names, last_name, email from cc_users } { set user_url [acs_community_member_url -user_id $user_id] } - </pre><p> + </pre> + + <p> You can also iterate over a multirow after it has been created - check the documentation for - template::multirow</p><p> + template::multirow</p> + + <p> For example, - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> db_multirow assets assets { select asset_id, from ... @@ -377,33 +540,44 @@ multirow foreach assets { lappend asset_id_l $asset_id } - </pre><p>Technically it's equivalent to using a code block on - the end of your db_multirow.</p></dd><dt><span class="term"> + </pre> + + <p>Technically it's equivalent to using a code block on + the end of your db_multirow.</p> + + </dd><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_null"></a>db_null </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> <code class="computeroutput">db_null</code> - </pre><p> + </pre> + + <p> Returns a value which can be used in a bind variable to represent the SQL value <code class="computeroutput">null</code>. See <a class="link" href="db-api.html#dbapi_nulls_and_bind_vars" title="Nulls and Bind Variables">Nulls and Bind Variables</a> above. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_foreach"></a>db_foreach </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_foreach <span class="emphasis"><em>statement-name sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] \ <span class="emphasis"><em>code_block</em></span> [ if_no_rows <span class="emphasis"><em>if_no_rows_block ]</em></span> - </pre><p> + </pre> + + <p> Performs the SQL query <span class="emphasis"><em> <code class="computeroutput">sql</code> </em></span>, executing @@ -416,76 +590,109 @@ specified). If the query returns no rows, executes <span class="emphasis"><em><code class="computeroutput">if_no_rows_block </code></em></span> (if provided). - </p><p>Example:</p><pre class="programlisting"> + </p> + <p>Example:</p> + + <pre class="programlisting"> + db_foreach select_foo "select foo, bar from greeble" { doc_body_append "<li>foo=$foo; bar=$bar\n" } if_no_rows { doc_body_append "<li>There are no greebles in the database.\n" } - </pre><p> + </pre> + + <p> The code block may contain <code class="computeroutput">break</code> statements (which terminate the loop and flush the database handle) and <code class="computeroutput">continue</code> statements - (which continue to the next row of the loop). </p></dd><dt><span class="term"> + (which continue to the next row of the loop). </p> + + </dd><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_1row"></a>db_1row </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_1row <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] - </pre><p> + </pre> + + <p> Performs the SQL query <span class="emphasis"><em> <code class="computeroutput">sql</code></em></span>, setting variables to column values. Raises an error if the query does not return exactly 1 row. - </p><p>Example:</p><pre class="programlisting"> + </p> + <p>Example:</p> + + <pre class="programlisting"> + db_1row select_foo "select foo, bar from greeble where greeble_id = $greeble_id" # Bombs if there's no such greeble! # Now $foo and $bar are set. - </pre></dd><dt><span class="term"> + </pre> + + </dd><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_0or1row"></a>db_0or1row </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_0or1row <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -column_array <span class="emphasis"><em>array_name</em></span> | -column_set <span class="emphasis"><em>set_name</em></span> ] - </pre><p> + </pre> + + <p> Performs the SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If a row is returned, sets variables to column values and returns 1. If no rows are returned, returns 0. If more than one row is returned, throws an error. - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_nextval"></a>db_nextval</code> </span></dt><dd><pre class="programlisting"> + </p> + + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_nextval"></a>db_nextval</code> </span></dt><dd> + <pre class="programlisting"> db_nextval <span class="emphasis"><em>sequence-name</em></span> - </pre><p> + </pre> + + <p> Returns the next value for the sequence <span class="emphasis"><em>sequence-name</em></span> (using a SQL statement like <code class="computeroutput">SELECT</code> <span class="emphasis"><em><code class="computeroutput">sequence-name</code></em></span><code class="computeroutput">.nextval FROM DUAL</code>). If sequence pooling is enabled for the sequence, transparently uses a value from the pool if available to save a round-trip to the database (see <span class="emphasis"><em><a class="xref" href="db-api.html#db-api-pooling" title="Sequence Pooling">Sequence Pooling</a></em></span>). - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_register_pooled_sequence"></a>db_register_pooled_sequence </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_register_pooled_sequence <span class="emphasis"><em>sequence-name</em></span> <span class="emphasis"><em>pool-size</em></span> - </pre><p>Registers the sequence <span class="emphasis"><em>sequence-name</em></span> to be pooled, with a pool + </pre> + + <p>Registers the sequence <span class="emphasis"><em>sequence-name</em></span> to be pooled, with a pool size of <span class="emphasis"><em>pool-size</em></span> sequence values (see <span class="emphasis"><em><a class="xref" href="db-api.html#db-api-pooling" title="Sequence Pooling">Sequence Pooling</a></em></span>). - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_string"></a>db_string</code> </span></dt><dd><pre class="programlisting"> + </p> + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_string"></a>db_string</code> </span></dt><dd> + <pre class="programlisting"> db_string <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -default <span class="emphasis"><em>default</em></span> ] [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] - </pre><p>Returns the first column of the result of SQL query + </pre> + + <p>Returns the first column of the result of SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If <span class="emphasis"><em><code class="computeroutput">sql</code></em></span> doesn't return a row, returns @@ -495,76 +702,117 @@ <code class="computeroutput">database_to_tcl_string</code> and <code class="computeroutput">database_to_tcl_string_or_null</code>. - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_list"></a>db_list</code></span></dt><dd><pre class="programlisting"> + </p> + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_list"></a>db_list</code></span></dt><dd> + <pre class="programlisting"> db_list <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] - </pre><p>Returns a Tcl list of the values in the first column of the result of SQL + </pre> + + <p>Returns a Tcl list of the values in the first column of the result of SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If <span class="emphasis"><em><code class="computeroutput">sql</code></em></span> doesn't return any rows, returns an empty list. Analogous to <code class="computeroutput">database_to_tcl_list</code>. - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_list_of_lists"></a>db_list_of_lists</code></span></dt><dd><pre class="programlisting"> + </p> + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_list_of_lists"></a>db_list_of_lists</code></span></dt><dd> + <pre class="programlisting"> db_list_of_lists <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] - </pre><p>Returns a Tcl list, each element of which is a list of all column values + </pre> + + <p>Returns a Tcl list, each element of which is a list of all column values in a row of the result of SQL query <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. If <span class="emphasis"><em><code class="computeroutput">sql</code></em></span> doesn't return any rows, returns an empty list. (Analogous to <code class="computeroutput">database_to_tcl_list_list</code>.) - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_dml"></a>db_dml</code></span></dt><dd><pre class="programlisting"> + </p> + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_dml"></a>db_dml</code></span></dt><dd> + <pre class="programlisting"> db_dml <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> \ [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] \ [ -blobs <span class="emphasis"><em>blob_list</em></span> | -clobs <span class="emphasis"><em>clob_list</em></span> | -blob_files <span class="emphasis"><em>blob_file_list</em></span> | -clob_files <span class="emphasis"><em>clob_file_list</em></span> ] - </pre><p>Performs the DML or DDL statement <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. </p><p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL + </pre> + + <p>Performs the DML or DDL statement <span class="emphasis"><em><code class="computeroutput">sql</code></em></span>. </p> + + <p>If a length-<span class="emphasis"><em>n</em></span> list of blobs or clobs is provided, then the SQL should return <span class="emphasis"><em>n</em></span> blobs or clobs into the bind variables <code class="computeroutput">:1</code>, <code class="computeroutput">:2</code>, ... :<span class="emphasis"><em><code class="computeroutput">n</code></em></span>. <span class="emphasis"><em><code class="computeroutput">blobs</code></em></span> or <span class="emphasis"><em><code class="computeroutput">clobs</code></em></span>, if specified, should be a list of individual BLOBs or CLOBs to insert; <span class="emphasis"><em><code class="computeroutput">blob_files</code></em></span> or <span class="emphasis"><em><code class="computeroutput">clob_files</code></em></span>, if specified, should be a list of <span class="emphasis"><em>paths to files</em></span> containing the data to insert. Only one of <code class="computeroutput">-blobs</code>, <code class="computeroutput">-clobs</code>, - <code class="computeroutput">-blob_files</code>, and <code class="computeroutput">-clob_files</code> may be provided.</p><p>Example:</p><pre class="programlisting"> + <code class="computeroutput">-blob_files</code>, and <code class="computeroutput">-clob_files</code> may be provided.</p> + + <p>Example:</p> + <pre class="programlisting"> + db_dml insert_photos { insert photos(photo_id, image, thumbnail_image) values(photo_id_seq.nextval, empty_blob(), empty_blob()) returning image, thumbnail_image into :1, :2 } -blob_files [list "/var/tmp/the_photo" "/var/tmp/the_thumbnail"] - </pre><p> + </pre> + + + <p> This inserts a new row into the <code class="computeroutput">photos</code> table, with the contents of the files <code class="computeroutput">/var/tmp/the_photo</code> and <code class="computeroutput">/var/tmp/the_thumbnail</code> in the <code class="computeroutput">image</code> and <code class="computeroutput">thumbnail</code> columns, respectively. - </p></dd><dt><span class="term"> + </p> + </dd><dt><span class="term"> <code class="computeroutput"><a name="devguide.dbapi_db_write_clob"></a>db_write_clob</code>, <code class="computeroutput"><a name="devguide.dbapi_db_write_blob"></a>db_write_blob</code>, <code class="computeroutput"><a name="devguide.dbapi_db_blob_get_file"></a>db_blob_get_file</code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_write_clob <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] db_write_blob <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] db_blob_get_file <span class="emphasis"><em>statement-name</em></span> <span class="emphasis"><em>sql</em></span> [ -bind <span class="emphasis"><em>bind_set_id</em></span> | -bind <span class="emphasis"><em>bind_value_list</em></span> ] - </pre><p>Analogous to <code class="computeroutput">ns_ora write_clob/write_blob/blob_get_file</code>. + </pre> + <p>Analogous to <code class="computeroutput">ns_ora write_clob/write_blob/blob_get_file</code>. - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_release_unused_handles"></a>db_release_unused_handles</code></span></dt><dd><pre class="programlisting"> + + </p> + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_release_unused_handles"></a>db_release_unused_handles</code></span></dt><dd> + <pre class="programlisting"> db_release_unused_handles - </pre><p>Releases any allocated, unused database handles. </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_transaction"></a>db_transaction</code></span></dt><dd><pre class="programlisting"> + </pre> + + <p>Releases any allocated, unused database handles. </p> + + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_transaction"></a>db_transaction</code></span></dt><dd> + + <pre class="programlisting"> db_transaction <span class="emphasis"><em>code_block</em></span> [ on_error { <span class="emphasis"><em>code_block</em></span> } ] - </pre><p>Executes <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span> transactionally. Nested + </pre> + + <p>Executes <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span> transactionally. Nested transactions are supported (<code class="computeroutput">end transaction</code> is transparently <code class="computeroutput">ns_db dml</code>'ed when the outermost transaction completes). The <code class="computeroutput">db_abort_transaction</code> command can be used to abort all levels of transactions. It is possible to specify an optional <code class="computeroutput">on_error</code> code block that will be executed if some code in <span class="emphasis"><em>code_block</em></span> throws an exception. The variable <code class="computeroutput">errmsg</code> will be bound in that scope. - If there is no <code class="computeroutput">on_error</code> code, any errors will be propagated. </p><p>Example:</p><pre class="programlisting"> + If there is no <code class="computeroutput">on_error</code> code, any errors will be propagated. </p> + <p>Example:</p> + + + + <pre class="programlisting"> + proc replace_the_foo { col } { db_transaction { db_dml delete {delete from foo} @@ -592,19 +840,34 @@ print_the_foo ; # Writes out "foo is 8" - </pre></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_resultrows"></a>db_resultrows</code></span></dt><dd><pre class="programlisting"> + </pre> + + </dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_resultrows"></a>db_resultrows</code></span></dt><dd> + <pre class="programlisting"> db_resultrows - </pre><p>Returns the number of rows affected or returned by the previous + </pre> + + <p>Returns the number of rows affected or returned by the previous statement. - </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_with_handle"></a>db_with_handle</code></span></dt><dd><pre class="programlisting"> + </p></dd><dt><span class="term"><code class="computeroutput"><a name="devguide.dbapi_db_with_handle"></a>db_with_handle</code></span></dt><dd> + <pre class="programlisting"> db_with_handle <span class="emphasis"><em>var</em></span> <span class="emphasis"><em>code_block</em></span> - </pre><p>Places a database handle into the variable <span class="emphasis"><em><code class="computeroutput">var</code></em></span> and + </pre> + + + <p>Places a database handle into the variable <span class="emphasis"><em><code class="computeroutput">var</code></em></span> and executes <span class="emphasis"><em><code class="computeroutput">code_block</code></em></span>. This is useful when you don't want to have to use the new API (<code class="computeroutput">db_foreach</code>, - <code class="computeroutput">db_1row</code>, etc.), but need to use database handles explicitly. </p><p>Example:</p><pre class="programlisting"> + <code class="computeroutput">db_1row</code>, etc.), but need to use database handles explicitly. </p> + <p>Example:</p> + + + + <pre class="programlisting"> + proc lookup_the_foo { foo } { db_with_handle db { return [db_string unused "select ..."] @@ -621,19 +884,25 @@ } } - </pre></dd><dt><span class="term"> + </pre> + </dd><dt><span class="term"> <code class="computeroutput"> <a name="devguide.dbapi_db_nullify_empty_string"></a>db_nullify_empty_string </code> - </span></dt><dd><pre class="programlisting"> + </span></dt><dd> + <pre class="programlisting"> db_nullify_empty_string <span class="emphasis"><em>string</em></span> - </pre><p>For true SQL purists, we provide the convenience function + </pre> + + <p>For true SQL purists, we provide the convenience function <code class="computeroutput">db_nullify_empty_string</code>, which returns [db_null] if its <span class="emphasis"><em><code class="computeroutput">string</code></em></span> argument is the empty string - and can be used to encapsulate another Oracle quirk: </p><pre class="programlisting"> + and can be used to encapsulate another Oracle quirk: </p> + <pre class="programlisting"> + set baz "" # Clean out the foo table @@ -647,34 +916,54 @@ # the empty string we just inserted (because of Oracle's coercion # quirk) - </pre><p> + </pre> + + <p> To balance out this asymmetry, you can explicitly set <code class="computeroutput">baz</code> to <code class="computeroutput">null</code> by writing: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> + db_dml foo_insert {insert into foo(baz) values(:1)} {[db_nullify_empty_string $baz]} - </pre></dd></dl></div><p> - </p><div class="cvstag">($Id$)</div><p> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-caching"></a>Caching Database API Results</h3></div></div></div><p>The database API allows for direct caching of query results. Repeated calls will + </pre> + + </dd></dl></div> + + <p> + <span class="cvstag">($Id$)</span> + </p> + + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-api-caching"></a>Caching Database API Results</h3></div></div></div> + + <p>The database API allows for direct caching of query results. Repeated calls will return the cached value until it is either explicitly flushed using db_flush_cache, times out (configured the ns_cache is called to create the cache), or another cached query fills the cache, causing older entries to be flushed. - </p><p>Values returned by a query are cached if you pass the "-cache_key" switch + </p> + + <p>Values returned by a query are cached if you pass the "-cache_key" switch to the database procedure. The switch value will be used as the key in the ns_cache eval call used to execute the query and processing code. The db_flush proc should be called to flush the cache when appropriate. The "-cache_pool" parameter can be used to specify the cache pool to be used, and defaults to db_cache_pool. The size of the default cache is governed by the kernel parameter "DBCacheSize" in the "caching" section. - </p><p> + </p> + <p> Currently db_string, db_list, db_list_of_lists, db_1row, db_0or1row, and db_multirow support caching. - </p><p>For caching to be effective, one must carefully design a cache_pool and cache_key + </p> + <p>For caching to be effective, one must carefully design a cache_pool and cache_key strategy that uniquely identifies a query within the system, including the relevant objects being referenced by the query. Typically a cache_key should include one or more object_ids and a name that identifies the operation being done. - </p><p>Here is an example from the layout-manager package:</p><pre class="programlisting"> + </p> + <p>Here is an example from the layout-manager package:</p> + <pre class="programlisting"> # Query to return the elements of a page as a list. The prefix "page_" is used to denote # that this is a page-related query, page_id is used to uniquely identify the query @@ -688,4 +977,7 @@ db_flush_cache -cache_key_pattern page_${page_id}_* - </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr><tr><td width="40%" align="left">The Request Processor </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Templates in OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="request-processor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="templates.html">Next</a></td></tr><tr><td width="40%" align="left">The Request Processor </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Templates in OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/dev-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/dev-guide.html,v diff -u -r1.37 -r1.38 --- openacs-4/packages/acs-core-docs/www/dev-guide.html 7 Aug 2017 23:47:49 -0000 1.37 +++ openacs-4/packages/acs-core-docs/www/dev-guide.html 8 Nov 2017 09:42:10 -0000 1.38 @@ -1,2 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 11. Development Reference</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="tutorial-future-topics.html" title="Future Topics"><link rel="next" href="packages.html" title="OpenACS Packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-future-topics.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="dev-guide"></a>Chapter 11. Development Reference</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="packages.html">OpenACS Packages</a></span></dt><dt><span class="sect1"><a href="objects.html">OpenACS Data Models and the Object System</a></span></dt><dt><span class="sect1"><a href="request-processor.html">The Request Processor</a></span></dt><dt><span class="sect1"><a href="db-api.html">The OpenACS Database Access API</a></span></dt><dt><span class="sect1"><a href="templates.html">Using Templates in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions.html">Groups, Context, Permissions</a></span></dt><dt><span class="sect1"><a href="subsites.html">Writing OpenACS Application Pages</a></span></dt><dt><span class="sect1"><a href="parties.html">Parties in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a></span></dt><dt><span class="sect1"><a href="object-identity.html">Object Identity</a></span></dt><dt><span class="sect1"><a href="programming-with-aolserver.html">Programming with AOLserver</a></span></dt><dt><span class="sect1"><a href="form-builder.html">Using Form Builder: building html forms dynamically</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-future-topics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr><tr><td width="40%" align="left">Future Topics </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 11. Development Reference</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="tutorial-future-topics.html" title="Future Topics"><link rel="next" href="packages.html" title="OpenACS Packages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-future-topics.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="dev-guide"></a>Chapter 11. Development Reference</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="packages.html">OpenACS Packages</a></span></dt><dt><span class="sect1"><a href="objects.html">OpenACS Data Models and the Object System</a></span></dt><dt><span class="sect1"><a href="request-processor.html">The Request Processor</a></span></dt><dt><span class="sect1"><a href="db-api.html">The OpenACS Database Access API</a></span></dt><dt><span class="sect1"><a href="templates.html">Using Templates in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions.html">Groups, Context, Permissions</a></span></dt><dt><span class="sect1"><a href="subsites.html">Writing OpenACS Application Pages</a></span></dt><dt><span class="sect1"><a href="parties.html">Parties in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a></span></dt><dt><span class="sect1"><a href="object-identity.html">Object Identity</a></span></dt><dt><span class="sect1"><a href="programming-with-aolserver.html">Programming with AOLserver</a></span></dt><dt><span class="sect1"><a href="form-builder.html">Using Form Builder: building html forms dynamically</a></span></dt></dl></div> + + + + + + + + + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-future-topics.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="packages.html">Next</a></td></tr><tr><td width="40%" align="left">Future Topics </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Packages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/doc-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/doc-standards.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/doc-standards.html 7 Aug 2017 23:47:49 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/doc-standards.html 8 Nov 2017 09:42:10 -0000 1.20 @@ -1,2 +1,9 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 13. Documentation Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="automated-testing-best-practices.html" title="Automated Testing"><link rel="next" href="docbook-primer.html" title="OpenACS Documentation Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="automated-testing-best-practices.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="doc-standards"></a>Chapter 13. Documentation Standards</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="docbook-primer.html">OpenACS Documentation Guide</a></span></dt><dt><span class="sect1"><a href="psgml-mode.html">Using PSGML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="nxml-mode.html">Using nXML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="filename.html">Detailed Design Documentation Template</a></span></dt><dt><span class="sect1"><a href="requirements-template.html">System/Application Requirements Template</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="automated-testing-best-practices.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr><tr><td width="40%" align="left">Automated Testing </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Documentation Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 13. Documentation Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="automated-testing-best-practices.html" title="Automated Testing"><link rel="next" href="docbook-primer.html" title="OpenACS Documentation Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="automated-testing-best-practices.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="doc-standards"></a>Chapter 13. Documentation Standards</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="docbook-primer.html">OpenACS Documentation Guide</a></span></dt><dt><span class="sect1"><a href="psgml-mode.html">Using PSGML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="nxml-mode.html">Using nXML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="filename.html">Detailed Design Documentation Template</a></span></dt><dt><span class="sect1"><a href="requirements-template.html">System/Application Requirements Template</a></span></dt></dl></div> + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="automated-testing-best-practices.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="docbook-primer.html">Next</a></td></tr><tr><td width="40%" align="left">Automated Testing </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Documentation Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/docbook-primer.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/docbook-primer.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -410,7 +410,7 @@ tools will be marked up to conform to the <a class="ulink" href="http://docbook.org/xml/index.html" target="_top">DocBook XML DTD</a>. The remaining discussion is about publishing using Docbook.</p><p> -<a class="indexterm" name="idp140592107950600" id="idp140592107950600"></a> is a publishing standard based on XML +<a class="indexterm" name="idp140623175611576" id="idp140623175611576"></a> is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>It is open-source.</p></li><li class="listitem"><p>The DocBook community <a class="ulink" href="http://docbook.org/help" target="_top">mailing lists</a> @@ -450,7 +450,7 @@ of elements</a> 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 <span class="strong"><strong>as long as -you remember to</strong></span>: <a class="indexterm" name="idp140592101961656" id="idp140592101961656"></a> +you remember to</strong></span>: <a class="indexterm" name="idp140623175588680" id="idp140623175588680"></a> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Always close your tags with corresponding end-tags and to <span class="strong"><strong>not use other tag @@ -491,7 +491,7 @@ <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-structure" id="dbprimer-structure"></a>Document Structure</h3></div></div></div><p>The documentation for each package will make up a little "book" that is structured like this - examples are -<span class="emphasis"><em>emphasized</em></span>: <a class="indexterm" name="idp140592102567448" id="idp140592102567448"></a> +<span class="emphasis"><em>emphasized</em></span>: <a class="indexterm" name="idp140623175542264" id="idp140623175542264"></a> </p><pre class="programlisting"> book : <span class="strong"><strong>Docs for one package</strong></span> - <span class="emphasis"><em>templating</em></span> | @@ -516,11 +516,11 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-sections" id="dbprimer-sections"></a>Headlines, Sections</h3></div></div></div><p> -<a class="indexterm" name="idp140592102754312" id="idp140592102754312"></a> Given that your job starts at the +<a class="indexterm" name="idp140623175476952" id="idp140623175476952"></a> Given that your job starts at the <code class="computeroutput">sect1</code>-level, all your documents should open with a <a class="ulink" href="http://docbook.org/tdg/en/html/sect1.html" target="_top"><code class="computeroutput"><sect1></code></a>-tag and end with the corresponding <code class="computeroutput"></sect1></code>.</p><p> -<a class="indexterm" name="idp140592107933944" id="idp140592107933944"></a> You need to feed every <code class="computeroutput"><sect1></code> two attributes. The first +<a class="indexterm" name="idp140623175464952" id="idp140623175464952"></a> You need to feed every <code class="computeroutput"><sect1></code> two attributes. The first attribute, <code class="computeroutput">id</code>, is standard and can be used with all elements. It comes in very handy when interlinking between documents (more about this when talking about @@ -529,7 +529,7 @@ <code class="computeroutput">id</code> has to be unique throughout the book you're making since the <code class="computeroutput">id</code>'s in your <code class="computeroutput">sect1</code>'s will turn into filenames when the book is parsed into HTML.</p><p> -<a class="indexterm" name="idp140592102633688" id="idp140592102633688"></a> The other attribute is <code class="computeroutput">xreflabel</code>. The value of this is the text +<a class="indexterm" name="idp140623175469752" id="idp140623175469752"></a> The other attribute is <code class="computeroutput">xreflabel</code>. The value of this is the text that will appear as the link when referring to this <code class="computeroutput">sect1</code>.</p><p>Right after the opening tag you put the title of the document - this is usually the same as <code class="computeroutput">xreflabel</code>-attribute. E.g. the top level of the document you're reading right now looks like this:</p><pre class="programlisting"> @@ -540,7 +540,7 @@ </sect1> </pre><p> -<a class="indexterm" name="idp140592107956824" id="idp140592107956824"></a> Inside this container your document will +<a class="indexterm" name="idp140623175474856" id="idp140623175474856"></a> Inside this container your document will be split up into <a class="ulink" href="http://docbook.org/tdg/en/html/sect2.html" target="_top"><code class="computeroutput"><sect2></code></a>'s, each with the same requirements - <code class="computeroutput">id</code> and <code class="computeroutput">xreflabel</code> attributes, and a <code class="computeroutput"><title></code>-tag inside. Actually, the <code class="computeroutput">xreflabel</code> is never required in @@ -550,7 +550,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-code" id="dbprimer-code"></a>Code</h3></div></div></div><p> -<a class="indexterm" name="idp140592102002600" id="idp140592102002600"></a> For displaying a snippet of code, a +<a class="indexterm" name="idp140623175449672" id="idp140623175449672"></a> For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we use <a class="ulink" href="http://docbook.org/tdg/en/html/computeroutput.html" target="_top"><code class="computeroutput"><computeroutput></code></a> and <a class="ulink" href="http://docbook.org/tdg/en/html/code.html" target="_top"><code class="code"><code></code></a> tags. These replace the HTML-tag <code class="code"><code></code> tag, @@ -564,15 +564,15 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-links" id="dbprimer-links"></a>Links</h3></div></div></div><p> -<a class="indexterm" name="idp140592100322072" id="idp140592100322072"></a> Linking falls into two different +<a class="indexterm" name="idp140623175460280" id="idp140623175460280"></a> Linking falls into two different categories: inside the book you're making and outside:</p><div class="variablelist"><dl class="variablelist"> <dt><span class="term"><span class="strong"><strong>1. Inside linking, cross-referencing other parts of your book</strong></span></span></dt><dd> <p>By having unique <code class="computeroutput">id</code>'s you can cross-reference any part of your book with a simple tag, regardless of where that part is.</p><p> -<a class="indexterm" name="idp140592100325384" id="idp140592100325384"></a>Check out how I link to a subsection of +<a class="indexterm" name="idp140623175394568" id="idp140623175394568"></a>Check out how I link to a subsection of the Developer's Guide:</p><p>Put this in your XML:</p><pre class="programlisting"> - Find information about creating a package in <xref linkend="packages-making-a-package"></xref>. @@ -596,7 +596,7 @@ </dd><dt><span class="term"><span class="strong"><strong>2. Linking outside the documentation</strong></span></span></dt><dd> <p> -<a class="indexterm" name="idp140592102378600" id="idp140592102378600"></a> If you're hyper-linking out of the +<a class="indexterm" name="idp140623175410504" id="idp140623175410504"></a> If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different (<a class="ulink" href="http://docbook.org/tdg/en/html/ulink.html" target="_top"><code class="computeroutput"><ulink></code></a>):</p><pre class="programlisting"> <ulink url="http://www.oracle.com/">Oracle Corporation</ulink> @@ -615,7 +615,7 @@ <span class="strong"><strong>Note:</strong></span> The graphics guidelines are not written in stone. Use another valid approach if it works better for you.</em></span></p><p> -<a class="indexterm" name="idp140592102265016" id="idp140592102265016"></a> To insert a graphic we use the elements +<a class="indexterm" name="idp140623175419144" id="idp140623175419144"></a> To insert a graphic we use the elements <a class="ulink" href="http://docbook.org/tdg/en/html/mediaobject.html" target="_top"><code class="computeroutput"><mediaobject></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/imageobject.html" target="_top"><code class="computeroutput"><imageobject></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/imagedata.html" target="_top"><code class="computeroutput"><imagedata></code></a>, @@ -640,7 +640,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-lists" id="dbprimer-lists"></a>Lists</h3></div></div></div><p> -<a class="indexterm" name="idp140592100631192" id="idp140592100631192"></a> Here's how you make the DocBook +<a class="indexterm" name="idp140623175427256" id="idp140623175427256"></a> Here's how you make the DocBook equivalent of the three usual HTML-lists:</p><div class="variablelist"><dl class="variablelist"> <dt><span class="term"><span class="strong"><strong>1. How to make an <ul></strong></span></span></dt><dd> @@ -693,7 +693,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-tables" id="dbprimer-tables"></a>Tables</h3></div></div></div><p> -<a class="indexterm" name="idp140592108147992" id="idp140592108147992"></a> DocBook supports several types of tables, +<a class="indexterm" name="idp140623175373160" id="idp140623175373160"></a> DocBook supports several types of tables, but in most cases, the <a class="ulink" href="http://docbook.org/tdg/en/html/informaltable.html" target="_top"><code class="computeroutput"><informaltable></code></a> is enough:</p><pre class="programlisting"> <informaltable frame="all"> <tgroup cols="3"> @@ -739,7 +739,7 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="dbprimer-emphasis" id="dbprimer-emphasis"></a>Emphasis</h3></div></div></div><p> -<a class="indexterm" name="idp140592101941752" id="idp140592101941752"></a> Our documentation uses two flavors of +<a class="indexterm" name="idp140623175386280" id="idp140623175386280"></a> Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <a class="ulink" href="http://docbook.org/tdg/en/html/emphasis.html" target="_top"><code class="computeroutput"><emphasis></code></a>.</p><p>The <code class="computeroutput"><emphasis></code> tag defaults to italics when parsed. If you're looking for emphasizing with bold type, use <code class="computeroutput"><emphasis Index: openacs-4/packages/acs-core-docs/www/docbook-primer.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/docbook-primer.html,v diff -u -r1.53 -r1.54 --- openacs-4/packages/acs-core-docs/www/docbook-primer.html 7 Aug 2017 23:47:49 -0000 1.53 +++ openacs-4/packages/acs-core-docs/www/docbook-primer.html 8 Nov 2017 09:42:10 -0000 1.54 @@ -1,21 +1,32 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Documentation Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="next" href="psgml-mode.html" title="Using PSGML mode in Emacs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="doc-standards.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="docbook-primer"></a>OpenACS Documentation Guide</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Documentation Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="next" href="psgml-mode.html" title="Using PSGML mode in Emacs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="doc-standards.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="docbook-primer"></a>OpenACS Documentation Guide</h2></div></div></div> + + + <p> By Claus Rasmussen, with additions by Roberto Mello, Vinod Kurup, and the OpenACS Community - </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-overview"></a>Overview of OpenACS Documentation</h3></div></div></div><p> + </p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-overview"></a>Overview of OpenACS Documentation</h3></div></div></div> + + <p> <span class="productname">OpenACS</span>™ is a powerful system with incredible possibilities and applications, but this power comes with some complexity and a steep learning curve that is only attenuated by good documentation. Our goal is to write superb documentation, so that users, developers and administrators of OpenACS installations can enjoy the system. - </p><p> + </p> + + <p> The history of OpenACS documentation: ..began by building on a good documentation base from ArsDigita's ACS in the late 1990's. Some sections of the documentation, however, lacked details and examples; others simply did not exist. The OpenACS community began meeting the challenge by identifying needs and writing documentation on an as needed basis. - </p><p> + </p> + + <p> By having documentation dependent on volunteers and code developers, documentation updates lagged behind the evolving system software. As significant development changes were made @@ -27,7 +38,8 @@ optimization quickly rendered documentation obsolete for developers. The code became the substitute and source for documentation. - </p><p> + </p> + <p> With thousands of lines of code and few developers tracking changes, features and advances to the OpenACS system went unnoticed or were not well understood except by the code @@ -37,19 +49,26 @@ working with it and discussion in the forums. Informal sharing of experiential and tacit knowledge has become the OpenACS community's main method of sharing knowledge. - </p><p> + </p> + <p> This document attempts to shape ongoing documentation efforts by using principles of continual improvement to re-engineer documentation production. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-managing"></a>Managing OpenACS Documentation</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-managing"></a>Managing OpenACS Documentation</h3></div></div></div> + + <p> Documentation production shares many of the challenges of software development, such as managing contributions, revisions and the (editorial) release cycle. This is yet another experiment in improving documentation --this time by using principles of continual improvement to focus the on-going efforts. These processes are outlined as project management phases: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> <span class="strong"><strong>Requirements phase</strong></span> is about setting goals and specifications, and includes exploration of scenarios, use cases etc. As an example, see the <a class="ulink" href="http://openacs.org/doc/openacs-4/requirements-template.html" target="_top"> @@ -82,30 +101,40 @@ cases, the OpenACS community verifies the project as a success through feedback including bug reports, user and administrator comments, and code changes. - </p></li></ol></div><p> + </p></li></ol></div> + <p> OpenACS forum discussions on documentation requirements and strategies are summarized in the following sections. Production phases are mainly organized and fulfilled by a designated documentation maintainer. Hopefully the following sections will help spur greater direct participation by the OpenACS community. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-requirements"></a>OpenACS General Documentation Requirements</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-requirements"></a>OpenACS General Documentation Requirements</h3></div></div></div> + + <p> By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. - </p><p> + </p> + <p> OpenACS documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> clarity in presentation. <a class="ulink" href="http://www.lifewithqmail.org/lwq.html" target="_top">Life with qmail</a> is a recommended example of "rated high" online documentation. </p></li><li class="listitem"><p> Avoid requirements that significantly increase the labor required to maintain documentation. - </p></li><li class="listitem"><p> + </p></li><li class="listitem"> + <p> Use best practices learned from the print world, web, and other media, about use of gamma, space, writing style etc. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Consistency in publishing -Establishing and adhering to publishing standards </p></li><li class="listitem"><p> Use standardized language -Use international English @@ -137,7 +166,8 @@ context of the document. For example, "requires basic competency with a text-based editor such as vi or emacs via telnet" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> Show where to find current information instead of writing about current info that becomes obsolete. If the information is not found elsewhere, then create one place for it, where @@ -146,7 +176,8 @@ to maintain up-to-date documentation. In other words, state facts in appropriately focused, designated areas only, then refer to them by reference (with links). - </p><p> + </p> + <p> Note: Sometimes facts should be stated multiple ways, to accommodate different reading style preferences. The should still be in 1 area, using a common layout of perhaps @@ -197,16 +228,25 @@ <book><title><part label="Part 1"><etc...> </pre><p> </p></li></ul></div><p> - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-end-user-reqs"></a>OpenACS Documentation Requirements for End-users</h3></div></div></div><p> + </p></li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-end-user-reqs"></a>OpenACS Documentation Requirements for End-users</h3></div></div></div> + + <p> By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. - </p><p> + </p> + <p> OpenACS end-user documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> End-users should not have to read docs to use the system. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Include how to get help. How and where to find answers, contact others, what to do if one gets an AOLserver or other error when using the system. Include types of available @@ -306,9 +346,11 @@ different emphasis on the various criteria, which is why providing a framework to help decide is probably more useful than an actual comparison. - </p></li></ul></div><p> + </p></li></ul></div> + <p> Package documentation requirements have additional requirements. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> A list of all packages, their names, their purposes, what they can and cannot do (strengths, limitations), what differentiates them from similar packages, minimal @@ -339,14 +381,21 @@ development document templates: a <a class="ulink" href="http://openacs.org/doc/current/requirements-template.html" target="_top"> Requirements Template</a> and <a class="ulink" href="http://openacs.org/doc/current/filename.html" target="_top">Detailed Design Document</a>. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-admin-reqs"></a>OpenACS Documentation Requirements for Site and Administrators</h3></div></div></div><p> + </p></li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-admin-reqs"></a>OpenACS Documentation Requirements for Site and Administrators</h3></div></div></div> + + <p> By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. - </p><p> + </p> + <p> OpenACS administrators' documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> For each requirement below, include links to developer tutorials and other documentation for more detail. </p></li><li class="listitem"><p> @@ -407,14 +456,22 @@ new master.adp, options on "user pages" , a quick introduction to the functions and processes. info about the user variables, file locations - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-install-reqs"></a>OpenACS Installation Documentation Requirements</h3></div></div></div><p> + </p></li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-install-reqs"></a>OpenACS Installation Documentation Requirements</h3></div></div></div> + + <p> By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. - </p><p> + </p> + <p> OpenACS installation documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> state installation prerequisites. For example: "You should read through the installation process to familiarize yourself with the installation process, before beginning an @@ -437,59 +494,86 @@ for OpenACS, RDBMS(s) install and configure, Webserver install and configure, OpenACS install and configure, post-install work - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-developer-tutorial-reqs"></a>OpenACS Developer Tutorial Documentation Requirements</h3></div></div></div><p> + </p></li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-developer-tutorial-reqs"></a>OpenACS Developer Tutorial Documentation Requirements</h3></div></div></div> + + <p> By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. - </p><p> + </p> + <p> OpenACS developer tutorial documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> list learning prerequisites to customize, fix, and improve OACS modules, and create new ones. You are expected to have read and understand the information [minimum requirements similar to adept at Using OpenACS Administrating Guide] before reading this guide. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Refer to development documentation instead of duplicating here - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> List suggestions for installing and setting up a development environment; these can be annotated links to the installation documentation - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Provide working examples that highlight the various subsystems, Tcl environment, OpenACS protocols, AOLserver template and ns_* commands, OpenACS templating, sql queries, db triggers, scheduling protocols, how to use the page contract, how to get the accessing user_id etc - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Show how to construct basic SQL queries using the db API, - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> The life of an http request to a dynamic, templated page - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> General rules to follow for stability, scalability - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Show the step by step customizing of an existing package that meets current recommended coding styles of OpenACS package development, by referring to developer resources. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Use the ArsDigita problem sets and "what Lars produced for ACS Java" as inspiration for a PostgreSQL equivalent tutorial about developing a new OpenACS package including discussion of the significance of the package documentation templates - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Include a summary of important links used by developers - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Note any deprecated tools and methods by linking to prior versions instead of describing them in current docs - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-developer-reqs"></a>OpenACS Developer Documentation Requirements</h3></div></div></div><p> + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="docs-developer-reqs"></a>OpenACS Developer Documentation Requirements</h3></div></div></div> + + <p> By the OpenACS Community. This section is a collection of documentation requirements that have been expressed in the OpenACS forums to 4th July 2003. - </p><p> + </p> + <p> OpenACS developer documentation should meet the following requirements. No significance has been given to the order presented, topic breadth or depth here. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> list documentation assumptions, such as familiarity with modifying OpenACS packages. All kernel docs are here etc. </p></li><li class="listitem"><p> @@ -554,20 +638,31 @@ Document kernel coding requirements, strategy and guidelines to help code changers make decisions that meet kernel designers' criteria - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="doc-strategy"></a>OpenACS Documentation Strategy</h3></div></div></div><p> + </p></li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="doc-strategy"></a>OpenACS Documentation Strategy</h3></div></div></div> + + <p> OpenACS documentation development is subject to the constraints of the software project development and release methods and cycles (<a class="xref" href="cvs-guidelines.html#using-cvs-with-openacs" title="Using CVS with OpenACS">the section called “Using CVS with OpenACS”</a>). Essentially, all phases of work may be active to accommodate the asynchronous nature of multiple subprojects evolving by the efforts of a global base of participants with culturally diverse time references and scheduling idiosyncrasies. - </p><p> + </p> + <p> The documentation strategy is to use project methods to involve others by collaborating or obtaining guidance or feedback (peer review) to distribute the workload and increase the overall value of output for the OpenACS project. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-why"></a>OpenACS Documentation Strategy: Why DocBook?</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-why"></a>OpenACS Documentation Strategy: Why DocBook?</h3></div></div></div> + + <p> OpenACS documentation is taking a dual approach to publishing. Documentation that is subject to rapid change and participation by the OpenACS community is managed through the <a class="ulink" href="http://openacs.org/xowiki/pages/en/Documentation_Project" target="_top">OpenACS @@ -577,11 +672,13 @@ <a class="ulink" href="http://docbook.org/xml/index.html" target="_top">DocBook XML DTD</a>. The remaining discussion is about publishing using Docbook. -</p><p> -<a class="indexterm" name="idp140592107950600"></a> +</p> +<p> +<a class="indexterm" name="idp140623175611576"></a> is a publishing standard based on XML with similar goals to the OpenACS Documentation project. Some specific reasons why we are using DocBook: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> It is open-source. </p></li><li class="listitem"><p> The DocBook community <a class="ulink" href="http://docbook.org/help" target="_top">mailing lists</a> @@ -598,9 +695,11 @@ </p></li><li class="listitem"><p> It is well tested technology. It has been in development since the <a class="ulink" href="http://docbook.org/tdg/en/html/ch01.html#d0e2132" target="_top">early 1990's</a>). - </p></li></ul></div><p> + </p></li></ul></div> + <p> Reasons why we are using Docbook XML instead of Docbook SGML: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <span class="emphasis"><em>Consistency</em></span> and history. We started with a collection of DocBook XML files that ArsDigita wrote. Trying to re-write them to conform to the SGML DTD would be unnecessary work. @@ -613,14 +712,16 @@ <span class="emphasis"><em>The tool chain has matured</em></span>. xsltproc and other XML based tools have improved to the point where they are about as good as the SGML tools. Both can output html and pdf formats. - </p></li></ul></div><p> + </p></li></ul></div> + <p> Albeit, the road to using DocBook has had some trials. In 2002, Docbook still was not fully capable of representing online books as practiced by book publishers and expected from readers with regards to usability on the web. That meant DocBook did not entirely meet OpenACS publishing requirements at that time. - </p><p> + </p> + <p> In 2004, Docbook released version 4.4, which complies with all the OpenACS publishing requirements. Producing a web friendly book hierarchy arguably remains DocBooks' @@ -633,65 +734,103 @@ <code class="computeroutput">bibliosource</code>. <a class="ulink" href="http://www.docbook.org/tdg/en/html/docbook.html" target="_top">DocBook: The Definitive Guide</a> is a good start for learning how to represent paper-based books online. - </p><p> + </p> + + <p> The following DocBook primer walks you through the basics, and should cover the needs for 95 percent of the documentation we produce. You are welcome to explore DocBook's <a class="ulink" href="http://docbook.org/tdg/en/html/part2.html" target="_top"> list of elements</a> 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 <span class="strong"><strong>as long as you remember to</strong></span>: - <a class="indexterm" name="idp140592101961656"></a> - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + <a class="indexterm" name="idp140623175588680"></a> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Always close your tags with corresponding end-tags and to <span class="strong"><strong>not use other tag minimization</strong></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Write all elements and attributes in lowercase - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Quote all attributes - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-validation"></a>Tools</h3></div></div></div><p> + </p></li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-validation"></a>Tools</h3></div></div></div> + + + <p> You are going to need the following to work with the OpenACS Docbook XML documentation: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> <a class="ulink" href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a> - The document type definition for XML. You can find an RPM or DEB package or you can download a zip file from the site linked from here. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="http://sourceforge.net/projects/docbook/" target="_top">XSL Stylesheets</a> (docbook-xsl) - The stylesheets to convert to HTML. We have been using a stylesheet based upon NWalsh's chunk.xsl. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <code class="computeroutput">xsltproc</code> - The processor that will take an XML document and, given a xsl stylesheet, convert it to HTML. It needs libxml2 and libxslt (available in RPM and DEB formats or from <a class="ulink" href="http://xmlsoft.org/" target="_top">xmlsoft.org</a>. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Some editing tool. A popular one is Emacs with the psgml and nXML modes. The <a class="ulink" href="http://www.tldp.org/LDP/LDP-Author-Guide/html/index.html" target="_top">LDP Author Guide</a> and <a class="ulink" href="https://github.com/docbook/wiki/wiki/DocBookTools" target="_top">DocBook Wiki</a> list some alternates. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-new-doc"></a>Writing New Docs</h3></div></div></div><p> + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-new-doc"></a>Writing New Docs</h3></div></div></div> + + <p> After you have the tools mentioned above, you need to define a title for your document. Then start thinking about the possible sections and subsections you will have in your document. Make sure you coordinate with the OpenACS Gatekeepers to make sure you are not writing something that someone else is already writing. Also, if you desire to use the OpenACS CVS repository, please e-mail the gatekeeper in charge of documentation. - </p><p> + </p> + <p> You can look at some templates for documents (in Docbook XML) in the <a class="ulink" href="https://github.com/openacs/openacs-core/tree/oacs-5-9/packages/acs-core-docs/www/xml/engineering-standards" target="_top">sources for acs-core-docs</a>, especially the <span class="emphasis"><em> Detailed Design Documentation Template</em></span> and the <span class="emphasis"><em>System/Application Requirements Template</em></span>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-structure"></a>Document Structure</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-structure"></a>Document Structure</h3></div></div></div> + + + <p> The documentation for each package will make up a little "book" that is structured like this - examples are <span class="emphasis"><em>emphasized</em></span>: - <a class="indexterm" name="idp140592102567448"></a> + <a class="indexterm" name="idp140623175542264"></a> - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> book : <span class="strong"><strong>Docs for one package</strong></span> - <span class="emphasis"><em>templating</em></span> | +--chapter : <span class="strong"><strong>One section</strong></span> - <span class="emphasis"><em>for developers</em></span> @@ -705,52 +844,83 @@ +--sect3 : <span class="strong"><strong>Subsections</strong></span> - <span class="emphasis"><em>Programmer's API</em></span> | ... : <span class="strong"><strong>...</strong></span> - </pre><p> + </pre> + + <p> The actual content is split up into documents that start at a <code class="computeroutput">sect1</code>-level. These are then tied together in a top-level document that contains all the information above the line. This will be explained in more detail in a later document, - and we will provide a set of templates for documenting an entire package. </p><p>For now you can take a look at the + and we will provide a set of templates for documenting an entire package. </p> + + <p>For now you can take a look at the <a class="ulink" href="https://github.com/openacs/openacs-core/tree/oacs-5-9/packages/acs-core-docs/www/xml/engineering-standards" target="_top">sources of these DocBook documents</a> to get an idea of how they are tied together. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-sections"></a>Headlines, Sections</h3></div></div></div><p> - <a class="indexterm" name="idp140592102754312"></a> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-sections"></a>Headlines, Sections</h3></div></div></div> + + + <p> + <a class="indexterm" name="idp140623175476952"></a> Given that your job starts at the <code class="computeroutput">sect1</code>-level, all your documents should open with a <a class="ulink" href="http://docbook.org/tdg/en/html/sect1.html" target="_top"><code class="computeroutput"><sect1></code></a>-tag and end with the corresponding <code class="computeroutput"></sect1></code>. - </p><p> - <a class="indexterm" name="idp140592107933944"></a> + </p> + + <p> + <a class="indexterm" name="idp140623175464952"></a> You need to feed every <code class="computeroutput"><sect1></code> two attributes. The first attribute, <code class="computeroutput">id</code>, 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 <a class="xref" href="docbook-primer.html#dbprimer-links" title="Links">the section called “Links”</a>). The value of <code class="computeroutput">id</code> has to be unique throughout the book you're making since the <code class="computeroutput">id</code>'s in your <code class="computeroutput">sect1</code>'s will turn into filenames when the book is parsed into HTML. - </p><p> - <a class="indexterm" name="idp140592102633688"></a> + </p> + + <p> + <a class="indexterm" name="idp140623175469752"></a> The other attribute is <code class="computeroutput">xreflabel</code>. The value of this is the text that will appear as the link when referring to this <code class="computeroutput">sect1</code>. - </p><p> + </p> + + <p> Right after the opening tag you put the title of the document - this is usually the same as <code class="computeroutput">xreflabel</code>-attribute. E.g. the top level of the document you're reading right now looks like this: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> <sect1 id="docbook-primer" xreflabel="DocBook Primer"> <title>DocBook Primer</title> ... </sect1> -</pre><p> - <a class="indexterm" name="idp140592107956824"></a> +</pre> + + <p> + <a class="indexterm" name="idp140623175474856"></a> Inside this container your document will be split up into <a class="ulink" href="http://docbook.org/tdg/en/html/sect2.html" target="_top"><code class="computeroutput"><sect2></code></a>'s, each with the same requirements - <code class="computeroutput">id</code> and <code class="computeroutput">xreflabel</code> attributes, and a <code class="computeroutput"><title></code>-tag inside. Actually, the <code class="computeroutput">xreflabel</code> is never required in sections, but it makes linking to that section a lot easier. - </p><p> + </p> + + <p> When it comes to naming your <code class="computeroutput">sect2</code>'s and below, prefix them with some abbreviation of the <code class="computeroutput">id</code> in the <code class="computeroutput">sect1</code> such as <code class="computeroutput">requirements-overview</code>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-code"></a>Code</h3></div></div></div><p> - <a class="indexterm" name="idp140592102002600"></a> + </p> + + </div> + + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-code"></a>Code</h3></div></div></div> + + + <p> + <a class="indexterm" name="idp140623175449672"></a> For displaying a snippet of code, a filename or anything else you just want to appear as a part of a sentence, we use <a class="ulink" href="http://docbook.org/tdg/en/html/computeroutput.html" target="_top"><code class="computeroutput"><computeroutput></code></a> @@ -759,66 +929,129 @@ These replace the HTML-tag <code class="code"><code></code> tag, depending on whether the tag is describing computer output or computer code. - </p><p> + </p> + + <p> For bigger chunks of code such as SQL-blocks, the tag <a class="ulink" href="http://docbook.org/tdg/en/html/programlisting.html" target="_top"><code class="computeroutput"><programlisting></code></a> is used. Just wrap your code block in it; mono-spacing, indents and all that stuff is taken care of automatically. - </p><p>For expressing user interaction via a terminal window, we wrap + </p> + <p>For expressing user interaction via a terminal window, we wrap the <a class="ulink" href="http://docbook.org/tdg/en/html/screen.html" target="_top"><code class="computeroutput"><screen></code></a> tag around text that has been wrapped by combinations of <a class="ulink" href="http://docbook.org/tdg/en/html/computeroutput.html" target="_top"><code class="computeroutput"><computeroutput></code></a> and <a class="ulink" href="http://docbook.org/tdg/en/html/userinput.html" target="_top"><strong class="userinput"><code><userinput></code></strong></a> -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-links"></a>Links</h3></div></div></div><p> - <a class="indexterm" name="idp140592100322072"></a> +</p> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-links"></a>Links</h3></div></div></div> + + + <p> + <a class="indexterm" name="idp140623175460280"></a> Linking falls into two different categories: inside the book you're making and outside: - </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>1. Inside linking, cross-referencing other parts of your book</strong></span></span></dt><dd><p> + </p> + + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>1. Inside linking, cross-referencing other parts of your book</strong></span></span></dt><dd><p> By having unique <code class="computeroutput">id</code>'s you can cross-reference any part of your book with a simple tag, regardless of where that part is. - </p><p><a class="indexterm" name="idp140592100325384"></a>Check out how I link to a subsection of the Developer's Guide:</p><p>Put this in your XML:</p><pre class="programlisting"> + </p> + + <p><a class="indexterm" name="idp140623175394568"></a>Check out how I link to a subsection of the Developer's Guide:</p> + + + <p>Put this in your XML:</p> + +<pre class="programlisting"> - Find information about creating a package in <xref linkend="packages-making-a-package"></xref>. -</pre><p>And the output is:</p><pre class="programlisting"> +</pre> + + <p>And the output is:</p> + +<pre class="programlisting"> - Find information about creating a package in <a class="xref" href="packages.html#packages-making-a-package" title="Making a Package">Making a Package</a>. -</pre><p> +</pre> + + <p> Note that even though this is an empty tag, you have to either: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> Provide the end-tag, <code class="computeroutput"></xref></code>, or - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Put a slash before the ending-bracket: <code class="computeroutput"><xref linkend="blahblah"/></code> - </p></li></ol></div><p>If the section you link to hasn't a specified <code class="computeroutput">xreflabel</code>-attribute, - the link is going to look like this:</p><p>Put this in your XML:</p><pre class="programlisting"> + </p> + </li></ol></div> + + <p>If the section you link to hasn't a specified <code class="computeroutput">xreflabel</code>-attribute, + the link is going to look like this:</p> + + + <p>Put this in your XML:</p> +<pre class="programlisting"> -Find information about what a package looks like in <xref linkend="packages-looks"></xref>. -</pre><p>And the output is:</p><pre class="programlisting"> +</pre> + + <p>And the output is:</p> + +<pre class="programlisting"> - Find information about what a package looks like in <a class="xref" href="packages.html#packages-looks" title="What a Package Looks Like">the section called “What a Package Looks Like”</a>. -</pre><p> +</pre> + + + <p> Note that since I haven't provided an <code class="computeroutput">xreflabel</code> for the subsection, <code class="computeroutput">packages-looks</code>, the parser will try its best to explain where the link takes you. - </p></dd><dt><span class="term"><span class="strong"><strong>2. Linking outside the documentation</strong></span></span></dt><dd><p> - <a class="indexterm" name="idp140592102378600"></a> + </p> + + + </dd><dt><span class="term"><span class="strong"><strong>2. Linking outside the documentation</strong></span></span></dt><dd><p> + <a class="indexterm" name="idp140623175410504"></a> If you're hyper-linking out of the documentation, it works almost the same way as HTML - the tag is just a little different (<a class="ulink" href="http://docbook.org/tdg/en/html/ulink.html" target="_top"><code class="computeroutput"><ulink></code></a>): - </p><pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre><p> + </p> + <pre class="programlisting"><ulink url="http://www.oracle.com/">Oracle Corporation</ulink></pre> + + <p> + ....will create a hyper-link to Oracle in the HTML-version of the documentation. - </p><p><span class="strong"><strong>NOTE:</strong></span> Do NOT use + </p> + + <p><span class="strong"><strong>NOTE:</strong></span> Do NOT use ampersands in your hyperlinks. These are reserved for referencing <a class="ulink" href="http://www.docbook.org/tdg/en/html/ch01.html#s-entities" target="_top">entities</a>. To create an ampersand, use the entity <code class="code">&amp;</code> - </p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-graphics"></a>Graphics</h3></div></div></div><p> + </p></dd></dl></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-graphics"></a>Graphics</h3></div></div></div> + + + <p> <span class="emphasis"><em> <span class="strong"><strong>Note:</strong></span> The graphics guidelines are not written in stone. Use another valid approach if it works better for you. </em></span> - </p><p> - <a class="indexterm" name="idp140592102265016"></a> + </p> + + <p> + <a class="indexterm" name="idp140623175419144"></a> To insert a graphic we use the elements <a class="ulink" href="http://docbook.org/tdg/en/html/mediaobject.html" target="_top"><code class="computeroutput"><mediaobject></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/imageobject.html" target="_top"><code class="computeroutput"><imageobject></code></a>, @@ -828,7 +1061,9 @@ Two versions of all graphics are required. One for the Web (usually a JPEG or GIF), and a brief text description. The description becomes the ALT text. You can also supply a version for print (EPS). - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> <mediaobject> <imageobject> <imagedata fileref="images/rp-flow.gif" format="GIF" align="center"/> @@ -840,41 +1075,62 @@ <phrase>This is an image of the flow in the Request Processor</phrase> </textobject> </mediaobject> -</pre><p> +</pre> + + <p> Put your graphics in a separate directory ("images") and link to them only with relative paths. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-lists"></a>Lists</h3></div></div></div><p> - <a class="indexterm" name="idp140592100631192"></a> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-lists"></a>Lists</h3></div></div></div> + + + <p> + <a class="indexterm" name="idp140623175427256"></a> Here's how you make the DocBook equivalent of the three usual HTML-lists: - </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>1. How to make an <ul></strong></span></span></dt><dd><p> + </p> + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>1. How to make an <ul></strong></span></span></dt><dd><p> Making an unordered list is pretty much like doing the same thing in HTML - if you close your <code class="computeroutput"><li></code>, that is. The only differences are that each list item has to be wrapped in something more, such as <code class="computeroutput"><para></code>, and that the tags are called <a class="ulink" href="http://docbook.org/tdg/en/html/itemizedlist.html" target="_top"><code class="computeroutput"><itemizedlist></code></a> and <a class="ulink" href="http://docbook.org/tdg/en/html/listitem.html" target="_top"><code class="computeroutput"><listitem></code></a>: - </p><pre class="programlisting"> + </p> + +<pre class="programlisting"> <itemizedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </itemizedlist> -</pre></dd><dt><span class="term"><span class="strong"><strong>2. How to make an <ol></strong></span></span></dt><dd><p> +</pre> + + </dd><dt><span class="term"><span class="strong"><strong>2. How to make an <ol></strong></span></span></dt><dd><p> The ordered list is like the preceding, except that you use - <a class="ulink" href="http://docbook.org/tdg/en/html/orderedlist.html" target="_top"><code class="computeroutput"><orderedlist></code></a> instead:</p><pre class="programlisting"> + <a class="ulink" href="http://docbook.org/tdg/en/html/orderedlist.html" target="_top"><code class="computeroutput"><orderedlist></code></a> instead:</p> + + <pre class="programlisting"> <orderedlist> <listitem><para>Stuff goes here</para></listitem> <listitem><para>More stuff goes here</para></listitem> </orderedlist> -</pre></dd><dt><span class="term"><span class="strong"><strong>3. How to make a <dl></strong></span></span></dt><dd><p> +</pre> + + </dd><dt><span class="term"><span class="strong"><strong>3. How to make a <dl></strong></span></span></dt><dd><p> This kind of list is called a <code class="computeroutput">variablelist</code> and these are the tags you'll need to make it happen: <a class="ulink" href="http://docbook.org/tdg/en/html/variablelist.html" target="_top"><code class="computeroutput"><variablelist></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/varlistentry.html" target="_top"><code class="computeroutput"><varlistentry></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/term.html" target="_top"><code class="computeroutput"><term></code></a> and - <a class="ulink" href="http://docbook.org/tdg/en/html/listitem.html" target="_top"><code class="computeroutput"><listitem></code></a>:</p><pre class="programlisting"> + <a class="ulink" href="http://docbook.org/tdg/en/html/listitem.html" target="_top"><code class="computeroutput"><listitem></code></a>:</p> + + <pre class="programlisting"> <variablelist> <varlistentry> @@ -888,12 +1144,24 @@ </varlistentry> </variablelist> -</pre></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-tables"></a>Tables</h3></div></div></div><p> - <a class="indexterm" name="idp140592108147992"></a> +</pre> + + </dd></dl></div> + + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-tables"></a>Tables</h3></div></div></div> + + + <p> + <a class="indexterm" name="idp140623175373160"></a> DocBook supports several types of tables, but in most cases, the <a class="ulink" href="http://docbook.org/tdg/en/html/informaltable.html" target="_top"><code class="computeroutput"><informaltable></code></a> is enough: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> <informaltable frame="all"> <tgroup cols="3"> <tbody> @@ -919,62 +1187,128 @@ </tbody> </tgroup> </informaltable> -</pre><p> +</pre> + + <p> With our current XSL-style-sheet, the output of the markup above will be a simple HTML-table: - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td>a1</td><td>b1</td><td>c1</td></tr><tr><td>a2</td><td>b2</td><td>c2</td></tr><tr><td>a3</td><td>b3</td><td>c3</td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col></colgroup><tbody><tr><td>a1</td><td>b1</td><td>c1</td></tr><tr><td>a2</td><td>b2</td><td>c2</td></tr><tr><td>a3</td><td>b3</td><td>c3</td></tr></tbody></table> + </div> + + + <p> If you want cells to span more than one row or column, it gets a bit more complicated - check out <a class="ulink" href="http://docbook.org/tdg/en/html/table.html" target="_top"><code class="computeroutput"><table></code></a> for an example. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-emphasis"></a>Emphasis</h3></div></div></div><p> - <a class="indexterm" name="idp140592101941752"></a> + </p> + </div> + + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-emphasis"></a>Emphasis</h3></div></div></div> + + + <p> + <a class="indexterm" name="idp140623175386280"></a> Our documentation uses two flavors of emphasis - italics and bold type. DocBook uses one - <a class="ulink" href="http://docbook.org/tdg/en/html/emphasis.html" target="_top"><code class="computeroutput"><emphasis></code></a>. - </p><p> + </p> + + <p> The <code class="computeroutput"><emphasis></code> tag defaults to italics when parsed. If you're looking for emphasizing with bold type, use <code class="computeroutput"><emphasis role="strong"></code>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-indexing"></a>Indexing Your DocBook Documents</h3></div></div></div><p> + </p> + + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-indexing"></a>Indexing Your DocBook Documents</h3></div></div></div> + + + <p> Words that are marked as index-words are referenced in an index in the final, parsed document. - </p><p> + </p> + + <p> Use <a class="ulink" href="http://docbook.org/tdg/en/html/indexterm.html" target="_top"><code class="computeroutput"><indexterm></code></a>, <a class="ulink" href="http://docbook.org/tdg/en/html/primary.html" target="_top"><code class="computeroutput"><primary></code></a> and <a class="ulink" href="http://docbook.org/tdg/en/html/secondary.html" target="_top"><code class="computeroutput"><secondary></code></a> for this. See these links for an explanation. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-converting"></a>Converting to HTML</h3></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This section is quoted almost verbatim from the LDP Author Guide.</p></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="dbprimer-converting"></a>Converting to HTML</h3></div></div></div> + + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + <p>This section is quoted almost verbatim from the LDP Author Guide.</p> + </div> + + <p> Once you have the <a class="xref" href="docbook-primer.html#dbprimer-validation" title="Tools">Docbook Tools</a> installed, you can convert your xml documents to HTML or other formats. - </p><p> + </p> + + <p> With the DocBook XSL stylesheets, generation of multiple files is controlled by the stylesheet. If you want to generate a single file, you call one stylesheet. If you want to generate multiple files, you call a different stylesheet. - </p><p> + </p> + + <p> To generate a single HTML file from your DocBook XML file, use the command: - </p><pre class="screen"> + </p> + + <pre class="screen"> <code class="computeroutput">bash$ </code><strong class="userinput"><code>xsltproc -o outputfilename.xml /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/html.xsl filename.xml</code></strong> -</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> +</pre> + + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + <p> This example uses Daniel Veillard's <span class="strong"><strong>xsltproc</strong></span> command available as part of libxslt from <a class="ulink" href="http://www.xmlsoft.org/XSLT/" target="_top">http://www.xmlsoft.org/XSLT/</a>. If you are using other XML processors such as Xalan or Saxon, you will need to change the command line appropriately. - </p></div><p> + </p> + </div> + + <p> To generate a set of linked HTML pages, with a separate page for each <chapter>, <sect1> or <appendix> tag, use the following command: - </p><pre class="screen"> + </p> + + <pre class="screen"> <code class="computeroutput">bash$ </code><strong class="userinput"><code>xsltproc /usr/share/sgml/docbook/stylesheet/xsl/nwalsh/html/chunk.xsl filename.xml</code></strong> -</pre><p> +</pre> + + <p> You could also look at the <a class="ulink" href="https://raw.githubusercontent.com/openacs/openacs-core/master/packages/acs-core-docs/www/xml/Makefile" target="_top">acs-core-docs Makefile</a> for examples of how these documents are generated. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-primer-further-reading"></a>Further Reading</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="http://www.xml.com/lpt/a/2002/07/31/xinclude.html" target="_top">Using Xinclude</a></p></li><li class="listitem"><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="db-primer-further-reading"></a>Further Reading</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><a class="ulink" href="http://www.xml.com/lpt/a/2002/07/31/xinclude.html" target="_top">Using Xinclude</a></p> + </li><li class="listitem"> + <p> The <a class="ulink" href="http://www.tldp.org/LDP/LDP-Author-Guide/html/index.html" target="_top">LDP Author Guide</a> has a lot of good information, a table of docbook elements and their "look" in HTML and lots of good links for tools. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> James Clark wrote <a class="link" href="nxml-mode.html" title="Using nXML mode in Emacs">nXML Mode</a>, an alternative to PSGML Mode. nXML Mode can validate a file as it is edited. @@ -990,10 +1324,13 @@ Converts docbook documents to a number of formats. <span class="emphasis"><em>NOTE: I only got these to work with Docbook SGML, NOT with Docbook XML. If you are able to make it work with our XML, please let us know.</em></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> AptConvert from <a class="ulink" href="http://www.pixware.fr/" target="_top">PIXware</a> is a Java editor that will produce DocBook documents and let you transform them into HTML and PDF for a local preview before you submit. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> In the process of transforming your HTML into XML, <a class="ulink" href="http://tidy.sourceforge.net/" target="_top">HTML tidy</a> can be a handy tool to make your HTML "regexp'able". @@ -1002,4 +1339,10 @@ script with directions</a> (now via archive.org) that gets you most of the way. - </p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="doc-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 13. Documentation Standards </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Using PSGML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li></ul></div> + </div> + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="doc-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 13. Documentation Standards </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Using PSGML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,10 +10,7 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="eng-standards-constraint-naming" id="eng-standards-constraint-naming"></a>Constraint naming -standard</h2></div></div></div><div class="authorblurb"> -<p>By Michael Bryzek</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +standard</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Michael Bryzek</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="eng-standards-constraint-naming-big-picture" id="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div></div><p>Constraint naming standard is important for one reason: The @@ -22,8 +19,8 @@ associate a particular constraint with our data model. This gives us two real advantages:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>We can quickly identify and fix any errors.</p></li><li class="listitem"><p>We can reliabily modify or drop constraints</p></li> -</ul></div><div>Why do we need a naming convention?</div><p> -<a class="ulink" href="https://docs.oracle.com/database/121/SQLRF/sql_elements008.htm#SQLRF00223" target="_top">Oracle limits names</a>, in general, to 30 +</ul></div><p> +<span class="phrase">Why do we need a naming convention?</span><a class="ulink" href="https://docs.oracle.com/database/121/SQLRF/sql_elements008.htm#SQLRF00223" target="_top">Oracle limits names</a>, in general, to 30 characters, which is hardly enough for a human readable constraint name.</p> </div><div class="sect2"> @@ -122,12 +119,13 @@ constraints is optional...</h3></div></div></div><p>People disagree on whether or not we should be naming not null constraints. So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not -a requirement.</p><div>About Naming the not null constraints</div><p>Though naming "not null" constraints doesn't help +a requirement.</p><p><span class="phrase">About Naming the not null +constraints</span></p><p>Though naming "not null" constraints doesn't help immeditately in error debugging (e.g. the error will say something like "Cannot insert null value into column"), we recommend naming not null constraints to be consistent in our -naming of all constraints.</p><div class="cvstag">($‌Id: constraint-naming.xml,v 1.6.14.3 -2017/06/16 17:19:52 gustafn Exp $)</div> +naming of all constraints.</p><p><span class="cvstag">($‌Id: constraint-naming.xml,v 1.7 +2017/08/07 23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 7 Aug 2017 23:47:49 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/eng-standards-constraint-naming.html 8 Nov 2017 09:42:10 -0000 1.50 @@ -1,32 +1,80 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Constraint naming standard</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="next" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-constraint-naming"></a>Constraint naming standard</h2></div></div></div><div class="authorblurb"><p>By Michael Bryzek</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Constraint naming standard</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-versioning.html" title="Release Version Numbering"><link rel="next" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-constraint-naming"></a>Constraint naming standard</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Michael Bryzek</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-big-picture"></a>The Big Picture</h3></div></div></div> + + +<p> Constraint naming standard is important for one reason: The SYS_* name oracle assigns to unnamed constraints is not very understandable. By correctly naming all contraints, we can quickly associate a particular constraint with our data model. This gives us two real advantages: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> We can quickly identify and fix any errors. </p></li><li class="listitem"><p> We can reliabily modify or drop constraints </p></li></ul></div><p> -</p><div>Why do we need a naming convention? </div><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> We can quickly identify and fix any errors. </p></li><li class="listitem"><p> We can reliabily modify or drop constraints </p></li></ul></div> + +<p> +<span class="phrase">Why do we need a naming convention? </span> <a class="ulink" href="https://docs.oracle.com/database/121/SQLRF/sql_elements008.htm#SQLRF00223" target="_top">Oracle limits names</a>, in general, to 30 characters, which is hardly enough for a human readable constraint name. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-abbr"></a>Abbreviations</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-abbr"></a>Abbreviations</h3></div></div></div> + + +<p> We propose the following naming convention for all constraints, with the following abbreviations taken from Oracle Docs. Note that we shortened all of the constraint abbrevations to two characters to save room. -</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Constraint type</th><th>Abbreviation</th></tr></thead><tbody><tr><td>references (foreign key)</td><td>fk</td></tr><tr><td>unique</td><td>un</td></tr><tr><td>primary key</td><td>pk</td></tr><tr><td>check</td><td>ck</td></tr><tr><td>not null</td><td>nn</td></tr><tr><td>index</td><td>idx</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-format"></a>Format of constraint name</h3></div></div></div><p> +</p> + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col></colgroup><thead><tr><th>Constraint type</th><th>Abbreviation</th></tr></thead><tbody><tr><td>references (foreign key)</td><td>fk</td></tr><tr><td>unique</td><td>un</td></tr><tr><td>primary key</td><td>pk</td></tr><tr><td>check</td><td>ck</td></tr><tr><td>not null</td><td>nn</td></tr><tr><td>index</td><td>idx</td></tr></tbody></table></div> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-format"></a>Format of constraint name</h3></div></div></div> + + +<p> <table name>_<column_name>_<constraint abbreviation> -</p><p> +</p> + +<p> In reality, this won't be possible because of the character limitation on names inside oracle. When the name is too long, we will follow these two steps in order: -</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). -</p></li><li class="listitem"><p> Truncate the column name until it fits.</p></li></ol></div><p> +</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> Abbreviate the table name with the table's initials (e.g. users -> u and users_contact -> uc). +</p></li><li class="listitem"><p> Truncate the column name until it fits.</p></li></ol></div> + +<p> If the constraint name is still too long, you should consider rewriting your entire data model :) -</p><p><span class="strong"><strong>Notes:</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints</p></li><li class="listitem"><p> If you are defining a multi column constraint, try to truncate the two column names evenly </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-example"></a>Example</h3></div></div></div><pre class="programlisting"> +</p> + +<p><span class="strong"><strong>Notes:</strong></span></p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> If you have to abbreviate the table name for one of the constraints, abbreviate it for all the constraints</p></li><li class="listitem"><p> If you are defining a multi column constraint, try to truncate the two column names evenly </p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-example"></a>Example</h3></div></div></div> + + + +<pre class="programlisting"> create table example_topics ( topic_id integer constraint example_topics_topic_id_pk @@ -50,11 +98,20 @@ constraint cne_example_id_one_line_unq unique(example_id, one_line_description) ); -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-pk"></a>Why it's good to name primary keys</h3></div></div></div><p> +</pre> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-pk"></a>Why it's good to name primary keys</h3></div></div></div> + + +<p> Naming primary keys might not have any obvious advantages. However, here's an example where naming the primary key really helps (and this is by no means a rare case! -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> SQL> set autotrace traceonly explain; @@ -68,19 +125,37 @@ 2 1 TABLE ACCESS (FULL) OF 'CONSTRAINT_NAMING_EXAMPLE' 3 1 INDEX (UNIQUE SCAN) OF 'EXAMPLE_TOPICS_TOPIC_ID_PK' (UNI QUE) -</pre><p> +</pre> + +<p> Isn't it nice to see "EXAMPLE_TOPICS_TOPIC_ID_PK" in the trace and know exactly which table oracle is using at each step? -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-nn"></a>Naming not null constraints is optional...</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-constraint-naming-nn"></a>Naming not null constraints is optional...</h3></div></div></div> + + +<p> People disagree on whether or not we should be naming not null constraints. So, if you want to name them, please do so and follow the above naming standard. But, naming not null constraints is not a requirement. -</p><p> -</p><div>About Naming the not null constraints</div><p> -</p><p> +</p> + +<p> +<span class="phrase">About Naming the not null constraints</span> +</p> +<p> Though naming "not null" constraints doesn't help immeditately in error debugging (e.g. the error will say something like "Cannot insert null value into column"), we recommend naming not null constraints to be consistent in our naming of all constraints. -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr><tr><td width="40%" align="left">Release Version Numbering </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> ACS File Naming and Formatting Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-versioning.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-filenaming.html">Next</a></td></tr><tr><td width="40%" align="left">Release Version Numbering </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> ACS File Naming and Formatting Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,10 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="eng-standards-filenaming" id="eng-standards-filenaming"></a>ACS -File Naming and Formatting Standards</h2></div></div></div><div class="authorblurb"> -<p>By Michael Yoon and Aurelius Prochazka</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>To ensure consistency (and its collateral benefit, +File Naming and Formatting Standards</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Michael Yoon and Aurelius +Prochazka</span></p><span style="color: red"></authorblurb></span><p>To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas:</p><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -103,7 +101,7 @@ <p> Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp </p> -</pre><p>This can be at the top or bottom of the file.</p><div>Using ad_page_contract</div><p>For non-library Tcl files (those not in the private Tcl +</pre><p>This can be at the top or bottom of the file.</p><p><span class="phrase">Using ad_page_contract</span></p><p>For non-library Tcl files (those not in the private Tcl directory), use <a class="link" href="tcl-doc" title="ad_page_contract"><code class="computeroutput">ad_page_contract</code></a> after the file path comment (this supersedes set_the_usual_form_variables and ad_return_complaint). Here is an example of using ad_page_contract, @@ -150,7 +148,7 @@ does not generate QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete.</p></li> -</ul></div><div>Using ad_library</div><p>For shared Tcl library files, use <a class="link" href="tcl-doc" title="ad_library"><code class="computeroutput">ad_library</code></a> after the file path comment. +</ul></div><p><span class="phrase">Using ad_library</span></p><p>For shared Tcl library files, use <a class="link" href="tcl-doc" title="ad_library"><code class="computeroutput">ad_library</code></a> after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like <code class="computeroutput">ad_page_contract</code>. Don't forget to put the \@cvs-id in there. Here is an example of @@ -163,7 +161,7 @@ \@author John Doe (jdoe\@example.com) \@cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp } -</pre><div>Non-Tcl Files</div><p>For SQL and other non-Tcl source files, the following file +</pre><p><span class="phrase">Non-Tcl Files</span></p><p>For SQL and other non-Tcl source files, the following file header structure is recommended:</p><pre class="programlisting"> -- <span class="emphasis"><em>path relative to the ACS root directory</em></span> -- @@ -216,8 +214,8 @@ </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="eng-standards-filenaming-tcllib" id="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div></div><p>Further standards for Tcl library files are under discussion; we -plan to include naming conventions for procs.</p><div class="cvstag">($‌Id: filenaming.xml,v 1.7.2.3 2017/04/21 -15:07:52 gustafn Exp $)</div> +plan to include naming conventions for procs.</p><p><span class="cvstag">($‌Id: filenaming.xml,v 1.8 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 7 Aug 2017 23:47:49 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/eng-standards-filenaming.html 8 Nov 2017 09:42:10 -0000 1.50 @@ -1,64 +1,149 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ACS File Naming and Formatting Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div></div><div class="authorblurb"><p>By Michael Yoon and Aurelius Prochazka</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>ACS File Naming and Formatting Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-constraint-naming.html" title="Constraint naming standard"><link rel="next" href="eng-standards-plsql.html" title="PL/SQL Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-filenaming"></a>ACS File Naming and Formatting Standards</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Michael Yoon and Aurelius Prochazka</p> +</authorblurb></span> + +<p> To ensure consistency (and its collateral benefit, maintainability), we define and adhere to standards in the following areas: -</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div></div><p> +</p> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-nomenclature"></a>File Nomenclature</h3></div></div></div> + + +<p> Usually we organize our files so that they mainly serve one of the following three purposes: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> displaying objects and their properties</p></li><li class="listitem"><p> manipulating or acting on objects in some way (by creating, editing, linking, etc)</p></li><li class="listitem"><p> housing procedures, packages, data models and other prerequisite code -Essentially, we want our files named in a fashion that reflects their purpose.</p></li></ul></div><p> +</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> displaying objects and their properties</p></li><li class="listitem"><p> manipulating or acting on objects in some way (by creating, editing, linking, etc)</p></li><li class="listitem"><p> housing procedures, packages, data models and other prerequisite code +Essentially, we want our files named in a fashion that reflects their purpose.</p></li></ul></div> + +<p> + Under the page root: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For naming files that enable a specific action on an object, use this format:</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For naming files that enable a specific action on an object, use this format:</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p> <span class="emphasis"><em><code class="computeroutput">object-verb.extension</code></em></span> -</p></blockquote></div><p> +</p> +</blockquote></div> + +<p> For example, the page to erase a user's portrait from the database is <code class="computeroutput">/admin/users/portrait-erase.tcl</code>. -</p></li><li class="listitem"><p>However, modules typically deal with only one primary type of object - +</p> +</li><li class="listitem"><p>However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages for the Bookmarks module live in the <code class="computeroutput">/bookmarks/</code> directory, and so there is no need to name the bookmark editing page with a redundant url: <code class="computeroutput">/bookmarks/bookmark-edit.tcl</code>. Instead, we omit the object type, and use this convention: -</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> +<div class="blockquote"><blockquote class="blockquote"> +<p> <span class="emphasis"><em><code class="computeroutput">verb.extension</code></em></span> -</p></blockquote></div><p> +</p> +</blockquote></div> + +<p> Thus, the page to edit a bookmark is <code class="computeroutput">/bookmarks/edit.tcl</code>. -</p></li><li class="listitem"><p>For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> +</li><li class="listitem"><p>For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p> <code class="computeroutput">one.extension</code> -</p></blockquote></div><p> +</p> +</blockquote></div> + +<p> For example, the page to view one bookmark is <code class="computeroutput">/bookmarks/one.tcl</code>. Note that no verb is necessary for display-type files. -</p></li><li class="listitem"><p>Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> +</li><li class="listitem"><p>Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p> <span class="emphasis"><em><code class="computeroutput">object.extension</code></em></span> -</p></blockquote></div><p> +</p> +</blockquote></div> + +<p> For example, the page to view the properties of an ecommerce product is <code class="computeroutput">/ecommerce/product.tcl</code>. -</p></li><li class="listitem"><p>For naming files in a page flow, use the convention:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="emphasis"><em><code class="computeroutput">foobar.extension</code></em></span> (Step 1)</p></li><li class="listitem"><p><span class="emphasis"><em><code class="computeroutput">foobar-2.extension</code></em></span> (Step 2)</p></li><li class="listitem"><p>...</p></li><li class="listitem"><p><span class="emphasis"><em><code class="computeroutput">foobar-N.extension</code></em></span> (Step N)</p></li></ul></div><p> +</p> +</li><li class="listitem"><p>For naming files in a page flow, use the convention:</p> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="emphasis"><em><code class="computeroutput">foobar.extension</code></em></span> (Step 1)</p></li><li class="listitem"><p><span class="emphasis"><em><code class="computeroutput">foobar-2.extension</code></em></span> (Step 2)</p></li><li class="listitem"><p>...</p></li><li class="listitem"><p><span class="emphasis"><em><code class="computeroutput">foobar-N.extension</code></em></span> (Step N)</p></li></ul></div> + + +<p> where <span class="emphasis"><em><code class="computeroutput">foobar</code></em></span> is determined by the above rules. -</p><p> +</p> + +<p> Typically, we use a three-step page flow when taking user information: -</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Present a form to the user</p></li><li class="listitem"><p>Present a confirmation page to the user</p></li><li class="listitem"><p>Perform the database transaction, then redirect</p></li></ol></div></li><li class="listitem"><p>Put data model files in <code class="computeroutput">/www/doc/sql</code>, and name them +</p> + + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Present a form to the user</p></li><li class="listitem"><p>Present a confirmation page to the user</p></li><li class="listitem"><p>Perform the database transaction, then redirect</p></li></ol></div> + +</li><li class="listitem"><p>Put data model files in <code class="computeroutput">/www/doc/sql</code>, and name them for the modules towards which they are used: -</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p> <span class="emphasis"><em><code class="computeroutput">module</code></em></span><code class="computeroutput">.sql</code> -</p></blockquote></div></li></ul></div><p> +</p> +</blockquote></div> +</li></ul></div> + +<p> In the Tcl library directory: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For files that contain module-specific procedures, use the -convention:</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For files that contain module-specific procedures, use the +convention:</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p> <span class="emphasis"><em><code class="computeroutput">module</code></em></span><code class="computeroutput">-procs.tcl</code> -</p></blockquote></div></li><li class="listitem"><p>For files that contain procedures that are part of the core ACS, -use the convention:</p><div class="blockquote"><blockquote class="blockquote"><p> +</p> +</blockquote></div> +</li><li class="listitem"><p>For files that contain procedures that are part of the core ACS, +use the convention:</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p> <code class="computeroutput">ad-</code><span class="emphasis"><em>description</em></span><code class="computeroutput">-procs.tcl</code> -</p></blockquote></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div></div><p> +</p> +</blockquote></div> +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-urls"></a>URLs</h3></div></div></div> + + +<p> File names also appear <span class="emphasis"><em>within</em></span> pages, as linked URLs and form targets. When they do, always use <a class="ulink" href="rp-design" target="_top">abstract URLs</a> (e.g., <code class="computeroutput">user-delete</code> instead of <code class="computeroutput">user-delete.tcl</code>), because they enhance maintainability. -</p><p> +</p> + +<p> Similarly, when linking to the index page of a directory, do not explicitly name the index file (<code class="computeroutput">index.tcl</code>, <code class="computeroutput">index.adp</code>, <code class="computeroutput">index.html</code>, etc.). Instead, use @@ -67,40 +152,71 @@ (<code class="computeroutput">/top-level-dir/</code>). If linking to the directory in which the page is located, use the empty string (<code class="computeroutput">""</code>), which browsers will resolve correctly. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-headers"></a>File Headers and Page Input</h3></div></div></div> + + +<p> Include the appropriate standard header in all scripts. The first line should be a comment specifying the file path relative to the ACS root directory. e.g. -</p><div class="blockquote"><blockquote class="blockquote"><p><code class="computeroutput"> +</p> + +<div class="blockquote"><blockquote class="blockquote"><p><code class="computeroutput"> # /www/index.tcl -</code></p></blockquote></div><p> +</code></p></blockquote></div> + +<p> or -</p><div class="blockquote"><blockquote class="blockquote"><p><code class="computeroutput"> +</p> + +<div class="blockquote"><blockquote class="blockquote"><p><code class="computeroutput"> # /tcl/module-defs.tcl -</code></p></blockquote></div><p> +</code></p></blockquote></div> + +<p> For static content files (html or adp), include a CVS identification tag as a comment at the top of the file, e.g. -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> <!-- file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp --> -</pre><p> +</pre> + +<p> In addition, all static HTML files, documentation and other pages should have a visible CVS ID stamp, at least during development. These can be removed at release times. This should take the form of a line like this: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> <p> Last Modified: file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp </p> -</pre><p> +</pre> + +<p> This can be at the top or bottom of the file. -</p><div>Using ad_page_contract</div><p> +</p> + + +<p><span class="phrase">Using ad_page_contract</span></p> + +<p> For non-library Tcl files (those not in the private Tcl directory), use <a class="link" href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract"><code class="computeroutput">ad_page_contract</code></a> after the file path comment (this supersedes set_the_usual_form_variables and ad_return_complaint). Here is an example of using ad_page_contract, which serves both documentation and page input validation purposes: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> # www/register/user-login-2.tcl ad_page_contract { @@ -118,9 +234,15 @@ {return_url {[ad_pvt_home]}} {persistent_cookie_p f} } -</pre><p> +</pre> + + + +<p> Salient features of <code class="computeroutput">ad_page_contract</code>: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A mandatory documentation string is the first argument. This has +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A mandatory documentation string is the first argument. This has the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the received variables and any necessary explanations. </p></li><li class="listitem"><p>The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags @@ -140,13 +262,20 @@ QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete. -</p></li></ul></div><div>Using ad_library</div><p> +</p></li></ul></div> + +<p><span class="phrase">Using ad_library</span></p> + +<p> For shared Tcl library files, use <a class="link" href="tcl-doc.html#tcl-doc-ad-library" title="ad_library"><code class="computeroutput">ad_library</code></a> after the file path comment. Its only argument is a doc_string in the standard (javadoc-style) format, like <code class="computeroutput">ad_page_contract</code>. Don't forget to put the @cvs-id in there. Here is an example of using ad_library: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> # tcl/wp-defs.tcl ad_library { @@ -155,9 +284,17 @@ @author John Doe (jdoe@example.com) @cvs-id file-standards.html,v 1.2 2000/09/19 07:22:45 ron Exp } -</pre><div>Non-Tcl Files</div><p> +</pre> + + +<p><span class="phrase">Non-Tcl Files</span></p> + +<p> For SQL and other non-Tcl source files, the following file header structure is recommended: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> -- <span class="emphasis"><em>path relative to the ACS root directory</em></span> -- -- <span class="emphasis"><em>brief description of the file's purpose</em></span> @@ -166,18 +303,33 @@ -- <span class="emphasis"><em>created</em></span> -- -- <a class="ulink" href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id$</a> -</pre><p> +</pre> + + +<p> Of course, replace "<code class="computeroutput">--</code>" with the comment delimiter appropriate for the language in which you are programming. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-pages"></a>Page Construction</h3></div></div></div> + + +<p> Construct the page as one Tcl variable (name it <code class="computeroutput">page_content</code>), and then send it back to the browser with one call to <code class="computeroutput">doc_return</code>, which will call db_release_unused_handles prior to executing ns_return, effectively combining the two operations. -</p><p> +</p> + +<p> For example: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> set page_content "<span class="emphasis"><em>Page Title</em></span>] <h2><span class="emphasis"><em>Page Title</em></span></h2> @@ -199,7 +351,11 @@ [ad_footer]" doc_return 200 text/html $page_content -</pre><p> +</pre> + + + +<p> The old convention was to call <code class="computeroutput">ReturnHeaders</code> and then <code class="computeroutput">ns_write</code> for each distinct chunk of the page. This approach has the disadvantage of tying up a scarce and valuable @@ -212,11 +368,26 @@ first, so that the user is not left to stare at an empty page while the query is running.) -</p><p> +</p> + +<p> Local procedures (i.e., procedures defined and used only within one page) should be prefixed with "<span class="emphasis"><em><code class="computeroutput">module_</code></em></span>" and should be used rarely, only when they are exceedingly useful. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-filenaming-tcllib"></a>Tcl Library Files</h3></div></div></div> + + +<p> Further standards for Tcl library files are under discussion; we plan to include naming conventions for procs. -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr><tr><td width="40%" align="left">Constraint naming standard </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> PL/SQL Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-constraint-naming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-plsql.html">Next</a></td></tr><tr><td width="40%" align="left">Constraint naming standard </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> PL/SQL Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="variables" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="eng-standards-plsql" id="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div></div><div class="authorblurb"> -<p>By Richard Li and Yon Feldman</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Like any other part of the OpenACS, PL/SQL (or pl/pgsql) code +<a name="eng-standards-plsql" id="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Richard Li and Yon +Feldman</span></p><span style="color: red"></authorblurb></span><p>Like any other part of the OpenACS, PL/SQL (or pl/pgsql) code must be maintainable and professional. This means that it must be consistent and therefore must abide by certain standards. The standards will ensure that our product will be useful long after @@ -142,8 +140,8 @@ browsers. This means that we should try to make it as consistent as possible to all source code readers.</p></li><li class="listitem"><p>Lowercase everything, with the exception of %TYPE and %ROWTYPE.</p></li> -</ol></div><div class="cvstag">($‌Id: plsql.xml,v 1.6.14.3 2017/06/16 17:19:52 -gustafn Exp $)</div> +</ol></div><p><span class="cvstag">($‌Id: plsql.xml,v 1.7 2017/08/07 23:47:54 +gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 7 Aug 2017 23:47:49 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/eng-standards-plsql.html 8 Nov 2017 09:42:10 -0000 1.51 @@ -1,17 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>PL/SQL Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="next" href="variables.html" title="Variables"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="variables.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div></div><div class="authorblurb"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>PL/SQL Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-filenaming.html" title="ACS File Naming and Formatting Standards"><link rel="next" href="variables.html" title="Variables"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="variables.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-plsql"></a>PL/SQL Standards</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p> By Richard Li and Yon Feldman </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +</authorblurb></span> + +<p> Like any other part of the OpenACS, PL/SQL (or pl/pgsql) code must be maintainable and professional. This means that it must be consistent and therefore must abide by certain standards. The standards will ensure that our product will be useful long after the current people building and maintaining it are around. Following are some standards and guidelines that will help us achieve this goal: -</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-plsql-general"></a>General</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> +</p> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-plsql-general"></a>General</h3></div></div></div> + + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> All PL/SQL code must be well documented. We must write code that is maintainable by others, this is especially true in our case because we are building an open source toolkit than anyone can @@ -23,7 +33,14 @@ as is possible given the nature of team development. This means carrying style and other conventions suchs as naming within an application, not just within one file. - </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-plsql-code"></a>Code</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p></li></ol></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-plsql-code"></a>Code</h3></div></div></div> + + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> Encapsulation of related fuctionality is key to maintainability and upgradeability of our software. Try to bundle your code into <a class="ulink" href="https://docs.oracle.com/database/121/LNPLS/packages.htm#LNPLS009" target="_top">packages</a> @@ -33,7 +50,9 @@ When creating functions or procedures use the following template, it demonstrates most of the guidelines set forth in this document that correspond to functions and procedures: - </p><pre class="programlisting"> + </p> + +<pre class="programlisting"> create or replace procedure|function <proc_or_func_name> ( <param_1> in|out|inout <datatype>, @@ -53,7 +72,9 @@ / show errors -</pre></li><li class="listitem"><p> +</pre> + + </li><li class="listitem"><p> Always use <code class="computeroutput">create or replace procedure|function <proc_or_func_name></code>. It makes reloading packages much easier and painless to someone who is upgrading or fixing a bug. @@ -70,8 +91,10 @@ Name parameters as simply as possible, i.e., use the column name if the parameter corresponds to a table column. We're deprecating the v_* and *_in syntax in favor of named parameters notation: - </p><pre class="programlisting"> + </p> +<pre class="programlisting"> + <code class="computeroutput"> acs_user.create(first_names => 'Jane', last_name => 'Doe', etc.) </code> @@ -80,15 +103,19 @@ acs_user.create(first_names_in => 'Jane', last_name_in => 'Doe', etc.) </code> -</pre><p> +</pre> + +<p> To achieve this we must fully qualify arguments passed into procedures or functions when using them inside a SQL statement. This will get rid of any ambiguities in your code, i.e. it will tell the parser when you want the value of the column and when you want the value from the local variable. Here is an example: -</p><pre class="programlisting"> +</p> +<pre class="programlisting"> + create or replace package body mypackage . . @@ -107,7 +134,9 @@ / show errors -</pre></li><li class="listitem"><p> +</pre> + + </li><li class="listitem"><p> Explicitly designate each parameter as "in," "out," or "inout." </p></li><li class="listitem"><p> Each parameter should be on its own line, with a tab after the @@ -121,8 +150,10 @@ </p></li><li class="listitem"><p> All <code class="computeroutput">new</code> functions (e.g., <code class="computeroutput">acs_object.new, party.new,</code> etc.) should optionally accept an ID: - </p><pre class="programlisting"> + </p> +<pre class="programlisting"> + <code class="computeroutput"> create or replace package acs_object as @@ -136,20 +167,38 @@ ) return acs_objects.object_id%TYPE; </code> -</pre><p> +</pre> + +<p> takes the optional argument <code class="computeroutput">object_id</code>. Do this to allow people to use the same API call when they are doing double click protection, that is, they have already gotten an <code class="computeroutput">object_id</code> and now they want to create the object with that <code class="computeroutput">object_id</code>. - </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-style"></a>Style</h3></div></div></div><p> + </p></li></ol></div> + + </div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-style"></a>Style</h3></div></div></div> + + +<p> Some general style guidelines to follow for the purpose of consistency across applications. -</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> +</p> + + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> Standard indentation is 4 spaces. Our PL/SQL code is not only viewable in the SQL files but also through our SQL and PL/SQL browsers. This means that we should try to make it as consistent as possible to all source code readers. </p></li><li class="listitem"><p> Lowercase everything, with the exception of %TYPE and %ROWTYPE. - </p></li></ol></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="variables.html">Next</a></td></tr><tr><td width="40%" align="left">ACS File Naming and Formatting Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Variables</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p></li></ol></div> + +<p><span class="cvstag">($Id$)</span></p> + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-filenaming.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="variables.html">Next</a></td></tr><tr><td width="40%" align="left">ACS File Naming and Formatting Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Variables</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,11 +9,11 @@ rightLink="eng-standards-constraint-naming" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="eng-standards-versioning" id="eng-standards-versioning"></a>Release Version Numbering</h2></div></div></div><div class="authorblurb"> -<div class="cvstag">($‌Id: eng-standards-versioning.xml,v 1.10.14.2 -2016/10/28 20:26:53 gustafn Exp $)</div><p>By Ron Henderson, Revised by Joel Aufrecht</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>OpenACS version numbers help identify at a high-level what is in +<a name="eng-standards-versioning" id="eng-standards-versioning"></a>Release Version Numbering</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red"><span class="cvstag">($‌Id: +eng-standards-versioning.xml,v 1.11 2017/08/07 23:47:54 gustafn Exp +$)</span></span></p><p>By Ron Henderson, Revised by Joel Aufrecht</p> +</authorblurb> +<p>OpenACS version numbers help identify at a high-level what is in a particular release and what has changed since the last release.</p><p>A "version number" is really just a string of the form:</p><div class="blockquote"><blockquote class="blockquote"><p> @@ -146,11 +146,11 @@ <a name="naming-upgrade-scripts" id="naming-upgrade-scripts"></a>Naming Database Upgrade Scripts</h3></div></div></div><p>Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.</p><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"><p>Upgrade scripts should be named <code class="computeroutput">/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>/sql/<span class="replaceable"><span class="replaceable">postgresql</span></span>/upgrade/upgrade-<span class="replaceable"><span class="replaceable">OLDVERSION</span></span>-<span class="replaceable"><span class="replaceable">NEWVERSION</span></span>.sql</code> +<li class="listitem"><p>Upgrade scripts should be named <code class="computeroutput">/packages/<em class="replaceable"><code>myfirstpackage</code></em>/sql/<em class="replaceable"><code>postgresql</code></em>/upgrade/upgrade-<em class="replaceable"><code>OLDVERSION</code></em>-<em class="replaceable"><code>NEWVERSION</code></em>.sql</code> </p></li><li class="listitem"><p>If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in -<code class="computeroutput">/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>.info</code>. So if +<code class="computeroutput">/packages/<em class="replaceable"><code>myfirstpackage</code></em>/<em class="replaceable"><code>myfirstpackage</code></em>.info</code>. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1.</p></li><li class="listitem"><p>If you are working on a pre-release version of a package, use Index: openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html,v diff -u -r1.52 -r1.53 --- openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 7 Aug 2017 23:47:49 -0000 1.52 +++ openacs-4/packages/acs-core-docs/www/eng-standards-versioning.html 8 Nov 2017 09:42:10 -0000 1.53 @@ -1,15 +1,50 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Release Version Numbering</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="cvs-guidelines.html" title="CVS Guidelines"><link rel="next" href="eng-standards-constraint-naming.html" title="Constraint naming standard"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-guidelines.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-versioning"></a>Release Version Numbering</h2></div></div></div><div class="authorblurb"><div class="cvstag">($Id$)</div><p>By Ron Henderson, Revised by Joel Aufrecht</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Release Version Numbering</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="cvs-guidelines.html" title="CVS Guidelines"><link rel="next" href="eng-standards-constraint-naming.html" title="Constraint naming standard"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="cvs-guidelines.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="eng-standards-versioning"></a>Release Version Numbering</h2></div></div></div> + +<span style="color: red"><authorblurb> +<p><span class="cvstag">($Id$)</span></p> + +<p>By Ron Henderson, Revised by Joel Aufrecht</p> +</authorblurb></span> + +<p> + OpenACS version numbers help identify at a high-level what is in a particular release and what has changed since the last release. -</p><p>A "version number" is really just a string of the form: -</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>major</em></span>.<span class="emphasis"><em>minor</em></span>.<span class="emphasis"><em>dot</em></span>[ <span class="emphasis"><em>milestone</em></span> ]</p></blockquote></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A <span class="emphasis"><em>major</em></span> number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.</p></li><li class="listitem"><p>A <span class="emphasis"><em>minor</em></span> change represents the addition of new functionality or changed UI.</p></li><li class="listitem"><p>A <span class="emphasis"><em>dot</em></span> holds only bug fixes and security patches. Dot releases are always recommended and safe. - </p></li><li class="listitem"><p>A <span class="emphasis"><em>milestone</em></span> marker indicates the state of the release:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="emphasis"><em>d</em></span>, for development, means the release is in active development and is not in its intended released form.</p></li><li class="listitem"><p><span class="emphasis"><em>a</em></span>, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.</p></li><li class="listitem"><p><span class="emphasis"><em>b</em></span>, for beta, means most severe bugs are fixed and end users can start trying the release.</p></li><li class="listitem"><p>Release Candidate builds (<span class="emphasis"><em>rc</em></span>) are believed to meet all of the criteria for release and can be installed on test instances of production systems.</p></li><li class="listitem"><p>Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.) - </p></li></ul></div><p>Milestone markers are numbered: d1, d2, ..., a1, b1, rc1, etc.</p></li></ul></div><p>A complete sequence of milestones between two releases: </p><pre class="programlisting">5.0.0 +</p> +<p>A "version number" is really just a string of the form: +</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>major</em></span>.<span class="emphasis"><em>minor</em></span>.<span class="emphasis"><em>dot</em></span>[ <span class="emphasis"><em>milestone</em></span> ]</p> +</blockquote></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>A <span class="emphasis"><em>major</em></span> number change indicates a fundamental change in the architecture of the system, e.g. OpenACS 3 to ACS 4. A major change is required if core backwards compatibility is broken, if upgrade is non-trivial, or if the platform changes substantially.</p> + </li><li class="listitem"> + <p>A <span class="emphasis"><em>minor</em></span> change represents the addition of new functionality or changed UI.</p> + </li><li class="listitem"> + <p>A <span class="emphasis"><em>dot</em></span> holds only bug fixes and security patches. Dot releases are always recommended and safe. + </p> + </li><li class="listitem"> + <p>A <span class="emphasis"><em>milestone</em></span> marker indicates the state of the release:</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p><span class="emphasis"><em>d</em></span>, for development, means the release is in active development and is not in its intended released form.</p> + </li><li class="listitem"> + <p><span class="emphasis"><em>a</em></span>, for alpha, means new development is complete and code checkins are frozen. Alpha builds should work well enough to be testable.</p> + </li><li class="listitem"> + <p><span class="emphasis"><em>b</em></span>, for beta, means most severe bugs are fixed and end users can start trying the release.</p> + </li><li class="listitem"> + <p>Release Candidate builds (<span class="emphasis"><em>rc</em></span>) are believed to meet all of the criteria for release and can be installed on test instances of production systems.</p> + </li><li class="listitem"> + <p>Final releases have no milestone marker. (Exception: In CVS, they are tagged with -final to differentiate them from branch tags.) + </p> + </li></ul></div> + <p>Milestone markers are numbered: d1, d2, ..., a1, b1, rc1, etc.</p> + </li></ul></div> +<p>A complete sequence of milestones between two releases: </p> +<pre class="programlisting">5.0.0 5.0.0rc2 5.0.0rc1 5.0.0b4 @@ -18,12 +53,16 @@ 5.0.0a3 5.0.0a1 5.0.0d1 -4.6.3</pre><p> +4.6.3</pre> + +<p> Version numbers are also recorded in the CVS repository so that the code tree can be restored to the exact state it was in for a particular release. To translate between a distribution tar file (acs-3.2.2.tar.gz) and a CVS tag, just swap '.' for '-'.The entire release history of the toolkit is recorded in the tags for the top-level <code class="computeroutput">readme.txt</code> file: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> > cvs log readme.txt RCS file: /usr/local/cvsroot/acs/readme.txt,v Working file: readme.txt @@ -55,23 +94,42 @@ total revisions: 13; selected revisions: 13 description: ... -</pre><p> +</pre> + +<p> In the future, OpenACS packages should follow this same convention on version numbers. -</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-transition-rules"></a>Transition Rules</h3></div></div></div><p>So what distinguishes an <span class="emphasis"><em>alpha</em></span> release from a <span class="emphasis"><em>beta</em></span> +</p> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-transition-rules"></a>Transition Rules</h3></div></div></div> + + + +<p>So what distinguishes an <span class="emphasis"><em>alpha</em></span> release from a <span class="emphasis"><em>beta</em></span> release? Or from a production release? We follow a specific set of rules for how OpenACS makes the transition from one state of maturity to -the next. These rules are fine-tuned with each release; an example is <a class="ulink" href="http://openacs.org/projects/openacs/5.0/milestones" target="_top">5.0.0 Milestones and Milestone Criteria</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-package-maturity"></a>Package Maturity</h3></div></div></div><p> +the next. These rules are fine-tuned with each release; an example is <a class="ulink" href="http://openacs.org/projects/openacs/5.0/milestones" target="_top">5.0.0 Milestones and Milestone Criteria</a></p> + +</div> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="eng-standards-package-maturity"></a>Package Maturity</h3></div></div></div> + + <p> Each package has a maturity level. Maturity level is recorded in the .info file for each major-minor release of OpenACS, and is set to the appropriate value for that release of the package. - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> <version ...> <provides .../> <requires .../> <maturity>1</maturity> <callbacks> ... - </pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <span class="strong"><strong>Level -1: + </pre> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <span class="strong"><strong>Level -1: Incompatible.</strong></span> This package is not supported for this platform and should not be expected to work. </p></li><li class="listitem"><p> <span class="strong"><strong>Level 0: New Submission.</strong></span> This is the default for packages that do @@ -93,10 +151,36 @@ Deprecated.</strong></span> The package was in some earlier version is use, but was probably replaced by a another package. The package description should point to a preferred version. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="naming-upgrade-scripts"></a>Naming Database Upgrade Scripts</h3></div></div></div><p>Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Upgrade scripts should be named <code class="computeroutput">/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>/sql/<span class="replaceable"><span class="replaceable">postgresql</span></span>/upgrade/upgrade-<span class="replaceable"><span class="replaceable">OLDVERSION</span></span>-<span class="replaceable"><span class="replaceable">NEWVERSION</span></span>.sql</code></p></li><li class="listitem"><p>If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in <code class="computeroutput">/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>.info</code>. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. - </p></li><li class="listitem"><p>If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use <code class="computeroutput">upgrade-2.0.1d3-2.0.1d4.sql</code>.</p></li><li class="listitem"><p>Database upgrades should be confined to development releases, not alpha or beta releases.</p></li><li class="listitem"><p> - Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.</p></li><li class="listitem"><p>Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.</p></li><li class="listitem"><p>The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in + </p></li></ul></div> +</div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="naming-upgrade-scripts"></a>Naming Database Upgrade Scripts</h3></div></div></div> + + <p>Database upgrade scripts must be named very precisely in order for the Package Manager to run the correct script at the correct time.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Upgrade scripts should be named <code class="computeroutput">/packages/<em class="replaceable"><code>myfirstpackage</code></em>/sql/<em class="replaceable"><code>postgresql</code></em>/upgrade/upgrade-<em class="replaceable"><code>OLDVERSION</code></em>-<em class="replaceable"><code>NEWVERSION</code></em>.sql</code></p> + </li><li class="listitem"> + <p>If the version you are working on is a later version than the current released version, OLDVERSION should be the current version. The current version is package version in the APM and in <code class="computeroutput">/packages/<em class="replaceable"><code>myfirstpackage</code></em>/<em class="replaceable"><code>myfirstpackage</code></em>.info</code>. So if forums is at 2.0.1, OLDVERSION should be 2.0.1d1. Note that this means that new version development that includes an upgrade must start at d2, not d1. + </p> + </li><li class="listitem"> + <p>If you are working on a pre-release version of a package, use the current package version as OLDVERSION. Increment the package version as appropriate (see above) and use the new version as NEWVERSION. For example, if you are working on 2.0.1d3, make it 2.0.1d4 and use <code class="computeroutput">upgrade-2.0.1d3-2.0.1d4.sql</code>.</p> + </li><li class="listitem"> + <p>Database upgrades should be confined to development releases, not alpha or beta releases.</p> + </li><li class="listitem"> + <p> + Never use a final release number as a NEWVERSION. If you do, then it is impossible to add any more database upgrades without incrementing the overall package version.</p> + </li><li class="listitem"> + <p>Use only the d, a, and b letters in OLDVERSION and NEWVERSION. rc is not supported by OpenACS APM.</p> + </li><li class="listitem"> + <p>The distance from OLDVERSION to NEWVERSION should never span a release. For example if we had a bug fix in acs-kernel on 5.1.0 you wouldn't want a file upgrade-5.0.4-5.1.0d1.sql since if you subsequently need to provide a 5.0.4-5.0.5 upgrade you will have to rename the 5.0.4-5.1.0 upgrade since you can't have upgrades which overlap like that. Instead, use <code class="computeroutput">upgrade-5.1.0d1-5.1.0d2.sql</code> -</p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-guidelines.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr><tr><td width="40%" align="left"> +</p> + </li></ol></div> + + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="cvs-guidelines.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-constraint-naming.html">Next</a></td></tr><tr><td width="40%" align="left"> CVS Guidelines </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Constraint naming standard</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/eng-standards.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/eng-standards.html,v diff -u -r1.33 -r1.34 --- openacs-4/packages/acs-core-docs/www/eng-standards.html 7 Aug 2017 23:47:49 -0000 1.33 +++ openacs-4/packages/acs-core-docs/www/eng-standards.html 8 Nov 2017 09:42:10 -0000 1.34 @@ -1,4 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 12. Engineering Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="form-builder.html" title="Using Form Builder: building html forms dynamically"><link rel="next" href="style-guide.html" title="OpenACS Style Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="form-builder.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="style-guide.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="eng-standards"></a>Chapter 12. Engineering Standards</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="style-guide.html">OpenACS Style Guide</a></span></dt><dt><span class="sect1"><a href="cvs-guidelines.html"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 12. Engineering Standards</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="form-builder.html" title="Using Form Builder: building html forms dynamically"><link rel="next" href="style-guide.html" title="OpenACS Style Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="form-builder.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="style-guide.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="eng-standards"></a>Chapter 12. Engineering Standards</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="style-guide.html">OpenACS Style Guide</a></span></dt><dt><span class="sect1"><a href="cvs-guidelines.html"> CVS Guidelines - </a></span></dt><dt><span class="sect1"><a href="eng-standards-versioning.html">Release Version Numbering</a></span></dt><dt><span class="sect1"><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></span></dt><dt><span class="sect1"><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></span></dt><dt><span class="sect1"><a href="eng-standards-plsql.html">PL/SQL Standards</a></span></dt><dt><span class="sect1"><a href="variables.html">Variables</a></span></dt><dt><span class="sect1"><a href="automated-testing-best-practices.html">Automated Testing</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="form-builder.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="style-guide.html">Next</a></td></tr><tr><td width="40%" align="left">Using Form Builder: building html forms dynamically </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Style Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </a></span></dt><dt><span class="sect1"><a href="eng-standards-versioning.html">Release Version Numbering</a></span></dt><dt><span class="sect1"><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></span></dt><dt><span class="sect1"><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></span></dt><dt><span class="sect1"><a href="eng-standards-plsql.html">PL/SQL Standards</a></span></dt><dt><span class="sect1"><a href="variables.html">Variables</a></span></dt><dt><span class="sect1"><a href="automated-testing-best-practices.html">Automated Testing</a></span></dt></dl></div> + + + + + + + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="form-builder.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="style-guide.html">Next</a></td></tr><tr><td width="40%" align="left">Using Form Builder: building html forms dynamically </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Style Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp 7 Aug 2017 23:47:49 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -12,7 +12,7 @@ <a name="ext-auth-requirements" id="ext-auth-requirements"></a>External Authentication Requirements</h2></div></div></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592122323816" id="idp140592122323816"></a>Vision</h3></div></div></div><p>People have plenty of usernames and passwords already, we +<a name="idp140623180002952" id="idp140623180002952"></a>Vision</h3></div></div></div><p>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.</p><p>Besides, administrators have better things to do than create @@ -74,41 +74,81 @@ <div class="titlepage"><div><div><h3 class="title"> <a name="Requirements" id="Requirements"></a>Requirements</h3></div></div></div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592122478744" id="idp140592122478744"></a>New API</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>New API</th></tr></thead><tbody> -<tr class="seglistitem"> -<td class="seg">EXT-AUTH-01</td><td class="seg">A</td><td class="seg">Extend Authentication/Acct Status API</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-03</td><td class="seg">A</td><td class="seg">Account Creation API</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-05</td><td class="seg">A</td><td class="seg">Password Management API</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-30</td><td class="seg">A</td><td class="seg">Authority Management API</td> -</tr> -</tbody> -</table></div> +<a name="idp140623180021992" id="idp140623180021992"></a>New API</h4></div></div></div><div class="segmentedlist"> +<div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">New +API:</span></strong> EXT-AUTH-01</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Extend Authentication/Acct Status API</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">New +API:</span></strong> EXT-AUTH-03</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Account Creation API</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">New +API:</span></strong> EXT-AUTH-05</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Password Management API</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">New +API:</span></strong> EXT-AUTH-30</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Authority Management API</div> +</div> +</div> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Login" id="Login"></a>Login</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>Login</th></tr></thead><tbody> -<tr class="seglistitem"> -<td class="seg">EXT-AUTH-04</td><td class="seg">A</td><td class="seg">Rewrite login, register, and admin pages to use -APIs</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-38</td><td class="seg">A</td><td class="seg">ad_form complain feature</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-19</td><td class="seg">A</td><td class="seg">Rewrite password recovery to use API</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-21</td><td class="seg">A</td><td class="seg">Rewrite email verification with API</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-28</td><td class="seg">A</td><td class="seg">Username is email switch</td> -</tr> -</tbody> -</table></div><p>Users will log in using a username, a authority, and a password. +<a name="Login" id="Login"></a>Login</h4></div></div></div><div class="segmentedlist"> +<div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Login:</span></strong> EXT-AUTH-04</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Rewrite login, register, and admin pages to use APIs</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Login:</span></strong> EXT-AUTH-38</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +ad_form complain feature</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Login:</span></strong> EXT-AUTH-19</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Rewrite password recovery to use API</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Login:</span></strong> EXT-AUTH-21</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Rewrite email verification with API</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Login:</span></strong> EXT-AUTH-28</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Username is email switch</div> +</div> +</div><p>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.</p><p>Each user in OpenACS will belong to exactly one authority, which can either be the "local" OpenACS users table, in which @@ -136,13 +176,14 @@ the authority drop-down element at all.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Configuratio" id="Configuratio"></a>Configuration</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>Configuration</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-07</td><td class="seg">A</td><td class="seg">Admin pages to control Ext-Auth parameters</td> -</tr></tbody> -</table></div><p>The site-wide systems administrator can configure the +<a name="Configuratio" id="Configuratio"></a>Configuration</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Configuration:</span></strong> EXT-AUTH-07</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Admin pages to control Ext-Auth parameters</div> +</div></div><p>The site-wide systems administrator can configure the authentication process from a page linked under /acs-admin.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Authorities - ordered list of authorities defined</p></li><li class="listitem"><p>Account Registration Allowed: Yes/No. Account registration can be disabled altogether.</p></li><li class="listitem"><p>Registration authority - the authority in which accounts should @@ -157,25 +198,41 @@ other drivers call external functions. The possible functions for each authority are split into several drivers for convenience. One driver handles authentication, one account creation, and one -changing passwords.</p><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>create service contract</th></tr></thead><tbody> -<tr class="seglistitem"> -<td class="seg">EXT-AUTH-16</td><td class="seg">A</td><td class="seg">Create service contract for Authentication</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-17</td><td class="seg">A</td><td class="seg">Create service contract for Acct. Creation</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-29</td><td class="seg">A</td><td class="seg">Create service contract for Passwd Management</td> -</tr> -</tbody> -</table></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th></th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-18</td><td class="seg">A</td><td class="seg">Authority configuration data model</td> -</tr></tbody> -</table></div><p>Each authority is defined like this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +changing passwords.</p><div class="segmentedlist"> +<div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">create service +contract:</span></strong> EXT-AUTH-16</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create service contract for Authentication</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">create service +contract:</span></strong> EXT-AUTH-17</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create service contract for Acct. Creation</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">create service +contract:</span></strong> EXT-AUTH-29</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create service contract for Passwd Management</div> +</div> +</div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">:</span></strong> +EXT-AUTH-18</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Authority configuration data model</div> +</div></div><p>Each authority is defined like this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Authority pretty-name, e.g. "URZ"</p></li><li class="listitem"><p>Authentication Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract implementation.</p></li><li class="listitem"><p>Authentication Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that this is @@ -211,23 +268,49 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Synchronizing_and_Linking_User" id="Synchronizing_and_Linking_User"></a>Synchronizing and Linking -Users</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>Synchronizing and linking users</th></tr></thead><tbody> -<tr class="seglistitem"> -<td class="seg">EXT-AUTH-28</td><td class="seg">A</td><td class="seg">Create service contract for Batch Sync.</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-38</td><td class="seg">A</td><td class="seg">Batch User Synchronization API</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-38</td><td class="seg">A</td><td class="seg">IMS Synchronization driver</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-08</td><td class="seg">A</td><td class="seg">Automation of batch Synchronization</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-15</td><td class="seg">B</td><td class="seg">On-demand synchronization</td> -</tr> -</tbody> -</table></div><p>Regardless of the login method, the user needs to have a row in +Users</h4></div></div></div><div class="segmentedlist"> +<div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Synchronizing and +linking users:</span></strong> EXT-AUTH-28</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create service contract for Batch Sync.</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Synchronizing and +linking users:</span></strong> EXT-AUTH-38</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Batch User Synchronization API</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Synchronizing and +linking users:</span></strong> EXT-AUTH-38</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +IMS Synchronization driver</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Synchronizing and +linking users:</span></strong> EXT-AUTH-08</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Automation of batch Synchronization</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Synchronizing and +linking users:</span></strong> EXT-AUTH-15</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +B</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +On-demand synchronization</div> +</div> +</div><p>Regardless of the login method, the user needs to have a row in the OpenACS users table. This can happen through a batch job, in real-time, or both in combination. We use the <a class="ulink" href="https://www.imsglobal.org/enterprise/index.html" target="_top">IMS Enterprise 1.1</a> specification.</p><p>Batch job means that we do a synchronization (import new users, modify changed, purge deleted) on a regular interval, e.g. every @@ -260,13 +343,14 @@ same person. We'd still have a problem if there was an email conflict between two accounts on the same authority. Hm. I don't think it's worth spending too much time trying to -solve this problem through software.</p><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-31</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-31</td><td class="seg">A</td><td class="seg">Upgrade user data model for ext-auth</td> -</tr></tbody> -</table></div><p>After having authenticated using the relevant authority driver, +solve this problem through software.</p><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-31:</span></strong> EXT-AUTH-31</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Upgrade user data model for ext-auth</div> +</div></div><p>After having authenticated using the relevant authority driver, we'll look for the username/authority pair in the users table.</p><p>If we don't find any, that means that we're either not doing batch synchronizing, or that the user has been added since @@ -310,13 +394,14 @@ desires to change password.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Login_Pages_Over_HTTP" id="Login_Pages_Over_HTTP"></a>Login Pages Over HTTPS</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-20</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-20</td><td class="seg">A</td><td class="seg">Login over HTTPS</td> -</tr></tbody> -</table></div><p>Login pages must be able to be sent over a secure connection +<a name="Login_Pages_Over_HTTP" id="Login_Pages_Over_HTTP"></a>Login Pages Over HTTPS</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-20:</span></strong> EXT-AUTH-20</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Login over HTTPS</div> +</div></div><p>Login pages must be able to be sent over a secure connection (https), so your password won't get sent over the wire in cleartext, while leaving the rest of the site non-secure (http). I believe that this requires some (minor) changes to the current @@ -343,13 +428,14 @@ we're messing with this part of the codebase anyway.</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Recommended__Untrusted_Logins_and_Login_Leve" id="Recommended__Untrusted_Logins_and_Login_Leve"></a>Recommended: -Untrusted Logins and Login Levels</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-33</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-33</td><td class="seg">A</td><td class="seg">Untrusted Logins</td> -</tr></tbody> -</table></div><p>I like the idea of having multiple login levels:</p><div class="orderedlist"><ol class="orderedlist" type="1"> +Untrusted Logins and Login Levels</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-33:</span></strong> EXT-AUTH-33</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Untrusted Logins</div> +</div></div><p>I like the idea of having multiple login levels:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Not logged in</p></li><li class="listitem"><p>Untrusted login: We'll show you un-sensitive personal content, but won't let you modify anything or see personal data. A normal login becomes untrusted after a certain amount of @@ -388,13 +474,14 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Recommended__Make_Non-Persistent_Login_Wor" id="Recommended__Make_Non-Persistent_Login_Wor"></a>Recommended: Make -Non-Persistent Login Work</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-34</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-34</td><td class="seg">A</td><td class="seg">Expire Logins</td> -</tr></tbody> -</table></div><p>Currently, OpenACS is unusable in practice without persistent +Non-Persistent Login Work</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-34:</span></strong> EXT-AUTH-34</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Expire Logins</div> +</div></div><p>Currently, OpenACS is unusable in practice without persistent login. The login will expire after just a few minutes of inactivity, and you'll get bounced to the login page where you have to enter both email and password again. Unacceptable in @@ -408,13 +495,12 @@ current session handling code.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Recommended__Single-Sign-O" id="Recommended__Single-Sign-O"></a>Recommended: Single-Sign-On</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-23</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-23</td><td class="seg"></td><td class="seg">Single sign-on</td> -</tr></tbody> -</table></div><p>Instead of redirecting to the login page, auth::require_login +<a name="Recommended__Single-Sign-O" id="Recommended__Single-Sign-O"></a>Recommended: Single-Sign-On</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-23:</span></strong> EXT-AUTH-23</div><div class="seg"><strong><span class="segtitle">:</span></strong></div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Single sign-on</div> +</div></div><p>Instead of redirecting to the login page, auth::require_login can redirect to an authentication server, which can redirect back to a page that logs the user in. This should be very easy to implement.</p><p>Alternatively, if you want to combine this with fallback to @@ -424,13 +510,14 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Recommended__Expire_All_Login" id="Recommended__Expire_All_Login"></a>Recommended: Expire All -Logins</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-22</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-22</td><td class="seg">B</td><td class="seg">rewrite cookie handling</td> -</tr></tbody> -</table></div><p>Currently, if you've ever left a permanent login cookie on +Logins</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-22:</span></strong> EXT-AUTH-22</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +B</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +rewrite cookie handling</div> +</div></div><p>Currently, if you've ever left a permanent login cookie on someone elses machine, that person will be forever logged in until he/she explicitly logs out. You can change your password, you can do anything you want, but unless a logout is requested from that @@ -449,24 +536,26 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Recommended__Email_account_owner_on_password" id="Recommended__Email_account_owner_on_password"></a>Recommended: -Email account owner on password change</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-24</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-24</td><td class="seg">A</td><td class="seg">Email on password change</td> -</tr></tbody> -</table></div><p>As an additional security measure, we should email the +Email account owner on password change</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-24:</span></strong> EXT-AUTH-24</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Email on password change</div> +</div></div><p>As an additional security measure, we should email the account's email address whenever the password is changed, so that he/she is at least alerted to the fact.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Optional__Password_polic" id="Optional__Password_polic"></a>Optional: Password policy</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-25</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-25</td><td class="seg">A</td><td class="seg">Implement password policy</td> -</tr></tbody> -</table></div><p>Again, to increase security, we should add password policies, +<a name="Optional__Password_polic" id="Optional__Password_polic"></a>Optional: Password policy</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-25:</span></strong> EXT-AUTH-25</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Implement password policy</div> +</div></div><p>Again, to increase security, we should add password policies, such as passwords needing to be changed after a certain number of days, change on next login (after a new random password has been generated), or requiring that the password satisfies certain @@ -476,13 +565,14 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Optional__Login_Without_Explicit_Domai" id="Optional__Login_Without_Explicit_Domai"></a>Optional: Login -Without Explicit Authority</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-26</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-26</td><td class="seg">B</td><td class="seg">Login without explicit domain</td> -</tr></tbody> -</table></div><p>In order to make it easier for people, we've been toying +Without Explicit Authority</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-26:</span></strong> EXT-AUTH-26</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +B</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Login without explicit domain</div> +</div></div><p>In order to make it easier for people, we've been toying with the idea of a functionality like this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>If the user enters "foobar\@ix.urz.uni-heidelberg.de", it is translated to mean username = "foobar", authority = @@ -514,13 +604,14 @@ </pre> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Optional__Whois_Onlin" id="Optional__Whois_Onlin"></a>Optional: Who's Online</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-27</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-27</td><td class="seg">B</td><td class="seg">Who's online list</td> -</tr></tbody> -</table></div><p>While we're touching the session handling code, anyway, it +<a name="Optional__Whois_Onlin" id="Optional__Whois_Onlin"></a>Optional: Who's Online</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-27:</span></strong> EXT-AUTH-27</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +B</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Who's online list</div> +</div></div><p>While we're touching the session handling code, anyway, it would be nice to add a feature to show who's currently online, a nice real-time collaboration feature frequently requested by members of the community. This is particularly interesting when @@ -538,31 +629,36 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Optional__Subsite-level_configuratio" id="Optional__Subsite-level_configuratio"></a>Optional: -Subsite-level configuration</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-28</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-28</td><td class="seg"></td><td class="seg">implement subsite-level config</td> -</tr></tbody> -</table></div><p>If we want to, we could let subsite administrators configure the +Subsite-level configuration</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-28:</span></strong> EXT-AUTH-28</div><div class="seg"><strong><span class="segtitle">:</span></strong></div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +implement subsite-level config</div> +</div></div><p>If we want to, we could let subsite administrators configure the login process for that particular subsite. This would probably only entail letting the subsite admin leave out certain authorities defined site-wide, and change the sort order.</p><p>I think we should leave this out until we have a use case for it, someone who'd need it.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Future__Making_the_Authentication_API_itself" id="Future__Making_the_Authentication_API_itself"></a>Future: Making -the Authentication API itself a service contract</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-32</th></tr></thead><tbody> -<tr class="seglistitem"> -<td class="seg">EXT-AUTH-32</td><td class="seg">A</td><td class="seg">Parameters for Service Contract Implementation</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-35</td><td class="seg">A</td><td class="seg">Make the Authentication API a service contract</td> -</tr> -</tbody> -</table></div><p>For completely free-form authentication logic and mechanisms, +the Authentication API itself a service contract</h4></div></div></div><div class="segmentedlist"> +<div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-32:</span></strong> EXT-AUTH-32</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Parameters for Service Contract Implementation</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-32:</span></strong> EXT-AUTH-35</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Make the Authentication API a service contract</div> +</div> +</div><p>For completely free-form authentication logic and mechanisms, something like Andrew Grumet's <a class="ulink" href="http://openacs.org/new-file-storage/download/oacs-pam.html?version_id=687" target="_top">Pluggable Authentication for OACS Draft</a> is interesting. He's proposing a scheme where the entire user interaction is encapsulated in, and left entirely to, a service @@ -576,13 +672,14 @@ </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> <a name="Future__Authenticating_against_multiple_serv" id="Future__Authenticating_against_multiple_serv"></a>Future: -Authenticating against multiple servers simultaneously</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>EXT-AUTH-36</th></tr></thead><tbody><tr class="seglistitem"> -<td class="seg">EXT-AUTH-36</td><td class="seg">A</td><td class="seg">Authenticate against multiple servers</td> -</tr></tbody> -</table></div><p>Both OKI and OpenACS supports a form of stacking, where you can +Authenticating against multiple servers simultaneously</h4></div></div></div><div class="segmentedlist"><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">EXT-AUTH-36:</span></strong> EXT-AUTH-36</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Authenticate against multiple servers</div> +</div></div><p>Both OKI and OpenACS supports a form of stacking, where you can be logged into multiple authorities at the same time. This is useful if, for example, you need to get login tokens such as Kerberos tickets for access to shared resources.</p><p>I can see the value in this, but for simplicity's sake, @@ -598,28 +695,59 @@ wait till they're there.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="Implement_Specific_Driver" id="Implement_Specific_Driver"></a>Implement Specific Drivers</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"> -<tr> -<th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th> -</tr><thead><tr><th>Implement specific drivers</th></tr></thead><tbody> -<tr class="seglistitem"> -<td class="seg">EXT-AUTH-09</td><td class="seg">A</td><td class="seg">Create Auth. drivers for Local Authority</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-10</td><td class="seg">A</td><td class="seg">Create Acct. Creation driver for Local -Authority</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-11</td><td class="seg">A</td><td class="seg">Create Auth. driver for PAM</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-12</td><td class="seg">X</td><td class="seg"><span class="emphasis"><em>Create Acct. Creation -driver for PAM - this functionality is explicitly excluded from -PAM</em></span></td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-13</td><td class="seg">A</td><td class="seg">Create Acct. Creation driver for LDAP</td> -</tr><tr class="seglistitem"> -<td class="seg">EXT-AUTH-14</td><td class="seg">A</td><td class="seg">Create Auth. driver for LDAP</td> -</tr> -</tbody> -</table></div><p>We'll need drivers for:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +<a name="Implement_Specific_Driver" id="Implement_Specific_Driver"></a>Implement Specific Drivers</h4></div></div></div><div class="segmentedlist"> +<div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Implement specific +drivers:</span></strong> EXT-AUTH-09</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create Auth. drivers for Local Authority</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Implement specific +drivers:</span></strong> EXT-AUTH-10</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create Acct. Creation driver for Local Authority</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Implement specific +drivers:</span></strong> EXT-AUTH-11</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create Auth. driver for PAM</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Implement specific +drivers:</span></strong> EXT-AUTH-12</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +X</div><div class="seg"> +<strong><span class="segtitle">:</span></strong><span class="emphasis"><em>Create Acct. Creation driver for PAM - +this functionality is explicitly excluded from +PAM</em></span> +</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Implement specific +drivers:</span></strong> EXT-AUTH-13</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create Acct. Creation driver for LDAP</div> +</div><div class="seglistitem"> +<div class="seg"> +<strong><span class="segtitle">Implement specific +drivers:</span></strong> EXT-AUTH-14</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +A</div><div class="seg"> +<strong><span class="segtitle">:</span></strong> +Create Auth. driver for LDAP</div> +</div> +</div><p>We'll need drivers for:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Operating system (Linux/Solaris) PAM: Delegate to the operating system, which can then talk to RADIUS, LDAP, whatever. This is convenient because there'll be plenty of drivers for the OS PAM Index: openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html,v diff -u -r1.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 7 Aug 2017 23:47:49 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/ext-auth-requirements.html 8 Nov 2017 09:42:10 -0000 1.42 @@ -1,14 +1,23 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>External Authentication Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="next" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="releasing-openacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ext-auth-requirements"></a>External Authentication Requirements</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592122323816"></a>Vision</h3></div></div></div><p>People have plenty of usernames and passwords already, we +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>External Authentication Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="bootstrap-acs.html" title="Bootstrapping OpenACS"><link rel="next" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="releasing-openacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="ext-auth-requirements"></a>External Authentication Requirements</h2></div></div></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623180002952"></a>Vision</h3></div></div></div> + <p>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.</p><p>Besides, administrators have better things to do than create +other system.</p> + + <p>Besides, administrators have better things to do than create accounts for people. So we want them to be able to create just one account on a central server (e.g. LDAP or RADIUS), and when they log on to OpenACS, an account will automatically be created for -them here.</p><p>Finally, security is increased with fewer passwords, since +them here.</p> + <p>Finally, security is increased with fewer passwords, since users generally can't remember all those passwords, so they tend to -keep them all the same and never change them.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Design_Goal"></a>Design Goals</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Transparent: Users don't have to do anything special to +keep them all the same and never change them.</p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Design_Goal"></a>Design Goals</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Transparent: Users don't have to do anything special to get an account on the local OpenACS system, if they already have an account on the external authentication server.</p></li><li class="listitem"><p>Fall-back: Users who don't have an account on the external authentication server are still allowed to create a local @@ -35,33 +44,115 @@ open to add other authentification mechanisms when needed and on the other hand very modular to enable a start with minimal requirements (driver implementations) as soon as - possible.</p></li></ul></div><p>The problem can be split into several logically separate -parts. Each has a section below.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Terminology"></a>Terminology</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authority: The name of an authority trusted to authenticate - users.</p></li><li class="listitem"><p>Authentication Driver: An implementation of the + possible.</p></li></ul></div> + <p>The problem can be split into several logically separate +parts. Each has a section below.</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Terminology"></a>Terminology</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authority: The name of an authority trusted to authenticate + users.</p> + </li><li class="listitem"><p>Authentication Driver: An implementation of the authentication service contract, which talks to an authentication of a certain type, e.g. PAM, RADIUS, LDAP, or Active Directory.</p></li><li class="listitem"><p>Authentication API: The API through which login pages and applications talk to the authentication service. There's one and only one implementation of the authentication API, namly the one included in OpenACS Core.</p></li><li class="listitem"><p>Authentication Driver API: The service contract which - authentication drivers implement.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Diagram"></a>Conceptual Pictures</h3></div></div></div><p>Authentication:</p><p><span class="inlinemediaobject"><img src="images/ext-auth.png"></span> -</p><p>Account Management (NO PICTURE YET)</p><p>Batch Synchronization (NO PICTURE YET)</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Requirements"></a>Requirements</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592122478744"></a>New API</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>New API</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-01</td><td class="seg">A</td><td class="seg">Extend Authentication/Acct Status API</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-03</td><td class="seg">A</td><td class="seg">Account Creation API</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-05</td><td class="seg">A</td><td class="seg">Password Management API</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-30</td><td class="seg">A</td><td class="seg">Authority Management API</td></tr></tbody></table></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Login"></a>Login</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>Login</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-04</td><td class="seg">A</td><td class="seg">Rewrite login, register, and admin pages to use APIs</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-38</td><td class="seg">A</td><td class="seg">ad_form complain feature</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-19</td><td class="seg">A</td><td class="seg">Rewrite password recovery to use API</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-21</td><td class="seg">A</td><td class="seg">Rewrite email verification with API</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-28</td><td class="seg">A</td><td class="seg">Username is email switch</td></tr></tbody></table></div><p>Users will log in using a username, a authority, and a + authentication drivers implement.</p></li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Diagram"></a>Conceptual Pictures</h3></div></div></div> + <p>Authentication:</p> + <p><span class="inlinemediaobject"><img src="images/ext-auth.png"></span> +</p> +<p>Account Management (NO PICTURE YET)</p> +<p>Batch Synchronization (NO PICTURE YET)</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Requirements"></a>Requirements</h3></div></div></div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623180021992"></a>New API</h4></div></div></div> + + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">New API: </span></strong>EXT-AUTH-01</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Extend Authentication/Acct Status API</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">New API: </span></strong>EXT-AUTH-03</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Account Creation API</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">New API: </span></strong>EXT-AUTH-05</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Password Management API</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">New API: </span></strong>EXT-AUTH-30</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Authority Management API</div> + </div> + </div> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Login"></a>Login</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Login: </span></strong>EXT-AUTH-04</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Rewrite login, register, and admin pages to use APIs</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Login: </span></strong>EXT-AUTH-38</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>ad_form complain feature</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Login: </span></strong>EXT-AUTH-19</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Rewrite password recovery to use API</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Login: </span></strong>EXT-AUTH-21</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Rewrite email verification with API</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Login: </span></strong>EXT-AUTH-28</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Username is email switch</div> + </div> + </div> + <p>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. </p><p>Each user in OpenACS will belong to exactly one authority, which + verification. OpenACS can be an authority itself. </p> + + <p>Each user in OpenACS will belong to exactly one authority, which can either be the "local" OpenACS users table, in which case the password column is used, or it can be some external authority, which will be communicated with using some protocol, as implemented -by an authentication driver.</p><p>Username will be separate from email address. It can be an +by an authentication driver.</p> + <p>Username will be separate from email address. It can be an email address, it can look like an email address but not be the name of an actual email mailbox, or it can be something else -entirely.</p><p>We're assuming that user information (name, email, etc.) will +entirely.</p> + <p>We're assuming that user information (name, email, etc.) will either already be in the users table through a batch synchronization job, or that the relevant authentication implementation supports real-time synchronization of user data. Specifically, if you want remote users who haven't yet logged in to OpenACS to show up in user searches, you'll have to do the batch -synchronization.</p><p>All in all, the login box will be an includeable template and -look like this:</p><pre class="programlisting"> +synchronization.</p> + <p>All in all, the login box will be an includeable template and +look like this:</p> + <pre class="programlisting"> Username: ________ Password: ________ Authority: [URZ ] @@ -70,21 +161,72 @@ [Forgot my password] [New user registration] -</pre><p>If there's only one active authority, we don't display the -authority drop-down element at all.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Configuratio"></a>Configuration</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>Configuration</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-07</td><td class="seg">A</td><td class="seg">Admin pages to control Ext-Auth parameters</td></tr></tbody></table></div><p>The site-wide systems administrator can configure the -authentication process from a page linked under /acs-admin.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authorities - ordered list of authorities defined</p></li><li class="listitem"><p>Account Registration Allowed: Yes/No. Account +</pre> + + + <p>If there's only one active authority, we don't display the +authority drop-down element at all.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Configuratio"></a>Configuration</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Configuration: </span></strong>EXT-AUTH-07</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Admin pages to control Ext-Auth parameters</div> + </div> + </div> + <p>The site-wide systems administrator can configure the +authentication process from a page linked under /acs-admin.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authorities - ordered list of authorities defined</p></li><li class="listitem"><p>Account Registration Allowed: Yes/No. Account registration can be disabled altogether.</p></li><li class="listitem"><p>Registration authority - the authority in which accounts should be created, using the relevant driver, if account registration is allowed.</p></li><li class="listitem"><p>Username is email? - instead of asking for username, we'll ask for email. And we'll store the value in both columns, username and email. This is a setting that spans all authorities, and is primarily meant for backwards compatibility with the old OpenACS - login process.</p></li></ul></div><p>The local authority driver is an encapsulation of current + login process.</p></li></ul></div> + <p>The local authority driver is an encapsulation of current functionality within an driver matching a service contract. The other drivers call external functions. The possible functions for each authority are split into several drivers for convenience. One driver handles authentication, one account creation, and one - changing passwords.</p><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>create service contract</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-16</td><td class="seg">A</td><td class="seg">Create service contract for Authentication</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-17</td><td class="seg">A</td><td class="seg">Create service contract for Acct. Creation</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-29</td><td class="seg">A</td><td class="seg">Create service contract for Passwd Management</td></tr></tbody></table></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th> </th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-18</td><td class="seg">A</td><td class="seg">Authority configuration data model</td></tr></tbody></table></div><p>Each authority is defined like this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authority pretty-name, e.g. "URZ"</p></li><li class="listitem"><p>Authentication Driver, e.g. "RADIUS". In practice, this + changing passwords.</p> + + + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">create service contract: </span></strong>EXT-AUTH-16</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create service contract for Authentication</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">create service contract: </span></strong>EXT-AUTH-17</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create service contract for Acct. Creation</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">create service contract: </span></strong>EXT-AUTH-29</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create service contract for Passwd Management</div> + </div> + </div> + + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle"> : </span></strong>EXT-AUTH-18</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Authority configuration data model</div> + </div> + </div> + <p>Each authority is defined like this:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authority pretty-name, e.g. "URZ"</p></li><li class="listitem"><p>Authentication Driver, e.g. "RADIUS". In practice, this would be a reference to a service contract implementation.</p></li><li class="listitem"><p>Authentication Driver configuration settings, e.g. host name, port, etc., as required by the particular driver. Note that @@ -109,17 +251,55 @@ registration using this account.</p></li><li class="listitem"><p>Sort order: Preference order of authorities.</p></li><li class="listitem"><p>HelpContactText: Text or HTML to be displayed when user has trouble authenticating with the authority. - Should include contact information such as a phone number or email.</p></li></ul></div><p>Each authority driver will have a set of configuration options + Should include contact information such as a phone number or email.</p></li></ul></div> + <p>Each authority driver will have a set of configuration options dependent on the driver, such as host, port, etc. We will need to find a mechanism for the driver to tell us which configuration options are available, a way to set these, and a way for the driver -to access these settings.</p><p>OpenACS will come pre-configured with one authority, which is +to access these settings.</p> + <p>OpenACS will come pre-configured with one authority, which is the "local" authority, meaning we'll authenticate as normal using the local users table. This will, just like any other authority, be -implemetned using a service contract.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Synchronizing_and_Linking_User"></a>Synchronizing -and Linking Users</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>Synchronizing and linking users</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-28</td><td class="seg">A</td><td class="seg">Create service contract for Batch Sync.</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-38</td><td class="seg">A</td><td class="seg">Batch User Synchronization API</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-38</td><td class="seg">A</td><td class="seg">IMS Synchronization driver</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-08</td><td class="seg">A</td><td class="seg">Automation of batch Synchronization</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-15</td><td class="seg">B</td><td class="seg">On-demand synchronization</td></tr></tbody></table></div><p>Regardless of the login method, the user needs to have a row +implemetned using a service contract.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Synchronizing_and_Linking_User"></a>Synchronizing +and Linking Users</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Synchronizing and linking users: </span></strong>EXT-AUTH-28</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create service contract for Batch Sync.</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Synchronizing and linking users: </span></strong>EXT-AUTH-38</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Batch User Synchronization API</div> + </div> + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Synchronizing and linking users: </span></strong>EXT-AUTH-38</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>IMS Synchronization driver</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Synchronizing and linking users: </span></strong>EXT-AUTH-08</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Automation of batch Synchronization</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Synchronizing and linking users: </span></strong>EXT-AUTH-15</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>B</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>On-demand synchronization</div> + </div> + </div> + + <p>Regardless of the login method, the user needs to have a row in the OpenACS users table. This can happen through a batch job, in -real-time, or both in combination. We use the <a class="ulink" href="https://www.imsglobal.org/enterprise/index.html" target="_top">IMS Enterprise 1.1</a> specification. </p><p>Batch job means that we do a synchronization (import new +real-time, or both in combination. We use the <a class="ulink" href="https://www.imsglobal.org/enterprise/index.html" target="_top">IMS Enterprise 1.1</a> specification. </p> + <p>Batch job means that we do a synchronization (import new users, modify changed, purge deleted) on a regular interval, e.g. every night. You can also decide to have a monthly full synchronization, plus daily incremental ones. That's up to you. The @@ -128,16 +308,21 @@ who happen to have used the OpenACS-based system. The down-side is that it takes some time for user information to propagate. This can be remedied by using the real-time solution. The batch job will also -require error logging and an admin interface to view logs.</p><p>If an email already belongs to some -other user, we log it as an error.</p><p>A user will always belong to exactly one authority, which can be +require error logging and an admin interface to view logs.</p> + <p>If an email already belongs to some +other user, we log it as an error.</p> + <p>A user will always belong to exactly one authority, which can be either the "local" authority or some other. Thus, the OpenACS user's -table will have to be augmented with the following columns:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authority. Reference to the site-wide authorities list. The - authority which can authenticate this user.</p></li><li class="listitem"><p>Authority-specific username.</p></li></ul></div><p>Real-time means that the first time the user logs into +table will have to be augmented with the following columns:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Authority. Reference to the site-wide authorities list. The + authority which can authenticate this user.</p></li><li class="listitem"><p>Authority-specific username.</p></li></ul></div> + <p>Real-time means that the first time the user logs into OpenACS, we'll query the authority that authenticated him for information about this user. That authentication authority will then give us at least first names, last name and email. The pros and cons are the opposite of batch jobs. Using both in combination -is ideal.</p><p>Note: One solution to the "two users from different authorities +is ideal.</p> + <p>Note: One solution to the "two users from different authorities have the same email" problem above would be to allow users to belong to multiple authorities. Then we would notice that the email already exists, ask the user if he thinks he's the same person, and @@ -146,60 +331,127 @@ authorities, and we can record that this is the same person. We'd still have a problem if there was an email conflict between two accounts on the same authority. Hm. I don't think it's worth spending too much -time trying to solve this problem through software.</p><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-31</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-31</td><td class="seg">A</td><td class="seg">Upgrade user data model for ext-auth</td></tr></tbody></table></div><p>After having authenticated using the relevant authority driver, -we'll look for the username/authority pair in the users table.</p><p>If we don't find any, that means that we're either not doing +time trying to solve this problem through software.</p> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-31: </span></strong>EXT-AUTH-31</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Upgrade user data model for ext-auth</div> + </div> + </div> + <p>After having authenticated using the relevant authority driver, +we'll look for the username/authority pair in the users table.</p> + <p>If we don't find any, that means that we're either not doing batch synchronizing, or that the user has been added since the last sync. In that case, we'll try to do a real-time synchronization, if the driver supports it. If it does, it'll return email, first_names, last_name, and other relevant information, and we'll create a row in the local users table using that -information.</p><p>If that doesn't work, we'll tell the user that their account +information.</p> + <p>If that doesn't work, we'll tell the user that their account isn't yet available, and the driver will supply a message for us, which could say "The account should be available tomorrow. If not, -contact X."</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Account_Registratio"></a>Account -Registration</h4></div></div></div><p>If a user doesn't have an account, the site-wide +contact X."</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Account_Registratio"></a>Account +Registration</h4></div></div></div> + <p>If a user doesn't have an account, the site-wide configuration can allow the user to register for one, as defined in the configuration discussed above. This section is about normal -account registration through a authority driver.</p><p>The account creation service contract implementation will -need to tell us which information to ask the user for:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Required Fields: A list of fields which are +account registration through a authority driver.</p> + <p>The account creation service contract implementation will +need to tell us which information to ask the user for:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Required Fields: A list of fields which are required.</p></li><li class="listitem"><p>Optional Fields: A list of fields which are - optional.</p></li></ul></div><p>The fields to choose from are these:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Username</p></li><li class="listitem"><p>First names</p></li><li class="listitem"><p>Last name</p></li><li class="listitem"><p>Email</p></li><li class="listitem"><p>URL</p></li><li class="listitem"><p>Password</p></li><li class="listitem"><p>Secret question</p></li><li class="listitem"><p>Secret answer</p></li></ul></div><p>It should return the following:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Creation status (OK, Try-Again, Fail)</p></li><li class="listitem"><p>Creation message: What went wrong, or a welcome + optional.</p></li></ul></div> + <p>The fields to choose from are these:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Username</p></li><li class="listitem"><p>First names</p></li><li class="listitem"><p>Last name</p></li><li class="listitem"><p>Email</p></li><li class="listitem"><p>URL</p></li><li class="listitem"><p>Password</p></li><li class="listitem"><p>Secret question</p></li><li class="listitem"><p>Secret answer</p></li></ul></div> + <p>It should return the following:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Creation status (OK, Try-Again, Fail)</p></li><li class="listitem"><p>Creation message: What went wrong, or a welcome message.</p></li><li class="listitem"><p>Account status: Is the account ready for use?</p></li><li class="listitem"><p>User information: first_names, last_name, email, url, password, password_hash, secret_question, secret_answer. The driver only needs to return the columns which were changed or added through the registration process. Typically, only the "local" - driver will return password and secret question/answer.</p></li></ul></div><p>After creating the remote account, a local account is created + driver will return password and secret question/answer.</p></li></ul></div> + <p>After creating the remote account, a local account is created with the information gathered through the form/returned by the -driver.</p><p>By default, a local account creation implementation is +driver.</p> + <p>By default, a local account creation implementation is provided, which will create a new OpenACS user, and, in addition to the default local account creation above, also store the password -in hashed form.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Password_Managemen"></a>Password -Management</h4></div></div></div><p>Password management is about changing password, retrieving -password, and resetting password.</p><p>It's up to the authority driver implementation to decide whether +in hashed form.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Password_Managemen"></a>Password +Management</h4></div></div></div> + <p>Password management is about changing password, retrieving +password, and resetting password.</p> + <p>It's up to the authority driver implementation to decide whether to support any or all of these features, and to say so using the -CanXXX methods (see driver API below).</p><p>Additionally, the authority can be configured with a URL to +CanXXX methods (see driver API below).</p> + <p>Additionally, the authority can be configured with a URL to redirect to in the case of forgotten passwords, or when the user -desires to change password.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Login_Pages_Over_HTTP"></a>Login Pages Over -HTTPS</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-20</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-20</td><td class="seg">A</td><td class="seg">Login over HTTPS</td></tr></tbody></table></div><p>Login pages must be able to be sent over a secure connection +desires to change password.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Login_Pages_Over_HTTP"></a>Login Pages Over +HTTPS</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-20: </span></strong>EXT-AUTH-20</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Login over HTTPS</div> + </div> + </div> + <p>Login pages must be able to be sent over a secure connection (https), so your password won't get sent over the wire in cleartext, while leaving the rest of the site non-secure (http). I believe that this requires some (minor) changes to the current -session handling code.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Email_Verificatio"></a>Email -Verification</h4></div></div></div><p>Email verification needs to be handled both at registration -and at login.</p><p>In both cases, it'll be handled by the driver sending +session handling code.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Email_Verificatio"></a>Email +Verification</h4></div></div></div> + <p>Email verification needs to be handled both at registration +and at login.</p> + <p>In both cases, it'll be handled by the driver sending automatically sending the email containing a link for the user to verify his account. Then the driver will return an account status of "closed,temporary", and a message that says "Check your inbox -and click the link in the email".</p><p>OpenACS will have a page which receives the email +and click the link in the email".</p> + <p>OpenACS will have a page which receives the email verification, for use by local accounts. Other authorities will have to implement their own page, most likely on the authority's -own server.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Other_Item"></a>Other Items</h3></div></div></div><p>There are a number of items which touch on external +own server.</p> + </div></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Other_Item"></a>Other Items</h3></div></div></div> + <p>There are a number of items which touch on external authentication and session management. And even though they're not directly linked to external authentication, I would recommend that we handle a number of them, either because they're important for security, or because it makes sense to fix them while we're messing -with this part of the codebase anyway.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Untrusted_Logins_and_Login_Leve"></a>Recommended: -Untrusted Logins and Login Levels</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-33</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-33</td><td class="seg">A</td><td class="seg">Untrusted Logins</td></tr></tbody></table></div><p>I like the idea of having multiple login levels:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Not logged in</p></li><li class="listitem"><p>Untrusted login: We'll show you un-sensitive personal +with this part of the codebase anyway.</p> + + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Untrusted_Logins_and_Login_Leve"></a>Recommended: +Untrusted Logins and Login Levels</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-33: </span></strong>EXT-AUTH-33</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Untrusted Logins</div> + </div> + </div> + <p>I like the idea of having multiple login levels:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Not logged in</p></li><li class="listitem"><p>Untrusted login: We'll show you un-sensitive personal content, but won't let you modify anything or see personal data. A normal login becomes untrusted after a certain amount of time, and the user will have to re-enter his/her password in order to gain @@ -211,168 +463,392 @@ specified amount of time.</p></li><li class="listitem"><p>Secure login: The user is logged in over a secure connection (HTTPS), potentially even using a special secure password. This would be for sensitive actions, such as credit card - transactions.</p></li></ol></div><p>There are two advantages to this. First, when people's login + transactions.</p></li></ol></div> + <p>There are two advantages to this. First, when people's login expires, we can ask them to re-enter only their password, and not both username and password, since we'll still remember who they were the last time their login was valid. This is a much faster operation (the password input field will be focused by default, so you just type your password and hit Return) that typing both username and password, which will make it practical to have your site configured to expire people's login after e.g. 2, 4, or 8 -hours.</p><p>The other advantage is that we can still offer certain +hours.</p> + <p>The other advantage is that we can still offer certain functionality to you, even when your login is not trusted. For example, we could let you browse publicly available forums, and only when you want to post do you need to log in. This makes it even more feasible to have a more secure login expiration -setting.</p><p>By default, <code class="literal">auth::require_login</code> would +setting.</p> + <p>By default, <code class="literal">auth::require_login</code> would bounce to the login page if the user is only logged in at the untrusted level. Only if you explicitly say <code class="literal">auth::require_login -untrusted</code> will we give you the user_id of a user who's only logged in in untrusted -mode.</p><p>Similarly, <code class="literal">ad_conn user_id</code> will continue +mode.</p> + <p>Similarly, <code class="literal">ad_conn user_id</code> will continue to return 0 (not logged in) when the user is only logged in untrusted, and we'll supply another variable, <code class="literal">ad_conn untrusted_user_id</code>, which wlll be set to the user_id for -all login levels.</p><p>This should ensure that we get full access to the new +all login levels.</p> + <p>This should ensure that we get full access to the new feature, while leaving all current code just as secure as it was -before.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Make_Non-Persistent_Login_Wor"></a>Recommended: -Make Non-Persistent Login Work</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-34</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-34</td><td class="seg">A</td><td class="seg">Expire Logins</td></tr></tbody></table></div><p>Currently, OpenACS is unusable in practice without persistent +before.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Make_Non-Persistent_Login_Wor"></a>Recommended: +Make Non-Persistent Login Work</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-34: </span></strong>EXT-AUTH-34</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Expire Logins</div> + </div> + </div> + <p>Currently, OpenACS is unusable in practice without persistent login. The login will expire after just a few minutes of inactivity, and you'll get bounced to the login page where you have to enter both email and password again. Unacceptable in -practice.</p><p>We should change the default, so a non-persistent login +practice.</p> + <p>We should change the default, so a non-persistent login doesn't expire until you either close your browser, or a few hours have elapsed. Even if you are constantly active, the login should still expire after at most x number of hours. We can still make the login expire after a period of inactivity, but the amount of time should be configurable and default to something reasonable like an -hour or so.</p><p>This will require looking into and changing the design of the -current session handling code.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Single-Sign-O"></a>Recommended: -Single-Sign-On</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-23</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-23</td><td class="seg"></td><td class="seg">Single sign-on</td></tr></tbody></table></div><p>Instead of redirecting to the login page, auth::require_login +hour or so.</p> + <p>This will require looking into and changing the design of the +current session handling code.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Single-Sign-O"></a>Recommended: +Single-Sign-On</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-23: </span></strong>EXT-AUTH-23</div> + <div class="seg"><strong><span class="segtitle">: </span></strong></div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Single sign-on</div> + </div> + </div> + <p>Instead of redirecting to the login page, auth::require_login can redirect to an authentication server, which can redirect back to a page that logs the user in. This should be very easy to -implement.</p><p>Alternatively, if you want to combine this with fallback to +implement.</p> + <p>Alternatively, if you want to combine this with fallback to OpenACS accounts, we would instead present the normal login screen, but put a button which says "Login using X", where X is the -redirection-based external authority.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Expire_All_Login"></a>Recommended: -Expire All Logins</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-22</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-22</td><td class="seg">B</td><td class="seg">rewrite cookie handling</td></tr></tbody></table></div><p>Currently, if you've ever left a permanent login cookie on +redirection-based external authority.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Expire_All_Login"></a>Recommended: +Expire All Logins</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-22: </span></strong>EXT-AUTH-22</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>B</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>rewrite cookie handling</div> + </div> + </div> + <p>Currently, if you've ever left a permanent login cookie on someone elses machine, that person will be forever logged in until he/she explicitly logs out. You can change your password, you can do anything you want, but unless a logout is requested from that -particular browser, that browser will be logged in forever.</p><p>I want to change our session handling code so that old login +particular browser, that browser will be logged in forever.</p> + <p>I want to change our session handling code so that old login cookies can be expired. This would be done automatically whenever you change your password, and we could also offer a link which does this without changing passwords. It's an important security -measure.</p><p>The implementation is simply to autogenerate some secret +measure.</p> + <p>The implementation is simply to autogenerate some secret token which is stored in the users table, and is also stored in the cookie somehow. Then, whenever we want to expire all logins, we'll just regenerate a new secret token, and the other cookies will be void. Of course, we don't want to incur a DB hit on every request, so we'll need to cache the secret token, or only check it when refreshing the session cookie, which, I believe, normally happens -every 10 minutes or so.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Email_account_owner_on_password"></a>Recommended: -Email account owner on password change</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-24</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-24</td><td class="seg">A</td><td class="seg">Email on password change</td></tr></tbody></table></div><p>As an additional security measure, we should email the +every 10 minutes or so.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Recommended__Email_account_owner_on_password"></a>Recommended: +Email account owner on password change</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-24: </span></strong>EXT-AUTH-24</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Email on password change</div> + </div> + </div> + <p>As an additional security measure, we should email the account's email address whenever the password is changed, so that -he/she is at least alerted to the fact.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Password_polic"></a>Optional: -Password policy</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-25</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-25</td><td class="seg">A</td><td class="seg">Implement password policy</td></tr></tbody></table></div><p>Again, to increase security, we should add password policies, +he/she is at least alerted to the fact.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Password_polic"></a>Optional: +Password policy</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-25: </span></strong>EXT-AUTH-25</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Implement password policy</div> + </div> + </div> + <p>Again, to increase security, we should add password policies, such as passwords needing to be changed after a certain number of days, change on next login (after a new random password has been generated), or requiring that the password satisfies certain complexity rules, i.e. both upper and lowercase characters, -numbers, special chars, etc.</p><p>It would good to extend the current maximum password length -from 10 to at least 32 characters.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Login_Without_Explicit_Domai"></a>Optional: -Login Without Explicit Authority</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-26</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-26</td><td class="seg">B</td><td class="seg">Login without explicit domain</td></tr></tbody></table></div><p>In order to make it easier for people, we've been toying with -the idea of a functionality like this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If the user enters "foobar@ix.urz.uni-heidelberg.de", it +numbers, special chars, etc.</p> + <p>It would good to extend the current maximum password length +from 10 to at least 32 characters.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Login_Without_Explicit_Domai"></a>Optional: +Login Without Explicit Authority</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-26: </span></strong>EXT-AUTH-26</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>B</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Login without explicit domain</div> + </div> + </div> + <p>In order to make it easier for people, we've been toying with +the idea of a functionality like this:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If the user enters "foobar@ix.urz.uni-heidelberg.de", it is translated to mean username = "foobar", authority = "ix.urz.uni-heidelberg.de".</p></li><li class="listitem"><p>If the user enters "foobar", it's recognized to not include any authority, and the default authority of "ix.urz.uni-heidelberg.de" is used.</p></li><li class="listitem"><p>If the user enters "foo@bar.com", it's recognized as not belonging to any known authority, and as such, it's translated to mean - username = "foo@bar.com", authority = "local".</p></li></ul></div><p>If this is deemed desirable, a way to implement this would be -through these settings:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Split: A regexp which will split the user's entry into + username = "foo@bar.com", authority = "local".</p></li></ul></div> + <p>If this is deemed desirable, a way to implement this would be +through these settings:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Split: A regexp which will split the user's entry into username and authority parts. For example "^([^@]+)(@[^@]+)?$". An easier to use but less flexible method would be that you simply specify a certain character to split by, such as "@" or "\". If the regexp doesn't match, or in the latter case, if there's more than one occurrence of the specified character sequence, the split will fail, signaling that the user's entry was not valid.</p></li><li class="listitem"><p>Default authority: The default authority will be the first one - in the sort order.</p></li></ul></div><p>The relevant code in user-login.tcl would look like -this:</p><pre class="programlisting"> + in the sort order.</p></li></ul></div> + <p>The relevant code in user-login.tcl would look like +this:</p> + <pre class="programlisting"> if { ![auth::split_username -username_var username -authority_var authority] } { # bounce back to the form with a message saying that the login wasn't valid. ad_script_abort } # username will now contain username # authority will now contain authority -</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Whois_Onlin"></a>Optional: Who's Online</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-27</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-27</td><td class="seg">B</td><td class="seg">Who's online list</td></tr></tbody></table></div><p>While we're touching the session handling code, anyway, it +</pre> + + </div> + + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Whois_Onlin"></a>Optional: Who's Online</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-27: </span></strong>EXT-AUTH-27</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>B</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Who's online list</div> + </div> + </div> + <p>While we're touching the session handling code, anyway, it would be nice to add a feature to show who's currently online, a nice real-time collaboration feature frequently requested by members of the community. This is particularly interesting when integrated with a chat or instant messaging service like -Jabber.</p><p>What I'm concretely suggesting is that we keep a record of +Jabber.</p> + <p>What I'm concretely suggesting is that we keep a record of which authenticated users have requested pags on the site in the last x minutes (typically about 5), and thus are considered to be currently online. There's nothing more to it. This lets us display a list of "active users" somewhere on the site, and make their name -a link to a real-time chat service like Jabber.</p><p>We've already made the changes necessary to +a link to a real-time chat service like Jabber.</p> + <p>We've already made the changes necessary to security-procs.tcl to do this on an earlier project, but haven't -quite finished the work and put it back into the tree.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Subsite-level_configuratio"></a>Optional: -Subsite-level configuration</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-28</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-28</td><td class="seg"></td><td class="seg">implement subsite-level config</td></tr></tbody></table></div><p>If we want to, we could let subsite administrators configure +quite finished the work and put it back into the tree.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Optional__Subsite-level_configuratio"></a>Optional: +Subsite-level configuration</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-28: </span></strong>EXT-AUTH-28</div> + <div class="seg"><strong><span class="segtitle">: </span></strong></div> + <div class="seg"><strong><span class="segtitle">: </span></strong>implement subsite-level config</div> + </div> + </div> + <p>If we want to, we could let subsite administrators configure the login process for that particular subsite. This would probably only entail letting the subsite admin leave out certain authorities -defined site-wide, and change the sort order.</p><p>I think we should leave this out until we have a use case for -it, someone who'd need it.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Future__Making_the_Authentication_API_itself"></a>Future: -Making the Authentication API itself a service contract</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-32</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-32</td><td class="seg">A</td><td class="seg">Parameters for Service Contract Implementation</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-35</td><td class="seg">A</td><td class="seg">Make the Authentication API a service contract</td></tr></tbody></table></div><p>For completely free-form authentication logic and mechanisms, +defined site-wide, and change the sort order.</p> + <p>I think we should leave this out until we have a use case for +it, someone who'd need it.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Future__Making_the_Authentication_API_itself"></a>Future: +Making the Authentication API itself a service contract</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-32: </span></strong>EXT-AUTH-32</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Parameters for Service Contract Implementation</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-32: </span></strong>EXT-AUTH-35</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Make the Authentication API a service contract</div> + </div> + </div> + <p>For completely free-form authentication logic and mechanisms, something like Andrew Grumet's <a class="ulink" href="http://openacs.org/new-file-storage/download/oacs-pam.html?version_id=687" target="_top">Pluggable Authentication for OACS Draft</a> is interesting. He's proposing a scheme where the entire user interaction is encapsulated in, and left entirely to, a service contract. This certainly opens up more advanced possibilities, such as perhaps -smart cards, personal certificates, etc.</p><p>I have chosen not to go this route, because I think that most +smart cards, personal certificates, etc.</p> + <p>I have chosen not to go this route, because I think that most people are going to want to use a username/password-based scheme, and having easy configuration through a web UI is more important -than total flexibility at this point.</p><p>Besides, we can always do this in the future, by letting the +than total flexibility at this point.</p> + <p>Besides, we can always do this in the future, by letting the public Authentication API (<code class="literal">auth::require_login</code> and <code class="literal">auth::authenticate</code>) be implemented through a -service contract.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Future__Authenticating_against_multiple_serv"></a>Future: -Authenticating against multiple servers simultaneously</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>EXT-AUTH-36</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-36</td><td class="seg">A</td><td class="seg">Authenticate against multiple servers</td></tr></tbody></table></div><p>Both OKI and OpenACS supports a form of stacking, where you +service contract.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Future__Authenticating_against_multiple_serv"></a>Future: +Authenticating against multiple servers simultaneously</h4></div></div></div> + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">EXT-AUTH-36: </span></strong>EXT-AUTH-36</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Authenticate against multiple servers</div> + </div> + </div> + <p>Both OKI and OpenACS supports a form of stacking, where you can be logged into multiple authorities at the same time. This is useful if, for example, you need to get login tokens such as -Kerberos tickets for access to shared resources.</p><p>I can see the value in this, but for simplicity's sake, I'm +Kerberos tickets for access to shared resources.</p> + <p>I can see the value in this, but for simplicity's sake, I'm in favor of keeping this use-case out of the loop until we have someone with a real requirement who could help us guide -development.</p><p>For now, OpenACS is still more of an integrated suite, it +development.</p> + <p>For now, OpenACS is still more of an integrated suite, it doesn't access many outside applications. I think it would be excellent for OpenACS to do so, e.g. by using an IMAP server to store emails, an iCal server to store calendar appointments, LDAP for user/group data and access control lists, SMB for file storage, etc. But at the moment, we don't have any users of such things that are ready. We have some who are on the steps, but let's wait till -they're there.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Implement_Specific_Driver"></a>Implement -Specific Drivers</h4></div></div></div><div class="segmentedlist"><table border="1" cellpadding="3" cellspacing="0" width="90%"><tr><th width="15%">Feature</th><th width="8%">Status</th><th width="77%">Description</th></tr><thead><tr><th>Implement specific drivers</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">EXT-AUTH-09</td><td class="seg">A</td><td class="seg">Create Auth. drivers for Local Authority</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-10</td><td class="seg">A</td><td class="seg">Create Acct. Creation driver for Local Authority</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-11</td><td class="seg">A</td><td class="seg">Create Auth. driver for PAM</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-12</td><td class="seg">X</td><td class="seg"><span class="emphasis"><em>Create Acct. Creation driver for PAM - this - functionality is explicitly excluded from PAM</em></span></td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-13</td><td class="seg">A</td><td class="seg">Create Acct. Creation driver for LDAP</td></tr><tr class="seglistitem"><td class="seg">EXT-AUTH-14</td><td class="seg">A</td><td class="seg">Create Auth. driver for LDAP</td></tr></tbody></table></div><p>We'll need drivers for:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Operating system (Linux/Solaris) PAM: Delegate to the +they're there.</p> + </div> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Implement_Specific_Driver"></a>Implement +Specific Drivers</h4></div></div></div> + + <div class="segmentedlist"> + + + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Implement specific drivers: </span></strong>EXT-AUTH-09</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create Auth. drivers for Local Authority</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Implement specific drivers: </span></strong>EXT-AUTH-10</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create Acct. Creation driver for Local Authority</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Implement specific drivers: </span></strong>EXT-AUTH-11</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create Auth. driver for PAM</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Implement specific drivers: </span></strong>EXT-AUTH-12</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>X</div> + <div class="seg"><strong><span class="segtitle">: </span></strong><span class="emphasis"><em>Create Acct. Creation driver for PAM - this + functionality is explicitly excluded from PAM</em></span></div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Implement specific drivers: </span></strong>EXT-AUTH-13</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create Acct. Creation driver for LDAP</div> + </div> + <div class="seglistitem"> + <div class="seg"><strong><span class="segtitle">Implement specific drivers: </span></strong>EXT-AUTH-14</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>A</div> + <div class="seg"><strong><span class="segtitle">: </span></strong>Create Auth. driver for LDAP</div> + </div> + </div> + <p>We'll need drivers for:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Operating system (Linux/Solaris) PAM: Delegate to the operating system, which can then talk to RADIUS, LDAP, whatever. This is convenient because there'll be plenty of drivers for the OS PAM level, so we don't have to write them all ourselves. The downside is that we can't do things like account creation, password management, real-time account synchronization, etc., not supported by PAM (I'm not entirely sure what is and is not - supported).</p></li><li class="listitem"><p>RADIUS</p></li><li class="listitem"><p>LDAP</p></li></ul></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="RADIU"></a>RADIUS</h5></div></div></div><p>RADIUS is a simple username/password-type authentication -server.</p><p>It also supports sending a challenge to which the user must + supported).</p></li><li class="listitem"><p>RADIUS</p></li><li class="listitem"><p>LDAP</p></li></ul></div> + <div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="RADIU"></a>RADIUS</h5></div></div></div> + <p>RADIUS is a simple username/password-type authentication +server.</p> + <p>It also supports sending a challenge to which the user must respond with the proper answer (e.g. mother's maiden name, or could be additional password), but we will not support this -feature.</p><p>A RADIUS client +feature.</p> + <p>A RADIUS client <a class="ulink" href="http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi/exuserfolder/exUserFolder/radiusAuthSource/radius.py?rev=1.4&content-type=text/vnd.viewcvs-markup" target="_top">implementation in Python</a> can be found in the <a class="ulink" href="http://exuserfolder.sourceforge.net/" target="_top">exUserFolder module</a> for Zope -(<a class="ulink" href="http://sourceforge.net/docman/display_doc.php?docid=7238&group_id=36318" target="_top">documentation</a>).</p></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Feedbac"></a>Feedback</h3></div></div></div><p>We'd really appreciate feedback on this proposal. Please follow up at +(<a class="ulink" href="http://sourceforge.net/docman/display_doc.php?docid=7238&group_id=36318" target="_top">documentation</a>).</p> + </div> + </div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Feedbac"></a>Feedback</h3></div></div></div> + <p>We'd really appreciate feedback on this proposal. Please follow up at <a class="ulink" href="http://openacs.org/forums/message-view?message_id=97341" target="_top">this -openacs.org forums thread</a>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Reference"></a>References</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <a class="ulink" href="https://www.imsglobal.org/enterprise/index.html/" target="_top">IMS Enterprise</a></p></li><li class="listitem"><p><a class="ulink" href="http://openacs.org/projects/openacs/packages/ex-auth/" target="_top">Threads +openacs.org forums thread</a>.</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Reference"></a>References</h3></div></div></div> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> <a class="ulink" href="https://www.imsglobal.org/enterprise/index.html/" target="_top">IMS Enterprise</a></p> + </li><li class="listitem"><p><a class="ulink" href="http://openacs.org/projects/openacs/packages/ex-auth/" target="_top">Threads and links</a> collected by Carl Blesius.</p></li><li class="listitem"><p><a class="ulink" href="http://java.sun.com/security/jaas/doc/pam.html" target="_top">Solaris/Linux PAM specification</a></p></li><li class="listitem"><p><a class="ulink" href="http://openacs.org/new-file-storage/download/oacs-pam.html?version_id=687" target="_top">Draft Proposal</a> by Andrew Grumet.</p></li><li class="listitem"><p><a class="ulink" href="http://www.yale.edu/tp/auth/" target="_top">Yale CAS</a>, a central authentication service a' la - Passport.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="ext-auth-revision-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>1</td><td>Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.</td><td>20 Aug 2003</td><td>Joel Aufrecht</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Bootstrapping OpenACS </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Chapter 16. Releasing OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + Passport.</p></li></ul></div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="ext-auth-revision-history"></a>Revision History</h3></div></div></div> + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>1</td><td>Updated work-in-progress for consortium-sponsored ext-auth work at Collaboraid.</td><td>20 Aug 2003</td><td>Joel Aufrecht</td></tr></tbody></table> + </div> + </div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="bootstrap-acs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-openacs.html">Next</a></td></tr><tr><td width="40%" align="left">Bootstrapping OpenACS </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Chapter 16. Releasing OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/filename.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/filename.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/filename.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -194,8 +194,8 @@ <td>0.1</td><td>Creation</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td> </tr> </tbody> -</table></div><div class="cvstag">($‌Id: design-template.xml,v 1.8.14.1 2016/06/23 -08:32:46 gustafn Exp $)</div> +</table></div><p><span class="cvstag">($‌Id: design-template.xml,v 1.9 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/filename.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/filename.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/filename.html 7 Aug 2017 23:47:50 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/filename.html 8 Nov 2017 09:42:10 -0000 1.50 @@ -1,5 +1,12 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Detailed Design Documentation Template</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="nxml-mode.html" title="Using nXML mode in Emacs"><link rel="next" href="requirements-template.html" title="System/Application Requirements Template"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="nxml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="filename"></a>Detailed Design Documentation Template</h2></div></div></div><p>By <a class="ulink" href="mailto:youremail@example.com" target="_top">You</a></p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-start-note"></a>Start Note</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Detailed Design Documentation Template</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="nxml-mode.html" title="Using nXML mode in Emacs"><link rel="next" href="requirements-template.html" title="System/Application Requirements Template"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="nxml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="filename"></a>Detailed Design Documentation Template</h2></div></div></div> + + + <p>By <a class="ulink" href="mailto:youremail@example.com" target="_top">You</a></p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-start-note"></a>Start Note</h3></div></div></div> + + <p> <span class="emphasis"><em>NOTE: Some of the sections of this template may not apply to your package, e.g. there may be no user-visible UI elements for a component of the OpenACS Core. Furthermore, it may be easier in some circumstances @@ -10,49 +17,108 @@ requirements document. As this template is just a starting point, use your own judgment, consult with peers when possible, and adapt intelligently.</em></span> - </p><p> + </p> + + <p> <span class="emphasis"><em>Also, bear in mind <span class="strong"><strong>the audience</strong></span> for detailed design: fellow programmers who want to maintain/extend the software, AND parties interested in evaluating software quality. </em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-essentials"></a>Essentials</h3></div></div></div><p> + </p> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-essentials"></a>Essentials</h3></div></div></div> + + + <p> When applicable, each of the following items should receive its own link: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> User directory </p></li><li class="listitem"><p> OpenACS administrator directory </p></li><li class="listitem"><p> Subsite administrator directory </p></li><li class="listitem"><p> Tcl script directory (link to the API browser page for the package) </p></li><li class="listitem"><p> PL/SQL file (link to the API browser page for the package) </p></li><li class="listitem"><p> Data model </p></li><li class="listitem"><p> Requirements document </p></li><li class="listitem"><p> ER diagram </p></li><li class="listitem"><p> Transaction flow diagram </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-introduction"></a>Introduction</h3></div></div></div><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> User directory </p></li><li class="listitem"><p> OpenACS administrator directory </p></li><li class="listitem"><p> Subsite administrator directory </p></li><li class="listitem"><p> Tcl script directory (link to the API browser page for the package) </p></li><li class="listitem"><p> PL/SQL file (link to the API browser page for the package) </p></li><li class="listitem"><p> Data model </p></li><li class="listitem"><p> Requirements document </p></li><li class="listitem"><p> ER diagram </p></li><li class="listitem"><p> Transaction flow diagram </p></li></ul></div> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-introduction"></a>Introduction</h3></div></div></div> + + + + <p> This section should provide an overview of the package and address at least the following issues: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> What this package is intended to allow the user (or different + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> What this package is intended to allow the user (or different classes of users) to accomplish. </p></li><li class="listitem"><p> Within reasonable bounds, what this package is not intended to allow users to accomplish. </p></li><li class="listitem"><p> The application domains where this package is most likely to be of use. </p></li><li class="listitem"><p> A high-level overview of how the package meets its requirements (which should have been documented elsewhere). This is to include relevant material from the "features" section of the cover sheet (the cover sheet is a wrapper doc with links to all - other package docs). </p></li></ul></div><p> + other package docs). </p></li></ul></div> + + <p> Also worthy of treatment in this section: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> When applicable, a careful demarcation between the + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> When applicable, a careful demarcation between the functionality of this package and others which - at least - superficially - appear to address the same requirements. </p></li></ul></div><p> + superficially - appear to address the same requirements. </p></li></ul></div> + + <p> Note: it's entirely possible that a discussion of what a package is not intended to do differs from a discussion of future improvements for the package. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-historical-consid"></a>Historical Considerations</h3></div></div></div><p> + </p> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-historical-consid"></a>Historical Considerations</h3></div></div></div> + + + + <p> For a given set of requirements, typically many possible implementations and solutions exist. Although eventually only one solution is implemented, a discussion of the alternative solutions canvassed - noting why they were rejected - proves helpful to both current and future developers. All readers would be reminded as to why and how the particular solution developed over time, avoiding re-analysis of problems already solved. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-competitive-analysis"></a>Competitive Analysis</h3></div></div></div><p> + </p> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-competitive-analysis"></a>Competitive Analysis</h3></div></div></div> + + + + <p> Although currently only a few package documentation pages contain a discussion of competing software, (e.g. chat, portals), this section should be present whenever such competition exists. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> If your package exhibits features missing from competing + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> If your package exhibits features missing from competing software, this fact should be underscored. </p></li><li class="listitem"><p> If your package lacks features which are present in competing software, the reasons for this should be discussed here; our sales team needs to be ready for inquiries regarding features our software - lacks. </p></li></ul></div><p> + lacks. </p></li></ul></div> + + <p> Note that such a discussion may differ from a discussion of a package's potential future improvements. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div> + + + + <p> No single design solution can optimize every desirable software attribute. For example, an increase in the security of a system will likely entail a decrease in its ease-of-use, and an increase in the @@ -62,16 +128,36 @@ should include a discussion of the tradeoffs involved with the design chosen, and the reasons for your choices. Some areas of importance to keep in mind are: - </p><p>Areas of interest to users:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Performance: availability and efficiency </p></li><li class="listitem"><p> Flexibility </p></li><li class="listitem"><p> Interoperability </p></li><li class="listitem"><p> Reliability and robustness </p></li><li class="listitem"><p> Usability </p></li></ul></div><p>Areas of interest to developers:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Maintainability </p></li><li class="listitem"><p> Portability </p></li><li class="listitem"><p> Reusability </p></li><li class="listitem"><p> Testability </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-api"></a>API</h3></div></div></div><p> + </p> + + <p>Areas of interest to users:</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Performance: availability and efficiency </p></li><li class="listitem"><p> Flexibility </p></li><li class="listitem"><p> Interoperability </p></li><li class="listitem"><p> Reliability and robustness </p></li><li class="listitem"><p> Usability </p></li></ul></div> + + <p>Areas of interest to developers:</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Maintainability </p></li><li class="listitem"><p> Portability </p></li><li class="listitem"><p> Reusability </p></li><li class="listitem"><p> Testability </p></li></ul></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-api"></a>API</h3></div></div></div> + + + + <p> Here's where you discuss the abstractions used by your package, such as the procedures encapsulating the legal transactions on the data model. Explain the organization of procedures and their particulars (detail above and beyond what is documented in the code), including: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Problem-domain components: key algorithms, e.g. a specialized + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Problem-domain components: key algorithms, e.g. a specialized statistics package would implement specific mathematical procedures. </p></li><li class="listitem"><p> User-interface components: e.g. HTML widgets that the package may need. </p></li><li class="listitem"><p> Data management components: procedures that provide a stable interface to database objects and legal transactions - the latter - often correspond to tasks. </p></li></ul></div><p> + often correspond to tasks. </p></li></ul></div> + + <p> Remember that the correctness, completeness, and stability of the API and interface are what experienced members of our audience are looking for. This is a cultural shift for us at aD (as of mid-year 2000), in @@ -80,60 +166,141 @@ handle transactions, instead of encapsulating them via procedures). Experience has taught us that we need to focus on the API for maintainability of our systems in the face of constant change. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-data-model"></a>Data Model Discussion</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-data-model"></a>Data Model Discussion</h3></div></div></div> + + + + <p> The data model discussion should do more than merely display the SQL code, since this information is already be available via a link in the "essentials" section above. Instead, there should be a high-level discussion of how your data model meets your solution requirements: why the database entities were defined as they are, and what transactions you expect to occur. (There may be some overlap with the API section.) Here are some starting points: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> The data model discussion should address the intended usage + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> The data model discussion should address the intended usage of each entity (table, trigger, view, procedure, etc.) when this information is not obvious from an inspection of the data model itself. </p></li><li class="listitem"><p> If a core service or other subsystem is being used (e.g., the new parties and groups, permissions, etc.) this should also be mentioned. </p></li><li class="listitem"><p> Any default permissions should be identified herein. </p></li><li class="listitem"><p> Discuss any data model extensions which tie into other - packages. </p></li><li class="listitem"><p><span class="strong"><strong>Transactions</strong></span></p><p> Discuss modifications which the database may undergo from + packages. </p></li><li class="listitem"><p><span class="strong"><strong>Transactions</strong></span></p> + + <p> Discuss modifications which the database may undergo from your package. Consider grouping legal transactions according to the invoking user class, i.e. transactions by an OpenACS-admin, by - subsite-admin, by a user, by a developer, etc. </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-ui"></a>User Interface</h3></div></div></div><p> + subsite-admin, by a user, by a developer, etc. </p></li></ul></div> + + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-ui"></a>User Interface</h3></div></div></div> + + + + <p> In this section, discuss user interface issues and pages to be built; you can organize by the expected classes of users. These may include: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Developers</p></li><li class="listitem"><p> OpenACS administrators (previously known as site-wide administrators)</p></li><li class="listitem"><p> Subsite administrators</p></li><li class="listitem"><p> End users</p></li></ul></div><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Developers</p></li><li class="listitem"><p> OpenACS administrators (previously known as site-wide administrators)</p></li><li class="listitem"><p> Subsite administrators</p></li><li class="listitem"><p> End users</p></li></ul></div> + + <p> You may want to include page mockups, site-maps, or other visual aids. Ideally this section is informed by some prototyping you've done, to establish the package's usability with the client and other interested parties. - </p><p> + </p> + + <p> <span class="emphasis"><em>Note: In order that developer documentation be uniform across different system documents, these users should herein be designated as "the developer," "the OpenACS-admin," "the sub-admin," and "the user," respectively. </em></span> - </p><p> + </p> + + <p> Finally, note that as our templating system becomes more entrenched within the OpenACS, this section's details are likely to shift from UI specifics to template interface specifics. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-config"></a>Configuration/Parameters</h3></div></div></div><p> + </p> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-config"></a>Configuration/Parameters</h3></div></div></div> + + + + <p> Under OpenACS 5.9.0, parameters are set at two levels: at the global level by the OpenACS-admin, and at the subsite level by a sub-admin. In this section, list and discuss both levels of parameters. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div><p> + </p> + + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div> + + + + <p> If the system presently lacks useful/desirable features, note details here. You could also comment on non-functional improvements to the package, such as usability. - </p><p> + </p> + + <p> Note that a careful treatment of the earlier "competitive analysis" section can greatly facilitate the documenting of this section. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-authors"></a>Authors</h3></div></div></div><p> + </p> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-authors"></a>Authors</h3></div></div></div> + + + + <p> Although a system's data model file often contains this information, this isn't always the case. Furthermore, data model files often undergo substantial revision, making it difficult to track down the system creator. An additional complication: package documentation may be authored by people not directly involved in coding. Thus to avoid unnecessary confusion, include email links to the following roles as they may apply: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> System creator</p></li><li class="listitem"><p> System owner</p></li><li class="listitem"><p> Documentation author</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-revision-history"></a>Revision History</h3></div></div></div><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> System creator</p></li><li class="listitem"><p> System owner</p></li><li class="listitem"><p> Documentation author</p></li></ul></div> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-design-revision-history"></a>Revision History</h3></div></div></div> + + + + <p> <span class="emphasis"><em>The revision history table below is for this template - modify it as needed for your actual design document. </em></span> - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Creation</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nxml-mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr><tr><td width="40%" align="left">Using nXML mode in Emacs </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> System/Application Requirements Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Creation</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div> + + <p><span class="cvstag">($Id$)</span></p> + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="nxml-mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="requirements-template.html">Next</a></td></tr><tr><td width="40%" align="left">Using nXML mode in Emacs </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> System/Application Requirements Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/for-everyone.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/for-everyone.html,v diff -u -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/for-everyone.html 7 Aug 2017 23:47:50 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/for-everyone.html 8 Nov 2017 09:42:10 -0000 1.30 @@ -1,2 +1,6 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part I. OpenACS For Everyone</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="index.html" title="OpenACS Core Documentation"><link rel="next" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="for-everyone"></a>Part I. OpenACS For Everyone</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="general-documents.html">1. High level information: What is OpenACS?</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="release-notes.html">OpenACS Release Notes</a></span></dt></dl></dd></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Core Documentation </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 1. High level information: What is OpenACS?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Part I. OpenACS For Everyone</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="index.html" title="OpenACS Core Documentation"><link rel="next" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr></table><hr></div><div class="part"><div class="titlepage"><div><div><h1 class="title"><a name="for-everyone"></a>Part I. OpenACS For Everyone</h1></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="general-documents.html">1. High level information: What is OpenACS?</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="release-notes.html">OpenACS Release Notes</a></span></dt></dl></dd></dl></div> + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="index.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="general-documents.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Core Documentation </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> Chapter 1. High level information: What is OpenACS?</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/form-builder.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/form-builder.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/form-builder.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -12,11 +12,11 @@ <a name="form-builder" id="form-builder"></a>Using Form Builder: building html forms dynamically</h2></div></div></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="ad-form-overview" id="ad-form-overview"></a>Overview</h3></div></div></div><div class="authorblurb"> -<div class="cvstag">($‌Id: form-builder.xml,v 1.9.2.2 2016/06/23 -08:32:46 gustafn Exp $)</div> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>OpenACS has a form manager called ad_form. Ad_form has an +<a name="ad-form-overview" id="ad-form-overview"></a>Overview</h3></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red"><span class="cvstag">($‌Id: +form-builder.xml,v 1.10 2017/08/07 23:47:54 gustafn Exp +$)</span></span></p> +</authorblurb> +<p>OpenACS has a form manager called ad_form. Ad_form has an adaptable UI. Error handling includes inline error reporting, and is customizable. However, ad_form can be tricky to use. In addition to this document, the ad_form <a class="ulink" href="http://openacs.org/api-doc/proc-view?proc=ad_form" target="_top">api documentation</a> is helpful.</p> @@ -25,10 +25,10 @@ <a name="multi-part-elements" id="multi-part-elements"></a>Multi-part Elements</h3></div></div></div><p>Some elements have more than one choice, or can submit more than one value.</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118527752" id="idp140592118527752"></a>SELECT elements</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> +<a name="idp140623176711352" id="idp140623176711352"></a>SELECT elements</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> <p> -<strong>Creating the form element. </strong>Populate -a list of lists with values for the option list.</p><pre class="programlisting"> +<strong>Creating the form element. </strong> +Populate a list of lists with values for the option list.</p><pre class="programlisting"> set foo_options [db_list_of_lists foo_option_list " select foo, foo_id @@ -106,7 +106,7 @@ Errors</h3></div></div></div><p>Here are some common errors and what to do when you encounter them:</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592118550568" id="idp140592118550568"></a>Error when selecting values</h4></div></div></div><p>This generally happens when there is an error in your query.</p> +<a name="idp140623176734104" id="idp140623176734104"></a>Error when selecting values</h4></div></div></div><p>This generally happens when there is an error in your query.</p> </div> </div> </div> Index: openacs-4/packages/acs-core-docs/www/form-builder.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/form-builder.html,v diff -u -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/form-builder.html 7 Aug 2017 23:47:50 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/form-builder.html 8 Nov 2017 09:42:10 -0000 1.32 @@ -1,47 +1,96 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using Form Builder: building html forms dynamically</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="next" href="eng-standards.html" title="Chapter 12. Engineering Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="form-builder"></a>Using Form Builder: building html forms dynamically</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="ad-form-overview"></a>Overview</h3></div></div></div><div class="authorblurb"><div class="cvstag">($Id$)</div> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>OpenACS has a form manager called ad_form. Ad_form has an +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using Form Builder: building html forms dynamically</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="programming-with-aolserver.html" title="Programming with AOLserver"><link rel="next" href="eng-standards.html" title="Chapter 12. Engineering Standards"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="form-builder"></a>Using Form Builder: building html forms dynamically</h2></div></div></div> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="ad-form-overview"></a>Overview</h3></div></div></div> + +<span style="color: red"><authorblurb> + <p><span class="cvstag">($Id$)</span></p> +</authorblurb></span> +<p>OpenACS has a form manager called ad_form. Ad_form has an adaptable UI. Error handling includes inline error reporting, and is customizable. However, ad_form can be tricky to use. In addition to this document, the ad_form <a class="ulink" href="http://openacs.org/api-doc/proc-view?proc=ad_form" target="_top">api - documentation</a> is helpful.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="multi-part-elements"></a>Multi-part Elements</h3></div></div></div><p>Some elements have more than one choice, or can submit more than one value.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118527752"></a>SELECT elements</h4></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Creating the form element. </b>Populate a list of lists with values for the option list.</p><pre class="programlisting">set foo_options [db_list_of_lists foo_option_list " + documentation</a> is helpful.</p> + +</div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="multi-part-elements"></a>Multi-part Elements</h3></div></div></div> + + <p>Some elements have more than one choice, or can submit more than one value.</p> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176711352"></a>SELECT elements</h4></div></div></div> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Creating the form element. </b> + Populate a list of lists with values for the option list. + </p> + <pre class="programlisting">set foo_options [db_list_of_lists foo_option_list " select foo, foo_id from foos "] -</pre><p>The variable <code class="computeroutput">foo_options</code> should resemble <code class="computeroutput">{{first foo} 1234} {{second foo} 1235} -</code></p><p>Within ad_form, set up the element to use this list:</p><pre class="programlisting">{foo:text(select) +</pre> + <p>The variable <code class="computeroutput">foo_options</code> should resemble <code class="computeroutput">{{first foo} 1234} {{second foo} 1235} +</code></p> + <p>Within ad_form, set up the element to use this list:</p> + <pre class="programlisting">{foo:text(select) {label "Which Foo"} {options $foo_options} - }</pre><p>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 <code class="computeroutput">-new_data</code> and <code class="computeroutput">-edit_data</code>. In the example, it is available as <code class="computeroutput">$foo</code></p></li></ol></div><p>See also the + }</pre> + <p>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 <code class="computeroutput">-new_data</code> and <code class="computeroutput">-edit_data</code>. In the example, it is available as <code class="computeroutput">$foo</code></p> + </li></ol></div> + <p>See also the <a class="ulink" href="http://www.w3.org/TR/html401/interact/forms.html#h-17.6" target="_top">W3C spec for "The SELECT, OPTGROUP, and OPTION elements"</a>. - </p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="refreshing"></a>Using refreshes to pull additional information from the - database</h3></div></div></div><p>A situation you may run into often is where you want to pull + </p> + </div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="refreshing"></a>Using refreshes to pull additional information from the + database</h3></div></div></div> + + <p>A situation you may run into often is where you want to pull in form items from a sub-category when the first category is selected. Ad_form makes this fairly easy to do. In the definition - of your form element, include an html section</p><pre class="programlisting"> {pm_task_id:integer(select),optional + of your form element, include an html section</p> + + <pre class="programlisting"> {pm_task_id:integer(select),optional {label "Subject"} {options {$task_options}} {html {onChange "document.form_name.__refreshing_p.value='1';submit()"}} {value $pm_task_id} } - </pre><p>What this will do is set the value for pm_task_id and all the + </pre> + + <p>What this will do is set the value for pm_task_id and all the other form elements, and resubmit the form. If you then include a block that extends the form, you'll have the opportunity to add in subcategories: - </p><pre class="programlisting"> if {[info exists pm_task_id] && $pm_task_id ne ""} { + </p> + <pre class="programlisting"> if {[info exists pm_task_id] && $pm_task_id ne ""} { db_1row get_task_values { } ad_form -extend -name form_name -form { ... } - </pre><p>Note that you will get strange results when you try to set + </pre> + + <p>Note that you will get strange results when you try to set the values for the form. You'll need to set them explicitly in an -on_refresh section of your ad_form. In that section, you'll get - the values from the database, and set the values as so:</p><pre class="programlisting"> db_1row get_task_values { } + the values from the database, and set the values as so:</p> + + <pre class="programlisting"> db_1row get_task_values { } template::element set_value form_name estimated_hours_work $estimated_hours_work - </pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="form-troubleshooting"></a>Troubleshooting</h3></div></div></div><p>A good way to troubleshoot when you're using ad_form is to + </pre> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="form-troubleshooting"></a>Troubleshooting</h3></div></div></div> + + <p>A good way to troubleshoot when you're using ad_form is to add the following code at the top of the .tcl page (thanks Jerry - Asher):</p><pre class="programlisting"> + Asher):</p> + + <pre class="programlisting"> ns_log notice it's my page! set mypage [ns_getform] if {$mypage eq ""} { @@ -50,6 +99,26 @@ ns_log notice the following form was submitted on my page ns_set print $mypage } - </pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="form-widgets"></a>Tips for form widgets</h3></div></div></div><p>Here are some tips for dealing with some of the form widgets:</p><p><a class="ulink" href="http://openacs.org/forums/message-view?message_id=106331" target="_top">Current widget</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="errors"></a>Common Errors</h3></div></div></div><p>Here are some common errors and what to do when you - encounter them:</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592118550568"></a>Error when selecting values</h4></div></div></div><p>This generally happens when there is an error in your - query.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr><tr><td width="40%" align="left">Programming with AOLserver </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Chapter 12. Engineering Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="form-widgets"></a>Tips for form widgets</h3></div></div></div> + + <p>Here are some tips for dealing with some of the form widgets:</p> + + <p><a class="ulink" href="http://openacs.org/forums/message-view?message_id=106331" target="_top">Current widget</a></p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="errors"></a>Common Errors</h3></div></div></div> + + <p>Here are some common errors and what to do when you + encounter them:</p> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623176734104"></a>Error when selecting values</h4></div></div></div> + + <p>This generally happens when there is an error in your + query.</p> + </div> + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="programming-with-aolserver.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards.html">Next</a></td></tr><tr><td width="40%" align="left">Programming with AOLserver </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Chapter 12. Engineering Standards</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/general-documents.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/general-documents.html,v diff -u -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/general-documents.html 7 Aug 2017 23:47:50 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/general-documents.html 8 Nov 2017 09:42:10 -0000 1.30 @@ -1,2 +1,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 1. High level information: What is OpenACS?</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="for-everyone.html" title="Part I. OpenACS For Everyone"><link rel="previous" href="for-everyone.html" title="Part I. OpenACS For Everyone"><link rel="next" href="openacs-overview.html" title="Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><th width="60%" align="center">Part I. OpenACS For Everyone</th><td width="20%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="general-documents"></a>Chapter 1. High level information: What is OpenACS?</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="openacs-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="release-notes.html">OpenACS Release Notes</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part I. OpenACS For Everyone </td><td width="20%" align="center"><a accesskey="u" href="for-everyone.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 1. High level information: What is OpenACS?</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="for-everyone.html" title="Part I. OpenACS For Everyone"><link rel="previous" href="for-everyone.html" title="Part I. OpenACS For Everyone"><link rel="next" href="openacs-overview.html" title="Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><th width="60%" align="center">Part I. OpenACS For Everyone</th><td width="20%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="general-documents"></a>Chapter 1. High level information: What is OpenACS?</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="openacs-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="release-notes.html">OpenACS Release Notes</a></span></dt></dl></div> + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="for-everyone.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part I. OpenACS For Everyone </td><td width="20%" align="center"><a accesskey="u" href="for-everyone.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/groups-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/groups-design.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/groups-design.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="subsites-requirements" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="groups-design" id="groups-design"></a>Groups Design</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and Mark Thomas</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="groups-design" id="groups-design"></a>Groups Design</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and +Mark Thomas</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="groups-design-essentials" id="groups-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>User directory</p></li><li class="listitem"><p>Sitewide administrator directory</p></li><li class="listitem"><p>Subsite administrator directory</p></li><li class="listitem"><p>Tcl script directory</p></li><li class="listitem"><p><a class="xref" href="groups-requirements" title="Groups Requirements">OpenACS 4 Groups Requirements</a></p></li><li class="listitem"><p>Data model</p></li><li class="listitem"> Index: openacs-4/packages/acs-core-docs/www/groups-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-design.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/groups-design.html 7 Aug 2017 23:47:50 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/groups-design.html 8 Nov 2017 09:42:10 -0000 1.36 @@ -1,31 +1,79 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Groups Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="groups-requirements.html" title="Groups Requirements"><link rel="next" href="subsites-requirements.html" title="Subsites Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groups-design"></a>Groups Design</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and Mark Thomas</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User directory</p></li><li class="listitem"><p>Sitewide administrator directory</p></li><li class="listitem"><p>Subsite administrator directory</p></li><li class="listitem"><p>Tcl script directory</p></li><li class="listitem"><p><a class="xref" href="groups-requirements.html" title="Groups Requirements">OpenACS 4 Groups Requirements</a></p></li><li class="listitem"><p>Data model</p></li><li class="listitem"><p>PL/SQL file </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=community-core-create.sql&package_key=acs-kernel" target="_top"> -community-core-create.sql</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=groups-create.sql&package_key=acs-kernel" target="_top">groups-create.sql</a></p></li></ul></div></li><li class="listitem"><p>ER diagram</p></li><li class="listitem"><p>Transaction flow diagram</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-intro"></a>Introduction</h3></div></div></div><p>Almost all database-backed websites have users, and need to model the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Groups Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="groups-requirements.html" title="Groups Requirements"><link rel="next" href="subsites-requirements.html" title="Subsites Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groups-design"></a>Groups Design</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and Mark Thomas</p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-essentials"></a>Essentials</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User directory</p></li><li class="listitem"><p>Sitewide administrator directory</p></li><li class="listitem"><p>Subsite administrator directory</p></li><li class="listitem"><p>Tcl script directory</p></li><li class="listitem"><p><a class="xref" href="groups-requirements.html" title="Groups Requirements">OpenACS 4 Groups Requirements</a></p></li><li class="listitem"><p>Data model</p></li><li class="listitem"><p>PL/SQL file </p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=community-core-create.sql&package_key=acs-kernel" target="_top"> +community-core-create.sql</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=groups-create.sql&package_key=acs-kernel" target="_top">groups-create.sql</a></p></li></ul></div> +</li><li class="listitem"><p>ER diagram</p></li><li class="listitem"><p>Transaction flow diagram</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-intro"></a>Introduction</h3></div></div></div> + + + +<p>Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services -for different user communities.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-hist-considerations"></a>Historical Considerations</h3></div></div></div><p>The primary limitation of the OpenACS 3.x user group system is that it +for different user communities.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-hist-considerations"></a>Historical Considerations</h3></div></div></div> + + + +<p>The primary limitation of the OpenACS 3.x user group system is that it restricts the application developer to representing a "flat group" that contains only users: The <code class="computeroutput">user_groups</code> table may contain the <code class="computeroutput">group_id</code> of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships -expensive.</p><p>In addition, the Module Scoping design in OpenACS 3.0 introduced a +expensive.</p> + +<p>In addition, the Module Scoping design in OpenACS 3.0 introduced a <span class="emphasis"><em>party</em></span> abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of <code class="computeroutput">scope</code>, <code class="computeroutput">user_id</code>, and <code class="computeroutput">group_id</code> columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer -to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>add these three columns to each "scoped" table</p></li><li class="listitem"><p>define a multi-column check constraint to protect against data corruption +to:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>add these three columns to each "scoped" table</p></li><li class="listitem"><p>define a multi-column check constraint to protect against data corruption (e.g., a row with a <code class="computeroutput">scope</code> value of "group" but a null <code class="computeroutput">group_id</code>)</p></li><li class="listitem"><p>perform extra checks in <code class="computeroutput">Tcl</code> and <code class="computeroutput">PL/SQL</code> functions and procedures to check both the <code class="computeroutput">user_id</code> and -<code class="computeroutput">group_id</code> values</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-competitors"></a>Competitive Analysis</h3></div></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div><p>The core of the Group Systems data model is quite simple, but it was +<code class="computeroutput">group_id</code> values</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-competitors"></a>Competitive Analysis</h3></div></div></div> + + + +<p>...</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div> + + + +<p>The core of the Group Systems data model is quite simple, but it was designed in the hopes of modeling "real world" organizations which can be complex graph structures. The Groups System only considers groups that can be modeled using directed acyclic graphs, but queries over these @@ -34,12 +82,24 @@ views, and auxiliary tables have been created in the hopes of increasing performance. To keep the triggers simple and the number of triggers small, the data model disallows updates on the membership and composition tables, -only inserts and deletes are permitted.</p><p>The data model has tried to balance the need to model actual organizations +only inserts and deletes are permitted.</p> + +<p>The data model has tried to balance the need to model actual organizations without making the system too complex or too slow. The added triggers, views, and tables and will increase storage requirements and the insert and delete times in an effort to speed access time. The limited flexibility (no updates -on membership) trades against the complexity of the code.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-data-model"></a>Data Model Discussion</h3></div></div></div><p>The Group System data model consists of the following tables:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">parties</code> +on membership) trades against the complexity of the code.</p> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-data-model"></a>Data Model Discussion</h3></div></div></div> + + + +<p>The Group System data model consists of the following tables:</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">parties</code> + </span></dt><dd><p>The set of all defined parties: any <span class="emphasis"><em>person</em></span>, <span class="emphasis"><em>user</em></span>, or <span class="emphasis"><em>group</em></span> must have a corresponding row in this table.</p></dd><dt><span class="term"><code class="computeroutput">persons</code> @@ -72,10 +132,14 @@ </span></dt><dd><p>A mapping of a group <span class="strong"><strong>G</strong></span>to the set of groups {<span class="strong"><strong>G<sub>i</sub></strong></span>} that <span class="strong"><strong>G</strong></span> is a component of; this mapping includes the type of relationship by including the -appropriate<code class="computeroutput">rel_id</code> from the <code class="computeroutput">composition_rels</code> table.</p></dd></dl></div><p>New groups are created through the <code class="computeroutput">group.new</code> constructor. +appropriate<code class="computeroutput">rel_id</code> from the <code class="computeroutput">composition_rels</code> table.</p></dd></dl></div> + +<p>New groups are created through the <code class="computeroutput">group.new</code> constructor. When a specialized type of group is required, the group type can be extended by an application developer. Membership constraints can be specified at -creation time by passing a parent group to the constructor.</p><p>The <code class="computeroutput">membership_rels</code> and <code class="computeroutput">composition_rels</code> tables indicate +creation time by passing a parent group to the constructor.</p> + +<p>The <code class="computeroutput">membership_rels</code> and <code class="computeroutput">composition_rels</code> tables indicate a group's direct members and direct components; these tables do not provide a record of the members or components that are in the group by virtue of being a member or component of one of the group's component groups. @@ -86,9 +150,13 @@ paragraph) which watch for changes in membership or composition and update tables that maintain the group party mappings, i.e., <code class="computeroutput">group_member_index</code> and <code class="computeroutput">group_component_index</code>. One can think -of these tables as a manually maintained index.</p><p>The following triggers keep the <code class="computeroutput">group_*_index</code> tables up to -date:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">membership_rels_in_tr</code> +of these tables as a manually maintained index.</p> +<p>The following triggers keep the <code class="computeroutput">group_*_index</code> tables up to +date:</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">membership_rels_in_tr</code> + </span></dt><dd><p>Is executed when a new group/member relationship is created (an insert on <code class="computeroutput">membership_rels</code>)</p></dd><dt><span class="term"><code class="computeroutput">membership_rels_del_tr</code> @@ -99,11 +167,15 @@ on <code class="computeroutput">composition_rels</code>)</p></dd><dt><span class="term"><code class="computeroutput">composition_rels_del_tr</code> </span></dt><dd><p>Is executed when a group/component relationship is deleted (a delete on -<code class="computeroutput">composition_rels</code>)</p></dd></dl></div><p>The data model provides the following views onto the +<code class="computeroutput">composition_rels</code>)</p></dd></dl></div> + +<p>The data model provides the following views onto the <code class="computeroutput">group_member_index</code> and <code class="computeroutput">group_component_index</code> tables. No code outside of Groups System should modify the <code class="computeroutput">group_*_index</code> -tables.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">group_member_map</code> +tables.</p> +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">group_member_map</code> + </span></dt><dd><p>A mapping of a party to the groups the party is a member of; this mapping includes the type of relationship by including the appropriate<code class="computeroutput">rel_id</code> from the <code class="computeroutput">membership_rels</code> table.</p></dd><dt><span class="term"><code class="computeroutput">group_approved_member_map</code> @@ -129,17 +201,42 @@ </span></dt><dd><p>A mapping of a party <span class="strong"><strong>P</strong></span> to the set of parties {<span class="strong"><strong>P<sub>i</sub></strong></span>} party <span class="strong"><strong>P</strong></span> is an -<span class="strong"><strong>approved</strong></span> member of.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-api"></a>API</h3></div></div></div><p> +<span class="strong"><strong>approved</strong></span> member of.</p></dd></dl></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-api"></a>API</h3></div></div></div> + + +<p> The API consists of tables and views and PL/SQL functions. -</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="groups-design-tables-views"></a>Tables and Views</h4></div></div></div><p>The <code class="computeroutput">group_types</code> table is used to create new types of groups.</p><p>The <code class="computeroutput">group_member_map</code>, <code class="computeroutput">group_approved_member_map</code>, +</p> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="groups-design-tables-views"></a>Tables and Views</h4></div></div></div> + + +<p>The <code class="computeroutput">group_types</code> table is used to create new types of groups.</p> + +<p>The <code class="computeroutput">group_member_map</code>, <code class="computeroutput">group_approved_member_map</code>, <code class="computeroutput">group_distinct_member_map</code>, <code class="computeroutput">group_component_map</code>, <code class="computeroutput">party_member_map</code>, and <code class="computeroutput">party_approved_member_map</code> views are -used to query group membership and composition.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="groups-design-pl-sql-api"></a>PL/SQL API</h4></div></div></div><p><span class="strong"><strong>Person</strong></span></p><p><code class="computeroutput">person.new</code> creates a new person and returns the +used to query group membership and composition.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="groups-design-pl-sql-api"></a>PL/SQL API</h4></div></div></div> + + +<p><span class="strong"><strong>Person</strong></span></p> + +<p><code class="computeroutput">person.new</code> creates a new person and returns the <code class="computeroutput">person_id</code>. The function must be given the full name of the person in two pieces: <code class="computeroutput">first_names</code> and <code class="computeroutput">last_name</code>. All other fields are optional and default to null except for <code class="computeroutput">object_type</code> which defaults to person and <code class="computeroutput">creation_date</code> which defaults to <code class="computeroutput">sysdate</code>. The -interface for this function is:</p><pre class="programlisting"> +interface for this function is:</p> + +<pre class="programlisting"> function person.new ( person_id persons.person_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -151,20 +248,34 @@ first_names persons.first_names%TYPE, last_name persons.last_name%TYPE ) return persons.person_id%TYPE; -</pre><p><code class="computeroutput">person.delete</code> deletes the person whose <code class="computeroutput">person_id</code> is -passed to it. The interface for this procedure is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">person.delete</code> deletes the person whose <code class="computeroutput">person_id</code> is +passed to it. The interface for this procedure is:</p> + +<pre class="programlisting"> procedure person.delete ( person_id persons.person_id%TYPE ); -</pre><p><code class="computeroutput">person.name</code> returns the name of the person whose -<code class="computeroutput">person_id</code> is passed to it. The interface for this function is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">person.name</code> returns the name of the person whose +<code class="computeroutput">person_id</code> is passed to it. The interface for this function is:</p> + +<pre class="programlisting"> function person.name ( person_id persons.person_id%TYPE ) return varchar; -</pre><p><span class="strong"><strong>User</strong></span></p><p><code class="computeroutput">acs_user.new</code> creates a new user and returns the <code class="computeroutput">user_id</code>. +</pre> + +<p><span class="strong"><strong>User</strong></span></p> + +<p><code class="computeroutput">acs_user.new</code> creates a new user and returns the <code class="computeroutput">user_id</code>. The function must be given the user's email address and the full name of the user in two pieces: <code class="computeroutput">first_names</code> and <code class="computeroutput">last_name</code>. All -other fields are optional. The interface for this function is:</p><pre class="programlisting"> +other fields are optional. The interface for this function is:</p> + +<pre class="programlisting"> function acs_user.new ( user_id users.user_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -182,33 +293,51 @@ screen_name users.screen_name%TYPE, email_verified_p users.email_verified_p%TYPE ) return users.user_id%TYPE; -</pre><p><code class="computeroutput">acs_user.delete</code> deletes the user whose <code class="computeroutput">user_id</code> is passed -to it. The interface for this procedure is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">acs_user.delete</code> deletes the user whose <code class="computeroutput">user_id</code> is passed +to it. The interface for this procedure is:</p> + +<pre class="programlisting"> procedure acs_user.delete ( user_id users.user_id%TYPE ); -</pre><p><code class="computeroutput">acs_user.receives_alerts_p</code> returns 't' if the user should +</pre> + +<p><code class="computeroutput">acs_user.receives_alerts_p</code> returns 't' if the user should receive email alerts and 'f' otherwise. The interface for this -function is:</p><pre class="programlisting"> +function is:</p> + +<pre class="programlisting"> function acs_user.receives_alerts_p ( user_id users.user_id%TYPE ) return varchar; -</pre><p>Use the procedures <code class="computeroutput">acs_user.approve_email</code> and +</pre> + +<p>Use the procedures <code class="computeroutput">acs_user.approve_email</code> and <code class="computeroutput">acs_user.unapprove_email</code> to specify whether the user's email -address is valid. The interface for these procedures are:</p><pre class="programlisting"> +address is valid. The interface for these procedures are:</p> + +<pre class="programlisting"> procedure acs_user.approve_email ( user_id users.user_id%TYPE ); procedure acs_user.unapprove_email ( user_id users.user_id%TYPE ); -</pre><p><span class="strong"><strong>Group</strong></span></p><p><code class="computeroutput">acs_group.new</code> creates a new group and returns the +</pre> + +<p><span class="strong"><strong>Group</strong></span></p> + +<p><code class="computeroutput">acs_group.new</code> creates a new group and returns the <code class="computeroutput">group_id</code>. All fields are optional and default to null except for <code class="computeroutput">object_type</code> which defaults to 'group', <code class="computeroutput">creation_date</code> which defaults to <code class="computeroutput">sysdate</code>, and <code class="computeroutput">group_name</code> which is required. The interface for -this function is:</p><pre class="programlisting"> +this function is:</p> + +<pre class="programlisting"> function acs_group.new ( group_id groups.group_id%TYPE, object_type acs_objects.object_type%TYPE, @@ -219,22 +348,36 @@ url parties.url%TYPE, group_name groups.group_name%TYPE ) return groups.group_id%TYPE; -</pre><p><code class="computeroutput">acs_group.name</code> returns the name of the group whose -<code class="computeroutput">group_id</code> is passed to it. The interface for this function is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">acs_group.name</code> returns the name of the group whose +<code class="computeroutput">group_id</code> is passed to it. The interface for this function is:</p> + +<pre class="programlisting"> function acs_group.name ( group_id groups.group_id%TYPE ) return varchar; -</pre><p><code class="computeroutput">acs_group.member_p</code> returns 't' if the specified party is +</pre> + +<p><code class="computeroutput">acs_group.member_p</code> returns 't' if the specified party is a member of the specified group. Returns 'f' otherwise. The interface -for this function is:</p><pre class="programlisting"> +for this function is:</p> + +<pre class="programlisting"> function acs_group.member_p ( group_id groups.group_id%TYPE, party_id parties.party_id%TYPE, ) return char; -</pre><p><span class="strong"><strong>Membership Relationship</strong></span></p><p><code class="computeroutput">membership_rel.new</code> creates a new membership relationship type +</pre> + +<p><span class="strong"><strong>Membership Relationship</strong></span></p> + +<p><code class="computeroutput">membership_rel.new</code> creates a new membership relationship type between two parties and returns the relationship type's <code class="computeroutput">rel_id</code>. All fields are optional and default to null except for <code class="computeroutput">rel_type</code> -which defaults to membership_rel. The interface for this function is:</p><pre class="programlisting"> +which defaults to membership_rel. The interface for this function is:</p> + +<pre class="programlisting"> function membership_rel.new ( rel_id membership_rels.rel_id%TYPE, rel_type acs_rels.rel_type%TYPE, @@ -244,43 +387,73 @@ creation_user acs_objects.creation_user%TYPE, creation_ip acs_objects.creation_ip%TYPE, ) return membership_rels.rel_id%TYPE; -</pre><p><code class="computeroutput">membership_rel.ban</code> sets the <code class="computeroutput">member_state</code> of the given -<code class="computeroutput">rel_id</code> to 'banned'. The interface for this procedure is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">membership_rel.ban</code> sets the <code class="computeroutput">member_state</code> of the given +<code class="computeroutput">rel_id</code> to 'banned'. The interface for this procedure is:</p> + +<pre class="programlisting"> procedure membership_rel.ban ( rel_id membership_rels.rel_id%TYPE ); -</pre><p><code class="computeroutput">membership_rel.approve</code> sets the <code class="computeroutput">member_state</code> of the +</pre> + +<p><code class="computeroutput">membership_rel.approve</code> sets the <code class="computeroutput">member_state</code> of the given <code class="computeroutput">rel_id</code> to 'approved'. The interface for this procedure -is:</p><pre class="programlisting"> +is:</p> + +<pre class="programlisting"> procedure membership_rel.approve ( rel_id membership_rels.rel_id%TYPE ); -</pre><p><code class="computeroutput">membership_rel.reject</code> sets the <code class="computeroutput">member_state</code> of the given -<code class="computeroutput">rel_id</code> to 'rejected. The interface for this procedure is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">membership_rel.reject</code> sets the <code class="computeroutput">member_state</code> of the given +<code class="computeroutput">rel_id</code> to 'rejected. The interface for this procedure is:</p> + +<pre class="programlisting"> procedure membership_rel.reject ( rel_id membership_rels.rel_id%TYPE ); -</pre><p><code class="computeroutput">membership_rel.unapprove</code> sets the <code class="computeroutput">member_state</code> of the +</pre> + +<p><code class="computeroutput">membership_rel.unapprove</code> sets the <code class="computeroutput">member_state</code> of the given <code class="computeroutput">rel_id</code> to an empty string ''. The interface for this -procedure is:</p><pre class="programlisting"> +procedure is:</p> + +<pre class="programlisting"> procedure membership_rel.unapprove ( rel_id membership_rels.rel_id%TYPE ); -</pre><p><code class="computeroutput">membership_rel.deleted</code> sets the <code class="computeroutput">member_state</code> of the +</pre> + +<p><code class="computeroutput">membership_rel.deleted</code> sets the <code class="computeroutput">member_state</code> of the given <code class="computeroutput">rel_id</code> to 'deleted'. The interface for this procedure -is:</p><pre class="programlisting"> +is:</p> + +<pre class="programlisting"> procedure membership_rel.deleted ( rel_id membership_rels.rel_id%TYPE ); -</pre><p><code class="computeroutput">membership_rel.delete</code> deletes the given <code class="computeroutput">rel_id</code>. The -interface for this procedure is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">membership_rel.delete</code> deletes the given <code class="computeroutput">rel_id</code>. The +interface for this procedure is:</p> + +<pre class="programlisting"> procedure membership_rel.delete ( rel_id membership_rels.rel_id%TYPE ); -</pre><p><span class="strong"><strong>Composition Relationship</strong></span></p><p><code class="computeroutput">composition_rel.new</code> creates a new composition relationship type +</pre> + +<p><span class="strong"><strong>Composition Relationship</strong></span></p> + +<p><code class="computeroutput">composition_rel.new</code> creates a new composition relationship type and returns the relationship's <code class="computeroutput">rel_id</code>. All fields are optional and default to null except for <code class="computeroutput">rel_type</code> which defaults to -composition_rel. The interface for this function is:</p><pre class="programlisting"> +composition_rel. The interface for this function is:</p> + +<pre class="programlisting"> function membership_rel.new ( rel_id composition_rels.rel_id%TYPE, rel_type acs_rels.rel_type%TYPE, @@ -289,19 +462,78 @@ creation_user acs_objects.creation_user%TYPE, creation_ip acs_objects.creation_ip%TYPE, ) return composition_rels.rel_id%TYPE; -</pre><p><code class="computeroutput">composition_rel.delete</code> deletes the given <code class="computeroutput">rel_id</code>. The -interface for this procedure is:</p><pre class="programlisting"> +</pre> + +<p><code class="computeroutput">composition_rel.delete</code> deletes the given <code class="computeroutput">rel_id</code>. The +interface for this procedure is:</p> + +<pre class="programlisting"> procedure membership_rel.delete ( rel_id composition_rels.rel_id%TYPE ); -</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-ui"></a>User Interface</h3></div></div></div><p>Describe the admin pages.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-config"></a>Configuration/Parameters</h3></div></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-acc-tests"></a>Acceptance Tests</h3></div></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-authors"></a>Authors</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">System creator +</pre> +</div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-ui"></a>User Interface</h3></div></div></div> + + + +<p>Describe the admin pages.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-config"></a>Configuration/Parameters</h3></div></div></div> + + + +<p>...</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-acc-tests"></a>Acceptance Tests</h3></div></div></div> + + + +<p>...</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div> + + + +<p>...</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-authors"></a>Authors</h3></div></div></div> + + + +<div class="variablelist"><dl class="variablelist"><dt><span class="term">System creator + </span></dt><dd><p><a class="ulink" href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">System owner </span></dt><dd><p><a class="ulink" href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">Documentation author -</span></dt><dd><p>Mark Thomas</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th><span class="strong"><strong>Document Revision #</strong></span></th><th><span class="strong"><strong>Action Taken, Notes</strong></span></th><th><span class="strong"><strong>When?</strong></span></th><th><span class="strong"><strong>By Whom?</strong></span></th></tr></thead><tbody><tr><td>0.1</td><td>Creation</td><td>08/22/2000</td><td><a class="ulink" href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></td></tr><tr><td>0.2</td><td>Initial Revision</td><td>08/30/2000</td><td> +</span></dt><dd><p>Mark Thomas</p></dd></dl></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-design-rev-history"></a>Revision History</h3></div></div></div> + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th><span class="strong"><strong>Document Revision #</strong></span></th><th><span class="strong"><strong>Action Taken, Notes</strong></span></th><th><span class="strong"><strong>When?</strong></span></th><th><span class="strong"><strong>By Whom?</strong></span></th></tr></thead><tbody><tr><td>0.1</td><td>Creation</td><td>08/22/2000</td><td><a class="ulink" href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></td></tr><tr><td>0.2</td><td>Initial Revision</td><td>08/30/2000</td><td> Mark Thomas </td></tr><tr><td>0.3</td><td>Additional revisions; tried to clarify membership/compostion</td><td>09/08/2000</td><td> Mark Thomas -</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Groups Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Subsites Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Groups Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Subsites Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/groups-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/groups-requirements.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="groups-design" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="groups-requirements" id="groups-requirements"></a>Groups Requirements</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a>, Mark Thomas</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="groups-requirements" id="groups-requirements"></a>Groups Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a>, Mark +Thomas</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="groups-requirements-intro" id="groups-requirements-intro"></a>Introduction</h3></div></div></div><p>Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups Index: openacs-4/packages/acs-core-docs/www/groups-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/groups-requirements.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/groups-requirements.html 7 Aug 2017 23:47:50 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/groups-requirements.html 8 Nov 2017 09:42:10 -0000 1.36 @@ -1,224 +1,445 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Groups Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="permissions-design.html" title="Permissions Design"><link rel="next" href="groups-design.html" title="Groups Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groups-requirements"></a>Groups Requirements</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a>, Mark Thomas</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-intro"></a>Introduction</h3></div></div></div><p>Almost all database-backed websites have users, and need to model the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Groups Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="permissions-design.html" title="Permissions Design"><link rel="next" href="groups-design.html" title="Groups Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="groups-requirements"></a>Groups Requirements</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a>, Mark Thomas</p> + </authorblurb></span> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-intro"></a>Introduction</h3></div></div></div> + + + + <p>Almost all database-backed websites have users, and need to model the grouping of users. The OpenACS 4 Parties and Groups system is intended to provide the flexibility needed to model complex real-world organizational structures, particularly to support powerful subsite services; that is, where one OpenACS installation can support what appears to the user as distinct web services - for different user communities.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-vision"></a>Vision Statement</h3></div></div></div><p>A powerful web service that can meet the needs of large enterprises must + for different user communities.</p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-vision"></a>Vision Statement</h3></div></div></div> + + + + <p>A powerful web service that can meet the needs of large enterprises must be able to model the the real world's very rich organizational structures and many ways of decomposing the same organization. For example, a corporation can be broken into structures (the corporation, its divisions, and their departments) or regions (the Boston office, the LA office); a person who is employed by (is a member of) a specific department is also a member of the division and the corporation, and works at (is a member of, but in a different sense) a particular office. OpenACS's Parties and Groups - system will support such complex relations faithfully.</p><p><span class="strong"><strong>Historical Motivations</strong></span></p><p>The primary limitation of the OpenACS 3.x user group system is that it + system will support such complex relations faithfully.</p> + + <p><span class="strong"><strong>Historical Motivations</strong></span></p> + + <p>The primary limitation of the OpenACS 3.x user group system is that it restricts the application developer to representing a "flat group" that contains only users: The <code class="computeroutput">user_groups</code> table may contain the <code class="computeroutput">group_id</code> of a parent group, but parent-child relationship support is limited because it only allows one kind of relationship between groups to be represented. Moreover, the Oracle database's limited support for tree-like structures makes the queries over these relationships - expensive.</p><p>In addition, the Module Scoping design in OpenACS 3.0 introduced a + expensive.</p> + + <p>In addition, the Module Scoping design in OpenACS 3.0 introduced a <span class="emphasis"><em>party</em></span> abstraction - a thing that is a person or a group of people - though not in the form of an explicit table. Rather, the triple of <code class="computeroutput">scope</code>, <code class="computeroutput">user_id</code>, and <code class="computeroutput">group_id</code> columns was used to identify the party. One disadvantage of this design convention is that it increases a data model's complexity by requiring the programmer - to:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>add these three columns to each "scoped" table</p></li><li class="listitem"><p>define a multi-column check constraint to protect against data corruption + to:</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>add these three columns to each "scoped" table</p></li><li class="listitem"><p>define a multi-column check constraint to protect against data corruption (e.g., a row with a <code class="computeroutput">scope</code> value of "group" but a null <code class="computeroutput">group_id</code>)</p></li><li class="listitem"><p>perform extra checks in <code class="computeroutput">Tcl</code> and <code class="computeroutput">PL/SQL</code> functions and procedures to check both the <code class="computeroutput">user_id</code> and - <code class="computeroutput">group_id</code> values</p></li></ul></div><p>In sum, the goal of the <span class="strong"><strong>Parties and Groups</strong></span> system is to + <code class="computeroutput">group_id</code> values</p></li></ul></div> + + <p>In sum, the goal of the <span class="strong"><strong>Parties and Groups</strong></span> system is to provide OpenACS programmers and site administrators with simple tools that fully describe the complex relationships that exist among groups in the real - world.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-user-scenarios"></a>User Scenarios</h3></div></div></div><p>Pat Developer has a client project and wants to model the company, its + world.</p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-user-scenarios"></a>User Scenarios</h3></div></div></div> + + + + <p>Pat Developer has a client project and wants to model the company, its offices, its divisions, and its departments as groups and the employees as - users.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-system-overview"></a>System Overview</h3></div></div></div><p>We start with <span class="strong"><strong>Groups</strong></span>, which contain members; the + users.</p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-system-overview"></a>System Overview</h3></div></div></div> + + + + <p>We start with <span class="strong"><strong>Groups</strong></span>, which contain members; the <span class="strong"><strong>member can be either a person or another group</strong></span> (i.e. a - member is a party).</p><p>In addition to membership, the party and groups system defines a + member is a party).</p> + + <p>In addition to membership, the party and groups system defines a <span class="strong"><strong>composition</strong></span> relationship that may exist between groups: A group can be a <span class="strong"><strong>component</strong></span> of another group. The child group is called a <span class="emphasis"><em>component group</em></span>; the parent group is called a - <span class="emphasis"><em>composite group</em></span>.</p><p>A group <span class="strong"><strong>G<sub>c</sub></strong></span> can be a member and/or a component + <span class="emphasis"><em>composite group</em></span>.</p> + + <p>A group <span class="strong"><strong>G<sub>c</sub></strong></span> can be a member and/or a component of another group <span class="strong"><strong>G<sub>p</sub></strong></span>; the difference is in the way the members of <span class="strong"><strong>G<sub>c</sub></strong></span> are related to - <span class="strong"><strong>G<sub>p</sub></strong></span>:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If a party <span class="strong"><strong>P</strong></span> is a member (or a component) of + <span class="strong"><strong>G<sub>p</sub></strong></span>:</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>If a party <span class="strong"><strong>P</strong></span> is a member (or a component) of <span class="strong"><strong>G<sub>c</sub></strong></span> and if <span class="strong"><strong>G<sub>c</sub></strong></span> is a component of <span class="strong"><strong>G<sub>p</sub></strong></span>, then <span class="strong"><strong>P</strong></span> is also a member (or a component) of <span class="strong"><strong>G<sub>p</sub></strong></span></p></li><li class="listitem"><p>If a party <span class="strong"><strong>P</strong></span> is a member (or a component) of <span class="strong"><strong>G<sub>c</sub></strong></span> and if <span class="strong"><strong>G<sub>c</sub></strong></span> is a member of <span class="strong"><strong>G<sub>p</sub></strong></span>, then <span class="strong"><strong>no relationship</strong></span> between <span class="strong"><strong>P</strong></span> and <span class="strong"><strong>G<sub>p</sub></strong></span> exists as a result of the relationship between - <span class="strong"><strong>G<sub>p</sub></strong></span> and <span class="strong"><strong>G<sub>p</sub></strong></span>.</p></li></ul></div><p>Consider an example to make this less abstract: Pretend that the Sierra + <span class="strong"><strong>G<sub>p</sub></strong></span> and <span class="strong"><strong>G<sub>p</sub></strong></span>.</p></li></ul></div> + + <p>Consider an example to make this less abstract: Pretend that the Sierra Club is a <span class="emphasis"><em>member</em></span> of Greenpeace. The Sierra Club has chapters; each chapter is a <span class="emphasis"><em>component</em></span> of the Sierra Club. If Eddie Environmentalist is a member of the Massachusetts Chapter of the Sierra Club, Eddie is automatically a member of the Sierra Club, but being a Sierra Club member - does not make Eddie a member of Greenpeace.</p><p>In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be + does not make Eddie a member of Greenpeace.</p> + + <p>In the OpenACS, Greenpeace, Sierra Club, and the Sierra Club chapters would be modeled as groups, and Eddie would be a user. There would be a composition relationship between each Sierra Club chapter and the Sierra Club. Membership relationships would exist between Eddie and the Massachusetts Chapter, between Eddie and the Sierra Club (due to Eddie's membership in the - Massachusetts chapter), and between the Sierra Club and Greenpeace.</p><p>Membership requirements can vary from group to group. The parties and + Massachusetts chapter), and between the Sierra Club and Greenpeace.</p> + + <p>Membership requirements can vary from group to group. The parties and groups system must provide a base type that specifies the bare minimum - necessary to join a group.</p><p>The parties and groups system must support constraints between a composite + necessary to join a group.</p> + + <p>The parties and groups system must support constraints between a composite group <span class="strong"><strong>G<sub>P</sub></strong></span> and any of its component groups, <span class="strong"><strong>G<sub>C</sub></strong></span>. For example, the system should be able to enforce a rule like: Do not allow a party <span class="strong"><strong>P</strong></span> to become a member of <span class="strong"><strong>G<sub>C</sub></strong></span> unless <span class="strong"><strong>P</strong></span> is already - a member of <span class="strong"><strong>G<sub>P</sub></strong></span>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-links"></a>Related Links</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="groups-design.html" title="Groups Design">OpenACS 4 Groups Design</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-data-model"></a>Requirements: Data Model</h3></div></div></div><p>The data model for the parties and groups system must provide support for - the following types of entities:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>10.0 Parties</strong></span> + a member of <span class="strong"><strong>G<sub>P</sub></strong></span>.</p> - </span></dt><dd><p>A <span class="strong"><strong>party</strong></span> is an entity used to represent either a - <span class="emphasis"><em>group</em></span> or a <span class="emphasis"><em>person</em></span>.</p><p>The data model should enforce these constraints:</p><p><span class="strong"><strong>10.10</strong></span> A party has an email address, which can be - empty.</p><p><span class="strong"><strong>10.20</strong></span> A party may have multiple email addresses - associated with it.</p><p><span class="strong"><strong>10.30</strong></span> The email address of a party must be unique within - an OpenACS system.</p></dd><dt><span class="term"><span class="strong"><strong>20.0 Groups</strong></span> + </div> - </span></dt><dd><p>A <span class="strong"><strong>group</strong></span> is a collection of zero or more parties.</p><p><span class="strong"><strong>20.10</strong></span> The data model should support the subclassing of - groups via OpenACS Objects.</p></dd><dt><span class="term"><span class="strong"><strong>30.0 Persons</strong></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-links"></a>Related Links</h3></div></div></div> + - </span></dt><dd><p>A <span class="strong"><strong>person</strong></span> represents an actual human being, past or - present.</p><p><a name="groups-requirements-30-10"></a><span class="strong"><strong>30.10.</strong></span> A person must have - an associated name.</p></dd><dt><span class="term"><span class="strong"><strong>40.0 Users</strong></span> - </span></dt><dd><p>A <span class="strong"><strong>user</strong></span> is a person who has registered with an OpenACS site. A - user may have additional attributes, such as a screen name.</p><p>The data model should enforce these constraints:</p><p><span class="strong"><strong>40.10</strong></span> A user must have a non-empty email address.</p><p><span class="strong"><strong>40.20</strong></span> Two different users may not have the same email + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="groups-design.html" title="Groups Design">OpenACS 4 Groups Design</a></p></li></ul></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-data-model"></a>Requirements: Data Model</h3></div></div></div> + + + + <p>The data model for the parties and groups system must provide support for + the following types of entities:</p> + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>10.0 Parties</strong></span> + + </span></dt><dd> + <p>A <span class="strong"><strong>party</strong></span> is an entity used to represent either a + <span class="emphasis"><em>group</em></span> or a <span class="emphasis"><em>person</em></span>.</p> + + <p>The data model should enforce these constraints:</p> + + <p><span class="strong"><strong>10.10</strong></span> A party has an email address, which can be + empty.</p> + + <p><span class="strong"><strong>10.20</strong></span> A party may have multiple email addresses + associated with it.</p> + + <p><span class="strong"><strong>10.30</strong></span> The email address of a party must be unique within + an OpenACS system.</p> + </dd><dt><span class="term"><span class="strong"><strong>20.0 Groups</strong></span> + + </span></dt><dd> + <p>A <span class="strong"><strong>group</strong></span> is a collection of zero or more parties.</p> + + <p><span class="strong"><strong>20.10</strong></span> The data model should support the subclassing of + groups via OpenACS Objects.</p> + </dd><dt><span class="term"><span class="strong"><strong>30.0 Persons</strong></span> + + </span></dt><dd> + <p>A <span class="strong"><strong>person</strong></span> represents an actual human being, past or + present.</p> + + <p><a name="groups-requirements-30-10"></a><span class="strong"><strong>30.10.</strong></span> A person must have + an associated name.</p> + </dd><dt><span class="term"><span class="strong"><strong>40.0 Users</strong></span> + + </span></dt><dd> + <p>A <span class="strong"><strong>user</strong></span> is a person who has registered with an OpenACS site. A + user may have additional attributes, such as a screen name.</p> + + <p>The data model should enforce these constraints:</p> + + <p><span class="strong"><strong>40.10</strong></span> A user must have a non-empty email address.</p> + + <p><span class="strong"><strong>40.20</strong></span> Two different users may not have the same email address on a single OpenACS installation; i.e., an email address identifies a - single user on the system.</p><p><span class="strong"><strong>40.30</strong></span> A user may have multiple email addresses; for - example, two or more email addresses may identify a single user.</p><p><span class="strong"><strong>40.40</strong></span> A user must have password field which can be - empty.</p></dd></dl></div><p>The data model for the parties and groups system must provide support for - the following types of relationships between entities:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>50.0 Membership</strong></span> + single user on the system.</p> + <p><span class="strong"><strong>40.30</strong></span> A user may have multiple email addresses; for + example, two or more email addresses may identify a single user.</p> + + <p><span class="strong"><strong>40.40</strong></span> A user must have password field which can be + empty.</p> + </dd></dl></div> + + <p>The data model for the parties and groups system must provide support for + the following types of relationships between entities:</p> + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>50.0 Membership</strong></span> + </span></dt><dd><p> A party <span class="strong"><strong>P</strong></span> is considered a <span class="strong"><strong>member</strong></span> of a - group <span class="strong"><strong>G</strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>when a direct membership relationship exists between <span class="strong"><strong>P</strong></span> + group <span class="strong"><strong>G</strong></span></p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>when a direct membership relationship exists between <span class="strong"><strong>P</strong></span> and <span class="strong"><strong>G</strong></span></p></li><li class="listitem"><p>or when there exists a direct membership relationship between <span class="strong"><strong>P</strong></span> and some group <span class="strong"><strong>G<sub>C</sub></strong></span> and - <span class="strong"><strong>G<sub>C</sub></strong></span> has a composition relationship (c.f., <a class="link" href="groups-requirements.html#groups-requirements-60-0">60.0</a>) with <span class="strong"><strong>G</strong></span>.</p></li></ul></div><p><span class="strong"><strong>50.10</strong></span> A party may be a member of multiple groups.</p><p><span class="strong"><strong>50.20</strong></span> A party may be a member of the same group multiple + <span class="strong"><strong>G<sub>C</sub></strong></span> has a composition relationship (c.f., <a class="link" href="groups-requirements.html#groups-requirements-60-0">60.0</a>) with <span class="strong"><strong>G</strong></span>.</p></li></ul></div> + + + <p><span class="strong"><strong>50.10</strong></span> A party may be a member of multiple groups.</p> + + <p><span class="strong"><strong>50.20</strong></span> A party may be a member of the same group multiple times only when all the memberships have different types; for example, Jane may be a member of The Company by being both an Employee and an - Executive.</p><p><span class="strong"><strong>50.30</strong></span> A party as a member of itself is not supported.</p><p><span class="strong"><strong>50.40</strong></span> The data model must support membership - constraints.</p><p><span class="strong"><strong>50.50</strong></span>The data model should support the subclassing of - membership via OpenACS Relationships.</p></dd></dl></div><div class="variablelist"><dl class="variablelist"><dt><span class="term"> + Executive.</p> + + <p><span class="strong"><strong>50.30</strong></span> A party as a member of itself is not supported.</p> + + <p><span class="strong"><strong>50.40</strong></span> The data model must support membership + constraints.</p> + + <p><span class="strong"><strong>50.50</strong></span>The data model should support the subclassing of + membership via OpenACS Relationships.</p> + </dd></dl></div> + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"> <a name="groups-requirements-60-0"></a> <span class="strong"><strong>60.0 Composition</strong></span> - </span></dt><dd><p>A group <span class="strong"><strong>G<sub>C</sub></strong></span> is considered a + </span></dt><dd> + <p>A group <span class="strong"><strong>G<sub>C</sub></strong></span> is considered a <span class="strong"><strong>component</strong></span> of a second group - <span class="strong"><strong>G<sub>P</sub></strong></span></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>when a direct composition relationship exists between + <span class="strong"><strong>G<sub>P</sub></strong></span></p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>when a direct composition relationship exists between <span class="strong"><strong>G<sub>C</sub></strong></span> and <span class="strong"><strong>G<sub>P</sub></strong></span></p></li><li class="listitem"><p>or when there exists a direct composition relationship between <span class="strong"><strong>G<sub>C</sub></strong></span> and some group <span class="strong"><strong>G<sub>i</sub></strong></span> and <span class="strong"><strong>G<sub>i</sub></strong></span> has a composition relationship with - <span class="strong"><strong>G<sub>P</sub></strong></span>.</p></li></ul></div><p><span class="strong"><strong>60.10</strong></span>A group may be a component of multiple groups.</p><p><span class="strong"><strong>60.20</strong></span>A group as a component of itself is not - supported.</p><p><span class="strong"><strong>60.30</strong></span>The data model must support component - constraints.</p><p><span class="strong"><strong>60.40</strong></span>The data model should support the subclassing of - composition via OpenACS Relationships.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-api"></a>Requirements: API</h3></div></div></div><p>The API should let programmers accomplish the following tasks:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>70.10 Create a group</strong></span> + <span class="strong"><strong>G<sub>P</sub></strong></span>.</p></li></ul></div> - </span></dt><dd><p>The parties and groups system provides a well defined API call that + + + <p><span class="strong"><strong>60.10</strong></span>A group may be a component of multiple groups.</p> + + <p><span class="strong"><strong>60.20</strong></span>A group as a component of itself is not + supported.</p> + + <p><span class="strong"><strong>60.30</strong></span>The data model must support component + constraints.</p> + + <p><span class="strong"><strong>60.40</strong></span>The data model should support the subclassing of + composition via OpenACS Relationships.</p> + </dd></dl></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-api"></a>Requirements: API</h3></div></div></div> + + + + <p>The API should let programmers accomplish the following tasks:</p> + + <div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>70.10 Create a group</strong></span> + + </span></dt><dd> + <p>The parties and groups system provides a well defined API call that creates a new group by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>70.20 Create a person</strong></span> + in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>70.20 Create a person</strong></span> - </span></dt><dd><p>The parties and groups system provides a well defined API call that + </span></dt><dd> + <p>The parties and groups system provides a well defined API call that creates a new person by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out - in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>70.30 Create a user</strong></span> + in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>70.30 Create a user</strong></span> - </span></dt><dd><p>The parties and groups system provides a well defined API call that + </span></dt><dd> + <p>The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on the parties and groups system data model. This API is subject to the constraints laid out in - the data model.</p></dd><dt><span class="term"><span class="strong"><strong>80.10 Refine a person to a user</strong></span> + the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>80.10 Refine a person to a user</strong></span> - </span></dt><dd><p>The parties and groups system provides a well defined API call that + </span></dt><dd> + <p>The parties and groups system provides a well defined API call that creates a new user by running the appropriate transactions on an existing person entity. This API is subject to the constraints laid out in the data - model.</p></dd><dt><span class="term"><span class="strong"><strong>80.30 Demote a user to a person</strong></span> + model.</p> + </dd><dt><span class="term"><span class="strong"><strong>80.30 Demote a user to a person</strong></span> - </span></dt><dd><p>The parties and groups system provides a well defined API call that + </span></dt><dd> + <p>The parties and groups system provides a well defined API call that demotes an existing user entity to a person entity by running the appropriate transactions on the existing user. This API is subject to the constraints - laid out in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>90.10 Update a party</strong></span> + laid out in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>90.10 Update a party</strong></span> - </span></dt><dd><p>The programmer should be able to modify, add, and delete attributes on any - party. This API is subject to the constraints laid out in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>95.10 Get the attributes of a party</strong></span> + </span></dt><dd> + <p>The programmer should be able to modify, add, and delete attributes on any + party. This API is subject to the constraints laid out in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>95.10 Get the attributes of a party</strong></span> - </span></dt><dd><p>The programmer should be able to view the attributes on any party. This - API is subject to the constraints laid out in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>100.10 Delete a party</strong></span> + </span></dt><dd> + <p>The programmer should be able to view the attributes on any party. This + API is subject to the constraints laid out in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>100.10 Delete a party</strong></span> - </span></dt><dd><p>The system provides an API for deleting a party. This API is subject to - the constraints laid out in the data model.</p><p><span class="strong"><strong>100.30</strong></span> The system may provide a single API call to remove - the party from all groups and then delete the party.</p><p><span class="strong"><strong>100.40</strong></span> In the case of a group, the system may provide a + </span></dt><dd> + <p>The system provides an API for deleting a party. This API is subject to + the constraints laid out in the data model.</p> + + <p><span class="strong"><strong>100.30</strong></span> The system may provide a single API call to remove + the party from all groups and then delete the party.</p> + + <p><span class="strong"><strong>100.40</strong></span> In the case of a group, the system may provide a single API call to remove all parties from a group and then delete the - group.</p></dd><dt><span class="term"><span class="strong"><strong>110.0 Add a party as a member of a group</strong></span> + group.</p> + </dd><dt><span class="term"><span class="strong"><strong>110.0 Add a party as a member of a group</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for adding a party as a + </span></dt><dd> + <p>The parties and groups system provides an API for adding a party as a member of a group. This API is subject to the constraints laid out in the - data model.</p></dd><dt><span class="term"><span class="strong"><strong>115.0 Add a group as a component of a second group</strong></span> + data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>115.0 Add a group as a component of a second group</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for adding a group as a + </span></dt><dd> + <p>The parties and groups system provides an API for adding a group as a component of a second group. This API is subject to the constraints laid out - in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>120.0 Remove a party as a member of a group</strong></span> + in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>120.0 Remove a party as a member of a group</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for deleting a party's + </span></dt><dd> + <p>The parties and groups system provides an API for deleting a party's membership in a group. This API is subject to the constraints laid out in the - data model.</p></dd><dt><span class="term"><span class="strong"><strong>125.0 Remove a group as a component of a second + data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>125.0 Remove a group as a component of a second group</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for deleting a group's + </span></dt><dd> + <p>The parties and groups system provides an API for deleting a group's composition in a second group. This API is subject to the constraints laid - out in the data model.</p></dd><dt><span class="term"><span class="strong"><strong>130.0 Membership check</strong></span> + out in the data model.</p> + </dd><dt><span class="term"><span class="strong"><strong>130.0 Membership check</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: "Is party <span class="strong"><strong>P</strong></span> a member of group - <span class="strong"><strong>G</strong></span>?"</p></dd><dt><span class="term"><span class="strong"><strong>135.0 Composition check</strong></span> + <span class="strong"><strong>G</strong></span>?"</p> + </dd><dt><span class="term"><span class="strong"><strong>135.0 Composition check</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: "Is group <span class="strong"><strong>G<sub>C</sub></strong></span> a component of group - <span class="strong"><strong>G<sub>P</sub></strong></span>?"</p></dd><dt><span class="term"><span class="strong"><strong>140.0 Get members query</strong></span> + <span class="strong"><strong>G<sub>P</sub></strong></span>?"</p> + </dd><dt><span class="term"><span class="strong"><strong>140.0 Get members query</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: - "Which parties are members of group <span class="strong"><strong>G</strong></span>?"</p></dd><dt><span class="term"><span class="strong"><strong>145.0 Get components query</strong></span> + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: + "Which parties are members of group <span class="strong"><strong>G</strong></span>?"</p> + </dd><dt><span class="term"><span class="strong"><strong>145.0 Get components query</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: - "Which groups are components of group <span class="strong"><strong>G</strong></span>?"</p></dd><dt><span class="term"><span class="strong"><strong>150.0 Member-of-groups query</strong></span> + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: + "Which groups are components of group <span class="strong"><strong>G</strong></span>?"</p> + </dd><dt><span class="term"><span class="strong"><strong>150.0 Member-of-groups query</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: - "Of which groups is party <span class="strong"><strong>P</strong></span> a member?"</p></dd><dt><span class="term"><span class="strong"><strong>155.0 Component-of-groups query</strong></span> + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: + "Of which groups is party <span class="strong"><strong>P</strong></span> a member?"</p> + </dd><dt><span class="term"><span class="strong"><strong>155.0 Component-of-groups query</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: - "Of which groups is group <span class="strong"><strong>G</strong></span> a component?"</p></dd><dt><span class="term"><span class="strong"><strong>160.0 Allowed membership check</strong></span> + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: + "Of which groups is group <span class="strong"><strong>G</strong></span> a component?"</p> + </dd><dt><span class="term"><span class="strong"><strong>160.0 Allowed membership check</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: "Is party <span class="strong"><strong>P</strong></span> allowed to become a member of group - <span class="strong"><strong>G</strong></span>?"</p></dd><dt><span class="term"><span class="strong"><strong>165.0 Allowed composition check</strong></span> + <span class="strong"><strong>G</strong></span>?"</p> + </dd><dt><span class="term"><span class="strong"><strong>165.0 Allowed composition check</strong></span> - </span></dt><dd><p>The parties and groups system provides an API for answering the question: + </span></dt><dd> + <p>The parties and groups system provides an API for answering the question: "Is group <span class="strong"><strong>G<sub>C</sub></strong></span> allowed to become a component - of group <span class="strong"><strong>G<sub>P</sub></strong></span>?"</p></dd><dt><span class="term"><span class="strong"><strong>170.0 Efficiency</strong></span> + of group <span class="strong"><strong>G<sub>P</sub></strong></span>?"</p> + </dd><dt><span class="term"><span class="strong"><strong>170.0 Efficiency</strong></span> - </span></dt><dd><p>Since many pages at a site may check membership in a group before serving + </span></dt><dd> + <p>Since many pages at a site may check membership in a group before serving a page (e.g., as part of a general permissions check), the data model must support the efficient storage and retrieval of party attributes and - membership.</p></dd><dt><span class="term"><span class="strong"><strong>180.0 Ease of Use</strong></span> + membership.</p> + </dd><dt><span class="term"><span class="strong"><strong>180.0 Ease of Use</strong></span> - </span></dt><dd><p>Since many SQL queries will check membership in a group as part of the + </span></dt><dd> + <p>Since many SQL queries will check membership in a group as part of the <code class="computeroutput">where</code> clause, whatever mechanism is used to check membership in SQL - should be fairly small and simple.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-ui"></a>Requirements: User Interface</h3></div></div></div><p>The user interface is a set of HTML pages that are used to drive the - underlying API. The user interface may provide the following functions:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>200.0</strong></span> Create a party</p></li><li class="listitem"><p><span class="strong"><strong>210.0</strong></span> View the attributes of a party</p></li><li class="listitem"><p><span class="strong"><strong>220.0</strong></span> Update the attributes of a party</p></li><li class="listitem"><p><span class="strong"><strong>240.0</strong></span> Delete a party</p></li><li class="listitem"><p><span class="strong"><strong>250.0</strong></span> Add a party to a group</p></li><li class="listitem"><p><span class="strong"><strong>260.0</strong></span> Remove a party from a group</p></li><li class="listitem"><p><span class="strong"><strong>270.0</strong></span> Perform the membership and composition checks - outlined in 130.x to 165.x</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/16/2000</td><td>Rafael Schloming</td></tr><tr><td>0.2</td><td>Initial revision</td><td>08/19/2000</td><td>Mark Thomas</td></tr><tr><td>0.3</td><td>Edited and reviewed, conforms to requirements template</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Further revised, added UI requirements</td><td>08/24/2000</td><td>Mark Thomas</td></tr><tr><td>0.5</td><td>Final edits, pending freeze</td><td>08/24/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>More revisions, added composition requirements</td><td>08/30/2000</td><td>Mark Thomas</td></tr><tr><td>0.7</td><td>More revisions, added composition requirements</td><td>09/08/2000</td><td>Mark Thomas</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr><tr><td width="40%" align="left">Permissions Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Groups Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + should be fairly small and simple.</p> + </dd></dl></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-ui"></a>Requirements: User Interface</h3></div></div></div> + + + + <p>The user interface is a set of HTML pages that are used to drive the + underlying API. The user interface may provide the following functions:</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>200.0</strong></span> Create a party</p></li><li class="listitem"><p><span class="strong"><strong>210.0</strong></span> View the attributes of a party</p></li><li class="listitem"><p><span class="strong"><strong>220.0</strong></span> Update the attributes of a party</p></li><li class="listitem"><p><span class="strong"><strong>240.0</strong></span> Delete a party</p></li><li class="listitem"><p><span class="strong"><strong>250.0</strong></span> Add a party to a group</p></li><li class="listitem"><p><span class="strong"><strong>260.0</strong></span> Remove a party from a group</p></li><li class="listitem"><p><span class="strong"><strong>270.0</strong></span> Perform the membership and composition checks + outlined in 130.x to 165.x</p></li></ul></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="groups-requirements-rev-history"></a>Revision History</h3></div></div></div> + + + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/16/2000</td><td>Rafael Schloming</td></tr><tr><td>0.2</td><td>Initial revision</td><td>08/19/2000</td><td>Mark Thomas</td></tr><tr><td>0.3</td><td>Edited and reviewed, conforms to requirements template</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Further revised, added UI requirements</td><td>08/24/2000</td><td>Mark Thomas</td></tr><tr><td>0.5</td><td>Final edits, pending freeze</td><td>08/24/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>More revisions, added composition requirements</td><td>08/30/2000</td><td>Mark Thomas</td></tr><tr><td>0.7</td><td>More revisions, added composition requirements</td><td>09/08/2000</td><td>Mark Thomas</td></tr></tbody></table></div> + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-design.html">Next</a></td></tr><tr><td width="40%" align="left">Permissions Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Groups Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/high-avail.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/high-avail.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/high-avail.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/high-avail.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -13,7 +13,7 @@ Configurations</h2></div></div></div><p>See also <a class="xref" href="remote-postgres" title="Running a PostgreSQL database on another server">the section called “Running a PostgreSQL database on another server”</a>.</p><div class="figure"> -<a name="idp140592101868456" id="idp140592101868456"></a><p class="title"><strong>Figure 6.1. Multiple-server +<a name="idp140623175654472" id="idp140623175654472"></a><p class="title"><strong>Figure 6.1. Multiple-server configuration</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/hpha.png" align="middle" alt="Multiple-server configuration"></div></div> </div><br class="figure-break"> </div> 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 -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/high-avail.html 7 Aug 2017 23:47:50 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/high-avail.html 8 Nov 2017 09:42:10 -0000 1.26 @@ -1,2 +1,10 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>High Availability/High Performance Configurations</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-next-add-server.html" title="Running multiple services on one machine"><link rel="next" href="maintenance-deploy.html" title="Staged Deployment for Production Networks"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-next-add-server.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="maintenance-deploy.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="high-avail"></a>High Availability/High Performance Configurations</h2></div></div></div><p>See also <a class="xref" href="remote-postgres.html" title="Running a PostgreSQL database on another server">the section called “Running a PostgreSQL database on another server”</a>.</p><div class="figure"><a name="idp140592101868456"></a><p class="title"><b>Figure 6.1. Multiple-server configuration</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/hpha.png" align="middle" alt="Multiple-server configuration"></div></div></div><br class="figure-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-next-add-server.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance-deploy.html">Next</a></td></tr><tr><td width="40%" align="left">Running multiple services on one machine </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Staged Deployment for Production Networks</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>High Availability/High Performance Configurations</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-next-add-server.html" title="Running multiple services on one machine"><link rel="next" href="maintenance-deploy.html" title="Staged Deployment for Production Networks"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-next-add-server.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="maintenance-deploy.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="high-avail"></a>High Availability/High Performance Configurations</h2></div></div></div> + + <p>See also <a class="xref" href="remote-postgres.html" title="Running a PostgreSQL database on another server">the section called “Running a PostgreSQL database on another server”</a>.</p> + <div class="figure"><a name="idp140623175654472"></a><p class="title"><b>Figure 6.1. Multiple-server configuration</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/hpha.png" align="middle" alt="Multiple-server configuration"></div> + </div></div><br class="figure-break"> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-next-add-server.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance-deploy.html">Next</a></td></tr><tr><td width="40%" align="left">Running multiple services on one machine </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Staged Deployment for Production Networks</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/how-do-I.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/how-do-I.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/how-do-I.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -12,20 +12,20 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="how-do-I" id="how-do-I"></a>How Do I?</h2></div></div></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104646280" id="idp140592104646280"></a>How do I edit the front page of a new site +<a name="idp140623157103896" id="idp140623157103896"></a>How do I edit the front page of a new site through a web interface?</h3></div></div></div><p>The easiest way is to install the Edit-This-Page package.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Log in to the web site as an administrator.</p></li><li class="listitem"><p>Click on Admin > Install Software > Install from OpenACS Repository / Install new application</p></li><li class="listitem"><p>Choose Edit This Page and install</p></li><li class="listitem"><p>Follow the instructions within <a class="ulink" href="/doc/edit-this-page/install" target="_top">Edit This Page</a> (the link will only work after Edit This Page is installed).</p></li> </ol></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104651656" id="idp140592104651656"></a>How do I let anybody who registers post to +<a name="idp140623160151304" id="idp140623160151304"></a>How do I let anybody who registers post to a weblog?</h3></div></div></div><p>Go to <code class="computeroutput"><a class="ulink" href="/admin/permissions" target="_top">/admin/permissions</a></code> and grant Create to Registered Users</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104653576" id="idp140592104653576"></a>How do I replace the front page of a new +<a name="idp140623179076680" id="idp140623179076680"></a>How do I replace the front page of a new site with the front page of an application on that site</h3></div></div></div><p>Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>On the front page, click the <code class="computeroutput"><a class="ulink" href="/admin" target="_top">Admin</a></code> button.</p></li><li class="listitem"><p>On the administration page, click <code class="computeroutput">Parameters</code> link.</p></li><li class="listitem"><p>Change the parameter <code class="computeroutput">IndexRedirectUrl</code> to be the URI of the @@ -35,22 +35,22 @@ </ol></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104660232" id="idp140592104660232"></a>How do I put custom functionality on front +<a name="idp140623178420040" id="idp140623178420040"></a>How do I put custom functionality on front page of a new site?</h3></div></div></div><p>Every page within an OpenACS site is part of a <span class="strong"><strong>subsite</strong></span><a class="ulink" href="/doc/acs-subsite" target="_top">More information)</a>. The home page of the entire site is the front page is a special, default -instance of a subsite, served from <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www</code>. If an -index page is not found there, the default index page for all +instance of a subsite, served from <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www</code>. +If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:</p><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"><pre class="screen"><strong class="userinput"><code>cp <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-subsite/www/index*</code><code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www</code> +<li class="listitem"><pre class="screen"><strong class="userinput"><code>cp <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-subsite/www/index*</code><code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www</code> </code></strong></pre></li><li class="listitem"><p>Edit the new <code class="computeroutput">index.adp</code> to change the text; you shouldn't need to edit <code class="computeroutput">index.tcl</code> unless you are adding new functionality.</p></li> </ol></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592106970264" id="idp140592106970264"></a>How do I change the site-wide style?</h3></div></div></div><p>Almost all pages on an OpenACS site use <a class="ulink" href="/doc/acs-templating" target="_top">ACS Templating</a>, and so +<a name="idp140623178430728" id="idp140623178430728"></a>How do I change the site-wide style?</h3></div></div></div><p>Almost all pages on an OpenACS site use <a class="ulink" href="/doc/acs-templating" target="_top">ACS Templating</a>, and so their appearance is driven by a layer of different files. Let's examine how this works:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> @@ -59,31 +59,31 @@ <master> </pre><p>If it appears exactly like this, without any arguments, the template processor uses <code class="computeroutput">default-master</code> for that subsite. For pages -in <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www</code>, this -is <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/default-master.adp</code> +in <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www</code>, +this is <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/default-master.adp</code> and the associated .tcl file.</p> </li><li class="listitem"><p>The <code class="computeroutput">default-master</code> is itself a normal ADP page. It draws the subsite navigation elements and invokes <code class="computeroutput">site-master</code> -(<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/site-master.adp</code> +(<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/site-master.adp</code> and .tcl)</p></li><li class="listitem"><p>The <code class="computeroutput">site-master</code> draws -site-wide navigation elements and invokes <code class="computeroutput">blank-master</code> (<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/blank-master.adp</code> +site-wide navigation elements and invokes <code class="computeroutput">blank-master</code> (<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/blank-master.adp</code> and .tcl).</p></li><li class="listitem"><p> <code class="computeroutput">Blank-master</code> does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.</p></li> </ul></div><div class="figure"> -<a name="idp140592106982936" id="idp140592106982936"></a><p class="title"><strong>Figure 4.1. Site +<a name="idp140623178931720" id="idp140623178931720"></a><p class="title"><strong>Figure 4.1. Site Templates</strong></p><div class="figure-contents"><div class="mediaobject"><img src="images/site-templates.png" alt="Site Templates"></div></div> </div><br class="figure-break"> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592106985240" id="idp140592106985240"></a>How do I diagnose a permissions +<a name="idp140623178934424" id="idp140623178934424"></a>How do I diagnose a permissions problem?</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> <p> -<strong>Steps to Reproduce. </strong>The events +<strong>Steps to Reproduce. </strong> The events package does not allow users to register for new events.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with @@ -98,7 +98,7 @@ shown.</p> </li><li class="listitem"> <p> -<strong>Finding the problem. </strong>We start with +<strong>Finding the problem. </strong> We start with the page that has the error. In the URL it's <code class="computeroutput">http://myserver.net/events/event-info.tcl</code>, so open the file <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl</code>. It contains this line:</p><pre class="programlisting"> @@ -116,20 +116,20 @@ event.</p> </li><li class="listitem"> <p> -<strong>Setting Permissions. </strong>A permission +<strong>Setting Permissions. </strong> A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>To grant permissions on a package, start at the <a class="ulink" href="/admin/site-map" target="_top">site map</a>. Find the event package and click "Set permissions".</p></li><li class="listitem"><p>Click "Grant Permission"</p></li><li class="listitem"> <p>Grant the write permission to Registered Users.</p><div class="figure"> -<a name="idp140592107005048" id="idp140592107005048"></a><p class="title"><strong>Figure 4.2. Granting +<a name="idp140623157109688" id="idp140623157109688"></a><p class="title"><strong>Figure 4.2. Granting Permissions</strong></p><div class="figure-contents"><div class="mediaobject"><img src="images/grant-perm-463.png" alt="Granting Permissions"></div></div> </div><br class="figure-break"> </li> </ol></div><p>OpenACS 5.0 offers a prettier version at <a class="ulink" href="/admin/applications" target="_top">/admin/applications</a>.</p><div class="figure"> -<a name="idp140592107008760" id="idp140592107008760"></a><p class="title"><strong>Figure 4.3. Granting Permissions in +<a name="idp140623157113640" id="idp140623157113640"></a><p class="title"><strong>Figure 4.3. Granting Permissions in 5.0</strong></p><div class="figure-contents"><div class="mediaobject"><img src="images/grant-perm-50.png" alt="Granting Permissions in 5.0"></div></div> </div><br class="figure-break"> </li> Index: openacs-4/packages/acs-core-docs/www/how-do-I.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/how-do-I.html,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/how-do-I.html 7 Aug 2017 23:47:50 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/how-do-I.html 8 Nov 2017 09:42:10 -0000 1.29 @@ -1,7 +1,116 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How Do I?</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-configuring-permissions.html" title="Setting Permissions on an OpenACS package"><link rel="next" href="upgrade.html" title="Chapter 5. Upgrading"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-configuring-permissions.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-do-I"></a>How Do I?</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104646280"></a>How do I edit the front page of a new site through a web interface?</h3></div></div></div><p>The easiest way is to install the Edit-This-Page package.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Log in to the web site as an administrator.</p></li><li class="listitem"><p>Click on Admin > Install Software > Install from OpenACS Repository / Install new application</p></li><li class="listitem"><p>Choose Edit This Page and install</p></li><li class="listitem"><p>Follow the instructions within <a class="ulink" href="/doc/edit-this-page/install" target="_top">Edit This Page</a> (the link will only work after Edit This Page is installed).</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104651656"></a>How do I let anybody who registers post to a weblog?</h3></div></div></div><p>Go to <code class="computeroutput"><a class="ulink" href="/admin/permissions" target="_top">/admin/permissions</a></code> and grant Create to Registered Users</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104653576"></a>How do I replace the front page of a new site with the front page of an application on that site</h3></div></div></div><p>Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>On the front page, click the <code class="computeroutput"><a class="ulink" href="/admin" target="_top">Admin</a></code> button.</p></li><li class="listitem"><p>On the administration page, click <code class="computeroutput">Parameters</code> link.</p></li><li class="listitem"><p>Change the parameter <code class="computeroutput">IndexRedirectUrl</code> to be the URI of the desired application. For a default weblogger installation, this would be <code class="computeroutput"><strong class="userinput"><code>weblogger/</code></strong></code>. Note the trailing slash.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104660232"></a>How do I put custom functionality on front page of a new site?</h3></div></div></div><p>Every page within an OpenACS site is part of a <span class="strong"><strong>subsite</strong></span> <a class="ulink" href="/doc/acs-subsite" target="_top">More information)</a>. The home page of the entire site is the front page is a special, default instance of a subsite, served from <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www</code>. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><pre class="screen"><strong class="userinput"><code>cp <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-subsite/www/index*</code> <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www</code></code></strong></pre></li><li class="listitem"><p>Edit the new <code class="computeroutput">index.adp</code> to change the text; you shouldn't need to edit <code class="computeroutput">index.tcl</code> unless you are adding new functionality.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592106970264"></a>How do I change the site-wide style?</h3></div></div></div><p>Almost all pages on an OpenACS site use <a class="ulink" href="/doc/acs-templating" target="_top">ACS Templating</a>, and so their appearance is driven by a layer of different files. Let's examine how this works:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How Do I?</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"><link rel="previous" href="configuring-configuring-permissions.html" title="Setting Permissions on an OpenACS package"><link rel="next" href="upgrade.html" title="Chapter 5. Upgrading"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="configuring-configuring-permissions.html">Prev</a> </td><th width="60%" align="center">Chapter 4. Configuring a new OpenACS Site</th><td width="20%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="how-do-I"></a>How Do I?</h2></div></div></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623157103896"></a>How do I edit the front page of a new site through a web interface?</h3></div></div></div> + + <p>The easiest way is to install the Edit-This-Page package.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Log in to the web site as an administrator.</p> + </li><li class="listitem"> + <p>Click on Admin > Install Software > Install from OpenACS Repository / Install new application</p> + </li><li class="listitem"> + <p>Choose Edit This Page and install</p> + </li><li class="listitem"> + <p>Follow the instructions within <a class="ulink" href="/doc/edit-this-page/install" target="_top">Edit This Page</a> (the link will only work after Edit This Page is installed).</p> + </li></ol></div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623160151304"></a>How do I let anybody who registers post to a weblog?</h3></div></div></div> + + <p>Go to <code class="computeroutput"><a class="ulink" href="/admin/permissions" target="_top">/admin/permissions</a></code> and grant Create to Registered Users</p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623179076680"></a>How do I replace the front page of a new site with the front page of an application on that site</h3></div></div></div> + + <p>Suppose you install a new site and install Weblogger, and you want all visitors to see weblogger automatically.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>On the front page, click the <code class="computeroutput"><a class="ulink" href="/admin" target="_top">Admin</a></code> button.</p> + </li><li class="listitem"> + <p>On the administration page, click <code class="computeroutput">Parameters</code> link.</p> + </li><li class="listitem"> + <p>Change the parameter <code class="computeroutput">IndexRedirectUrl</code> to be the URI of the desired application. For a default weblogger installation, this would be <code class="computeroutput"><strong class="userinput"><code>weblogger/</code></strong></code>. Note the trailing slash.</p> + </li></ol></div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178420040"></a>How do I put custom functionality on front page of a new site?</h3></div></div></div> + + <p>Every page within an OpenACS site is part of a <span class="strong"><strong>subsite</strong></span> <a class="ulink" href="/doc/acs-subsite" target="_top">More information)</a>. The home page of the entire site is the front page is a special, default instance of a subsite, served from <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www</code>. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <pre class="screen"><strong class="userinput"><code>cp <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-subsite/www/index*</code> <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www</code></code></strong></pre> + </li><li class="listitem"> + <p>Edit the new <code class="computeroutput">index.adp</code> to change the text; you shouldn't need to edit <code class="computeroutput">index.tcl</code> unless you are adding new functionality.</p> + </li></ol></div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178430728"></a>How do I change the site-wide style?</h3></div></div></div> + + <p>Almost all pages on an OpenACS site use <a class="ulink" href="/doc/acs-templating" target="_top">ACS Templating</a>, and so their appearance is driven by a layer of different files. Let's examine how this works:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> A templated page uses an ADP/Tcl pair. The first line in the ADP file is usually: - </p><pre class="programlisting"><master></pre><p>If it appears exactly like this, without any arguments, the template processor uses <code class="computeroutput">default-master</code> for that subsite. For pages in <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www</code>, this is <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/default-master.adp</code> and the associated .tcl file. - </p></li><li class="listitem"><p>The <code class="computeroutput">default-master</code> is itself a normal ADP page. It draws the subsite navigation elements and invokes <code class="computeroutput">site-master</code> (<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/site-master.adp</code> and .tcl)</p></li><li class="listitem"><p>The <code class="computeroutput">site-master</code> draws site-wide navigation elements and invokes <code class="computeroutput">blank-master</code> (<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/www/blank-master.adp</code> and .tcl). </p></li><li class="listitem"><p><code class="computeroutput">Blank-master</code> does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.</p></li></ul></div><div class="figure"><a name="idp140592106982936"></a><p class="title"><b>Figure 4.1. Site Templates</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/site-templates.png" alt="Site Templates"></div></div></div><br class="figure-break"></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592106985240"></a>How do I diagnose a permissions problem?</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Steps to Reproduce. </b>The events package does not allow users to register for new events.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.</p></li><li class="listitem"><p>Select an available event</p></li><li class="listitem"><p>A link such as <code class="computeroutput">Registration: Deadline is 03/15/2004 10:00am. + </p> + <pre class="programlisting"><master></pre> + <p>If it appears exactly like this, without any arguments, the template processor uses <code class="computeroutput">default-master</code> for that subsite. For pages in <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www</code>, this is <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/default-master.adp</code> and the associated .tcl file. + </p> + </li><li class="listitem"> + <p>The <code class="computeroutput">default-master</code> is itself a normal ADP page. It draws the subsite navigation elements and invokes <code class="computeroutput">site-master</code> (<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/site-master.adp</code> and .tcl)</p> + </li><li class="listitem"> + <p>The <code class="computeroutput">site-master</code> draws site-wide navigation elements and invokes <code class="computeroutput">blank-master</code> (<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/www/blank-master.adp</code> and .tcl). </p> + </li><li class="listitem"> + <p><code class="computeroutput">Blank-master</code> does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets.</p> + </li></ul></div> + <div class="figure"><a name="idp140623178931720"></a><p class="title"><b>Figure 4.1. Site Templates</b></p><div class="figure-contents"> + + <div class="mediaobject"><img src="images/site-templates.png" alt="Site Templates"></div> + </div></div><br class="figure-break"> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178934424"></a>How do I diagnose a permissions problem?</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Steps to Reproduce. </b> + The events package does not allow users to register for new events. + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Go to the http://yourserver.net/events as a visitor (ie, log out and, if necessary, clear cookies). This in on a 4.6.3 site with events version 0.1d3.</p> + </li><li class="listitem"> + <p>Select an available event</p> + </li><li class="listitem"> + <p>A link such as <code class="computeroutput">Registration: Deadline is 03/15/2004 10:00am. » Login or sign up to register for this event.</code> is visible. Click on "Login or sign up" - </p></li><li class="listitem"><p>Complete a new registration. Afterwards, you should be redirected back to the same page.</p></li></ol></div><p>Actual Results: The page says <code class="computeroutput">"You do not have permission to register for this event."</code></p><p>Expected results: A link or form to sign up for the event is shown.</p></li><li class="listitem"><p><b>Finding the problem. </b>We start with the page that has the error. In the URL it's <code class="computeroutput">http://myserver.net/events/event-info.tcl</code>, so open the file <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl</code>. It contains this line:</p><pre class="programlisting">set can_register_p [events::security::can_register_for_event_p -event_id $event_id]</pre><p>We need to know what that procedure does, so go to <a class="ulink" href="/api-doc" target="_top">/api-doc</a>, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply</p><pre class="programlisting">return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]</pre><p>This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.</p></li><li class="listitem"><p><b>Setting Permissions. </b>A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>To grant permissions on a package, start at the <a class="ulink" href="/admin/site-map" target="_top">site map</a>. Find the event package and click "Set permissions". </p></li><li class="listitem"><p>Click "Grant Permission"</p></li><li class="listitem"><p>Grant the write permission to Registered Users.</p><div class="figure"><a name="idp140592107005048"></a><p class="title"><b>Figure 4.2. Granting Permissions</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/grant-perm-463.png" alt="Granting Permissions"></div></div></div><br class="figure-break"></li></ol></div><p>OpenACS 5.0 offers a prettier version at <a class="ulink" href="/admin/applications" target="_top">/admin/applications</a>.</p><div class="figure"><a name="idp140592107008760"></a><p class="title"><b>Figure 4.3. Granting Permissions in 5.0</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/grant-perm-50.png" alt="Granting Permissions in 5.0"></div></div></div><br class="figure-break"></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-configuring-permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr><tr><td width="40%" align="left">Setting Permissions on an OpenACS package </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Chapter 5. Upgrading</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li><li class="listitem"> + <p>Complete a new registration. Afterwards, you should be redirected back to the same page.</p> + </li></ol></div> + <p>Actual Results: The page says <code class="computeroutput">"You do not have permission to register for this event."</code></p> + <p>Expected results: A link or form to sign up for the event is shown.</p> + </li><li class="listitem"> + <p> + <b>Finding the problem. </b> + We start with the page that has the error. In the URL it's <code class="computeroutput">http://myserver.net/events/event-info.tcl</code>, so open the file <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl</code>. It contains this line: + </p> + <pre class="programlisting">set can_register_p [events::security::can_register_for_event_p -event_id $event_id]</pre> + <p>We need to know what that procedure does, so go to <a class="ulink" href="/api-doc" target="_top">/api-doc</a>, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply</p> + <pre class="programlisting">return [permission::permission_p -party_id $user_id -object_id $event_id -privilege write]</pre> + <p>This means that a given user must have the write privilige on the event in order to register. Let's assume that the priviliges inherit, so that if a user has the write privilige on the whole package, they will have the write privilege on the event.</p> + </li><li class="listitem"> + <p> + <b>Setting Permissions. </b> + A permission has three parts: the privilige, the object of the privilige, and the subject being granted the privilige. In this case the privilige is "write," the object is the Events package, and the subject is all Registered Users. + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>To grant permissions on a package, start at the <a class="ulink" href="/admin/site-map" target="_top">site map</a>. Find the event package and click "Set permissions". </p> + </li><li class="listitem"> + <p>Click "Grant Permission"</p> + </li><li class="listitem"> + <p>Grant the write permission to Registered Users.</p> + <div class="figure"><a name="idp140623157109688"></a><p class="title"><b>Figure 4.2. Granting Permissions</b></p><div class="figure-contents"> + + <div class="mediaobject"><img src="images/grant-perm-463.png" alt="Granting Permissions"></div> + </div></div><br class="figure-break"> + + </li></ol></div> + <p>OpenACS 5.0 offers a prettier version at <a class="ulink" href="/admin/applications" target="_top">/admin/applications</a>.</p> + <div class="figure"><a name="idp140623157113640"></a><p class="title"><b>Figure 4.3. Granting Permissions in 5.0</b></p><div class="figure-contents"> + + <div class="mediaobject"><img src="images/grant-perm-50.png" alt="Granting Permissions in 5.0"></div> + </div></div><br class="figure-break"> + </li></ul></div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-configuring-permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade.html">Next</a></td></tr><tr><td width="40%" align="left">Setting Permissions on an OpenACS package </td><td width="20%" align="center"><a accesskey="u" href="configuring-new-site.html">Up</a></td><td width="40%" align="right"> Chapter 5. Upgrading</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/i18n-convert.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-convert.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-convert.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -23,7 +23,7 @@ <li class="listitem"> <p> <strong>Replace all text with temporary message -tags. </strong>From<code class="computeroutput">/acs-admin/apm/</code>, select a package and then +tags. </strong> From<code class="computeroutput">/acs-admin/apm/</code>, select a package and then click on <code class="computeroutput">Internationalization</code>, then <code class="computeroutput">Convert ADP, Tcl, and SQL files to using the message catalog.</code>. This pass only changes the @@ -33,7 +33,7 @@ them key by key.</p><div class="mediaobject" align="center"><img src="images/i18n-2.png" align="middle"></div> </li><li class="listitem"><p> <strong>Replace the temporary message tags in ADP -files. </strong>From the same <code class="computeroutput">Convert ADP ...</code> page in <code class="computeroutput">/acs-admin/apm</code> as in the last step, repeat +files. </strong> From the same <code class="computeroutput">Convert ADP ...</code> page in <code class="computeroutput">/acs-admin/apm</code> as in the last step, repeat the process but deselect <code class="computeroutput">Find human language text ...</code> and select <code class="computeroutput">Replace <# ... #> tags ...</code> and click OK. This step replaces all of the temporary tags with @@ -42,7 +42,7 @@ an xml file.</p></li><li class="listitem"> <p> <strong>Replace human-readable text in Tcl files with temporary -tags. </strong>Examine all of the Tcl files in the +tags. </strong> 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 @@ -67,7 +67,7 @@ </li><li class="listitem"> <p> <strong>Replace the temporary message tags in Tcl -files. </strong>Repeat step 2 for Tcl files. Here is +files. </strong> Repeat step 2 for Tcl files. Here is the example Tcl file after conversion:</p><pre class="programlisting"> set title [_ simulation.admin_title] set context [list [list . [_ simulation.SimPlay]] \ @@ -76,8 +76,8 @@ [_ simulation.lt_Messages_for_role_pre]] </pre> </li><li class="listitem"><p> -<strong>Internationalize SQL Code. </strong>If there -is any user-visible Tcl code in the .sql or .xql files, +<strong>Internationalize SQL Code. </strong> If +there is any user-visible Tcl code in the .sql or .xql files, internationalize that the same way as for the Tcl files.</p></li><li class="listitem"><p> <strong>Internationalize Package Parameters. </strong> See <a class="xref" href="i18n-introduction" title="APM Parameters">Multilingual APM Parameters</a> @@ -131,20 +131,20 @@ internationalize numbers, use <code class="computeroutput">lc_numeric $value</code>, which formats the number using the appropriate decimal point and thousand separator for the locale.</p></li><li class="listitem"><p> -<strong>Internationalizing Forms. </strong>When +<strong>Internationalizing Forms. </strong> When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.</p></li><li class="listitem"> <p> -<a name="catalog-consistency-check" id="catalog-consistency-check"></a><strong>Checking the Consistency of -Catalog Files. </strong> 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: +<a name="catalog-consistency-check" id="catalog-consistency-check"></a><strong>Checking the Consistency +of Catalog Files. </strong> 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: <code class="computeroutput">acs-lang/bin/check-catalog.sh package_key</code> </p><p>where package_key is the key of the package that you want to @@ -154,11 +154,11 @@ </li> </ol></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592105633688" id="idp140592105633688"></a>Avoiding common i18n mistakes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +<a name="idp140623179206504" id="idp140623179206504"></a>Avoiding common i18n mistakes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> <p> <strong>Replace complicated keys with longer, simpler -keys. </strong>When writing in one language, it is +keys. </strong> When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an <code class="computeroutput">if</code> command at the end of a word which adds "s" if a count is @@ -247,9 +247,9 @@ </li><li class="listitem"> <p> <strong>Don't combine keys in display -text. </strong>Converting a phrase from one language to -another is usually more complicated than simply replacing each word -with an equivalent. When several keys are concatenated, the +text. </strong> Converting a phrase from one language +to another is usually more complicated than simply replacing each +word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys @@ -269,9 +269,9 @@ </pre> </li><li class="listitem"> <p> -<strong>Avoid unnecessary duplicate -keys. </strong>When phrases are exactly the same in -several places, use a single key.</p><p>For common words such as Yes and No, you can use a library of +<strong>Avoid unnecessary duplicate keys. </strong> +When phrases are exactly the same in several places, use a single +key.</p><p>For common words such as Yes and No, you can use a library of keys at <a class="ulink" href="/acs-lang/admin/message-list?package%5fkey=acs%2dkernel&locale=en%5fUS" target="_top">acs-kernel</a>. For example, instead of using <code class="computeroutput">myfirstpackage.Yes</code>, you can use <code class="computeroutput">acs-kernel.Yes</code>. You can also @@ -283,7 +283,7 @@ </li><li class="listitem"> <p> <strong>Don't internationalize internal code -words. </strong>Many packages use code words or key +words. </strong> Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change @@ -293,7 +293,7 @@ -key "resolution" \ -value [db_string select_resolution_code {}] </pre><p>This is incorrectly internationalized to</p><pre class="programlisting"> - workflow::case::add_log_data \ + workflow::case::add_log_data \ -entry_id $entry_id \ -key "[_ bug-tracker.resolution]" \ -value [db_string select_resolution_code {}] @@ -308,7 +308,7 @@ </li><li class="listitem"> <p> <strong>Fix automatic truncated message -keys. </strong>The automatic converter may create +keys. </strong> The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:</p><pre class="programlisting"> <msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg> @@ -334,9 +334,9 @@ should be <code class="computeroutput">bug_tracker_component_maintainer</code>.</p> </li><li class="listitem"><p> <strong>Translations in Avoid "clever" message -reuse. </strong>Translations may need to differ +reuse. </strong> Translations may need to differ depending on the context in which the message appears.</p></li><li class="listitem"><p> -<strong>Avoid plurals. </strong>Different languages +<strong>Avoid plurals. </strong> Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a @@ -345,7 +345,7 @@ two forms of plurals.</p></li><li class="listitem"> <p> <strong>Quoting in the message catalog for -tcl. </strong>Watch out for quoting and escaping when +tcl. </strong> Watch out for quoting and escaping when editing text that is also code. For example, the original string</p><pre class="programlisting"> set title "Patch \"$patch_summary\" is nice." @@ -360,11 +360,11 @@ output).</p> </li><li class="listitem"> <p> -<strong>Be careful with curly -brackets. </strong>Code within curly brackets isn't -evaluated. Tcl uses curly brackets as an alternative way to build -lists. But Tcl also uses curly brackets as an alternative to -quotation marks for quoting text. So this original code</p><pre class="programlisting"> +<strong>Be careful with curly brackets. </strong> +Code within curly brackets isn't evaluated. Tcl uses curly +brackets as an alternative way to build lists. But Tcl also uses +curly brackets as an alternative to quotation marks for quoting +text. So this original code</p><pre class="programlisting"> array set names { key "Pretty" ...} </pre><p>... if converted to</p><pre class="programlisting"> array set names { key "[_bug-tracker.Pretty]" ...} 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 -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/i18n-convert.html 7 Aug 2017 23:47:50 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/i18n-convert.html 8 Nov 2017 09:42:10 -0000 1.28 @@ -1,5 +1,9 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to Internationalize a Package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-introduction.html" title="How Internationalization/Localization works in OpenACS"><link rel="next" href="i18n-design.html" title="Design Notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-introduction.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-convert"></a>How to Internationalize a Package</h2></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to Internationalize a Package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-introduction.html" title="How Internationalization/Localization works in OpenACS"><link rel="next" href="i18n-design.html" title="Design Notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-introduction.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-convert"></a>How to Internationalize a Package</h2></div></div></div> + + + <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + <p> For multilingual websites we recommend using the UTF8 charset. In order for AOLserver to use utf8 you need to set the config parameters OutputCharset and @@ -9,53 +13,151 @@ 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). - </p></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Replace all text with temporary message tags. </b>From<code class="computeroutput">/acs-admin/apm/</code>, select a + </p> + </div> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Replace all text with temporary message tags. </b> + From<code class="computeroutput">/acs-admin/apm/</code>, select a package and then click on <code class="computeroutput">Internationalization</code>, then <code class="computeroutput">Convert ADP, Tcl, and SQL files to using the - message catalog.</code>. This pass only changes the adp files; it does not affect catalog files or the catalog in the database.</p><div class="mediaobject" align="center"><img src="images/i18n-1.png" align="middle"></div><p>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.</p><div class="mediaobject" align="center"><img src="images/i18n-2.png" align="middle"></div></li><li class="listitem"><p><b>Replace the temporary message tags in ADP files. </b>From the same <code class="computeroutput">Convert ADP ...</code> page in <code class="computeroutput">/acs-admin/apm</code> as in the last step, repeat the process but deselect <code class="computeroutput">Find human language text ...</code> and select <code class="computeroutput">Replace <# ... #> tags ...</code> 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.</p></li><li class="listitem"><p><b>Replace human-readable text in Tcl files with temporary tags. </b>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 (<code class="computeroutput">_</code>), then the message keys will be auto-generated from the original message text. Here is an unmodified Tcl file:</p><pre class="programlisting"> + message catalog.</code>. This pass only changes the adp files; it does not affect catalog files or the catalog in the database. + </p> + <div class="mediaobject" align="center"><img src="images/i18n-1.png" align="middle"></div> + + <p>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.</p> + <div class="mediaobject" align="center"><img src="images/i18n-2.png" align="middle"></div> + + </li><li class="listitem"> + <p> + <b>Replace the temporary message tags in ADP files. </b> + From the same <code class="computeroutput">Convert ADP ...</code> page in <code class="computeroutput">/acs-admin/apm</code> as in the last step, repeat the process but deselect <code class="computeroutput">Find human language text ...</code> and select <code class="computeroutput">Replace <# ... #> tags ...</code> 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. + </p> + </li><li class="listitem"> + <p> + <b>Replace human-readable text in Tcl files with temporary tags. </b> + 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 (<code class="computeroutput">_</code>), then the message keys will be auto-generated from the original message text. Here is an unmodified Tcl file: + </p> +<pre class="programlisting"> set title "Messages for $a(name) in $b(label)" set context [list [list . "SimPlay"] \ [list [export_vars -base case-admin { case_id }] \ "Administer $a(name)"] \ "Messages for $a(name)"] -</pre><p>... and here is the same file after temporary message tags have been manually added:</p><pre class="programlisting"> +</pre> +<p>... and here is the same file after temporary message tags have been manually added:</p> + +<pre class="programlisting"> set title <#admin_title Messages for %a.name% in %b.label%#> set context [list [list . <#_ SimPlay#>] \ [list [export_vars -base case-admin { case_id }] \ <#_ Administer %a.name%#>] \ <#_ Messages for %a.name%#>] -</pre><p>Note that the message key <code class="computeroutput">case_admin_page_title</code> was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing -</p></li><li class="listitem"><p><b>Replace the temporary message tags in Tcl files. </b>Repeat step 2 for Tcl files. Here is the example Tcl file after conversion:</p><pre class="programlisting"> +</pre> + <p>Note that the message key <code class="computeroutput">case_admin_page_title</code> was manually selected, because an autogenerated key for this text, with its substitute variables, would have been very confusing +</p> + </li><li class="listitem"> + <p> + <b>Replace the temporary message tags in Tcl files. </b> + Repeat step 2 for Tcl files. Here is the example Tcl file after conversion: + </p> + <pre class="programlisting"> set title [_ simulation.admin_title] set context [list [list . [_ simulation.SimPlay]] \ [list [export_vars -base case-admin { case_id }] \ [_ simulation.lt_Administer_name_gt]] \ [_ simulation.lt_Messages_for_role_pre]] -</pre></li><li class="listitem"><p><b>Internationalize SQL Code. </b>If there is any user-visible Tcl code in the .sql or .xql files, internationalize that the same way as for the Tcl files.</p></li><li class="listitem"><p><b>Internationalize Package Parameters. </b> +</pre> + </li><li class="listitem"> + <p> + <b>Internationalize SQL Code. </b> + If there is any user-visible Tcl code in the .sql or .xql files, internationalize that the same way as for the Tcl files. + </p> + </li><li class="listitem"> + <p> + <b>Internationalize Package Parameters. </b> + See <a class="xref" href="i18n-introduction.html#i18n-message-apm-params" title="APM Parameters">Multilingual APM Parameters</a> - </p></li><li class="listitem"><p><b>Internationalize Date and Time queries. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Find datetime in .xql files. Use command line tools to find suspect SQL code:</p><pre class="programlisting">grep -r "to_char.*H" * + + </p> + </li><li class="listitem"> + <p> + <b>Internationalize Date and Time queries. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Find datetime in .xql files. Use command line tools to find suspect SQL code:</p> + <pre class="programlisting">grep -r "to_char.*H" * grep -r "to_date.*H" * -</pre></li><li class="listitem"><p>In SQL statements, replace the format string with the ANSI standard format, <code class="computeroutput">YYYY-MM-DD HH24:MI:SS</code> and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,</p><pre class="programlisting">to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty</pre><p>becomes</p><pre class="programlisting">to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi</pre></li><li class="listitem"><p>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 <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=lc_time_system_to_conn" target="_top">lc_time_system_to_conn</a></code>:</p><pre class="programlisting"> -set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]</pre><p>When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=lc%5ftime%5fconn%5fto%5fsystem" target="_top">lc_time_conn_to_system</a></code>. -</p></li><li class="listitem"><p>When a datetime field will be displayed, format it using the localizing function <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=lc_time_fmt" target="_top">lc_time_fmt</a></code>. 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: <code class="computeroutput">%x, %X, %q, %Q, and %c.</code></p><pre class="programlisting">set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]</pre><p> +</pre> + </li><li class="listitem"> + <p>In SQL statements, replace the format string with the ANSI standard format, <code class="computeroutput">YYYY-MM-DD HH24:MI:SS</code> and change the field name to *_ansi so that it cannot be confused with previous, improperly formatting fields. For example,</p> + <pre class="programlisting">to_char(timestamp,'MM/DD/YYYY HH:MI:SS') as foo_date_pretty</pre> + <p>becomes</p> + <pre class="programlisting">to_char(timestamp,'YYYY-MM-DD HH24:MI:SS') as foo_date_ansi</pre> + </li><li class="listitem"> + <p>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 <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=lc_time_system_to_conn" target="_top">lc_time_system_to_conn</a></code>:</p> +<pre class="programlisting"> +set foo_date_ansi [lc_time_system_to_conn $foo_date_ansi]</pre> + <p>When a datetime will be written to the database, first convert it from the user's local time to the server's timezone with <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=lc%5ftime%5fconn%5fto%5fsystem" target="_top">lc_time_conn_to_system</a></code>. +</p> + </li><li class="listitem"> + <p>When a datetime field will be displayed, format it using the localizing function <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=lc_time_fmt" target="_top">lc_time_fmt</a></code>. 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: <code class="computeroutput">%x, %X, %q, %Q, and %c.</code></p> + <pre class="programlisting">set foo_date_pretty [lc_time_fmt $foo_date_ansi "%x %X"]</pre> + + <p> Use the <code class="computeroutput">_pretty</code> version in your ADP page. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> %c: Long date and time (Mon November 18, 2002 12:00 AM) - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> %x: Short date (11/18/02) - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> %X: Time (12:00 AM) - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> %q: Long date without weekday (November 18, 2002) - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> %Q: Long date with weekday (Monday November 18, 2002) - </p></li></ul></div><p> + </p> + </li></ul></div> + + <p> The "q" format strings are OpenACS additions; the rest follow unix standards (see <code class="computeroutput">man strftime</code>). - </p></li></ol></div></li><li class="listitem"><p><b>Internationalize Numbers. </b> + </p> + + </li></ol></div> + </li><li class="listitem"> + <p> + <b>Internationalize Numbers. </b> + To internationalize numbers, use <code class="computeroutput">lc_numeric $value</code>, which formats the number using the appropriate decimal point and thousand separator for the locale. - </p></li><li class="listitem"><p><b>Internationalizing Forms. </b>When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels.</p></li><li class="listitem"><p><a name="catalog-consistency-check"></a><b>Checking the Consistency of Catalog Files. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Internationalizing Forms. </b> + When coding forms, remember to use message keys for each piece of text that is user-visible, including form option labels and button labels. + </p> + </li><li class="listitem"> + <p><a name="catalog-consistency-check"></a> + + <b>Checking the Consistency of Catalog Files. </b> + + 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 @@ -67,20 +169,46 @@ <code class="computeroutput"> acs-lang/bin/check-catalog.sh package_key </code> - </p><p> + + </p> + + + <p> 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. - </p></li></ol></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592105633688"></a>Avoiding common i18n mistakes</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Replace complicated keys with longer, simpler keys. </b>When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an <code class="computeroutput">if</code> command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it.</p><p>The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:</p><pre class="programlisting"> <p class="form-help-text"><b>Invitations</b> are sent, - when this wizard is completed and casting begins.</p></pre><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:</p><div class="mediaobject" align="center"><img src="images/i18n-3.png" align="middle"></div><p>Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:</p><pre class="programlisting"> <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, + </p> + </li></ol></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623179206504"></a>Avoiding common i18n mistakes</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Replace complicated keys with longer, simpler keys. </b> + When writing in one language, it is possible to create clever code to make correct text. In English, for example, you can put an <code class="computeroutput">if</code> command at the end of a word which adds "s" if a count is anything but 1. This pluralizes nouns correctly based on the data. However, it is confusing to read and, when internationalized, may result in message keys that are both confusing and impossible to set correctly in some languages. While internationalizing, watch out that the automate converter does not create such keys. Also, refactor compound text as you encounter it. + </p> + + <p>The automated system can easily get confused by tags within message texts, so that it tries to create two or three message keys for one long string with a tag in the middle. In these cases, uncheck those keys during the conversion and then edit the files directly. For example, this code:</p> + <pre class="programlisting"> <p class="form-help-text"><b>Invitations</b> are sent, + when this wizard is completed and casting begins.</p></pre> + <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:</p> + <div class="mediaobject" align="center"><img src="images/i18n-3.png" align="middle"></div> + <p>Instead, we cancel those keys, edit the file manually, and put in a single temporary message tag:</p> + + <pre class="programlisting"> <p class="form-help-text"> <#Invitations_are_sent <b>Invitations</b> are sent, when this wizard is completed and casting begins.#> - </p></pre><p>Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:</p><pre class="programlisting">Select which case <if @simulation.casting_type@ eq "open">and + </p></pre> + + <p>Complex if statements may produce convoluted message keys that are very hard to localize. Rewrite these if statements. For example:</p> + <pre class="programlisting">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.</pre><p>... can be rewritten:</p><pre class="programlisting"><if @simulation.casting_type@ eq "open"> +simulation begins.</pre> + <p>... can be rewritten:</p> + <pre class="programlisting"><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 @@ -95,7 +223,9 @@ be automatically assigned to a case when the simulation begins. -</else></pre><p>Another example, where bugs are concatenated with a number:</p><pre class="programlisting"><if @components.view_bugs_url@ not nil> +</else></pre> + <p>Another example, where bugs are concatenated with a number:</p> +<pre class="programlisting"><if @components.view_bugs_url@ not nil> <a href="@components.view_bugs_url@" title="View the @pretty_names.bugs@ for this component"> </if> @components.num_bugs@ @@ -122,41 +252,125 @@ <if @components.view_bugs_url@ not nil> </a> </if> -</pre><p>It would probably be better to do this as something like:</p><pre class="programlisting"><if @components.view_bugs_url@ not nil> +</pre> + <p>It would probably be better to do this as something like:</p> +<pre class="programlisting"><if @components.view_bugs_url@ not nil> <if @components.num_bugs@ eq 1> <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.one_bug#</a> </if><else> <a href="@components.view_bugs_url@" title="#bug-tracker.View_the_bug_fo_component#">#bug-tracker.N_bugs#</a> </else> -</if></pre></li><li class="listitem"><p><b>Don't combine keys in display text. </b>Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example:</p><p>Original code:</p><pre class="programlisting">multirow append links "New [bug_tracker::conn Bug]" </pre><p>Problematic conversion:</p><pre class="programlisting">multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"</pre><p>Better conversion:</p><pre class="programlisting">set bug_label [bug_tracker::conn Bug] -multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"</pre><p>... and include the variable in the key: <code class="computeroutput">"New %bug_label%"</code>. This gives translators more control over the phrase.</p><p>In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):</p><pre class="programlisting"><a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@"> -@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a></pre></li><li class="listitem"><p><b>Avoid unnecessary duplicate keys. </b>When phrases are exactly the same in several places, use a single key.</p><p>For common words such as +</if></pre> + </li><li class="listitem"> + <p> + <b>Don't combine keys in display text. </b> + Converting a phrase from one language to another is usually more complicated than simply replacing each word with an equivalent. When several keys are concatenated, the resulting word order will not be correct for every language. Different languages may use expressions or idioms that don't match the phrase key-for-key. Create complete, distinct keys instead of building text from several keys. For example: + </p> + <p>Original code:</p> + <pre class="programlisting">multirow append links "New [bug_tracker::conn Bug]" </pre> + <p>Problematic conversion:</p> + <pre class="programlisting">multirow append links "[_ bug-tracker.New] [bug_tracker::conn Bug]"</pre> + <p>Better conversion:</p> + <pre class="programlisting">set bug_label [bug_tracker::conn Bug] +multirow append links "[_ bug-tracker.New_Bug]" "${url_prefix}bug-add"</pre> + <p>... and include the variable in the key: <code class="computeroutput">"New %bug_label%"</code>. This gives translators more control over the phrase.</p> + + + <p>In this example of bad i18n, full name is created by concatenating first and last name (admittedly this is pervasive in the toolkit):</p> + <pre class="programlisting"><a href="@past_version.maintainer_url@" title="#bug-tracker.Email# @past_version.maintainer_email@"> +@past_version.maintainer_first_names@ @past_version.maintainer_last_name@</a></pre> + </li><li class="listitem"> + <p> + <b>Avoid unnecessary duplicate keys. </b> + + When phrases are exactly the same in several places, use a single key. + </p> + <p>For common words such as Yes and No, you can use a library of keys at <a class="ulink" href="/acs-lang/admin/message-list?package%5fkey=acs%2dkernel&locale=en%5fUS" target="_top">acs-kernel</a>. For example, instead of using <code class="computeroutput">myfirstpackage.Yes</code>, you can use <code class="computeroutput">acs-kernel.Yes</code>. You can also use the <a class="ulink" href="/acs-lang/admin/package-list?locale=en%5fUS" target="_top">Message Key Search</a> facility to find duplicates. Be careful, however, building up sentences from keys because grammar and other elements may not be consistent - across different locales.</p><p>Additional discussion: <a class="ulink" href="http://openacs.org/forums/message-view?message_id=164973" target="_top">Re: + across different locales.</p> + <p>Additional discussion: <a class="ulink" href="http://openacs.org/forums/message-view?message_id=164973" target="_top">Re: Bug 961 ("Control Panel" displayed instead of "Administer")</a>, <a class="ulink" href="http://openacs.org/forums/message-view?message_id=125235" target="_top">Translation - server upgraded</a>, and <a class="ulink" href="http://openacs.org/forums/message-view?message_id=158580" target="_top">Localization questions</a>.</p></li><li class="listitem"><p><b>Don't internationalize internal code words. </b>Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these.</p><p>For example, the original code is </p><pre class="programlisting">workflow::case::add_log_data \ + server upgraded</a>, and <a class="ulink" href="http://openacs.org/forums/message-view?message_id=158580" target="_top">Localization questions</a>.</p> + </li><li class="listitem"> + <p> + <b>Don't internationalize internal code words. </b> + Many packages use code words or key words, such as "open" and "closed", which will never be shown to the user. They may match key values in the database, or be used in a switch or if statement. Don't change these. + </p> + <p>For example, the original code is </p> + <pre class="programlisting">workflow::case::add_log_data \ -entry_id $entry_id \ -key "resolution" \ - -value [db_string select_resolution_code {}]</pre><p>This is incorrectly internationalized to </p><pre class="programlisting"> workflow::case::add_log_data \ + -value [db_string select_resolution_code {}]</pre> + <p>This is incorrectly internationalized to </p> + <pre class="programlisting"> workflow::case::add_log_data \ -entry_id $entry_id \ -key "[_ bug-tracker.resolution]" \ - -value [db_string select_resolution_code {}]</pre><p>But <code class="computeroutput">resolution</code> is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:</p><pre class="programlisting">{show_patch_status "open"}</pre><p>It is broken if changed to</p><pre class="programlisting">{show_patch_status "[_ bug-tracker.open]"}</pre></li><li class="listitem"><p><b>Fix automatic truncated message keys. </b>The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example:</p><pre class="programlisting"> + -value [db_string select_resolution_code {}]</pre> + <p>But <code class="computeroutput">resolution</code> is a keyword in a table and in the code, so this breaks the code. It should not have been internationalized at all. Here's another example of text that should not have been internationalized:</p> + <pre class="programlisting">{show_patch_status "open"}</pre> + <p>It is broken if changed to</p> + <pre class="programlisting">{show_patch_status "[_ bug-tracker.open]"}</pre> + </li><li class="listitem"> + <p> + <b>Fix automatic truncated message keys. </b> + The automatic converter may create unique but crytic message keys. Watch out for these and replace them with more descriptive keys. For example: + </p> + <pre class="programlisting"> <msg key="You">You can filter by this %component_name% by viisting %filter_url_string%</msg> <msg key="You_1">You do not have permission to map this patch to a bug. Only the submitter of the patch and users with write permission on this Bug Tracker project (package instance) may do so.</msg> <msg key="You_2">You do not have permission to edit this patch. Only the submitter of the patch -and users with write permission on the Bug Tracker project (package instance) may do so.</msg></pre><p>These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? -</p><p>Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:</p><pre class="programlisting"><msg key="Fix">for version</msg> +and users with write permission on the Bug Tracker project (package instance) may do so.</msg></pre> + <p>These would be more useful if they were, "you_can_filter", "you_do_not_have_permission_to_map_this_patch", and "you_do_not_have_permission_to_edit_this_patch". Don't worry about exactly matching the english text, because that might change; instead try to capture the meaning of the phrase. Ask yourself, if I was a translator and didn't know how this application worked, would this key and text make translation easy for me? +</p> + <p>Sometimes the automatic converter creates keys that don't semantically match their text. Fix these:</p> + <pre class="programlisting"><msg key="Fix">for version</msg> <msg key="Fix_1">for</msg> -<msg key="Fix_2">for Bugs</msg></pre><p>Another example: <code class="computeroutput">Bug-tracker component maintainer</code> was converted to <code class="computeroutput">[_ bug-tracker.Bug-tracker]</code>. Instead, it should be <code class="computeroutput">bug_tracker_component_maintainer</code>.</p></li><li class="listitem"><p><b>Translations in Avoid "clever" message reuse. </b>Translations may need to differ depending on the context in which +<msg key="Fix_2">for Bugs</msg></pre> + + <p>Another example: <code class="computeroutput">Bug-tracker component maintainer</code> was converted to <code class="computeroutput">[_ bug-tracker.Bug-tracker]</code>. Instead, it should be <code class="computeroutput">bug_tracker_component_maintainer</code>.</p> + </li><li class="listitem"> + <p> + <b>Translations in Avoid "clever" message reuse. </b> + Translations may need to differ depending on the context in which the message appears. -</p></li><li class="listitem"><p><b>Avoid plurals. </b>Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals.</p></li><li class="listitem"><p><b>Quoting in the message catalog for tcl. </b>Watch out for quoting and escaping when editing text that is also code. For example, the original string </p><pre class="programlisting">set title "Patch \"$patch_summary\" is nice."</pre><p>breaks if the message text retains all of the escaping that was in the Tcl command:</p><pre class="programlisting"><msg>Patch \"$patch_summary\" is nice.</msg></pre><p>When it becomes a key, it should be:</p><pre class="programlisting"><msg>Patch "$patch_summary" is nice.</msg></pre><p>Also, some keys had %var;noquote%, which is not needed since those + + </p> + </li><li class="listitem"> + <p> + <b>Avoid plurals. </b> + Different languages create plurals differently. Try to avoid keys which will change based on the value of a number. OpenACS does not currently support internationalization of plurals. If you use two different keys, a plural and a singular form, your application will not localize properly for locales which use different rules or have more than two forms of plurals. + </p> + </li><li class="listitem"> + <p> + <b>Quoting in the message catalog for tcl. </b> + Watch out for quoting and escaping when editing text that is also code. For example, the original string + </p> + <pre class="programlisting">set title "Patch \"$patch_summary\" is nice."</pre> + <p>breaks if the message text retains all of the escaping that was in the Tcl command:</p> + <pre class="programlisting"><msg>Patch \"$patch_summary\" is nice.</msg></pre> + <p>When it becomes a key, it should be:</p> + <pre class="programlisting"><msg>Patch "$patch_summary" is nice.</msg></pre> + <p>Also, some keys had %var;noquote%, which is not needed since those variables are not quoted (and in fact the variable won't even be - recognized so you get the literal %var;noquote% in the output).</p></li><li class="listitem"><p><b>Be careful with curly brackets. </b>Code within curly brackets isn't evaluated. Tcl uses curly brackets as an alternative way to build lists. But Tcl also uses curly brackets as an alternative to quotation marks for quoting text. So this original code</p><pre class="programlisting">array set names { key "Pretty" ...} </pre><p>... if converted to </p><pre class="programlisting">array set names { key "[_bug-tracker.Pretty]" ...} </pre><p>... won't work since the _ func will not be called. Instead, it should be </p><pre class="programlisting">array set names [list key [_bug-tracker.Pretty] ...]</pre></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-introduction.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-design.html">Next</a></td></tr><tr><td width="40%" align="left">How Internationalization/Localization works in OpenACS </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> Design Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + recognized so you get the literal %var;noquote% in the output).</p> + </li><li class="listitem"> + <p> + <b>Be careful with curly brackets. </b> + Code within curly brackets isn't evaluated. Tcl uses curly brackets as an alternative way to build lists. But Tcl also uses curly brackets as an alternative to quotation marks for quoting text. So this original code + </p> + <pre class="programlisting">array set names { key "Pretty" ...} </pre> + <p>... if converted to </p> + <pre class="programlisting">array set names { key "[_bug-tracker.Pretty]" ...} </pre> + <p>... won't work since the _ func will not be called. Instead, it should be </p> + <pre class="programlisting">array set names [list key [_bug-tracker.Pretty] ...]</pre> + </li></ul></div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-introduction.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-design.html">Next</a></td></tr><tr><td width="40%" align="left">How Internationalization/Localization works in OpenACS </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> Design Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> 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 -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/i18n-design.html 7 Aug 2017 23:47:50 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/i18n-design.html 8 Nov 2017 09:42:10 -0000 1.18 @@ -1,3 +1,9 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Design Notes</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-convert.html" title="How to Internationalize a Package"><link rel="next" href="i18n-translators.html" title="Translator's Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-convert.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-translators.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-design"></a>Design Notes</h2></div></div></div><p>User locale is a property of ad_conn, <code class="computeroutput">ad_conn locale</code>. The request processor sets this by calling <code class="computeroutput">lang::conn::locale</code>, which looks for the following in order of precedence:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Use user preference for this package (stored in ad_locale_user_prefs)</p></li><li class="listitem"><p>Use system preference for the package (stored in apm_packages)</p></li><li class="listitem"><p>Use user's general preference (stored in user_preferences)</p></li><li class="listitem"><p>Use Browser header (<code class="computeroutput">Accept-Language</code> HTTP header)</p></li><li class="listitem"><p>Use system locale (an APM parameter for acs_lang)</p></li><li class="listitem"><p>default to en_US</p></li></ol></div><p>For ADP pages, message key lookup occurs in the templating engine. For Tcl pages, message key lookup happens with the <code class="computeroutput">_</code> 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.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-convert.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-translators.html">Next</a></td></tr><tr><td width="40%" align="left">How to Internationalize a Package </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> Translator's Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Design Notes</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-convert.html" title="How to Internationalize a Package"><link rel="next" href="i18n-translators.html" title="Translator's Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-convert.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-translators.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-design"></a>Design Notes</h2></div></div></div> + + <p>User locale is a property of ad_conn, <code class="computeroutput">ad_conn locale</code>. The request processor sets this by calling <code class="computeroutput">lang::conn::locale</code>, which looks for the following in order of precedence:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Use user preference for this package (stored in ad_locale_user_prefs)</p></li><li class="listitem"><p>Use system preference for the package (stored in apm_packages)</p> + </li><li class="listitem"><p>Use user's general preference (stored in user_preferences)</p></li><li class="listitem"><p>Use Browser header (<code class="computeroutput">Accept-Language</code> HTTP header)</p></li><li class="listitem"><p>Use system locale (an APM parameter for acs_lang)</p></li><li class="listitem"><p>default to en_US</p></li></ol></div> + <p>For ADP pages, message key lookup occurs in the templating engine. For Tcl pages, message key lookup happens with the <code class="computeroutput">_</code> 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.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-convert.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-translators.html">Next</a></td></tr><tr><td width="40%" align="left">How to Internationalize a Package </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> Translator's Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/i18n-introduction.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-introduction.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -76,16 +76,15 @@ page is usable before you have done localization.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> <p>The <span class="strong"><strong>short</strong></span>: -<code class="computeroutput">#<span class="replaceable"><span class="replaceable">package_key.message_key</span></span>#</code> +<code class="computeroutput">#<em class="replaceable"><code>package_key.message_key</code></em>#</code> </p><p>The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable. Example: -<code class="computeroutput">#<span class="replaceable"><span class="replaceable">forum.title</span></span>#</code> +<code class="computeroutput">#<em class="replaceable"><code>forum.title</code></em>#</code> </p> </li><li class="listitem"> <p>The <span class="strong"><strong>verbose</strong></span>: -<code class="computeroutput"><trn key="<span class="replaceable"><span class="replaceable">package_key.message_key</span></span>" -locale="<span class="replaceable"><span class="replaceable">locale</span></span>"><span class="replaceable"><span class="replaceable">default -text</span></span></trn></code> +<code class="computeroutput"><trn key="<em class="replaceable"><code>package_key.message_key</code></em>" +locale="<em class="replaceable"><code>locale</code></em>"><em class="replaceable"><code>default text</code></em></trn></code> </p><p>The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended anymore, but it can be convenient for development, because it still works even if @@ -97,8 +96,7 @@ </p> </li><li class="listitem"> <p>The <span class="strong"><strong>temporary</strong></span>: -<code class="computeroutput"><#<span class="replaceable"><span class="replaceable">message_key</span></span><span class="replaceable"><span class="replaceable">original -text</span></span>#></code> +<code class="computeroutput"><#<em class="replaceable"><code>message_key</code></em><em class="replaceable"><code>original text</code></em>#></code> </p><p>This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that stays in the page. As you'll see later, it'll be replaced with the @@ -219,12 +217,12 @@ </tr></thead><tbody> <tr> <td>class_instance_pages_csv</td><td> -<code class="computeroutput">#<span class="replaceable"><span class="replaceable">dotlrn.class_page_home_title</span></span>#</code>,Simple -2-Column;<code class="computeroutput">#<span class="replaceable"><span class="replaceable">dotlrn.class_page_calendar_title</span></span>#</code>,Simple -1-Column;<code class="computeroutput">#<span class="replaceable"><span class="replaceable">dotlrn.class_page_file_storage_title</span></span>#</code>,Simple +<code class="computeroutput">#<em class="replaceable"><code>dotlrn.class_page_home_title</code></em>#</code>,Simple +2-Column;<code class="computeroutput">#<em class="replaceable"><code>dotlrn.class_page_calendar_title</code></em>#</code>,Simple +1-Column;<code class="computeroutput">#<em class="replaceable"><code>dotlrn.class_page_file_storage_title</code></em>#</code>,Simple 1-Column</td> </tr><tr> -<td>departments_pretty_name</td><td><code class="computeroutput">#<span class="replaceable"><span class="replaceable">departments_pretty_name</span></span>#</code></td> +<td>departments_pretty_name</td><td><code class="computeroutput">#<em class="replaceable"><code>departments_pretty_name</code></em>#</code></td> </tr> </tbody> </table></div><p>Then, depending on how we retrieve the value, here's what we @@ -242,7 +240,7 @@ <td>parameter::get <span class="strong"><strong>-localize</strong></span> -parameter departments_pretty_name</td><td>Abteilung</td> </tr><tr> -<td>parameter::get -parameter departments_pretty_name</td><td><code class="computeroutput">#<span class="replaceable"><span class="replaceable">departments_pretty_name</span></span>#</code></td> +<td>parameter::get -parameter departments_pretty_name</td><td><code class="computeroutput">#<em class="replaceable"><code>departments_pretty_name</code></em>#</code></td> </tr> </tbody> </table></div><p>The value in the rightmost column in the table above is the 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 -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/i18n-introduction.html 7 Aug 2017 23:47:50 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/i18n-introduction.html 8 Nov 2017 09:42:10 -0000 1.20 @@ -1,5 +1,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How Internationalization/Localization works in OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-overview.html" title="Internationalization and Localization Overview"><link rel="next" href="i18n-convert.html" title="How to Internationalize a Package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-convert.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-introduction"></a>How Internationalization/Localization works in OpenACS</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How Internationalization/Localization works in OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-overview.html" title="Internationalization and Localization Overview"><link rel="next" href="i18n-convert.html" title="How to Internationalize a Package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-convert.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-introduction"></a>How Internationalization/Localization works in OpenACS</h2></div></div></div> + + <p> This document describes how to develop internationalized OpenACS packages, including writing new packages with internationalization and converting old packages. Text that @@ -11,19 +13,25 @@ not also localize your package for different locales, volunteers may use a public "localization server" to submit suggested text. Otherwise, your package will not be usable for all locales. - </p><p> + </p> + + <p> The main difference between monolingual and internationalized packages is that all user-visible text in the code of an internationalized package are coded as "message keys." The message keys correspond to a message catalog, which contains versions of the text for each available language. Script files (.adp and .tcl and .vuh), database files (.sql), and APM parameters are affected. - </p><p> + </p> + + <p> 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. - </p><p> + </p> + + <p> 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 @@ -33,34 +41,60 @@ 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. - </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-content"></a>User Content</h3></div></div></div><p>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.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-locale-templates"></a>Separate Templates for each Locale</h3></div></div></div><p>If the request processor finds a file named <code class="computeroutput">filename.locale.adp</code>, where locale matches the user's locale, it will process that file instead of <code class="computeroutput">filename.adp</code>. For example, for a user with locale <code class="computeroutput">tl_PH</code>, the file <code class="computeroutput">index.tl_PH.adp</code>, if found, will be used instead of <code class="computeroutput">index.adp</code>. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-message-catalog"></a>Message Catalogs</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-catalog-adps"></a>Message Keys in Template Files (ADP Files)</h4></div></div></div><p> + </p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-content"></a>User Content</h3></div></div></div> + + <p>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.</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-locale-templates"></a>Separate Templates for each Locale</h3></div></div></div> + + + <p>If the request processor finds a file named <code class="computeroutput">filename.locale.adp</code>, where locale matches the user's locale, it will process that file instead of <code class="computeroutput">filename.adp</code>. For example, for a user with locale <code class="computeroutput">tl_PH</code>, the file <code class="computeroutput">index.tl_PH.adp</code>, if found, will be used instead of <code class="computeroutput">index.adp</code>. The locale-specific file should thus contain text in the language appropriate for that locale. The code in the page, however, should still be in English. Message keys are processed normally.</p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-message-catalog"></a>Message Catalogs</h3></div></div></div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-catalog-adps"></a>Message Keys in Template Files (ADP Files)</h4></div></div></div> + + + <p> Internationalizing templates is about replacing human readable text in a certain language with internal message keys, which can then be dynamically replaced with real human language in the desired locale. Message keys themselves should be in ASCII English, as should all code. Three different syntaxes are possible for message keys. - </p><p> + </p> + + <p> "Short" syntax is the recommended syntax and should be used for new development. When internationalizing an existing package, you can use the "temporary" syntax, which the APM can use to auto-generate missing keys and automatically translate to the short syntax. The "verbose" syntax is useful while developing, because it allows default text so that the page is usable before you have done - localization. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + localization. </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> The <span class="strong"><strong>short</strong></span>: - <code class="computeroutput">#<span class="replaceable"><span class="replaceable">package_key.message_key</span></span>#</code> - </p><p> + <code class="computeroutput">#<em class="replaceable"><code>package_key.message_key</code></em>#</code> + </p> + <p> The advantage of the short syntax is that it's short. It's as simple as inserting the value of a variable. Example: - <code class="computeroutput">#<span class="replaceable"><span class="replaceable">forum.title</span></span>#</code> - </p></li><li class="listitem"><p> + <code class="computeroutput">#<em class="replaceable"><code>forum.title</code></em>#</code> + </p> + </li><li class="listitem"> + <p> The <span class="strong"><strong>verbose</strong></span>: <code class="computeroutput"><trn - key="<span class="replaceable"><span class="replaceable">package_key.message_key</span></span>" - locale="<span class="replaceable"><span class="replaceable">locale</span></span>"><span class="replaceable"><span class="replaceable">default - text</span></span></trn></code> - </p><p> + key="<em class="replaceable"><code>package_key.message_key</code></em>" + locale="<em class="replaceable"><code>locale</code></em>"><em class="replaceable"><code>default + text</code></em></trn></code> + </p> + <p> The verbose syntax allows you to specify a default text in a certain language. This syntax is not recommended anymore, but it can be convenient for development, because @@ -69,27 +103,45 @@ create the message key with the default text from the tag as the localized message. Example: <span class="emphasis"><em><trn key="forum.title" locale="en_US">Title</trn></em></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The <span class="strong"><strong>temporary</strong></span>: - <code class="computeroutput"> <#<span class="replaceable"><span class="replaceable">message_key</span></span> - <span class="replaceable"><span class="replaceable">original text</span></span>#></code> - </p><p> + <code class="computeroutput"> <#<em class="replaceable"><code>message_key</code></em> + <em class="replaceable"><code>original text</code></em>#></code> + </p> + <p> This syntax has been designed to make it easy to internationalize existing pages. This is not a syntax that stays in the page. As you'll see later, it'll be replaced with the short syntax by a special feature of the APM. You may leave out the message_key by writing an underscore (_) character instead, in which case a message key will be auto-generated by the APM. Example: <span class="emphasis"><em><_ Title></em></span> - </p></li></ul></div><p> + </p> + </li></ul></div> + + <p> We recommend the short notation for new package development. - </p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-catalog-tcl"></a>Message Keys in Tcl Files</h4></div></div></div><p> + </p> + + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-catalog-tcl"></a>Message Keys in Tcl Files</h4></div></div></div> + + + <p> In adp files message lookups are typically done with the syntax <code class="computeroutput">\#package_key.message_key\#</code>. In Tcl files all message lookups *must* be on either of the following formats: - </p><p> - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Typical static key lookup: <code class="computeroutput">[_ package_key.message_key]</code> - The message key and package key used here must be string literals, they can't result from variable evaluation.</p></li><li class="listitem"><p> - Static key lookup with non-default locale: <code class="computeroutput">[lang::message::lookup $locale package_key.message_key]</code> - The message key and package key used here must be string literals, they can't result from variable evaluation.</p></li><li class="listitem"><p> + </p> + + <p> + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Typical static key lookup: <code class="computeroutput">[_ package_key.message_key]</code> - The message key and package key used here must be string literals, they can't result from variable evaluation.</p> + </li><li class="listitem"><p> + Static key lookup with non-default locale: <code class="computeroutput">[lang::message::lookup $locale package_key.message_key]</code> - The message key and package key used here must be string literals, they can't result from variable evaluation.</p> + </li><li class="listitem"> + <p> Dynamic key lookup: <code class="computeroutput">[lang::util::localize $var_with_embedded_message_keys]</code> - In this case the message keys in the variable <code class="computeroutput">var_with_embedded_message_keys</code> must appear as string literals <code class="computeroutput">\#package_key.message_key\#</code> somewhere in the code. Here is an example of a dynamic lookup: <code class="computeroutput">set message_key_array { dynamic_key_1 \#package_key.message_key1\# @@ -98,13 +150,17 @@ set my_text [lang::util::localize $message_key_array([get_dynamic_key])] </code> - </p></li></ul></div><p> - </p><p> + </p> + </li></ul></div><p> + </p> + + <p> Translatable texts in page Tcl scripts are often found in page titles, 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: - </p><pre class="screen"> + </p> + <pre class="screen"> # Find text in double quotes <strong class="userinput"><code>find -iname '*.tcl'|xargs egrep -i '"[a-z]'</code></strong> @@ -117,20 +173,26 @@ # Find text in error messages <strong class="userinput"><code>find -iname '*.tcl'|xargs egrep -i '(ad_complain|ad_return_error)'|egrep -v '<#'</code></strong> - </pre><p> + </pre> + <p> 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 variables and or procedure calls in it you should in most cases try to turn the whole text into one message in the catalog (remember that translators is made easier the longer the phrases to translate are). In those cases, follow these steps: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> For each message call in the text, decide on a variable name and replace the procedure call with a variable lookup on the syntax %var_name%. Remember to initialize a Tcl variable with the same name on some line above the text.</p></li><li class="listitem"><p>If the text is in a Tcl file you must replace variable lookups (occurrences of $var_name or ${var_name}) with %var_name%</p></li><li class="listitem"><p>You are now ready to follow the normal procedure and mark up the text using a tempoarary message tag (<#_ text_with_percentage_vars#>) and run the action - replace tags with keys in the APM.</p></li></ul></div><p> + replace tags with keys in the APM.</p></li></ul></div> + + <p> The variable values in the message are usually fetched with upvar, here is an example from dotlrn: <code class="computeroutput"> ad_return_complaint 1 "Error: A [parameter::get -parameter classes_pretty_name] @@ -143,20 +205,31 @@ ad_return_complaint 1 [_ dotlrn.class_may_not_be_deleted] </code> - </p><p> + </p> + + + <p> This kind of interpolation also works in adp files where adp variable values will be inserted into the message. - </p><p> + </p> + + <p> Alternatively, you may pass in an array list of the variable values to be interpolated into the message so that our example becomes: - </p><pre class="screen"> + </p> + +<pre class="screen"> <strong class="userinput"><code>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] </code></strong> -</pre><p> +</pre> + + <p> When we were done going through the Tcl files we ran the following commands to check for mistakes: - </p><pre class="screen"> + </p> + +<pre class="screen"> # 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) @@ -167,14 +240,22 @@ # Review the list of Tcl files with no message lookups <strong class="userinput"><code>for tcl_file in $(find -iname '*.tcl'); do egrep -L '(<#|\[_)' $tcl_file; done</code></strong> -</pre><p> +</pre> + + <p> When you feel ready you may vist your package in the <a class="ulink" href="/acs-admin/apm" target="_top">package manager</a> 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. - </p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="i18n-date-time-number"></a>Dates, Times, and Numbers in Tcl files</h5></div></div></div><p> + </p> + + <div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="i18n-date-time-number"></a>Dates, Times, and Numbers in Tcl files</h5></div></div></div> + + + + <p> 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 @@ -184,30 +265,62 @@ <code class="computeroutput">lang::system::timezone.</code>. When retrieved from the database and displayed, dates and times must be localized to the user's locale. - </p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-apm-params"></a>APM Parameters</h4></div></div></div><p> + </p> + </div> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="i18n-message-apm-params"></a>APM Parameters</h4></div></div></div> + + + + <p> Some parameters contain text that need to be localized. In this case, instead of storing the real text in the parameter, you should use message keys using the short notation above, i.e. <span class="strong"><strong>#<span class="emphasis"><em>package_key.message_key</em></span>#</strong></span>. - </p><p> + </p> + + <p> In order to avoid clashes with other uses of the hash character, you need to tell the APM that the parameter value needs to be localized when retrieving it. You do that by saying: <span class="strong"><strong>parameter::get -localize</strong></span>. - </p><p> + </p> + + <p> Here are a couple of examples. Say we have the following two parameters, taken directly from the dotlrn package. - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col class="c1"><col class="c2"></colgroup><thead><tr><th>Parameter Name</th><th>Parameter Value</th></tr></thead><tbody><tr><td>class_instance_pages_csv</td><td><code class="computeroutput">#<span class="replaceable"><span class="replaceable">dotlrn.class_page_home_title</span></span>#</code>,Simple 2-Column;<code class="computeroutput">#<span class="replaceable"><span class="replaceable">dotlrn.class_page_calendar_title</span></span>#</code>,Simple 1-Column;<code class="computeroutput">#<span class="replaceable"><span class="replaceable">dotlrn.class_page_file_storage_title</span></span>#</code>,Simple 1-Column</td></tr><tr><td>departments_pretty_name</td><td><code class="computeroutput">#<span class="replaceable"><span class="replaceable">departments_pretty_name</span></span>#</code></td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col class="c1"><col class="c2"></colgroup><thead><tr><th>Parameter Name</th><th>Parameter Value</th></tr></thead><tbody><tr><td>class_instance_pages_csv</td><td><code class="computeroutput">#<em class="replaceable"><code>dotlrn.class_page_home_title</code></em>#</code>,Simple 2-Column;<code class="computeroutput">#<em class="replaceable"><code>dotlrn.class_page_calendar_title</code></em>#</code>,Simple 1-Column;<code class="computeroutput">#<em class="replaceable"><code>dotlrn.class_page_file_storage_title</code></em>#</code>,Simple 1-Column</td></tr><tr><td>departments_pretty_name</td><td><code class="computeroutput">#<em class="replaceable"><code>departments_pretty_name</code></em>#</code></td></tr></tbody></table> + </div> + + <p> Then, depending on how we retrieve the value, here's what we get: - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col class="c1"><col class="c2"></colgroup><thead><tr><th>Command used to retrieve Value</th><th>Retrieved Value</th></tr></thead><tbody><tr><td>parameter::get <span class="strong"><strong>-localize</strong></span> -parameter class_instances_pages_csv</td><td>Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column</td></tr><tr><td>parameter::get <span class="strong"><strong>-localize</strong></span> -parameter departments_pretty_name</td><td>Abteilung</td></tr><tr><td>parameter::get -parameter departments_pretty_name</td><td><code class="computeroutput">#<span class="replaceable"><span class="replaceable">departments_pretty_name</span></span>#</code></td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col class="c1"><col class="c2"></colgroup><thead><tr><th>Command used to retrieve Value</th><th>Retrieved Value</th></tr></thead><tbody><tr><td>parameter::get <span class="strong"><strong>-localize</strong></span> -parameter class_instances_pages_csv</td><td>Kurs Startseite,Simple 2-Column;Kalender,Simple 1-Column;Dateien,Simple 1-Column</td></tr><tr><td>parameter::get <span class="strong"><strong>-localize</strong></span> -parameter departments_pretty_name</td><td>Abteilung</td></tr><tr><td>parameter::get -parameter departments_pretty_name</td><td><code class="computeroutput">#<em class="replaceable"><code>departments_pretty_name</code></em>#</code></td></tr></tbody></table> + </div> + + <p> The value in the rightmost column in the table above is the value returned by an invocation of parameter::get. Note that for localization to happen you must use the -localize flag. - </p><p> + </p> + + <p> The locale used for the message lookup will be the locale of the current request, i.e. lang::conn::locale or ad_conn locale. - </p><p> + </p> + + <p> Developers are responsible for creating the keys in the message catalog, which is available at <code class="computeroutput">/acs-lang/admin/</code> - </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-convert.html">Next</a></td></tr><tr><td width="40%" align="left">Internationalization and Localization Overview </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> How to Internationalize a Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + </div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-convert.html">Next</a></td></tr><tr><td width="40%" align="left">Internationalization and Localization Overview </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> How to Internationalize a Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> 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 -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/i18n-overview.html 7 Aug 2017 23:47:50 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/i18n-overview.html 8 Nov 2017 09:42:10 -0000 1.18 @@ -1,2 +1,8 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Internationalization and Localization Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n.html" title="Chapter 14. Internationalization"><link rel="next" href="i18n-introduction.html" title="How Internationalization/Localization works in OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-introduction.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-overview"></a>Internationalization and Localization Overview</h2></div></div></div><div class="table"><a name="i18n-l10n-process"></a><p class="title"><b>Table 14.1. Internationalization and Localization Overview</b></p><div class="table-contents"><table class="table" summary="Internationalization and Localization Overview" cellspacing="0" border="1"><colgroup><col class="step"><col class="description"><col class="who"></colgroup><thead><tr><th>Stage</th><th>Task</th><th>Who</th></tr></thead><tbody><tr><td>Internationalization</td><td>Package Developer uses the acs-lang tools to replace all visible text in a package with <span class="emphasis"><em>message keys</em></span>. (<a class="link" href="i18n-introduction.html" title="How Internationalization/Localization works in OpenACS">More information</a>)</td><td>Package Developer</td></tr><tr><td rowspan="2">Release Management</td><td>The newly internationalized package is released.</td><td>Package Developer</td></tr><tr><td>The translation server is updated with the new package.</td><td>Translation server maintainers</td></tr><tr><td>Localization</td><td>Translators work in their respective locales to write text for each message key. (<a class="link" href="i18n-translators.html" title="Translator's Guide">More information</a>)</td><td>Translators</td></tr><tr><td rowspan="3">Release Management</td><td>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.</td><td>Translation server maintainers</td></tr><tr><td>The catalog files are committed to the OpenACS code base.</td><td>Translation server maintainers</td></tr><tr><td>A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.</td><td>Release Manager</td></tr><tr><td rowspan="2">Upgrading</td><td>Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS </td><td>Site Administrators</td></tr><tr><td>Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.</td><td>Site Administrators</td></tr></tbody></table></div></div><br class="table-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-introduction.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 14. Internationalization </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> How Internationalization/Localization works in OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Internationalization and Localization Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n.html" title="Chapter 14. Internationalization"><link rel="next" href="i18n-introduction.html" title="How Internationalization/Localization works in OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="i18n-introduction.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-overview"></a>Internationalization and Localization Overview</h2></div></div></div> + + <div class="table"><a name="i18n-l10n-process"></a><p class="title"><b>Table 14.1. Internationalization and Localization Overview</b></p><div class="table-contents"> + + <table class="table" summary="Internationalization and Localization Overview" cellspacing="0" border="1"><colgroup><col class="step"><col class="description"><col class="who"></colgroup><thead><tr><th>Stage</th><th>Task</th><th>Who</th></tr></thead><tbody><tr><td>Internationalization</td><td>Package Developer uses the acs-lang tools to replace all visible text in a package with <span class="emphasis"><em>message keys</em></span>. (<a class="link" href="i18n-introduction.html" title="How Internationalization/Localization works in OpenACS">More information</a>)</td><td>Package Developer</td></tr><tr><td rowspan="2">Release Management</td><td>The newly internationalized package is released.</td><td>Package Developer</td></tr><tr><td>The translation server is updated with the new package.</td><td>Translation server maintainers</td></tr><tr><td>Localization</td><td>Translators work in their respective locales to write text for each message key. (<a class="link" href="i18n-translators.html" title="Translator's Guide">More information</a>)</td><td>Translators</td></tr><tr><td rowspan="3">Release Management</td><td>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.</td><td>Translation server maintainers</td></tr><tr><td>The catalog files are committed to the OpenACS code base.</td><td>Translation server maintainers</td></tr><tr><td>A new version of OpenACS core and/or affected packages is released and published in the OpenACS.org repository.</td><td>Release Manager</td></tr><tr><td rowspan="2">Upgrading</td><td>Site Administrators upgrade their OpenACS sites, either via the automatic upgrade from the Repository or via tarball or CVS </td><td>Site Administrators</td></tr><tr><td>Site Administrators import the new translations. Existing local translations, if they exist, are not overwritten.</td><td>Site Administrators</td></tr></tbody></table> + </div></div><br class="table-break"> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-introduction.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 14. Internationalization </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> How Internationalization/Localization works in OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,12 +10,9 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="i18n-requirements" id="i18n-requirements"></a>OpenACS Internationalization -Requirements</h2></div></div></div><div class="authorblurb"> -<p>by Henry Minsky, <a class="ulink" href="mailto:yon\@openforce.net" target="_top">Yon Feldman</a>, <a class="ulink" href="mailto:lars\@collaboraid.biz" target="_top">Lars +Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by Henry Minsky, <a class="ulink" href="mailto:yon\@openforce.net" target="_top">Yon Feldman</a>, <a class="ulink" href="mailto:lars\@collaboraid.biz" target="_top">Lars Pind</a>, <a class="ulink" href="mailto:peter\@collaboraid.biz" target="_top">Peter Marklund</a>, <a class="ulink" href="mailto:christian\@collaboraid.biz" target="_top">Christian -Hvid</a>, and others.</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +Hvid</a>, and others.</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="i18n-requirements-introduction" id="i18n-requirements-introduction"></a>Introduction</h3></div></div></div><p>This document describes the requirements for functionality in the OpenACS platform to support globalization of the core and Index: openacs-4/packages/acs-core-docs/www/i18n-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-requirements.html,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/i18n-requirements.html 7 Aug 2017 23:47:50 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/i18n-requirements.html 8 Nov 2017 09:42:10 -0000 1.28 @@ -1,286 +1,662 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Internationalization Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="db-api-detailed.html" title="Database Access API"><link rel="next" href="security-requirements.html" title="Security Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-requirements"></a>OpenACS Internationalization Requirements</h2></div></div></div><div class="authorblurb"><p>by Henry Minsky, +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Internationalization Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="db-api-detailed.html" title="Database Access API"><link rel="next" href="security-requirements.html" title="Security Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-requirements"></a>OpenACS Internationalization Requirements</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by Henry Minsky, <a class="ulink" href="mailto:yon@openforce.net" target="_top">Yon Feldman</a>, <a class="ulink" href="mailto:lars@collaboraid.biz" target="_top">Lars Pind</a>, <a class="ulink" href="mailto:peter@collaboraid.biz" target="_top">Peter Marklund</a>, <a class="ulink" href="mailto:christian@collaboraid.biz" target="_top">Christian Hvid</a>, and others.</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-introduction"></a>Introduction</h3></div></div></div><p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-introduction"></a>Introduction</h3></div></div></div> + + + <p> This document describes the requirements for functionality in the OpenACS platform to support globalization of the core and optional modules. The goal is to make it possible to support delivery of applications which work properly in multiple locales with the lowest development and maintenance cost. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-definitions"></a>Definitions</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">internationalization (i18n)</span></dt><dd><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-definitions"></a>Definitions</h3></div></div></div> + + + <div class="variablelist"><dl class="variablelist"><dt><span class="term">internationalization (i18n)</span></dt><dd> + <p> The provision within a computer program of the capability of making itself adaptable to the requirements of different native languages, local customs and coded character sets. - </p></dd><dt><span class="term">locale</span></dt><dd><p> + </p> + </dd><dt><span class="term">locale</span></dt><dd> + <p> The definition of the subset of a user's environment that depends on language and cultural conventions. - </p></dd><dt><span class="term">localization (L10n)</span></dt><dd><p> + </p> + </dd><dt><span class="term">localization (L10n)</span></dt><dd> + <p> The process of establishing information within a computer system specific to the operation of particular native languages, local customs and coded character sets. - </p></dd><dt><span class="term">globalization</span></dt><dd><p> + </p> + </dd><dt><span class="term">globalization</span></dt><dd> + <p> A product development approach which ensures that software products are usable in the worldwide markets through a combination of internationalization and localization. - </p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="II._Vision_Statement"></a>Vision Statement</h3></div></div></div><p>The Mozilla project suggests keeping two catchy phrases in -mind when thinking about globalization:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>One code base for the world</p></li><li class="listitem"><p>English is just another language</p></li></ul></div><p>Building an application often involves making a number of + </p> + </dd></dl></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="II._Vision_Statement"></a>Vision Statement</h3></div></div></div> + + +<p>The Mozilla project suggests keeping two catchy phrases in +mind when thinking about globalization:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p>One code base for the world</p> +</li><li class="listitem"> +<p>English is just another language</p> +</li></ul></div> + +<p>Building an application often involves making a number of assumptions on the part of the developers which depend on their own culture. These include constant strings in the user interface and system error messages, names of countries, cities, order of given and family names for people, syntax of numeric and date strings and -collation order of strings.</p><p>The OpenACS should be able to operate in languages and regions +collation order of strings.</p> + +<p>The OpenACS should be able to operate in languages and regions beyond US English. The goal of OpenACS Globalization is to provide a clean and efficient way to factor out the locale dependent functionality from our applications, in order to be able to easily -swap in alternate localizations.</p><p>This in turn will reduce redundant, costly, and error prone +swap in alternate localizations.</p> + +<p>This in turn will reduce redundant, costly, and error prone rework when targeting the toolkit or applications built with the -toolkit to another locale.</p><p>The cost of porting the OpenACS to another locale without some +toolkit to another locale.</p> + +<p>The cost of porting the OpenACS to another locale without some kind of globalization support would be large and ongoing, since without a mechanism to incorporate the locale-specific changes cleanly back into the code base, it would require making a new fork -of the source code for each locale.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="system-application-overview"></a>System/Application Overview</h3></div></div></div><p>A globalized application will perform some or all of the +of the source code for each locale.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="system-application-overview"></a>System/Application Overview</h3></div></div></div> + + + +<p>A globalized application will perform some or all of the following steps to handle a page request for a specific -locale:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Decide what the target locale is for an incoming page -request</p></li><li class="listitem"><p>Decide which character set encoding the output should be -delivered in</p></li><li class="listitem"><p>If a script file to handle the request needs to be loaded +locale:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> +<p>Decide what the target locale is for an incoming page +request</p> +</li><li class="listitem"> +<p>Decide which character set encoding the output should be +delivered in</p> +</li><li class="listitem"> +<p>If a script file to handle the request needs to be loaded from disk, determine if a character set conversion needs to be -performed when loading the script</p></li><li class="listitem"><p>If needed, locale-specific resources are fetched. These can +performed when loading the script</p> +</li><li class="listitem"> +<p>If needed, locale-specific resources are fetched. These can include text, graphics, or other resources that would vary with the -target locale.</p></li><li class="listitem"><p>If content data is fetched from the database, check for -locale-specific versions of the data (e.g. country names).</p></li><li class="listitem"><p>Source code should use a message catalog API to translate -constant strings in the code to the target locale</p></li><li class="listitem"><p>Perform locale-specific linguistic sorting on data if -needed</p></li><li class="listitem"><p>If the user submitted form input data, decide what character +target locale.</p> +</li><li class="listitem"> +<p>If content data is fetched from the database, check for +locale-specific versions of the data (e.g. country names).</p> +</li><li class="listitem"> +<p>Source code should use a message catalog API to translate +constant strings in the code to the target locale</p> +</li><li class="listitem"> +<p>Perform locale-specific linguistic sorting on data if +needed</p> +</li><li class="listitem"> +<p>If the user submitted form input data, decide what character set encoding conversion if any is needed. Parse locale-specific -quantities if needed (number formats, date formats).</p></li><li class="listitem"><p>If templating is being used, select correct locale-specific -template to merge with content</p></li><li class="listitem"><p>Format output data quantities in locale-specific manner +quantities if needed (number formats, date formats).</p> +</li><li class="listitem"> +<p>If templating is being used, select correct locale-specific +template to merge with content</p> +</li><li class="listitem"> +<p>Format output data quantities in locale-specific manner (date, time, numeric, currency). If templating is being used, this may be done either before and/or after merging the data with a -template.</p></li></ol></div><p>Since the internationalization APIs may potentially be used +template.</p> +</li></ol></div> + +<p>Since the internationalization APIs may potentially be used on every page in an application, the overhead for adding internationalization to a module or application must not cause a -significant time delay in handling page requests.</p><p>In many cases there are facilities in Oracle to perform +significant time delay in handling page requests.</p> + +<p>In many cases there are facilities in Oracle to perform various localization functions, and also there are facilities in Java which we will want to move to. So the design to meet the requirements will tend to rely on these capabilities, or close approximations to them where possible, in order to make it easier -to maintain Tcl and Java OpenACS versions.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="IV._Use-cases_and_User-scenarios"></a>Use-cases and User-scenarios</h3></div></div></div><p>Here are the cases that we need to be able to handle -efficiently:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>A developer needs to author a web site/application in a +to maintain Tcl and Java OpenACS versions.</p> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="IV._Use-cases_and_User-scenarios"></a>Use-cases and User-scenarios</h3></div></div></div> + +<p>Here are the cases that we need to be able to handle +efficiently:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> +<p>A developer needs to author a web site/application in a language besides English, and possibly a character set besides ISO-8859-1. This includes the operation of the OpenACS itself, i.e., navigation, admin pages for modules, error messages, as well as additional modules or content supplied by the web site -developer.</p><p>What do they need to modify to make this work? Can their +developer.</p> + +<p>What do they need to modify to make this work? Can their localization work be easily folded in to future releases of -OpenACS?</p></li><li class="listitem"><p>A developer needs to author a web site which operates in +OpenACS?</p> +</li><li class="listitem"> +<p>A developer needs to author a web site which operates in multiple languages simultaneously. For example, www.un.org with -content and navigation in multiple languages.</p><p>The site would have an end-user visible UI to support these +content and navigation in multiple languages.</p> + +<p>The site would have an end-user visible UI to support these languages, and the content management system must allow articles to be posted in these languages. In some cases it may be necessary to make the modules' admin UI's operate in more than one supported language, while in other cases the backend admin -interface can operate in a single language.</p></li><li class="listitem"><p>A developer is writing a new module, and wants to make it +interface can operate in a single language.</p> +</li><li class="listitem"> +<p>A developer is writing a new module, and wants to make it easy for someone to localize it. There should be a clear path to author the module so that future developers can easily add support for other locales. This would include support for creating resources such as message catalogs, non-text assets such as graphics, and use of templates which help to separate application -logic from presentation.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Competitive_Analysis"></a>Competitive -Analysis</h3></div></div></div><p>Other application servers: ATG Dyanmo, Broadvision, Vignette, -... ? Anyone know how they deal with i18n ?</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="V._Related_Links"></a>Related -Links</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>System/Package "coversheet" - where all -documentation for this software is linked off of</em></span></p></li><li class="listitem"><p><span class="emphasis"><em><a class="link" href="i18n-design.html" title="Design Notes">Design document</a></em></span></p></li><li class="listitem"><p><span class="emphasis"><em><a class="link" href="i18n.html" title="Chapter 14. Internationalization">Developer's guide</a></em></span></p></li><li class="listitem"><p><span class="emphasis"><em>User's guide</em></span></p></li><li class="listitem"><p><span class="emphasis"><em>Other-cool-system-related-to-this-one -document</em></span></p><p><a class="ulink" href="http://www.li18nux.net/" target="_top">LI18NUX +logic from presentation.</p> +</li></ol></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="Competitive_Analysis"></a>Competitive +Analysis</h3></div></div></div> + +<p>Other application servers: ATG Dyanmo, Broadvision, Vignette, +... ? Anyone know how they deal with i18n ?</p> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="V._Related_Links"></a>Related +Links</h3></div></div></div> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p><span class="emphasis"><em>System/Package "coversheet" - where all +documentation for this software is linked off of</em></span></p> +</li><li class="listitem"> + <p><span class="emphasis"><em><a class="link" href="i18n-design.html" title="Design Notes">Design document</a></em></span></p> + </li><li class="listitem"> + <p><span class="emphasis"><em><a class="link" href="i18n.html" title="Chapter 14. Internationalization">Developer's guide</a></em></span></p> + </li><li class="listitem"> + <p><span class="emphasis"><em>User's guide</em></span></p> + </li><li class="listitem"> + <p><span class="emphasis"><em>Other-cool-system-related-to-this-one +document</em></span></p> +<p><a class="ulink" href="http://www.li18nux.net/" target="_top">LI18NUX 2000 Globalization Specification: -http://www.li18nux.net/</a></p><p><a class="ulink" href="http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html" target="_top">Mozilla +http://www.li18nux.net/</a></p> + +<p><a class="ulink" href="http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html" target="_top">Mozilla i18N Guidelines: -http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html</a></p><p><a class="ulink" href="https://www.iso.org/standard/4766.html" target="_top">ISO +http://www.mozilla.org/docs/refList/i18n/l12yGuidelines.html</a></p> + +<p><a class="ulink" href="https://www.iso.org/standard/4766.html" target="_top">ISO 639:1988 Code for the representation of names of languages -</a></p><p><a class="ulink" href="https://www.iso.org/standard/24591.html" target="_top">ISO 3166-1:1997 +</a></p> + +<p><a class="ulink" href="https://www.iso.org/standard/24591.html" target="_top">ISO 3166-1:1997 Codes for the representation of names of countries and their subdivisions Part 1: Country codes -</a></p><p><a class="ulink" href="http://www.isi.edu/in-notes/iana/assignments/character-sets" target="_top">IANA -Registry of Character Sets</a></p></li><li class="listitem"><p><span class="emphasis"><em>Test plan</em></span></p></li><li class="listitem"><p><span class="emphasis"><em>Competitive system(s)</em></span></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI_Requirements"></a>Requirements</h3></div></div></div><p>Because the requirements for globalization affect many areas +</a></p> + +<p><a class="ulink" href="http://www.isi.edu/in-notes/iana/assignments/character-sets" target="_top">IANA +Registry of Character Sets</a></p> +</li><li class="listitem"> +<p><span class="emphasis"><em>Test plan</em></span></p> +</li><li class="listitem"> +<p><span class="emphasis"><em>Competitive system(s)</em></span></p> +</li></ul></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI_Requirements"></a>Requirements</h3></div></div></div> + +<p>Because the requirements for globalization affect many areas of the system, we will break up the requirements into phases, with a base required set of features, and then stages of increasing -functionality.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.A_Locales"></a>Locales</h3></div></div></div><p><span class="emphasis"><em>10.0</em></span></p><p>A standard representation of locale will be used throughout +functionality.</p> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.A_Locales"></a>Locales</h3></div></div></div> + +<p><span class="emphasis"><em>10.0</em></span></p> +<p>A standard representation of locale will be used throughout the system. A locale refers to a language and territory, and is uniquely identified by a combination of ISO language and ISO -country abbreviations.</p><div class="blockquote"><blockquote class="blockquote"><p>See +country abbreviations.</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p>See <a class="ulink" href="/doc/acs-content-repository/requirements.html#100-20" target="_top">Content -Repository Requirement 100.20</a></p><p><span class="emphasis"><em>10.10</em></span> Provide a consistent -representation and API for creating and referencing a locale</p><p><span class="emphasis"><em>10.20</em></span> There will be a Tcl library of +Repository Requirement 100.20</a></p> + +<p><span class="emphasis"><em>10.10</em></span> Provide a consistent +representation and API for creating and referencing a locale</p> + +<p><span class="emphasis"><em>10.20</em></span> There will be a Tcl library of locale-aware formatting and parsing functions for numbers, dates and times. <span class="emphasis"><em>Note that Java has builtin support for these -already</em></span>.</p><p><span class="emphasis"><em>10.30</em></span> For each locale there will be +already</em></span>.</p> + +<p><span class="emphasis"><em>10.30</em></span> For each locale there will be default date, number and currency formats. <em><span class="remark">Currency i18n is -NOT IMPLEMENTED for 5.0.0.</span></em></p><p><span class="emphasis"><em>10.40</em></span>Administrators can upgrade their +NOT IMPLEMENTED for 5.0.0.</span></em></p> + + <p><span class="emphasis"><em>10.40</em></span>Administrators can upgrade their servers to use new locales via the APM. <em><span class="remark">NOT IMPLEMENTED in 5.0.0; current workaround is to get an xml file and load it -manually.</span></em></p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.B_Associating_a_Locale_with_a_Request"></a>Associating a Locale with a Request</h3></div></div></div><p><span class="emphasis"><em>20.0</em></span></p><p>The request processor must have a mechanism for associating a +manually.</span></em></p> + + +</blockquote></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.B_Associating_a_Locale_with_a_Request"></a>Associating a Locale with a Request</h3></div></div></div> + +<p><span class="emphasis"><em>20.0</em></span></p> +<p>The request processor must have a mechanism for associating a locale with each request. This locale is then used to select the appropriate template for a request, and will also be passed as the locale argument to the message catalog or locale-specific -formatting functions.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>20.10</em></span> The locale for a request should be +formatting functions.</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>20.10</em></span> The locale for a request should be computed by the following method, in descending order of -priority:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>get locale associated with subsite or package id</p></li><li class="listitem"><p>get locale from user preference</p></li><li class="listitem"><p>get locale from site wide default</p><p><span class="emphasis"><em>20.20</em></span> An API will be provided for +priority:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p>get locale associated with subsite or package id</p> +</li><li class="listitem"> +<p>get locale from user preference</p> +</li><li class="listitem"> +<p>get locale from site wide default</p> + +<p><span class="emphasis"><em>20.20</em></span> An API will be provided for getting the current request locale from the -<code class="literal">ad_conn</code> structure.</p></li></ul></div></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="resource-bundles"></a>Resource Bundles / Content Repository</h3></div></div></div><p><span class="emphasis"><em>30.0</em></span></p><p>A mechanism must be provided for a developer to group a set +<code class="literal">ad_conn</code> structure.</p> +</li></ul></div> +</blockquote></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="resource-bundles"></a>Resource Bundles / Content Repository</h3></div></div></div> + + + +<p><span class="emphasis"><em>30.0</em></span></p> +<p>A mechanism must be provided for a developer to group a set of arbitrary content resources together, keyed by a unique -identifier and a locale.</p><p>For example, what approaches could be used to implement a +identifier and a locale.</p> + +<p>For example, what approaches could be used to implement a localizable nav-bar mechanism for a site? A navigation bar might be made up of a set of text strings and graphics, where the graphics themselves are locale-specific, such as images of English or Japanese text (as on www.un.org). It should be easy to specify alternate configurations of text and graphics to lay out -the page for different locales.</p><p>Design note: Alternative mechanisms to implement this +the page for different locales.</p> + +<p>Design note: Alternative mechanisms to implement this functionality might include using templates, Java ResourceBundles, content-item containers in the Content Repository, or some convention assigning a common prefix to key strings in the message -catalog.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.D_Message_Catalog_for_String_Translation"></a>Message Catalog for String Translation</h3></div></div></div><p><span class="emphasis"><em>40.0</em></span></p><p>A message catalog facility will provide a database of +catalog.</p> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.D_Message_Catalog_for_String_Translation"></a>Message Catalog for String Translation</h3></div></div></div> + +<p><span class="emphasis"><em>40.0</em></span></p> +<p>A message catalog facility will provide a database of translations for constant strings for multilingual applications. It -must support the following:</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>40.10</em></span> Each message will referenced via -unique a key.</p><p><span class="emphasis"><em>40.20</em></span> The key for a message will have +must support the following:</p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>40.10</em></span> Each message will referenced via +unique a key.</p> + +<p><span class="emphasis"><em>40.20</em></span> The key for a message will have some hierarchical structure to it, so that sets of messages can be -grouped with respect to a module name or package path.</p><p><span class="emphasis"><em>40.30</em></span> The API for lookup of a message +grouped with respect to a module name or package path.</p> + +<p><span class="emphasis"><em>40.30</em></span> The API for lookup of a message will take a locale and message key as arguments, and return the appropriate translation of that message for the specifed -locale.</p><p><span class="emphasis"><em>40.40</em></span> The API for lookup of a message +locale.</p> + +<p><span class="emphasis"><em>40.40</em></span> The API for lookup of a message will accept an optional default string which can be used if the message key is not found in the catalog. This lets the developer get code working and tested in a single language before having to -initialize or update a message catalog.</p><p><span class="emphasis"><em>40.50</em></span> For use within templates, custom -tags which invoke the message lookup API will be provided.</p><p><span class="emphasis"><em>40.60</em></span> Provide a method for importing and +initialize or update a message catalog.</p> + +<p><span class="emphasis"><em>40.50</em></span> For use within templates, custom +tags which invoke the message lookup API will be provided.</p> + +<p><span class="emphasis"><em>40.60</em></span> Provide a method for importing and exporting a flat file of translation strings, in order to make it as easy as possible to create and modify message translations in -bulk without having to use a web interface.</p><p><span class="emphasis"><em>40.70</em></span> Since translations may be in +bulk without having to use a web interface.</p> + +<p><span class="emphasis"><em>40.70</em></span> Since translations may be in different character sets, there must be provision for writing and reading catalog files in different character sets. A mechanism must exist for identifying the character set of a catalog file before -reading it.</p><p><span class="emphasis"><em>40.80</em></span> There should be a mechanism for +reading it.</p> + +<p><span class="emphasis"><em>40.80</em></span> There should be a mechanism for tracking dependencies in the message catalog, so that if a string is modified, the other translations of that string can be flagged -as needing update.</p><p><span class="emphasis"><em>40.90</em></span> The message lookup must be as +as needing update.</p> + +<p><span class="emphasis"><em>40.90</em></span> The message lookup must be as efficient as possible so as not to slow down the delivery of -pages.</p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.E_Character_Set_Encoding"></a>Character Set Encoding</h3></div></div></div><p><span class="emphasis"><em>Character Sets</em></span></p><p><span class="emphasis"><em>50.0</em></span> A locale will have a primary +pages.</p> + +</blockquote></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.E_Character_Set_Encoding"></a>Character Set Encoding</h3></div></div></div> + +<p><span class="emphasis"><em>Character Sets</em></span></p> +<p><span class="emphasis"><em>50.0</em></span> A locale will have a primary associated character set which is used to encode text in the language. When given a locale, we can query the system for the -associated character set to use.</p><p>The assumption is that we are going to use Unicode in our +associated character set to use.</p> + +<p>The assumption is that we are going to use Unicode in our database to hold all text data. Our current programming environments (Tcl/Oracle or Java/Oracle) operate on Unicode data internally. However, since Unicode is not yet commonly used in browsers and authoring tools, the system must be able to read and write other character sets. In particular, conversions to and from Unicode will need to be explicitly performed at the following -times:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Loading source files (.tcl or .adp) or content files from the -filesystem</p></li><li class="listitem"><p>Accepting form input data from users</p></li><li class="listitem"><p>Delivering text output to a browser</p></li><li class="listitem"><p>Composing an email message</p></li><li class="listitem"><p>Writing data to the filesystem</p></li></ul></div><p>Acs-templating does the following.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>When the acs-templating package opens an an ADP or Tcl file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. -Writing Files</p></li><li class="listitem"><p>When the acs-templating package writes an an ADP or +times:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p>Loading source files (.tcl or .adp) or content files from the +filesystem</p> +</li><li class="listitem"> +<p>Accepting form input data from users</p> +</li><li class="listitem"> +<p>Delivering text output to a browser</p> +</li><li class="listitem"> +<p>Composing an email message</p> +</li><li class="listitem"> +<p>Writing data to the filesystem</p> +</li></ul></div> +<p>Acs-templating does the following.</p> +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>When the acs-templating package opens an an ADP or Tcl file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, then acs-templating assumes it's that charset. +Writing Files</p> + </li><li class="listitem"> + <p>When the acs-templating package writes an an ADP or Tcl file, it assumes the file is iso-8859-1. If the output charset (OutputCharset) in the AOLserver config file is set, - then acs-templating assumes it's that charset. </p></li></ul></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Tcl_Source_File_Character_Set"></a>Tcl Source File Character Set</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"><p>There are two classes of Tcl files loaded by the system; + then acs-templating assumes it's that charset. </p> + </li></ul></div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Tcl_Source_File_Character_Set"></a>Tcl Source File Character Set</h4></div></div></div> + + <div class="blockquote"><blockquote class="blockquote"> + + <p>There are two classes of Tcl files loaded by the system; library files loaded at server startup, and page script files, - which are run on each page request.</p><p><span class="emphasis"><em>Should we require all Tcl files be stored as UTF8? - That seems too much of a burden on developers.</em></span></p><p><span class="emphasis"><em>50.10</em></span> Tcl library files can be authored + which are run on each page request.</p> + + <p><span class="emphasis"><em>Should we require all Tcl files be stored as UTF8? + That seems too much of a burden on developers.</em></span></p> + + <p><span class="emphasis"><em>50.10</em></span> Tcl library files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from the - filename.</p><p><span class="emphasis"><em>50.20</em></span> Tcl page script files can be + filename.</p> + + <p><span class="emphasis"><em>50.20</em></span> Tcl page script files can be authored in any character set. The system must have a way to determine the character set before loading the files, probably from - the filename.</p></blockquote></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Submitted_Form_Data_Character_Set"></a>Submitted Form Data Character Set</h4></div></div></div><p><span class="emphasis"><em>50.30</em></span> Data which is submitted with a + the filename.</p> + </blockquote></div> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Submitted_Form_Data_Character_Set"></a>Submitted Form Data Character Set</h4></div></div></div> + + + <p><span class="emphasis"><em>50.30</em></span> Data which is submitted with a HTTP request using a GET or POST method may be in any character set. The system must be able to determine the encoding of the form - data and convert it to Unicode on demand. </p><p><span class="emphasis"><em>50.35</em></span> The developer must be able to + data and convert it to Unicode on demand. </p> + + <p><span class="emphasis"><em>50.35</em></span> The developer must be able to override the default system choice of character set when parsing and validating user form data. <em><span class="remark">INCOMPLETE - form widgets in acs-templating/tcl/date-procs.tcl are not internationalized. Also, acs-templating's UI needs to be internationalized by replacing all user-visible strings with - message keys.</span></em></p><p><span class="emphasis"><em>50.30.10</em></span>In Japan and some + message keys.</span></em></p> + + + <p><span class="emphasis"><em>50.30.10</em></span>In Japan and some other Asian languages where there are multiple character set encodings in common use, the server may need to attempt to do an auto-detection of the character set, because buggy browsers may - submit form data in an unexpected alternate encoding.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Output_Character_Set"></a>Output Character Set</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>50.40</em></span> The output character set for a + submit form data in an unexpected alternate encoding.</p> + </div> + + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Output_Character_Set"></a>Output Character Set</h4></div></div></div> + + + <div class="blockquote"><blockquote class="blockquote"> + <p><span class="emphasis"><em>50.40</em></span> The output character set for a page request will be determined by default by the locale associated - with the request (see requirement 20.0).</p><p><span class="emphasis"><em>50.50</em></span> It must be possible for a + with the request (see requirement 20.0).</p> + + <p><span class="emphasis"><em>50.50</em></span> It must be possible for a developer to manually override the output character set encoding for a request using an API function. - </p></blockquote></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.F_ACS_Kernel_Issues"></a>ACS Kernel Issues</h3></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>60.10</em></span> All OpenACS error messages must use + </p> + + </blockquote></div> + + </div> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.F_ACS_Kernel_Issues"></a>ACS Kernel Issues</h3></div></div></div> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>60.10</em></span> All OpenACS error messages must use the message catalog and the request locale to generate error -message for the appropriate locale.<em><span class="remark">NOT IMPLEMENTED for 5.0.0.</span></em></p><p><span class="emphasis"><em>60.20</em></span> Web server error messages such as +message for the appropriate locale.<em><span class="remark">NOT IMPLEMENTED for 5.0.0.</span></em></p> + +<p><span class="emphasis"><em>60.20</em></span> Web server error messages such as 404, 500, etc must also be delivered in the appropriate -locale.</p><p><span class="emphasis"><em>60.30</em></span> Where files are written or read +locale.</p> + +<p><span class="emphasis"><em>60.30</em></span> Where files are written or read from disk, their filenames must use a character set and character -values which are safe for the underlying operating system.</p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.G_Templates"></a>Templates</h3></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>70.0</em></span> For a given abstract URL, the +values which are safe for the underlying operating system.</p> +</blockquote></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.G_Templates"></a>Templates</h3></div></div></div> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>70.0</em></span> For a given abstract URL, the designer may create multiple locale-specific template files may be -created (one per locale or language)</p><p><span class="emphasis"><em>70.10</em></span> For a given page request, the +created (one per locale or language)</p> + +<p><span class="emphasis"><em>70.10</em></span> For a given page request, the system must be able to select an approprate locale-specific template file to use. The request locale is computed as per (see -requirement 20.0).</p><p><span class="emphasis"><em>70.20</em></span>A template file may be created for +requirement 20.0).</p> + +<p><span class="emphasis"><em>70.20</em></span>A template file may be created for a partial locale (language only, without a territory), and the request processor should be able to find the closest match for the -current request locale.</p><p><span class="emphasis"><em>70.30</em></span> A template file may be created in +current request locale.</p> + +<p><span class="emphasis"><em>70.30</em></span> A template file may be created in any character set. The system must have a way to know which character set a template file contains, so it can properly process -it.</p></blockquote></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Formatting_Datasource_Output_in_Templates"></a>Formatting -Datasource Output in Templates</h4></div></div></div><p><span class="emphasis"><em>70.50</em></span> The properties of a datasource +it.</p> +</blockquote></div> +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Formatting_Datasource_Output_in_Templates"></a>Formatting +Datasource Output in Templates</h4></div></div></div> + +<p><span class="emphasis"><em>70.50</em></span> The properties of a datasource column may include a datatype so that the templating system can format the output for the current locale. The datatype is defined by a standard OpenACS datatype plus a format token or format string, for example: a date column might be specified as 'current_date:date LONG,' or 'current_date:date -"YYYY-Mon-DD"'</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Forms"></a>Forms</h4></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>70.60</em></span> The forms API must support +"YYYY-Mon-DD"'</p> + +</div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Forms"></a>Forms</h4></div></div></div> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>70.60</em></span> The forms API must support construction of locale-specific HTML form widgets, such as date entry widgets, and form validation of user input data for locale-specific data, such as dates or numbers. <span class="emphasis"><em>NOT -IMPLEMENTED in 5.0.0.</em></span></p><p><span class="emphasis"><em>70.70</em></span> For forms which allow users to +IMPLEMENTED in 5.0.0.</em></span></p> + +<p><span class="emphasis"><em>70.70</em></span> For forms which allow users to upload files, a standard method for a user to indicate the charset -of a text file being uploaded must be provided.</p><p><span class="emphasis"><em>Design note: this presumably applies to uploading -data to the content repository as well</em></span></p></blockquote></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.H_Sorting_and_Searching"></a>Sorting and Searching</h3></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>80.10</em></span> Support API for correct collation -(sorting order) on lists of strings in locale-dependent way.</p><p><span class="emphasis"><em>80.20</em></span> For the Tcl API, we will say that +of a text file being uploaded must be provided.</p> + +<p><span class="emphasis"><em>Design note: this presumably applies to uploading +data to the content repository as well</em></span></p> +</blockquote></div> + +</div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.H_Sorting_and_Searching"></a>Sorting and Searching</h3></div></div></div> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>80.10</em></span> Support API for correct collation +(sorting order) on lists of strings in locale-dependent way.</p> + +<p><span class="emphasis"><em>80.20</em></span> For the Tcl API, we will say that locale-dependent sorting will use Oracle SQL operations (i.e., we won't provide a Tcl API for this). We require a Tcl API function to return the correct incantation of NLS_SORT to use for a given locale with <code class="literal">ORDER BY</code> clauses in -queries.</p><p><span class="emphasis"><em>80.40</em></span> The system must handle full-text -search in any supported language.</p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.G_Time_Zones"></a>Time Zones</h3></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>90.10</em></span> Provide API support for specifying -a time zone</p><p><span class="emphasis"><em>90.20</em></span> Provide an API for computing time +queries.</p> + +<p><span class="emphasis"><em>80.40</em></span> The system must handle full-text +search in any supported language.</p> +</blockquote></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.G_Time_Zones"></a>Time Zones</h3></div></div></div> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>90.10</em></span> Provide API support for specifying +a time zone</p> + +<p><span class="emphasis"><em>90.20</em></span> Provide an API for computing time and date operations which are aware of timezones. So for example a calendar module can properly synchronize items inserted into a calendar from users in different time zones using their own local -times.</p><p><span class="emphasis"><em>90.30</em></span> Store all dates and times in -universal time zone, UTC.</p><p><span class="emphasis"><em>90.40</em></span> For a registered users, a time -zone preference should be stored.</p><p><span class="emphasis"><em>90.50</em></span> For a non-registered user a time +times.</p> + +<p><span class="emphasis"><em>90.30</em></span> Store all dates and times in +universal time zone, UTC.</p> + +<p><span class="emphasis"><em>90.40</em></span> For a registered users, a time +zone preference should be stored.</p> + +<p><span class="emphasis"><em>90.50</em></span> For a non-registered user a time zone preference should be attached via a session or else UTC should -be used to display every date and time.</p><p><span class="emphasis"><em>90.60</em></span> The default if we can't +be used to display every date and time.</p> + +<p><span class="emphasis"><em>90.60</em></span> The default if we can't determine a time zone is to display all dates and times in some -universal time zone such as GMT.</p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.H_Database"></a>Database</h3></div></div></div><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>100.10</em></span> Since UTF8 strings can use up to +universal time zone such as GMT.</p> +</blockquote></div> + +</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.H_Database"></a>Database</h3></div></div></div> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="emphasis"><em>100.10</em></span> Since UTF8 strings can use up to three (UCS2) or six (UCS4) bytes per character, make sure that column size declarations in the schema are large enough to accommodate required data (such as email addresses in Japanese). <em><span class="remark">Since 5.0.0, this is covered in the database -install instructions for both PostgreSQL and Oracle.</span></em></p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.I_Email_and_Messaging"></a>Email and Messaging</h3></div></div></div><p>When sending an email message, just as when delivering the +install instructions for both PostgreSQL and Oracle.</span></em></p> +</blockquote></div> + +</div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="VI.I_Email_and_Messaging"></a>Email and Messaging</h3></div></div></div> + + + + <p>When sending an email message, just as when delivering the content in web page over an HTTP connection, it is necessary to be - able to specify what character set encoding to use, defaulting to UTF-8.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>110.10</em></span> The email message sending API - will allow for a character set encoding to be specified.</p><p><span class="emphasis"><em>110.20</em></span> The email accepting API + able to specify what character set encoding to use, defaulting to UTF-8.</p> + + <div class="blockquote"><blockquote class="blockquote"> + <p><span class="emphasis"><em>110.10</em></span> The email message sending API + will allow for a character set encoding to be specified.</p> + + <p><span class="emphasis"><em>110.20</em></span> The email accepting API allows for character set to be parsed correctly (the message has a MIME - character set content type header) </p></blockquote></div><p>Mail is not internationalized. The following issues must be addressed.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + character set content type header) </p> + </blockquote></div> + + <p>Mail is not internationalized. The following issues must be addressed.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Many functions still call ns_sendmail. This means that there are different end points for sending mail. This should be changed to use the acs-mail-lite API instead. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Consumers of email services must do the following: Determine the appropriate language or languages to use for the message subject and message body and localize them (as in notifications). - </p></li><li class="listitem"><p>Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?</p></li><li class="listitem"><p>Incoming mail should be localized.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-implementation-notes"></a>Implementation Notes</h3></div></div></div><p> + </p> + </li><li class="listitem"> + <p>Extreme Use case: Web site has a default language of Danish. A forum is set up for Swedes, so the forum has a package_id and a language setting of Swedish. A poster posts to the forum in Russian (is this possible?). A user is subscribed to the forum and has a language preference of Chinese. What should be in the message body and message subject?</p> + </li><li class="listitem"><p>Incoming mail should be localized.</p> + </li></ul></div> + + + + +</div> +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-implementation-notes"></a>Implementation Notes</h3></div></div></div> + + <p> Because globalization touches many different parts of the system, we want to reduce the implementation risk by breaking the implementation into phases. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-revision-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>1</td><td>Updated with results of MIT-sponsored i18n work at Collaboraid.</td><td>14 Aug 2003</td><td>Joel Aufrecht</td></tr><tr><td>0.4</td><td>converting from HTML to DocBook and importing the document to the OpenACS + </p> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="i18n-requirements-revision-history"></a>Revision History</h3></div></div></div> + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>1</td><td>Updated with results of MIT-sponsored i18n work at Collaboraid.</td><td>14 Aug 2003</td><td>Joel Aufrecht</td></tr><tr><td>0.4</td><td>converting from HTML to DocBook and importing the document to the OpenACS kernel documents. This was done as a part of the internationalization of - OpenACS and .LRN for the Heidelberg University in Germany</td><td>12 September 2002</td><td>Peter Marklund</td></tr><tr><td>0.3</td><td>comments from Christian</td><td>1/14/2000</td><td>Henry Minsky</td></tr><tr><td>0.2</td><td>Minor typos fixed, clarifications to wording</td><td>11/14/2000</td><td>Henry Minsky</td></tr><tr><td>0.1</td><td>Creation</td><td>11/08/2000</td><td>Henry Minsky</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Database Access API </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Security Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + OpenACS and .LRN for the Heidelberg University in Germany</td><td>12 September 2002</td><td>Peter Marklund</td></tr><tr><td>0.3</td><td>comments from Christian</td><td>1/14/2000</td><td>Henry Minsky</td></tr><tr><td>0.2</td><td>Minor typos fixed, clarifications to wording</td><td>11/14/2000</td><td>Henry Minsky</td></tr><tr><td>0.1</td><td>Creation</td><td>11/08/2000</td><td>Henry Minsky</td></tr></tbody></table> + </div> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api-detailed.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Database Access API </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Security Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/i18n-translators.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n-translators.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n-translators.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -23,9 +23,8 @@ <a class="ulink" href="/acs-lang/admin" target="_top">Administration of Localization</a> and create the locale.</p></li><li class="listitem"> <p> -<strong>Translating with Translator -Mode. </strong>To translate messages in the pages they -appear, <a class="ulink" href="http://localhost:8008/acs-lang/admin/translator-mode-toggle" target="_top">Toggle Translator Mode</a> and then browse to the +<strong>Translating with Translator Mode. </strong> +To translate messages in the pages they appear, <a class="ulink" href="http://localhost:8008/acs-lang/admin/translator-mode-toggle" target="_top">Toggle Translator Mode</a> 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 @@ -35,7 +34,7 @@ the bottom of each page.</p><div class="mediaobject" align="center"><img src="images/translations.png" align="middle"></div> </li><li class="listitem"> <p> -<strong>Batch translation. </strong>To translate +<strong>Batch translation. </strong> To translate many messages at once, go to <a class="ulink" href="/acs-lang/admin" target="_top">Administration of Localization</a>, click on the locale to translate, then click on a package, and then click <code class="computeroutput">Batch edit these 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 -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/i18n-translators.html 7 Aug 2017 23:47:50 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/i18n-translators.html 8 Nov 2017 09:42:10 -0000 1.18 @@ -1,2 +1,25 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Translator's Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-design.html" title="Design Notes"><link rel="next" href="cvs-tips.html" title="Appendix D. Using CVS with an OpenACS Site"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-design.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-translators"></a>Translator's Guide</h2></div></div></div><p>Most translators use the <a class="ulink" href="http://translate.openacs.org" target="_top">OpenACS Public Translation Server</a>, 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.</p><p>The basic steps for translators:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Go to the <a class="ulink" href="/acs-lang" target="_top">Localization</a> page and choose the locale that you are translating to. If the locale is not present you need to visit <a class="ulink" href="/acs-lang/admin" target="_top">Administration of Localization</a> and create the locale.</p></li><li class="listitem"><p><b>Translating with Translator Mode. </b>To translate messages in the pages they appear, <a class="ulink" href="http://localhost:8008/acs-lang/admin/translator-mode-toggle" target="_top">Toggle Translator Mode</a> 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.</p><div class="mediaobject" align="center"><img src="images/translator-mode.png" align="middle"></div><p>While in Translator mode, a list of all message keys appears at the bottom of each page.</p><div class="mediaobject" align="center"><img src="images/translations.png" align="middle"></div></li><li class="listitem"><p><b>Batch translation. </b>To translate many messages at once, go to <a class="ulink" href="/acs-lang/admin" target="_top">Administration of Localization</a>, click on the locale to translate, then click on a package, and then click <code class="computeroutput">Batch edit these messages</code>.</p><div class="mediaobject" align="center"><img src="images/translation-batch-edit.png" align="middle"></div></li></ul></div><p>When creating a new locale based on an existing one, such as creating the Guatemalan version of Spanish, you can copy the existing locale's catalog files using the script <code class="computeroutput">/packages/acs-core-docs/www/files/create-new-catalog.sh</code>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr><tr><td width="40%" align="left">Design Notes </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> Appendix D. Using CVS with an OpenACS Site</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Translator's Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="i18n.html" title="Chapter 14. Internationalization"><link rel="previous" href="i18n-design.html" title="Design Notes"><link rel="next" href="cvs-tips.html" title="Appendix D. Using CVS with an OpenACS Site"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-design.html">Prev</a> </td><th width="60%" align="center">Chapter 14. Internationalization</th><td width="20%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="i18n-translators"></a>Translator's Guide</h2></div></div></div> + + <p>Most translators use the <a class="ulink" href="http://translate.openacs.org" target="_top">OpenACS Public Translation Server</a>, 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.</p> + <p>The basic steps for translators:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Go to the <a class="ulink" href="/acs-lang" target="_top">Localization</a> page and choose the locale that you are translating to. If the locale is not present you need to visit <a class="ulink" href="/acs-lang/admin" target="_top">Administration of Localization</a> and create the locale.</p> + </li><li class="listitem"> + <p> + <b>Translating with Translator Mode. </b> + To translate messages in the pages they appear, <a class="ulink" href="http://localhost:8008/acs-lang/admin/translator-mode-toggle" target="_top">Toggle Translator Mode</a> 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. + </p> + <div class="mediaobject" align="center"><img src="images/translator-mode.png" align="middle"></div> + <p>While in Translator mode, a list of all message keys appears at the bottom of each page.</p> + <div class="mediaobject" align="center"><img src="images/translations.png" align="middle"></div> + </li><li class="listitem"> + <p> + <b>Batch translation. </b> + To translate many messages at once, go to <a class="ulink" href="/acs-lang/admin" target="_top">Administration of Localization</a>, click on the locale to translate, then click on a package, and then click <code class="computeroutput">Batch edit these messages</code>. + </p> + <div class="mediaobject" align="center"><img src="images/translation-batch-edit.png" align="middle"></div> + + </li></ul></div> + <p>When creating a new locale based on an existing one, such as creating the Guatemalan version of Spanish, you can copy the existing locale's catalog files using the script <code class="computeroutput">/packages/acs-core-docs/www/files/create-new-catalog.sh</code>.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-tips.html">Next</a></td></tr><tr><td width="40%" align="left">Design Notes </td><td width="20%" align="center"><a accesskey="u" href="i18n.html">Up</a></td><td width="40%" align="right"> Appendix D. Using CVS with an OpenACS Site</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/i18n.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/i18n.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/i18n.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -20,11 +20,9 @@ Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators">Translator's Guide</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:peter\@collaboraid.biz" target="_top">Peter Marklund</a> and <a class="ulink" href="mailto:lars\@collaboraid.biz" target="_top">Lars Pind</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div> +</div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:peter\@collaboraid.biz" target="_top">Peter Marklund</a> and +<a class="ulink" href="mailto:lars\@collaboraid.biz" target="_top">Lars Pind</a> +</span></p><span style="color: red"></authorblurb></span> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="requirements-template" leftLabel="Prev" leftTitle="System/Application Requirements Index: openacs-4/packages/acs-core-docs/www/i18n.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/i18n.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/i18n.html 7 Aug 2017 23:47:50 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/i18n.html 8 Nov 2017 09:42:10 -0000 1.36 @@ -1,8 +1,22 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 14. Internationalization</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="requirements-template.html" title="System/Application Requirements Template"><link rel="next" href="i18n-overview.html" title="Internationalization and Localization Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="i18n-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="i18n"></a>Chapter 14. Internationalization</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="i18n-overview.html">Internationalization and Localization Overview</a></span></dt><dt><span class="sect1"><a href="i18n-introduction.html">How Internationalization/Localization works in OpenACS</a></span></dt><dt><span class="sect1"><a href="i18n-convert.html">How to Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design.html">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators.html">Translator's Guide</a></span></dt></dl></div><div class="authorblurb"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 14. Internationalization</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="requirements-template.html" title="System/Application Requirements Template"><link rel="next" href="i18n-overview.html" title="Internationalization and Localization Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="i18n-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="i18n"></a>Chapter 14. Internationalization</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="i18n-overview.html">Internationalization and Localization Overview</a></span></dt><dt><span class="sect1"><a href="i18n-introduction.html">How Internationalization/Localization works in OpenACS</a></span></dt><dt><span class="sect1"><a href="i18n-convert.html">How to Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design.html">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators.html">Translator's Guide</a></span></dt></dl></div> + + + <span style="color: red"><authorblurb> + <p> By <a class="ulink" href="mailto:peter@collaboraid.biz" target="_top">Peter Marklund</a> and <a class="ulink" href="mailto:lars@collaboraid.biz" target="_top">Lars Pind</a> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-overview.html">Next</a></td></tr><tr><td width="40%" align="left">System/Application Requirements Template </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Internationalization and Localization Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </authorblurb></span> + + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="requirements-template.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n-overview.html">Next</a></td></tr><tr><td width="40%" align="left">System/Application Requirements Template </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Internationalization and Localization Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/index.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.adp,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/index.adp 7 Aug 2017 23:47:50 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/index.adp 8 Nov 2017 09:42:10 -0000 1.28 @@ -9,7 +9,7 @@ <div class="book"> <div class="titlepage"> <div><div><h1 class="title"> -<a name="idp140592082495080" id="idp140592082495080"></a>OpenACS Core Documentation</h1></div></div><hr> +<a name="idp140623166870808" id="idp140623166870808"></a>OpenACS Core Documentation</h1></div></div><hr> </div><div class="toc"> <p><strong>Table of Contents</strong></p><dl class="toc"> <dt><span class="part"><a href="for-everyone">I. OpenACS For @@ -87,8 +87,7 @@ (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2">Install Full Text Search -using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-openfts">Install Full Text Search -using OpenFTS (deprecated see tsearch2)</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl">Install +using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail">Install Index: openacs-4/packages/acs-core-docs/www/index.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/index.html,v diff -u -r1.54 -r1.55 --- openacs-4/packages/acs-core-docs/www/index.html 7 Aug 2017 23:47:50 -0000 1.54 +++ openacs-4/packages/acs-core-docs/www/index.html 8 Nov 2017 09:42:10 -0000 1.55 @@ -1,4 +1,15 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Core Documentation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="next" href="for-everyone.html" title="Part I. OpenACS For Everyone"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr></table><hr></div><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="idp140592082495080"></a>OpenACS Core Documentation</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="part"><a href="for-everyone.html">I. OpenACS For Everyone</a></span></dt><dd><dl><dt><span class="chapter"><a href="general-documents.html">1. High level information: What is OpenACS?</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="release-notes.html">OpenACS Release Notes</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="acs-admin.html">II. Administrator's Guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="install-overview.html">2. Installation Overview</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-steps.html">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs.html">Prerequisite Software</a></span></dt></dl></dd><dt><span class="chapter"><a href="complete-install.html">3. Complete Installation</a></span></dt><dd><dl><dt><span class="sect1"><a href="unix-installation.html">Install a Unix-like system and supporting software</a></span></dt><dt><span class="sect1"><a href="oracle.html">Install Oracle 8.1.7</a></span></dt><dt><span class="sect1"><a href="postgres.html">Install PostgreSQL</a></span></dt><dt><span class="sect1"><a href="aolserver4.html">Install AOLserver 4</a></span></dt><dt><span class="sect1"><a href="openacs.html">Install OpenACS 5.9.0</a></span></dt><dt><span class="sect1"><a href="win2k-installation.html">OpenACS Installation Guide for Windows</a></span></dt><dt><span class="sect1"><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></span></dt></dl></dd><dt><span class="chapter"><a href="configuring-new-site.html">4. Configuring a new OpenACS Site</a></span></dt><dd><dl><dt><span class="sect1"><a href="configuring-install-packages.html">Installing OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-mounting-packages.html">Mounting OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-packages.html">Configuring an OpenACS package</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-permissions.html">Setting Permissions on an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I.html">How Do I?</a></span></dt></dl></dd><dt><span class="chapter"><a href="upgrade.html">5. Upgrading</a></span></dt><dd><dl><dt><span class="sect1"><a href="upgrade-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></span></dt><dt><span class="sect1"><a href="upgrade-4.6.3-to-5.html">Upgrading OpenACS 4.6.3 to 5.0</a></span></dt><dt><span class="sect1"><a href="upgrade-5-0-dot.html">Upgrading an OpenACS 5.0.0 or greater installation</a></span></dt><dt><span class="sect1"><a href="upgrade-openacs-files.html">Upgrading the OpenACS files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting.html">Upgrading Platform components</a></span></dt></dl></dd><dt><span class="chapter"><a href="maintenance-web.html">6. Production Environments</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-openacs-keepalive.html">Starting and Stopping an OpenACS instance.</a></span></dt><dt><span class="sect1"><a href="install-openacs-inittab.html">AOLserver keepalive with inittab</a></span></dt><dt><span class="sect1"><a href="install-next-add-server.html">Running multiple services on one machine</a></span></dt><dt><span class="sect1"><a href="high-avail.html">High Availability/High Performance Configurations</a></span></dt><dt><span class="sect1"><a href="maintenance-deploy.html">Staged Deployment for Production Networks</a></span></dt><dt><span class="sect1"><a href="install-ssl.html">Installing SSL Support for an OpenACS service</a></span></dt><dt><span class="sect1"><a href="analog-setup.html">Set up Log Analysis Reports</a></span></dt><dt><span class="sect1"><a href="uptime.html">External uptime validation</a></span></dt><dt><span class="sect1"><a href="maint-performance.html">Diagnosing Performance Problems</a></span></dt></dl></dd><dt><span class="chapter"><a href="database-management.html">7. Database Management</a></span></dt><dd><dl><dt><span class="sect1"><a href="remote-postgres.html">Running a PostgreSQL database on another server</a></span></dt><dt><span class="sect1"><a href="install-openacs-delete-tablespace.html">Deleting a tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum.html">Vacuum Postgres nightly</a></span></dt></dl></dd><dt><span class="chapter"><a href="backup-recovery.html">8. Backup and Recovery</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-next-backups.html">Backup Strategy</a></span></dt><dt><span class="sect1"><a href="snapshot-backup.html">Manual backup and recovery</a></span></dt><dt><span class="sect1"><a href="automated-backup.html">Automated Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs.html">Using CVS for backup-recovery</a></span></dt></dl></dd><dt><span class="appendix"><a href="install-redhat.html">A. Install Red Hat 8/9</a></span></dt><dt><span class="appendix"><a href="install-more-software.html">B. Install additional supporting software</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></span></dt><dt><span class="sect1"><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-qmail.html">Install qmail (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install.html">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam.html">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2.html">Install Full Text Search using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-openfts.html">Install Full Text Search using OpenFTS (deprecated see tsearch2)</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl.html">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest.html">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php.html">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail.html">Install Squirrelmail for use as a webmail system for OpenACS</a></span></dt><dt><span class="sect1"><a href="install-pam-radius.html">Install PAM Radius for use as external authentication</a></span></dt><dt><span class="sect1"><a href="install-ldap-radius.html">Install LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver.html">Install AOLserver 3.3oacs1</a></span></dt></dl></dd><dt><span class="appendix"><a href="credits.html">C. Credits</a></span></dt><dd><dl><dt><span class="section"><a href="install-origins.html">Where did this document come from?</a></span></dt><dt><span class="section"><a href="os-install.html">Linux Install Guides</a></span></dt><dt><span class="section"><a href="os-security.html">Security Information</a></span></dt><dt><span class="section"><a href="install-resources.html">Resources</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="acs-package-dev.html">III. For OpenACS Package Developers</a></span></dt><dd><dl><dt><span class="chapter"><a href="tutorial.html">9. Development Tutorial</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-newpackage.html">Creating an Application Package</a></span></dt><dt><span class="sect1"><a href="tutorial-database.html">Setting Up Database Objects</a></span></dt><dt><span class="sect1"><a href="tutorial-pages.html">Creating Web Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-debug.html">Debugging and Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="tutorial-advanced.html">10. Advanced Topics</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-specs.html">Write the Requirements and Design Specs</a></span></dt><dt><span class="sect1"><a href="tutorial-cvs.html">Add the new package to CVS</a></span></dt><dt><span class="sect1"><a href="tutorial-etp-templates.html">OpenACS Edit This Page Templates</a></span></dt><dt><span class="sect1"><a href="tutorial-comments.html">Adding Comments</a></span></dt><dt><span class="sect1"><a href="tutorial-admin-pages.html">Admin Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-categories.html">Categories</a></span></dt><dt><span class="sect1"><a href="profile-code.html">Profile your code</a></span></dt><dt><span class="sect1"><a href="tutorial-distribute.html">Prepare the package for distribution.</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrades.html">Distributing upgrades of your package</a></span></dt><dt><span class="sect1"><a href="tutorial-notifications.html">Notifications</a></span></dt><dt><span class="sect1"><a href="tutorial-hierarchical.html">Hierarchical data</a></span></dt><dt><span class="sect1"><a href="tutorial-vuh.html">Using .vuh files for pretty urls</a></span></dt><dt><span class="sect1"><a href="tutorial-css-layout.html">Laying out a page with CSS instead of tables</a></span></dt><dt><span class="sect1"><a href="tutorial-html-email.html">Sending HTML email from your application</a></span></dt><dt><span class="sect1"><a href="tutorial-caching.html">Basic Caching</a></span></dt><dt><span class="sect1"><a href="tutorial-schedule-procs.html">Scheduled Procedures</a></span></dt><dt><span class="sect1"><a href="tutorial-wysiwyg-editor.html">Enabling WYSIWYG</a></span></dt><dt><span class="sect1"><a href="tutorial-parameters.html">Adding in parameters for your package</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrade-scripts.html">Writing upgrade scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database.html">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics.html">Future Topics</a></span></dt></dl></dd><dt><span class="chapter"><a href="dev-guide.html">11. Development Reference</a></span></dt><dd><dl><dt><span class="sect1"><a href="packages.html">OpenACS Packages</a></span></dt><dt><span class="sect1"><a href="objects.html">OpenACS Data Models and the Object System</a></span></dt><dt><span class="sect1"><a href="request-processor.html">The Request Processor</a></span></dt><dt><span class="sect1"><a href="db-api.html">The OpenACS Database Access API</a></span></dt><dt><span class="sect1"><a href="templates.html">Using Templates in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions.html">Groups, Context, Permissions</a></span></dt><dt><span class="sect1"><a href="subsites.html">Writing OpenACS Application Pages</a></span></dt><dt><span class="sect1"><a href="parties.html">Parties in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a></span></dt><dt><span class="sect1"><a href="object-identity.html">Object Identity</a></span></dt><dt><span class="sect1"><a href="programming-with-aolserver.html">Programming with AOLserver</a></span></dt><dt><span class="sect1"><a href="form-builder.html">Using Form Builder: building html forms dynamically</a></span></dt></dl></dd><dt><span class="chapter"><a href="eng-standards.html">12. Engineering Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="style-guide.html">OpenACS Style Guide</a></span></dt><dt><span class="sect1"><a href="cvs-guidelines.html"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Core Documentation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="next" href="for-everyone.html" title="Part I. OpenACS For Everyone"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"> </td><th width="60%" align="center"></th><td width="20%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr></table><hr></div><div class="book"><div class="titlepage"><div><div><h1 class="title"><a name="idp140623166870808"></a>OpenACS Core Documentation</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="part"><a href="for-everyone.html">I. OpenACS For Everyone</a></span></dt><dd><dl><dt><span class="chapter"><a href="general-documents.html">1. High level information: What is OpenACS?</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="release-notes.html">OpenACS Release Notes</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="acs-admin.html">II. Administrator's Guide</a></span></dt><dd><dl><dt><span class="chapter"><a href="install-overview.html">2. Installation Overview</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-steps.html">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs.html">Prerequisite Software</a></span></dt></dl></dd><dt><span class="chapter"><a href="complete-install.html">3. Complete Installation</a></span></dt><dd><dl><dt><span class="sect1"><a href="unix-installation.html">Install a Unix-like system and supporting software</a></span></dt><dt><span class="sect1"><a href="oracle.html">Install Oracle 8.1.7</a></span></dt><dt><span class="sect1"><a href="postgres.html">Install PostgreSQL</a></span></dt><dt><span class="sect1"><a href="aolserver4.html">Install AOLserver 4</a></span></dt><dt><span class="sect1"><a href="openacs.html">Install OpenACS 5.9.0</a></span></dt><dt><span class="sect1"><a href="win2k-installation.html">OpenACS Installation Guide for Windows</a></span></dt><dt><span class="sect1"><a href="mac-installation.html">OpenACS Installation Guide for Mac OS X</a></span></dt></dl></dd><dt><span class="chapter"><a href="configuring-new-site.html">4. Configuring a new OpenACS Site</a></span></dt><dd><dl><dt><span class="sect1"><a href="configuring-install-packages.html">Installing OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-mounting-packages.html">Mounting OpenACS packages</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-packages.html">Configuring an OpenACS package</a></span></dt><dt><span class="sect1"><a href="configuring-configuring-permissions.html">Setting Permissions on an OpenACS package</a></span></dt><dt><span class="sect1"><a href="how-do-I.html">How Do I?</a></span></dt></dl></dd><dt><span class="chapter"><a href="upgrade.html">5. Upgrading</a></span></dt><dd><dl><dt><span class="sect1"><a href="upgrade-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></span></dt><dt><span class="sect1"><a href="upgrade-4.6.3-to-5.html">Upgrading OpenACS 4.6.3 to 5.0</a></span></dt><dt><span class="sect1"><a href="upgrade-5-0-dot.html">Upgrading an OpenACS 5.0.0 or greater installation</a></span></dt><dt><span class="sect1"><a href="upgrade-openacs-files.html">Upgrading the OpenACS files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting.html">Upgrading Platform components</a></span></dt></dl></dd><dt><span class="chapter"><a href="maintenance-web.html">6. Production Environments</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-openacs-keepalive.html">Starting and Stopping an OpenACS instance.</a></span></dt><dt><span class="sect1"><a href="install-openacs-inittab.html">AOLserver keepalive with inittab</a></span></dt><dt><span class="sect1"><a href="install-next-add-server.html">Running multiple services on one machine</a></span></dt><dt><span class="sect1"><a href="high-avail.html">High Availability/High Performance Configurations</a></span></dt><dt><span class="sect1"><a href="maintenance-deploy.html">Staged Deployment for Production Networks</a></span></dt><dt><span class="sect1"><a href="install-ssl.html">Installing SSL Support for an OpenACS service</a></span></dt><dt><span class="sect1"><a href="analog-setup.html">Set up Log Analysis Reports</a></span></dt><dt><span class="sect1"><a href="uptime.html">External uptime validation</a></span></dt><dt><span class="sect1"><a href="maint-performance.html">Diagnosing Performance Problems</a></span></dt></dl></dd><dt><span class="chapter"><a href="database-management.html">7. Database Management</a></span></dt><dd><dl><dt><span class="sect1"><a href="remote-postgres.html">Running a PostgreSQL database on another server</a></span></dt><dt><span class="sect1"><a href="install-openacs-delete-tablespace.html">Deleting a tablespace</a></span></dt><dt><span class="sect1"><a href="install-next-nightly-vacuum.html">Vacuum Postgres nightly</a></span></dt></dl></dd><dt><span class="chapter"><a href="backup-recovery.html">8. Backup and Recovery</a></span></dt><dd><dl><dt><span class="sect1"><a href="install-next-backups.html">Backup Strategy</a></span></dt><dt><span class="sect1"><a href="snapshot-backup.html">Manual backup and recovery</a></span></dt><dt><span class="sect1"><a href="automated-backup.html">Automated Backup</a></span></dt><dt><span class="sect1"><a href="backups-with-cvs.html">Using CVS for backup-recovery</a></span></dt></dl></dd><dt><span class="appendix"><a href="install-redhat.html">A. Install Red Hat 8/9</a></span></dt><dt><span class="appendix"><a href="install-more-software.html">B. Install additional supporting software</a></span></dt><dd><dl><dt><span class="sect1"><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></span></dt><dt><span class="sect1"><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-qmail.html">Install qmail (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install.html">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam.html">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2.html">Install Full Text Search using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl.html">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest.html">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php.html">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail.html">Install Squirrelmail for use as a webmail system for OpenACS</a></span></dt><dt><span class="sect1"><a href="install-pam-radius.html">Install PAM Radius for use as external authentication</a></span></dt><dt><span class="sect1"><a href="install-ldap-radius.html">Install LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver.html">Install AOLserver 3.3oacs1</a></span></dt></dl></dd><dt><span class="appendix"><a href="credits.html">C. Credits</a></span></dt><dd><dl><dt><span class="section"><a href="install-origins.html">Where did this document come from?</a></span></dt><dt><span class="section"><a href="os-install.html">Linux Install Guides</a></span></dt><dt><span class="section"><a href="os-security.html">Security Information</a></span></dt><dt><span class="section"><a href="install-resources.html">Resources</a></span></dt></dl></dd></dl></dd><dt><span class="part"><a href="acs-package-dev.html">III. For OpenACS Package Developers</a></span></dt><dd><dl><dt><span class="chapter"><a href="tutorial.html">9. Development Tutorial</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-newpackage.html">Creating an Application Package</a></span></dt><dt><span class="sect1"><a href="tutorial-database.html">Setting Up Database Objects</a></span></dt><dt><span class="sect1"><a href="tutorial-pages.html">Creating Web Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-debug.html">Debugging and Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="tutorial-advanced.html">10. Advanced Topics</a></span></dt><dd><dl><dt><span class="sect1"><a href="tutorial-specs.html">Write the Requirements and Design Specs</a></span></dt><dt><span class="sect1"><a href="tutorial-cvs.html">Add the new package to CVS</a></span></dt><dt><span class="sect1"><a href="tutorial-etp-templates.html">OpenACS Edit This Page Templates</a></span></dt><dt><span class="sect1"><a href="tutorial-comments.html">Adding Comments</a></span></dt><dt><span class="sect1"><a href="tutorial-admin-pages.html">Admin Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-categories.html">Categories</a></span></dt><dt><span class="sect1"><a href="profile-code.html">Profile your code</a></span></dt><dt><span class="sect1"><a href="tutorial-distribute.html">Prepare the package for distribution.</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrades.html">Distributing upgrades of your package</a></span></dt><dt><span class="sect1"><a href="tutorial-notifications.html">Notifications</a></span></dt><dt><span class="sect1"><a href="tutorial-hierarchical.html">Hierarchical data</a></span></dt><dt><span class="sect1"><a href="tutorial-vuh.html">Using .vuh files for pretty urls</a></span></dt><dt><span class="sect1"><a href="tutorial-css-layout.html">Laying out a page with CSS instead of tables</a></span></dt><dt><span class="sect1"><a href="tutorial-html-email.html">Sending HTML email from your application</a></span></dt><dt><span class="sect1"><a href="tutorial-caching.html">Basic Caching</a></span></dt><dt><span class="sect1"><a href="tutorial-schedule-procs.html">Scheduled Procedures</a></span></dt><dt><span class="sect1"><a href="tutorial-wysiwyg-editor.html">Enabling WYSIWYG</a></span></dt><dt><span class="sect1"><a href="tutorial-parameters.html">Adding in parameters for your package</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrade-scripts.html">Writing upgrade scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database.html">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics.html">Future Topics</a></span></dt></dl></dd><dt><span class="chapter"><a href="dev-guide.html">11. Development Reference</a></span></dt><dd><dl><dt><span class="sect1"><a href="packages.html">OpenACS Packages</a></span></dt><dt><span class="sect1"><a href="objects.html">OpenACS Data Models and the Object System</a></span></dt><dt><span class="sect1"><a href="request-processor.html">The Request Processor</a></span></dt><dt><span class="sect1"><a href="db-api.html">The OpenACS Database Access API</a></span></dt><dt><span class="sect1"><a href="templates.html">Using Templates in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions.html">Groups, Context, Permissions</a></span></dt><dt><span class="sect1"><a href="subsites.html">Writing OpenACS Application Pages</a></span></dt><dt><span class="sect1"><a href="parties.html">Parties in OpenACS</a></span></dt><dt><span class="sect1"><a href="permissions-tediously-explained.html">OpenACS Permissions Tediously Explained</a></span></dt><dt><span class="sect1"><a href="object-identity.html">Object Identity</a></span></dt><dt><span class="sect1"><a href="programming-with-aolserver.html">Programming with AOLserver</a></span></dt><dt><span class="sect1"><a href="form-builder.html">Using Form Builder: building html forms dynamically</a></span></dt></dl></dd><dt><span class="chapter"><a href="eng-standards.html">12. Engineering Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="style-guide.html">OpenACS Style Guide</a></span></dt><dt><span class="sect1"><a href="cvs-guidelines.html"> CVS Guidelines - </a></span></dt><dt><span class="sect1"><a href="eng-standards-versioning.html">Release Version Numbering</a></span></dt><dt><span class="sect1"><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></span></dt><dt><span class="sect1"><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></span></dt><dt><span class="sect1"><a href="eng-standards-plsql.html">PL/SQL Standards</a></span></dt><dt><span class="sect1"><a href="variables.html">Variables</a></span></dt><dt><span class="sect1"><a href="automated-testing-best-practices.html">Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="doc-standards.html">13. Documentation Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="docbook-primer.html">OpenACS Documentation Guide</a></span></dt><dt><span class="sect1"><a href="psgml-mode.html">Using PSGML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="nxml-mode.html">Using nXML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="filename.html">Detailed Design Documentation Template</a></span></dt><dt><span class="sect1"><a href="requirements-template.html">System/Application Requirements Template</a></span></dt></dl></dd><dt><span class="chapter"><a href="i18n.html">14. Internationalization</a></span></dt><dd><dl><dt><span class="sect1"><a href="i18n-overview.html">Internationalization and Localization Overview</a></span></dt><dt><span class="sect1"><a href="i18n-introduction.html">How Internationalization/Localization works in OpenACS</a></span></dt><dt><span class="sect1"><a href="i18n-convert.html">How to Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design.html">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators.html">Translator's Guide</a></span></dt></dl></dd><dt><span class="appendix"><a href="cvs-tips.html">D. Using CVS with an OpenACS Site</a></span></dt></dl></dd><dt><span class="part"><a href="acs-plat-dev.html">IV. For OpenACS Platform Developers</a></span></dt><dd><dl><dt><span class="chapter"><a href="kernel-doc.html">15. Kernel Documentation</a></span></dt><dd><dl><dt><span class="sect1"><a href="kernel-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="object-system-requirements.html">Object Model Requirements</a></span></dt><dt><span class="sect1"><a href="object-system-design.html">Object Model Design</a></span></dt><dt><span class="sect1"><a href="permissions-requirements.html">Permissions Requirements</a></span></dt><dt><span class="sect1"><a href="permissions-design.html">Permissions Design</a></span></dt><dt><span class="sect1"><a href="groups-requirements.html">Groups Requirements</a></span></dt><dt><span class="sect1"><a href="groups-design.html">Groups Design</a></span></dt><dt><span class="sect1"><a href="subsites-requirements.html">Subsites Requirements</a></span></dt><dt><span class="sect1"><a href="subsites-design.html">Subsites Design Document</a></span></dt><dt><span class="sect1"><a href="apm-requirements.html">Package Manager Requirements</a></span></dt><dt><span class="sect1"><a href="apm-design.html">Package Manager Design</a></span></dt><dt><span class="sect1"><a href="db-api-detailed.html">Database Access API</a></span></dt><dt><span class="sect1"><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></span></dt><dt><span class="sect1"><a href="security-requirements.html">Security Requirements</a></span></dt><dt><span class="sect1"><a href="security-design.html">Security Design</a></span></dt><dt><span class="sect1"><a href="security-notes.html">Security Notes</a></span></dt><dt><span class="sect1"><a href="rp-requirements.html">Request Processor Requirements</a></span></dt><dt><span class="sect1"><a href="rp-design.html">Request Processor Design</a></span></dt><dt><span class="sect1"><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></span></dt><dt><span class="sect1"><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></span></dt><dt><span class="sect1"><a href="ext-auth-requirements.html">External Authentication Requirements</a></span></dt></dl></dd><dt><span class="chapter"><a href="releasing-openacs.html">16. Releasing OpenACS</a></span></dt><dd><dl><dt><span class="section"><a href="releasing-openacs-core.html">OpenACS Core and .LRN</a></span></dt><dt><span class="section"><a href="update-repository.html">How to Update the OpenACS.org repository</a></span></dt><dt><span class="section"><a href="releasing-package.html">How to package and release an OpenACS Package</a></span></dt><dt><span class="section"><a href="update-translations.html">How to Update the translations</a></span></dt></dl></dd></dl></dd><dt><span class="index"><a href="ix01.html">Index</a></span></dt></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>4.1. <a href="how-do-I.html#idp140592106982936">Site Templates</a></dt><dt>4.2. <a href="how-do-I.html#idp140592107005048">Granting Permissions</a></dt><dt>4.3. <a href="how-do-I.html#idp140592107008760">Granting Permissions in 5.0</a></dt><dt>5.1. <a href="upgrade-overview.html#idp140592104571672">Upgrading with the APM</a></dt><dt>5.2. <a href="upgrade-openacs-files.html#idp140592101750040">Upgrading a local CVS repository</a></dt><dt>6.1. <a href="high-avail.html#idp140592101868456">Multiple-server configuration</a></dt><dt>6.2. <a href="maintenance-deploy.html#idp140592101353384">Simple A/B Deployment - Step 1</a></dt><dt>6.3. <a href="maintenance-deploy.html#idp140592101356072">Simple A/B Deployment - Step 2</a></dt><dt>6.4. <a href="maintenance-deploy.html#idp140592101358760">Simple A/B Deployment - Step 3</a></dt><dt>6.5. <a href="maintenance-deploy.html#idp140592101362216">Complex A/B Deployment - Step 1</a></dt><dt>6.6. <a href="maintenance-deploy.html#idp140592101364904">Complex A/B Deployment - Step 2</a></dt><dt>6.7. <a href="maintenance-deploy.html#idp140592101367592">Complex A/B Deployment - Step 3</a></dt><dt>6.8. <a href="maint-performance.html#idp140592101531128">Query Analysis example</a></dt><dt>8.1. <a href="backup-recovery.html#idp140592101131768">Backup and Recovery Strategy</a></dt><dt>9.1. <a href="tutorial-newpackage.html#idp140592100698680">Assumptions in this section</a></dt><dt>9.2. <a href="tutorial-database.html#idp140592094116616">Tutorial Data Model</a></dt><dt>9.3. <a href="tutorial-database.html#idp140592098943512">The Database Creation Script</a></dt><dt>9.4. <a href="tutorial-database.html#idp140592099179128">Database Deletion Script</a></dt><dt>9.5. <a href="tutorial-pages.html#idp140592102541576">Page Map</a></dt><dt>10.1. <a href="tutorial-cvs.html#idp140592099723480">Upgrading a local CVS repository</a></dt><dt>11.1. <a href="packages.html#idp140592107056328">Server file layout diagram</a></dt><dt>11.2. <a href="packages.html#idp140592107063624">Package file layout diagram</a></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="install-steps.html#idp140592102795880">Default directories for a standard install</a></dt><dt>2.2. <a href="individual-programs.html#compatibility-matrix">Version Compatibility Matrix</a></dt><dt>5.1. <a href="upgrade-overview.html#idp140592104575352">Assumptions in this section</a></dt><dt>6.1. <a href="install-openacs-keepalive.html#idp140592099316488">How it Works</a></dt><dt>10.1. <a href="tutorial-etp-templates.html#idp140592099042408">table showing ETP layout</a></dt><dt>11.1. <a href="packages.html#idp140592107069416">Package files</a></dt><dt>11.2. <a href="permissions-tediously-explained.html#idp140592100090856">Context Hierarchy Example</a></dt><dt>11.3. <a href="permissions-tediously-explained.html#idp140592100109768">acs_objects example data</a></dt><dt>14.1. <a href="i18n-overview.html#i18n-l10n-process">Internationalization and Localization Overview</a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>12.1. <a href="variables.html#idp140592120153288">Getting datetime from the database ANSI-style</a></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> Part I. OpenACS For Everyone</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </a></span></dt><dt><span class="sect1"><a href="eng-standards-versioning.html">Release Version Numbering</a></span></dt><dt><span class="sect1"><a href="eng-standards-constraint-naming.html">Constraint naming standard</a></span></dt><dt><span class="sect1"><a href="eng-standards-filenaming.html">ACS File Naming and Formatting Standards</a></span></dt><dt><span class="sect1"><a href="eng-standards-plsql.html">PL/SQL Standards</a></span></dt><dt><span class="sect1"><a href="variables.html">Variables</a></span></dt><dt><span class="sect1"><a href="automated-testing-best-practices.html">Automated Testing</a></span></dt></dl></dd><dt><span class="chapter"><a href="doc-standards.html">13. Documentation Standards</a></span></dt><dd><dl><dt><span class="sect1"><a href="docbook-primer.html">OpenACS Documentation Guide</a></span></dt><dt><span class="sect1"><a href="psgml-mode.html">Using PSGML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="nxml-mode.html">Using nXML mode in Emacs</a></span></dt><dt><span class="sect1"><a href="filename.html">Detailed Design Documentation Template</a></span></dt><dt><span class="sect1"><a href="requirements-template.html">System/Application Requirements Template</a></span></dt></dl></dd><dt><span class="chapter"><a href="i18n.html">14. Internationalization</a></span></dt><dd><dl><dt><span class="sect1"><a href="i18n-overview.html">Internationalization and Localization Overview</a></span></dt><dt><span class="sect1"><a href="i18n-introduction.html">How Internationalization/Localization works in OpenACS</a></span></dt><dt><span class="sect1"><a href="i18n-convert.html">How to Internationalize a Package</a></span></dt><dt><span class="sect1"><a href="i18n-design.html">Design Notes</a></span></dt><dt><span class="sect1"><a href="i18n-translators.html">Translator's Guide</a></span></dt></dl></dd><dt><span class="appendix"><a href="cvs-tips.html">D. Using CVS with an OpenACS Site</a></span></dt></dl></dd><dt><span class="part"><a href="acs-plat-dev.html">IV. For OpenACS Platform Developers</a></span></dt><dd><dl><dt><span class="chapter"><a href="kernel-doc.html">15. Kernel Documentation</a></span></dt><dd><dl><dt><span class="sect1"><a href="kernel-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="object-system-requirements.html">Object Model Requirements</a></span></dt><dt><span class="sect1"><a href="object-system-design.html">Object Model Design</a></span></dt><dt><span class="sect1"><a href="permissions-requirements.html">Permissions Requirements</a></span></dt><dt><span class="sect1"><a href="permissions-design.html">Permissions Design</a></span></dt><dt><span class="sect1"><a href="groups-requirements.html">Groups Requirements</a></span></dt><dt><span class="sect1"><a href="groups-design.html">Groups Design</a></span></dt><dt><span class="sect1"><a href="subsites-requirements.html">Subsites Requirements</a></span></dt><dt><span class="sect1"><a href="subsites-design.html">Subsites Design Document</a></span></dt><dt><span class="sect1"><a href="apm-requirements.html">Package Manager Requirements</a></span></dt><dt><span class="sect1"><a href="apm-design.html">Package Manager Design</a></span></dt><dt><span class="sect1"><a href="db-api-detailed.html">Database Access API</a></span></dt><dt><span class="sect1"><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></span></dt><dt><span class="sect1"><a href="security-requirements.html">Security Requirements</a></span></dt><dt><span class="sect1"><a href="security-design.html">Security Design</a></span></dt><dt><span class="sect1"><a href="security-notes.html">Security Notes</a></span></dt><dt><span class="sect1"><a href="rp-requirements.html">Request Processor Requirements</a></span></dt><dt><span class="sect1"><a href="rp-design.html">Request Processor Design</a></span></dt><dt><span class="sect1"><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></span></dt><dt><span class="sect1"><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></span></dt><dt><span class="sect1"><a href="ext-auth-requirements.html">External Authentication Requirements</a></span></dt></dl></dd><dt><span class="chapter"><a href="releasing-openacs.html">16. Releasing OpenACS</a></span></dt><dd><dl><dt><span class="section"><a href="releasing-openacs-core.html">OpenACS Core and .LRN</a></span></dt><dt><span class="section"><a href="update-repository.html">How to Update the OpenACS.org repository</a></span></dt><dt><span class="section"><a href="releasing-package.html">How to package and release an OpenACS Package</a></span></dt><dt><span class="section"><a href="update-translations.html">How to Update the translations</a></span></dt></dl></dd></dl></dd><dt><span class="index"><a href="ix01.html">Index</a></span></dt></dl></div><div class="list-of-figures"><p><b>List of Figures</b></p><dl><dt>4.1. <a href="how-do-I.html#idp140623178931720">Site Templates</a></dt><dt>4.2. <a href="how-do-I.html#idp140623157109688">Granting Permissions</a></dt><dt>4.3. <a href="how-do-I.html#idp140623157113640">Granting Permissions in 5.0</a></dt><dt>5.1. <a href="upgrade-overview.html#idp140623159984264">Upgrading with the APM</a></dt><dt>5.2. <a href="upgrade-openacs-files.html#idp140623159992456">Upgrading a local CVS repository</a></dt><dt>6.1. <a href="high-avail.html#idp140623175654472">Multiple-server configuration</a></dt><dt>6.2. <a href="maintenance-deploy.html#idp140623175654760">Simple A/B Deployment - Step 1</a></dt><dt>6.3. <a href="maintenance-deploy.html#idp140623175792120">Simple A/B Deployment - Step 2</a></dt><dt>6.4. <a href="maintenance-deploy.html#idp140623175788536">Simple A/B Deployment - Step 3</a></dt><dt>6.5. <a href="maintenance-deploy.html#idp140623175695688">Complex A/B Deployment - Step 1</a></dt><dt>6.6. <a href="maintenance-deploy.html#idp140623174978168">Complex A/B Deployment - Step 2</a></dt><dt>6.7. <a href="maintenance-deploy.html#idp140623174977320">Complex A/B Deployment - Step 3</a></dt><dt>6.8. <a href="maint-performance.html#idp140623175898008">Query Analysis example</a></dt><dt>8.1. <a href="backup-recovery.html#idp140623175809992">Backup and Recovery Strategy</a></dt><dt>9.1. <a href="tutorial-newpackage.html#idp140623174045016">Assumptions in this section</a></dt><dt>9.2. <a href="tutorial-database.html#idp140623163033192">Tutorial Data Model</a></dt><dt>9.3. <a href="tutorial-database.html#idp140623161557048">The Database Creation Script</a></dt><dt>9.4. <a href="tutorial-database.html#idp140623165914152">Database Deletion Script</a></dt><dt>9.5. <a href="tutorial-pages.html#idp140623165411624">Page Map</a></dt><dt>10.1. <a href="tutorial-cvs.html#idp140623162867368">Upgrading a local CVS repository</a></dt><dt>11.1. <a href="packages.html#idp140623177082456">Server file layout diagram</a></dt><dt>11.2. <a href="packages.html#idp140623172256280">Package file layout diagram</a></dt></dl></div><div class="list-of-tables"><p><b>List of Tables</b></p><dl><dt>2.1. <a href="install-steps.html#idp140623179122616">Default directories for a standard install</a></dt><dt>2.2. <a href="individual-programs.html#compatibility-matrix">Version Compatibility Matrix</a></dt><dt>5.1. <a href="upgrade-overview.html#idp140623160218856">Assumptions in this section</a></dt><dt>6.1. <a href="install-openacs-keepalive.html#idp140623159800936">How it Works</a></dt><dt>10.1. <a href="tutorial-etp-templates.html#idp140623170145000">table showing ETP layout</a></dt><dt>11.1. <a href="packages.html#idp140623177767000">Package files</a></dt><dt>11.2. <a href="permissions-tediously-explained.html#idp140623163017608">Context Hierarchy Example</a></dt><dt>11.3. <a href="permissions-tediously-explained.html#idp140623167583592">acs_objects example data</a></dt><dt>14.1. <a href="i18n-overview.html#i18n-l10n-process">Internationalization and Localization Overview</a></dt></dl></div><div class="list-of-examples"><p><b>List of Examples</b></p><dl><dt>12.1. <a href="variables.html#idp140623173823464">Getting datetime from the database ANSI-style</a></dt></dl></div> + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> <a accesskey="n" href="for-everyone.html">Next</a></td></tr><tr><td width="40%" align="left"> </td><td width="20%" align="center"></td><td width="40%" align="right"> Part I. OpenACS For Everyone</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/individual-programs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/individual-programs.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/individual-programs.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="complete-install" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="individual-programs" id="individual-programs"></a>Prerequisite Software</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>OpenACS requires, at a minimum, an operating system, database, +<a name="individual-programs" id="individual-programs"></a>Prerequisite Software</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><p>OpenACS requires, at a minimum, an operating system, database, and webserver to work. Many additional programs, such as a build environment, Mail Transport Agent, and source control system, are also needed for a fully effective installation.</p><div class="table"> @@ -81,18 +79,18 @@ <li class="listitem"> <a name="openacs-download" id="openacs-download"></a><p> <strong> -<a class="ulink" href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 5.9.0</a>. </strong>The OpenACS tarball +<a class="ulink" href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 5.9.0</a>. </strong> The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL and Oracle. Some scripts require bash shell.</p> </li><li class="listitem"> <p> -<strong>Operating System. </strong>OpenACS is +<strong>Operating System. </strong> OpenACS is designed for a Unix-like system. It is developed primarily in Linux. It can be run on Mac OS X, and in Windows within VMWare.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"><p> -<strong>GNU/Linux. </strong>The installation assumes -a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.</p></li><li class="listitem"><p> +<strong>GNU/Linux. </strong> The installation +assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.</p></li><li class="listitem"><p> <strong>FreeBSD. </strong><a class="ulink" href="https://web.archive.org/web/20011204174701/http://www.orchardlabs.com:80/freebsd/" target="_top">FreeBSD guide</a>. The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different shell, you will need to @@ -112,17 +110,17 @@ </ul></div> </li><li class="listitem"> <p> -<strong>Build Environment. </strong>The Reference +<strong>Build Environment. </strong> The Reference Platform installation compiles most programs from source code.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"><p> <strong> -<a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> 2.2 or newer, REQUIRED. </strong>You +<a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> 2.2 or newer, REQUIRED. </strong> You need recent versions of these libraries for Oracle to work properly. For Unicode support, you need glibc 2.2 or newer. This should be included in your operating system distribution.</p></li><li class="listitem"><p> <strong> <a class="ulink" href="http://www.gnu.org/software/make/" target="_top">GNU Make</a> -3.76.1 or newer, REQUIRED. </strong>PostgreSQL and +3.76.1 or newer, REQUIRED. </strong> PostgreSQL and AOLserver require gmake to compile. Note that on most linux distributions, GNU Make is simply named <code class="computeroutput">make</code> and there is no <code class="computeroutput">gmake</code>, whereas on BSD distributions, <code class="computeroutput">make</code> and <code class="computeroutput">gmake</code> are different --use gmake.</p></li> @@ -132,7 +130,7 @@ <a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x. </strong></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"><p> <strong> -<a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x, REQUIRED. </strong>OpenACS is +<a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x, REQUIRED. </strong> OpenACS is written in Tcl, an interpreted language. A threaded version of the Tcl interpreter must be installed for OpenACS to work. The Tcl interpreter that is included in most standard distributions may not @@ -152,27 +150,27 @@ </li><li class="listitem"> <a name="source-tdom" id="source-tdom"></a><p> <strong> -<a class="ulink" href="http://www.tdom.org/" target="_top">tDOM</a>, REQUIRED. </strong>OpenACS 5.9.0 +<a class="ulink" href="http://www.tdom.org/" target="_top">tDOM</a>, REQUIRED. </strong> OpenACS 5.9.0 stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which was used prior to 4.6.4.)</p> </li><li class="listitem"> <a name="source-tclwebtest" id="source-tclwebtest"></a><p> <strong> -<a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=31075" target="_top">tclwebtest</a>, -OPTIONAL. </strong>tclwebtest is a tool for testing web -interfaces via Tcl scripts.</p> +<a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=31075" target="_top">tclwebtest</a>, OPTIONAL. </strong> +tclwebtest is a tool for testing web interfaces via Tcl +scripts.</p> </li><li class="listitem"> <p> -<strong>Web Server. </strong>The web server handles +<strong>Web Server. </strong> The web server handles incoming HTTP requests, provides a runtime environment for OpenACS's Tcl code, connects to the database, sends out HTTP responses, and logs requests and errors. OpenACS uses AOLserver; <a class="ulink" href="http://openacs.org/forums/message-view?message_id=21461" target="_top">some people have had success running Apache with mod_nsd</a>.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"><li class="listitem"> <a name="source-aolserver" id="source-aolserver"></a><p> <strong> -<a class="ulink" href="http://aolserver.com/" target="_top">AOLserver</a> 4.x, REQUIRED. </strong>Provides +<a class="ulink" href="http://aolserver.com/" target="_top">AOLserver</a> 4.x, REQUIRED. </strong> Provides the base HTTP server</p> </li></ul></div><p>Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS @@ -194,7 +192,7 @@ </ul></div> </li><li class="listitem"> <a name="nsopenssl-download" id="nsopenssl-download"></a><p> -<strong>nsopenssl, OPTIONAL. </strong>Provides SSL +<strong>nsopenssl, OPTIONAL. </strong> Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make secure (https) connections to your webserver. aolserver3.x requires <a class="ulink" href="http://www.scottg.net/download/nsopenssl-2.1a.tar.gz" target="_top">nsopenssl 2.1a</a>. aolserver4.x requires nsopenssl3; see @@ -203,47 +201,45 @@ <a name="nspam-download" id="nspam-download"></a><p> <strong> <a class="ulink" href="http://wayback.archive.org/web/20050228071203/http://braindamage.alal.com/software/nspam.html" target="_top">ns_pam</a> 0.1 or newer, -OPTIONAL. </strong>Provides PAM capabilities for +OPTIONAL. </strong> Provides PAM capabilities for AOLserver. You need this if you want OpenACS users to authenticate through a PAM module (such as RADIUS).</p> </li><li class="listitem"> <a name="pam-radius-download" id="pam-radius-download"></a><p> <strong> -<a class="ulink" href="ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar" target="_top">pam_radius 1.3.16</a>, -OPTIONAL. </strong>Provides RADIUS capabilities for -PAM. You need this if you want to use RADIUS authentication via PAM -in OpenACS.</p> +<a class="ulink" href="ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar" target="_top">pam_radius 1.3.16</a>, OPTIONAL. </strong> +Provides RADIUS capabilities for PAM. You need this if you want to +use RADIUS authentication via PAM in OpenACS.</p> </li><li class="listitem"> <a name="nsldap-download" id="nsldap-download"></a><p> <strong> -<a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=3152" target="_top">ns_ldap 0.r8</a>, -OPTIONAL. </strong>Provides LDAP capabilities for -AOLserver. You need this if you want to use LDAP authentication in -OpenACS.</p> +<a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=3152" target="_top">ns_ldap 0.r8</a>, OPTIONAL. </strong> +Provides LDAP capabilities for AOLserver. You need this if you want +to use LDAP authentication in OpenACS.</p> </li><li class="listitem"> <a name="openfts-download" id="openfts-download"></a><p> <strong> <a class="ulink" href="http://unc.dl.sourceforge.net/sourceforge/openfts/Search-OpenFTS-tcl-0.3.2.tar.gz" target="_top">OpenFTS Tcl 0.3.2</a>, -OPTIONAL. </strong>Adds full-text-search to PostgreSQL +OPTIONAL. </strong> Adds full-text-search to PostgreSQL and includes a driver for AOLserver. You need this if you want users to be able to search for any text on your site. For postgres 7.4.x and higher, full text search is also available via tsearch2.</p> </li><li class="listitem"><p> <a name="analog-download" id="analog-download"></a><strong> -<a class="ulink" href="http://www.analog.cx/" target="_top">Analog</a> 5.32 or newer, -OPTIONAL. </strong>This program examines web server -request logs, looks up DNS values, and produces a report. You need -this if you want to see how much traffic your site is getting.</p></li><li class="listitem"><p> +<a class="ulink" href="http://www.analog.cx/" target="_top">Analog</a> 5.32 or newer, OPTIONAL. </strong> +This program examines web server request logs, looks up DNS values, +and produces a report. You need this if you want to see how much +traffic your site is getting.</p></li><li class="listitem"><p> <a name="balance-download" id="balance-download"></a><strong> -<a class="ulink" href="http://sourceforge.net/projects/balance/" target="_top">Balance</a> 3.11 or newer, -OPTIONAL. </strong>"Balance is a simple but -powerful generic tcp proxy with round robin load balancing and -failover mechanisms." You need this or something equivalent if -you are running a high-availability production site and do not have -an external load balancing system.</p></li><li class="listitem"> +<a class="ulink" href="http://sourceforge.net/projects/balance/" target="_top">Balance</a> 3.11 or newer, OPTIONAL. </strong> +"Balance is a simple but powerful generic tcp proxy with round +robin load balancing and failover mechanisms." You need this +or something equivalent if you are running a high-availability +production site and do not have an external load balancing +system.</p></li><li class="listitem"> <p> -<strong>Database. </strong>The data on your site +<strong>Database. </strong> The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS separates the database with an abstraction layer, which means that several different @@ -252,71 +248,70 @@ support all databases.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"><p> <strong>Oracle 8.1.7 (Either this or PostgreSQL is -REQUIRED). </strong>You can register and download +REQUIRED). </strong> You can register and download Oracle from <a class="ulink" href="https://www.oracle.com/downloads/index.html" target="_top">Oracle TechNet</a>. You need this if you want to use an Oracle database.</p></li><li class="listitem"><p> <a name="source-postgresql" id="source-postgresql"></a><strong> <a class="ulink" href="http://sourceforge.net/projects/pgsql/" target="_top">PostgreSQL</a> 7.4.x (Either this or Oracle is -REQUIRED). </strong>You need this if you want to use a +REQUIRED). </strong> You need this if you want to use a PostgreSQL database.</p></li> </ul></div> </li><li class="listitem"> <p> -<strong>Process Controller. </strong>This is +<strong>Process Controller. </strong> This is software that initiates other software, and restarts that software if it fails. On Linux, we recommend using Daemontools to control AOLserver and qmail.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"><li class="listitem"> <a name="daemontools-download" id="daemontools-download"></a><p> <strong> -<a class="ulink" href="http://cr.yp.to/daemontools/daemontools-0.76.tar.gz" target="_top">Daemontools 0.76</a>, OPTIONAL. </strong>You +<a class="ulink" href="http://cr.yp.to/daemontools/daemontools-0.76.tar.gz" target="_top">Daemontools 0.76</a>, OPTIONAL. </strong> You need this if you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. An alternative would be to run the services from inittab.</p> </li></ul></div> </li><li class="listitem"> <p> -<strong>Mail Transport Agent. </strong>A Mail +<strong>Mail Transport Agent. </strong> A Mail Transport Agent is a program that handles all incoming and outgoing mail. The Reference Platform uses Qmail; any MTA that provides a sendmail wrapper (that is, that can be invoked by calling the sendmail program with the same variables that sendmail expects) can be used.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"><p> <a name="qmail-download" id="qmail-download"></a><strong> -<a class="ulink" href="http://www.qmail.org/netqmail/" target="_top">Netqmail 1.04</a>, -OPTIONAL. </strong>You need this (or a different Mail -Transport Agent) if you want your webserver to send and receive -email.</p></li><li class="listitem"><p> +<a class="ulink" href="http://www.qmail.org/netqmail/" target="_top">Netqmail 1.04</a>, OPTIONAL. </strong> +You need this (or a different Mail Transport Agent) if you want +your webserver to send and receive email.</p></li><li class="listitem"><p> <a name="ucspi-download" id="ucspi-download"></a><strong> -<a class="ulink" href="http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz" target="_top">ucspi-tcp 0.88</a>, OPTIONAL. </strong>This +<a class="ulink" href="http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz" target="_top">ucspi-tcp 0.88</a>, OPTIONAL. </strong> This program listens for incoming TCP connections and hands them to a program. We use it instead of inetd, which is insecure. You need this if you are running qmail.</p></li> </ul></div> </li><li class="listitem"><p> <strong> -<a class="ulink" href="http://www.docbook.org/" target="_top">DocBook</a>, OPTIONAL. </strong>(docbook-xml +<a class="ulink" href="http://www.docbook.org/" target="_top">DocBook</a>, OPTIONAL. </strong> (docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need this to write or edit documentation.</p></li><li class="listitem"> <p> -<strong>Source Control. </strong>A Source Control +<strong>Source Control. </strong> A Source Control system keeps track of all of the old versions of your files. It lets you recover old files, compare versions of file, and identify specific versions of files. You can use any source control system; the Reference Platform and the OpenACS.org repository (where you can get patched and development code in between releases) use cvs.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"><li class="listitem"><p> <strong> -<a class="ulink" href="https://www.cvshome.org/" target="_top">cvs</a> 1.11.18, OPTIONAL. </strong>cvs is +<a class="ulink" href="https://www.cvshome.org/" target="_top">cvs</a> 1.11.18, OPTIONAL. </strong> cvs is included in most unix distributions. You need this if you want to track old versions of your files, do controlled deployment of code from development to production, or get or contribute development code from openacs.org.</p></li></ul></div> </li> -</ul></div><div class="cvstag">($‌Id: software.xml,v 1.26.2.6 2017/06/17 -10:15:42 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: software.xml,v 1.27 2017/08/07 +23:47:55 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="install-steps" leftLabel="Prev" leftTitle="Basic Steps" Index: openacs-4/packages/acs-core-docs/www/individual-programs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/individual-programs.html,v diff -u -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/individual-programs.html 7 Aug 2017 23:47:50 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/individual-programs.html 8 Nov 2017 09:42:10 -0000 1.35 @@ -1,33 +1,86 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Prerequisite Software</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-overview.html" title="Chapter 2. Installation Overview"><link rel="previous" href="install-steps.html" title="Basic Steps"><link rel="next" href="complete-install.html" title="Chapter 3. Complete Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-steps.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installation Overview</th><td width="20%" align="right"> <a accesskey="n" href="complete-install.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="individual-programs"></a>Prerequisite Software</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Prerequisite Software</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-overview.html" title="Chapter 2. Installation Overview"><link rel="previous" href="install-steps.html" title="Basic Steps"><link rel="next" href="complete-install.html" title="Chapter 3. Complete Installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-steps.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installation Overview</th><td width="20%" align="right"> <a accesskey="n" href="complete-install.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="individual-programs"></a>Prerequisite Software</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <p> OpenACS requires, at a minimum, an operating system, database, and webserver to work. Many additional programs, such as a build environment, Mail Transport Agent, and source control system, are also needed for a fully effective installation. - </p><div class="table"><a name="compatibility-matrix"></a><p class="title"><b>Table 2.2. Version Compatibility Matrix</b></p><div class="table-contents"><table class="table" summary="Version Compatibility Matrix" cellspacing="0" border="1"><colgroup><col class="c1"><col class="c2"><col class="3.2.5"><col class="4.5"><col class="4.6"><col class="4.6.1"><col class="4.6.2"><col class="4.6.3"><col class="5.0"><col class="5.1"></colgroup><thead><tr><th colspan="2" align="center">OpenACS Version</th><th>3.2.5</th><th> 4.5 </th><th> 4.6 </th><th>4.6.1</th><th>4.6.2</th><th>4.6.3</th><th>5.0</th><th>5.1</th><th>5.2</th><th>5.3</th><th>5.4</th><th>5.5</th></tr></thead><tbody><tr><td rowspan="8">AOLserver</td><td>3</td><td bgcolor="lightgreen" align="center">Yes</td><td bgcolor="red" colspan="11" align="center">No</td></tr><tr><td>3.3+ad13</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="7" align="center">Yes</td><td bgcolor="red" colspan="4" align="center">No</td></tr><tr><td>3.3oacs1</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="7" align="center">Yes</td><td bgcolor="red" colspan="4" align="center">No</td></tr><tr><td>3.4.4</td><td bgcolor="red" colspan="12" align="center">No</td></tr><tr><td>3.4.4oacs1</td><td bgcolor="yellow" colspan="4" align="center">Maybe</td><td bgcolor="lightgreen" colspan="2" align="center">Yes</td><td bgcolor="red" colspan="6" align="center">No</td></tr><tr><td>3.5.5</td><td bgcolor="yellow" colspan="4" align="center">Maybe</td><td bgcolor="lightgreen" colspan="2" align="center">Yes</td><td bgcolor="red" colspan="6" align="center">No</td></tr><tr><td>4.0</td><td bgcolor="yellow" colspan="4" align="center">Maybe</td><td bgcolor="lightgreen" colspan="8" align="center">Yes</td></tr><tr><td>4.5</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td rowspan="2">Tcl</td><td>8.4</td><td bgcolor="lightgreen" colspan="12" align="center">Yes</td></tr><tr><td>8.5.4 -</td><td bgcolor="yellow" colspan="12" align="center">Maybe</td></tr><tr><td rowspan="8">PostgreSQL</td><td>7.0</td><td bgcolor="lightgreen" align="center">Yes</td><td bgcolor="red" colspan="11" align="center">No</td></tr><tr><td>7.2</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="5" align="center">Yes</td><td bgcolor="red" colspan="6" align="center">No</td></tr><tr><td>7.3.2 - 7.3.x</td><td bgcolor="red" colspan="5" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td><td bgcolor="red" colspan="3" align="center">No</td></tr><tr><td>7.4</td><td bgcolor="red" colspan="6" align="center">No</td><td bgcolor="lightgreen" colspan="3" align="center">Yes</td><td bgcolor="red" colspan="3" align="center">No</td></tr><tr><td>8.0</td><td bgcolor="red" colspan="7" align="center">No</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td>8.1</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td>8.2</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="yellow" align="center">CVS version only</td><td bgcolor="lightgreen" colspan="3" align="center">Yes</td></tr><tr><td>8.3</td><td bgcolor="red" colspan="11" align="center">No</td><td bgcolor="lightgreen" align="center">Yes</td></tr><tr><td rowspan="5">Oracle</td><td>8.1.6</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="8" align="center">Yes</td><td bgcolor="yellow" colspan="3" align="center">Maybe</td></tr><tr><td>8.1.7</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="8" align="center">Yes</td><td bgcolor="yellow" colspan="3" align="center">Maybe</td></tr><tr><td>9i</td><td bgcolor="red" colspan="6" align="center">No</td><td bgcolor="lightgreen" colspan="6" align="center">Yes</td></tr><tr><td>10g</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td>11g</td><td bgcolor="red" colspan="11" align="center">No</td><td bgcolor="yellow" align="center">Maybe</td></tr></tbody></table></div></div><br class="table-break"><p>The OpenACS installation instructions assume the operating system and build environment are installed. + </p> + + <div class="table"><a name="compatibility-matrix"></a><p class="title"><b>Table 2.2. Version Compatibility Matrix</b></p><div class="table-contents"> + + <table class="table" summary="Version Compatibility Matrix" cellspacing="0" border="1"><colgroup><col class="c1"><col class="c2"><col class="3.2.5"><col class="4.5"><col class="4.6"><col class="4.6.1"><col class="4.6.2"><col class="4.6.3"><col class="5.0"><col class="5.1"></colgroup><thead><tr><th colspan="2" align="center">OpenACS Version</th><th>3.2.5</th><th> 4.5 </th><th> 4.6 </th><th>4.6.1</th><th>4.6.2</th><th>4.6.3</th><th>5.0</th><th>5.1</th><th>5.2</th><th>5.3</th><th>5.4</th><th>5.5</th></tr></thead><tbody><tr><td rowspan="8">AOLserver</td><td>3</td><td bgcolor="lightgreen" align="center">Yes</td><td bgcolor="red" colspan="11" align="center">No</td></tr><tr><td>3.3+ad13</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="7" align="center">Yes</td><td bgcolor="red" colspan="4" align="center">No</td></tr><tr><td>3.3oacs1</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="7" align="center">Yes</td><td bgcolor="red" colspan="4" align="center">No</td></tr><tr><td>3.4.4</td><td bgcolor="red" colspan="12" align="center">No</td></tr><tr><td>3.4.4oacs1</td><td bgcolor="yellow" colspan="4" align="center">Maybe</td><td bgcolor="lightgreen" colspan="2" align="center">Yes</td><td bgcolor="red" colspan="6" align="center">No</td></tr><tr><td>3.5.5</td><td bgcolor="yellow" colspan="4" align="center">Maybe</td><td bgcolor="lightgreen" colspan="2" align="center">Yes</td><td bgcolor="red" colspan="6" align="center">No</td></tr><tr><td>4.0</td><td bgcolor="yellow" colspan="4" align="center">Maybe</td><td bgcolor="lightgreen" colspan="8" align="center">Yes</td></tr><tr><td>4.5</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td rowspan="2">Tcl</td><td>8.4</td><td bgcolor="lightgreen" colspan="12" align="center">Yes</td></tr><tr><td>8.5.4 -</td><td bgcolor="yellow" colspan="12" align="center">Maybe</td></tr><tr><td rowspan="8">PostgreSQL</td><td>7.0</td><td bgcolor="lightgreen" align="center">Yes</td><td bgcolor="red" colspan="11" align="center">No</td></tr><tr><td>7.2</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="5" align="center">Yes</td><td bgcolor="red" colspan="6" align="center">No</td></tr><tr><td>7.3.2 - 7.3.x</td><td bgcolor="red" colspan="5" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td><td bgcolor="red" colspan="3" align="center">No</td></tr><tr><td>7.4</td><td bgcolor="red" colspan="6" align="center">No</td><td bgcolor="lightgreen" colspan="3" align="center">Yes</td><td bgcolor="red" colspan="3" align="center">No</td></tr><tr><td>8.0</td><td bgcolor="red" colspan="7" align="center">No</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td>8.1</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td>8.2</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="yellow" align="center">CVS version only</td><td bgcolor="lightgreen" colspan="3" align="center">Yes</td></tr><tr><td>8.3</td><td bgcolor="red" colspan="11" align="center">No</td><td bgcolor="lightgreen" align="center">Yes</td></tr><tr><td rowspan="5">Oracle</td><td>8.1.6</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="8" align="center">Yes</td><td bgcolor="yellow" colspan="3" align="center">Maybe</td></tr><tr><td>8.1.7</td><td bgcolor="yellow" align="center">Maybe</td><td bgcolor="lightgreen" colspan="8" align="center">Yes</td><td bgcolor="yellow" colspan="3" align="center">Maybe</td></tr><tr><td>9i</td><td bgcolor="red" colspan="6" align="center">No</td><td bgcolor="lightgreen" colspan="6" align="center">Yes</td></tr><tr><td>10g</td><td bgcolor="red" colspan="8" align="center">No</td><td bgcolor="lightgreen" colspan="4" align="center">Yes</td></tr><tr><td>11g</td><td bgcolor="red" colspan="11" align="center">No</td><td bgcolor="yellow" align="center">Maybe</td></tr></tbody></table> + </div></div><br class="table-break"> + <p>The OpenACS installation instructions assume the operating system and build environment are installed. The instructions explain installation of Tcl, Tcllib, tDOM, tclwebtest, a Web Server, a Database, a Process Controller, and Source Control software. The following external links are for reference only. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a name="openacs-download"></a><p><b><a class="ulink" href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 5.9.0</a>. </b>The OpenACS tarball comprises the core packages and + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><a name="openacs-download"></a><p><b><a class="ulink" href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 5.9.0</a>. </b> + The OpenACS tarball comprises the core packages and many useful additional packages. This includes a full set of documentation. The tarball works with both PostgreSQL - and Oracle. Some scripts require bash shell.</p></li><li class="listitem"><p><b>Operating System. </b>OpenACS is designed for a Unix-like system. It is + and Oracle. Some scripts require bash shell. + </p> + </li><li class="listitem"> + <p> + <b>Operating System. </b> + OpenACS is designed for a Unix-like system. It is developed primarily in Linux. It can be run on Mac OS X, - and in Windows within VMWare.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>GNU/Linux. </b>The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer.</p></li><li class="listitem"><p><b>FreeBSD. </b><a class="ulink" href="https://web.archive.org/web/20011204174701/http://www.orchardlabs.com:80/freebsd/" target="_top">FreeBSD guide</a>. The OpenACS Reference Platform uses shell scripts written for bash, which is the + and in Windows within VMWare. + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p> + <b>GNU/Linux. </b> + The installation assumes a linux kernel of 2.2.22 or newer, or 2.4.14 or newer. + </p> + </li><li class="listitem"> + <p> + <b>FreeBSD. </b> + <a class="ulink" href="https://web.archive.org/web/20011204174701/http://www.orchardlabs.com:80/freebsd/" target="_top">FreeBSD guide</a>. The OpenACS Reference Platform uses shell scripts written for bash, which is the standard Linux shell. If you are using a different shell, you will need to substitute your shell's conventions for setting environment variables when appropriate, and install bash to work with the scripts. Substitute <strong class="userinput"><code>fetch</code></strong> when the instructions suggest you use - <strong class="userinput"><code>wget</code></strong> to download software.</p></li><li class="listitem"><p><b>Mac OS X. </b><a class="xref" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X">the section called “OpenACS Installation Guide for Mac OS X”</a></p></li><li class="listitem"><p><b>Windows/VMWare. </b><a class="xref" href="win2k-installation.html" title="OpenACS Installation Guide for Windows">the section called “OpenACS Installation Guide for Windows”</a> The only + <strong class="userinput"><code>wget</code></strong> to download software. + </p> + </li><li class="listitem"> + <p> + <b>Mac OS X. </b> + <a class="xref" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X">the section called “OpenACS Installation Guide for Mac OS X”</a> + </p> + </li><li class="listitem"> + <p> + <b>Windows/VMWare. </b> + <a class="xref" href="win2k-installation.html" title="OpenACS Installation Guide for Windows">the section called “OpenACS Installation Guide for Windows”</a> The only way to run OpenACS on Windows is through the VMWare emulator. (Please let me know if you have OpenACS - running directly in Windows.)</p></li></ul></div></li><li class="listitem"><p><b>Build Environment. </b>The Reference Platform installation compiles most programs from - source code.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b><a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> 2.2 or newer, REQUIRED. </b>You need recent versions of these libraries for + running directly in Windows.) + </p> + </li></ul></div> + </li><li class="listitem"> + <p> + <b>Build Environment. </b> + The Reference Platform installation compiles most programs from + source code. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p> + <b><a class="ulink" href="http://www.gnu.org/software/libc/libc.html" target="_top">glibc</a> 2.2 or newer, REQUIRED. </b> + You need recent versions of these libraries for Oracle to work properly. For Unicode support, you need glibc 2.2 or newer. This should be included in your - operating system distribution.</p></li><li class="listitem"><p><b><a class="ulink" href="http://www.gnu.org/software/make/" target="_top">GNU Make</a> 3.76.1 or newer, REQUIRED. </b>PostgreSQL and AOLserver require gmake to + operating system distribution. + </p> + </li><li class="listitem"> + <p> + <b><a class="ulink" href="http://www.gnu.org/software/make/" target="_top">GNU Make</a> 3.76.1 or newer, REQUIRED. </b> + PostgreSQL and AOLserver require gmake to compile. Note that on most linux distributions, GNU Make is simply named <code class="computeroutput">make</code> and @@ -36,30 +89,81 @@ whereas on BSD distributions, <code class="computeroutput">make</code> and <code class="computeroutput">gmake</code> are - different --use gmake.</p></li></ul></div></li><li class="listitem"><p><b><a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x. </b></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b><a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x, REQUIRED. </b>OpenACS is written in Tcl, an interpreted + different --use gmake. + </p> + </li></ul></div> + </li><li class="listitem"> + <p> + <b><a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x. </b> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p> + <b><a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x, REQUIRED. </b> + OpenACS is written in Tcl, an interpreted language. A threaded version of the Tcl interpreter must be installed for OpenACS to work. The Tcl interpreter that is included in most standard - distributions may not be thread safe. </p></li><li class="listitem"><p><b><a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x development headers and libraries, OPTIONAL. </b> The site-wide-search service, OpenFTS, requires these to + distributions may not be thread safe. + </p> + </li><li class="listitem"> + <p> + <b><a class="ulink" href="http://www.tcl.tk/" target="_top">Tcl</a> 8.5.x development headers and libraries, OPTIONAL. </b> + The site-wide-search service, OpenFTS, requires these to compile. (Debian users: <code class="computeroutput">apt-get install tcl8.5-dev</code>). You need this - to install OpenFTS.</p></li></ul></div></li><li class="listitem"><a name="source-tcllib"></a><p><b><a class="ulink" href="http://tcllib.sourceforge.net/" target="_top">Tcllib</a>, REQUIRED. </b> + to install OpenFTS. + </p> + </li></ul></div> + </li><li class="listitem"><a name="source-tcllib"></a> + <p> + <b><a class="ulink" href="http://tcllib.sourceforge.net/" target="_top">Tcllib</a>, REQUIRED. </b> + OpenACS 5.9.0 uses those Tcl extensions to send e-mail out, among others. - </p></li><li class="listitem"><a name="source-tdom"></a><p><b><a class="ulink" href="http://www.tdom.org/" target="_top">tDOM</a>, REQUIRED. </b>OpenACS 5.9.0 stores + + </p> + </li><li class="listitem"><a name="source-tdom"></a> + <p> + <b><a class="ulink" href="http://www.tdom.org/" target="_top">tDOM</a>, REQUIRED. </b> + OpenACS 5.9.0 stores queries in XML files, so we use an AOLserver module called tDOM to parse these files. (This replaces libxml2, which - was used prior to 4.6.4.)</p></li><li class="listitem"><a name="source-tclwebtest"></a><p><b><a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=31075" target="_top">tclwebtest</a>, OPTIONAL. </b>tclwebtest is a tool for testing web interfaces via Tcl scripts.</p></li><li class="listitem"><p><b>Web Server. </b>The web server handles incoming HTTP requests, provides + was used prior to 4.6.4.) + </p> + </li><li class="listitem"><a name="source-tclwebtest"></a> + <p> + <b><a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=31075" target="_top">tclwebtest</a>, OPTIONAL. </b> + tclwebtest is a tool for testing web interfaces via Tcl scripts. + </p> + </li><li class="listitem"> + <p> + <b>Web Server. </b> + The web server handles incoming HTTP requests, provides a runtime environment for OpenACS's Tcl code, connects to the database, sends out HTTP responses, and logs requests and errors. OpenACS uses AOLserver; - <a class="ulink" href="http://openacs.org/forums/message-view?message_id=21461" target="_top">some people have had success running Apache with mod_nsd</a>.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><a name="source-aolserver"></a><p><b><a class="ulink" href="http://aolserver.com/" target="_top">AOLserver</a> 4.x, REQUIRED. </b>Provides the base HTTP server</p></li></ul></div><p> + <a class="ulink" href="http://openacs.org/forums/message-view?message_id=21461" target="_top">some people have had success running Apache with mod_nsd</a>. + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><a name="source-aolserver"></a> + <p> + <b><a class="ulink" href="http://aolserver.com/" target="_top">AOLserver</a> 4.x, REQUIRED. </b> + Provides the base HTTP server + </p> + </li></ul></div> + + <p> Mat Kovach is graciously maintaining an AOLserver distribution that includes all the patches and modules needed to run OpenACS 5.9.0. These instructions will describe how to install using his source distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and perhaps more to come), currently located at <a class="ulink" href="http://uptime.openacs.org/aolserver-openacs/" target="_top">uptime.openacs.org</a>. - </p><p> + </p> + + <p> It's also possible to download all the pieces and patches yourself: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> AOLserver is available at <a class="ulink" href="http://aolserver.com" target="_top">aolserver.com</a> </p></li><li class="listitem"><p> The OpenACS PostgreSQL driver (nspostgres.so) is available from @@ -79,53 +183,149 @@ The patch that makes AOLserver 3.x respect the <code class="computeroutput">-g</code> flag is available at <a class="ulink" href="http://sourceforge.net/tracker/index.php?func=detail&aid=509413&group_id=3152&atid=303152" target="_top">sourceforge.net</a> - </p></li></ul></div></li><li class="listitem"><a name="nsopenssl-download"></a><p><b>nsopenssl, OPTIONAL. </b>Provides SSL capabilities for AOLserver. It requires + </p></li></ul></div> + </li><li class="listitem"><a name="nsopenssl-download"></a> + <p> + <b>nsopenssl, OPTIONAL. </b> + Provides SSL capabilities for AOLserver. It requires OpenSSL. You need this if you want users to make secure (https) connections to your webserver. aolserver3.x requires <a class="ulink" href="http://www.scottg.net/download/nsopenssl-2.1a.tar.gz" target="_top">nsopenssl 2.1a</a>. aolserver4.x requires nsopenssl3; see <a class="ulink" href="http://www.aolserver.com/" target="_top">aolserver.com</a> for latest release. (<a class="ulink" href="http://panoptic.com/wiki/aolserver/Nsopenssl" target="_top">home page</a>) - </p></li><li class="listitem"><a name="nspam-download"></a><p><b><a class="ulink" href="http://wayback.archive.org/web/20050228071203/http://braindamage.alal.com/software/nspam.html" target="_top">ns_pam</a> 0.1 or newer, OPTIONAL. </b>Provides PAM capabilities for AOLserver. You + + </p> + </li><li class="listitem"><a name="nspam-download"></a> + <p> + <b><a class="ulink" href="http://wayback.archive.org/web/20050228071203/http://braindamage.alal.com/software/nspam.html" target="_top">ns_pam</a> 0.1 or newer, OPTIONAL. </b> + Provides PAM capabilities for AOLserver. You need this if you want OpenACS users to authenticate - through a PAM module (such as RADIUS).</p></li><li class="listitem"><a name="pam-radius-download"></a><p><b><a class="ulink" href="ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar" target="_top">pam_radius 1.3.16</a>, OPTIONAL. </b>Provides RADIUS capabilities for PAM. You need - this if you want to use RADIUS authentication via PAM in OpenACS.</p></li><li class="listitem"><a name="nsldap-download"></a><p><b><a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=3152" target="_top">ns_ldap 0.r8</a>, OPTIONAL. </b>Provides LDAP capabilities for AOLserver. You need - this if you want to use LDAP authentication in OpenACS.</p></li><li class="listitem"><a name="openfts-download"></a><p><b><a class="ulink" href="http://unc.dl.sourceforge.net/sourceforge/openfts/Search-OpenFTS-tcl-0.3.2.tar.gz" target="_top">OpenFTS - Tcl 0.3.2</a>, OPTIONAL. </b>Adds + through a PAM module (such as RADIUS). + </p> + </li><li class="listitem"><a name="pam-radius-download"></a> + <p> + <b><a class="ulink" href="ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar" target="_top">pam_radius 1.3.16</a>, OPTIONAL. </b> + Provides RADIUS capabilities for PAM. You need + this if you want to use RADIUS authentication via PAM in OpenACS. + </p> + </li><li class="listitem"><a name="nsldap-download"></a> + <p> + <b><a class="ulink" href="http://sourceforge.net/project/showfiles.php?group_id=3152" target="_top">ns_ldap 0.r8</a>, OPTIONAL. </b> + Provides LDAP capabilities for AOLserver. You need + this if you want to use LDAP authentication in OpenACS. + </p> + </li><li class="listitem"><a name="openfts-download"></a> + <p> + <b><a class="ulink" href="http://unc.dl.sourceforge.net/sourceforge/openfts/Search-OpenFTS-tcl-0.3.2.tar.gz" target="_top">OpenFTS + Tcl 0.3.2</a>, OPTIONAL. </b> Adds full-text-search to PostgreSQL and includes a driver for AOLserver. You need this if you want users to be able to search for any text on your site. For postgres 7.4.x and higher, full text search is also available via tsearch2. - </p></li><li class="listitem"><p><a name="analog-download"></a><b><a class="ulink" href="http://www.analog.cx/" target="_top">Analog</a> 5.32 or newer, OPTIONAL. </b>This program examines web server request logs, looks up + + </p> + </li><li class="listitem"> + <p><a name="analog-download"></a> + <b><a class="ulink" href="http://www.analog.cx/" target="_top">Analog</a> 5.32 or newer, OPTIONAL. </b> + This program examines web server request logs, looks up DNS values, and produces a report. You need this if you - want to see how much traffic your site is getting.</p></li><li class="listitem"><p><a name="balance-download"></a><b><a class="ulink" href="http://sourceforge.net/projects/balance/" target="_top">Balance</a> 3.11 or newer, OPTIONAL. </b>"Balance is a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system.</p></li><li class="listitem"><p><b>Database. </b>The data on your site (for example, user names and passwords, + want to see how much traffic your site is getting. + </p> + </li><li class="listitem"> + <p><a name="balance-download"></a> + <b><a class="ulink" href="http://sourceforge.net/projects/balance/" target="_top">Balance</a> 3.11 or newer, OPTIONAL. </b> + "Balance is a simple but powerful generic tcp proxy with round robin load balancing and failover mechanisms." You need this or something equivalent if you are running a high-availability production site and do not have an external load balancing system. + </p> + </li><li class="listitem"> + <p> + <b>Database. </b> + The data on your site (for example, user names and passwords, calender entries, and notes) is stored in the database. OpenACS separates the database with an abstraction layer, which means that several different databases all function identically. While you can run the core OpenACS on any supported database, not all contributed packages support all - databases.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED). </b>You can register and download Oracle from <a class="ulink" href="https://www.oracle.com/downloads/index.html" target="_top">Oracle + databases. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + + <p> + <b>Oracle 8.1.7 (Either this or PostgreSQL is REQUIRED). </b> + You can register and download Oracle from <a class="ulink" href="https://www.oracle.com/downloads/index.html" target="_top">Oracle TechNet</a>. You need this if you want to use an - Oracle database.</p></li><li class="listitem"><p><a name="source-postgresql"></a><b><a class="ulink" href="http://sourceforge.net/projects/pgsql/" target="_top">PostgreSQL</a> 7.4.x (Either this or Oracle is REQUIRED). </b>You need this if you want to use a PostgreSQL database.</p></li></ul></div></li><li class="listitem"><p><b>Process Controller. </b>This is software that initiates other software, and + Oracle database. + </p> + </li><li class="listitem"> + <p><a name="source-postgresql"></a> + <b><a class="ulink" href="http://sourceforge.net/projects/pgsql/" target="_top">PostgreSQL</a> 7.4.x (Either this or Oracle is REQUIRED). </b> + You need this if you want to use a PostgreSQL database. + </p> + </li></ul></div> + </li><li class="listitem"> + <p> + <b>Process Controller. </b> + This is software that initiates other software, and restarts that software if it fails. On Linux, we recommend - using Daemontools to control AOLserver and qmail.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><a name="daemontools-download"></a><p><b><a class="ulink" href="http://cr.yp.to/daemontools/daemontools-0.76.tar.gz" target="_top">Daemontools - 0.76</a>, OPTIONAL. </b>You need this if + using Daemontools to control AOLserver and qmail. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><a name="daemontools-download"></a> + <p> + <b><a class="ulink" href="http://cr.yp.to/daemontools/daemontools-0.76.tar.gz" target="_top">Daemontools + 0.76</a>, OPTIONAL. </b> You need this if you want AOLserver and qmail to run "supervised," meaning that they are monitored and automatically restarted if they fail. An alternative would be to - run the services from inittab.</p></li></ul></div></li><li class="listitem"><p><b>Mail Transport Agent. </b>A Mail Transport Agent is a program that handles all + run the services from inittab. + </p> + </li></ul></div> + </li><li class="listitem"> + <p> + <b>Mail Transport Agent. </b> + A Mail Transport Agent is a program that handles all incoming and outgoing mail. The Reference Platform uses Qmail; any MTA that provides a sendmail wrapper (that is, that can be invoked by calling the sendmail program with the - same variables that sendmail expects) can be used.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a name="qmail-download"></a><b><a class="ulink" href="http://www.qmail.org/netqmail/" target="_top">Netqmail 1.04</a>, OPTIONAL. </b>You need this (or a different Mail Transport - Agent) if you want your webserver to send and receive email.</p></li><li class="listitem"><p><a name="ucspi-download"></a><b><a class="ulink" href="http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz" target="_top">ucspi-tcp 0.88</a>, OPTIONAL. </b>This program listens for incoming TCP connections and + same variables that sendmail expects) can be used. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p><a name="qmail-download"></a> + <b><a class="ulink" href="http://www.qmail.org/netqmail/" target="_top">Netqmail 1.04</a>, OPTIONAL. </b> + You need this (or a different Mail Transport + Agent) if you want your webserver to send and receive email. + </p> + </li><li class="listitem"> + <p><a name="ucspi-download"></a> + <b><a class="ulink" href="http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz" target="_top">ucspi-tcp 0.88</a>, OPTIONAL. </b> + This program listens for incoming TCP connections and hands them to a program. We use it instead of inetd, - which is insecure. You need this if you are running qmail.</p></li></ul></div></li><li class="listitem"><p><b><a class="ulink" href="http://www.docbook.org/" target="_top">DocBook</a>, OPTIONAL. </b>(docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, + which is insecure. You need this if you are running qmail. + </p> + </li></ul></div> + </li><li class="listitem"> + <p> + <b><a class="ulink" href="http://www.docbook.org/" target="_top">DocBook</a>, OPTIONAL. </b> + (docbook-xml v4.4, docbook-xsl v1.56, libxslt 1.0.21, xsltproc 1.0.21). You need this to write or edit documentation. - </p></li><li class="listitem"><p><b>Source Control. </b>A Source Control system keeps track of all of the old + + </p> + </li><li class="listitem"> + <p> + <b>Source Control. </b> + A Source Control system keeps track of all of the old versions of your files. It lets you recover old files, compare versions of file, and identify specific versions of files. You can use any source control system; the Reference Platform and the OpenACS.org repository (where you can - get patched and development code in between releases) use cvs.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b><a class="ulink" href="https://www.cvshome.org/" target="_top">cvs</a> 1.11.18, OPTIONAL. </b>cvs is included in most unix distributions. You + get patched and development code in between releases) use cvs. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p> + <b><a class="ulink" href="https://www.cvshome.org/" target="_top">cvs</a> 1.11.18, OPTIONAL. </b> + cvs is included in most unix distributions. You need this if you want to track old versions of your files, do controlled deployment of code from development - to production, or get or contribute development code from openacs.org.</p></li></ul></div></li></ul></div><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-steps.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="complete-install.html">Next</a></td></tr><tr><td width="40%" align="left">Basic Steps </td><td width="20%" align="center"><a accesskey="u" href="install-overview.html">Up</a></td><td width="40%" align="right"> Chapter 3. Complete Installation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + to production, or get or contribute development code from openacs.org. + </p> + </li></ul></div> + </li></ul></div> + <p><span class="cvstag">($Id$)</span></p> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-steps.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="complete-install.html">Next</a></td></tr><tr><td width="40%" align="left">Basic Steps </td><td width="20%" align="center"><a accesskey="u" href="install-overview.html">Up</a></td><td width="40%" align="right"> Chapter 3. Complete Installation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-cvs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-cvs.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-cvs.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -10,13 +10,13 @@ rightLink="psgml-for-emacs" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="install-cvs" id="install-cvs"></a>Initialize CVS (OPTIONAL)</h2></div></div></div><a class="indexterm" name="idp140592107194328" id="idp140592107194328"></a><p>CVS is a source control system. Create and initialize a +<a name="install-cvs" id="install-cvs"></a>Initialize CVS (OPTIONAL)</h2></div></div></div><a class="indexterm" name="idp140623161616552" id="idp140623161616552"></a><p>CVS is a source control system. Create and initialize a directory for a local cvs repository.</p><pre class="screen"> [root tmp]# <strong class="userinput"><code>mkdir /cvsroot</code></strong> [root tmp]#<strong class="userinput"><code> cvs -d /cvsroot init</code></strong> [root tmp]# -<span class="action"><span class="action">mkdir /cvsroot -cvs -d /cvsroot init</span></span> +<span class="action">mkdir /cvsroot +cvs -d /cvsroot init</span> </pre> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/install-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-cvs.html,v diff -u -r1.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/install-cvs.html 7 Aug 2017 23:47:50 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/install-cvs.html 8 Nov 2017 09:42:10 -0000 1.42 @@ -1,7 +1,12 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Initialize CVS (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="openacs-unpack.html" title="Unpack the OpenACS tarball"><link rel="next" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-cvs"></a>Initialize CVS (OPTIONAL)</h2></div></div></div><a class="indexterm" name="idp140592107194328"></a><p>CVS is a source control system. Create and initialize a - directory for a local cvs repository.</p><pre class="screen">[root tmp]# <strong class="userinput"><code>mkdir /cvsroot</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Initialize CVS (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="openacs-unpack.html" title="Unpack the OpenACS tarball"><link rel="next" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-cvs"></a>Initialize CVS (OPTIONAL)</h2></div></div></div> + + <a class="indexterm" name="idp140623161616552"></a> + <p>CVS is a source control system. Create and initialize a + directory for a local cvs repository.</p> + <pre class="screen">[root tmp]# <strong class="userinput"><code>mkdir /cvsroot</code></strong> [root tmp]#<strong class="userinput"><code> cvs -d /cvsroot init</code></strong> [root tmp]# -<span class="action"><span class="action">mkdir /cvsroot -cvs -d /cvsroot init</span></span></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr><tr><td width="40%" align="left">Unpack the OpenACS tarball </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Add PSGML commands to emacs init file (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<span class="action">mkdir /cvsroot +cvs -d /cvsroot init</span></pre> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-unpack.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="psgml-for-emacs.html">Next</a></td></tr><tr><td width="40%" align="left">Unpack the OpenACS tarball </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Add PSGML commands to emacs init file (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-daemontools.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-daemontools.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-daemontools.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -16,7 +16,7 @@ svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific services.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> -<p>Install Daemontools</p><a class="indexterm" name="idp140592107210552" id="idp140592107210552"></a><p> +<p>Install Daemontools</p><a class="indexterm" name="idp140623170211560" id="idp140623170211560"></a><p> <a class="link" href="individual-programs">download daemontools</a> and install it.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> @@ -33,12 +33,12 @@ Adding svscanboot to inittab... init should start svscan now. [root root]# -<span class="action"><span class="action">mkdir -p /package +<span class="action">mkdir -p /package chmod 1755 /package cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/install</span></span> +package/install</span> </pre> </li><li class="listitem"> <p>Red Hat 9, Fedora Core 1-4</p><p>Make sure you have the source tarball in <code class="computeroutput">/tmp</code>, or <a class="link" href="individual-programs">download @@ -68,15 +68,15 @@ Adding svscanboot to inittab... init should start svscan now. [root root]# -<span class="action"><span class="action">mkdir -p /package +<span class="action">mkdir -p /package chmod 1755 /package cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin wget http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch cd daemontools-0.76 patch -p1 < ../daemontools-0.76.errno.patch -package/install</span></span> +package/install</span> </pre> </li><li class="listitem"> <p>FreeBSD (follow standard install)</p><p>Make sure you have the source tarball in <code class="computeroutput">/tmp</code>, or <a class="link" href="individual-programs">download @@ -92,12 +92,12 @@ Adding svscanboot to inittab... init should start svscan now. [root root]# -<span class="action"><span class="action">mkdir -p /package +<span class="action">mkdir -p /package chmod 1755 /package cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/install</span></span> +package/install</span> </pre> </li><li class="listitem"> <p>Debian</p><pre class="screen"> @@ -118,8 +118,8 @@ <p>Install a script to grant non-root users permission to control daemontools services.</p><pre class="screen"> [root root]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup</code></strong> -[root root]# <strong class="userinput"><code>chmod 755 /usr/local/bin/svgroup</code></strong><span class="action"><span class="action">cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup -chmod 755 /usr/local/bin/svgroup</span></span> +[root root]# <strong class="userinput"><code>chmod 755 /usr/local/bin/svgroup</code></strong><span class="action">cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup +chmod 755 /usr/local/bin/svgroup</span> </pre> </li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/install-daemontools.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-daemontools.html,v diff -u -r1.42 -r1.43 --- openacs-4/packages/acs-core-docs/www/install-daemontools.html 7 Aug 2017 23:47:50 -0000 1.42 +++ openacs-4/packages/acs-core-docs/www/install-daemontools.html 8 Nov 2017 09:42:10 -0000 1.43 @@ -1,10 +1,19 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Daemontools (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"><link rel="next" href="install-qmail.html" title="Install qmail (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-daemontools"></a>Install Daemontools (OPTIONAL)</h2></div></div></div><p>Daemontools is a collection of programs for controlling +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Daemontools (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)"><link rel="next" href="install-qmail.html" title="Install qmail (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-daemontools"></a>Install Daemontools (OPTIONAL)</h2></div></div></div> + + <p>Daemontools is a collection of programs for controlling other processes. We use daemontools to run and monitor AOLserver. It is installed in /package. These commands install daemontools and svgroup. svgroup is a script for granting permissions, to allow users other than root to use daemontools for specific - services.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install Daemontools</p><a class="indexterm" name="idp140592107210552"></a><p><a class="link" href="individual-programs.html#daemontools-download">download daemontools</a> and install it.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Red Hat 8</p><pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /package</code></strong> + services.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Install Daemontools</p> + <a class="indexterm" name="idp140623170211560"></a> + <p><a class="link" href="individual-programs.html#daemontools-download">download daemontools</a> and install it.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Red Hat 8</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /package</code></strong> [root root]# <strong class="userinput"><code>chmod 1755 /package/</code></strong> [root root]# <strong class="userinput"><code>cd /package/</code></strong> [root package]# <strong class="userinput"><code>tar xzf /tmp/daemontools-0.76.tar.gz</code></strong> @@ -16,14 +25,18 @@ Adding svscanboot to inittab... init should start svscan now. [root root]# -<span class="action"><span class="action">mkdir -p /package +<span class="action">mkdir -p /package chmod 1755 /package cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/install</span></span></pre></li><li class="listitem"><p>Red Hat 9, Fedora Core 1-4</p><p>Make sure you have the source tarball in +package/install</span></pre> + </li><li class="listitem"> + <p>Red Hat 9, Fedora Core 1-4</p> + <p>Make sure you have the source tarball in <code class="computeroutput">/tmp</code>, or <a class="link" href="individual-programs.html#daemontools-download">download it</a>. -</p><pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /package</code></strong> +</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /package</code></strong> [root root]# <strong class="userinput"><code>chmod 1755 /package/</code></strong> [root root]# <strong class="userinput"><code>cd /package/</code></strong> [root package]# <strong class="userinput"><code>tar xzf /tmp/daemontools-0.76.tar.gz</code></strong> @@ -48,17 +61,21 @@ Adding svscanboot to inittab... init should start svscan now. [root root]# -<span class="action"><span class="action">mkdir -p /package +<span class="action">mkdir -p /package chmod 1755 /package cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin wget http://moni.csi.hu/pub/glibc-2.3.1/daemontools-0.76.errno.patch cd daemontools-0.76 patch -p1 < ../daemontools-0.76.errno.patch -package/install</span></span></pre></li><li class="listitem"><p>FreeBSD (follow standard install)</p><p>Make sure you have the source tarball in +package/install</span></pre> + </li><li class="listitem"> + <p>FreeBSD (follow standard install)</p> + <p>Make sure you have the source tarball in <code class="computeroutput">/tmp</code>, or <a class="link" href="individual-programs.html#daemontools-download">download it</a>. -</p><pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /package</code></strong> +</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /package</code></strong> [root root]# <strong class="userinput"><code>chmod 1755 /package/</code></strong> [root root]# <strong class="userinput"><code>cd /package/</code></strong> [root package]# <strong class="userinput"><code>tar xzf /tmp/daemontools-0.76.tar.gz</code></strong> @@ -69,18 +86,30 @@ Adding svscanboot to inittab... init should start svscan now. [root root]# -<span class="action"><span class="action">mkdir -p /package +<span class="action">mkdir -p /package chmod 1755 /package cd /package tar xzf /tmp/daemontools-0.76.tar.gz cd admin/daemontools-0.76 -package/install</span></span></pre></li><li class="listitem"><p>Debian</p><pre class="screen">[root ~]# <strong class="userinput"><code>apt-get install daemontools-installer</code></strong> -[root ~]# <strong class="userinput"><code>build-daemontools</code></strong></pre></li></ul></div></li><li class="listitem"><p>Verify that svscan is running. If it is, you should see - these two processes running:</p><pre class="screen">[root root]# <strong class="userinput"><code>ps -auxw | grep service</code></strong> +package/install</span></pre> + </li><li class="listitem"> + <p>Debian</p> + <pre class="screen">[root ~]# <strong class="userinput"><code>apt-get install daemontools-installer</code></strong> +[root ~]# <strong class="userinput"><code>build-daemontools</code></strong></pre> + </li></ul></div> + </li><li class="listitem"> + <p>Verify that svscan is running. If it is, you should see + these two processes running:</p> + <pre class="screen">[root root]# <strong class="userinput"><code>ps -auxw | grep service</code></strong> root 13294 0.0 0.1 1352 272 ? S 09:51 0:00 svscan /service root 13295 0.0 0.0 1304 208 ? S 09:51 0:00 readproctitle service errors: ....................................... -[root root]#</pre></li><li class="listitem"><p>Install a script to grant non-root users permission to - control daemontools services.</p><pre class="screen">[root root]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup</code></strong> +[root root]#</pre> + </li><li class="listitem"> + <p>Install a script to grant non-root users permission to + control daemontools services.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup</code></strong> [root root]# <strong class="userinput"><code>chmod 755 /usr/local/bin/svgroup</code></strong> -<span class="action"><span class="action">cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup -chmod 755 /usr/local/bin/svgroup</span></span></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr><tr><td width="40%" align="left">Add PSGML commands to emacs init file (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install qmail (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<span class="action">cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/svgroup.txt /usr/local/bin/svgroup +chmod 755 /usr/local/bin/svgroup</span></pre> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-for-emacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-qmail.html">Next</a></td></tr><tr><td width="40%" align="left">Add PSGML commands to emacs init file (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install qmail (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -7,159 +7,33 @@ title=" Appendix B. Install additional supporting software" - rightLink="install-full-text-search-openfts" rightLabel="Next"> + rightLink="install-nsopenssl" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="install-full-text-search-tsearch2" id="install-full-text-search-tsearch2"></a>Install Full Text Search -using Tsearch2</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:dave\@thedesignexperience.org" target="_top">Dave Bauer</a>, <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> and -<a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> with help from <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/docs/tsearch-V2-intro.html" target="_top">Tsearch V2 Introduction by Andrew J. Kopciuch</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +using Tsearch2</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:dave\@thedesignexperience.org" target="_top">Dave Bauer</a>, +<a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> and <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> +with help from <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/docs/tsearch-V2-intro.html" target="_top">Tsearch V2 Introduction by Andrew J. +Kopciuch</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="install-tsearch2" id="install-tsearch2"></a>Install Tsearch2 module</h3></div></div></div><a class="indexterm" name="idp140592107348664" id="idp140592107348664"></a><p>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 tsearch2 -module form PostgreSQL contrib. This is included with the -PostgreSQL full source distribution. It is also available with the -PostgreSQL contrib package provided by most distribution packages. -On debian it is called postgresql-contrib.</p><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"><p>For PostgreSQL 7.3 or 7.4, download the -http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz -tsearch2 patch to correctly restore from a pg_dump backup. If you -installed tsearch2 from a package, you can use the -http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql -regprocedure script to update the database after tsearch2 is -installed into it. TODO link to section describing how to fix an -existing tsearch2 database with this patch.</p></li><li class="listitem"> -<p>As of May 9, 2004 there is a source patch available for -tsearch2. The patch provides changes to the pg_ts_ configuration -tables to allow for easy dump and restore of a database containing -tsearch2. The patch is available here : <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz" target="_top">[http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz]</a> -</p><p>To apply this patch, download the mentioned file and place it in -your postgreSQL source tree ($PGSQL_SRC). This patch makes the -backup and restore procedures very simple.</p><pre class="screen"> - [postgres pgsql]$ <strong class="userinput"><code>cd /tmp</code></strong> - [postgres tmp]$ <strong class="userinput"><code>wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz</code></strong> - [postgres pgsql]$ <strong class="userinput"><code>cd /usr/local/src/postgresql-7.4.5/</code></strong> - [postgres postgresql-7.4.5] <strong class="userinput"><code>gunzip /tmp/regprocedure_7.4.patch.gz</code></strong> - [postgres postgresql-7.4.5] <strong class="userinput"><code>patch -b -p1 < regprocedure_7.4.patch</code></strong> -</pre><p>If you have a working version of tsearch2 in your database, you -do not need to re-install the tsearch2 module. Just apply the patch -and run make. This patch only affects the tsearch2.sql file. You -can run the SQL script found : <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql" target="_top">[right here]</a> This script will make the -modifications found in the patch, and update the fields from the -existing data. From this point on, you can dump and restore the -database in a normal fashion. Without this patch, you must follow -the instructions later in this document for backup and restore.</p><p>This patch is only needed for tsearch2 in PostgreSQL versions -7.3.x and 7.4.x. The patch has been applied to the sources for -8.0.</p> -</li><li class="listitem"> -<p>Install Tsearch2. This is a PostgreSQL module that the -tsearch2-driver OpenACS package requires. These instructions assume -you are using the latest point release of PostgreSQL 7.4.5.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - postgres</code></strong> -[postgres pgsql]$ <strong class="userinput"><code>cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/</code></strong> -[postgres tsearch2]$ <strong class="userinput"><code>make</code></strong> -[postgres tsearch2]$ <strong class="userinput"><code>make install</code></strong> -mkdir /usr/local/pgsql/share/contrib -mkdir /usr/local/pgsql/doc/contrib -(2 lines omitted) -/bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so -[postgres tsearch]$ <strong class="userinput"><code>exit</code></strong> -logout - -[root root]# -<span class="action"><span class="action">su - postgres -cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2 -make -make install -exit</span></span> -</pre> -</li> -</ol></div> -</div><div class="sect2"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="install-fts-engine" id="install-fts-engine"></a>Install Full Text Search Engine Package in -OpenACS</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Admin</span></span></code> on the -top of the default home page. If prompted, log in with the account -and password you entered during install.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install -software</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install new -service</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install</span></span></code> link -next to Tsearch2 Driver. If you have installed tsearch2 into your -PostgreSQL database, the installer will automatically enable -tsearch in your OpenACS database instance.</p></li><li class="listitem"> -<p>Restart the service.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ -</pre> -</li><li class="listitem"><p>Wait a minute, then browse back to the home page.</p></li><li class="listitem"><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Admin</span></span></code> on the -top of the screen.</p></li><li class="listitem"><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Main Site -Administration</span></span></code> in the "Subsite -Administration" section.</p></li><li class="listitem"><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Site Map</span></span></code> in -the "Advanced Features" section.</p></li><li class="listitem"> -<p>Mount the Search interface in the site map.</p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p>Click the <code class="computeroutput"><span class="guilabel"><span class="guilabel">new sub -folder</span></span></code> link on the Main Site line.</p></li><li class="listitem"><p>Type <strong class="userinput"><code>search</code></strong> and -click <code class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></code>.</p></li><li class="listitem"><p>Click the <code class="computeroutput"><span class="guilabel"><span class="guilabel">new -application</span></span></code> link on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">search</span></span></code> line.</p></li><li class="listitem"><p>Type <strong class="userinput"><code>search</code></strong> -where it says <code class="computeroutput"><span class="guilabel"><span class="guilabel">untitled</span></span></code>, -choose <code class="computeroutput"><span class="guilabel"><span class="guilabel">search</span></span></code> from -the drop-down list, and click <code class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></code>.</p></li><li class="listitem"><p>Click the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Parameters</span></span></code> -link next to the Search package istance.</p></li><li class="listitem"><p>Type <strong class="userinput"><code>tsearch2-driver</code></strong> where it says -<code class="computeroutput"><span class="guilabel"><span class="guilabel">openfts-driver</span></span></code> in the <code class="computeroutput"><span class="guilabel"><span class="guilabel">FtsEngineDriver</span></span></code> parameter.</p></li> -</ol></div> -</li><li class="listitem"> -<p>Restart the service.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ -</pre> -</li><li class="listitem"><p>Wait a minute, then click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Main -Site</span></span></code> at the top of the page.</p></li> -</ol></div> -</div><div class="sect2"> -<div class="titlepage"><div><div><h3 class="title"> -<a name="install-fts-content-provider" id="install-fts-content-provider"></a>Enable Full Text Search in -packages</h3></div></div></div><p>Enabling Full Text Search in packages at the moment is not -trivial. It involves a couple of steps, which I will illustrate -taking lars-blogger as an example package</p><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"> -<p>Install the package.</p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Admin</span></span></code> on the -top of the default home page. If prompted, log in with the account -and password you entered during install.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install -software</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install new -application</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install</span></span></code> link -next to Weblogger.</p></li><li class="listitem"><p>Install all required packages as well (always say okay until you -shall restart the server)</p></li> -</ol></div> -</li><li class="listitem"> -<p>Load the service contracts datamodell and enable the service -contract</p><pre class="screen"> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd packages/lars-blogger/sql/postgresql</code></strong> -[$OPENACS_SERVICE_NAME postgresql]$ psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f lars-blogger-sc-create.sql -</pre><p>Note: Usually this script is called <span class="replaceable"><span class="replaceable">package_name</span></span>-sc-create.sql</p> -</li><li class="listitem"> -<p>Restart the service.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code></strong> - [$OPENACS_SERVICE_NAME postgresl]$ -</pre> -</li> -</ol></div><p>If you are lucky, Full Text Search is enabled now, if not -consult <a class="ulink" href="http://openacs.org/forums/message-view?message_id=154759" target="_top">http://openacs.org/forums/message-view?message_id=154759</a>. -This link also contains some hints on how to make sure it is -enabled.</p> +<a name="install-tsearch2" id="install-tsearch2"></a>Install Tsearch2 module</h3></div></div></div><a class="indexterm" name="idp140623176482456" id="idp140623176482456"></a><p>In earlier versions of PostgreSQL (7.4), tsearch2 was a contrib +module. With PostgreSQL 9.*, it was included in the standard +PostgreSQL package with minor naming changes (e.g. the function +"rank" became "ts_rank"). PostgreSQL 9 included +a backward compatibility module named "tsearch2". Newer +OpenACS installations (at least 5.9.0 or newer) do not need the +compatiblity package. In PostgreSQL 10 the tsearch2 compatiblity +package has been removed.</p><p>On new OpenACS installations for PostgreSQL, install the +tsearch2-driver package via "/acs-admin/install/" and +mount the search package under "/search" via +"/admin/site-map" if necessary.</p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="install-nspam" leftLabel="Prev" leftTitle="Install nspam" - rightLink="install-full-text-search-openfts" rightLabel="Next" rightTitle="Install Full Text Search using -OpenFTS (deprecated see tsearch2)" + rightLink="install-nsopenssl" rightLabel="Next" rightTitle="Install nsopenssl" homeLink="index" homeLabel="Home" upLink="install-more-software" upLabel="Up"> \ No newline at end of file Index: openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 7 Aug 2017 23:47:50 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/install-full-text-search-tsearch2.html 8 Nov 2017 09:42:10 -0000 1.13 @@ -1,108 +1,31 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Full Text Search using Tsearch2</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-nspam.html" title="Install nspam"><link rel="next" href="install-full-text-search-openfts.html" title="Install Full Text Search using OpenFTS (deprecated see tsearch2)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-nspam.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-full-text-search-openfts.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-full-text-search-tsearch2"></a>Install Full Text Search using Tsearch2</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:dave@thedesignexperience.org" target="_top">Dave +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Full Text Search using Tsearch2</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-nspam.html" title="Install nspam"><link rel="next" href="install-nsopenssl.html" title="Install nsopenssl"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-nspam.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-nsopenssl.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-full-text-search-tsearch2"></a>Install Full Text Search using Tsearch2</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:dave@thedesignexperience.org" target="_top">Dave Bauer</a>, <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a> and <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a> with help from <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/docs/tsearch-V2-intro.html" target="_top">Tsearch V2 Introduction by Andrew J. Kopciuch</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-tsearch2"></a>Install Tsearch2 module</h3></div></div></div><a class="indexterm" name="idp140592107348664"></a><p>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 tsearch2 module form PostgreSQL - contrib. This is included with the PostgreSQL full source - distribution. It is also available with the PostgreSQL contrib - package provided by most distribution packages. On debian it is - called postgresql-contrib.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>For PostgreSQL 7.3 or 7.4, download the - http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz - tsearch2 patch - to correctly restore from a pg_dump backup. If you installed - tsearch2 from a package, you can use the - http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql - regprocedure script to update the database after tsearch2 is - installed into it. TODO link to section describing how to fix - an existing tsearch2 database with this patch.</p></li><li class="listitem"><p>As of May 9, 2004 there is a source patch available - for - tsearch2. The patch provides changes to the pg_ts_ - configuration - tables to allow for easy dump and restore of a database - containing - tsearch2. The patch is available here : <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz" target="_top"> - [http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz]</a></p><p>To apply this patch, download the mentioned file and - place it in your postgreSQL source tree ($PGSQL_SRC). This - patch makes the backup and restore procedures very - simple.</p><pre class="screen"> - [postgres pgsql]$ <strong class="userinput"><code>cd /tmp</code></strong> - [postgres tmp]$ <strong class="userinput"><code>wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz</code></strong> - [postgres pgsql]$ <strong class="userinput"><code>cd /usr/local/src/postgresql-7.4.5/</code></strong> - [postgres postgresql-7.4.5] <strong class="userinput"><code>gunzip /tmp/regprocedure_7.4.patch.gz</code></strong> - [postgres postgresql-7.4.5] <strong class="userinput"><code>patch -b -p1 < regprocedure_7.4.patch</code></strong> - </pre><p>If you have a working version of tsearch2 in your - database, you - do not need to re-install the tsearch2 module. Just - apply the patch - and run make. This patch only affects the tsearch2.sql - file. You - can run the SQL script found : <a class="ulink" href="http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql" target="_top"> - [right here]</a> This script will make the - modifications found in - the patch, and update the fields from the existing - data. From this - point on, you can dump and restore the database in a - normal - fashion. Without this patch, you must follow the - instructions later - in this document for backup and restore.</p><p>This patch is only needed for tsearch2 in PostgreSQL - versions - 7.3.x and 7.4.x. The patch has been applied to the - sources for - 8.0.</p></li><li class="listitem"><p>Install Tsearch2. This is a PostgreSQL module - that the tsearch2-driver OpenACS package requires. These - instructions assume you are using the latest point - release of PostgreSQL 7.4.5.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - postgres</code></strong> -[postgres pgsql]$ <strong class="userinput"><code>cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/</code></strong> -[postgres tsearch2]$ <strong class="userinput"><code>make</code></strong> -[postgres tsearch2]$ <strong class="userinput"><code>make install</code></strong> -mkdir /usr/local/pgsql/share/contrib -mkdir /usr/local/pgsql/doc/contrib -(2 lines omitted) -/bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so -[postgres tsearch]$ <strong class="userinput"><code>exit</code></strong> -logout + </authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-tsearch2"></a>Install Tsearch2 module</h3></div></div></div> + + <a class="indexterm" name="idp140623176482456"></a> + <p>In earlier versions of PostgreSQL (7.4), tsearch2 was a contrib + module. With PostgreSQL 9.*, it was included in the standard + PostgreSQL package with minor naming changes (e.g. the function + "rank" became "ts_rank"). PostgreSQL 9 included a backward + compatibility module named "tsearch2". Newer OpenACS + installations (at least 5.9.0 or newer) do not + need the compatiblity package. In PostgreSQL 10 the tsearch2 + compatiblity package has been removed. + </p> + <p> + On new OpenACS installations for PostgreSQL, install the + tsearch2-driver package via "/acs-admin/install/" and mount the + search package under "/search" via "/admin/site-map" if + necessary. + </p> -[root root]# -<span class="action"><span class="action">su - postgres -cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2 -make -make install -exit</span></span></pre></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-fts-engine"></a>Install Full Text Search Engine Package in OpenACS</h3></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Admin</span></span></code> on the top of the default home page. If prompted, log in with the account and password you entered during install.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install -software</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install -new service</span></span></code> link.</p></li><li class="listitem"><p>Click on the - <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install</span></span></code> - link next to Tsearch2 Driver. If you have installed tsearch2 - into your PostgreSQL database, the installer will - automatically enable tsearch in your OpenACS database instance.</p></li><li class="listitem"><p>Restart the service.</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre></li><li class="listitem"><p>Wait a minute, then browse back to the home page.</p></li><li class="listitem"><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Admin</span></span></code> on the top of the screen.</p></li><li class="listitem"><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Main Site Administration</span></span></code> in the "Subsite Administration" section.</p></li><li class="listitem"><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Site Map</span></span></code> in the "Advanced Features" section.</p></li><li class="listitem"><p>Mount the Search interface in the site map.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Click the -<code class="computeroutput"><span class="guilabel"><span class="guilabel">new sub folder</span></span></code> link on the -Main Site line. </p></li><li class="listitem"><p>Type <strong class="userinput"><code>search</code></strong> -and click <code class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></code>. </p></li><li class="listitem"><p>Click the <code class="computeroutput"><span class="guilabel"><span class="guilabel">new -application</span></span></code> link on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">search</span></span></code> - line. </p></li><li class="listitem"><p>Type <strong class="userinput"><code>search</code></strong> -where it says -<code class="computeroutput"><span class="guilabel"><span class="guilabel">untitled</span></span></code>, choose -<code class="computeroutput"><span class="guilabel"><span class="guilabel">search</span></span></code> from the -drop-down list, and click -<code class="computeroutput"><span class="guibutton"><span class="guibutton">New</span></span></code>. -</p></li><li class="listitem"><p>Click the -<code class="computeroutput"><span class="guilabel"><span class="guilabel">Parameters</span></span></code> link - next to the Search package istance.</p></li><li class="listitem"><p>Type <strong class="userinput"><code>tsearch2-driver</code></strong> -where it says -<code class="computeroutput"><span class="guilabel"><span class="guilabel">openfts-driver</span></span></code> - in the - <code class="computeroutput"><span class="guilabel"><span class="guilabel">FtsEngineDriver</span></span></code> parameter. -</p></li></ol></div></li><li class="listitem"><p>Restart the service.</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre></li><li class="listitem"><p>Wait a minute, then click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Main Site</span></span></code> at the top of the page.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-fts-content-provider"></a>Enable Full Text Search in packages</h3></div></div></div><p>Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install the package. - </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Admin</span></span></code> on the top of the default home page. If prompted, log in with the account and password you entered during install.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install - software</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install - new application</span></span></code> link.</p></li><li class="listitem"><p>Click on the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install</span></span></code> link next to Weblogger.</p></li><li class="listitem"><p>Install all required packages as well (always say okay until you shall restart the server)</p></li></ol></div><p> - </p></li><li class="listitem"><p>Load the service contracts datamodell and enable the service contract</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd packages/lars-blogger/sql/postgresql</code></strong> -[$OPENACS_SERVICE_NAME postgresql]$ psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f lars-blogger-sc-create.sql</pre><p>Note: Usually this script is called <span class="replaceable"><span class="replaceable">package_name</span></span>-sc-create.sql</p></li><li class="listitem"><p>Restart the service.</p><pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> - [$OPENACS_SERVICE_NAME postgresl]$</pre></li></ol></div><p>If you are lucky, Full Text Search is enabled now, if not consult <a class="ulink" href="http://openacs.org/forums/message-view?message_id=154759" target="_top">http://openacs.org/forums/message-view?message_id=154759</a>. This link also contains some hints on how to make sure it is enabled.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-nspam.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-full-text-search-openfts.html">Next</a></td></tr><tr><td width="40%" align="left">Install nspam </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Full Text Search using OpenFTS (deprecated see tsearch2)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-nspam.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-nsopenssl.html">Next</a></td></tr><tr><td width="40%" align="left">Install nspam </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install nsopenssl</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-ldap-radius.adp 8 Nov 2017 09:42:10 -0000 1.3 @@ -11,17 +11,15 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="install-ldap-radius" id="install-ldap-radius"></a>Install LDAP for use as external -authentication</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This step by step guide on how to use LDAP for external +authentication</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte +Sussdorff</a> +</span></p><span style="color: red"></authorblurb></span><p>This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> <a name="install-openldap" id="install-openldap"></a><p> -<strong>Install openldap. </strong>Download and +<strong>Install openldap. </strong> Download and install ns_ldap</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/src/</code></strong> [root src]# <strong class="userinput"><code>wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz</code></strong> @@ -30,35 +28,35 @@ [root src]# <strong class="userinput"><code>./configure --prefix=/usr/local/openldap</code></strong> [root openldap]# <strong class="userinput"><code>make install</code></strong> [root openldap]# -<span class="action"><span class="action">cd /usr/local/src/ +<span class="action">cd /usr/local/src/ wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz tar xvfz openldap-2.2.17.tgz cd openldap-2.2.17 ./configure --prefix=/usr/local/openldap --disable-slapd make install -</span></span> +</span> </pre> </li><li class="listitem"> <a name="install-ns_ldap" id="install-ns_ldap"></a><p> -<strong>Install ns_ldap. </strong>Download and +<strong>Install ns_ldap. </strong> Download and install ns_ldap</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver/</code></strong> [root aolserver]# <strong class="userinput"><code>wget http://www.sussdorff.de/ressources/nsldap.tgz</code></strong> [root aolserver]# <strong class="userinput"><code>tar xfz nsldap.tgz</code></strong> [root aolserver]# <strong class="userinput"><code>cd nsldap</code></strong> [root ns_pam-0.1]# <strong class="userinput"><code>make install LDAP=/usr/local/openldap INST=/usr/local/aolserver</code></strong> [root ns_pam-0.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver/ +<span class="action">cd /usr/local/src/aolserver/ wget http://www.sussdorff.de/resources/nsldap.tgz tar xfz nsldap.tgz cd nsldap make install LDAP=/usr/local/openldap INST=/usr/local/aolserver -</span></span> +</span> </pre> </li><li class="listitem"> <a name="configure-ns_ldap" id="configure-ns_ldap"></a><p> <strong>Configure ns_ldap for traditional -use. </strong>Traditionally OpenACS has supported +use. </strong> Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for @@ -73,7 +71,7 @@ </li><li class="listitem"> <a name="configure-ns_ldap-bind" id="configure-ns_ldap-bind"></a><p> <strong>Configure ns_ldap for use with LDAP -bind. </strong>LDAP authentication usually is done by +bind. </strong> LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this Index: openacs-4/packages/acs-core-docs/www/install-ldap-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ldap-radius.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 7 Aug 2017 23:47:50 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/install-ldap-radius.html 8 Nov 2017 09:42:10 -0000 1.12 @@ -1,33 +1,61 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install LDAP for use as external authentication</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-pam-radius.html" title="Install PAM Radius for use as external authentication"><link rel="next" href="aolserver.html" title="Install AOLserver 3.3oacs1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-pam-radius.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-ldap-radius"></a>Install LDAP for use as external authentication</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a name="install-openldap"></a><p><b>Install openldap. </b>Download and install ns_ldap</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install LDAP for use as external authentication</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-pam-radius.html" title="Install PAM Radius for use as external authentication"><link rel="next" href="aolserver.html" title="Install AOLserver 3.3oacs1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-pam-radius.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-ldap-radius"></a>Install LDAP for use as external authentication</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> + </authorblurb></span> + + <p>This step by step guide on how to use LDAP for external authentication using the LDAP bind command, which differs from the approach usually taken by auth-ldap. Both will be dealt with in these section</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a name="install-openldap"></a> + <p> + <b>Install openldap. </b> + Download and install ns_ldap + </p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/</code></strong> [root src]# <strong class="userinput"><code>wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz</code></strong> [root src]# <strong class="userinput"><code>tar xvfz openldap-2.2.17.tgz</code></strong> [root src]# <strong class="userinput"><code>cd openldap-2.2.17</code></strong> [root src]# <strong class="userinput"><code>./configure --prefix=/usr/local/openldap</code></strong> [root openldap]# <strong class="userinput"><code>make install</code></strong> [root openldap]# -<span class="action"><span class="action">cd /usr/local/src/ +<span class="action">cd /usr/local/src/ wget ftp://ftp.openldap.org/pub/OpenLDAP/openldap-release/openldap-2.2.17.tgz tar xvfz openldap-2.2.17.tgz cd openldap-2.2.17 ./configure --prefix=/usr/local/openldap --disable-slapd make install -</span></span> - </pre></li><li class="listitem"><a name="install-ns_ldap"></a><p><b>Install ns_ldap. </b>Download and install ns_ldap</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver/</code></strong> +</span> + </pre> + </li><li class="listitem"><a name="install-ns_ldap"></a> + <p> + <b>Install ns_ldap. </b> + Download and install ns_ldap + </p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver/</code></strong> [root aolserver]# <strong class="userinput"><code>wget http://www.sussdorff.de/ressources/nsldap.tgz</code></strong> [root aolserver]# <strong class="userinput"><code>tar xfz nsldap.tgz</code></strong> [root aolserver]# <strong class="userinput"><code>cd nsldap</code></strong> [root ns_pam-0.1]# <strong class="userinput"><code>make install LDAP=/usr/local/openldap INST=/usr/local/aolserver</code></strong> [root ns_pam-0.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver/ +<span class="action">cd /usr/local/src/aolserver/ wget http://www.sussdorff.de/resources/nsldap.tgz tar xfz nsldap.tgz cd nsldap make install LDAP=/usr/local/openldap INST=/usr/local/aolserver -</span></span> - </pre></li><li class="listitem"><a name="configure-ns_ldap"></a><p><b>Configure ns_ldap for traditional use. </b>Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the <span class="emphasis"><em>username</em></span>stored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +</span> + </pre> + </li><li class="listitem"><a name="configure-ns_ldap"></a> + <p> + <b>Configure ns_ldap for traditional use. </b> + Traditionally OpenACS has supported ns_ldap for authentification by storing the OpenACS password in an encrypted field within the LDAP server called "userPassword". Furthermore a CN field was used for searching for the username, usually userID or something similar. This field is identical to the <span class="emphasis"><em>username</em></span>stored in OpenACS. Therefore the login will only work if you change login method to make use of the username instead. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Change <span class="emphasis"><em>config.tcl</em></span>. Remove the <span class="emphasis"><em>#</em></span> in front of <code class="computeroutput">ns_param nsldap ${bindir}/nsldap.so</code> to enable the loading of the ns_ldap module. - </p></li></ul></div></li><li class="listitem"><a name="configure-ns_ldap-bind"></a><p><b>Configure ns_ldap for use with LDAP bind. </b>LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the <span class="emphasis"><em>ns_ldap bind</em></span> command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it).</p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-pam-radius.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr><tr><td width="40%" align="left">Install PAM Radius for use as external authentication </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install AOLserver 3.3oacs1</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p></li></ul></div> + </li><li class="listitem"><a name="configure-ns_ldap-bind"></a> + <p> + <b>Configure ns_ldap for use with LDAP bind. </b> + LDAP authentication usually is done by trying to bind (aka. login) a user with the LDAP server. The password of the user is not stored in any field of the LDAP server, but kept internally. The latest version of ns_ldap supports this method with the <span class="emphasis"><em>ns_ldap bind</em></span> command. All you have to do to enable this is to configure auth_ldap to make use of the BIND authentification instead. Alternatively you can write a small script on how to calculate the username out of the given input (e.g. if the OpenACS username is malte.fb03.tu, the LDAP request can be translated into "ou=malte,ou=fb03,o=tu" (this example is encoded in auth_ldap and you just have to comment it out to make use of it). + </p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-pam-radius.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="aolserver.html">Next</a></td></tr><tr><td width="40%" align="left">Install PAM Radius for use as external authentication </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install AOLserver 3.3oacs1</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-more-software.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-more-software.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-more-software.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -22,8 +22,7 @@ (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2">Install Full Text Search -using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-openfts">Install Full Text Search -using OpenFTS (deprecated see tsearch2)</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl">Install +using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail">Install @@ -33,11 +32,9 @@ LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver">Install AOLserver 3.3oacs1</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This section assumes that the source tarballs for supporting +</div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><p>This section assumes that the source tarballs for supporting software are in <code class="computeroutput">/tmp</code>. It assumes that you begin each continuous block of commands as root, and you should end each block as root. It doesn't care which Index: openacs-4/packages/acs-core-docs/www/install-more-software.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-more-software.html,v diff -u -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/install-more-software.html 7 Aug 2017 23:47:50 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/install-more-software.html 8 Nov 2017 09:42:11 -0000 1.24 @@ -1,10 +1,37 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix B. Install additional supporting software</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9"><link rel="next" href="openacs-unpack.html" title="Unpack the OpenACS tarball"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-redhat.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="openacs-unpack.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="install-more-software"></a>Appendix B. Install additional supporting software</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></span></dt><dt><span class="sect1"><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-qmail.html">Install qmail (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install.html">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam.html">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2.html">Install Full Text Search using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-openfts.html">Install Full Text Search using OpenFTS (deprecated see tsearch2)</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl.html">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest.html">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php.html">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail.html">Install Squirrelmail for use as a webmail system for OpenACS</a></span></dt><dt><span class="sect1"><a href="install-pam-radius.html">Install PAM Radius for use as external authentication</a></span></dt><dt><span class="sect1"><a href="install-ldap-radius.html">Install LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver.html">Install AOLserver 3.3oacs1</a></span></dt></dl></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This section assumes that the source tarballs for supporting +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix B. Install additional supporting software</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9"><link rel="next" href="openacs-unpack.html" title="Unpack the OpenACS tarball"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-redhat.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="openacs-unpack.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="install-more-software"></a>Appendix B. Install additional supporting software</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="openacs-unpack.html">Unpack the OpenACS tarball</a></span></dt><dt><span class="sect1"><a href="install-cvs.html">Initialize CVS (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="install-qmail.html">Install qmail (OPTIONAL)</a></span></dt><dt><span class="sect1"><a href="analog-install.html">Install Analog web file analyzer</a></span></dt><dt><span class="sect1"><a href="install-nspam.html">Install nspam</a></span></dt><dt><span class="sect1"><a href="install-full-text-search-tsearch2.html">Install Full Text Search using Tsearch2</a></span></dt><dt><span class="sect1"><a href="install-nsopenssl.html">Install nsopenssl</a></span></dt><dt><span class="sect1"><a href="install-tclwebtest.html">Install tclwebtest.</a></span></dt><dt><span class="sect1"><a href="install-php.html">Install PHP for use in AOLserver</a></span></dt><dt><span class="sect1"><a href="install-squirrelmail.html">Install Squirrelmail for use as a webmail system for OpenACS</a></span></dt><dt><span class="sect1"><a href="install-pam-radius.html">Install PAM Radius for use as external authentication</a></span></dt><dt><span class="sect1"><a href="install-ldap-radius.html">Install LDAP for use as external authentication</a></span></dt><dt><span class="sect1"><a href="aolserver.html">Install AOLserver 3.3oacs1</a></span></dt></dl></div> + + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <p>This section assumes that the source tarballs for supporting software are in <code class="computeroutput">/tmp</code>. It assumes that you begin each continuous block of commands as root, and you should end each block as root. It doesn't care which directory you start in. Text instructions always precede the commands they - refer to.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-redhat.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-unpack.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix A. Install Red Hat 8/9 </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Unpack the OpenACS tarball</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + refer to.</p> + + + + + + + + + + + + + + + + + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-redhat.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="openacs-unpack.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix A. Install Red Hat 8/9 </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Unpack the OpenACS tarball</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-next-add-server.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -11,21 +11,19 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="install-next-add-server" id="install-next-add-server"></a>Running multiple services on one machine</h2></div></div></div><p> -<strong>Services on different ports. </strong>To run -a different service on another port but the same ip, simply repeat -<a class="xref" href="openacs" title="Install OpenACS 5.9.0">Install OpenACS 5.9.0</a> replacing -<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>, and change -the</p><pre class="programlisting"> +<strong>Services on different ports. </strong> To +run a different service on another port but the same ip, simply +repeat <a class="xref" href="openacs" title="Install OpenACS 5.9.0">Install OpenACS 5.9.0</a> replacing +<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>, +and change the</p><pre class="programlisting"> set httpport 8000 set httpsport 8443 </pre><p>to different values.</p><p> -<strong>Services on different host -names. </strong>For example, suppose you want to -support <code class="computeroutput">http://service0.com</code> and -<code class="computeroutput">http://bar.com</code> on the same -machine. The easiest way is to assign each one a different ip -address. Then you can install two services as above, but with -different values for</p><pre class="programlisting"> +<strong>Services on different host names. </strong> +For example, suppose you want to support <code class="computeroutput">http://service0.com</code> and <code class="computeroutput">http://bar.com</code> on the same machine. The +easiest way is to assign each one a different ip address. Then you +can install two services as above, but with different values +for</p><pre class="programlisting"> set hostname [ns_info hostname] set address 127.0.0.1 </pre><p>If you want to install two services with different host names Index: openacs-4/packages/acs-core-docs/www/install-next-add-server.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-add-server.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/install-next-add-server.html 7 Aug 2017 23:47:50 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/install-next-add-server.html 8 Nov 2017 09:42:11 -0000 1.19 @@ -1,19 +1,32 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Running multiple services on one machine</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab"><link rel="next" href="high-avail.html" title="High Availability/High Performance Configurations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-openacs-inittab.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="high-avail.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-next-add-server"></a>Running multiple services on one machine</h2></div></div></div><p><b>Services on different ports. </b>To run a different service on another port but the same +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Running multiple services on one machine</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab"><link rel="next" href="high-avail.html" title="High Availability/High Performance Configurations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-openacs-inittab.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="high-avail.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-next-add-server"></a>Running multiple services on one machine</h2></div></div></div> + + <p> + <b>Services on different ports. </b> + To run a different service on another port but the same ip, simply repeat <a class="xref" href="openacs.html" title="Install OpenACS 5.9.0">Install OpenACS 5.9.0</a> replacing - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>, and change the + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>, and change the </p><pre class="programlisting">set httpport 8000 set httpsport 8443 </pre><p> - to different values.</p><p><b>Services on different host names. </b>For example, suppose you want to support + to different values. + </p> + <p> + <b>Services on different host names. </b> + For example, suppose you want to support <code class="computeroutput">http://service0.com</code> and <code class="computeroutput">http://bar.com</code> on the same machine. The easiest way is to assign each one a different ip address. Then you can install two services as above, but with different values for </p><pre class="programlisting">set hostname [ns_info hostname] set address 127.0.0.1 </pre><p> -</p><p>If you want to install two services with different host + + </p> + + <p>If you want to install two services with different host names sharing the same ip, you'll need nsvhr to redirect requests based on the contents of the tcp headers. See <a class="ulink" href="http://borkware.com/rants/aolserver-vhosting/" target="_top">AOLserver Virtual Hosting with TCP</a> by <a class="ulink" href="mailto:markd@borkware.com" target="_top">markd</a>. -</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-openacs-inittab.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="high-avail.html">Next</a></td></tr><tr><td width="40%" align="left">AOLserver keepalive with inittab </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> High Availability/High Performance Configurations</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-openacs-inittab.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="high-avail.html">Next</a></td></tr><tr><td width="40%" align="left">AOLserver keepalive with inittab </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> High Availability/High Performance Configurations</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-next-backups.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-backups.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-next-backups.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-next-backups.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -23,10 +23,10 @@ that you are more likely to do it.</p></li> </ul></div><p>OpenACS installations comprise files and database contents. If you follow the reference install and put all files, including -configuration files, in <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/</code>, -and back up the database nightly to a file in <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup</code>, +configuration files, in <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/</code>, and +back up the database nightly to a file in <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup</code>, then you can apply standard file-based backup strategies to -<code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code> </p> </div> Index: openacs-4/packages/acs-core-docs/www/install-next-backups.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-backups.html,v diff -u -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/install-next-backups.html 7 Aug 2017 23:47:50 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/install-next-backups.html 8 Nov 2017 09:42:11 -0000 1.14 @@ -1,16 +1,22 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Backup Strategy</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="next" href="snapshot-backup.html" title="Manual backup and recovery"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="snapshot-backup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-next-backups"></a>Backup Strategy</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Backup Strategy</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="next" href="snapshot-backup.html" title="Manual backup and recovery"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="snapshot-backup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-next-backups"></a>Backup Strategy</h2></div></div></div> + + <p> The purpose of backup is to enable recovery. Backup and recovery are always risky; here are some steps that minimize the chance recovery is necessary: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Store everything on a fault-tolerant disk array (RAID 1 or 5 or better). </p></li><li class="listitem"><p> Use battery backup. </p></li><li class="listitem"><p> Use more reliable hardware, such as SCSI instead of IDE. - </p></li></ul></div><p>These steps improve the chances of successful recovery:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p></li></ul></div> + + <p>These steps improve the chances of successful recovery:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Store backups on a third disk on another controller </p></li><li class="listitem"><p> Store backups on a different computer on a different network @@ -24,13 +30,16 @@ </p></li><li class="listitem"><p> Make it easy to maintain and test your recovery strategy, so that you are more likely to do it. - </p></li></ul></div><p> + </p></li></ul></div> + + <p> OpenACS installations comprise files and database contents. If you follow the reference install and put all files, including configuration files, in - <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/</code>, + <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/</code>, and back up the database nightly to a file in - <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup</code>, + <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup</code>, then you can apply standard file-based backup strategies to - <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="snapshot-backup.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 8. Backup and Recovery </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Manual backup and recovery</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> + </p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backup-recovery.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="snapshot-backup.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 8. Backup and Recovery </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Manual backup and recovery</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -26,9 +26,9 @@ [joeuser ~]$ <strong class="userinput"><code>crontab -e</code></strong> </pre><p>We'll set vacuum up to run nightly at 1 AM. Add the following line:</p><pre class="programlisting"> -0 1 * * * /usr/local/pgsql/bin/vacuumdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</pre><div class="cvstag">($‌Id: database-maintenance.xml,v 1.8.14.1 -2016/06/23 08:32:46 gustafn Exp $)</div> +0 1 * * * /usr/local/pgsql/bin/vacuumdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</pre><p><span class="cvstag">($‌Id: database-maintenance.xml,v 1.9 +2017/08/07 23:47:54 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="install-openacs-delete-tablespace" leftLabel="Prev" leftTitle="Deleting a tablespace" Index: openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html,v diff -u -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 7 Aug 2017 23:47:50 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/install-next-nightly-vacuum.html 8 Nov 2017 09:42:11 -0000 1.25 @@ -1,5 +1,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Vacuum Postgres nightly</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="database-management.html" title="Chapter 7. Database Management"><link rel="previous" href="install-openacs-delete-tablespace.html" title="Deleting a tablespace"><link rel="next" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-openacs-delete-tablespace.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Database Management</th><td width="20%" align="right"> <a accesskey="n" href="backup-recovery.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-next-nightly-vacuum"></a>Vacuum Postgres nightly</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Vacuum Postgres nightly</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="database-management.html" title="Chapter 7. Database Management"><link rel="previous" href="install-openacs-delete-tablespace.html" title="Deleting a tablespace"><link rel="next" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-openacs-delete-tablespace.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Database Management</th><td width="20%" align="right"> <a accesskey="n" href="backup-recovery.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-next-nightly-vacuum"></a>Vacuum Postgres nightly</h2></div></div></div> + + <p> The "vacuum" command must be run periodically to reclaim space in versions of PostgreSQL before 7.4. The "vacuum analyze" form additionally collects statistics on the @@ -14,6 +16,15 @@ the key to good system management. So, if you're using the export procedure described above, you don't need to do this extra step. - </p><p>Edit your crontab:</p><pre class="programlisting">[joeuser ~]$ <strong class="userinput"><code>crontab -e</code></strong></pre><p>We'll set vacuum up to run nightly at 1 AM. Add the following - line:</p><pre class="programlisting"> -0 1 * * * /usr/local/pgsql/bin/vacuumdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></pre><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-openacs-delete-tablespace.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-recovery.html">Next</a></td></tr><tr><td width="40%" align="left">Deleting a tablespace </td><td width="20%" align="center"><a accesskey="u" href="database-management.html">Up</a></td><td width="40%" align="right"> Chapter 8. Backup and Recovery</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + <p>Edit your crontab:</p> + <pre class="programlisting">[joeuser ~]$ <strong class="userinput"><code>crontab -e</code></strong></pre> + + <p>We'll set vacuum up to run nightly at 1 AM. Add the following + line:</p> + <pre class="programlisting"> +0 1 * * * /usr/local/pgsql/bin/vacuumdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></pre> + <p><span class="cvstag">($Id$)</span></p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-openacs-delete-tablespace.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="backup-recovery.html">Next</a></td></tr><tr><td width="40%" align="left">Deleting a tablespace </td><td width="20%" align="center"><a accesskey="u" href="database-management.html">Up</a></td><td width="40%" align="right"> Chapter 8. Backup and Recovery</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -3,18 +3,16 @@ <property name="doc(title)">Install nsopenssl</property> <master> <include src="/packages/acs-core-docs/lib/navheader" - leftLink="install-full-text-search-openfts" leftLabel="Prev" + leftLink="install-full-text-search-tsearch2" leftLabel="Prev" title=" Appendix B. Install additional supporting software" rightLink="install-tclwebtest" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="install-nsopenssl" id="install-nsopenssl"></a>Install nsopenssl</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> and <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This AOLserver module is required if you want people to connect +<a name="install-nsopenssl" id="install-nsopenssl"></a>Install nsopenssl</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> and +<a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> +</span></p><span style="color: red"></authorblurb></span><p>This AOLserver module is required if you want people to connect to your site via https. These commands compile nsopenssl and install it, along with a Tcl helper script to handle https connections. You will also need ssl certificates. Because those @@ -36,20 +34,20 @@ [root nsopenssl-2.1]# <strong class="userinput"><code>cp nsopenssl.so /usr/local/aolserver/bin</code></strong> [root nsopenssl-2.1]# <strong class="userinput"><code>cp https.tcl /usr/local/aolserver/modules/tcl/</code></strong> [root nsopenssl-2.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver +<span class="action">cd /usr/local/src/aolserver wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz tar xzf nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/local/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/</span></span> -</pre><p>For Debian (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=93854" target="_top">more information</a>):</p><pre class="screen"><span class="action"><span class="action">apt-get install libssl-dev +cp https.tcl /usr/local/aolserver/modules/tcl/</span> +</pre><p>For Debian (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=93854" target="_top">more information</a>):</p><pre class="screen"><span class="action">apt-get install libssl-dev cd /usr/local/src/aolserver tar xzf /tmp/nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/lib/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/</span></span></pre> +cp https.tcl /usr/local/aolserver/modules/tcl/</span></pre> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="install-nsopenssl-aolserver4" id="install-nsopenssl-aolserver4"></a>Install on AOLserver4</h3></div></div></div><p>You will need the AOLserver4 source in <code class="computeroutput">/usr/local/src/aolserver/aolserver</code> and @@ -70,40 +68,40 @@ <span class="emphasis"><em>(many lines omitted)</em></span> [root nsopenssl-2.1]# <strong class="userinput"><code>make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10</code></strong> [root nsopenssl-2.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver +<span class="action">cd /usr/local/src/aolserver cvs -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/aolserver login cvs -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl cd nsopenssl make OPENSSL=/usr/local/ssl -make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10</span></span> +make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10</span> </pre><p>If you have problems starting your server with nsopenssl.so due to missing libssl.so.0.9.7 (or lower), you have to create symlinks</p><pre class="screen"> [root nsopenssl]# <strong class="userinput"><code>cd /usr/local/aolserver/lib</code></strong> [root lib]# <strong class="userinput"><code>ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7</code></strong> [root lib]# <strong class="userinput"><code>ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7</code></strong> [root lib]# -<span class="action"><span class="action">cd /usr/local/aolserver/lib +<span class="action">cd /usr/local/aolserver/lib ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7 -</span></span> +</span> </pre><p>SSL support must be enabled separately in each OpenACS server (<a class="xref" href="install-ssl">Generate ssl certificates</a>.</p><p>If your ports for SSL are privileged (below 1024), you will have to start AOLserver with prebinds for both your HTTP and your HTTPS -port (usually by adding <code class="computeroutput">-b -<span class="replaceable"><span class="replaceable">your_ip:your_http_port</span></span>,<span class="replaceable"><span class="replaceable">your_ip:your_https_port</span></span> -</code> to the -nsd call. If you are using daemontools, this can be changed in your -<code class="computeroutput">etc/daemontools/run file</code>).</p><p>To enable SSL support in your server, make sure your +port (usually by adding <code class="computeroutput">-b <em class="replaceable"><code>your_ip:your_http_port</code></em>,<em class="replaceable"><code>your_ip:your_https_port</code></em> +</code> to +the nsd call. If you are using daemontools, this can be changed in +your <code class="computeroutput">etc/daemontools/run +file</code>).</p><p>To enable SSL support in your server, make sure your etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If that section is not present, try looking at the README file in <code class="computeroutput">/usr/local/src/aolserver/nsopenssl</code>.</p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" - leftLink="install-full-text-search-openfts" leftLabel="Prev" leftTitle="Install Full Text Search using OpenFTS -(deprecated see tsearch2)" + leftLink="install-full-text-search-tsearch2" leftLabel="Prev" leftTitle="Install Full Text Search using +Tsearch2" rightLink="install-tclwebtest" rightLabel="Next" rightTitle="Install tclwebtest." homeLink="index" homeLabel="Home" upLink="install-more-software" upLabel="Up"> Index: openacs-4/packages/acs-core-docs/www/install-nsopenssl.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nsopenssl.html,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 7 Aug 2017 23:47:50 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/install-nsopenssl.html 8 Nov 2017 09:42:11 -0000 1.28 @@ -1,17 +1,26 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install nsopenssl</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-full-text-search-openfts.html" title="Install Full Text Search using OpenFTS (deprecated see tsearch2)"><link rel="next" href="install-tclwebtest.html" title="Install tclwebtest."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-full-text-search-openfts.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-tclwebtest.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-nsopenssl"></a>Install nsopenssl</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a> and <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This AOLserver module is required if you want people to connect to your site via +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install nsopenssl</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-full-text-search-tsearch2.html" title="Install Full Text Search using Tsearch2"><link rel="next" href="install-tclwebtest.html" title="Install tclwebtest."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-full-text-search-tsearch2.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-tclwebtest.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-nsopenssl"></a>Install nsopenssl</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a> and <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> + </authorblurb></span> + + <p>This AOLserver module is required if you want people to connect to your site via https. These commands compile nsopenssl and install it, along with a Tcl helper script to handle https connections. You will also need ssl certificates. Because those should be different for each server service, you won't need <a class="link" href="install-ssl.html#ssl-certificates">those instructions</a> until - later. </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-nsopenssl-aolserver3"></a>Install on AOLserver3</h3></div></div></div><p> You will need the <a class="link" href="aolserver.html#install-aolserver-compile">unpacked Aolserver tarball</a> in + later. </p> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-nsopenssl-aolserver3"></a>Install on AOLserver3</h3></div></div></div> + + <p> You will need the <a class="link" href="aolserver.html#install-aolserver-compile">unpacked Aolserver tarball</a> in <code class="computeroutput">/usr/local/src/aolserver</code> and the <a class="link" href="individual-programs.html#nsopenssl-download">nsopenssl tarball</a> in - <code class="computeroutput">/tmp</code>.</p><p>Red Hat 9 note: see <a class="ulink" href="http://openacs.org/forums/message-view?message_id=92882" target="_top">this - thread</a> for details on compiling nsopenssl.)</p><pre class="screen">[root bin]#<strong class="userinput"><code> cd /usr/local/src/aolserver</code></strong> + <code class="computeroutput">/tmp</code>.</p> + <p>Red Hat 9 note: see <a class="ulink" href="http://openacs.org/forums/message-view?message_id=92882" target="_top">this + thread</a> for details on compiling nsopenssl.)</p> + + <pre class="screen">[root bin]#<strong class="userinput"><code> cd /usr/local/src/aolserver</code></strong> [root aolserver]# <strong class="userinput"><code>wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>tar xzf nsopenssl-2.1.tar.gz </code></strong> [root aolserver]# <strong class="userinput"><code>cd nsopenssl-2.1</code></strong> @@ -22,21 +31,30 @@ [root nsopenssl-2.1]# <strong class="userinput"><code>cp nsopenssl.so /usr/local/aolserver/bin</code></strong> [root nsopenssl-2.1]# <strong class="userinput"><code>cp https.tcl /usr/local/aolserver/modules/tcl/</code></strong> [root nsopenssl-2.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver +<span class="action">cd /usr/local/src/aolserver wget --passive http://www.scottg.net/download/nsopenssl-2.1.tar.gz tar xzf nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/local/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/</span></span></pre><p>For Debian (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=93854" target="_top">more - information</a>):</p><pre class="screen"><span class="action"><span class="action">apt-get install libssl-dev +cp https.tcl /usr/local/aolserver/modules/tcl/</span></pre> + <p>For Debian (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=93854" target="_top">more + information</a>):</p> +<pre class="screen"><span class="action">apt-get install libssl-dev cd /usr/local/src/aolserver tar xzf /tmp/nsopenssl-2.1.tar.gz cd nsopenssl-2.1 make OPENSSL=/usr/lib/ssl cp nsopenssl.so /usr/local/aolserver/bin -cp https.tcl /usr/local/aolserver/modules/tcl/</span></span></pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-nsopenssl-aolserver4"></a>Install on AOLserver4</h3></div></div></div><p> You will need the AOLserver4 source in <code class="computeroutput">/usr/local/src/aolserver/aolserver</code> and OpenSSL installed in <code class="computeroutput">/usr/local/ssl</code> (or at least symlinked there). The use of <code class="computeroutput">INST=/point/to/aolserver</code> is being replaced with <code class="computeroutput">AOLSERVER=/point/to/aolserver</code>. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.</p><p>FreeBSD note: build nsopenssl with <strong class="userinput"><code>gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10</code></strong> - </p><pre class="screen">[root bin]#<strong class="userinput"><code> cd /usr/local/src/aolserver</code></strong> +cp https.tcl /usr/local/aolserver/modules/tcl/</span></pre> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-nsopenssl-aolserver4"></a>Install on AOLserver4</h3></div></div></div> + + <p> You will need the AOLserver4 source in <code class="computeroutput">/usr/local/src/aolserver/aolserver</code> and OpenSSL installed in <code class="computeroutput">/usr/local/ssl</code> (or at least symlinked there). The use of <code class="computeroutput">INST=/point/to/aolserver</code> is being replaced with <code class="computeroutput">AOLSERVER=/point/to/aolserver</code>. We are including both here, because while this module still requires INST, if one just uses AOLSERVER, the default value would be used and could intefere with another existing installation.</p> + <p>FreeBSD note: build nsopenssl with <strong class="userinput"><code>gmake install OPENSSL=/usr/local/openssl AOLSERVER=/usr/local/aolserver4r10</code></strong> + </p> + + <pre class="screen">[root bin]#<strong class="userinput"><code> cd /usr/local/src/aolserver</code></strong> [root aolserver]# <strong class="userinput"><code>cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login</code></strong> [root aolserver]# <strong class="userinput"><code>cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl</code></strong> [root aolserver]# <strong class="userinput"><code>cd nsopenssl</code></strong> @@ -45,30 +63,40 @@ <span class="emphasis"><em>(many lines omitted)</em></span> [root nsopenssl-2.1]# <strong class="userinput"><code>make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver4r10 INST=/usr/local/aolserver4r10</code></strong> [root nsopenssl-2.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver +<span class="action">cd /usr/local/src/aolserver cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nsopenssl cd nsopenssl make OPENSSL=/usr/local/ssl -make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10</span></span></pre><p>If you have problems starting your server with nsopenssl.so due to missing libssl.so.0.9.7 (or lower), you have to create symlinks +make install OPENSSL=/usr/local/ssl AOLSERVER=/usr/local/aolserver AOLSERVER=/usr/local/aolserver4r10</span></pre> +<p>If you have problems starting your server with nsopenssl.so due to missing libssl.so.0.9.7 (or lower), you have to create symlinks </p><pre class="screen"> [root nsopenssl]# <strong class="userinput"><code>cd /usr/local/aolserver/lib</code></strong> [root lib]# <strong class="userinput"><code>ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7</code></strong> [root lib]# <strong class="userinput"><code>ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7</code></strong> [root lib]# -<span class="action"><span class="action">cd /usr/local/aolserver/lib +<span class="action">cd /usr/local/aolserver/lib ln -s /usr/local/ssl/lib/libssl.so.0.9.7 libssl.so.0.9.7 ln -s /usr/local/ssl/lib/libcrypto.so.0.9.7 libcrypto.so.0.9.7 -</span></span> +</span> </pre><p> -</p><p>SSL support must be enabled separately in each OpenACS - server (<a class="xref" href="install-ssl.html#ssl-certificates">Generate ssl certificates</a>. </p><p>If your ports for SSL are privileged (below 1024), you +</p> + + <p>SSL support must be enabled separately in each OpenACS + server (<a class="xref" href="install-ssl.html#ssl-certificates">Generate ssl certificates</a>. </p> + + <p>If your ports for SSL are privileged (below 1024), you will have to start AOLserver with prebinds for both your HTTP and your HTTPS port (usually by adding <code class="computeroutput">-b - <span class="replaceable"><span class="replaceable">your_ip:your_http_port</span></span>,<span class="replaceable"><span class="replaceable">your_ip:your_https_port</span></span></code> + <em class="replaceable"><code>your_ip:your_http_port</code></em>,<em class="replaceable"><code>your_ip:your_https_port</code></em></code> to the nsd call. If you are using daemontools, this can be changed in your <code class="computeroutput">etc/daemontools/run - file</code>).</p><p>To enable SSL support in your server, make sure your + file</code>).</p> + + <p>To enable SSL support in your server, make sure your etc/config.tcl file has a section on "OpenSSL 3 with AOLserver4". If that section is not present, try looking at the README file in - <code class="computeroutput">/usr/local/src/aolserver/nsopenssl</code>.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-full-text-search-openfts.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-tclwebtest.html">Next</a></td></tr><tr><td width="40%" align="left">Install Full Text Search using OpenFTS (deprecated see tsearch2) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install tclwebtest.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + <code class="computeroutput">/usr/local/src/aolserver/nsopenssl</code>.</p> + </div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-full-text-search-tsearch2.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-tclwebtest.html">Next</a></td></tr><tr><td width="40%" align="left">Install Full Text Search using Tsearch2 </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install tclwebtest.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-nspam.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-nspam.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/install-nspam.html 7 Aug 2017 23:47:50 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/install-nspam.html 8 Nov 2017 09:42:11 -0000 1.19 @@ -1,2 +1,6 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install nspam</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="analog-install.html" title="Install Analog web file analyzer"><link rel="next" href="install-full-text-search-tsearch2.html" title="Install Full Text Search using Tsearch2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="analog-install.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-full-text-search-tsearch2.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-nspam"></a>Install nspam</h2></div></div></div><p><a class="ulink" href="/doc/acs-authentication/ext-auth-install.html" target="_top">/doc/acs-authentication/ext-auth-install.html</a></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analog-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-full-text-search-tsearch2.html">Next</a></td></tr><tr><td width="40%" align="left">Install Analog web file analyzer </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Full Text Search using Tsearch2</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install nspam</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="analog-install.html" title="Install Analog web file analyzer"><link rel="next" href="install-full-text-search-tsearch2.html" title="Install Full Text Search using Tsearch2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="analog-install.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-full-text-search-tsearch2.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-nspam"></a>Install nspam</h2></div></div></div> + + + <p><a class="ulink" href="/doc/acs-authentication/ext-auth-install.html" target="_top">/doc/acs-authentication/ext-auth-install.html</a></p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analog-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-full-text-search-tsearch2.html">Next</a></td></tr><tr><td width="40%" align="left">Install Analog web file analyzer </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Full Text Search using Tsearch2</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -17,19 +17,19 @@ you can use the <code class="computeroutput">drop user</code> command in SVRMGRL with the <code class="computeroutput">cascade</code> option. This command will drop the user and every database object the user owns.</p><pre class="programlisting"> -SVRMGR> <strong class="userinput"><code>drop user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> cascade;</code></strong> +SVRMGR> <strong class="userinput"><code>drop user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cascade;</code></strong> </pre><p>If this does not work because svrmgrl "cannot drop a user that is currently connected", make sure to kill the AOLserver using this user. If it still does not work, do:</p><pre class="programlisting"> -SVRMGR> <strong class="userinput"><code>select username, sid, serial# from v$session where lower(username)='<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>';</code></strong> +SVRMGR> <strong class="userinput"><code>select username, sid, serial# from v$session where lower(username)='<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>';</code></strong> </pre><p>and then</p><pre class="programlisting"> -SVRMGR> <strong class="userinput"><code>alter system kill session '<span class="replaceable"><span class="replaceable">sid, serial#</span></span>';</code></strong> +SVRMGR> <strong class="userinput"><code>alter system kill session '<em class="replaceable"><code>sid, serial#</code></em>';</code></strong> </pre><p>where <span class="emphasis"><em>sid</em></span> and <span class="emphasis"><em>serial#</em></span> are replaced with the corresponding values for the open session.</p><p><span class="strong"><strong>Use with caution!</strong></span></p><p>If you feel the need to delete <span class="emphasis"><em>everything</em></span> related to the service, you can also issue the following:</p><pre class="programlisting"> -SVRMGR> <strong class="userinput"><code>drop tablespace <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> including contents cascade constraints;</code></strong> +SVRMGR> <strong class="userinput"><code>drop tablespace <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> including contents cascade constraints;</code></strong> </pre> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -40,9 +40,9 @@ 'down' flag (-d). If you're using inittab, you have to comment out your server in <code class="computeroutput">/etc/inittab</code>, reread the inittab with <code class="computeroutput">/sbin/init q</code>, and then -<code class="computeroutput">restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<code class="computeroutput">restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code>.</p><p>Then, to drop the db, just do:</p><pre class="programlisting"> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>dropdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>dropdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> DROP DATABASE </pre> Index: openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 7 Aug 2017 23:47:50 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-openacs-delete-tablespace.html 8 Nov 2017 09:42:11 -0000 1.15 @@ -1,25 +1,60 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Deleting a tablespace</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="database-management.html" title="Chapter 7. Database Management"><link rel="previous" href="remote-postgres.html" title="Running a PostgreSQL database on another server"><link rel="next" href="install-next-nightly-vacuum.html" title="Vacuum Postgres nightly"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="remote-postgres.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Database Management</th><td width="20%" align="right"> <a accesskey="n" href="install-next-nightly-vacuum.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-openacs-delete-tablespace"></a>Deleting a tablespace</h2></div></div></div><p>Skip down for instructions on <a class="xref" href="install-openacs-delete-tablespace.html#install-openacs-delete-postgres-tablespace" title="Deleting a PostgreSQL tablespace">Deleting a PostgreSQL tablespace</a>. - </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-delete-oracle-tablespace"></a>Deleting an Oracle tablespace</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Deleting a tablespace</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="database-management.html" title="Chapter 7. Database Management"><link rel="previous" href="remote-postgres.html" title="Running a PostgreSQL database on another server"><link rel="next" href="install-next-nightly-vacuum.html" title="Vacuum Postgres nightly"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="remote-postgres.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Database Management</th><td width="20%" align="right"> <a accesskey="n" href="install-next-nightly-vacuum.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-openacs-delete-tablespace"></a>Deleting a tablespace</h2></div></div></div> + + + <p>Skip down for instructions on <a class="xref" href="install-openacs-delete-tablespace.html#install-openacs-delete-postgres-tablespace" title="Deleting a PostgreSQL tablespace">Deleting a PostgreSQL tablespace</a>. + </p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-delete-oracle-tablespace"></a>Deleting an Oracle tablespace</h3></div></div></div> + + + <p> Should it become necessary to rebuild a tablespace from scratch, you can use the <code class="computeroutput">drop user</code> command in SVRMGRL with the <code class="computeroutput">cascade</code> option. This command will drop the user and every database object - the user owns.</p><pre class="programlisting">SVRMGR> <strong class="userinput"><code>drop user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> cascade;</code></strong></pre><p> + the user owns.</p> + + <pre class="programlisting">SVRMGR> <strong class="userinput"><code>drop user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cascade;</code></strong></pre> + + <p> If this does not work because svrmgrl "cannot drop a user that is currently connected", make sure to kill the AOLserver using - this user. If it still does not work, do:</p><pre class="programlisting">SVRMGR> <strong class="userinput"><code>select username, sid, serial# from v$session where lower(username)='<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>';</code></strong></pre><p>and then</p><pre class="programlisting">SVRMGR> <strong class="userinput"><code>alter system kill session '<span class="replaceable"><span class="replaceable">sid, serial#</span></span>';</code></strong></pre><p> + this user. If it still does not work, do:</p> + + <pre class="programlisting">SVRMGR> <strong class="userinput"><code>select username, sid, serial# from v$session where lower(username)='<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>';</code></strong></pre> + + <p>and then</p> + <pre class="programlisting">SVRMGR> <strong class="userinput"><code>alter system kill session '<em class="replaceable"><code>sid, serial#</code></em>';</code></strong></pre> + + <p> where <span class="emphasis"><em>sid</em></span> and <span class="emphasis"><em>serial#</em></span> are - replaced with the corresponding values for the open session.</p><p><span class="strong"><strong>Use with caution!</strong></span></p><p> + replaced with the corresponding values for the open session.</p> + + <p><span class="strong"><strong>Use with caution!</strong></span></p> + + <p> If you feel the need to delete <span class="emphasis"><em>everything</em></span> - related to the service, you can also issue the following:</p><pre class="programlisting">SVRMGR> <strong class="userinput"><code>drop tablespace <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> including contents cascade constraints;</code></strong></pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-delete-postgres-tablespace"></a>Deleting a PostgreSQL tablespace</h3></div></div></div><p> + related to the service, you can also issue the following:</p> + <pre class="programlisting">SVRMGR> <strong class="userinput"><code>drop tablespace <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> including contents cascade constraints;</code></strong></pre> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-openacs-delete-postgres-tablespace"></a>Deleting a PostgreSQL tablespace</h3></div></div></div> + + + <p> Dropping a PostgreSQL tablespace is easy. You have to stop any AOLserver instances that are using the database that you wish to drop. If you're using daemontools, this is simple, just use the 'down' flag (-d). If you're using inittab, you have to comment out your server in <code class="computeroutput">/etc/inittab</code>, reread the inittab with <code class="computeroutput">/sbin/init q</code>, and then <code class="computeroutput">restart-aolserver - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code>.</p><p>Then, to drop the db, just do:</p><pre class="programlisting"> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>dropdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -DROP DATABASE</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="remote-postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-next-nightly-vacuum.html">Next</a></td></tr><tr><td width="40%" align="left">Running a PostgreSQL database on another server </td><td width="20%" align="center"><a accesskey="u" href="database-management.html">Up</a></td><td width="40%" align="right"> Vacuum Postgres nightly</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code>.</p> + + <p>Then, to drop the db, just do:</p> + <pre class="programlisting"> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>dropdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +DROP DATABASE</pre> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="remote-postgres.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-next-nightly-vacuum.html">Next</a></td></tr><tr><td width="40%" align="left">Running a PostgreSQL database on another server </td><td width="20%" align="center"><a accesskey="u" href="database-management.html">Up</a></td><td width="40%" align="right"> Vacuum Postgres nightly</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 7 Aug 2017 23:47:50 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/install-openacs-inittab.html 8 Nov 2017 09:42:11 -0000 1.15 @@ -1,12 +1,20 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>AOLserver keepalive with inittab</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance."><link rel="next" href="install-next-add-server.html" title="Running multiple services on one machine"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-openacs-keepalive.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="install-next-add-server.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-openacs-inittab"></a>AOLserver keepalive with inittab</h2></div></div></div><p>This is an alternative method for keeping the AOLserver +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>AOLserver keepalive with inittab</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance."><link rel="next" href="install-next-add-server.html" title="Running multiple services on one machine"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-openacs-keepalive.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="install-next-add-server.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-openacs-inittab"></a>AOLserver keepalive with inittab</h2></div></div></div> + + + <p>This is an alternative method for keeping the AOLserver process running. The recommended method is to <a class="link" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance.">run AOLserver - supervised</a>.</p><p> + supervised</a>.</p> + + <p> This step should be completed as root. This can break every service on your machine, so proceed with caution. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> There are 2 general steps to getting this working. - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> Install a script called <code class="computeroutput">restart-aolserver</code>. This script doesn't actually restart AOLserver - it just kills @@ -15,7 +23,9 @@ Ask the OS to restart our service whenever it's not running. We do this by adding a line to <code class="computeroutput">/etc/inittab</code>. - </p></li></ol></div><p> + </p></li></ol></div> + + <p> Calling <code class="computeroutput">restart-aolserver</code> kills our service. The OS notices that our service is not running, so it automatically restarts it. Thus, calling @@ -34,27 +44,33 @@ general system users cannot run the script. You also need to have Perl installed and also a symbolic link to it in <code class="computeroutput">/usr/local/bin</code>. - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> [joeuser ~]$ su - Password: *********** [root ~]# cp /var/tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver [root ~]# chown root.web /usr/local/bin/restart-aolserver [root ~]# chmod 4750 /usr/local/bin/restart-aolserver [root ~]# ln -s /usr/bin/perl /usr/local/bin/perl -[root ~]# exit</pre></li><li class="listitem"><p> +[root ~]# exit</pre> + </li><li class="listitem"><p> Test the <code class="computeroutput">restart-aolserver</code> script. We'll first kill all running servers to clean the slate. Then, we'll start one server and use <code class="computeroutput">restart-aolserver</code> to kill it. If it works, then there should be no more servers - running. You should see the following lines. </p><pre class="programlisting"> + running. You should see the following lines. </p> + + <pre class="programlisting"> [joeuser ~]$ killall nsd nsd: no process killed [joeuser ~]$ /usr/local/aolserver/bin/nsd-postgres -t ~/var/lib/aolserver/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl [joeuser ~]$ restart-aolserver <span class="emphasis"><em>birdnotes</em></span> Killing 23727 [joeuser ~]$ killall nsd -nsd: no process killed</pre><p> +nsd: no process killed</pre> + + <p> The number 23727 indicates the process id(s) (PIDs) of the processes being killed. It is important that <span class="strong"><strong>no processes are killed</strong></span> by the second call to <code class="computeroutput">killall</code>. If there are @@ -63,30 +79,43 @@ Assuming that the <code class="computeroutput">restart-aolserver</code> script worked, login as root and open <code class="computeroutput">/etc/inittab</code> for - editing. </p><pre class="programlisting"> + editing. </p> + <pre class="programlisting"> [joeuser ~]$ su - Password: ************ -[root ~]# emacs -nw /etc/inittab</pre></li><li class="listitem"><p> +[root ~]# emacs -nw /etc/inittab</pre> + </li><li class="listitem"><p> Copy this line into the bottom of the file as a template, making sure that the first field <code class="computeroutput">nss1</code> is unique. - </p><pre class="programlisting"> -nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/<span class="emphasis"><em>joeuser</em></span>/var/lib/aolserver/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl</pre></li><li class="listitem"><p> + </p> + <pre class="programlisting"> +nss1:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nobody -g web -t /home/<span class="emphasis"><em>joeuser</em></span>/var/lib/aolserver/<span class="emphasis"><em>birdnotes</em></span>/nsd.tcl</pre> + </li><li class="listitem"><p> <span class="strong"><strong>Important:</strong></span> Make sure there is a newline at the end of the file. If there is not a newline at the end of the file, the system may suffer catastrophic failures. </p></li><li class="listitem"><p> Still as root, enter the following command to re-initialize - <code class="computeroutput">/etc/inittab</code>. </p><pre class="programlisting"> + <code class="computeroutput">/etc/inittab</code>. </p> + + <pre class="programlisting"> [root ~]# killall nsd nsd: no process killed -[root ~]# /sbin/init q</pre></li><li class="listitem"><p> +[root ~]# /sbin/init q</pre> + </li><li class="listitem"><p> See if it worked by running the <code class="computeroutput">restart-aolserver</code> script - again. </p><pre class="programlisting"> + again. </p> + + <pre class="programlisting"> [root ~]# restart-aolserver <span class="emphasis"><em>birdnotes</em></span> -Killing 23750</pre></li></ul></div><p> +Killing 23750</pre> + </li></ul></div> + + <p> If processes were killed, congratulations, your server is now automated for startup and shutdown. - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-openacs-keepalive.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-next-add-server.html">Next</a></td></tr><tr><td width="40%" align="left">Starting and Stopping an OpenACS instance. </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Running multiple services on one machine</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-openacs-keepalive.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-next-add-server.html">Next</a></td></tr><tr><td width="40%" align="left">Starting and Stopping an OpenACS instance. </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Running multiple services on one machine</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -11,7 +11,7 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="install-openacs-keepalive" id="install-openacs-keepalive"></a>Starting and Stopping an OpenACS instance.</h2></div></div></div><p>The simplest way to start and stop and OpenACS site is to run -the startup shell script provided, <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/run</code>. +the startup shell script provided, <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/run</code>. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.</p><p>A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is @@ -40,9 +40,9 @@ started by the file <code class="computeroutput">/service/$OPENACS_SERVICE_NAME/run</code>. But we use a symlink to make it easier to add and remove stuff from the <code class="computeroutput">/service</code>, so the actual -location is <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>etc/daemontools/run</code>.</p><p>Daemontools creates additional files and directories to track +location is <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>etc/daemontools/run</code>.</p><p>Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS -tarball at <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools</code>. +tarball at <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools</code>. To use it, first ill any existing AOLserver instances. As root, link the <code class="computeroutput">daemontools</code> directory into the <code class="computeroutput">/service</code> directory. @@ -51,47 +51,47 @@ <code class="computeroutput">run</code>.</p><pre class="screen"> [$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>killall nsd</code></strong> nsd: no process killed -[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>emacs /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/run</code></strong> +[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>emacs /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/run</code></strong> [$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>exit</code></strong> -[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/ /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/ /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre><p>Verify that AOLserver is running.</p><pre class="screen"> -[root root]#<strong class="userinput"><code> ps -auxw | grep nsd</code></strong><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> 5562 14.4 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl -u serve +[root root]#<strong class="userinput"><code> ps -auxw | grep nsd</code></strong><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> 5562 14.4 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl -u serve root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd [root root]# </pre> </li><li class="listitem"> -<p>The user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> can now control -the service <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> with these +<p>The user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> can now +control the service <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> with these commands:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p> -<code class="computeroutput">svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code> - Bring -the server down</p></li><li class="listitem"><p> -<code class="computeroutput">svc -u /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code> - Start -the server up and leave it in keepalive mode.</p></li><li class="listitem"><p> -<code class="computeroutput">svc -o /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code> - Start -the server up once. Do not restart it if it stops.</p></li><li class="listitem"><p> -<code class="computeroutput">svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code> - Stop and -immediately restart the server.</p></li><li class="listitem"><p> -<code class="computeroutput">svc -k /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</code> - Sends -the server a KILL signal. This is like KILL -9. AOLserver exits -immediately. If svc -t fails to fully kill AOLserver, use this -option. This does not take the server out of keepalive mode, so it -should still bounce back up immediately.</p></li> +<code class="computeroutput">svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</code> - +Bring the server down</p></li><li class="listitem"><p> +<code class="computeroutput">svc -u /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</code> - +Start the server up and leave it in keepalive mode.</p></li><li class="listitem"><p> +<code class="computeroutput">svc -o /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</code> - +Start the server up once. Do not restart it if it stops.</p></li><li class="listitem"><p> +<code class="computeroutput">svc -t /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</code> - Stop +and immediately restart the server.</p></li><li class="listitem"><p> +<code class="computeroutput">svc -k /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</code> - +Sends the server a KILL signal. This is like KILL -9. AOLserver +exits immediately. If svc -t fails to fully kill AOLserver, use +this option. This does not take the server out of keepalive mode, +so it should still bounce back up immediately.</p></li> </ul></div> </li><li class="listitem"> <p>Install a script to automate the stopping and starting of AOLserver services via daemontools. You can then restart a service -via <code class="computeroutput">restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +via <code class="computeroutput">restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code> </p><pre class="screen"> -[root root]# <strong class="userinput"><code>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver</code></strong> +[root root]# <strong class="userinput"><code>cp /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver</code></strong> [root root]# <strong class="userinput"><code>chmod 755 /usr/local/bin/restart-aolserver</code></strong> [root root]# </pre> @@ -100,19 +100,19 @@ <code class="computeroutput">root</code> user. Grant permission for the <code class="computeroutput">web</code> group to use <code class="computeroutput">svc</code> commands on the -<span class="emphasis"><em><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></em></span> +<span class="emphasis"><em><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></em></span> server.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>/usr/local/bin/svgroup web /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>/usr/local/bin/svgroup web /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [root root]# </pre> </li><li class="listitem"> -<p>Verify that the controls work. You may want to <code class="computeroutput">tail -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-error.log</code> +<p>Verify that the controls work. You may want to <code class="computeroutput">tail -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-error.log</code> in another window, so you can see what happens when you type these commands.</p><p>More information can be found on the <a class="ulink" href="http://panoptic.com/wiki/aolserver/How_to_start_stop_AOLserver_using_Daemontools" target="_top">AOLserver Daemontools</a> page.</p> </li> </ol></div><div class="table"> -<a name="idp140592099316488" id="idp140592099316488"></a><p class="title"><strong>Table 6.1. How it +<a name="idp140623159800936" id="idp140623159800936"></a><p class="title"><strong>Table 6.1. How it Works</strong></p><div class="table-contents"><table class="table" summary="How it Works" cellspacing="0" border="1"> <colgroup> <col><col><col><col><col><col> @@ -122,7 +122,7 @@ <tr> <td align="center">svscanboot</td><td align="center">init</td><td align="center">/etc/inittab</td><td align="center">ps -auxw | grep readproctitle</td><td align="center">n/a</td><td align="center"> </td> </tr><tr> -<td align="center">aolserver</td><td align="center">supervise (a child of svscanboot)</td><td align="center">/service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/run</td><td align="center">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/error.log</td><td align="center">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/$OPENACS_SERVICE_NAME.log</td><td align="center">svc -k /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<td align="center">aolserver</td><td align="center">supervise (a child of svscanboot)</td><td align="center">/service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/run</td><td align="center">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/error.log</td><td align="center">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/$OPENACS_SERVICE_NAME.log</td><td align="center">svc -k /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </td> </tr><tr> <td align="center">postgresql</td><td align="center">Redhat init scripts during boot</td><td align="center">/etc/init.d/postgresql</td><td align="center">/usr/local/pgsql/data/server.log</td><td align="center"> </td><td align="center">service postgresql start (Red Hat), 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 -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 7 Aug 2017 23:47:50 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/install-openacs-keepalive.html 8 Nov 2017 09:42:11 -0000 1.26 @@ -1,69 +1,109 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Starting and Stopping an OpenACS instance.</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="next" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance-web.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="install-openacs-inittab.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-openacs-keepalive"></a>Starting and Stopping an OpenACS instance.</h2></div></div></div><p>The simplest way to start and stop and OpenACS site is to run the startup shell script provided, <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/run</code>. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.</p><p>A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.</p><p>The Reference Platform uses Daemontools to control AOLserver. A simpler method, using <code class="computeroutput">init</code>, is <a class="link" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab">here</a>.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Daemontools must already be installed. If not, <a class="link" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install it</a>.</p></li><li class="listitem"><p>Each service controlled by daemontools must have a +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Starting and Stopping an OpenACS instance.</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="next" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance-web.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="install-openacs-inittab.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-openacs-keepalive"></a>Starting and Stopping an OpenACS instance.</h2></div></div></div> + + + <p>The simplest way to start and stop and OpenACS site is to run the startup shell script provided, <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/run</code>. This runs as a regular task, and logs to the logfile. To stop the site, kill the script.</p> + <p>A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers.</p> + <p>The Reference Platform uses Daemontools to control AOLserver. A simpler method, using <code class="computeroutput">init</code>, is <a class="link" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab">here</a>.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Daemontools must already be installed. If not, <a class="link" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install it</a>.</p> + </li><li class="listitem"> + <p>Each service controlled by daemontools must have a directory in <code class="computeroutput">/service</code>. That directory must have a file called - <code class="computeroutput">run</code>. It works like this:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The <code class="computeroutput">init</code> program starts every + <code class="computeroutput">run</code>. It works like this:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The <code class="computeroutput">init</code> program starts every time the computer is booted. </p></li><li class="listitem"><p>A line in <code class="computeroutput">init</code>'s configuration file, <code class="computeroutput">/etc/inittab</code>, tells init to run, and to restart if necessary, <code class="computeroutput">svscanboot</code>.</p></li><li class="listitem"><p><code class="computeroutput">svscanboot</code> checks the directory <code class="computeroutput">/service</code> - every few seconds.</p></li><li class="listitem"><p>If it sees a subdirectory there, it + every few seconds.</p> + </li><li class="listitem"><p>If it sees a subdirectory there, it looks for a file in the subdirectory called - <code class="computeroutput">run</code>. If it finds a run file, it creates a <code class="computeroutput">supervise</code> process</p></li><li class="listitem"><p><code class="computeroutput">supervise </code> executes the run script. Whenever the run script stops, <code class="computeroutput">supervise</code> executes it again. It also creates additional control files in the same directory. </p></li></ul></div><p>Hence, the AOLserver + <code class="computeroutput">run</code>. If it finds a run file, it creates a <code class="computeroutput">supervise</code> process</p> + </li><li class="listitem"> + <p><code class="computeroutput">supervise </code> executes the run script. Whenever the run script stops, <code class="computeroutput">supervise</code> executes it again. It also creates additional control files in the same directory. </p> + </li></ul></div> + <p>Hence, the AOLserver instance for your development server is started by the file <code class="computeroutput">/service/$OPENACS_SERVICE_NAME/run</code>. But we use a symlink to make it easier to add and remove stuff from the <code class="computeroutput">/service</code>, so the actual location is - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>etc/daemontools/run</code>.</p><p>Daemontools creates additional files and directories to track status and + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>etc/daemontools/run</code>.</p> + + <p>Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS tarball at - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools</code>. To use it, first ill any existing AOLserver instances. As root, link the <code class="computeroutput">daemontools</code> directory into the <code class="computeroutput">/service</code> directory. Daemontools' <code class="computeroutput">svscan</code> process checks this directory every five seconds, and will quickly execute <code class="computeroutput">run</code>.</p><pre class="screen">[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>killall nsd</code></strong> + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools</code>. To use it, first ill any existing AOLserver instances. As root, link the <code class="computeroutput">daemontools</code> directory into the <code class="computeroutput">/service</code> directory. Daemontools' <code class="computeroutput">svscan</code> process checks this directory every five seconds, and will quickly execute <code class="computeroutput">run</code>.</p> + + <pre class="screen">[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>killall nsd</code></strong> nsd: no process killed -[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>emacs /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/run</code></strong> +[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>emacs /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/run</code></strong> [$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>exit</code></strong> -[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/ /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre><p>Verify that AOLserver is running.</p><pre class="screen">[root root]#<strong class="userinput"><code> ps -auxw | grep nsd</code></strong> -<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> 5562 14.4 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl -u serve +[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/ /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + <p>Verify that AOLserver is running.</p> + <pre class="screen">[root root]#<strong class="userinput"><code> ps -auxw | grep nsd</code></strong> +<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> 5562 14.4 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl -u serve root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd -[root root]#</pre></li><li class="listitem"><p>The user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> can now control the service <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> with these commands:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +[root root]#</pre> + </li><li class="listitem"> + <p>The user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> can now control the service <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> with these commands:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> - <code class="computeroutput">svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> - + <code class="computeroutput">svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> - Bring the server down </p></li><li class="listitem"><p> - <code class="computeroutput">svc -u /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> - + <code class="computeroutput">svc -u /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> - Start the server up and leave it in keepalive mode. </p></li><li class="listitem"><p> - <code class="computeroutput">svc -o /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> - + <code class="computeroutput">svc -o /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> - Start the server up once. Do not restart it if it stops. </p></li><li class="listitem"><p> - <code class="computeroutput">svc -t /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> - + <code class="computeroutput">svc -t /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> - Stop and immediately restart the server. </p></li><li class="listitem"><p> - <code class="computeroutput">svc -k /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> - + <code class="computeroutput">svc -k /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> - Sends the server a KILL signal. This is like KILL -9. AOLserver exits immediately. If svc -t fails to fully kill AOLserver, use this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately. - </p></li></ul></div></li><li class="listitem"><p>Install a script to automate the stopping and starting - of AOLserver services via daemontools. You can then restart a service via <code class="computeroutput">restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></p><pre class="screen">[root root]# <strong class="userinput"><code>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver</code></strong> + </p></li></ul></div> + </li><li class="listitem"> + <p>Install a script to automate the stopping and starting + of AOLserver services via daemontools. You can then restart a service via <code class="computeroutput">restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></p> + <pre class="screen">[root root]# <strong class="userinput"><code>cp /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver</code></strong> [root root]# <strong class="userinput"><code>chmod 755 /usr/local/bin/restart-aolserver</code></strong> -[root root]#</pre></li><li class="listitem"><p> +[root root]#</pre> + </li><li class="listitem"> + <p> At this point, these commands will work only for the - <code class="computeroutput">root</code> user. Grant permission for the <code class="computeroutput">web</code> group to use <code class="computeroutput">svc</code> commands on the <span class="emphasis"><em><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></em></span> server.</p><pre class="screen">[root root]# <strong class="userinput"><code>/usr/local/bin/svgroup web /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[root root]#</pre></li><li class="listitem"><p>Verify that the controls work. You may want to <code class="computeroutput">tail -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-error.log</code> in another window, so you can see what happens when you type these commands. - </p><p> + <code class="computeroutput">root</code> user. Grant permission for the <code class="computeroutput">web</code> group to use <code class="computeroutput">svc</code> commands on the <span class="emphasis"><em><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></em></span> server.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>/usr/local/bin/svgroup web /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[root root]#</pre> + </li><li class="listitem"> + <p>Verify that the controls work. You may want to <code class="computeroutput">tail -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-error.log</code> in another window, so you can see what happens when you type these commands. + </p> + <p> More information can be found on the <a class="ulink" href="http://panoptic.com/wiki/aolserver/How_to_start_stop_AOLserver_using_Daemontools" target="_top">AOLserver Daemontools</a> page. -</p></li></ol></div><div class="table"><a name="idp140592099316488"></a><p class="title"><b>Table 6.1. How it Works</b></p><div class="table-contents"><table class="table" summary="How it Works" cellspacing="0" border="1"><colgroup><col><col><col><col><col><col></colgroup><thead><tr><th align="center">Program</th><th align="center">Invoked by this program ...</th><th align="center">... using this file</th><th align="center">Where to find errors</th><th align="center">Log goes to</th><th align="center">Use these commands to control it</th></tr></thead><tbody><tr><td align="center">svscanboot +</p> + </li></ol></div> + + <div class="table"><a name="idp140623159800936"></a><p class="title"><b>Table 6.1. How it Works</b></p><div class="table-contents"> + <table class="table" summary="How it Works" cellspacing="0" border="1"><colgroup><col><col><col><col><col><col></colgroup><thead><tr><th align="center">Program</th><th align="center">Invoked by this program ...</th><th align="center">... using this file</th><th align="center">Where to find errors</th><th align="center">Log goes to</th><th align="center">Use these commands to control it</th></tr></thead><tbody><tr><td align="center">svscanboot </td><td align="center">init</td><td align="center">/etc/inittab</td><td align="center">ps -auxw | grep readproctitle</td><td align="center">n/a</td><td align="center"> </td></tr><tr><td align="center">aolserver</td><td align="center"><code class="computeroutput"></code>supervise -(a child of svscanboot)</td><td align="center">/service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/run</td><td align="center">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/error.log</td><td align="center">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/$OPENACS_SERVICE_NAME.log</td><td align="center">svc -k /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td align="center">postgresql</td><td align="center">Redhat init scripts during boot</td><td align="center">/etc/init.d/postgresql</td><td align="center">/usr/local/pgsql/data/server.log</td><td align="center"> </td><td align="center">service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)</td></tr></tbody></table></div></div><br class="table-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance-web.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-openacs-inittab.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 6. Production Environments </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> AOLserver keepalive with inittab</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +(a child of svscanboot)</td><td align="center">/service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/run</td><td align="center">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/error.log</td><td align="center">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/$OPENACS_SERVICE_NAME.log</td><td align="center">svc -k /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td align="center">postgresql</td><td align="center">Redhat init scripts during boot</td><td align="center">/etc/init.d/postgresql</td><td align="center">/usr/local/pgsql/data/server.log</td><td align="center"> </td><td align="center">service postgresql start (Red Hat), /etc/init.d/postgresql start (Debian)</td></tr></tbody></table> + </div></div><br class="table-break"> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance-web.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-openacs-inittab.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 6. Production Environments </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> AOLserver keepalive with inittab</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-origins.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-origins.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-origins.html 7 Aug 2017 23:47:50 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-origins.html 8 Nov 2017 09:42:11 -0000 1.18 @@ -1,11 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Where did this document come from?</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="credits.html" title="Appendix C. Credits"><link rel="next" href="os-install.html" title="Linux Install Guides"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="os-install.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-origins"></a>Where did this document come from?</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Where did this document come from?</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="credits.html" title="Appendix C. Credits"><link rel="next" href="os-install.html" title="Linux Install Guides"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="os-install.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-origins"></a>Where did this document come from?</h2></div></div></div> + + <p> This document was created by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a>, but it's really just plagiarism from a number of documents that came before it. If I've used something that you've written without proper credit, let me know and I'll fix it right away. - </p><p>Versions 4.6.2 to present were edited by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a>. -</p><p>These are a few of my sources:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <p>Versions 4.6.2 to present were edited by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a>. +</p> + + <p>These are a few of my sources:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> ArsDigita installation guide </p></li><li class="listitem"><p> OpenACS 3.x installation guide @@ -18,6 +24,8 @@ </p></li><li class="listitem"><p> <a class="ulink" href="https://web.archive.org/web/20081005114800/http://aufrecht.org:80/openacs-4.5-quick-guide/" target="_top">Joel Aufrecht's OpenACS 4.5 Quick Guide.</a> - </p></li></ul></div><p> + </p></li></ul></div> + <p> Please also see the <a class="xref" href="credits.html" title="Appendix C. Credits">Credits</a> section for more acknowledgements. - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="os-install.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix C. Credits </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Linux Install Guides</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="credits.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="os-install.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix C. Credits </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Linux Install Guides</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-overview.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-overview.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-overview.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -17,11 +17,8 @@ <dt><span class="sect1"><a href="install-steps">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs">Prerequisite Software</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div> +</div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> +</span></p><span style="color: red"></authorblurb></span> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="acs-admin" leftLabel="Prev" leftTitle=" Index: openacs-4/packages/acs-core-docs/www/install-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-overview.html,v diff -u -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/install-overview.html 7 Aug 2017 23:47:50 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/install-overview.html 8 Nov 2017 09:42:11 -0000 1.35 @@ -1,5 +1,12 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 2. Installation Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="next" href="install-steps.html" title="Basic Steps"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-steps.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="install-overview"></a>Chapter 2. Installation Overview</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="install-steps.html">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs.html">Prerequisite Software</a></span></dt></dl></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-steps.html">Next</a></td></tr><tr><td width="40%" align="left">Part II. Administrator's Guide </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Basic Steps</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 2. Installation Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="next" href="install-steps.html" title="Basic Steps"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-steps.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="install-overview"></a>Chapter 2. Installation Overview</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="install-steps.html">Basic Steps</a></span></dt><dt><span class="sect1"><a href="individual-programs.html">Prerequisite Software</a></span></dt></dl></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> + </authorblurb></span> + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-admin.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-steps.html">Next</a></td></tr><tr><td width="40%" align="left">Part II. Administrator's Guide </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Basic Steps</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-pam-radius.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-pam-radius.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-pam-radius.adp 7 Aug 2017 23:47:50 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-pam-radius.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -13,37 +13,35 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="install-pam-radius" id="install-pam-radius"></a>Install PAM Radius for use as external -authentication</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This step by step guide is derived from the installation -instructions which you can find at <span class="replaceable"><span class="replaceable">yourdomain.com</span></span>/doc/acs-authentication/ext-auth-pam-install.html. +authentication</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte +Sussdorff</a> +</span></p><span style="color: red"></authorblurb></span><p>This step by step guide is derived from the installation +instructions which you can find at <em class="replaceable"><code>yourdomain.com</code></em>/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> <a name="install-ns_pam" id="install-ns_pam"></a><p> -<strong>Install ns_pam. </strong>Download and +<strong>Install ns_pam. </strong> Download and install ns_pam</p><pre class="screen"> [root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver/</code></strong> [root aolserver]# <strong class="userinput"><code>wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>tar xvfz ns_pam-0.1.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>cd ns_pam-0.1</code></strong> [root ns_pam-0.1]# <strong class="userinput"><code>make install INST=/usr/local/aolserver</code></strong> [root ns_pam-0.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver/ +<span class="action">cd /usr/local/src/aolserver/ wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz tar xvfz ns_pam-0.1.tar.gz cd ns_pam-0.1 make install INST=/usr/local/aolserver -</span></span> +</span> </pre> </li><li class="listitem"> <a name="configure-ns_pam" id="configure-ns_pam"></a><p> -<strong>Configure ns_pam. </strong>Configure +<strong>Configure ns_pam. </strong> Configure AOLserver for ns_pam</p><p>To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> @@ -57,14 +55,14 @@ <strong class="userinput"><code>aolserver</code></strong> </p></li><li class="listitem"> <p>Create <span class="emphasis"><em>/etc/pam.d/aolserver</em></span>.</p><pre class="screen"> - [root ns_pam]#<strong class="userinput"><code>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver</code></strong> + [root ns_pam]#<strong class="userinput"><code>cp /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver</code></strong> </pre> </li> </ul></div> </li><li class="listitem"> <a name="configure-pam-radius" id="configure-pam-radius"></a><p> -<strong>Configure PAM Radius. </strong>Configure and -install PAM Radius</p><p>You have to make sure that pam_radius v.1.3.16 or higher is +<strong>Configure PAM Radius. </strong> Configure +and install PAM Radius</p><p>You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.</p><pre class="screen"> [root ns_pam]# <strong class="userinput"><code>cd /usr/local/src/</code></strong> [root src]# <strong class="userinput"><code>wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar</code></strong> @@ -73,19 +71,19 @@ [root pam_radius]# <strong class="userinput"><code>make</code></strong> [root pam_radius]# <strong class="userinput"><code>cp pam_radius_auth.so /lib/security/</code></strong> [root pam_radius]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar tar xvf pam_radius-1.3.16 cd pam_radius make cp pam_radius_auth.so /lib/security/ -</span></span> +</span> </pre><p>Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.</p><pre class="screen"> -[root pam_radius]# <strong class="userinput"><code>echo "radius.<span class="replaceable"><span class="replaceable">yourdomain.com</span></span>:1645 <span class="replaceable"><span class="replaceable">your_radius_password</span></span> >>/etc/rddb/server</code></strong> - [root src]# <strong class="userinput"><code>chown <span class="replaceable"><span class="replaceable">service0</span></span>:web /etc/rddb/server</code></strong> +[root pam_radius]# <strong class="userinput"><code>echo "radius.<em class="replaceable"><code>yourdomain.com</code></em>:1645 <em class="replaceable"><code>your_radius_password</code></em> >>/etc/rddb/server</code></strong> + [root src]# <strong class="userinput"><code>chown <em class="replaceable"><code>service0</code></em>:web /etc/rddb/server</code></strong> </pre> </li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/install-pam-radius.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-pam-radius.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/install-pam-radius.html 7 Aug 2017 23:47:50 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/install-pam-radius.html 8 Nov 2017 09:42:11 -0000 1.12 @@ -1,20 +1,36 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install PAM Radius for use as external authentication</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-squirrelmail.html" title="Install Squirrelmail for use as a webmail system for OpenACS"><link rel="next" href="install-ldap-radius.html" title="Install LDAP for use as external authentication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-squirrelmail.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-ldap-radius.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-pam-radius"></a>Install PAM Radius for use as external authentication</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This step by step guide is derived from the installation instructions which you can find at <span class="replaceable"><span class="replaceable">yourdomain.com</span></span>/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a name="install-ns_pam"></a><p><b>Install ns_pam. </b>Download and install ns_pam</p><pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver/</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install PAM Radius for use as external authentication</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-squirrelmail.html" title="Install Squirrelmail for use as a webmail system for OpenACS"><link rel="next" href="install-ldap-radius.html" title="Install LDAP for use as external authentication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-squirrelmail.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-ldap-radius.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-pam-radius"></a>Install PAM Radius for use as external authentication</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> + </authorblurb></span> + + <p>This step by step guide is derived from the installation instructions which you can find at <em class="replaceable"><code>yourdomain.com</code></em>/doc/acs-authentication/ext-auth-pam-install.html. It is build upon PAM 0.77 (tested) and does not work on RedHat Linux Enterprise 3 (using PAM 0.75). It makes use of the ns_pam module written by Mat Kovach. The instructions given in here do work with PAM LDAP accordingly and differences will be shown at the end of the file.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><a name="install-ns_pam"></a> + <p> + <b>Install ns_pam. </b> + Download and install ns_pam + </p> + <pre class="screen">[root aolserver]# <strong class="userinput"><code>cd /usr/local/src/aolserver/</code></strong> [root aolserver]# <strong class="userinput"><code>wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>tar xvfz ns_pam-0.1.tar.gz</code></strong> [root aolserver]# <strong class="userinput"><code>cd ns_pam-0.1</code></strong> [root ns_pam-0.1]# <strong class="userinput"><code>make install INST=/usr/local/aolserver</code></strong> [root ns_pam-0.1]# -<span class="action"><span class="action">cd /usr/local/src/aolserver/ +<span class="action">cd /usr/local/src/aolserver/ wget http://braindamage.alal.com/software/ns_pam-0.1.tar.gz tar xvfz ns_pam-0.1.tar.gz cd ns_pam-0.1 make install INST=/usr/local/aolserver -</span></span> - </pre></li><li class="listitem"><a name="configure-ns_pam"></a><p><b>Configure ns_pam. </b>Configure AOLserver for ns_pam</p><p>To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +</span> + </pre> + </li><li class="listitem"><a name="configure-ns_pam"></a> + <p> + <b>Configure ns_pam. </b> + Configure AOLserver for ns_pam + </p> + <p>To enable ns_pam in AOLServer you will first have to edit your config.tcl file and enable the loading of the ns_pam module and configure the aolservers pam configuration file.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Change <span class="emphasis"><em>config.tcl</em></span>. Remove the <span class="emphasis"><em>#</em></span> in front of <code class="computeroutput">ns_param nspam ${bindir}/nspam.so</code> to enable the loading @@ -26,21 +42,33 @@ with <strong class="userinput"><code>aolserver</code></strong> </p></li><li class="listitem"><p>Create <span class="emphasis"><em>/etc/pam.d/aolserver</em></span>. </p><pre class="screen"> - [root ns_pam]#<strong class="userinput"><code>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver</code></strong> - </pre></li></ul></div></li><li class="listitem"><a name="configure-pam-radius"></a><p><b>Configure PAM Radius. </b>Configure and install PAM Radius</p><p>You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.</p><pre class="screen">[root ns_pam]# <strong class="userinput"><code>cd /usr/local/src/</code></strong> + [root ns_pam]#<strong class="userinput"><code>cp /var/lib/aolserver/<em class="replaceable"><code>service0</code></em>/packages/acs-core-docs/www/files/pam-aolserver.txt /etc/pam.d/aolserver</code></strong> + </pre> + </li></ul></div> + </li><li class="listitem"><a name="configure-pam-radius"></a> + <p> + <b>Configure PAM Radius. </b> + Configure and install PAM Radius + </p> + <p>You have to make sure that pam_radius v.1.3.16 or higher is installed, otherwise you will have to install it.</p> + <pre class="screen">[root ns_pam]# <strong class="userinput"><code>cd /usr/local/src/</code></strong> [root src]# <strong class="userinput"><code>wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar</code></strong> [root src]# <strong class="userinput"><code>tar xvf pam_radius-1.3.16</code></strong> [root src]# <strong class="userinput"><code>cd pam_radius</code></strong> [root pam_radius]# <strong class="userinput"><code>make</code></strong> [root pam_radius]# <strong class="userinput"><code>cp pam_radius_auth.so /lib/security/</code></strong> [root pam_radius]# -<span class="action"><span class="action">cd /usr/local/src +<span class="action">cd /usr/local/src wget ftp://ftp.freeradius.org/pub/radius/pam_radius-1.3.16.tar tar xvf pam_radius-1.3.16 cd pam_radius make cp pam_radius_auth.so /lib/security/ -</span></span> - </pre><p>Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.</p><pre class="screen">[root pam_radius]# <strong class="userinput"><code>echo "radius.<span class="replaceable"><span class="replaceable">yourdomain.com</span></span>:1645 <span class="replaceable"><span class="replaceable">your_radius_password</span></span> >>/etc/rddb/server</code></strong> - [root src]# <strong class="userinput"><code>chown <span class="replaceable"><span class="replaceable">service0</span></span>:web /etc/rddb/server</code></strong> - </pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-squirrelmail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-ldap-radius.html">Next</a></td></tr><tr><td width="40%" align="left">Install Squirrelmail for use as a webmail system for OpenACS </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install LDAP for use as external authentication</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</span> + </pre> + <p>Next you have to add the configuration lines to your Radius configuration file (/etc/rddb/server). For AOLserver to be able to access this information you have to change the access rights to this file as well.</p> + <pre class="screen">[root pam_radius]# <strong class="userinput"><code>echo "radius.<em class="replaceable"><code>yourdomain.com</code></em>:1645 <em class="replaceable"><code>your_radius_password</code></em> >>/etc/rddb/server</code></strong> + [root src]# <strong class="userinput"><code>chown <em class="replaceable"><code>service0</code></em>:web /etc/rddb/server</code></strong> + </pre> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-squirrelmail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-ldap-radius.html">Next</a></td></tr><tr><td width="40%" align="left">Install Squirrelmail for use as a webmail system for OpenACS </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install LDAP for use as external authentication</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-php.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-php.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-php.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-php.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -10,11 +10,9 @@ rightLink="install-squirrelmail" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="install-php" id="install-php"></a>Install PHP for use in AOLserver</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>To be able to use PHP software with AOLserver (and OpenACS), you +<a name="install-php" id="install-php"></a>Install PHP for use in AOLserver</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte +Sussdorff</a> +</span></p><span style="color: red"></authorblurb></span><p>To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from <a class="ulink" href="http://www.php.net" target="_top">www.php.net</a>. For convenience we get version 4.3.4 from a mirror</p><pre class="screen"> Index: openacs-4/packages/acs-core-docs/www/install-php.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-php.html,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/install-php.html 7 Aug 2017 23:47:51 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/install-php.html 8 Nov 2017 09:42:11 -0000 1.17 @@ -1,12 +1,18 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install PHP for use in AOLserver</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-tclwebtest.html" title="Install tclwebtest."><link rel="next" href="install-squirrelmail.html" title="Install Squirrelmail for use as a webmail system for OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-tclwebtest.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-squirrelmail.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-php"></a>Install PHP for use in AOLserver</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from <a class="ulink" href="http://www.php.net" target="_top">www.php.net</a>. For convenience we get version 4.3.4 from a mirror</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install PHP for use in AOLserver</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-tclwebtest.html" title="Install tclwebtest."><link rel="next" href="install-squirrelmail.html" title="Install Squirrelmail for use as a webmail system for OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-tclwebtest.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-squirrelmail.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-php"></a>Install PHP for use in AOLserver</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> + </authorblurb></span> + + <p>To be able to use PHP software with AOLserver (and OpenACS), you have to install PHP with AOLserver support. Get the latest version from <a class="ulink" href="http://www.php.net" target="_top">www.php.net</a>. For convenience we get version 4.3.4 from a mirror</p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> [root src]# <strong class="userinput"><code>wget http://de3.php.net/distributions/php-4.3.4.tar.gz</code></strong> [root src]# <strong class="userinput"><code>tar xfz php-4.3.4.tar.gz</code></strong> [root src]# <strong class="userinput"><code>cd php-4.3.4</code></strong> [root php-4.3.4]# <strong class="userinput"><code>cd php-4.3.4</code></strong> [root php-4.3.4]# <strong class="userinput"><code> ./configure --with-aolserver=/usr/local/aolserver/ --with-pgsql=/usr/local/pgsql --without-mysql</code></strong> [root php-4.3.4]# <strong class="userinput"><code>make install</code></strong> - </pre><p>Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add <strong class="userinput"><code>index.php</code></strong> as the last element to your <code class="computeroutput">directoryfile</code> directive.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-tclwebtest.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-squirrelmail.html">Next</a></td></tr><tr><td width="40%" align="left">Install tclwebtest. </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Squirrelmail for use as a webmail system for OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + <p>Once installed you can enable this by configuring your config file. Make sure your config file supports php (it should have a php section with it). Furthermore add <strong class="userinput"><code>index.php</code></strong> as the last element to your <code class="computeroutput">directoryfile</code> directive.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-tclwebtest.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-squirrelmail.html">Next</a></td></tr><tr><td width="40%" align="left">Install tclwebtest. </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Squirrelmail for use as a webmail system for OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-qmail.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-qmail.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-qmail.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -10,141 +10,30 @@ rightLink="analog-install" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="install-qmail" id="install-qmail"></a>Install qmail (OPTIONAL)</h2></div></div></div><p>Qmail is a Mail Transfer Agent. It handles incoming and outgoing -mail. Install qmail if you want your OpenACS server to send and -receive mail, and you don't want to use an alternate MTA.</p><p>Red Hat 9: all djb tools (qmail, daemontools, ucspi) will fail -to compile in Red Hat 9 because of changes to glibc (<a class="ulink" href="http://moni.csi.hu/pub/glibc-2.3.1/" target="_top">patches</a>)</p><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"> -<p> -<strong>Install ucspi. </strong>This program handles -incoming tcp connections. <a class="link" href="individual-programs" title="ucspi-tcp 0.88, OPTIONAL">Download ucspi</a> and install it.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> -[root src]# <strong class="userinput"><code>wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz</code></strong> -[root src]# <strong class="userinput"><code>tar xzf ucspi-tcp-0.88.tar.gz</code></strong><span class="action"><span class="action">cd /usr/local/src -wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz -tar xzf ucspi-tcp-0.88.tar.gz </span></span> -</pre><p>Red Hat 9 only</p><pre class="screen"><span class="action"><span class="action">wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch -cd ucspi-tcp-0.88 -patch -p1 <../ucspi-tcp-0.88.errno.patch -cd ..</span></span></pre><p>All platforms continue:</p><pre class="screen"> -[root src]# <strong class="userinput"><code>cd ucspi-tcp-0.88</code></strong> -[root ucspi-tcp-0.88]#<strong class="userinput"><code> make</code></strong> -( cat warn-auto.sh; \ -echo 'main="$1"; shift'; \<span class="emphasis"><em>(many lines omitted)</em></span> -./compile instcheck.c -./load instcheck hier.o auto_home.o unix.a byte.a -[root ucspi-tcp-0.88]# <strong class="userinput"><code>make setup check</code></strong> -./install -./instcheck -[root ucspi-tcp-0.88]# -<span class="action"><span class="action"> -cd ucspi-tcp-0.88 -make -make setup check</span></span> -</pre><p>Verify that ucspi-tcp was installed successfully by running the -tcpserver program which is part of ucspi-tcp:</p><pre class="screen"> -[root ucspi-tcp-0.88]# <strong class="userinput"><code>tcpserver</code></strong> -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]# -</pre><p> -<a class="indexterm" name="idp140592107236824" id="idp140592107236824"></a> (I'm not sure if this next step is -100% necessary, but when I skip it I get problems. If you get the -error <code class="computeroutput">553 sorry, that domain isn't -in my list of allowed rcpthosts (#5.7.1)</code> then you need to do -this.) AOLserver sends outgoing mail via the ns_sendmail command, -which pipes a command to the sendmail executable. Or, in our case, -the qmail replacement wrapper for the sendmail executable. In some -cases, though, the outgoing mail requset is apparently sent through -tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP -address that means the local machine - the "loopback" -interface). Unless this mail is addressed to the same machine, -qmail thinks that it's an attempt to relay mail, and rejects -it. So these two commands set up an exception so that any mail sent -from 127.0.0.1 is allowed to send outgoing mail.</p><pre class="screen"> -[root ucspi-tcp-0.88]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp</code></strong> -[root ucspi-tcp-0.88]# <strong class="userinput"><code>tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp</code></strong><span class="action"><span class="action">cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp </span></span> -</pre> -</li><li class="listitem"> -<p> -<strong>Install Qmail. </strong><a class="indexterm" name="idp140592107243816" id="idp140592107243816"></a> -</p><p> -<a class="link" href="individual-programs" title="ucspi-tcp 0.88, OPTIONAL">Download qmail</a>, set up the -standard supporting users and build the binaries:</p><pre class="screen"> -[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> -[root src]# <strong class="userinput"><code>wget http://www.qmail.org/netqmail-1.04.tar.gz</code></strong> -[root src]# <strong class="userinput"><code>tar xzf netqmail-1.04.tar.gz</code></strong> ---15:04:11-- http://www.qmail.org/netqmail-1.04.tar.gz - => `netqmail-1.04.tar.gz' -Resolving www.qmail.org... done. -Connecting to www.qmail.org[192.203.178.37]:80... connected. -HTTP request sent, awaiting response... 200 OK -Length: 242,310 [application/x-gunzip] - -88% [===============================> ] 214,620 22.93K/s ETA 00:01 - -15:04:21 (24.04 KB/s) - `netqmail-1.04.tar.gz' saved [242310/242310] - -[root src]# <strong class="userinput"><code>mkdir /var/qmail</code></strong> -[root src]#<strong class="userinput"><code> groupadd nofiles</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail/alias alias</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail qmaild</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail qmaill</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail qmailp</code></strong> -[root src]# <strong class="userinput"><code>groupadd qmail</code></strong> -[root src]# <strong class="userinput"><code>useradd -g qmail -d /var/qmail qmailq</code></strong> -[root src]# <strong class="userinput"><code>useradd -g qmail -d /var/qmail qmailr</code></strong> -[root src]# <strong class="userinput"><code>useradd -g qmail -d /var/qmail qmails</code></strong> -[root src]# <strong class="userinput"><code>cd netqmail-1.04</code></strong> -[root netqmail-1.04]# <strong class="userinput"><code>./collate.sh</code></strong> - -You should see 7 lines of text below. If you see anything -else, then something might be wrong. -[1] Extracting qmail-1.03... -[2] Patching qmail-1.03 into netqmail-1.04. Look for errors below: - 20 -[4] The previous line should say 20 if you used GNU patch. -[5] Renaming qmail-1.03 to netqmail-1.04... -[6] Continue installing qmail using the instructions found at: -[7] http://www.lifewithqmail.org/lwq.html#installation -[root netqmail-1.04]# <strong class="userinput"><code>cd netqmail-1.04</code></strong> -[root netqmail-1.04]# <strong class="userinput"><code>make setup check</code></strong> -( cat warn-auto.sh; \ -echo CC=\'`head -1 conf-cc`\'; \<span class="emphasis"><em>(many lines omitted)</em></span> -./install -./instcheck -<span class="action"><span class="action">cd /usr/local/src -wget http://www.qmail.org/netqmail-1.04.tar.gz -tar xzf netqmail-1.04.tar.gz -mkdir /var/qmail -groupadd nofiles -useradd -g nofiles -d /var/qmail/alias alias -useradd -g nofiles -d /var/qmail qmaild -useradd -g nofiles -d /var/qmail qmaill -useradd -g nofiles -d /var/qmail qmailp -groupadd qmail -useradd -g qmail -d /var/qmail qmailq -useradd -g qmail -d /var/qmail qmailr -useradd -g qmail -d /var/qmail qmails -cd netqmail-1.04 -./collate.sh -cd netqmail-1.04 -make setup check</span></span> -</pre><p>Replace sendmail with qmail's wrapper.</p><a class="indexterm" name="idp140592107290328" id="idp140592107290328"></a><pre class="screen"> +<a name="install-qmail" id="install-qmail"></a>Install qmail (OPTIONAL)</h2></div></div></div><p>Qmail is a secure, reliable, efficient, simple Mail Transfer +Agent. It handles incoming and outgoing mail. Install qmail if you +want your OpenACS server to send and receive mail, and you +don't want to use an alternate MTA.</p><div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"><p> +<strong>Install qmail. </strong> QMail is available +as standard Debian/Ubuntu package, rpms for Fedora/Redhat/CenTOS +are available from <a class="ulink" href="https://en.wikipedia.org/wiki/Qmail/" target="_top">QMail wiki +page</a> +</p></li><li class="listitem"> +<p>Replace sendmail with qmail's wrapper.</p><a class="indexterm" name="idp140623090549880" id="idp140623090549880"></a><pre class="screen"> [root qmail-1.03]# <strong class="userinput"><code>rm -f /usr/bin/sendmail /usr/sbin/sendmail</code></strong> [root qmail-1.03]# <strong class="userinput"><code>ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</code></strong> [root qmail-1.03]# -<span class="action"><span class="action">rm -f /usr/bin/sendmail /usr/sbin/sendmail -ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</span></span> +<span class="action">rm -f /usr/bin/sendmail /usr/sbin/sendmail +ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</span> </pre><p>Configure qmail - specifically, run the config script to set up files in <code class="computeroutput">/var/qmail/control</code> specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read <code class="computeroutput">/var/qmail/doc/INSTALL.ctl</code> to find out how to configure qmail.</p><pre class="screen"> -[root qmail-1.03]# <strong class="userinput"><code>./config-fast <span class="replaceable"><span class="replaceable">yourserver.test</span></span> +[root qmail-1.03]# <strong class="userinput"><code>./config-fast <em class="replaceable"><code>yourserver.test</code></em> </code></strong> Your fully qualified host name is yourserver.test. Putting yourserver.test into control/me... @@ -155,8 +44,8 @@ Now qmail will refuse to accept SMTP messages except to yourserver.test. Make sure to change rcpthosts if you add hosts to locals or virtualdomains! [root qmail-1.03]# -<span class="action"><span class="action">./config-fast <span class="replaceable"><span class="replaceable">yourserver.test</span></span> -</span></span> +<span class="action">./config-fast <em class="replaceable"><code>yourserver.test</code></em> +</span> </pre><p>All incoming mail that isn't for a specific user is handled by the <code class="computeroutput">alias</code> user. This includes all root mail. These commands prepare the alias user to @@ -166,28 +55,28 @@ [root alias]# <strong class="userinput"><code>/var/qmail/bin/maildirmake ~alias/Maildir/</code></strong> [root alias]# <strong class="userinput"><code>chown -R alias.nofiles /var/qmail/alias/Maildir</code></strong> [root alias]# -<span class="action"><span class="action">cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root +<span class="action">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</span></span> -</pre><a class="indexterm" name="idp140592107304760" id="idp140592107304760"></a><p>Configure qmail to use the Maildir delivery format (instead of +chown -R alias.nofiles /var/qmail/alias/Maildir</span> +</pre><a class="indexterm" name="idp140623162685720" id="idp140623162685720"></a><p>Configure qmail to use the Maildir delivery format (instead of mbox), and install a version of the qmail startup script modified to use Maildir.</p><pre class="screen"> [root alias]# <strong class="userinput"><code>echo "./Maildir" > /var/qmail/bin/.qmail</code></strong> [root alias]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc</code></strong> [root alias]# <strong class="userinput"><code>chmod 755 /var/qmail/rc</code></strong> [root alias]# -<span class="action"><span class="action">echo "./Maildir" > /var/qmail/bin/.qmail +<span class="action">echo "./Maildir" > /var/qmail/bin/.qmail cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc chmod 755 /var/qmail/rc -</span></span> +</span> </pre><p>Set up the skeleton directory so that new users will be configured for qmail.</p><pre class="screen"> [root root]# <strong class="userinput"><code>/var/qmail/bin/maildirmake /etc/skel/Maildir</code></strong> [root root]# <strong class="userinput"><code>echo "./Maildir/" > /etc/skel/.qmail</code></strong> [root root]# -<span class="action"><span class="action">/var/qmail/bin/maildirmake /etc/skel/Maildir -echo "./Maildir/" > /etc/skel/.qmail</span></span> +<span class="action">/var/qmail/bin/maildirmake /etc/skel/Maildir +echo "./Maildir/" > /etc/skel/.qmail</span> </pre><p>As recommended, we will run qmail with daemontools control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set @@ -210,7 +99,7 @@ [root root]# <strong class="userinput"><code>chmod 755 /var/qmail/supervise/qmail-smtpd/run</code></strong> [root root]# <strong class="userinput"><code>chmod 755 /var/qmail/supervise/qmail-smtpd/log/run</code></strong> [root root]# <strong class="userinput"><code>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</code></strong> -[root root]# <strong class="userinput"><code>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</code></strong><span class="action"><span class="action">mkdir -p /var/qmail/supervise/qmail-send/log +[root root]# <strong class="userinput"><code>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</code></strong><span class="action">mkdir -p /var/qmail/supervise/qmail-send/log mkdir -p /var/qmail/supervise/qmail-smtpd/log mkdir /var/log/qmail chown qmaill /var/log/qmail @@ -226,7 +115,7 @@ chmod 755 /var/qmail/supervise/qmail-smtpd/run chmod 755 /var/qmail/supervise/qmail-smtpd/log/run ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service -</span></span> +</span> </pre><p>Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. Index: openacs-4/packages/acs-core-docs/www/install-qmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-qmail.html,v diff -u -r1.42 -r1.43 --- openacs-4/packages/acs-core-docs/www/install-qmail.html 7 Aug 2017 23:47:51 -0000 1.42 +++ openacs-4/packages/acs-core-docs/www/install-qmail.html 8 Nov 2017 09:42:11 -0000 1.43 @@ -1,113 +1,30 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install qmail (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"><link rel="next" href="analog-install.html" title="Install Analog web file analyzer"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-qmail"></a>Install qmail (OPTIONAL)</h2></div></div></div><p>Qmail is a Mail Transfer Agent. It handles incoming and +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install qmail (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"><link rel="next" href="analog-install.html" title="Install Analog web file analyzer"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-qmail"></a>Install qmail (OPTIONAL)</h2></div></div></div> + + <p>Qmail is a secure, reliable, efficient, simple Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate - MTA.</p><p>Red Hat 9: all djb tools (qmail, daemontools, ucspi) will - fail to compile in Red Hat 9 because of changes to glibc (<a class="ulink" href="http://moni.csi.hu/pub/glibc-2.3.1/" target="_top">patches</a>)</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Install ucspi. </b>This program handles incoming tcp connections. - <a class="link" href="individual-programs.html#ucspi-download" title="ucspi-tcp 0.88, OPTIONAL">Download ucspi</a> and install it.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> -[root src]# <strong class="userinput"><code>wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz</code></strong> -[root src]# <strong class="userinput"><code>tar xzf ucspi-tcp-0.88.tar.gz</code></strong> -<span class="action"><span class="action">cd /usr/local/src -wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz -tar xzf ucspi-tcp-0.88.tar.gz </span></span></pre><p>Red Hat 9 only</p><pre class="screen"><span class="action"><span class="action">wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch -cd ucspi-tcp-0.88 -patch -p1 <../ucspi-tcp-0.88.errno.patch -cd ..</span></span></pre><p>All platforms continue:</p><pre class="screen">[root src]# <strong class="userinput"><code>cd ucspi-tcp-0.88</code></strong> -[root ucspi-tcp-0.88]#<strong class="userinput"><code> make</code></strong> -( cat warn-auto.sh; \ -echo 'main="$1"; shift'; \<span class="emphasis"><em>(many lines omitted)</em></span> -./compile instcheck.c -./load instcheck hier.o auto_home.o unix.a byte.a -[root ucspi-tcp-0.88]# <strong class="userinput"><code>make setup check</code></strong> -./install -./instcheck -[root ucspi-tcp-0.88]# -<span class="action"><span class="action"> -cd ucspi-tcp-0.88 -make -make setup check</span></span></pre><p>Verify that ucspi-tcp was installed successfully by -running the tcpserver program which is part of ucspi-tcp:</p><pre class="screen">[root ucspi-tcp-0.88]# <strong class="userinput"><code>tcpserver</code></strong> -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]# -</pre><p><a class="indexterm" name="idp140592107236824"></a> -(I'm not sure if this next step is 100% necessary, but when I skip it -I get problems. If you get the error <code class="computeroutput">553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1)</code> then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail -command, which pipes a command to the sendmail executable. Or, in our -case, the qmail replacement wrapper for the sendmail executable. In -some cases, though, the outgoing mail requset is apparently sent -through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP -address that means the local machine - the "loopback" interface). -Unless this mail is addressed to the same machine, qmail thinks that -it's an attempt to relay mail, and rejects it. So these two commands -set up an exception so that any mail sent from 127.0.0.1 is allowed to -send outgoing mail.</p><pre class="screen">[root ucspi-tcp-0.88]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp</code></strong> -[root ucspi-tcp-0.88]# <strong class="userinput"><code>tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp</code></strong> -<span class="action"><span class="action">cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp </span></span></pre></li><li class="listitem"><p><b>Install Qmail. </b><a class="indexterm" name="idp140592107243816"></a></p><p><a class="link" href="individual-programs.html#ucspi-download" title="ucspi-tcp 0.88, OPTIONAL">Download qmail</a>, - set up the standard supporting users and build the binaries:</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /usr/local/src</code></strong> -[root src]# <strong class="userinput"><code>wget http://www.qmail.org/netqmail-1.04.tar.gz</code></strong> -[root src]# <strong class="userinput"><code>tar xzf netqmail-1.04.tar.gz</code></strong> ---15:04:11-- http://www.qmail.org/netqmail-1.04.tar.gz - => `netqmail-1.04.tar.gz' -Resolving www.qmail.org... done. -Connecting to www.qmail.org[192.203.178.37]:80... connected. -HTTP request sent, awaiting response... 200 OK -Length: 242,310 [application/x-gunzip] - -88% [===============================> ] 214,620 22.93K/s ETA 00:01 - -15:04:21 (24.04 KB/s) - `netqmail-1.04.tar.gz' saved [242310/242310] - -[root src]# <strong class="userinput"><code>mkdir /var/qmail</code></strong> -[root src]#<strong class="userinput"><code> groupadd nofiles</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail/alias alias</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail qmaild</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail qmaill</code></strong> -[root src]# <strong class="userinput"><code>useradd -g nofiles -d /var/qmail qmailp</code></strong> -[root src]# <strong class="userinput"><code>groupadd qmail</code></strong> -[root src]# <strong class="userinput"><code>useradd -g qmail -d /var/qmail qmailq</code></strong> -[root src]# <strong class="userinput"><code>useradd -g qmail -d /var/qmail qmailr</code></strong> -[root src]# <strong class="userinput"><code>useradd -g qmail -d /var/qmail qmails</code></strong> -[root src]# <strong class="userinput"><code>cd netqmail-1.04</code></strong> -[root netqmail-1.04]# <strong class="userinput"><code>./collate.sh</code></strong> - -You should see 7 lines of text below. If you see anything -else, then something might be wrong. -[1] Extracting qmail-1.03... -[2] Patching qmail-1.03 into netqmail-1.04. Look for errors below: - 20 -[4] The previous line should say 20 if you used GNU patch. -[5] Renaming qmail-1.03 to netqmail-1.04... -[6] Continue installing qmail using the instructions found at: -[7] http://www.lifewithqmail.org/lwq.html#installation -[root netqmail-1.04]# <strong class="userinput"><code>cd netqmail-1.04</code></strong> -[root netqmail-1.04]# <strong class="userinput"><code>make setup check</code></strong> -( cat warn-auto.sh; \ -echo CC=\'`head -1 conf-cc`\'; \<span class="emphasis"><em>(many lines omitted)</em></span> -./install -./instcheck -<span class="action"><span class="action">cd /usr/local/src -wget http://www.qmail.org/netqmail-1.04.tar.gz -tar xzf netqmail-1.04.tar.gz -mkdir /var/qmail -groupadd nofiles -useradd -g nofiles -d /var/qmail/alias alias -useradd -g nofiles -d /var/qmail qmaild -useradd -g nofiles -d /var/qmail qmaill -useradd -g nofiles -d /var/qmail qmailp -groupadd qmail -useradd -g qmail -d /var/qmail qmailq -useradd -g qmail -d /var/qmail qmailr -useradd -g qmail -d /var/qmail qmails -cd netqmail-1.04 -./collate.sh -cd netqmail-1.04 -make setup check</span></span></pre><p>Replace sendmail with qmail's wrapper.</p><a class="indexterm" name="idp140592107290328"></a><pre class="screen">[root qmail-1.03]# <strong class="userinput"><code>rm -f /usr/bin/sendmail /usr/sbin/sendmail</code></strong> + MTA.</p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Install qmail. </b> + QMail is available as standard Debian/Ubuntu package, + rpms for Fedora/Redhat/CenTOS are available from <a class="ulink" href="https://en.wikipedia.org/wiki/Qmail/" target="_top">QMail wiki + page</a> + </p> + </li><li class="listitem"> + <p> + Replace sendmail with qmail's wrapper. + </p> + <a class="indexterm" name="idp140623090549880"></a> + <pre class="screen">[root qmail-1.03]# <strong class="userinput"><code>rm -f /usr/bin/sendmail /usr/sbin/sendmail</code></strong> [root qmail-1.03]# <strong class="userinput"><code>ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</code></strong> [root qmail-1.03]# -<span class="action"><span class="action">rm -f /usr/bin/sendmail /usr/sbin/sendmail -ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</span></span></pre><p>Configure qmail - specifically, run the config script to set up files in <code class="computeroutput">/var/qmail/control</code> specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read <code class="computeroutput">/var/qmail/doc/INSTALL.ctl</code> to find out how to configure qmail.</p><pre class="screen">[root qmail-1.03]# <strong class="userinput"><code>./config-fast <span class="replaceable"><span class="replaceable">yourserver.test</span></span></code></strong> +<span class="action">rm -f /usr/bin/sendmail /usr/sbin/sendmail +ln -s /var/qmail/bin/sendmail /usr/sbin/sendmail</span></pre> + <p>Configure qmail - specifically, run the config script to set up files in <code class="computeroutput">/var/qmail/control</code> specifying the computer's identity and which addresses it should accept mail for. This command will automatically set up qmail correctly if you have correctly set a valid host nome. If not, you'll want to read <code class="computeroutput">/var/qmail/doc/INSTALL.ctl</code> to find out how to configure qmail.</p> + <pre class="screen">[root qmail-1.03]# <strong class="userinput"><code>./config-fast <em class="replaceable"><code>yourserver.test</code></em></code></strong> Your fully qualified host name is yourserver.test. Putting yourserver.test into control/me... Putting yourserver.test into control/defaultdomain... @@ -117,29 +34,39 @@ Now qmail will refuse to accept SMTP messages except to yourserver.test. Make sure to change rcpthosts if you add hosts to locals or virtualdomains! [root qmail-1.03]# -<span class="action"><span class="action">./config-fast <span class="replaceable"><span class="replaceable">yourserver.test</span></span></span></span></pre><p>All incoming mail that isn't for a specific user is handled by the <code class="computeroutput">alias</code> user. This includes all root mail. These commands prepare the alias user to receive mail.</p><pre class="screen">[root qmail-1.03]# <strong class="userinput"><code>cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root</code></strong> +<span class="action">./config-fast <em class="replaceable"><code>yourserver.test</code></em></span></pre> + <p>All incoming mail that isn't for a specific user is handled by the <code class="computeroutput">alias</code> user. This includes all root mail. These commands prepare the alias user to receive mail.</p> + <pre class="screen">[root qmail-1.03]# <strong class="userinput"><code>cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root</code></strong> [root alias]# <strong class="userinput"><code>chmod 644 ~alias/.qmail*</code></strong> [root alias]# <strong class="userinput"><code>/var/qmail/bin/maildirmake ~alias/Maildir/</code></strong> [root alias]# <strong class="userinput"><code>chown -R alias.nofiles /var/qmail/alias/Maildir</code></strong> [root alias]# -<span class="action"><span class="action">cd ~alias; touch .qmail-postmaster .qmail-mailer-daemon .qmail-root +<span class="action">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</span></span></pre><a class="indexterm" name="idp140592107304760"></a><p>Configure qmail to use the Maildir delivery format - (instead of mbox), and install a version of the qmail startup script modified to use Maildir.</p><pre class="screen">[root alias]# <strong class="userinput"><code>echo "./Maildir" > /var/qmail/bin/.qmail</code></strong> +chown -R alias.nofiles /var/qmail/alias/Maildir</span></pre> + <a class="indexterm" name="idp140623162685720"></a> + <p>Configure qmail to use the Maildir delivery format + (instead of mbox), and install a version of the qmail startup script modified to use Maildir.</p> + <pre class="screen">[root alias]# <strong class="userinput"><code>echo "./Maildir" > /var/qmail/bin/.qmail</code></strong> [root alias]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc</code></strong> [root alias]# <strong class="userinput"><code>chmod 755 /var/qmail/rc</code></strong> [root alias]# -<span class="action"><span class="action">echo "./Maildir" > /var/qmail/bin/.qmail +<span class="action">echo "./Maildir" > /var/qmail/bin/.qmail cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/qmail.rc.txt /var/qmail/rc chmod 755 /var/qmail/rc -</span></span></pre><p>Set up the skeleton directory so that new users will - be configured for qmail.</p><pre class="screen">[root root]# <strong class="userinput"><code>/var/qmail/bin/maildirmake /etc/skel/Maildir</code></strong> +</span></pre> + <p>Set up the skeleton directory so that new users will + be configured for qmail.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>/var/qmail/bin/maildirmake /etc/skel/Maildir</code></strong> [root root]# <strong class="userinput"><code>echo "./Maildir/" > /etc/skel/.qmail</code></strong> [root root]# -<span class="action"><span class="action">/var/qmail/bin/maildirmake /etc/skel/Maildir -echo "./Maildir/" > /etc/skel/.qmail</span></span></pre><p>As recommended, we will run qmail with daemontools - control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.</p><pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /var/qmail/supervise/qmail-send/log</code></strong> +<span class="action">/var/qmail/bin/maildirmake /etc/skel/Maildir +echo "./Maildir/" > /etc/skel/.qmail</span></pre> + + <p>As recommended, we will run qmail with daemontools + control files. Create daemontools control directories, set up a daemontools control script, copy the supervise control files, and set permissions. The last line links the control directories to /service, which will cause supervise to detect them and execute the run files, causing qmail to start.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mkdir -p /var/qmail/supervise/qmail-send/log</code></strong> [root root]# <strong class="userinput"><code>mkdir -p /var/qmail/supervise/qmail-smtpd/log</code></strong> [root root]# <strong class="userinput"><code>mkdir /var/log/qmail</code></strong> [root root]# <strong class="userinput"><code>chown qmaill /var/log/qmail</code></strong> @@ -156,7 +83,7 @@ [root root]# <strong class="userinput"><code>chmod 755 /var/qmail/supervise/qmail-smtpd/log/run</code></strong> [root root]# <strong class="userinput"><code>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</code></strong> [root root]# <strong class="userinput"><code>ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service</code></strong> -<span class="action"><span class="action">mkdir -p /var/qmail/supervise/qmail-send/log +<span class="action">mkdir -p /var/qmail/supervise/qmail-send/log mkdir -p /var/qmail/supervise/qmail-smtpd/log mkdir /var/log/qmail chown qmaill /var/log/qmail @@ -172,11 +99,16 @@ chmod 755 /var/qmail/supervise/qmail-smtpd/run chmod 755 /var/qmail/supervise/qmail-smtpd/log/run ln -s /var/qmail/supervise/qmail-send /var/qmail/supervise/qmail-smtpd /service -</span></span></pre><p>Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.</p><pre class="screen">[root root]# <strong class="userinput"><code>qmailctl stat</code></strong> +</span></pre> + <p>Wait ten seconds or so, and then verify that that the four qmail processes are running. If uptimes don't rise above 1 second, this may indicate broken scripts that are continuously restarting. In that case, start debugging by checking permissions.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>qmailctl stat</code></strong> /service/qmail-send: up (pid 32700) 430 seconds /service/qmail-send/log: up (pid 32701) 430 seconds /service/qmail-smtpd: up (pid 32704) 430 seconds /service/qmail-smtpd/log: up (pid 32705) 430 seconds messages in queue: 0 messages in queue but not yet preprocessed: 0 -[root root]#</pre><p>Further verify by sending and receiving email. Incoming mail for root is stored in <code class="computeroutput">/var/qmail/alias/Maildir</code>. </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr><tr><td width="40%" align="left">Install Daemontools (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Analog web file analyzer</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +[root root]#</pre> + <p>Further verify by sending and receiving email. Incoming mail for root is stored in <code class="computeroutput">/var/qmail/alias/Maildir</code>. </p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-daemontools.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="analog-install.html">Next</a></td></tr><tr><td width="40%" align="left">Install Daemontools (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Analog web file analyzer</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-redhat.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-redhat.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-redhat.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -12,11 +12,9 @@ <div class="appendix"> <div class="titlepage"><div><div><h2 class="title"> <a name="install-redhat" id="install-redhat"></a>Appendix A. Install -Red Hat 8/9</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This section takes a blank PC and sets up some supporting +Red Hat 8/9</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><p>This section takes a blank PC and sets up some supporting software. You should do this section as-is if you have a machine you can reformat and you want to be sure that your installation works and is secure; it should take about an hour. (In my @@ -38,45 +36,46 @@ <a name="install-first-step" id="install-first-step"></a>Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. -<a class="indexterm" name="idp140592097869976" id="idp140592097869976"></a> (Wherever you see the word secure, you +<a class="indexterm" name="idp140623091303016" id="idp140623091303016"></a> (Wherever you see the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're willing to exert and the estimated risk and consequences.")</p></li><li class="listitem"><p>Insert Red Hat 8.0 or 9.0 Disk 1 into the CD-ROM and reboot the -computer</p></li><li class="listitem"><p>At the <code class="computeroutput"><span class="guilabel"><span class="guilabel">boot:</span></span></code> -prompt, press Enter for a graphical install. The text install is -fairly different, so if you need to do that instead proceed with -caution, because the guide won't match the steps.</p></li><li class="listitem"><p>Checking the media is probably a waste of time, so when it asks -press Tab and then Enter to skip it.</p></li><li class="listitem"><p>After the graphical introduction page loads, click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> -</p></li><li class="listitem"><p>Choose the language you want to use and then click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> -</p></li><li class="listitem"><p>Select the keyboard layout you will use and Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> -</p></li><li class="listitem"><p>Choose your mouse type and Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> +computer</p></li><li class="listitem"><p>At the <code class="computeroutput"><span class="guilabel">boot:</span></code> prompt, press Enter for a graphical +install. The text install is fairly different, so if you need to do +that instead proceed with caution, because the guide won't +match the steps.</p></li><li class="listitem"><p>Checking the media is probably a waste of time, so when it asks +press Tab and then Enter to skip it.</p></li><li class="listitem"><p>After the graphical introduction page loads, click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> +</p></li><li class="listitem"><p>Choose the language you want to use and then click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> +</p></li><li class="listitem"><p>Select the keyboard layout you will use and Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> +</p></li><li class="listitem"><p>Choose your mouse type and Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> </p></li><li class="listitem"><p>Red Hat has several templates for new computers. We'll start with the "Server" template and then fine-tune it during -the rest of the install. Choose <code class="computeroutput"><span class="guilabel"><span class="guilabel">Server</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"> +the rest of the install. Choose <code class="computeroutput"><span class="guilabel">Server</span></code> and +click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"> <p>Reformat the hard drive. If you know what you're doing, do this step on your own. Otherwise: we're going to let the installer wipe out the everything on the main hard drive and then arrange things to its liking.</p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p>Choose <code class="computeroutput"><span class="guilabel"><span class="guilabel">Automatically -Partition</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> -</p></li><li class="listitem"><p>Uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Re<u><span class="accel">v</span></u>iew (and modify if needed) the partitions -created</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> +<li class="listitem"><p>Choose <code class="computeroutput"><span class="guilabel">Automatically Partition</span></code> and click +<code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> +</p></li><li class="listitem"><p>Uncheck <code class="computeroutput"><span class="guilabel">Re<span class="accel">v</span>iew (and modify if needed) +the partitions created</span></code> and click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> </p></li><li class="listitem"><p>On the pop-up window asking "Are you sure you want to do -this?" click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">Y</span></u>es</span></span></code> IF YOU ARE WIPING YOUR -HARD DRIVE.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> on the boot loader -screen</p></li> +this?" click <code class="computeroutput"><span class="guibutton"> +<span class="accel">Y</span>es</span></code> IF YOU ARE +WIPING YOUR HARD DRIVE.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> on the +boot loader screen</p></li> </ol></div> </li><li class="listitem"> -<p>Configure Networking. <a class="indexterm" name="idp140592098515848" id="idp140592098515848"></a> Again, if you +<p>Configure Networking. <a class="indexterm" name="idp140623091331368" id="idp140623091331368"></a> 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 @@ -87,29 +86,30 @@ doesn't, it will be tricky to access the OpenACS service from the outside world), we're going to set up that address. If you don't know your netmask, 255.255.255.0 is usually a pretty safe -guess. Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Edit</span></span></code>, -uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Configure using <u><span class="accel">D</span></u>HCP</span></span></code> and type in your IP -and netmask. Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">O</span></u>k</span></span></code>.</p></li><li class="listitem"><p>Type in your host name, gateway, and DNS server(s). Then click -<code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>We're going to use the firewall template for high security, +guess. Click <code class="computeroutput"><span class="guibutton">Edit</span></code>, uncheck <code class="computeroutput"><span class="guilabel">Configure using +<span class="accel">D</span>HCP</span></code> and type in your IP +and netmask. Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">O</span>k</span></code>.</p></li><li class="listitem"><p>Type in your host name, gateway, and DNS server(s). Then click +<code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>We're going to use the firewall template for high security, meaning that we'll block almost all incoming traffic. Then we'll add a few holes to the firewall for services which we -need and know are secure. Choose <code class="computeroutput"><span class="guilabel"><span class="guilabel">Hi<u><span class="accel">g</span></u>h</span></span></code> security level. Check -<code class="computeroutput"><span class="guilabel"><span class="guilabel">WWW</span></span></code>, <code class="computeroutput"><span class="guilabel"><span class="guilabel">SSH</span></span></code>, and <code class="computeroutput"><span class="guilabel"><span class="guilabel">Mail -(SMTP)</span></span></code>. In the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Other <u><span class="accel">p</span></u>orts</span></span></code> box, enter +need and know are secure. Choose <code class="computeroutput"><span class="guilabel">Hi<span class="accel">g</span>h</span></code> security level. Check <code class="computeroutput"><span class="guilabel">WWW</span></code>, +<code class="computeroutput"><span class="guilabel">SSH</span></code>, and <code class="computeroutput"><span class="guilabel">Mail (SMTP)</span></code>. +In the <code class="computeroutput"><span class="guilabel">Other +<span class="accel">p</span>orts</span></code> box, enter <strong class="userinput"><code>443, 8000, 8443</code></strong>. -Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code>. 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.</p></li> +Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code>. 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.</p></li> </ol></div> </li><li class="listitem"><p> -<a class="indexterm" name="idp140592098533608" id="idp140592098533608"></a>Select any additional languages you want -the computer to support and then click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> -</p></li><li class="listitem"><p>Choose your time zone and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>Type in a root password, twice.</p></li><li class="listitem"> +<a class="indexterm" name="idp140623091350264" id="idp140623091350264"></a>Select any additional languages you want +the computer to support and then click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> +</p></li><li class="listitem"><p>Choose your time zone and click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>Type in a root password, twice.</p></li><li class="listitem"> <p>On the Package selection page, we're going to uncheck a lot of packages that install software we don't need, and add packages that have stuff we do need. You should install everything @@ -120,66 +120,54 @@ 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.</p><table border="0" summary="Simple list" class="simplelist"> -<tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">Editors</span></span></code> -(this installs emacs<a class="indexterm" name="idp140592098541336" id="idp140592098541336"></a>),</td></tr><tr><td>click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Details</span></span></code> next -to <code class="computeroutput"><span class="guilabel"><span class="guilabel">Text-based Internet</span></span></code>, check -<code class="computeroutput"><span class="guilabel"><span class="guilabel">lynx</span></span></code>, and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">O</span></u>K</span></span></code>;</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">Authoring and -Publishing</span></span></code> (<a class="indexterm" name="idp140592098548152" id="idp140592098548152"></a>this installs -docbook),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Server Configuration -Tools</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Web -Server</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Windows File -Server</span></span></code>,</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">SQL Database -Server</span></span></code> (this installs PostgreSQL),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">Development -Tools</span></span></code> (this installs gmake and other build -tools),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Administration -Tools</span></span></code>, and</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Printing -Support</span></span></code>.</td></tr> -</table><p>At the bottom, check <code class="computeroutput"><span class="guilabel"><span class="guilabel"> -<u><span class="accel">S</span></u>elect Individual Packages</span></span></code> -and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> +<tr><td>check <code class="computeroutput"><span class="guilabel">Editors</span></code> (this installs emacs<a class="indexterm" name="idp140623091358664" id="idp140623091358664"></a>),</td></tr><tr><td>click <code class="computeroutput"><span class="guilabel">Details</span></code> next to <code class="computeroutput"><span class="guilabel">Text-based +Internet</span></code>, check <code class="computeroutput"><span class="guilabel">lynx</span></code>, and +click <code class="computeroutput"><span class="guibutton"> +<span class="accel">O</span>K</span></code>;</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">Authoring and Publishing</span></code> (<a class="indexterm" name="idp140623091366120" id="idp140623091366120"></a>this installs docbook),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Server Configuration Tools</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Web +Server</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Windows File Server</span></code>,</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">SQL +Database Server</span></code> (this installs PostgreSQL),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">Development Tools</span></code> (this installs gmake and +other build tools),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Administration Tools</span></code>, and</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Printing Support</span></code>.</td></tr> +</table><p>At the bottom, check <code class="computeroutput"><span class="guilabel"> +<span class="accel">S</span>elect Individual +Packages</span></code> and click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> </p> </li><li class="listitem"> <p>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 <code class="computeroutput"><span class="guilabel"><span class="guilabel"> -<u><span class="accel">F</span></u>lat -View</span></span></code> and wait. In a minute, a list of packages -will appear.</p><table border="0" summary="Simple list" class="simplelist"> -<tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">apmd</span></span></code> -(monitors power, not very useful for servers),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">ImageMagick</span></span></code> -(required for the <a class="indexterm" name="idp140592098566760" id="idp140592098566760"></a>photo-album packages,</td></tr><tr><td>uncheck<code class="computeroutput"><span class="guilabel"><span class="guilabel">isdn4k-utils</span></span></code> -(unless you are using isdn, this installs a useless daemon),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">mutt</span></span></code> (a mail -program that reads Maildir),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">nfs-utils</span></span></code> -(nfs is a major security risk),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">pam-devel</span></span></code> (I -don't remember why, but we don't want this),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">portmap</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">postfix</span></span></code> -(this is an MTA, but we're going to install qmail later),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">postgresql-devel</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">rsh</span></span></code> (rsh is -a security hole),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">sendmail</span></span></code> -(sendmail is an insecure MTA; we're going to install qmail -instead later),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">tcl</span></span></code> (we need -tcl), and</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">xinetd</span></span></code> -(xinetd handles incoming tcp connections. We'll install a -different, more secure program, ucspi-tcp).</td></tr><tr><td>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> +through all the packages in one big list, so select <code class="computeroutput"><span class="guilabel"> +<span class="accel">F</span>lat View</span></code> and wait. In a minute, a +list of packages will appear.</p><table border="0" summary="Simple list" class="simplelist"> +<tr><td>uncheck <code class="computeroutput"><span class="guilabel">apmd</span></code> (monitors power, not very useful for +servers),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">ImageMagick</span></code> (required for the <a class="indexterm" name="idp140623091218680" id="idp140623091218680"></a>photo-album packages,</td></tr><tr><td>uncheck<code class="computeroutput"><span class="guilabel">isdn4k-utils</span></code> (unless you are using isdn, +this installs a useless daemon),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">mutt</span></code> (a mail program that reads +Maildir),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">nfs-utils</span></code> (nfs is a major security +risk),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">pam-devel</span></code> (I don't remember why, but +we don't want this),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">portmap</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">postfix</span></code> (this is an MTA, but we're +going to install qmail later),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">postgresql-devel</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">rsh</span></code> (rsh is a security hole),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">sendmail</span></code> (sendmail is an insecure MTA; +we're going to install qmail instead later),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">tcl</span></code> (we need tcl), and</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">xinetd</span></code> (xinetd handles incoming tcp +connections. We'll install a different, more secure program, +ucspi-tcp).</td></tr><tr><td>Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> </td></tr> </table> </li><li class="listitem"><p>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 -<code class="computeroutput"><span class="guilabel"><span class="guilabel">I<u><span class="accel">g</span></u>nore Package -Dependencies</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code> to start the copying -of files.</p></li><li class="listitem"><p>Wait. Insert Disk 2 when asked.</p></li><li class="listitem"><p>Wait. Insert Disk 3 when asked.</p></li><li class="listitem"><p>If you know how to use it, create a boot disk. Since you can +<code class="computeroutput"><span class="guilabel">I<span class="accel">g</span>nore Package Dependencies</span></code> and click +<code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code> to start +the copying of files.</p></li><li class="listitem"><p>Wait. Insert Disk 2 when asked.</p></li><li class="listitem"><p>Wait. Insert Disk 3 when asked.</p></li><li class="listitem"><p>If you know how to use it, create a boot disk. Since you can also boot into recovery mode with the Install CDs, this is less useful than it used to be, and we won't bother. Select -<code class="computeroutput"><span class="guilabel"><span class="guilabel">No,I <u><span class="accel">d</span></u>o not want to -create a boot disk</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel"> -<u><span class="accel">E</span></u>xit</span></span></code>, remove the CD, and -watch the computer reboot.</p></li><li class="listitem"> +<code class="computeroutput"><span class="guilabel">No,I +<span class="accel">d</span>o not want to create a boot +disk</span></code> and click <code class="computeroutput"><span class="guibutton"> +<span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"> +<span class="accel">E</span>xit</span></code>, remove +the CD, and watch the computer reboot.</p></li><li class="listitem"> <p>After it finishes rebooting and shows the login prompt, log in:</p><pre class="screen"> yourserver login: <strong class="userinput"><code>root</code></strong> @@ -197,7 +185,7 @@ <p>Lock down SSH</p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> <p> -<a class="indexterm" name="idp140592098603064" id="idp140592098603064"></a> SSH is the protocol we use to connect +<a class="indexterm" name="idp140623091405192" id="idp140623091405192"></a> SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming ssh connections. As a security precaution, we are now going to tell ssh not to allow @@ -245,16 +233,16 @@ [root root]# <strong class="userinput"><code>chkconfig --del pcmcia</code></strong> [root root]# <strong class="userinput"><code>chkconfig --del netfs</code></strong> [root root]# -<span class="action"><span class="action">service pcmcia stop +<span class="action">service pcmcia stop service netfs stop chkconfig --del pcmcia -chkconfig --del netfs</span></span> +chkconfig --del netfs</span> </pre><p>If you installed PostgreSQL, do also <code class="computeroutput">service postgresql start</code> and <code class="computeroutput">chkconfig --add postgresql</code>.</p> </li><li class="listitem"><p>Plug in the network cable.</p></li><li class="listitem"> <p>Verify that you have connectivity by going to another computer -and ssh'ing to <span class="replaceable"><span class="replaceable">yourserver</span></span>, logging in as remadmin, and -promoting yourself to root:</p><pre class="screen"> -[joeuser\@someotherserver]$ <strong class="userinput"><code> ssh <span class="replaceable"><span class="replaceable">remadmin\@yourserver.test</span></span> +and ssh'ing to <em class="replaceable"><code>yourserver</code></em>, logging in as remadmin, +and promoting yourself to root:</p><pre class="screen"> +[joeuser\@someotherserver]$ <strong class="userinput"><code> ssh <em class="replaceable"><code>remadmin\@yourserver.test</code></em> </code></strong> The authenticity of host 'yourserver.test (1.2.3.4)' can't be established. DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5. @@ -298,10 +286,10 @@ The system is going down for reboot NOW! [root tmp]# -<span class="action"><span class="action">cd /var/tmp +<span class="action">cd /var/tmp wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm -reboot</span></span> +reboot</span> </pre> </li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/install-redhat.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-redhat.html,v diff -u -r1.42 -r1.43 --- openacs-4/packages/acs-core-docs/www/install-redhat.html 7 Aug 2017 23:47:51 -0000 1.42 +++ openacs-4/packages/acs-core-docs/www/install-redhat.html 8 Nov 2017 09:42:11 -0000 1.43 @@ -1,17 +1,31 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix A. Install Red Hat 8/9</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="backups-with-cvs.html" title="Using CVS for backup-recovery"><link rel="next" href="install-more-software.html" title="Appendix B. Install additional supporting software"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="backups-with-cvs.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="install-redhat"></a>Appendix A. Install Red Hat 8/9</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This section takes a blank PC and sets up some supporting +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Appendix A. Install Red Hat 8/9</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="backups-with-cvs.html" title="Using CVS for backup-recovery"><link rel="next" href="install-more-software.html" title="Appendix B. Install additional supporting software"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="backups-with-cvs.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr></table><hr></div><div class="appendix"><div class="titlepage"><div><div><h2 class="title"><a name="install-redhat"></a>Appendix A. Install Red Hat 8/9</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <p>This section takes a blank PC and sets up some supporting software. You should do this section as-is if you have a machine you can reformat and you want to be sure that your installation works and is secure; it should take about an hour. (In my experience, it's almost always a net time savings of several hours to install a new machine from scratch compared to installing each - of these packages installed independently.)</p><p>The installation guide assumes you have:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A PC with hard drive you can reinstall</p></li><li class="listitem"><p>Red Hat 8.0 or 9.0 install discs</p></li><li class="listitem"><p>A CD with the current <a class="ulink" href="http://www.redhat.com/apps/support/errata/" target="_top">Security - Patches</a> for your version of Red Hat.</p></li></ul></div><p>The installation guide assumes that you can do the following on + of these packages installed independently.)</p> + + <p>The installation guide assumes you have:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A PC with hard drive you can reinstall</p> + </li><li class="listitem"><p>Red Hat 8.0 or 9.0 install discs</p> + </li><li class="listitem"><p>A CD with the current <a class="ulink" href="http://www.redhat.com/apps/support/errata/" target="_top">Security + Patches</a> for your version of Red Hat.</p> + </li></ul></div> + +<p>The installation guide assumes that you can do the following on your platform: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Adding users, groups, setting passwords </p></li><li class="listitem"><p> (For Oracle) Starting an X server and running an X program remotely @@ -20,66 +34,83 @@ mv,</code> and <code class="computeroutput">cd</code> </p></li><li class="listitem"><p> Compiling a program using ./config and make. - </p></li></ul></div><p> + </p></li></ul></div> + + <p> You can complete this install without the above knowledge, but if anything goes wrong it may take extra time to understand and correct the problem. <a class="link" href="install-resources.html" title="Resources">Some useful UNIX resources</a>. - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><a name="install-first-step"></a>Unplug the network cable from your + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><a name="install-first-step"></a>Unplug the network cable from your computer. We don't want to connect to the network until we're sure the computer is secure. - <a class="indexterm" name="idp140592097869976"></a> + <a class="indexterm" name="idp140623091303016"></a> (Wherever you see the word secure, you should always read it as, "secure enough for our purposes, given the amount of work we're willing to exert and the estimated risk and - consequences.")</p></li><li class="listitem"><p>Insert Red Hat 8.0 or 9.0 Disk 1 into the + consequences.")</p> + </li><li class="listitem"> + <p>Insert Red Hat 8.0 or 9.0 Disk 1 into the CD-ROM and reboot the computer</p></li><li class="listitem"><p>At the - <code class="computeroutput"><span class="guilabel"><span class="guilabel">boot:</span></span></code> + <code class="computeroutput"><span class="guilabel">boot:</span></code> prompt, press Enter for a graphical install. The text install is fairly different, so if you need to do that instead proceed with caution, because the guide won't match the steps.</p></li><li class="listitem"><p>Checking the media is probably a waste of time, so when it asks press Tab and - then Enter to skip it.</p></li><li class="listitem"><p>After the graphical introduction page loads, click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>Choose the language you want to use and then click -<code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code> -</p></li><li class="listitem"><p>Select the keyboard layout you will use and Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>Choose your mouse type and Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>Red Hat has several templates for new + then Enter to skip it.</p></li><li class="listitem"><p>After the graphical introduction page loads, click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p></li><li class="listitem"><p>Choose the language you want to use and then click +<code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code> +</p> + </li><li class="listitem"><p>Select the keyboard layout you will use and Click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p></li><li class="listitem"><p>Choose your mouse type and Click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p></li><li class="listitem"><p>Red Hat has several templates for new computers. We'll start with the "Server" template and then fine-tune it during the rest of the install. Choose - <code class="computeroutput"><span class="guilabel"><span class="guilabel">Server</span></span></code> + <code class="computeroutput"><span class="guilabel">Server</span></code> and click - <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>Reformat the hard drive. If you know what you're doing, + <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code>.</p> + </li><li class="listitem"> + <p>Reformat the hard drive. If you know what you're doing, do this step on your own. Otherwise: we're going to let the installer wipe out the everything on the main hard drive and then arrange things to - its liking.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Choose <code class="computeroutput"><span class="guilabel"><span class="guilabel">Automatically Partition</span></span></code> - and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>Uncheck -<code class="computeroutput"><span class="guilabel"><span class="guilabel">Re<u><span class="accel">v</span></u>iew (and modify if needed) the partitions created</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>On the pop-up window asking "Are you sure + its liking.</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Choose <code class="computeroutput"><span class="guilabel">Automatically Partition</span></code> + and click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p></li><li class="listitem"><p>Uncheck +<code class="computeroutput"><span class="guilabel">Re<span class="accel">v</span>iew (and modify if needed) the partitions created</span></code> and click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p></li><li class="listitem"><p>On the pop-up window asking "Are you sure you want to do this?" click - <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">Y</span></u>es</span></span></code> - IF YOU ARE WIPING YOUR HARD DRIVE.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code> on the boot loader screen</p></li></ol></div></li><li class="listitem"><p>Configure Networking. <a class="indexterm" name="idp140592098515848"></a> + <code class="computeroutput"><span class="guibutton"><span class="accel">Y</span>es</span></code> + IF YOU ARE WIPING YOUR HARD DRIVE.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code> on the boot loader screen</p></li></ol></div> + </li><li class="listitem"> + <p>Configure Networking. <a class="indexterm" name="idp140623091331368"></a> 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.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>DHCP is a system by which a computer that + follow the instructions in this step to set up a computer directly connected to the internet with a dedicated IP address.</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>DHCP is a system by which a computer that joins a network (such as on boot) can request a temporary IP address and other network information. Assuming the machine has a dedicated IP address (if it doesn't, it will be tricky to access the OpenACS service from the outside world), we're going to set up that address. If you don't know your netmask, 255.255.255.0 is usually a pretty safe -guess. Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Edit</span></span></code>, uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Configure using <u><span class="accel">D</span></u>HCP</span></span></code> -and type in your IP and netmask. Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">O</span></u>k</span></span></code>.</p></li><li class="listitem"><p> Type in your host -name, gateway, and DNS server(s). Then click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>We're going to use the firewall template for high +guess. Click <code class="computeroutput"><span class="guibutton">Edit</span></code>, uncheck <code class="computeroutput"><span class="guilabel">Configure using <span class="accel">D</span>HCP</span></code> +and type in your IP and netmask. Click <code class="computeroutput"><span class="guibutton"><span class="accel">O</span>k</span></code>.</p> + </li><li class="listitem"><p> Type in your host +name, gateway, and DNS server(s). Then click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>We're going to use the firewall template for high security, meaning that we'll block almost all incoming traffic. Then we'll add a few holes to the firewall for services which we need and -know are secure. Choose <code class="computeroutput"><span class="guilabel"><span class="guilabel">Hi<u><span class="accel">g</span></u>h</span></span></code> +know are secure. Choose <code class="computeroutput"><span class="guilabel">Hi<span class="accel">g</span>h</span></code> security level. Check -<code class="computeroutput"><span class="guilabel"><span class="guilabel">WWW</span></span></code>, -<code class="computeroutput"><span class="guilabel"><span class="guilabel">SSH</span></span></code>, and -<code class="computeroutput"><span class="guilabel"><span class="guilabel">Mail (SMTP)</span></span></code>. In the <code class="computeroutput"><span class="guilabel"><span class="guilabel">Other <u><span class="accel">p</span></u>orts</span></span></code> +<code class="computeroutput"><span class="guilabel">WWW</span></code>, +<code class="computeroutput"><span class="guilabel">SSH</span></code>, and +<code class="computeroutput"><span class="guilabel">Mail (SMTP)</span></code>. In the <code class="computeroutput"><span class="guilabel">Other <span class="accel">p</span>orts</span></code> box, enter <strong class="userinput"><code>443, 8000, 8443</code></strong>. Click -<code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code>. -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.</p></li></ol></div></li><li class="listitem"><p><a class="indexterm" name="idp140592098533608"></a>Select any additional languages you want the +<code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code>. +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.</p> + </li></ol></div> + </li><li class="listitem"><p><a class="indexterm" name="idp140623091350264"></a>Select any additional languages you want the computer to support and then click - <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>Choose your time zone and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>Type in a root -password, twice.</p></li><li class="listitem"><p>On the Package selection page, we're going to + <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p></li><li class="listitem"><p>Choose your time zone and click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>Type in a root +password, twice.</p> + </li><li class="listitem"><p>On the Package selection page, we're going to uncheck a lot of packages that install software we don't need, and add packages that have stuff we do need. You should install everything we're installing here or the guide may not work for you; you can @@ -88,54 +119,79 @@ 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. -</p><table border="0" summary="Simple list" class="simplelist"><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">Editors</span></span></code> (this installs emacs<a class="indexterm" name="idp140592098541336"></a>),</td></tr><tr><td>click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Details</span></span></code> next to <code class="computeroutput"><span class="guilabel"><span class="guilabel">Text-based Internet</span></span></code>, check <code class="computeroutput"><span class="guilabel"><span class="guilabel">lynx</span></span></code>, and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">O</span></u>K</span></span></code>;</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">Authoring and Publishing</span></span></code> (<a class="indexterm" name="idp140592098548152"></a>this installs docbook),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Server Configuration Tools</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Web Server</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Windows File Server</span></span></code>,</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">SQL Database Server</span></span></code> (this installs PostgreSQL),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">Development Tools</span></span></code> (this installs gmake and other build tools),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Administration Tools</span></span></code>, and</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">Printing Support</span></span></code>.</td></tr></table><p>At the bottom, check <code class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">S</span></u>elect Individual Packages</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></p></li><li class="listitem"><p>We need to fine-tune the exact list of packages. +</p><table border="0" summary="Simple list" class="simplelist"><tr><td>check <code class="computeroutput"><span class="guilabel">Editors</span></code> (this installs emacs<a class="indexterm" name="idp140623091358664"></a>),</td></tr><tr><td>click <code class="computeroutput"><span class="guilabel">Details</span></code> next to <code class="computeroutput"><span class="guilabel">Text-based Internet</span></code>, check <code class="computeroutput"><span class="guilabel">lynx</span></code>, and click <code class="computeroutput"><span class="guibutton"><span class="accel">O</span>K</span></code>;</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">Authoring and Publishing</span></code> (<a class="indexterm" name="idp140623091366120"></a>this installs docbook),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Server Configuration Tools</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Web Server</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Windows File Server</span></code>,</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">SQL Database Server</span></code> (this installs PostgreSQL),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">Development Tools</span></code> (this installs gmake and other build tools),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Administration Tools</span></code>, and</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">Printing Support</span></code>.</td></tr></table> +<p>At the bottom, check <code class="computeroutput"><span class="guilabel"><span class="accel">S</span>elect Individual Packages</span></code> and click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></p> + +</li><li class="listitem"><p>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 -<code class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">F</span></u>lat -View</span></span></code> and wait. In a minute, a -list of packages will appear.</p><table border="0" summary="Simple list" class="simplelist"><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">apmd</span></span></code> (monitors power, not very useful for servers), </td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">ImageMagick</span></span></code> (required for the <a class="indexterm" name="idp140592098566760"></a>photo-album packages, </td></tr><tr><td>uncheck<code class="computeroutput"><span class="guilabel"><span class="guilabel">isdn4k-utils</span></span></code> (unless you are using isdn, this installs a useless daemon), </td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">mutt</span></span></code> (a mail program that reads Maildir),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">nfs-utils</span></span></code> (nfs is a major security risk), </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">pam-devel</span></span></code> (I don't remember why, but we don't want this), </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">portmap</span></span></code>, </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">postfix</span></span></code> (this is an MTA, but we're going to install qmail later), </td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">postgresql-devel</span></span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">rsh</span></span></code> (rsh is a security hole), </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">sendmail</span></span></code> (sendmail is an insecure MTA; we're going to install qmail instead later),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel"><span class="guilabel">tcl</span></span></code> (we need tcl), and </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel"><span class="guilabel">xinetd</span></span></code> (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).</td></tr><tr><td>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code></td></tr></table></li><li class="listitem"><p>Red Hat isn't completely happy with the combination +<code class="computeroutput"><span class="guilabel"><span class="accel">F</span>lat +View</span></code> and wait. In a minute, a +list of packages will appear.</p> +<table border="0" summary="Simple list" class="simplelist"><tr><td>uncheck <code class="computeroutput"><span class="guilabel">apmd</span></code> (monitors power, not very useful for servers), </td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">ImageMagick</span></code> (required for the <a class="indexterm" name="idp140623091218680"></a>photo-album packages, </td></tr><tr><td>uncheck<code class="computeroutput"><span class="guilabel">isdn4k-utils</span></code> (unless you are using isdn, this installs a useless daemon), </td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">mutt</span></code> (a mail program that reads Maildir),</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">nfs-utils</span></code> (nfs is a major security risk), </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">pam-devel</span></code> (I don't remember why, but we don't want this), </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">portmap</span></code>, </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">postfix</span></code> (this is an MTA, but we're going to install qmail later), </td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">postgresql-devel</span></code>,</td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">rsh</span></code> (rsh is a security hole), </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">sendmail</span></code> (sendmail is an insecure MTA; we're going to install qmail instead later),</td></tr><tr><td>check <code class="computeroutput"><span class="guilabel">tcl</span></code> (we need tcl), and </td></tr><tr><td>uncheck <code class="computeroutput"><span class="guilabel">xinetd</span></code> (xinetd handles incoming tcp connections. We'll install a different, more secure program, ucspi-tcp).</td></tr><tr><td>Click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code></td></tr></table> + +</li><li class="listitem"><p>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 -<code class="computeroutput"><span class="guilabel"><span class="guilabel">I<u><span class="accel">g</span></u>nore Package -Dependencies</span></span></code> and click -<code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code>. -</p></li><li class="listitem"><p>Click - <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code> +<code class="computeroutput"><span class="guilabel">I<span class="accel">g</span>nore Package +Dependencies</span></code> and click +<code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code>. +</p> + </li><li class="listitem"><p>Click + <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code> to start the copying of files.</p></li><li class="listitem"><p>Wait. Insert Disk 2 when asked.</p></li><li class="listitem"><p>Wait. Insert Disk 3 when asked.</p></li><li class="listitem"><p>If you know how to use it, create a boot disk. Since you can also boot into recovery mode with the Install CDs, this is less useful than it used to be, and we - won't bother. Select <code class="computeroutput"><span class="guilabel"><span class="guilabel">No,I <u><span class="accel">d</span></u>o not want to create a boot disk</span></span></code> and click <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">N</span></u>ext</span></span></code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">E</span></u>xit</span></span></code>, remove the CD, and watch the + won't bother. Select <code class="computeroutput"><span class="guilabel">No,I <span class="accel">d</span>o not want to create a boot disk</span></code> and click <code class="computeroutput"><span class="guibutton"><span class="accel">N</span>ext</span></code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="accel">E</span>xit</span></code>, remove the CD, and watch the computer reboot. -</p></li><li class="listitem"><p>After it finishes rebooting and shows the login - prompt, log in:</p><pre class="screen">yourserver login: <strong class="userinput"><code>root</code></strong> +</p> + </li><li class="listitem"><p>After it finishes rebooting and shows the login + prompt, log in:</p> + <pre class="screen">yourserver login: <strong class="userinput"><code>root</code></strong> Password: -[root root]#</pre></li><li class="listitem"><p>Install any security patches. For example, insert your CD with +[root root]#</pre> + </li><li class="listitem"> + <p>Install any security patches. For example, insert your CD with patches, mount it with <code class="computeroutput">mount /dev/cdrom</code>, then <code class="computeroutput">cd /mnt/cdrom</code>, then <code class="computeroutput">rpm -UVH *rpm</code>. Both Red Hat 8.0 and 9.0 have had both kernel and openssl/openssh root exploits, so you should be upgrading all of that. Since you are upgrading the kernel, reboot after this step. -</p></li><li class="listitem"><p>Lock down SSH</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> - <a class="indexterm" name="idp140592098603064"></a> +</p> + </li><li class="listitem"> + <p>Lock down SSH</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p> + <a class="indexterm" name="idp140623091405192"></a> SSH is the protocol we use to connect securely to the computer (replacing telnet, which is insecure). sshd is the daemon that listens for incoming ssh connections. As a security precaution, we are now going to tell ssh not to allow anyone to connect directly to this computer as root. Type this into the shell: - </p><pre class="screen"><strong class="userinput"><code>emacs /etc/ssh/sshd_config</code></strong></pre></li><li class="listitem"><p>Search for the word "root" by typing <strong class="userinput"><code>C-s</code></strong> (that's emacs-speak for control-s) and then <strong class="userinput"><code>root</code></strong>.</p></li><li class="listitem"><p>Make the following changes:</p><table border="0" summary="Simple list" class="simplelist"><tr><td><code class="computeroutput">#Protocol 2,1</code> to + </p> + <pre class="screen"><strong class="userinput"><code>emacs /etc/ssh/sshd_config</code></strong></pre> + </li><li class="listitem"> + <p>Search for the word "root" by typing <strong class="userinput"><code>C-s</code></strong> (that's emacs-speak for control-s) and then <strong class="userinput"><code>root</code></strong>.</p> + </li><li class="listitem"> + <p>Make the following changes:</p> + <table border="0" summary="Simple list" class="simplelist"><tr><td><code class="computeroutput">#Protocol 2,1</code> to <code class="computeroutput">Protocol 2</code> (this prevents any connections via SSH 1, which is insecure)</td></tr><tr><td><code class="computeroutput">#PermitRootLogin yes</code> to <code class="computeroutput">PermitRootLogin no</code> (this prevents the root user from logging in remotely via ssh. If you do this, be sure to create a remote access account, such as "remadmin", which you can use to get ssh before using "su" to become root)</td></tr><tr><td><code class="computeroutput">#PermitEmptyPasswords no</code> to <code class="computeroutput">PermitEmptyPasswords no</code> - (this blocks passwordless accounts) and save and exit by typing <strong class="userinput"><code>C-x C-s C-x C-c</code></strong></td></tr></table></li><li class="listitem"><p>Restart sshd so that the change takes effect.</p><pre class="screen"><strong class="userinput"><code>service sshd restart</code></strong></pre></li></ol></div></li><li class="listitem"><p> + (this blocks passwordless accounts) and save and exit by typing <strong class="userinput"><code>C-x C-s C-x C-c</code></strong></td></tr></table> + </li><li class="listitem"><p>Restart sshd so that the change takes effect.</p><pre class="screen"><strong class="userinput"><code>service sshd restart</code></strong></pre> + </li></ol></div> + </li><li class="listitem"> + <p> Red Hat still installed a few services we don't need, and which can be security holes. Use the service command to turn them off, and then use chkconfig to automatically edit the @@ -149,19 +205,26 @@ (The reason for this discrepencies is that, while daemontools is better, it's a pain in the ass to deal with and nobody's had any trouble leaving PostgreSQL the way it is.) - </p><pre class="screen">[root root]# <strong class="userinput"><code>service pcmcia stop</code></strong> + </p> +<pre class="screen">[root root]# <strong class="userinput"><code>service pcmcia stop</code></strong> [root root]# <strong class="userinput"><code>service netfs stop</code></strong> [root root]# <strong class="userinput"><code>chkconfig --del pcmcia</code></strong> [root root]# <strong class="userinput"><code>chkconfig --del netfs</code></strong> [root root]# -<span class="action"><span class="action">service pcmcia stop +<span class="action">service pcmcia stop service netfs stop chkconfig --del pcmcia -chkconfig --del netfs</span></span></pre><p>If you installed PostgreSQL, do also -<code class="computeroutput">service postgresql start</code> and <code class="computeroutput">chkconfig --add postgresql</code>.</p></li><li class="listitem"><p>Plug in the network cable.</p></li><li class="listitem"><p>Verify that you have connectivity by going to another +chkconfig --del netfs</span></pre> + <p>If you installed PostgreSQL, do also +<code class="computeroutput">service postgresql start</code> and <code class="computeroutput">chkconfig --add postgresql</code>.</p> + </li><li class="listitem"> + <p>Plug in the network cable.</p> + </li><li class="listitem"> + <p>Verify that you have connectivity by going to another computer and ssh'ing to - <span class="replaceable"><span class="replaceable">yourserver</span></span>, logging in as - remadmin, and promoting yourself to root:</p><pre class="screen">[joeuser@someotherserver]$ <strong class="userinput"><code> ssh <span class="replaceable"><span class="replaceable">remadmin@yourserver.test</span></span></code></strong> + <em class="replaceable"><code>yourserver</code></em>, logging in as + remadmin, and promoting yourself to root:</p> +<pre class="screen">[joeuser@someotherserver]$ <strong class="userinput"><code> ssh <em class="replaceable"><code>remadmin@yourserver.test</code></em></code></strong> The authenticity of host 'yourserver.test (1.2.3.4)' can't be established. DSA key fingerprint is 10:b9:b6:10:79:46:14:c8:2d:65:ae:c1:61:4b:a5:a5. Are you sure you want to continue connecting (yes/no)? <strong class="userinput"><code>yes</code></strong> @@ -170,12 +233,16 @@ Last login: Mon Mar 3 21:15:27 2003 from host-12-01.dsl-sea.seanet.com [remadmin remadmin]$ <strong class="userinput"><code>su -</code></strong> Password: -[root root]#</pre></li><li class="listitem"><p>If you didn't burn a CD of patches and use it, can still +[root root]#</pre> + </li><li class="listitem"> + <p>If you didn't burn a CD of patches and use it, can still download and install the necessary patches. Here's how to do it for the kernel; you should also check for other - critical packages.</p><p>Upgrade the kernel to fix a security hole. The default + critical packages.</p> + <p>Upgrade the kernel to fix a security hole. The default Red Hat 8.0 system kernel (2.4.18-14, which you can check - with <strong class="userinput"><code>uname -a</code></strong>) has several <a class="ulink" href="https://rhn.redhat.com/errata/RHSA-2003-098.html" target="_top">security problems</a>. Download the new kernel, install it, and reboot.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /var/tmp</code></strong> + with <strong class="userinput"><code>uname -a</code></strong>) has several <a class="ulink" href="https://rhn.redhat.com/errata/RHSA-2003-098.html" target="_top">security problems</a>. Download the new kernel, install it, and reboot.</p> +<pre class="screen">[root root]# <strong class="userinput"><code>cd /var/tmp</code></strong> [root tmp]# <strong class="userinput"><code>wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm</code></strong> --20:39:00-- http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm => `kernel-2.4.18-27.7.x.i686.rpm' @@ -198,7 +265,10 @@ The system is going down for reboot NOW! [root tmp]# -<span class="action"><span class="action">cd /var/tmp +<span class="action">cd /var/tmp wget http://updates.redhat.com/7.1/en/os/i686/kernel-2.4.18-27.7.x.i686.rpm rpm -Uvh kernel-2.4.18-27.7.x.i686.rpm -reboot</span></span></pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backups-with-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr><tr><td width="40%" align="left">Using CVS for backup-recovery </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Appendix B. Install additional supporting software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +reboot</span></pre> + </li></ol></div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="backups-with-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-more-software.html">Next</a></td></tr><tr><td width="40%" align="left">Using CVS for backup-recovery </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Appendix B. Install additional supporting software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-resources.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-resources.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-resources.html 7 Aug 2017 23:47:51 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-resources.html 8 Nov 2017 09:42:11 -0000 1.18 @@ -1,8 +1,16 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Resources</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="os-security.html" title="Security Information"><link rel="next" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="os-security.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-resources"></a>Resources</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Resources</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="os-security.html" title="Security Information"><link rel="next" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="os-security.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-resources"></a>Resources</h2></div></div></div> + + + <p> Here are some resources that OpenACS users have found useful. - </p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="install-resources-books"></a>Books</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="install-resources-books"></a>Books</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + <a class="ulink" href="http://www.amazon.com/exec/obidos/ASIN/1558605347/photonetA" target="_top">Philip and Alex's Guide to Web Publishing</a> - A very readable guide to database-backed community websites. @@ -34,8 +42,13 @@ <a class="ulink" href="http://www.amazon.com/exec/obidos/ASIN/1565925858/photonetA" target="_top">Linux in a Nutshell</a> - </p></li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="install-resources-web"></a>Web Sites</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p></li></ul></div> + <div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="install-resources-web"></a>Web Sites</h4></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + <a class="ulink" href="https://web.archive.org/web/19990302021704/http://www.geek-girl.com:80/unix.html" target="_top">The UNIX Reference Desk</a> @@ -51,4 +64,8 @@ IBM developerworks on basic and intermediate Linux skills (requires registration) - </p></li></ul></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="os-security.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Security Information </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Part III. For OpenACS Package Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p></li></ul></div> + + </div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="os-security.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-package-dev.html">Next</a></td></tr><tr><td width="40%" align="left">Security Information </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Part III. For OpenACS Package Developers</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-squirrelmail.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-squirrelmail.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-squirrelmail.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-squirrelmail.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -13,11 +13,9 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="install-squirrelmail" id="install-squirrelmail"></a>Install -Squirrelmail for use as a webmail system for OpenACS</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte Sussdorff</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This section is work in progress. It will detail how you can +Squirrelmail for use as a webmail system for OpenACS</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:openacs\@sussdorff.de" target="_top">Malte +Sussdorff</a> +</span></p><span style="color: red"></authorblurb></span><p>This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a separate webmail package within OpenACS</p><pre class="screen"> Index: openacs-4/packages/acs-core-docs/www/install-squirrelmail.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-squirrelmail.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/install-squirrelmail.html 7 Aug 2017 23:47:51 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/install-squirrelmail.html 8 Nov 2017 09:42:11 -0000 1.18 @@ -1,11 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Squirrelmail for use as a webmail system for OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-php.html" title="Install PHP for use in AOLserver"><link rel="next" href="install-pam-radius.html" title="Install PAM Radius for use as external authentication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-php.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-pam-radius.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-squirrelmail"></a>Install Squirrelmail for use as a webmail system for OpenACS</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a separate webmail package within OpenACS</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# <strong class="userinput"><code>cd www</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Squirrelmail for use as a webmail system for OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-php.html" title="Install PHP for use in AOLserver"><link rel="next" href="install-pam-radius.html" title="Install PAM Radius for use as external authentication"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-php.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-pam-radius.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-squirrelmail"></a>Install Squirrelmail for use as a webmail system for OpenACS</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:openacs@sussdorff.de" target="_top">Malte Sussdorff</a></p> + </authorblurb></span> + + <p>This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a separate webmail package within OpenACS</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# <strong class="userinput"><code>cd www</code></strong> [$OPENACS_SERVICE_NAME www]# <strong class="userinput"><code>wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.4.tar.gz</code></strong> [$OPENACS_SERVICE_NAME www]# <strong class="userinput"><code>tar xfz squirrelmail-1.4.4.tar.gz</code></strong> [$OPENACS_SERVICE_NAME www]# <strong class="userinput"><code>mv squirrelmail-1.4.4 mail</code></strong> [$OPENACS_SERVICE_NAME www]# <strong class="userinput"><code>cd mail/config</code></strong> [$OPENACS_SERVICE_NAME www]# <strong class="userinput"><code>./conf.pl</code></strong> - </pre><p>Now you are about to configure Squirrelmail. The configuration heavily depends on your setup, so no instructions are given here.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-php.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-pam-radius.html">Next</a></td></tr><tr><td width="40%" align="left">Install PHP for use in AOLserver </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install PAM Radius for use as external authentication</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + <p>Now you are about to configure Squirrelmail. The configuration heavily depends on your setup, so no instructions are given here.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-php.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-pam-radius.html">Next</a></td></tr><tr><td width="40%" align="left">Install PHP for use in AOLserver </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install PAM Radius for use as external authentication</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-ssl.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-ssl.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-ssl.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-ssl.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -18,14 +18,12 @@ #ns_param nsopenssl ${bindir}/nsopenssl.so </pre> </li><li class="listitem"> -<p> -<a name="ssl-certificates" id="ssl-certificates"></a>Prepare a -certificate directory for the service.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs</code></strong> -[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>chmod 700 /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs</code></strong> +<p>Prepare a certificate directory for the service.</p><pre class="screen"> +[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs</code></strong> +[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>chmod 700 /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs</code></strong> [$OPENACS_SERVICE_NAME etc]$ -<span class="action"><span class="action">mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs -chmod 700 /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs</span></span> +<span class="action">mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs +chmod 700 /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs</span> </pre> </li><li class="listitem"> <p>It takes two files to support an SSL connection. The certificate 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 -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/install-ssl.html 7 Aug 2017 23:47:51 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/install-ssl.html 8 Nov 2017 09:42:11 -0000 1.17 @@ -1,34 +1,64 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing SSL Support for an OpenACS service</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="maintenance-deploy.html" title="Staged Deployment for Production Networks"><link rel="next" href="analog-setup.html" title="Set up Log Analysis Reports"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance-deploy.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="analog-setup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-ssl"></a>Installing SSL Support for an OpenACS service</h2></div></div></div><p>Debian Users: <code class="computeroutput">apt-get install openssl</code> before proceeding.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Make sure nsopenssl.so is <a class="link" href="install-nsopenssl.html" title="Install nsopenssl">installed</a> for AOLserver.</p></li><li class="listitem"><p>Uncomment this line from <code class="computeroutput">config.tcl</code>.</p><pre class="programlisting">#ns_param nsopenssl ${bindir}/nsopenssl.so -</pre></li><li class="listitem"><p><a name="ssl-certificates"></a>Prepare a certificate directory for the service.</p><pre class="screen">[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs</code></strong> -[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>chmod 700 /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Installing SSL Support for an OpenACS service</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="maintenance-deploy.html" title="Staged Deployment for Production Networks"><link rel="next" href="analog-setup.html" title="Set up Log Analysis Reports"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="maintenance-deploy.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="analog-setup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-ssl"></a>Installing SSL Support for an OpenACS service</h2></div></div></div> + + <p>Debian Users: <code class="computeroutput">apt-get install openssl</code> before proceeding.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Make sure nsopenssl.so is <a class="link" href="install-nsopenssl.html" title="Install nsopenssl">installed</a> for AOLserver.</p> + </li><li class="listitem"> + <p>Uncomment this line from <code class="computeroutput">config.tcl</code>.</p> + <pre class="programlisting">#ns_param nsopenssl ${bindir}/nsopenssl.so +</pre> + </li><li class="listitem"> + <p>Prepare a certificate directory for the service.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs</code></strong> +[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>chmod 700 /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs</code></strong> [$OPENACS_SERVICE_NAME etc]$ -<span class="action"><span class="action">mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs -chmod 700 /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/certs</span></span></pre></li><li class="listitem"><p>It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.</p><p>Use an OpenSSL perl script to generate a certificate and key.</p><p> +<span class="action">mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs +chmod 700 /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/certs</span></pre> + </li><li class="listitem"> + <p>It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages.</p> + <p>Use an OpenSSL perl script to generate a certificate and key.</p> + + <p> Debian users: use /usr/lib/ssl/misc/CA.pl instead of /usr/share/ssl/CA - </p><p> + </p> + + <p> Mac OS X users: use perl /System/Library/OpenSSL/misc/CA.pl -newcert instead of /usr/share/ssl/CA - </p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs</code></strong> + </p> + + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs</code></strong> [$OPENACS_SERVICE_NAME certs]$ <strong class="userinput"><code>perl /usr/share/ssl/misc/CA -newcert</code></strong> Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key ...++++++ .......++++++ writing new private key to 'newreq.pem' -Enter PEM pass phrase:</pre><p>Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this:</p><pre class="screen">Certificate (and private key) is in newreq.pem -[$OPENACS_SERVICE_NAME certs]$</pre><p><code class="computeroutput">newreq.pem</code> contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. <span class="emphasis"><em>Security implication</em></span>: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.</p><pre class="screen">[root misc]# <strong class="userinput"><code>openssl rsa -in newreq.pem -out keyfile.pem</code></strong> +Enter PEM pass phrase:</pre> + <p>Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this:</p> + <pre class="screen">Certificate (and private key) is in newreq.pem +[$OPENACS_SERVICE_NAME certs]$</pre> + <p><code class="computeroutput">newreq.pem</code> contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. <span class="emphasis"><em>Security implication</em></span>: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site.</p> + <pre class="screen">[root misc]# <strong class="userinput"><code>openssl rsa -in newreq.pem -out keyfile.pem</code></strong> read RSA key Enter PEM pass phrase: writing RSA key -[$OPENACS_SERVICE_NAME certs]$ </pre><p>To create the certificate file, we take the combined file, copy it, and strip out the key.</p><pre class="screen">[$OPENACS_SERVICE_NAME certs]$ <strong class="userinput"><code>cp newreq.pem certfile.pem</code></strong> -[root misc]# <strong class="userinput"><code>emacs certfile.pem</code></strong></pre><p>Strip out the section that looks like</p><pre class="programlisting">-----BEGIN RSA PRIVATE KEY----- +[$OPENACS_SERVICE_NAME certs]$ </pre> + <p>To create the certificate file, we take the combined file, copy it, and strip out the key.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME certs]$ <strong class="userinput"><code>cp newreq.pem certfile.pem</code></strong> +[root misc]# <strong class="userinput"><code>emacs certfile.pem</code></strong></pre> + <p>Strip out the section that looks like</p> + <pre class="programlisting">-----BEGIN RSA PRIVATE KEY----- Proc-Type: 4,ENCRYPTED DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997 S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T <span class="emphasis"><em>(11 lines omitted)</em></span> 1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw== ------END RSA PRIVATE KEY-----</pre></li><li class="listitem"><p> +-----END RSA PRIVATE KEY-----</pre> + </li><li class="listitem"><p> If you start up using the etc/daemontools/run script, you will need to edit this script to make sure the ports are bound for SSL. Details of this are in the run script. - </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance-deploy.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="analog-setup.html">Next</a></td></tr><tr><td width="40%" align="left">Staged Deployment for Production Networks </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Set up Log Analysis Reports</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="maintenance-deploy.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="analog-setup.html">Next</a></td></tr><tr><td width="40%" align="left">Staged Deployment for Production Networks </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Set up Log Analysis Reports</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-steps.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-steps.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-steps.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -58,9 +58,10 @@ use this guide</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p> <code class="computeroutput">This</code> is text you will see on -screen, such as a <code class="computeroutput"><span class="guibutton"><span class="guibutton"> -<u><span class="accel">B</span></u>utton</span></span></code> or <code class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">link</span></u></span></span></code> in a radio button list -or menu.</p></li><li class="listitem"><p><strong class="userinput"><code>This is text that you will +screen, such as a <code class="computeroutput"><span class="guibutton"> +<span class="accel">B</span>utton</span></code> or +<code class="computeroutput"><span class="guilabel"><span class="accel">link</span></span></code> in a radio button list or +menu.</p></li><li class="listitem"><p><strong class="userinput"><code>This is text that you will type.</code></strong></p></li><li class="listitem"> <p>This is text from a program or file which you may need to examine or edit:</p><pre class="programlisting"> @@ -70,73 +71,73 @@ </pre> </li><li class="listitem"> <p>This is text that you will <code class="computeroutput">see</code> and <strong class="userinput"><code>type</code></strong> in a command shell, -including <span class="replaceable"><span class="replaceable">text -you may have to change</span></span>. It is followed by a list of -just the commands, which you can copy and paste. The command prompt -varies by system; in the examples we use the form<code class="computeroutput">[$OPENACS_SERVICE_NAME aolserver]$</code>, where +including <em class="replaceable"><code>text you may have to +change</code></em>. It is followed by a list of just the commands, +which you can copy and paste. The command prompt varies by system; +in the examples we use the form<code class="computeroutput">[$OPENACS_SERVICE_NAME aolserver]$</code>, where <code class="computeroutput">$OPENACS_SERVICE_NAME</code> is the current user and <code class="computeroutput">aolserver</code> is the current directory. The root prompt is shown ending in # and all other prompts in $.</p><pre class="screen"> [root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>dropdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>dropdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> DROP DATABASE -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>createdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>createdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> CREATE DATABASE -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -dropdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -createdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</span></span> +<span class="action">su - $OPENACS_SERVICE_NAME +svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +dropdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +createdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</span> </pre><p> <a name="cut-and-paste-name-var" id="cut-and-paste-name-var"></a><strong>Setting a global shell -variable for cut and paste. </strong>In order to cut +variable for cut and paste. </strong> In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME. In order to set it globally so that it works for any new users or special service users you may create, edit the file <code class="computeroutput">/etc/profile</code> ( <code class="computeroutput">/etc/share/skel/dot.profile</code> for FreeBSD) and add this line:</p><pre class="programlisting"> -export OPENACS_SERVICE_NAME=<span class="replaceable"><span class="replaceable">service0</span></span> +export OPENACS_SERVICE_NAME=<em class="replaceable"><code>service0</code></em> </pre> </li> </ul></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592102795240" id="idp140592102795240"></a>Paths and Users</h3></div></div></div><div class="table"> -<a name="idp140592102795880" id="idp140592102795880"></a><p class="title"><strong>Table 2.1. Default +<a name="idp140623179121976" id="idp140623179121976"></a>Paths and Users</h3></div></div></div><div class="table"> +<a name="idp140623179122616" id="idp140623179122616"></a><p class="title"><strong>Table 2.1. Default directories for a standard install</strong></p><div class="table-contents"><table class="table" summary="Default directories for a standard install" cellspacing="0" width="100%" border="1"> <colgroup> <col><col> </colgroup><tbody> <tr> -<td>Fully qualified domain name of your server</td><td><span class="replaceable"><span class="replaceable">yourserver.test</span></span></td> +<td>Fully qualified domain name of your server</td><td><em class="replaceable"><code>yourserver.test</code></em></td> </tr><tr> <td>name of administrative access account</td><td>remadmin</td> </tr><tr> <td>OpenACS service</td><td> -<a class="indexterm" name="idp140592102800488" id="idp140592102800488"></a><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> (set to service0 -in default install)</td> +<a class="indexterm" name="idp140623179128168" id="idp140623179128168"></a><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> (set to +service0 in default install)</td> </tr><tr> -<td>OpenACS service account</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td> +<td>OpenACS service account</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> -<td>OpenACS database name</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td> +<td>OpenACS database name</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> -<td>Root of OpenACS service file tree (SERVERROOT)</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME</span></span></td> +<td>Root of OpenACS service file tree (SERVERROOT)</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> <td>Location of source code tarballs for new software</td><td>/var/tmp</td> </tr><tr> <td>The OpenACS tarball contains some files which are useful while setting up other software. Those files are located at:</td><td>/var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files</td> </tr><tr> -<td>Database backup directory</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</span></span></td> +<td>Database backup directory</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</code></em></td> </tr><tr> -<td>Service config files</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</span></span></td> +<td>Service config files</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</code></em></td> </tr><tr> -<td>Service log files</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/log</span></span></td> +<td>Service log files</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/log</code></em></td> </tr><tr> <td>Compile directory</td><td>/usr/local/src</td> </tr><tr> @@ -148,9 +149,9 @@ </table></div> </div><br class="table-break"><p>None of these locations are set in stone - they're simply the values that we've chosen. The values that you'll -probably want to change, such as service name, are <span class="replaceable"><span class="replaceable">marked like -this</span></span>. The other values we recommend you leave -unchanged unless you have a reason to change them.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> +probably want to change, such as service name, are <em class="replaceable"><code>marked like this</code></em>. The other values +we recommend you leave unchanged unless you have a reason to change +them.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Note</h3><p>Some of the paths and user accounts have been changed from those recommended in previous versions of this document to improve security and maintainability. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=82934" target="_top">this thread</a> for discussion.</p> @@ -183,8 +184,8 @@ there's a SQL error in the Tcl error or in the log, post that too.</p></li><li class="listitem"><p>If you find errors in this document or if you have ideas about making it better, please post them in our <a class="ulink" href="http://openacs.org/bugtracker/openacs/" target="_top">BugTracker</a>.</p></li> -</ul></div><div class="cvstag">($‌Id: overview.xml,v 1.29.2.2 2016/06/23 -08:32:46 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: overview.xml,v 1.30 2017/08/07 +23:47:55 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/install-steps.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-steps.html,v diff -u -r1.36 -r1.37 --- openacs-4/packages/acs-core-docs/www/install-steps.html 7 Aug 2017 23:47:51 -0000 1.36 +++ openacs-4/packages/acs-core-docs/www/install-steps.html 8 Nov 2017 09:42:11 -0000 1.37 @@ -1,100 +1,200 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Basic Steps</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-overview.html" title="Chapter 2. Installation Overview"><link rel="previous" href="install-overview.html" title="Chapter 2. Installation Overview"><link rel="next" href="individual-programs.html" title="Prerequisite Software"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installation Overview</th><td width="20%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-steps"></a>Basic Steps</h2></div></div></div><p>Most of the documentation in this section is kept as a +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Basic Steps</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-overview.html" title="Chapter 2. Installation Overview"><link rel="previous" href="install-overview.html" title="Chapter 2. Installation Overview"><link rel="next" href="individual-programs.html" title="Prerequisite Software"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Installation Overview</th><td width="20%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-steps"></a>Basic Steps</h2></div></div></div> + + + <p>Most of the documentation in this section is kept as a reference. More up-to-date documentation is in the <a class="ulink" href="http://openacs.org/xowiki/openacs-system-install" target="_top">install sections in the Wiki</a>. - </p><p> + </p> + + + <p> The basic steps for installing OpenACS are: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install an OS and supporting software (see <a class="xref" href="unix-installation.html" title="Install a Unix-like system and supporting software">Install a Unix-like OS</a> or <a class="xref" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9">Appendix A, <i>Install Red Hat 8/9</i></a> for more details). See the <a class="xref" href="individual-programs.html#compatibility-matrix" title="Table 2.2. Version Compatibility Matrix">Table 2.2, “Version Compatibility Matrix”</a>.</p></li><li class="listitem"><p>Install a database (see <a class="xref" href="oracle.html" title="Install Oracle 8.1.7">the section called “Install Oracle 8.1.7”</a> or - <a class="xref" href="postgres.html" title="Install PostgreSQL">Install PostgreSQL</a>).</p></li><li class="listitem"><p> Install AOLserver (<a class="xref" href="aolserver4.html" title="Install AOLserver 4">Install AOLserver 4</a>) .</p></li><li class="listitem"><p>Create a unique database and system user. + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Install an OS and supporting software (see <a class="xref" href="unix-installation.html" title="Install a Unix-like system and supporting software">Install a Unix-like OS</a> or <a class="xref" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9">Appendix A, <i>Install Red Hat 8/9</i></a> for more details). See the <a class="xref" href="individual-programs.html#compatibility-matrix" title="Table 2.2. Version Compatibility Matrix">Table 2.2, “Version Compatibility Matrix”</a>.</p> + </li><li class="listitem"><p>Install a database (see <a class="xref" href="oracle.html" title="Install Oracle 8.1.7">the section called “Install Oracle 8.1.7”</a> or + <a class="xref" href="postgres.html" title="Install PostgreSQL">Install PostgreSQL</a>).</p> + </li><li class="listitem"> + <p> Install AOLserver (<a class="xref" href="aolserver4.html" title="Install AOLserver 4">Install AOLserver 4</a>) .</p> + </li><li class="listitem"><p>Create a unique database and system user. Install the OpenACS tarball, start and AOLserver instance, and use the OpenACS web pages to complete installation - (see <a class="xref" href="openacs.html" title="Install OpenACS 5.9.0">Install OpenACS 5.9.0</a>).</p></li></ol></div><p> Specific instructions are available for Mac OS X and + (see <a class="xref" href="openacs.html" title="Install OpenACS 5.9.0">Install OpenACS 5.9.0</a>).</p> + </li></ol></div> + + <p> Specific instructions are available for Mac OS X and Windows2000 (see <a class="xref" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X">the section called “OpenACS Installation Guide for Mac OS X”</a> or - <a class="xref" href="win2k-installation.html" title="OpenACS Installation Guide for Windows">the section called “OpenACS Installation Guide for Windows”</a>).</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-rpms"></a>Binaries and other shortcuts</h3></div></div></div><p>You can try out OpenACS using some binary installers. In + <a class="xref" href="win2k-installation.html" title="OpenACS Installation Guide for Windows">the section called “OpenACS Installation Guide for Windows”</a>).</p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-rpms"></a>Binaries and other shortcuts</h3></div></div></div> + + + <p>You can try out OpenACS using some binary installers. In general, they are not yet supported by the community, so they are mostly for evaluation purposes. <a class="ulink" href="http://openacs.org/faq/one-faq?faq_id=130897#130917" target="_top">Installing - OpenACS</a></p><p>You can see a list of <a class="ulink" href="http://openacs.org/projects/openacs/installer" target="_top">current installers</a>. - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + OpenACS</a></p> + + <p>You can see a list of <a class="ulink" href="http://openacs.org/projects/openacs/installer" target="_top">current installers</a>. + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> The packaged version of - PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.</p></li><li class="listitem"><p>Once AOLserver and a database are installed, a bash script <a class="link" href="openacs.html#install-with-script" title="Installation Option 1: Use automated script">automates the OpenACS checkout and + PostgreSQL in Debian, Red Hat, and FreeBSD ports works fine.</p> + </li><li class="listitem"> + <p>Once AOLserver and a database are installed, a bash script <a class="link" href="openacs.html#install-with-script" title="Installation Option 1: Use automated script">automates the OpenACS checkout and installation</a>. - </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-requirements"></a>System Requirements</h3></div></div></div><p> + </p> + </li></ol></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-requirements"></a>System Requirements</h3></div></div></div> + + <p> You will need a PC (or equivalent) with at least these minimum specifications: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>128MB RAM (much more if you want Oracle)</p></li><li class="listitem"><p>1GB free space on your hard drive (much more if you want Oracle)</p></li><li class="listitem"><p>A Unix-like operating system with Tcl, tDOM, and - a mail transport agent like sendmail or qmail. (see <a class="xref" href="individual-programs.html" title="Prerequisite Software">the section called “Prerequisite Software”</a>)</p></li></ul></div><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>128MB RAM (much more if you want Oracle)</p></li><li class="listitem"><p>1GB free space on your hard drive (much more if you want Oracle)</p></li><li class="listitem"><p>A Unix-like operating system with Tcl, tDOM, and + a mail transport agent like sendmail or qmail. (see <a class="xref" href="individual-programs.html" title="Prerequisite Software">the section called “Prerequisite Software”</a>)</p> + </li></ul></div><p> All of the software mentioned is open-source and available without direct costs, except for Oracle. You can obtain a free copy of Oracle for development purposes. This is described in the <a class="xref" href="oracle.html#install-oracle-getit" title="Acquire Oracle">Acquire Oracle</a> section. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="how-to-use"></a>How to use this guide</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">This</code> is text you will see on - screen, such as a <code class="computeroutput"><span class="guibutton"><span class="guibutton"><u><span class="accel">B</span></u>utton</span></span></code> or <code class="computeroutput"><span class="guilabel"><span class="guilabel"><u><span class="accel">link</span></u></span></span></code> - in a radio button list or menu.</p></li><li class="listitem"><p><strong class="userinput"><code>This is text that you will type.</code></strong></p></li><li class="listitem"><p>This is text from a program or file which you may need to - examine or edit:</p><pre class="programlisting">if {$database eq "oracle"} { + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="how-to-use"></a>How to use this guide</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><code class="computeroutput">This</code> is text you will see on + screen, such as a <code class="computeroutput"><span class="guibutton"><span class="accel">B</span>utton</span></code> or <code class="computeroutput"><span class="guilabel"><span class="accel">link</span></span></code> + in a radio button list or menu.</p> + </li><li class="listitem"><p><strong class="userinput"><code>This is text that you will type.</code></strong></p></li><li class="listitem"> + <p>This is text from a program or file which you may need to + examine or edit:</p> + <pre class="programlisting">if {$database eq "oracle"} { set db_password "mysitepassword" -}</pre></li><li class="listitem"><p>This is text that you will - <code class="computeroutput">see</code> and <strong class="userinput"><code>type</code></strong> in a command shell, including <span class="replaceable"><span class="replaceable">text you may have to - change</span></span>. It is followed by a list of just the commands, - which you can copy and paste. The command prompt varies by system; in the examples we use the form<code class="computeroutput">[$OPENACS_SERVICE_NAME aolserver]$</code>, where <code class="computeroutput">$OPENACS_SERVICE_NAME</code> is the current user and <code class="computeroutput">aolserver</code> is the current directory. The root prompt is shown ending in # and all other prompts in $.</p><pre class="screen"> +}</pre> + </li><li class="listitem"> + <p>This is text that you will + <code class="computeroutput">see</code> and <strong class="userinput"><code>type</code></strong> in a command shell, including <em class="replaceable"><code>text you may have to + change</code></em>. It is followed by a list of just the commands, + which you can copy and paste. The command prompt varies by system; in the examples we use the form<code class="computeroutput">[$OPENACS_SERVICE_NAME aolserver]$</code>, where <code class="computeroutput">$OPENACS_SERVICE_NAME</code> is the current user and <code class="computeroutput">aolserver</code> is the current directory. The root prompt is shown ending in # and all other prompts in $.</p> + <pre class="screen"> [root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>dropdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>dropdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> DROP DATABASE -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>createdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>createdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> CREATE DATABASE -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -dropdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -createdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></span></span></pre><p><a name="cut-and-paste-name-var"></a><b>Setting a global shell variable for cut and paste. </b>In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME. In order to set it globally so that it works for any new users or special service users you may create, edit the file <code class="computeroutput">/etc/profile</code> ( <code class="computeroutput">/etc/share/skel/dot.profile</code> for FreeBSD) and add this line:</p><pre class="programlisting">export OPENACS_SERVICE_NAME=<span class="replaceable"><span class="replaceable">service0</span></span></pre></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592102795240"></a>Paths and Users</h3></div></div></div><div class="table"><a name="idp140592102795880"></a><p class="title"><b>Table 2.1. Default directories for a standard install</b></p><div class="table-contents"><table class="table" summary="Default directories for a standard install" cellspacing="0" width="100%" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><span class="replaceable"><span class="replaceable">yourserver.test</span></span></td></tr><tr><td>name of administrative access account</td><td>remadmin</td></tr><tr><td>OpenACS service</td><td><a class="indexterm" name="idp140592102800488"></a> - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> (set to service0 in default install)</td></tr><tr><td>OpenACS service account</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>OpenACS database name</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>Root of OpenACS service file tree (SERVERROOT)</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>Location of source code tarballs for new software</td><td>/var/tmp</td></tr><tr><td>The OpenACS tarball contains some files which +<span class="action">su - $OPENACS_SERVICE_NAME +svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +dropdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +createdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></span></pre> + <p><a name="cut-and-paste-name-var"></a> + <b>Setting a global shell variable for cut and paste. </b> + In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME. In order to set it globally so that it works for any new users or special service users you may create, edit the file <code class="computeroutput">/etc/profile</code> ( <code class="computeroutput">/etc/share/skel/dot.profile</code> for FreeBSD) and add this line: + </p> + <pre class="programlisting">export OPENACS_SERVICE_NAME=<em class="replaceable"><code>service0</code></em></pre> + </li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623179121976"></a>Paths and Users</h3></div></div></div> + + + <div class="table"><a name="idp140623179122616"></a><p class="title"><b>Table 2.1. Default directories for a standard install</b></p><div class="table-contents"> + + <table class="table" summary="Default directories for a standard install" cellspacing="0" width="100%" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><em class="replaceable"><code>yourserver.test</code></em></td></tr><tr><td>name of administrative access account</td><td>remadmin</td></tr><tr><td>OpenACS service</td><td><a class="indexterm" name="idp140623179128168"></a> + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> (set to service0 in default install)</td></tr><tr><td>OpenACS service account</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>OpenACS database name</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>Root of OpenACS service file tree (SERVERROOT)</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>Location of source code tarballs for new software</td><td>/var/tmp</td></tr><tr><td>The OpenACS tarball contains some files which are useful while setting up other software. Those - files are located at:</td><td>/var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files</td></tr><tr><td>Database backup directory</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</span></span></td></tr><tr><td>Service config files</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</span></span></td></tr><tr><td>Service log files</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/log</span></span></td></tr><tr><td>Compile directory</td><td>/usr/local/src</td></tr><tr><td>PostgreSQL directory</td><td>/usr/local/pgsql</td></tr><tr><td>AOLserver directory</td><td>/usr/local/aolserver</td></tr></tbody></table></div></div><br class="table-break"><p> + files are located at:</td><td>/var/tmp/openacs-5.9.0/packages/acs-core-docs/www/files</td></tr><tr><td>Database backup directory</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</code></em></td></tr><tr><td>Service config files</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc</code></em></td></tr><tr><td>Service log files</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/log</code></em></td></tr><tr><td>Compile directory</td><td>/usr/local/src</td></tr><tr><td>PostgreSQL directory</td><td>/usr/local/pgsql</td></tr><tr><td>AOLserver directory</td><td>/usr/local/aolserver</td></tr></tbody></table> + </div></div><br class="table-break"> + + <p> None of these locations are set in stone - they're simply the values that we've chosen. The values that you'll probably want to change, such as service name, are - <span class="replaceable"><span class="replaceable">marked like this</span></span>. The other + <em class="replaceable"><code>marked like this</code></em>. The other values we recommend you leave unchanged unless you have a - reason to change them.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + reason to change them.</p> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + <p> Some of the paths and user accounts have been changed from those recommended in previous versions of this document to improve security and maintainability. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=82934" target="_top">this - thread</a> for discussion.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-stuck"></a>Getting Help during installation</h3></div></div></div><p> + thread</a> for discussion.</p> + </div> + + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-stuck"></a>Getting Help during installation</h3></div></div></div> + + + <p> We'll do our best to assure that following our instructions will get you to the promised land. If something goes wrong, don't panic. There are plenty of ways to get help. Here are some tips: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Keep track of the commands you are run and record their output. I like to do my installations in a shell inside of emacs (<code class="computeroutput">M-x shell</code>) so that I can save the output if needed. An alternative would be to use the <code class="computeroutput">script</code> command. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> We'll point out where the error logs for the various pieces of software are. Output from those logs will help us help you. Don't worry if you feel overwhelmed by all the information in the error logs. Over time, you'll find that they make more and more sense. Soon, you'll actually look forward to errors so that you can run to the log and diagnose the problem. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Search the <a class="ulink" href="http://openacs.org/forums/" target="_top">forums at openacs.org</a> - you'll often find many people who have struggled through the same spot that you're in. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The bottom of each page has a link to OpenACS.org, where you can post comments and read other users comments about the contents of the page. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Ask questions at the irc channel on <a class="ulink" href="http://freenode.net" target="_top">freenode.net</a> (#openacs). They're knowledgeable and quite friendly if you can keep them on topic. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Post a question on the <a class="ulink" href="http://openacs.org/forums/" target="_top">forums</a>. Make sure you've done a search first. When you do post, be sure to include your setup information (OS, etc) as well as the exact commands that are failing with the accompanying error. If there's a SQL error in the Tcl error or in the log, post that too. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> If you find errors in this document or if you have ideas about making it better, please post them in our <a class="ulink" href="http://openacs.org/bugtracker/openacs/" target="_top">BugTracker</a>. - </p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 2. Installation Overview </td><td width="20%" align="center"><a accesskey="u" href="install-overview.html">Up</a></td><td width="40%" align="right"> Prerequisite Software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li></ul></div> + <p><span class="cvstag">($Id$)</span></p> + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="individual-programs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 2. Installation Overview </td><td width="20%" align="center"><a accesskey="u" href="install-overview.html">Up</a></td><td width="40%" align="right"> Prerequisite Software</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/install-tclwebtest.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -15,14 +15,14 @@ required for auto-tests in OpenACS 5.1. When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) -As root:</p><pre class="screen"><span class="action"><span class="action">cd /tmp +As root:</p><pre class="screen"><span class="action">cd /tmp cvs -z3 -d:pserver:anonymous\@cvs.sourceforge.net:/cvsroot/tclwebtest co tclwebtest #wget http://umn.dl.sourceforge.net/sourceforge/tclwebtest/tclwebtest-1.0.tar.gz #tar xvzf tclwebtest-1-0.tar.gz mv tclwebtest-0.3 /usr/local/ ln -s /usr/local/tclwebtest-0.3 /usr/local/tclwebtest ln -s /usr/local/tclwebtest/tclwebtest /usr/local/bin -</span></span></pre> +</span></pre> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="install-nsopenssl" leftLabel="Prev" leftTitle="Install nsopenssl" Index: openacs-4/packages/acs-core-docs/www/install-tclwebtest.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/install-tclwebtest.html,v diff -u -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 7 Aug 2017 23:47:51 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/install-tclwebtest.html 8 Nov 2017 09:42:11 -0000 1.22 @@ -1,11 +1,16 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install tclwebtest.</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-nsopenssl.html" title="Install nsopenssl"><link rel="next" href="install-php.html" title="Install PHP for use in AOLserver"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-php.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-tclwebtest"></a>Install tclwebtest.</h2></div></div></div><p>Download the <a class="link" href="individual-programs.html#source-tclwebtest">tclwebtest +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install tclwebtest.</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-nsopenssl.html" title="Install nsopenssl"><link rel="next" href="install-php.html" title="Install PHP for use in AOLserver"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-php.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="install-tclwebtest"></a>Install tclwebtest.</h2></div></div></div> + + <p>Download the <a class="link" href="individual-programs.html#source-tclwebtest">tclwebtest source</a>, unpack it, and put it an appropriate - place. (tclwebtest 1.0 will be required for auto-tests in OpenACS 5.1. When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) As root:</p><pre class="screen"><span class="action"><span class="action">cd /tmp + place. (tclwebtest 1.0 will be required for auto-tests in OpenACS 5.1. When it exists, the cvs command here will be replaced with http://prdownloads.sourceforge.net/tclwebtest/tclwebtest-0.3.tar.gz?download.) As root:</p> + <pre class="screen"><span class="action">cd /tmp cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tclwebtest co tclwebtest #wget http://umn.dl.sourceforge.net/sourceforge/tclwebtest/tclwebtest-1.0.tar.gz #tar xvzf tclwebtest-1-0.tar.gz mv tclwebtest-0.3 /usr/local/ ln -s /usr/local/tclwebtest-0.3 /usr/local/tclwebtest ln -s /usr/local/tclwebtest/tclwebtest /usr/local/bin -</span></span></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-php.html">Next</a></td></tr><tr><td width="40%" align="left">Install nsopenssl </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install PHP for use in AOLserver</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</span></pre> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-nsopenssl.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-php.html">Next</a></td></tr><tr><td width="40%" align="left">Install nsopenssl </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install PHP for use in AOLserver</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/ix01.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/ix01.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/ix01.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -8,23 +8,23 @@ rightLink="" rightLabel=""> <div class="index"> <div class="titlepage"><div><div><h1 class="title"> -<a name="idp140592097697704" id="idp140592097697704"></a>Index</h1></div></div></div><div xmlns:xlink="http://www.w3.org/1999/xlink" class="index"> +<a name="idp140623181428584" id="idp140623181428584"></a>Index</h1></div></div></div><div xmlns:xlink="http://www.w3.org/1999/xlink" class="index"> <div class="indexdiv"> -<h3>Symbols</h3><dl><dt id="ientry-idp140592102800488">$OPENACS_SERVICE_NAME, <a class="indexterm" href="install-steps">Paths and +<h3>Symbols</h3><dl><dt id="ientry-idp140623179128168">$OPENACS_SERVICE_NAME, <a class="indexterm" href="install-steps">Paths and Users</a> </dt></dl> </div><div class="indexdiv"> <h3>A</h3><dl> -<dt id="ientry-idp140592101013272">AOLserver</dt><dd><dl><dt>configuration, <a class="indexterm" href="openacs">Installation Option 2: Install +<dt id="ientry-idp140623178345544">AOLserver</dt><dd><dl><dt>configuration, <a class="indexterm" href="openacs">Installation Option 2: Install from tarball</a> -</dt></dl></dd><dt id="ientry-idp140592102521720">Automated tests, <a class="indexterm" href="tutorial-debug">Write +</dt></dl></dd><dt id="ientry-idp140623162159976">Automated tests, <a class="indexterm" href="tutorial-debug">Write automated tests</a> </dt> </dl> </div><div class="indexdiv"> <h3>C</h3><dl> -<dt id="ientry-idp140592102002600">computeroutput</dt><dd><dl><dt>code, <a class="indexterm" href="docbook-primer">Code</a> -</dt></dl></dd><dt id="ientry-idp140592107194328">cvs</dt><dd><dl> +<dt id="ientry-idp140623175449672">computeroutput</dt><dd><dl><dt>code, <a class="indexterm" href="docbook-primer">Code</a> +</dt></dl></dd><dt id="ientry-idp140623161616552">cvs</dt><dd><dl> <dt>initializing, <a class="indexterm" href="install-cvs">Initialize CVS (OPTIONAL)</a> </dt><dt>setup, <a class="indexterm" href="cvs-tips">Using CVS with an OpenACS Site</a> @@ -33,104 +33,98 @@ </dl> </div><div class="indexdiv"> <h3>D</h3><dl> -<dt id="ientry-idp140592107210552">daemontools</dt><dd><dl><dt>installation, <a class="indexterm" href="install-daemontools">Install Daemontools (OPTIONAL)</a> -</dt></dl></dd><dt id="ientry-idp140592098548152">docbook</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> -</dt></dl></dd><dt id="ientry-idp140592107200216">DocBook</dt><dd><dl> +<dt id="ientry-idp140623170211560">daemontools</dt><dd><dl><dt>installation, <a class="indexterm" href="install-daemontools">Install Daemontools (OPTIONAL)</a> +</dt></dl></dd><dt id="ientry-idp140623091366120">docbook</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> +</dt></dl></dd><dt id="ientry-idp140623161896472">DocBook</dt><dd><dl> <dt>DTD, <a class="indexterm" href="docbook-primer">OpenACS Documentation Strategy: Why DocBook?</a> </dt><dt>emacs configuration for, <a class="indexterm" href="psgml-for-emacs">Add PSGML commands to emacs init file (OPTIONAL)</a> </dt> -</dl></dd><dt id="ientry-idp140592102567448">Document structure, <a class="indexterm" href="docbook-primer">Document +</dl></dd><dt id="ientry-idp140623175542264">Document structure, <a class="indexterm" href="docbook-primer">Document Structure</a> </dt> </dl> </div><div class="indexdiv"> <h3>E</h3><dl> -<dt id="ientry-idp140592098541336">emacs</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> -</dt></dl></dd><dt id="ientry-idp140592101941752">emphasis</dt><dd><dl><dt>bold, italics, <a class="indexterm" href="docbook-primer">Emphasis</a> +<dt id="ientry-idp140623091358664">emacs</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> +</dt></dl></dd><dt id="ientry-idp140623175386280">emphasis</dt><dd><dl><dt>bold, italics, <a class="indexterm" href="docbook-primer">Emphasis</a> </dt></dl></dd> </dl> </div><div class="indexdiv"> <h3>F</h3><dl> -<dt id="ientry-idp140592107348664">full text search</dt><dd><dl><dt>installation, <a class="indexterm" href="install-full-text-search-tsearch2">Install -Tsearch2 module</a>, <a class="indexterm" href="install-full-text-search-openfts">Install -OpenFTS module</a>, <a class="indexterm" href="install-full-text-search-openfts">Install -OpenFTS prerequisites in PostgreSQL instance</a> +<dt id="ientry-idp140623176482456">full text search</dt><dd><dl><dt>installation, <a class="indexterm" href="install-full-text-search-tsearch2">Install +Tsearch2 module</a> </dt></dl></dd> </dl> </div><div class="indexdiv"> <h3>G</h3><dl> -<dt id="ientry-idp140592102265016">Graphics</dt><dd><dl><dt>Images, <a class="indexterm" href="docbook-primer">Graphics</a> +<dt id="ientry-idp140623175419144">Graphics</dt><dd><dl><dt>Images, <a class="indexterm" href="docbook-primer">Graphics</a> </dt></dl></dd> </dl> </div><div class="indexdiv"> <h3>I</h3><dl> -<dt id="ientry-idp140592108147992">informaltable</dt><dd><dl><dt>table, <a class="indexterm" href="docbook-primer">Tables</a> +<dt id="ientry-idp140623175373160">informaltable</dt><dd><dl><dt>table, <a class="indexterm" href="docbook-primer">Tables</a> </dt></dl></dd> </dl> </div><div class="indexdiv"> <h3>L</h3><dl> -<dt id="ientry-idp140592098533608">language</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> -</dt></dl></dd><dt id="ientry-idp140592100322072">Linking, <a class="indexterm" href="docbook-primer">Links</a> -</dt><dt id="ientry-idp140592100631192">lists, <a class="indexterm" href="docbook-primer">Lists</a> +<dt id="ientry-idp140623091350264">language</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> +</dt></dl></dd><dt id="ientry-idp140623175460280">Linking, <a class="indexterm" href="docbook-primer">Links</a> +</dt><dt id="ientry-idp140623175427256">lists, <a class="indexterm" href="docbook-primer">Lists</a> </dt> </dl> </div><div class="indexdiv"> -<h3>O</h3><dl><dt id="ientry-idp140592107062392">OpenACS Package, <a class="indexterm" href="packages">What a Package +<h3>O</h3><dl><dt id="ientry-idp140623172251672">OpenACS Package, <a class="indexterm" href="packages">What a Package Looks Like</a> </dt></dl> </div><div class="indexdiv"> <h3>P</h3><dl> -<dt id="ientry-idp140592098566760">photo-album</dt><dd><dl><dt>installation (see ImageMagick)</dt></dl></dd><dt id="ientry-idp140592104083832">Postgres</dt><dd><dl><dt>Vacuuming, <a class="indexterm" href="openacs">Installation Option 2: Install +<dt id="ientry-idp140623091218680">photo-album</dt><dd><dl><dt>installation (see ImageMagick)</dt></dl></dd><dt id="ientry-idp140623178583368">Postgres</dt><dd><dl><dt>Vacuuming, <a class="indexterm" href="openacs">Installation Option 2: Install from tarball</a> </dt></dl></dd> </dl> </div><div class="indexdiv"> <h3>Q</h3><dl> -<dt id="ientry-idp140592107236824">qmail</dt><dd><dl> -<dt>installation, <a class="indexterm" href="install-qmail">Install qmail (OPTIONAL)</a> -</dt><dt>Maildir, <a class="indexterm" href="install-qmail">Install +<dt id="ientry-idp140623162685720">qmail</dt><dd><dl><dt>Maildir, <a class="indexterm" href="install-qmail">Install qmail (OPTIONAL)</a> -</dt><dt>rcpthosts error message, <a class="indexterm" href="install-qmail">Install qmail (OPTIONAL)</a> -</dt> -</dl></dd> +</dt></dl></dd> </dl> </div><div class="indexdiv"> <h3>S</h3><dl> -<dt id="ientry-idp140592107933944">sect1, <a class="indexterm" href="docbook-primer">Headlines, +<dt id="ientry-idp140623175464952">sect1, <a class="indexterm" href="docbook-primer">Headlines, Sections</a> -</dt><dt id="ientry-idp140592107956824">sect2, <a class="indexterm" href="docbook-primer">Headlines, +</dt><dt id="ientry-idp140623175474856">sect2, <a class="indexterm" href="docbook-primer">Headlines, Sections</a> -</dt><dt id="ientry-idp140592102754312">Sections</dt><dd><dl><dt>Headlines, <a class="indexterm" href="docbook-primer">Headlines, +</dt><dt id="ientry-idp140623175476952">Sections</dt><dd><dl><dt>Headlines, <a class="indexterm" href="docbook-primer">Headlines, Sections</a> -</dt></dl></dd><dt id="ientry-idp140592097869976">security</dt><dd><dl> +</dt></dl></dd><dt id="ientry-idp140623091303016">security</dt><dd><dl> <dt>definition, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> </dt><dt>firewall, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> </dt> -</dl></dd><dt id="ientry-idp140592107290328">sendmail</dt><dd><dl><dt>removing, <a class="indexterm" href="install-qmail">Install qmail (OPTIONAL)</a> -</dt></dl></dd><dt id="ientry-idp140592098603064">ssh, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> +</dl></dd><dt id="ientry-idp140623090549880">sendmail</dt><dd><dl><dt>removing, <a class="indexterm" href="install-qmail">Install qmail (OPTIONAL)</a> +</dt></dl></dd><dt id="ientry-idp140623091405192">ssh, <a class="indexterm" href="install-redhat">Install Red Hat 8/9</a> </dt> </dl> </div><div class="indexdiv"> -<h3>T</h3><dl><dt id="ientry-idp140592104250328">The publish point for new +<h3>T</h3><dl><dt id="ientry-idp140623164525208">The publish point for new packages should be fixed., <a class="indexterm" href="tutorial-distribute">Prepare the package for distribution.</a> </dt></dl> </div><div class="indexdiv"> <h3>U</h3><dl> -<dt id="ientry-idp140592102378600">ulink, <a class="indexterm" href="docbook-primer">Links</a> -</dt><dt id="ientry-idp140592104583224">upgrade</dt><dd><dl> +<dt id="ientry-idp140623175410504">ulink, <a class="indexterm" href="docbook-primer">Links</a> +</dt><dt id="ientry-idp140623160154424">upgrade</dt><dd><dl> <dt>OpenACS 4.5 to 4.6.x</dt><dd><dl><dt>Linux/Unix, <a class="indexterm" href="upgrade-4.5-to-4.6">Upgrading 4.5 or higher to 4.6.3</a> </dt></dl></dd> </dl></dd> </dl> </div><div class="indexdiv"> <h3>X</h3><dl> -<dt id="ientry-idp140592101961656">XML guidelines, <a class="indexterm" href="docbook-primer">OpenACS +<dt id="ientry-idp140623175588680">XML guidelines, <a class="indexterm" href="docbook-primer">OpenACS Documentation Strategy: Why DocBook?</a> -</dt><dt id="ientry-idp140592100325384">xref</dt><dd><dl><dt>linkend, <a class="indexterm" href="docbook-primer">Links</a> -</dt></dl></dd><dt id="ientry-idp140592102633688">xreflabel, <a class="indexterm" href="docbook-primer">Headlines, +</dt><dt id="ientry-idp140623175394568">xref</dt><dd><dl><dt>linkend, <a class="indexterm" href="docbook-primer">Links</a> +</dt></dl></dd><dt id="ientry-idp140623175469752">xreflabel, <a class="indexterm" href="docbook-primer">Headlines, Sections</a> </dt> </dl> Index: openacs-4/packages/acs-core-docs/www/ix01.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/ix01.html,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/ix01.html 7 Aug 2017 23:47:51 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/ix01.html 8 Nov 2017 09:42:11 -0000 1.31 @@ -1,3 +1,3 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Index</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="update-translations.html" title="How to Update the translations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="update-translations.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> </td></tr></table><hr></div><div class="index"><div class="titlepage"><div><div><h1 class="title"><a name="idp140592097697704"></a>Index</h1></div></div></div><div xmlns:xlink="http://www.w3.org/1999/xlink" class="index"><div class="indexdiv"><h3>Symbols</h3><dl><dt id="ientry-idp140592102800488">$OPENACS_SERVICE_NAME, <a class="indexterm" href="install-steps.html#idp140592102795240">Paths and Users</a></dt></dl></div><div class="indexdiv"><h3>A</h3><dl><dt id="ientry-idp140592101013272">AOLserver</dt><dd><dl><dt>configuration, <a class="indexterm" href="openacs.html#install-from-tarball">Installation Option 2: Install from tarball</a></dt></dl></dd><dt id="ientry-idp140592102521720">Automated tests, <a class="indexterm" href="tutorial-debug.html#idp140592102696792">Write automated tests</a></dt></dl></div><div class="indexdiv"><h3>C</h3><dl><dt id="ientry-idp140592102002600">computeroutput</dt><dd><dl><dt>code, <a class="indexterm" href="docbook-primer.html#dbprimer-code">Code</a></dt></dl></dd><dt id="ientry-idp140592107194328">cvs</dt><dd><dl><dt>initializing, <a class="indexterm" href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt>setup, <a class="indexterm" href="cvs-tips.html">Using CVS with an OpenACS Site</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>D</h3><dl><dt id="ientry-idp140592107210552">daemontools</dt><dd><dl><dt>installation, <a class="indexterm" href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt></dl></dd><dt id="ientry-idp140592098548152">docbook</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140592107200216">DocBook</dt><dd><dl><dt>DTD, <a class="indexterm" href="docbook-primer.html#dbprimer-why">OpenACS Documentation Strategy: Why DocBook?</a></dt><dt>emacs configuration for, <a class="indexterm" href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt></dl></dd><dt id="ientry-idp140592102567448">Document structure, <a class="indexterm" href="docbook-primer.html#dbprimer-structure">Document Structure</a></dt></dl></div><div class="indexdiv"><h3>E</h3><dl><dt id="ientry-idp140592098541336">emacs</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140592101941752">emphasis</dt><dd><dl><dt>bold, italics, <a class="indexterm" href="docbook-primer.html#dbprimer-emphasis">Emphasis</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>F</h3><dl><dt id="ientry-idp140592107348664">full text search</dt><dd><dl><dt>installation, <a class="indexterm" href="install-full-text-search-tsearch2.html#install-tsearch2">Install Tsearch2 module</a>, <a class="indexterm" href="install-full-text-search-openfts.html#install-openfts">Install OpenFTS module</a>, <a class="indexterm" href="install-full-text-search-openfts.html#install-openfts-postgres">Install OpenFTS prerequisites in PostgreSQL instance</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>G</h3><dl><dt id="ientry-idp140592102265016">Graphics</dt><dd><dl><dt>Images, <a class="indexterm" href="docbook-primer.html#dbprimer-graphics">Graphics</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>I</h3><dl><dt id="ientry-idp140592108147992">informaltable</dt><dd><dl><dt>table, <a class="indexterm" href="docbook-primer.html#dbprimer-tables">Tables</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>L</h3><dl><dt id="ientry-idp140592098533608">language</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140592100322072">Linking, <a class="indexterm" href="docbook-primer.html#dbprimer-links">Links</a></dt><dt id="ientry-idp140592100631192">lists, <a class="indexterm" href="docbook-primer.html#dbprimer-lists">Lists</a></dt></dl></div><div class="indexdiv"><h3>O</h3><dl><dt id="ientry-idp140592107062392">OpenACS Package, <a class="indexterm" href="packages.html#packages-looks">What a Package Looks Like</a></dt></dl></div><div class="indexdiv"><h3>P</h3><dl><dt id="ientry-idp140592098566760">photo-album</dt><dd><dl><dt>installation (see ImageMagick)</dt></dl></dd><dt id="ientry-idp140592104083832">Postgres</dt><dd><dl><dt>Vacuuming, <a class="indexterm" href="openacs.html#install-from-tarball">Installation Option 2: Install from tarball</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>Q</h3><dl><dt id="ientry-idp140592107236824">qmail</dt><dd><dl><dt>installation, <a class="indexterm" href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt>Maildir, <a class="indexterm" href="install-qmail.html">Install qmail (OPTIONAL)</a></dt><dt>rcpthosts error message, <a class="indexterm" href="install-qmail.html">Install qmail (OPTIONAL)</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>S</h3><dl><dt id="ientry-idp140592107933944">sect1, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt><dt id="ientry-idp140592107956824">sect2, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt><dt id="ientry-idp140592102754312">Sections</dt><dd><dl><dt>Headlines, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt></dl></dd><dt id="ientry-idp140592097869976">security</dt><dd><dl><dt>definition, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt><dt>firewall, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140592107290328">sendmail</dt><dd><dl><dt>removing, <a class="indexterm" href="install-qmail.html">Install qmail (OPTIONAL)</a></dt></dl></dd><dt id="ientry-idp140592098603064">ssh, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></div><div class="indexdiv"><h3>T</h3><dl><dt id="ientry-idp140592104250328">The publish point for new packages should be - fixed., <a class="indexterm" href="tutorial-distribute.html">Prepare the package for distribution.</a></dt></dl></div><div class="indexdiv"><h3>U</h3><dl><dt id="ientry-idp140592102378600">ulink, <a class="indexterm" href="docbook-primer.html#dbprimer-links">Links</a></dt><dt id="ientry-idp140592104583224">upgrade</dt><dd><dl><dt>OpenACS 4.5 to 4.6.x</dt><dd><dl><dt>Linux/Unix, <a class="indexterm" href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></dt></dl></dd></dl></dd></dl></div><div class="indexdiv"><h3>X</h3><dl><dt id="ientry-idp140592101961656">XML guidelines, <a class="indexterm" href="docbook-primer.html#dbprimer-why">OpenACS Documentation Strategy: Why DocBook?</a></dt><dt id="ientry-idp140592100325384">xref</dt><dd><dl><dt>linkend, <a class="indexterm" href="docbook-primer.html#dbprimer-links">Links</a></dt></dl></dd><dt id="ientry-idp140592102633688">xreflabel, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="update-translations.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left">How to Update the translations </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Index</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="index.html" title="OpenACS Core Documentation"><link rel="previous" href="update-translations.html" title="How to Update the translations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="update-translations.html">Prev</a> </td><th width="60%" align="center"></th><td width="20%" align="right"> </td></tr></table><hr></div><div class="index"><div class="titlepage"><div><div><h1 class="title"><a name="idp140623181428584"></a>Index</h1></div></div></div><div xmlns:xlink="http://www.w3.org/1999/xlink" class="index"><div class="indexdiv"><h3>Symbols</h3><dl><dt id="ientry-idp140623179128168">$OPENACS_SERVICE_NAME, <a class="indexterm" href="install-steps.html#idp140623179121976">Paths and Users</a></dt></dl></div><div class="indexdiv"><h3>A</h3><dl><dt id="ientry-idp140623178345544">AOLserver</dt><dd><dl><dt>configuration, <a class="indexterm" href="openacs.html#install-from-tarball">Installation Option 2: Install from tarball</a></dt></dl></dd><dt id="ientry-idp140623162159976">Automated tests, <a class="indexterm" href="tutorial-debug.html#idp140623164614664">Write automated tests</a></dt></dl></div><div class="indexdiv"><h3>C</h3><dl><dt id="ientry-idp140623175449672">computeroutput</dt><dd><dl><dt>code, <a class="indexterm" href="docbook-primer.html#dbprimer-code">Code</a></dt></dl></dd><dt id="ientry-idp140623161616552">cvs</dt><dd><dl><dt>initializing, <a class="indexterm" href="install-cvs.html">Initialize CVS (OPTIONAL)</a></dt><dt>setup, <a class="indexterm" href="cvs-tips.html">Using CVS with an OpenACS Site</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>D</h3><dl><dt id="ientry-idp140623170211560">daemontools</dt><dd><dl><dt>installation, <a class="indexterm" href="install-daemontools.html">Install Daemontools (OPTIONAL)</a></dt></dl></dd><dt id="ientry-idp140623091366120">docbook</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140623161896472">DocBook</dt><dd><dl><dt>DTD, <a class="indexterm" href="docbook-primer.html#dbprimer-why">OpenACS Documentation Strategy: Why DocBook?</a></dt><dt>emacs configuration for, <a class="indexterm" href="psgml-for-emacs.html">Add PSGML commands to emacs init file (OPTIONAL)</a></dt></dl></dd><dt id="ientry-idp140623175542264">Document structure, <a class="indexterm" href="docbook-primer.html#dbprimer-structure">Document Structure</a></dt></dl></div><div class="indexdiv"><h3>E</h3><dl><dt id="ientry-idp140623091358664">emacs</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140623175386280">emphasis</dt><dd><dl><dt>bold, italics, <a class="indexterm" href="docbook-primer.html#dbprimer-emphasis">Emphasis</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>F</h3><dl><dt id="ientry-idp140623176482456">full text search</dt><dd><dl><dt>installation, <a class="indexterm" href="install-full-text-search-tsearch2.html#install-tsearch2">Install Tsearch2 module</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>G</h3><dl><dt id="ientry-idp140623175419144">Graphics</dt><dd><dl><dt>Images, <a class="indexterm" href="docbook-primer.html#dbprimer-graphics">Graphics</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>I</h3><dl><dt id="ientry-idp140623175373160">informaltable</dt><dd><dl><dt>table, <a class="indexterm" href="docbook-primer.html#dbprimer-tables">Tables</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>L</h3><dl><dt id="ientry-idp140623091350264">language</dt><dd><dl><dt>installation, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140623175460280">Linking, <a class="indexterm" href="docbook-primer.html#dbprimer-links">Links</a></dt><dt id="ientry-idp140623175427256">lists, <a class="indexterm" href="docbook-primer.html#dbprimer-lists">Lists</a></dt></dl></div><div class="indexdiv"><h3>O</h3><dl><dt id="ientry-idp140623172251672">OpenACS Package, <a class="indexterm" href="packages.html#packages-looks">What a Package Looks Like</a></dt></dl></div><div class="indexdiv"><h3>P</h3><dl><dt id="ientry-idp140623091218680">photo-album</dt><dd><dl><dt>installation (see ImageMagick)</dt></dl></dd><dt id="ientry-idp140623178583368">Postgres</dt><dd><dl><dt>Vacuuming, <a class="indexterm" href="openacs.html#install-from-tarball">Installation Option 2: Install from tarball</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>Q</h3><dl><dt id="ientry-idp140623162685720">qmail</dt><dd><dl><dt>Maildir, <a class="indexterm" href="install-qmail.html">Install qmail (OPTIONAL)</a></dt></dl></dd></dl></div><div class="indexdiv"><h3>S</h3><dl><dt id="ientry-idp140623175464952">sect1, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt><dt id="ientry-idp140623175474856">sect2, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt><dt id="ientry-idp140623175476952">Sections</dt><dd><dl><dt>Headlines, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt></dl></dd><dt id="ientry-idp140623091303016">security</dt><dd><dl><dt>definition, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt><dt>firewall, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></dd><dt id="ientry-idp140623090549880">sendmail</dt><dd><dl><dt>removing, <a class="indexterm" href="install-qmail.html">Install qmail (OPTIONAL)</a></dt></dl></dd><dt id="ientry-idp140623091405192">ssh, <a class="indexterm" href="install-redhat.html">Install Red Hat 8/9</a></dt></dl></div><div class="indexdiv"><h3>T</h3><dl><dt id="ientry-idp140623164525208">The publish point for new packages should be + fixed., <a class="indexterm" href="tutorial-distribute.html">Prepare the package for distribution.</a></dt></dl></div><div class="indexdiv"><h3>U</h3><dl><dt id="ientry-idp140623175410504">ulink, <a class="indexterm" href="docbook-primer.html#dbprimer-links">Links</a></dt><dt id="ientry-idp140623160154424">upgrade</dt><dd><dl><dt>OpenACS 4.5 to 4.6.x</dt><dd><dl><dt>Linux/Unix, <a class="indexterm" href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></dt></dl></dd></dl></dd></dl></div><div class="indexdiv"><h3>X</h3><dl><dt id="ientry-idp140623175588680">XML guidelines, <a class="indexterm" href="docbook-primer.html#dbprimer-why">OpenACS Documentation Strategy: Why DocBook?</a></dt><dt id="ientry-idp140623175394568">xref</dt><dd><dl><dt>linkend, <a class="indexterm" href="docbook-primer.html#dbprimer-links">Links</a></dt></dl></dd><dt id="ientry-idp140623175469752">xreflabel, <a class="indexterm" href="docbook-primer.html#dbprimer-sections">Headlines, Sections</a></dt></dl></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="update-translations.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> </td></tr><tr><td width="40%" align="left">How to Update the translations </td><td width="20%" align="center"><a accesskey="u" href="index.html">Up</a></td><td width="40%" align="right"> </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/kernel-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-doc.html,v diff -u -r1.38 -r1.39 --- openacs-4/packages/acs-core-docs/www/kernel-doc.html 7 Aug 2017 23:47:51 -0000 1.38 +++ openacs-4/packages/acs-core-docs/www/kernel-doc.html 8 Nov 2017 09:42:11 -0000 1.39 @@ -1,2 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 15. Kernel Documentation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"><link rel="previous" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"><link rel="next" href="kernel-overview.html" title="Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><th width="60%" align="center">Part IV. For OpenACS Platform Developers</th><td width="20%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="kernel-doc"></a>Chapter 15. Kernel Documentation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="kernel-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="object-system-requirements.html">Object Model Requirements</a></span></dt><dt><span class="sect1"><a href="object-system-design.html">Object Model Design</a></span></dt><dt><span class="sect1"><a href="permissions-requirements.html">Permissions Requirements</a></span></dt><dt><span class="sect1"><a href="permissions-design.html">Permissions Design</a></span></dt><dt><span class="sect1"><a href="groups-requirements.html">Groups Requirements</a></span></dt><dt><span class="sect1"><a href="groups-design.html">Groups Design</a></span></dt><dt><span class="sect1"><a href="subsites-requirements.html">Subsites Requirements</a></span></dt><dt><span class="sect1"><a href="subsites-design.html">Subsites Design Document</a></span></dt><dt><span class="sect1"><a href="apm-requirements.html">Package Manager Requirements</a></span></dt><dt><span class="sect1"><a href="apm-design.html">Package Manager Design</a></span></dt><dt><span class="sect1"><a href="db-api-detailed.html">Database Access API</a></span></dt><dt><span class="sect1"><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></span></dt><dt><span class="sect1"><a href="security-requirements.html">Security Requirements</a></span></dt><dt><span class="sect1"><a href="security-design.html">Security Design</a></span></dt><dt><span class="sect1"><a href="security-notes.html">Security Notes</a></span></dt><dt><span class="sect1"><a href="rp-requirements.html">Request Processor Requirements</a></span></dt><dt><span class="sect1"><a href="rp-design.html">Request Processor Design</a></span></dt><dt><span class="sect1"><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></span></dt><dt><span class="sect1"><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></span></dt><dt><span class="sect1"><a href="ext-auth-requirements.html">External Authentication Requirements</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part IV. For OpenACS Platform Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-plat-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 15. Kernel Documentation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"><link rel="previous" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"><link rel="next" href="kernel-overview.html" title="Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><th width="60%" align="center">Part IV. For OpenACS Platform Developers</th><td width="20%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="kernel-doc"></a>Chapter 15. Kernel Documentation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="kernel-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="object-system-requirements.html">Object Model Requirements</a></span></dt><dt><span class="sect1"><a href="object-system-design.html">Object Model Design</a></span></dt><dt><span class="sect1"><a href="permissions-requirements.html">Permissions Requirements</a></span></dt><dt><span class="sect1"><a href="permissions-design.html">Permissions Design</a></span></dt><dt><span class="sect1"><a href="groups-requirements.html">Groups Requirements</a></span></dt><dt><span class="sect1"><a href="groups-design.html">Groups Design</a></span></dt><dt><span class="sect1"><a href="subsites-requirements.html">Subsites Requirements</a></span></dt><dt><span class="sect1"><a href="subsites-design.html">Subsites Design Document</a></span></dt><dt><span class="sect1"><a href="apm-requirements.html">Package Manager Requirements</a></span></dt><dt><span class="sect1"><a href="apm-design.html">Package Manager Design</a></span></dt><dt><span class="sect1"><a href="db-api-detailed.html">Database Access API</a></span></dt><dt><span class="sect1"><a href="i18n-requirements.html">OpenACS Internationalization Requirements</a></span></dt><dt><span class="sect1"><a href="security-requirements.html">Security Requirements</a></span></dt><dt><span class="sect1"><a href="security-design.html">Security Design</a></span></dt><dt><span class="sect1"><a href="security-notes.html">Security Notes</a></span></dt><dt><span class="sect1"><a href="rp-requirements.html">Request Processor Requirements</a></span></dt><dt><span class="sect1"><a href="rp-design.html">Request Processor Design</a></span></dt><dt><span class="sect1"><a href="tcl-doc.html">Documenting Tcl Files: Page Contracts and Libraries</a></span></dt><dt><span class="sect1"><a href="bootstrap-acs.html">Bootstrapping OpenACS</a></span></dt><dt><span class="sect1"><a href="ext-auth-requirements.html">External Authentication Requirements</a></span></dt></dl></div> + + + + + + + + + + + + + + + + + + + + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-plat-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="kernel-overview.html">Next</a></td></tr><tr><td width="40%" align="left">Part IV. For OpenACS Platform Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-plat-dev.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/kernel-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/kernel-overview.html,v diff -u -r1.32 -r1.33 --- openacs-4/packages/acs-core-docs/www/kernel-overview.html 7 Aug 2017 23:47:51 -0000 1.32 +++ openacs-4/packages/acs-core-docs/www/kernel-overview.html 8 Nov 2017 09:42:11 -0000 1.33 @@ -1,17 +1,25 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="next" href="object-system-requirements.html" title="Object Model Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-overview"></a>Overview</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="next" href="object-system-requirements.html" title="Object Model Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="kernel-overview"></a>Overview</h2></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> The <span class="emphasis"><em>OpenACS Kernel</em></span>, which handles system-wide necessities such as metadata, security, users and groups, subsites, and package management and deployment. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The <span class="emphasis"><em>OpenACS Core</em></span>, which comprises all the other packages that ship with the kernel and are most frequently needed by users, such as templating, forums, and user registration/management. The packages tend to be developed and distributed with the kernel. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <span class="emphasis"><em>OpenACS Application packages</em></span>, which typically provide user-level @@ -20,7 +28,10 @@ developed separately from the Kernel, and are typically released independently of it. - </p></li></ul></div><p> + </p> + </li></ul></div> + <p> This document provides a high level overview of the kernel package. <a class="ulink" href="index.html" target="_top">Documentation for other packages on this server</a> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 15. Kernel Documentation </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Object Model Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-doc.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 15. Kernel Documentation </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Object Model Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/mac-installation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/mac-installation.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/mac-installation.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/mac-installation.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -11,8 +11,8 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="mac-installation" id="mac-installation"></a>OpenACS Installation Guide for Mac OS X</h2></div></div></div><p>See the wiki for an actual guideline: <a class="ulink" href="http://openacs.org/xowiki/openacs-system-install-osx/" target="_top">Installing OpenACS on Mac OS X</a> -</p><div class="cvstag">($‌Id: macinstall.xml,v 1.7 2014/10/27 16:39:31 -victorg Exp $)</div> +</p><p><span class="cvstag">($‌Id: macinstall.xml,v 1.7 2014/10/27 +16:39:31 victorg Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="win2k-installation" leftLabel="Prev" leftTitle="OpenACS Installation Guide for Index: openacs-4/packages/acs-core-docs/www/mac-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/mac-installation.html,v diff -u -r1.43 -r1.44 --- openacs-4/packages/acs-core-docs/www/mac-installation.html 7 Aug 2017 23:47:51 -0000 1.43 +++ openacs-4/packages/acs-core-docs/www/mac-installation.html 8 Nov 2017 09:42:11 -0000 1.44 @@ -1,3 +1,10 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Installation Guide for Mac OS X</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="win2k-installation.html" title="OpenACS Installation Guide for Windows"><link rel="next" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="configuring-new-site.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mac-installation"></a>OpenACS Installation Guide for Mac OS X</h2></div></div></div><p> - See the wiki for an actual guideline: <a class="ulink" href="http://openacs.org/xowiki/openacs-system-install-osx/" target="_top">Installing OpenACS on Mac OS X</a></p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-new-site.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Windows </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Chapter 4. Configuring a new OpenACS Site</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Installation Guide for Mac OS X</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="win2k-installation.html" title="OpenACS Installation Guide for Windows"><link rel="next" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="configuring-new-site.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="mac-installation"></a>OpenACS Installation Guide for Mac OS X</h2></div></div></div> + + <p> + See the wiki for an actual guideline: <a class="ulink" href="http://openacs.org/xowiki/openacs-system-install-osx/" target="_top">Installing OpenACS on Mac OS X</a> + </p> + + <p><span class="cvstag">($Id$)</span></p> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win2k-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="configuring-new-site.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Installation Guide for Windows </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Chapter 4. Configuring a new OpenACS Site</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/maint-performance.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/maint-performance.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/maint-performance.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -32,15 +32,15 @@ <p>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.</p><div class="figure"> -<a name="idp140592101531128" id="idp140592101531128"></a><p class="title"><strong>Figure 6.8. Query +<a name="idp140623175898008" id="idp140623175898008"></a><p class="title"><strong>Figure 6.8. Query Analysis example</strong></p><div class="figure-contents"><div class="mediaobject"><img src="images/query-duration.png" alt="Query Analysis example"></div></div> </div><br class="figure-break"> </li> </ol></div> </li><li class="listitem"> <p>Identify a runaway Oracle query: first, use <strong class="userinput"><code>ps aux</code></strong> or <strong class="userinput"><code>top</code></strong> to get the UNIX process ID of a runaway Oracle process.</p><p>Log in to SQL*Plus as the admin:</p><pre class="screen"> -[<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> ~]$ svrmgrl +[<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production @@ -83,9 +83,10 @@ </pre><p>to</p><pre class="programlisting"> stats_command_string = true </pre><p>Next, connect to postgres (<code class="computeroutput">psql -<span class="replaceable"><span class="replaceable">service0</span></span> -</code>) and <code class="computeroutput">select * from pg_stat_activity;</code>. Typical -output should look like:</p><pre class="programlisting"> +<em class="replaceable"><code>service0</code></em> +</code>) and +<code class="computeroutput">select * from +pg_stat_activity;</code>. Typical output should look like:</p><pre class="programlisting"> datid | datname | procpid | usesysid | usename | current_query ----------+-------------+---------+----------+---------+----------------- 64344418 | openacs.org | 14122 | 101 | nsadmin | <IDLE> @@ -123,7 +124,7 @@ query, install "autotrace". I usually follow the instructions here <a class="ulink" href="http://asktom.oracle.com/~tkyte/article1/autotrace.html" target="_top">http://asktom.oracle.com/~tkyte/article1/autotrace.html</a>.</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592104105016" id="idp140592104105016"></a>Make sure, that the Oracle CBO works with +<a name="idp140623175869304" id="idp140623175869304"></a>Make sure, that the Oracle CBO works with adequate statistics</h4></div></div></div><p>The Oracle Cost Based optimizer is a piece of software that tries to find the "optimal" execution plan for a given SQL statement. For that it estimates the costs of running a SQL Index: openacs-4/packages/acs-core-docs/www/maint-performance.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maint-performance.html,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/maint-performance.html 7 Aug 2017 23:47:51 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/maint-performance.html 8 Nov 2017 09:42:11 -0000 1.31 @@ -1,8 +1,44 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Diagnosing Performance Problems</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="uptime.html" title="External uptime validation"><link rel="next" href="database-management.html" title="Chapter 7. Database Management"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="uptime.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="maint-performance"></a>Diagnosing Performance Problems</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Did performance problems happen overnight, or did they sneak up on +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Diagnosing Performance Problems</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="uptime.html" title="External uptime validation"><link rel="next" href="database-management.html" title="Chapter 7. Database Management"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="uptime.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="maint-performance"></a>Diagnosing Performance Problems</h2></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>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)</p></li><li class="listitem"><p>Is the file system out of space? Is the machine swapping to disk constantly?</p></li><li class="listitem"><p>Isolating and solving database problems.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see <a class="xref" href="install-next-nightly-vacuum.html" title="Vacuum Postgres nightly">the section called “Vacuum Postgres nightly”</a>. For Oracle, use <code class="computeroutput">exec dbms_stats.gather_schema_stats('SCHEMA_NAME')</code> (<a class="ulink" href="http://www.piskorski.com/docs/oracle.html" target="_top">Andrew Piskorski's Oracle notes</a>).</p></li><li class="listitem"><p>You can track the exact amount of time each database query on a page takes:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Go to <a class="ulink" href="/acs-admin/install" target="_top">Main Site : Site-Wide Administration : Install Software</a></p></li><li class="listitem"><p>Click on "Install New Application" in "Install from OpenACS Repository"</p></li><li class="listitem"><p>Choose "ACS Developer Support"></p></li><li class="listitem"><p>After install is complete, restart the server.</p></li><li class="listitem"><p>Browse to Developer Support, which is automatically mounted at <code class="computeroutput"><a class="ulink" href="/ds" target="_top">/ds</a></code>. - </p></li><li class="listitem"><p>Turn on Database statistics</p></li><li class="listitem"><p>Browse directly to a slow page and click "Request Information" at the bottom of the page.</p></li><li class="listitem"><p>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.</p><div class="figure"><a name="idp140592101531128"></a><p class="title"><b>Figure 6.8. Query Analysis example</b></p><div class="figure-contents"><div class="mediaobject"><img src="images/query-duration.png" alt="Query Analysis example"></div></div></div><br class="figure-break"></li></ol></div></li><li class="listitem"><p>Identify a runaway Oracle query: first, use <strong class="userinput"><code>ps aux</code></strong> or <strong class="userinput"><code>top</code></strong> to get the UNIX process ID of a runaway Oracle process.</p><p>Log in to SQL*Plus as the admin:</p><pre class="screen">[<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> ~]$ svrmgrl + users into .LRN)</p> + </li><li class="listitem"> + <p>Is the file system out of space? Is the machine swapping to disk constantly?</p> + </li><li class="listitem"> + <p>Isolating and solving database problems.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p>Without daily internal maintenance, most databases slowly degrade in performance. For PostGreSQL, see <a class="xref" href="install-next-nightly-vacuum.html" title="Vacuum Postgres nightly">the section called “Vacuum Postgres nightly”</a>. For Oracle, use <code class="computeroutput">exec dbms_stats.gather_schema_stats('SCHEMA_NAME')</code> (<a class="ulink" href="http://www.piskorski.com/docs/oracle.html" target="_top">Andrew Piskorski's Oracle notes</a>).</p> + </li><li class="listitem"> + <p>You can track the exact amount of time each database query on a page takes:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Go to <a class="ulink" href="/acs-admin/install" target="_top">Main Site : Site-Wide Administration : Install Software</a></p> + </li><li class="listitem"> + <p>Click on "Install New Application" in "Install from OpenACS Repository"</p> + </li><li class="listitem"> + <p>Choose "ACS Developer Support"></p> + </li><li class="listitem"> + <p>After install is complete, restart the server.</p> + </li><li class="listitem"> + <p>Browse to Developer Support, which is automatically mounted at <code class="computeroutput"><a class="ulink" href="/ds" target="_top">/ds</a></code>. + </p> + </li><li class="listitem"> + <p>Turn on Database statistics</p> + </li><li class="listitem"> + <p>Browse directly to a slow page and click "Request Information" at the bottom of the page.</p> + </li><li class="listitem"> + <p>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.</p> + <div class="figure"><a name="idp140623175898008"></a><p class="title"><b>Figure 6.8. Query Analysis example</b></p><div class="figure-contents"> + + <div class="mediaobject"><img src="images/query-duration.png" alt="Query Analysis example"></div> + </div></div><br class="figure-break"> + </li></ol></div> + </li><li class="listitem"> + <p>Identify a runaway Oracle query: first, use <strong class="userinput"><code>ps aux</code></strong> or <strong class="userinput"><code>top</code></strong> to get the UNIX process ID of a runaway Oracle process.</p> + <p>Log in to SQL*Plus as the admin:</p> + <pre class="screen">[<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production @@ -13,21 +49,36 @@ JServer Release 8.1.7.3.0 - Production SVRMGR> <strong class="userinput"><code>connect internal</code></strong> -Password:</pre><p>See all of the running queries, and match the UNIX PID:</p><pre class="programlisting">select p.spid -- The UNIX PID +Password:</pre> + <p>See all of the running queries, and match the UNIX PID:</p> + <pre class="programlisting">select p.spid -- The UNIX PID ,s.sid ,s.serial# ,p.username as os_user ,s.username ,s.status ,p.terminal ,p.program from v$session s ,v$process p where p.addr = s.paddr - order by s.username ,p.spid ,s.sid ,s.serial# ;</pre><p>See the SQL behind the oracle processes:</p><pre class="programlisting">select s.username + order by s.username ,p.spid ,s.sid ,s.serial# ;</pre> + <p>See the SQL behind the oracle processes:</p> + <pre class="programlisting">select s.username ,s.sid ,s.serial# ,sql.sql_text from v$session s, v$sqltext sql where sql.address = s.sql_address and sql.hash_value = s.sql_hash_value --and upper(s.username) like 'USERNAME%' - order by s.username ,s.sid ,s.serial# ,sql.piece ;</pre><p>To kill a troubled process:</p><pre class="programlisting">alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL#</pre><p>(See <a class="ulink" href="http://www.piskorski.com/docs/oracle.html" target="_top">Andrew Piskorski's Oracle notes</a>)</p></li><li class="listitem"><p>Identify a runaway Postgres query. First, logging must be enabled in the database. This imposes a performance penalty and should not be done in normal operation.</p><p>Edit the file <code class="computeroutput">postgresql.conf</code> - its location depends on the PostGreSQL installation - and change</p><pre class="programlisting">#stats_command_string = false</pre><p>to</p><pre class="programlisting">stats_command_string = true</pre><p>Next, connect to postgres (<code class="computeroutput">psql <span class="replaceable"><span class="replaceable">service0</span></span></code>) and <code class="computeroutput">select * from pg_stat_activity;</code>. Typical output should look like:</p><pre class="programlisting"> + order by s.username ,s.sid ,s.serial# ,sql.piece ;</pre> + <p>To kill a troubled process:</p> + <pre class="programlisting">alter system kill session 'SID,SERIAL#'; --substitute values for SID and SERIAL#</pre> + <p>(See <a class="ulink" href="http://www.piskorski.com/docs/oracle.html" target="_top">Andrew Piskorski's Oracle notes</a>)</p> + </li><li class="listitem"> + <p>Identify a runaway Postgres query. First, logging must be enabled in the database. This imposes a performance penalty and should not be done in normal operation.</p> + <p>Edit the file <code class="computeroutput">postgresql.conf</code> - its location depends on the PostGreSQL installation - and change</p> + <pre class="programlisting">#stats_command_string = false</pre> + <p>to</p> + <pre class="programlisting">stats_command_string = true</pre> + <p>Next, connect to postgres (<code class="computeroutput">psql <em class="replaceable"><code>service0</code></em></code>) and <code class="computeroutput">select * from pg_stat_activity;</code>. Typical output should look like:</p> + <pre class="programlisting"> datid | datname | procpid | usesysid | usename | current_query ----------+-------------+---------+----------+---------+----------------- 64344418 | openacs.org | 14122 | 101 | nsadmin | <IDLE> @@ -42,7 +93,13 @@ 64344418 | openacs.org | 14311 | 101 | nsadmin | <IDLE> 64344418 | openacs.org | 14549 | 101 | nsadmin | <IDLE> (8 rows) -openacs.org=></pre></li></ul></div></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-monitoring"></a>Creating an appropriate tuning and monitoring environment</h3></div></div></div><p> +openacs.org=></pre> + </li></ul></div> + </li></ul></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-monitoring"></a>Creating an appropriate tuning and monitoring environment</h3></div></div></div> + + <p> The first task is to create an appropriate environment for finding out what is going on inside Oracle. Oracle provides Statspack, a package to monitor and save the state of the v$ performance views. These reports @@ -51,20 +108,35 @@ instructions in $ORACLE_HOME/rdbms/admin/spdoc.txt. Follow the instructions carefully and take periodic snapshots, this way you'll be able to look at historical performance data. - </p><p> + </p> + + <p> Also turn on the timed_statistics in your init.ora file, so that Statspack reports (and all other Oracle reports) are timed, which makes them a lot more meaningful. The overhead of timing data is about 1% per Oracle Support information. - </p><p> + </p> + + + <p> To be able to get a overview of how Oracle executes a particular query, install "autotrace". I usually follow the instructions here <a class="ulink" href="http://asktom.oracle.com/~tkyte/article1/autotrace.html" target="_top">http://asktom.oracle.com/~tkyte/article1/autotrace.html</a>. - </p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592104105016"></a>Make sure, that the Oracle CBO works with adequate statistics</h4></div></div></div><p> + </p> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623175869304"></a>Make sure, that the Oracle CBO works with adequate statistics</h4></div></div></div> + + + <p> The Oracle Cost Based optimizer is a piece of software that tries to find the "optimal" execution plan for a given SQL statement. For that it estimates the costs of running a SQL query in a particular way (by default up to 80.000 permutations are being tested in a Oracle 8i). To get an adequate cost estimate, the CBO needs to have adequate statistics. For that Oracle supplies the <a class="ulink" href="http://docs.oracle.com/cd/B19306_01/appdev.102/b14258/d_stats.htm#CIHBIEII" target="_top">dbms_stats package</a>. - </p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="uptime.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr><tr><td width="40%" align="left">External uptime validation </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Chapter 7. Database Management</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </div> + + </div> + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="uptime.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="database-management.html">Next</a></td></tr><tr><td width="40%" align="left">External uptime validation </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Chapter 7. Database Management</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -10,12 +10,12 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="maintenance-deploy" id="maintenance-deploy"></a>Staged Deployment for Production -Networks</h2></div></div></div><div class="authorblurb"> -<div class="cvstag">($‌Id: maintenance.xml,v 1.30.6.3 2017/06/17 -08:29:28 gustafn Exp $)</div><p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> +Networks</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red"><span class="cvstag">($‌Id: +maintenance.xml,v 1.31 2017/08/07 23:47:55 gustafn Exp +$)</span></span></p><p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> </p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This section describes two minimal-risk methods for deploying +</authorblurb> +<p>This section describes two minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT)</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Control: You know for sure that the change you are making is the @@ -24,7 +24,7 @@ working configuration safely and quickly.</p></li> </ul></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592101338280" id="idp140592101338280"></a>Method 1: Deployment with CVS</h3></div></div></div><p>With this method, we control the files on a site via CVS. This +<a name="idp140623174990600" id="idp140623174990600"></a>Method 1: Deployment with CVS</h3></div></div></div><p>With this method, we control the files on a site via CVS. This example uses one developmental server (service0-dev) and one production server (service0). Depending on your needs, you can also have a staging server for extensive testing before you go live. The @@ -103,7 +103,7 @@ tags to follow ...</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592101350328" id="idp140592101350328"></a>Method 2: A/B Deployment</h3></div></div></div><p>The approach taken in this section is to always create a new +<a name="idp140623175758344" id="idp140623175758344"></a>Method 2: A/B Deployment</h3></div></div></div><p>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 @@ -119,28 +119,28 @@ function or risk losing data in the shuffle. It also requires extra steps if the database will be affected.</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592101352744" id="idp140592101352744"></a>Simple A/B Deployment: Database is not +<a name="idp140623174971944" id="idp140623174971944"></a>Simple A/B Deployment: Database is not changed</h4></div></div></div><div class="figure"> -<a name="idp140592101353384" id="idp140592101353384"></a><p class="title"><strong>Figure 6.2. Simple +<a name="idp140623175654760" id="idp140623175654760"></a><p class="title"><strong>Figure 6.2. Simple A/B Deployment - Step 1</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/simple-deploy-1.png" align="middle" alt="Simple A/B Deployment - Step 1"></div></div> </div><br class="figure-break"><div class="figure"> -<a name="idp140592101356072" id="idp140592101356072"></a><p class="title"><strong>Figure 6.3. Simple +<a name="idp140623175792120" id="idp140623175792120"></a><p class="title"><strong>Figure 6.3. Simple A/B Deployment - Step 2</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/simple-deploy-2.png" align="middle" alt="Simple A/B Deployment - Step 2"></div></div> </div><br class="figure-break"><div class="figure"> -<a name="idp140592101358760" id="idp140592101358760"></a><p class="title"><strong>Figure 6.4. Simple +<a name="idp140623175788536" id="idp140623175788536"></a><p class="title"><strong>Figure 6.4. Simple A/B Deployment - Step 3</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/simple-deploy-3.png" align="middle" alt="Simple A/B Deployment - Step 3"></div></div> </div><br class="figure-break"> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592101361576" id="idp140592101361576"></a>Complex A/B Deployment: Database is +<a name="idp140623175018872" id="idp140623175018872"></a>Complex A/B Deployment: Database is changed</h4></div></div></div><div class="figure"> -<a name="idp140592101362216" id="idp140592101362216"></a><p class="title"><strong>Figure 6.5. Complex A/B Deployment +<a name="idp140623175695688" id="idp140623175695688"></a><p class="title"><strong>Figure 6.5. Complex A/B Deployment - Step 1</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/complex-deploy-1.png" align="middle" alt="Complex A/B Deployment - Step 1"></div></div> </div><br class="figure-break"><div class="figure"> -<a name="idp140592101364904" id="idp140592101364904"></a><p class="title"><strong>Figure 6.6. Complex A/B Deployment +<a name="idp140623174978168" id="idp140623174978168"></a><p class="title"><strong>Figure 6.6. Complex A/B Deployment - Step 2</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/complex-deploy-2.png" align="middle" alt="Complex A/B Deployment - Step 2"></div></div> </div><br class="figure-break"><div class="figure"> -<a name="idp140592101367592" id="idp140592101367592"></a><p class="title"><strong>Figure 6.7. Complex A/B Deployment +<a name="idp140623174977320" id="idp140623174977320"></a><p class="title"><strong>Figure 6.7. Complex A/B Deployment - Step 3</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/complex-deploy-3.png" align="middle" alt="Complex A/B Deployment - Step 3"></div></div> </div><br class="figure-break"> </div> 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 -r1.25 -r1.26 --- openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 7 Aug 2017 23:47:51 -0000 1.25 +++ openacs-4/packages/acs-core-docs/www/maintenance-deploy.html 8 Nov 2017 09:42:11 -0000 1.26 @@ -1,38 +1,62 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Staged Deployment for Production Networks</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="high-avail.html" title="High Availability/High Performance Configurations"><link rel="next" href="install-ssl.html" title="Installing SSL Support for an OpenACS service"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="high-avail.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="install-ssl.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="maintenance-deploy"></a>Staged Deployment for Production Networks</h2></div></div></div><div class="authorblurb"><div class="cvstag">($Id$)</div><p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This section describes two minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT)</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>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.</p></li><li class="listitem"><p>Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.</p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592101338280"></a>Method 1: Deployment with CVS</h3></div></div></div><p>With this method, we control the files on a site via +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Staged Deployment for Production Networks</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="high-avail.html" title="High Availability/High Performance Configurations"><link rel="next" href="install-ssl.html" title="Installing SSL Support for an OpenACS service"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="high-avail.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="install-ssl.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="maintenance-deploy"></a>Staged Deployment for Production Networks</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p><span class="cvstag">($Id$)</span></p> +<p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + <p>This section describes two minimal-risk methods for deploying changes on a production network. The important characteristics of a safe change deployment include: (THIS SECTION IN DEVELOPMENT)</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>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.</p> + </li><li class="listitem"> + <p>Rollback: If anything goes wrong, you can return to the previous working configuration safely and quickly.</p> + </li></ul></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623174990600"></a>Method 1: Deployment with CVS</h3></div></div></div> + + <p>With this method, we control the files on a site via CVS. This example uses one developmental server (service0-dev) and one production server (service0). Depending on your needs, you can also have a staging server for extensive testing before you go live. The only way files should move between the server - instances is via cvs.</p><p>To set up a developmental installation, first set up + instances is via cvs.</p> + + <p>To set up a developmental installation, first set up either your developmental installation or your production installation, and follow the instructions for committing your files to CVS. We'll assume in this example that you set up the production server (service0). To set up the developmental instance, you then follow the intall guide again, this time creating a new user (service0-dev) that you'll use for the new installation. To get the files for service0-dev, you check them out from cvs (check out - service0). </p><pre class="programlisting"> + service0). </p> + +<pre class="programlisting"> su - service0-dev co -d /cvsroot service0 mv service0 /var/lib/aolserver/service0-dev ln -s /home/service0-dev/web /var/lib/aolserver/service0-dev emacs web/etc/config.tcl emacs web/etc/daemontools/run -</pre><p>In the config.tcl file, you'll probably want to pay attention +</pre> + + <p>In the config.tcl file, you'll probably want to pay attention the rollout support section. That will ensure that email on your - developmental server will not be sent out to the general world.</p><p>Also, instead of going through the OpenACS online + developmental server will not be sent out to the general world.</p> + + <p>Also, instead of going through the OpenACS online installer, you'll actually load live data into your production - server. </p><p>You can even automate the process of getting live data + server. </p> + + <p>You can even automate the process of getting live data from your production server. Copy something like this to /home/service0-dev/bin and put it in service0-dev's crontab to run once a night. You'll need to make sure the database backups are set up in service0's crontab, and that if the servers are on different physical machines, that the database backup is copied - to the developmental machine once per night.</p><pre class="programlisting"> + to the developmental machine once per night.</p> + +<pre class="programlisting"> /usr/local/bin/svc -d /service/service0-dev /bin/sleep 60 # this deletes the dev database! @@ -46,8 +70,14 @@ /usr/local/pgsql/bin/psql service0-dev < /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup.dmp /usr/local/bin/svc -u /service/service0-dev /bin/gzip /var/lib/aolserver/service0-dev/database-backup/service0-nightly-backup-old.dmp -</pre><p>Your developmental server will always have data about a day - old.</p><p>To make changes on service0-dev:</p><pre class="programlisting"> +</pre> + + <p>Your developmental server will always have data about a day + old.</p> + + <p>To make changes on service0-dev:</p> + +<pre class="programlisting"> 1) change the file on service0-dev as desired 2) test the new file 3) commit the file: @@ -61,10 +91,59 @@ if that looks okay, commit with: cvs -m "changing text on front page for February conference" index.adp the stuff in -m "service0" is a comment visible only from within cvs commands -</pre><p>To make these changes take place on service0:</p><pre class="programlisting"> +</pre> + + <p>To make these changes take place on service0:</p> + +<pre class="programlisting"> 4) update the file on production: cd /var/lib/aolserver/service0/www -cvs up -Pd index.adp</pre><p>If you make changes that require changes to the database, +cvs up -Pd index.adp</pre> + + <p>If you make changes that require changes to the database, test them out first on service0-dev, using either -create.sql or upgrade scripts. Once you've tested them, you then update and - run the upgrade scripts from the package manager. </p><p>The production site can run "HEAD" from cvs.</p><p>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 ...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592101350328"></a>Method 2: A/B Deployment</h3></div></div></div><p>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.</p><p>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.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592101352744"></a>Simple A/B Deployment: Database is not changed</h4></div></div></div><div class="figure"><a name="idp140592101353384"></a><p class="title"><b>Figure 6.2. Simple A/B Deployment - Step 1</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/simple-deploy-1.png" align="middle" alt="Simple A/B Deployment - Step 1"></div></div></div><br class="figure-break"><div class="figure"><a name="idp140592101356072"></a><p class="title"><b>Figure 6.3. Simple A/B Deployment - Step 2</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/simple-deploy-2.png" align="middle" alt="Simple A/B Deployment - Step 2"></div></div></div><br class="figure-break"><div class="figure"><a name="idp140592101358760"></a><p class="title"><b>Figure 6.4. Simple A/B Deployment - Step 3</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/simple-deploy-3.png" align="middle" alt="Simple A/B Deployment - Step 3"></div></div></div><br class="figure-break"></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592101361576"></a>Complex A/B Deployment: Database is changed</h4></div></div></div><div class="figure"><a name="idp140592101362216"></a><p class="title"><b>Figure 6.5. Complex A/B Deployment - Step 1</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/complex-deploy-1.png" align="middle" alt="Complex A/B Deployment - Step 1"></div></div></div><br class="figure-break"><div class="figure"><a name="idp140592101364904"></a><p class="title"><b>Figure 6.6. Complex A/B Deployment - Step 2</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/complex-deploy-2.png" align="middle" alt="Complex A/B Deployment - Step 2"></div></div></div><br class="figure-break"><div class="figure"><a name="idp140592101367592"></a><p class="title"><b>Figure 6.7. Complex A/B Deployment - Step 3</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/complex-deploy-3.png" align="middle" alt="Complex A/B Deployment - Step 3"></div></div></div><br class="figure-break"></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="high-avail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-ssl.html">Next</a></td></tr><tr><td width="40%" align="left">High Availability/High Performance Configurations </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Installing SSL Support for an OpenACS service</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + run the upgrade scripts from the package manager. </p> + +<p>The production site can run "HEAD" from cvs.</p> + +<p>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 ...</p> + + + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623175758344"></a>Method 2: A/B Deployment</h3></div></div></div> + + <p>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.</p> + <p>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.</p> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623174971944"></a>Simple A/B Deployment: Database is not changed</h4></div></div></div> + + <div class="figure"><a name="idp140623175654760"></a><p class="title"><b>Figure 6.2. Simple A/B Deployment - Step 1</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/simple-deploy-1.png" align="middle" alt="Simple A/B Deployment - Step 1"></div> + </div></div><br class="figure-break"> + <div class="figure"><a name="idp140623175792120"></a><p class="title"><b>Figure 6.3. Simple A/B Deployment - Step 2</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/simple-deploy-2.png" align="middle" alt="Simple A/B Deployment - Step 2"></div> + </div></div><br class="figure-break"> + <div class="figure"><a name="idp140623175788536"></a><p class="title"><b>Figure 6.4. Simple A/B Deployment - Step 3</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/simple-deploy-3.png" align="middle" alt="Simple A/B Deployment - Step 3"></div> + </div></div><br class="figure-break"> + </div> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623175018872"></a>Complex A/B Deployment: Database is changed</h4></div></div></div> + + <div class="figure"><a name="idp140623175695688"></a><p class="title"><b>Figure 6.5. Complex A/B Deployment - Step 1</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/complex-deploy-1.png" align="middle" alt="Complex A/B Deployment - Step 1"></div> + </div></div><br class="figure-break"> + <div class="figure"><a name="idp140623174978168"></a><p class="title"><b>Figure 6.6. Complex A/B Deployment - Step 2</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/complex-deploy-2.png" align="middle" alt="Complex A/B Deployment - Step 2"></div> + </div></div><br class="figure-break"> + <div class="figure"><a name="idp140623174977320"></a><p class="title"><b>Figure 6.7. Complex A/B Deployment - Step 3</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/complex-deploy-3.png" align="middle" alt="Complex A/B Deployment - Step 3"></div> + </div></div><br class="figure-break"> + </div> + </div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="high-avail.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-ssl.html">Next</a></td></tr><tr><td width="40%" align="left">High Availability/High Performance Configurations </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Installing SSL Support for an OpenACS service</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/maintenance-web.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/maintenance-web.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -25,11 +25,9 @@ validation</a></span></dt><dt><span class="sect1"><a href="maint-performance">Diagnosing Performance Problems</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div> +</div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="upgrade-supporting" leftLabel="Prev" leftTitle="Upgrading Platform components" Index: openacs-4/packages/acs-core-docs/www/maintenance-web.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/maintenance-web.html,v diff -u -r1.41 -r1.42 --- openacs-4/packages/acs-core-docs/www/maintenance-web.html 7 Aug 2017 23:47:51 -0000 1.41 +++ openacs-4/packages/acs-core-docs/www/maintenance-web.html 8 Nov 2017 09:42:11 -0000 1.42 @@ -1,5 +1,22 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 6. Production Environments</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="upgrade-supporting.html" title="Upgrading Platform components"><link rel="next" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-supporting.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-openacs-keepalive.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="maintenance-web"></a>Chapter 6. Production Environments</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="install-openacs-keepalive.html">Starting and Stopping an OpenACS instance.</a></span></dt><dt><span class="sect1"><a href="install-openacs-inittab.html">AOLserver keepalive with inittab</a></span></dt><dt><span class="sect1"><a href="install-next-add-server.html">Running multiple services on one machine</a></span></dt><dt><span class="sect1"><a href="high-avail.html">High Availability/High Performance Configurations</a></span></dt><dt><span class="sect1"><a href="maintenance-deploy.html">Staged Deployment for Production Networks</a></span></dt><dt><span class="sect1"><a href="install-ssl.html">Installing SSL Support for an OpenACS service</a></span></dt><dt><span class="sect1"><a href="analog-setup.html">Set up Log Analysis Reports</a></span></dt><dt><span class="sect1"><a href="uptime.html">External uptime validation</a></span></dt><dt><span class="sect1"><a href="maint-performance.html">Diagnosing Performance Problems</a></span></dt></dl></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-supporting.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-openacs-keepalive.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading Platform components </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Starting and Stopping an OpenACS instance.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 6. Production Environments</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="upgrade-supporting.html" title="Upgrading Platform components"><link rel="next" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-supporting.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="install-openacs-keepalive.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="maintenance-web"></a>Chapter 6. Production Environments</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="install-openacs-keepalive.html">Starting and Stopping an OpenACS instance.</a></span></dt><dt><span class="sect1"><a href="install-openacs-inittab.html">AOLserver keepalive with inittab</a></span></dt><dt><span class="sect1"><a href="install-next-add-server.html">Running multiple services on one machine</a></span></dt><dt><span class="sect1"><a href="high-avail.html">High Availability/High Performance Configurations</a></span></dt><dt><span class="sect1"><a href="maintenance-deploy.html">Staged Deployment for Production Networks</a></span></dt><dt><span class="sect1"><a href="install-ssl.html">Installing SSL Support for an OpenACS service</a></span></dt><dt><span class="sect1"><a href="analog-setup.html">Set up Log Analysis Reports</a></span></dt><dt><span class="sect1"><a href="uptime.html">External uptime validation</a></span></dt><dt><span class="sect1"><a href="maint-performance.html">Diagnosing Performance Problems</a></span></dt></dl></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + + </authorblurb></span> + + + + + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-supporting.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-openacs-keepalive.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading Platform components </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Starting and Stopping an OpenACS instance.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/nxml-mode.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/nxml-mode.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/nxml-mode.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/nxml-mode.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="filename" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="nxml-mode" id="nxml-mode"></a>Using nXML mode in Emacs</h2></div></div></div><div class="authorblurb"> -<p>By Jeff Davis</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>An alternative to psgml mode is nXML by James Clark, a new major +<a name="nxml-mode" id="nxml-mode"></a>Using nXML mode in Emacs</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Jeff Davis</span></p><span style="color: red"></authorblurb></span><p>An alternative to psgml mode is nXML by James Clark, a new major mode for GNU Emacs for editing XML, and which features highlighting, indentation, and on the fly validation versus a RelaxNG Schema.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> Index: openacs-4/packages/acs-core-docs/www/nxml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/nxml-mode.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/nxml-mode.html 7 Aug 2017 23:47:51 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/nxml-mode.html 8 Nov 2017 09:42:11 -0000 1.20 @@ -1,11 +1,19 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using nXML mode in Emacs</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="next" href="filename.html" title="Detailed Design Documentation Template"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nxml-mode"></a>Using nXML mode in Emacs</h2></div></div></div><div class="authorblurb"><p>By Jeff Davis</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using nXML mode in Emacs</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="psgml-mode.html" title="Using PSGML mode in Emacs"><link rel="next" href="filename.html" title="Detailed Design Documentation Template"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="nxml-mode"></a>Using nXML mode in Emacs</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>By Jeff Davis</p> + </authorblurb></span> + + <p> An alternative to psgml mode is nXML by James Clark, a new major mode for GNU Emacs for editing XML, and which features highlighting, indentation, and on the fly validation versus a RelaxNG Schema. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>An + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>An <a class="ulink" href="http://www.xmlhack.com/read.php?item=2061" target="_top">introduction to nXML mode</a> at xmlhack.com. - </p></li><li class="listitem"><p>The <a class="ulink" href="http://groups.yahoo.com/group/emacs-nxml-mode/" target="_top">nXML mode mail list</a> at groups.yahoo.com. - </p></li><li class="listitem"><p>The <a class="ulink" href="http://www.thaiopensource.com/download/" target="_top">nXML download page</a> at <a class="ulink" href="http://www.thaiopensource.com/" target="_top">thaiopensource.com</a>.</p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr><tr><td width="40%" align="left">Using PSGML mode in Emacs </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Detailed Design Documentation Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li><li class="listitem"><p>The <a class="ulink" href="http://groups.yahoo.com/group/emacs-nxml-mode/" target="_top">nXML mode mail list</a> at groups.yahoo.com. + </p></li><li class="listitem"><p>The <a class="ulink" href="http://www.thaiopensource.com/download/" target="_top">nXML download page</a> at <a class="ulink" href="http://www.thaiopensource.com/" target="_top">thaiopensource.com</a>.</p></li></ul></div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="psgml-mode.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="filename.html">Next</a></td></tr><tr><td width="40%" align="left">Using PSGML mode in Emacs </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Detailed Design Documentation Template</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/object-identity.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/object-identity.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/object-identity.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="programming-with-aolserver" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="object-identity" id="object-identity"></a>Object Identity</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>One of the major design features of OpenACS 5.9.0 is the +<a name="object-identity" id="object-identity"></a>Object Identity</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. +Schloming</a> +</span></p><span style="color: red"></authorblurb></span><p>One of the major design features of OpenACS 5.9.0 is the explicit representation of <span class="emphasis"><em>object identity</em></span>. The reason I say "explicit representation" is because the concept of object identity has @@ -50,8 +48,8 @@ with an integer primary key that is derived from a globally unique sequence is the key to eliminating redundant code and replacing it with generic <span class="emphasis"><em>object level -services</em></span>.</p><div class="cvstag">($‌Id: object-identity.xml,v 1.7 2006/07/17 -05:38:37 torbenb Exp $)</div> +services</em></span>.</p><p><span class="cvstag">($‌Id: object-identity.xml,v 1.7 2006/07/17 +05:38:37 torbenb Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="permissions-tediously-explained" leftLabel="Prev" leftTitle="OpenACS Permissions Tediously Index: openacs-4/packages/acs-core-docs/www/object-identity.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-identity.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/object-identity.html 7 Aug 2017 23:47:51 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/object-identity.html 8 Nov 2017 09:42:11 -0000 1.51 @@ -1,35 +1,53 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Object Identity</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="permissions-tediously-explained.html" title="OpenACS Permissions Tediously Explained"><link rel="next" href="programming-with-aolserver.html" title="Programming with AOLserver"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-tediously-explained.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-identity"></a>Object Identity</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>One of the major design features of OpenACS 5.9.0 is the explicit representation +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Object Identity</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="permissions-tediously-explained.html" title="OpenACS Permissions Tediously Explained"><link rel="next" href="programming-with-aolserver.html" title="Programming with AOLserver"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-tediously-explained.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-identity"></a>Object Identity</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a></p> +</authorblurb></span> + + +<p>One of the major design features of OpenACS 5.9.0 is the explicit representation of <span class="emphasis"><em>object identity</em></span>. The reason I say "explicit representation" is because the concept of object identity has been around forever. It is inherent to our problem domain. Consider the example of 3.x style scoping. The 3.x data models use the triple (user_id, group_id, scope) to <span class="emphasis"><em>identify</em></span> an <span class="emphasis"><em>object</em></span>. In the 5.9.0 data model this -object is <span class="emphasis"><em>explicitly represented</em></span> by a single party_id.</p><p>Another good example of this is can be found in the user groups data +object is <span class="emphasis"><em>explicitly represented</em></span> by a single party_id.</p> + +<p>Another good example of this is can be found in the user groups data model. The 3.x user groups data model contains another example of an <span class="emphasis"><em>implied identity</em></span>. Every mapping between a user and a group could have an arbitrary number of attached values (user_group_member_fields, etc.). In this case it is the pair (group_id, user_id) that implicitly refers to an object (the person's membership in a group). In the 5.9.0 data model this object identity is made explicit by adding an integer primary key to the -table that maps users to groups.</p><p>Coming from a purely relational world, this might seem slightly weird at +table that maps users to groups.</p> + +<p>Coming from a purely relational world, this might seem slightly weird at first. The pair (group_id, user_id) is sufficient to uniquely identify the object in question, so why have the redundant integer primary key? If you take a closer look, it actually isn't quite so redundant. If you want to be able to use the object model's permissioning features, and generic attribute features on a table, you need an integer primary key for that table. This is because you can't really write a data model in oracle that -uses more than one way to represent identity.</p><p>So, this apparently redundant primary key has saved us the trouble of +uses more than one way to represent identity.</p> + +<p>So, this apparently redundant primary key has saved us the trouble of duplicating the entire generic storage system for the special case of the user_group_map, and has saved us from implementing ad-hoc security instead of just using acs-permissions. This design choice is further validated by the fact that services like journals that weren't previously thought to be generic can in fact be generically applied to membership objects, thereby allowing us to eliminated membership state auditing columns that weren't -even capable of fully tracking the history of membership state.</p><p>The design choice of explicitly representing object identity with an +even capable of fully tracking the history of membership state.</p> + +<p>The design choice of explicitly representing object identity with an integer primary key that is derived from a globally unique sequence is the key to eliminating redundant code and replacing it with generic <span class="emphasis"><em>object -level services</em></span>.</p><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-tediously-explained.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Permissions Tediously Explained </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Programming with AOLserver</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +level services</em></span>.</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-tediously-explained.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="programming-with-aolserver.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Permissions Tediously Explained </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Programming with AOLserver</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/object-system-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/object-system-design.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/object-system-design.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -10,10 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="object-system-design" id="object-system-design"></a>Object Model -Design</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su, Michael Yoon, Richard Li, Rafael Schloming</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +Design</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su, Michael Yoon, Richard Li, +Rafael Schloming</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="object-system-design-essentials" id="object-system-design-essentials"></a>Essentials</h3></div></div></div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> Index: openacs-4/packages/acs-core-docs/www/object-system-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-design.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/object-system-design.html 7 Aug 2017 23:47:51 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/object-system-design.html 8 Nov 2017 09:42:11 -0000 1.36 @@ -1,54 +1,127 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Object Model Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="object-system-requirements.html" title="Object Model Requirements"><link rel="next" href="permissions-requirements.html" title="Permissions Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-system-design"></a>Object Model Design</h2></div></div></div><div class="authorblurb"><p>By Pete Su, Michael Yoon, Richard Li, Rafael Schloming</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-essentials"></a>Essentials</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-data-model"></a>Data Model</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Object Model Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="object-system-requirements.html" title="Object Model Requirements"><link rel="next" href="permissions-requirements.html" title="Permissions Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-system-design"></a>Object Model Design</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By Pete Su, Michael Yoon, Richard Li, Rafael Schloming</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-essentials"></a>Essentials</h3></div></div></div> + + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-data-model"></a>Data Model</h4></div></div></div> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top"> acs-metadata-create.sql</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-objects-create.sql&package_key=acs-kernel" target="_top"> acs-objects-create.sql</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-relationships-create.sql&package_key=acs-kernel" target="_top"> -acs-relationships-create.sql</a></p></li></ul></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-tcl-files"></a>Tcl Files</h4></div></div></div><p><span class="emphasis"><em>Not yet linked.</em></span></p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-requirements"></a>Requirements</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="object-system-requirements.html" title="Object Model Requirements">Object Model +acs-relationships-create.sql</a></p></li></ul></div> +</div> +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-tcl-files"></a>Tcl Files</h4></div></div></div> + + +<p><span class="emphasis"><em>Not yet linked.</em></span></p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-requirements"></a>Requirements</h4></div></div></div> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="link" href="object-system-requirements.html" title="Object Model Requirements">Object Model Requirements</a></p></li><li class="listitem"><p><a class="link" href="groups-requirements.html" title="Groups Requirements">Groups Requirements</a></p></li><li class="listitem"><p><a class="link" href="permissions-requirements.html" title="Permissions Requirements">Permissions -Requirements</a></p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-introduction"></a>Introduction</h3></div></div></div><p>Before OpenACS 4, software developers writing OpenACS applications or modules +Requirements</a></p></li></ul></div> +</div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-introduction"></a>Introduction</h3></div></div></div> + + + +<p>Before OpenACS 4, software developers writing OpenACS applications or modules would develop each data model separately. However, many applications built on OpenACS share certain characteristics or require certain common services. -Examples of such services include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User comments</p></li><li class="listitem"><p>Storage of user-defined or extensible sets of attributes</p></li><li class="listitem"><p>Access control</p></li><li class="listitem"><p>General auditing and bookkeeping (e.g. creation date, IP addresses, and +Examples of such services include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User comments</p></li><li class="listitem"><p>Storage of user-defined or extensible sets of attributes</p></li><li class="listitem"><p>Access control</p></li><li class="listitem"><p>General auditing and bookkeeping (e.g. creation date, IP addresses, and so forth)</p></li><li class="listitem"><p>Presentation tools (e.g. how to display a field in a form or on a -page)</p></li></ul></div><p>All of these services involve relating additional service-related +page)</p></li></ul></div> + +<p>All of these services involve relating additional service-related information to application data objects. Examples of application objects -include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>forum messages</p></li><li class="listitem"><p>A user home page</p></li><li class="listitem"><p>A ticket in the ticket tracker</p></li></ul></div><p>In the past, developers had to use ad-hoc and inconsistent schemes to +include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>forum messages</p></li><li class="listitem"><p>A user home page</p></li><li class="listitem"><p>A ticket in the ticket tracker</p></li></ul></div> + +<p>In the past, developers had to use ad-hoc and inconsistent schemes to interface to various "general" services. OpenACS 4 defines a central data model that keeps track of the application objects that we wish to manage, and serves as a primary store of <span class="emphasis"><em>metadata</em></span>. By <span class="emphasis"><em>metadata</em></span>, we mean data stored on behalf of an application <span class="emphasis"><em>outside</em></span> of the application's data model in order to enable certain central services. The OpenACS 4 Object Model (or object system) manages several different kinds of data and metadata to allow us to provide general -services to applications:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-object-ident" title="Object Identification">Object Identification</a> </p><p>Every application object is given a unique identifier in the system. This +services to applications:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-object-ident" title="Object Identification">Object Identification</a> </p> + +<p>Every application object is given a unique identifier in the system. This identifier can be used to find all data related to a particular object. -</p></li><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-obj-context" title="Object Context and Access Control">Object Context and Access Control</a> </p><p>Every object is created in a particular security context, so the system +</p></li><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-obj-context" title="Object Context and Access Control">Object Context and Access Control</a> </p> + +<p>Every object is created in a particular security context, so the system can provide centralized access control. -</p></li><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-object-types" title="Object Types and Attributes">Object Types and Attributes</a> </p><p>Objects are instances of developer-defined object types. Object types +</p></li><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-object-types" title="Object Types and Attributes">Object Types and Attributes</a> </p> + +<p>Objects are instances of developer-defined object types. Object types allow developers to customize the data that is stored with each object. -</p></li><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-relation-types" title="Relation Types">Relation Types</a> </p><p>Relation types provide a general mechanism for mapping instances of one +</p></li><li class="listitem"><p><a class="xref" href="object-system-design.html#objects-design-relation-types" title="Relation Types">Relation Types</a> </p> + +<p>Relation types provide a general mechanism for mapping instances of one object type (e.g. users) to instances of another object type (e.g. groups). -</p></li></ul></div><p>The next section will explore these facilities in the context of the the -particular programming idioms that we wish to generalize.</p><p><span class="strong"><strong>Related Links</strong></span></p><p>This design document should be read along with the design documents for <a class="link" href="groups-design.html" title="Groups Design">the new groups system</a>, <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a> and <a class="link" href="permissions-design.html" title="Permissions Design">the permissions system</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-history"></a>History</h3></div></div></div><p>The motivation for most of the facilities in the OpenACS 4 Object Model can be +</p></li></ul></div> + +<p>The next section will explore these facilities in the context of the the +particular programming idioms that we wish to generalize.</p> + +<p><span class="strong"><strong>Related Links</strong></span></p> + +<p>This design document should be read along with the design documents for <a class="link" href="groups-design.html" title="Groups Design">the new groups system</a>, <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a> and <a class="link" href="permissions-design.html" title="Permissions Design">the permissions system</a></p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-history"></a>History</h3></div></div></div> + + + +<p>The motivation for most of the facilities in the OpenACS 4 Object Model can be understood in the context of the 3.x code base and the kinds of programming -idioms that evolved there. These are listed and discussed below.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-object-ident"></a>Object Identification</h4></div></div></div><p>Object identification is a central mechanism in OpenACS 4. Every application +idioms that evolved there. These are listed and discussed below.</p> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-object-ident"></a>Object Identification</h4></div></div></div> + + +<p>Object identification is a central mechanism in OpenACS 4. Every application object in OpenACS 4 has a unique ID which is mapped to a row in a central table called <code class="computeroutput">acs_objects</code>. Developers that wish to use OpenACS 4 services need only take a few simple steps to make sure that their application objects appear in this table. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. In other words, we use object identifiers to enable centralized services in a -global and uniform manner.</p><p><span class="emphasis"><em>Implicit Object Identifiers in OpenACS 3.x</em></span></p><p>The motivation for implementing general object identifiers comes from +global and uniform manner.</p> + +<p><span class="emphasis"><em>Implicit Object Identifiers in OpenACS 3.x</em></span></p> + +<p>The motivation for implementing general object identifiers comes from several observations of data models in OpenACS 3.x. Many modules use a <code class="computeroutput">(user_id, group_id, scope)</code> column-triple for the purpose of recording ownership information on objects, for access control. User/groups also uses <code class="computeroutput">(user_id, group_id)</code> pairs in its <code class="computeroutput">user_group_map</code> table as a way to identify data associated with a -single membership relation.</p><p>Also, in OpenACS 3.x many utility modules exist that do nothing more than +single membership relation.</p> + +<p>Also, in OpenACS 3.x many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, general comments maintains a table that maps application "page" data (static or dynamic pages on the website) to one or more user comments on @@ -58,11 +131,17 @@ as the "(on_which_table + on_what_id)" method for identifying application data. In particular, general comments stores its map from pages to comments using a "(on_which_table + on_what_id)" key plus the ID -of the comment itself.</p><p>All of these composite key constructions are implicit object identifiers - +of the comment itself.</p> + +<p>All of these composite key constructions are implicit object identifiers - they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent, making the construction of generic application-independent services unnecessarily -difficult.</p><p><span class="emphasis"><em>Object Identifiers in OpenACS 4</em></span></p><p>The OpenACS 4 Object Model defines a single mechanism that applications use to +difficult.</p> + +<p><span class="emphasis"><em>Object Identifiers in OpenACS 4</em></span></p> + +<p>The OpenACS 4 Object Model defines a single mechanism that applications use to attach unique identifiers to application data. This identifier is the primary key of the <code class="computeroutput">acs_objects</code> table. This table forms the core of what we need to provide generic services like access control, general attribute @@ -73,20 +152,40 @@ make sure every object the system is to manage is associated with a row in <code class="computeroutput">acs_objects</code>. More importantly, if they do this, new services like general comments can be created without requiring existing applications -to "hook into" them via new metadata.</p><p><span class="strong"><strong>Note:</strong></span> Object identifiers are a good example of metadata +to "hook into" them via new metadata.</p> + +<p><span class="strong"><strong>Note:</strong></span> Object identifiers are a good example of metadata in the new system. Each row in <code class="computeroutput">acs_objects</code> stores information <span class="emphasis"><em>about</em></span> the application object, but not the application object itself. This becomes more clear if you skip ahead and look at the SQL schema code -that defines this table.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-obj-context"></a>Object Context and Access Control</h4></div></div></div><p>Until the implementation of the general permissions system, every OpenACS +that defines this table.</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-obj-context"></a>Object Context and Access Control</h4></div></div></div> + + +<p>Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a -notion of "scoping" was introduced into the core data model.</p><p>"Scope" is a term best explained by example. Consider some -hypothetical rows in the <code class="computeroutput">address_book</code> table:</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>...</strong></span></td><td><span class="strong"><strong><code class="computeroutput">scope</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">user_id</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">group_id</code></strong></span></td><td><span class="strong"><strong>...</strong></span></td></tr><tr><td>...</td><td><code class="computeroutput">user</code></td><td><code class="computeroutput">123</code></td><td> </td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">group</code></td><td> </td><td><code class="computeroutput">456</code></td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">public</code></td><td> </td><td> </td><td>...</td></tr></tbody></table></div><p>The first row represents an entry in User 123's personal address book, +notion of "scoping" was introduced into the core data model.</p> + +<p>"Scope" is a term best explained by example. Consider some +hypothetical rows in the <code class="computeroutput">address_book</code> table:</p> + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>...</strong></span></td><td><span class="strong"><strong><code class="computeroutput">scope</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">user_id</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">group_id</code></strong></span></td><td><span class="strong"><strong>...</strong></span></td></tr><tr><td>...</td><td><code class="computeroutput">user</code></td><td><code class="computeroutput">123</code></td><td> </td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">group</code></td><td> </td><td><code class="computeroutput">456</code></td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">public</code></td><td> </td><td> </td><td>...</td></tr></tbody></table></div> + +<p>The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address -book.</p><p>In this way, the scoping columns identify the security context in which a +book.</p> + +<p>In this way, the scoping columns identify the security context in which a given object belongs, where each context is <span class="emphasis"><em>either</em></span> a person <span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public (itself a group -of people).</p><p>In OpenACS 4, rather than breaking the world into a limited set of scopes, +of people).</p> + +<p>In OpenACS 4, rather than breaking the world into a limited set of scopes, every object lives in a single <span class="emphasis"><em>context</em></span>. A context is just an abstract name for the default security domain to which the object belongs. Each context has a unique identifier, and all the contexts in a system form a @@ -95,37 +194,61 @@ forum topic might list a subsite as its context. Thus, contexts make it easier to break the site up into security domains according to its natural structure. An object's context is stored in the <code class="computeroutput">context_id</code> -column of the <code class="computeroutput">acs_objects</code> table.</p><p>We use an object's context to provide a default answer to questions +column of the <code class="computeroutput">acs_objects</code> table.</p> + +<p>We use an object's context to provide a default answer to questions regarding access control. Whenever we ask a question of the form "can user X perform action Y on object Z", the OpenACS security model will defer to an object's context if there is no information about user X's -permission to perform action Y on object Z.</p><p>The context system forms the basis for the rest of the OpenACS access control +permission to perform action Y on object Z.</p> + +<p>The context system forms the basis for the rest of the OpenACS access control system, which is described in in two separate documents: one for the <a class="link" href="permissions-design.html" title="Permissions Design">permissions system</a> and another for the <a class="link" href="groups-design.html" title="Groups Design">party groups</a> system. The context system -is also used to implement <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a>.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-obj-types"></a>Object Types</h4></div></div></div><p>As mentioned above, many OpenACS modules provide extensible data models, and +is also used to implement <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a>.</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-obj-types"></a>Object Types</h4></div></div></div> + + +<p>As mentioned above, many OpenACS modules provide extensible data models, and need to use application specific mechanisms to keep track of user defined attributes and to map application data to these attributes. In the past, modules either used user/groups or their own ad hoc data model to provide -this functionality.</p><p><span class="emphasis"><em>User/Groups in OpenACS 3.x</em></span></p><p>The user/group system allowed developers to define <span class="emphasis"><em>group types</em></span> +this functionality.</p> + +<p><span class="emphasis"><em>User/Groups in OpenACS 3.x</em></span></p> + +<p>The user/group system allowed developers to define <span class="emphasis"><em>group types</em></span> along with attributes to be stored with each instance of a group type. Each group type could define a helper table that stored attributes on each instance of the group type. This table was called the "<code class="computeroutput">_info</code>" table because the name was generated by -appending <code class="computeroutput">_info</code> to the name of the group type.</p><p>The user/groups data model also provided the +appending <code class="computeroutput">_info</code> to the name of the group type.</p> + +<p>The user/groups data model also provided the <code class="computeroutput">user_group_type_member_fields</code> and <code class="computeroutput">user_group_member_fields</code> tables to define attributes for members of groups of a specific type and for members of a specific group, respectively. The <code class="computeroutput">user_group_member_field_map</code> table stored values for both categories of attributes in its <code class="computeroutput">field_value</code> column. These tables allowed developers and users to define custom sets of attributes to store on groups and group members without changing the data -model at the code level.</p><p>Many applications in OpenACS 3.x and earlier used the group type mechanism in +model at the code level.</p> + +<p>Many applications in OpenACS 3.x and earlier used the group type mechanism in ways that were only tangentially related to groups of users, just to obtain access to this group types mechanism. Thus the motivation for generalizing -the group types mechanism in OpenACS 4.</p><p><span class="emphasis"><em>Object Types and Subtypes</em></span></p><p>In OpenACS 4 <span class="emphasis"><em>object types</em></span> generalize the OpenACS 3.x notion of group +the group types mechanism in OpenACS 4.</p> + +<p><span class="emphasis"><em>Object Types and Subtypes</em></span></p> + +<p>In OpenACS 4 <span class="emphasis"><em>object types</em></span> generalize the OpenACS 3.x notion of group types. Each object type can define one or more attributes to be attached to instances of the type. This allows developers to define new types without -being artificially tied to a particular module (i.e. user/groups).</p><p>In addition, the OpenACS 4 object model provides mechanism for defining +being artificially tied to a particular module (i.e. user/groups).</p> + +<p>In addition, the OpenACS 4 object model provides mechanism for defining <span class="emphasis"><em>subtypes</em></span> of existing types. A subtype of a parent type inherits all the attributes defined in the parent type, and can define some of its own. The motivation for subtypes comes from the need for OpenACS to be more @@ -135,34 +258,50 @@ containing a hodge podge of unrelated information that should have been normalized away. The canonical example of this is the explosion of the <code class="computeroutput">users</code> table in OpenACS 3.x. In addition to being sloppy technically, -these fat tables have a couple of other problems:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>They degrade performance.</p></li><li class="listitem"><p>Denormalization can make it hard to maintain consistency constraints on -the data.</p></li></ul></div><p>Object subtypes provide a way to factor the data model while still keeping +these fat tables have a couple of other problems:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>They degrade performance.</p></li><li class="listitem"><p>Denormalization can make it hard to maintain consistency constraints on +the data.</p></li></ul></div> + +<p>Object subtypes provide a way to factor the data model while still keeping track of the fact that each member of a subtype (i.e. for each row in the subtype's table), is also a member of the parent type (i.e. there is a corresponding row in the parent type table). Therefore, applications an use this mechanism without worrying about this bookkeeping themselves, and we avoid having applications pollute the core data model with their specific -information.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-attributes"></a>Object Attributes, Skinny Tables</h4></div></div></div><p>As we described above, the OpenACS 3.x user/groups system stored object +information.</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-attributes"></a>Object Attributes, Skinny Tables</h4></div></div></div> + + +<p>As we described above, the OpenACS 3.x user/groups system stored object attributes in two ways. The first was to use columns in the helper table. The second consisted of two tables, one describing attributes and one storing values, to provide a flexible means for attaching attributes to metadata objects. This style of attribute storage is used in several other parts of OpenACS 3.x, and we will refer to it as "skinny tables". For -example:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>In the Ecommerce data model, the <code class="computeroutput">ec_custom_product_fields</code> +example:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>In the Ecommerce data model, the <code class="computeroutput">ec_custom_product_fields</code> table defines attributes for catalog products, and the <code class="computeroutput">ec_custom_product_field_values</code> table stores values for those attributes.</p></li><li class="listitem"><p>In the Photo DB data model, the <code class="computeroutput">ph_custom_photo_fields</code> table defines attributes for the photographs owned by a specific user, and tables named according to the convention "<code class="computeroutput">ph_user_<user_id>_custom_info</code>" are used to -store values for those attributes.</p></li></ul></div><p>In addition, there are some instances where we are not using this model +store values for those attributes.</p></li></ul></div> + +<p>In addition, there are some instances where we are not using this model but <span class="emphasis"><em>should</em></span>, e.g. the <code class="computeroutput">users_preferences</code> table, which stores preferences for registered users in columns such as <code class="computeroutput">prefer_text_only_p</code> and <code class="computeroutput">dont_spam_me_p</code>. The "standard" way for an OpenACS 3.x-based application to add to the list of user preferences is to add a column to the <code class="computeroutput">users_preferences</code> table (exactly the kind of data model change that has historically -complicated the process of upgrading to a more recent OpenACS version).</p><p>The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups +complicated the process of upgrading to a more recent OpenACS version).</p> + +<p>The Objet Model generalizes the scheme used in the old OpenACS 3.x user/groups system. It defines a table called <code class="computeroutput">acs_attributes</code> that record what attributes belong to which object types, and how the attributes are stored. As before, attributes can either be stored in helper tables, or in a @@ -173,7 +312,13 @@ skinny tables because doing so allows developers and users to dynamically update the set of attributes stored on an object without updating the data model at the code level. The bottom line: Helper tables are more functional -and more efficient, skinny tables are more flexible but limited.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-relation-types"></a>Relation Types</h4></div></div></div><p>Many OpenACS 3.x modules use <span class="emphasis"><em>mapping tables</em></span> to model relationships +and more efficient, skinny tables are more flexible but limited.</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-relation-types"></a>Relation Types</h4></div></div></div> + + +<p>Many OpenACS 3.x modules use <span class="emphasis"><em>mapping tables</em></span> to model relationships between application objects. Again, the 3.x user/groups system provides the canonical example of this design style. In that system, there was a single table called <code class="computeroutput">user_group_map</code> that kept track of which users @@ -182,31 +327,53 @@ <code class="computeroutput">user_group_member_fields_map</code> tables to allow developers to attach custom attributes to group members. In fact, these attributes were not really attached to the users, but to the fact that a user was a member of a -particular group - a subtle but important distinction.</p><p>In OpenACS 4, <span class="emphasis"><em>relation types</em></span> generalize this mechanism. Relation +particular group - a subtle but important distinction.</p> + +<p>In OpenACS 4, <span class="emphasis"><em>relation types</em></span> generalize this mechanism. Relation types allow developers to define general mappings from objects of a given type T, to other objects of a given type R. Each relation type is a subtype of <code class="computeroutput">acs_object</code>, extended with extra attributes that store constraints on the relation, and the types of objects the relation actually maps. In turn, each instance of a relation type is an object that represents a single fact of the form "the object t of type T is related to the object r of type R." That is, each instance of a relation type is -essentially just a pair of objects.</p><p>Relation types generalize mapping tables. For example, the 3.x user/groups +essentially just a pair of objects.</p> + +<p>Relation types generalize mapping tables. For example, the 3.x user/groups data model can be largely duplicated using a single relation type describing the "group membership" relation. Group types would then be subtypes of this membership relation type. Group type attributes would be attached to the relation type itself. Group member attributes would be attached to instances of the membership relation. Finally, the mapping table would be -replaced by a central skinny table that the relation type system defines.</p><p>Relation types should be used when you want to be able to attach data to +replaced by a central skinny table that the relation type system defines.</p> + +<p>Relation types should be used when you want to be able to attach data to the "fact" that object X and object Y are related to each other. On the face of it, they seem like a redundant mechanism however, since one could easily create a mapping table to do the same thing. The advantage of registering this table as a relation type is that in principle the OpenACS 4 object system could use the meta data in the types table to do useful things in a generic way on all relation types. But this mechanism doesn't really -exist yet.</p><p>Relation types are a somewhat abstract idea. To get a better feel for -them, you should just skip to the <a class="link" href="object-system-design.html#object-system-design-relsmodel">data model</a>.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-summary"></a>Summary and Design Considerations</h3></div></div></div><p>The OpenACS 4 Object Model is designed to generalize and unify the following +exist yet.</p> + +<p>Relation types are a somewhat abstract idea. To get a better feel for +them, you should just skip to the <a class="link" href="object-system-design.html#object-system-design-relsmodel">data model</a>.</p> +</div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-summary"></a>Summary and Design Considerations</h3></div></div></div> + + + +<p>The OpenACS 4 Object Model is designed to generalize and unify the following mechanisms that are repeatedly implemented in OpenACS-based systems to manage -generic and application specific metadata:</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-why-not-objdb"></a>Why not Object Databases?</h4></div></div></div><p>The presence of a framework for subtyping and inheritance always brings up +generic and application specific metadata:</p> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-why-not-objdb"></a>Why not Object Databases?</h4></div></div></div> + + +<p>The presence of a framework for subtyping and inheritance always brings up the question of why we don't just use an object database. The main reason is that all of the major object database vendors ship products that are effectively tied to some set of object oriented programming languages. Their @@ -219,7 +386,8 @@ expressible in the host language. In particular, we lose many of the best features of the relational database model. This is a disaster from an ease of use standpoint. - </p><p>The "Object relational" systems provide an interesting + </p> +<p>The "Object relational" systems provide an interesting alternative. Here, some notion of subtyping is embedded into an existing SQL or SQL-like database engine. Examples of systems like this include the new Informix, PostgreSQL 7, and Oracle has something like this too. The main @@ -230,35 +398,72 @@ practice. Finally, object databases are not as widely used as traditional relational systems. They have not been tested as extensively and their scalability to very large databases is not proven (though some will disagree -with this statement).</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-oracle"></a>Oracle</h4></div></div></div><p>The conclusion: the best design is to add a limited notion of subtyping to +with this statement).</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-oracle"></a>Oracle</h4></div></div></div> + + +<p>The conclusion: the best design is to add a limited notion of subtyping to our existing relational data model. By doing this, we retain all the power of the relational data model while gaining the object oriented features we need -most.</p><p>In the context of OpenACS 4, this means using the object model to make our +most.</p> + +<p>In the context of OpenACS 4, this means using the object model to make our data models more flexible, so that new modules can easily gain access to generic features. However, while the API itself doesn't enforce the idea that applications only use the object model for metadata, it is also the case that the data model is not designed to scale to large type hierarchies. In the more limited domain of the metadata model, this is acceptable since the type hierarchy is fairly small. But the object system data model is not designed to support, for example, a huge type tree like the Java runtime -libraries might define.</p><p>This last point cannot be over-stressed: <span class="strong"><strong>the object model is not +libraries might define.</p> + +<p>This last point cannot be over-stressed: <span class="strong"><strong>the object model is not meant to be used for large scale application data storage</strong></span>. It is -meant to represent and store metadata, not application data.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-datamodel"></a>Data Model</h3></div></div></div><p>Like most data models, the OpenACS Core data model has two levels:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>The <span class="emphasis"><em>knowledge level</em></span> (i.e. the metadata model)</p></li><li class="listitem"><p>The <span class="emphasis"><em>operational level</em></span> (i.e. the concrete data model)</p></li></ol></div><p> +meant to represent and store metadata, not application data.</p> +</div> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-datamodel"></a>Data Model</h3></div></div></div> + + + +<p>Like most data models, the OpenACS Core data model has two levels:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>The <span class="emphasis"><em>knowledge level</em></span> (i.e. the metadata model)</p></li><li class="listitem"><p>The <span class="emphasis"><em>operational level</em></span> (i.e. the concrete data model)</p></li></ol></div> + +<p> You can browse the data models themselves from here: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top"> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-metadata-create.sql&package_key=acs-kernel" target="_top"> acs-metadata-create.sql</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-objects-create.sql&package_key=acs-kernel" target="_top"> acs-objects-create.sql</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-relationships-create.sql&package_key=acs-kernel" target="_top"> -acs-relationships-create.sql</a></p></li></ul></div><p>(Note that we have subdivided the operational level into the latter two -files.)</p><p>The operational level depends on the knowledge level, so we discuss the +acs-relationships-create.sql</a></p></li></ul></div> + +<p>(Note that we have subdivided the operational level into the latter two +files.)</p> + +<p>The operational level depends on the knowledge level, so we discuss the knowledge level first. In the text below, we include abbreviated versions of the SQL definitions of many tables. Generally, these match the actual definitions in the existing data model but they are meant to reflect design information, not implementation. Some less relevant columns may be left out, -and things like constraint names are not included.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-knowledge-level"></a>Knowledge-Level Model</h4></div></div></div><p>The knowledge level data model for OpenACS objects centers around three tables +and things like constraint names are not included.</p> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-knowledge-level"></a>Knowledge-Level Model</h4></div></div></div> + + +<p>The knowledge level data model for OpenACS objects centers around three tables that keep track of object types, attributes, and relation types. The first table is <code class="computeroutput">acs_object_types</code>, shown here in an abbreviated -form:</p><pre class="programlisting"> +form:</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table acs_object_types ( object_type varchar(1000) not null primary key, supertype references acs_object_types (object_type), @@ -272,8 +477,13 @@ ); </code> -</pre><p>This table contains one row for every object type in the system. The key -things to note about this table are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For every type, we store metadata for how to display this type in certain +</pre> + + +<p>This table contains one row for every object type in the system. The key +things to note about this table are:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>For every type, we store metadata for how to display this type in certain contexts (<code class="computeroutput">pretty_name</code> and <code class="computeroutput">pretty_plural</code>).</p></li><li class="listitem"><p>If the type is a subtype, then its parent type is stored in the column <code class="computeroutput">supertype</code>.</p></li><li class="listitem"><p>We support a notion of "abstract" types that contain no instances (as of 9/2000 this is not actually used). These types exist only to @@ -282,13 +492,19 @@ create subtypes that represent real, concrete shapes like circles, squares, and so on.</p></li><li class="listitem"><p>Every type defines a table in which one can find one row for every instance of this type (<code class="computeroutput">table_name</code>, <code class="computeroutput">id_column</code>).</p></li><li class="listitem"><p><code class="computeroutput">type_extension_table</code> is for naming a table that stores extra -generic attributes.</p></li></ul></div><p>The second table we use to describe types is <code class="computeroutput">acs_attributes</code>. +generic attributes.</p></li></ul></div> + +<p>The second table we use to describe types is <code class="computeroutput">acs_attributes</code>. Each row in this table represents a single attribute on a specific object type (e.g. the "password" attribute of the "user" type). Again, here is an abbreviated version of what this table looks like. The actual table used in the implementation is somewhat different and is -discussed in a separate document.</p><pre class="programlisting"> +discussed in a separate document.</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table acs_attributes ( attribute_id integer not null primary key object_type not null references acs_object_types (object_type), @@ -307,7 +523,12 @@ ); </code> -</pre><p>The following points are important about this table:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Every attribute has a unique identifier.</p></li><li class="listitem"><p>Every attribute is associated with an object type.</p></li><li class="listitem"><p>We store various things about each attribute for presentation +</pre> + + +<p>The following points are important about this table:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Every attribute has a unique identifier.</p></li><li class="listitem"><p>Every attribute is associated with an object type.</p></li><li class="listitem"><p>We store various things about each attribute for presentation (<code class="computeroutput">pretty_name</code>, <code class="computeroutput">sort_order</code>).</p></li><li class="listitem"><p>The <code class="computeroutput">data_type</code> column stores type information on this attribute. This is not the SQL type of the attribute; it is just a human readable name for the type of data we think the attribute holds (e.g. @@ -325,17 +546,26 @@ encode information about the number of values an attribute may hold. Attributes can be defined to hold 0 or more total values.</p></li><li class="listitem"><p>The <code class="computeroutput">static_p</code> flag indicates whether this attribute value is shard by all instances of a type, as with static member fields in C++. Static -attribute are like group level attributes in OpenACS 3.x.</p></li></ul></div><p>The final part of the knowledge level model keeps track of relationship +attribute are like group level attributes in OpenACS 3.x.</p></li></ul></div> + + +<p>The final part of the knowledge level model keeps track of relationship types. We said above that object relationships are used to generalize the 3.x notion of <span class="emphasis"><em>group member fields</em></span>. These were fields that a developer could store on each member of a group, but which were contextualized to the membership relation. That is, they were really "attached" to the fact that a user was a member of a particular group, and not really attached to the user. This is a subtle but important distinction, because it allowed the 3.x system to store multiple sets of attributes on a given user, one set -for each group membership relation in which they participated.</p><p>In OpenACS 4, this sort of data can be stored as a relationship type, in <a name="object-system-design-relsmodel"></a> -<code class="computeroutput">acs_rel_types</code>. The key parts of this table look like this:</p><pre class="programlisting"> +for each group membership relation in which they participated.</p> +<p>In OpenACS 4, this sort of data can be stored as a relationship type, in <a name="object-system-design-relsmodel"></a> +<code class="computeroutput">acs_rel_types</code>. The key parts of this table look like this:</p> + + + +<pre class="programlisting"> + <code class="computeroutput">create table acs_rel_types ( rel_type varchar(1000) not null references acs_object_types(object_type), @@ -352,28 +582,50 @@ ); </code> -</pre><p>Things to note about this table:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The main part of this table records the fact that the relation is between +</pre> + + +<p>Things to note about this table:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>The main part of this table records the fact that the relation is between instances of <code class="computeroutput">object_type_one</code> and instances of <code class="computeroutput">object_type_two</code>. Therefore, each instance of this relation type will be a pair of objects of the appropriate types.</p></li><li class="listitem"><p>The <code class="computeroutput">role</code> columns store human readable names for the roles played by each object in the relation (e.g. "employee" and "employer"). Each role must appear in the <code class="computeroutput">acs_rel_roles</code>.</p></li><li class="listitem"><p>The <code class="computeroutput">min_n_rels_one</code> column, and its three friends allow the programmer to specify constraints on how many objects any given object can be -related to on either side of the relation.</p></li></ul></div><p>This table is easier to understand if you also know how the <a class="link" href="object-system-design.html#object-system-design-acs-rels"><code class="computeroutput">acs_rels</code> table</a> works.</p><p>To summarize, the <code class="computeroutput">acs_object_types</code> and +related to on either side of the relation.</p></li></ul></div> + + +<p>This table is easier to understand if you also know how the <a class="link" href="object-system-design.html#object-system-design-acs-rels"><code class="computeroutput">acs_rels</code> table</a> works.</p> + +<p>To summarize, the <code class="computeroutput">acs_object_types</code> and <code class="computeroutput">acs_attributes</code> tables store metadata that describes every object type and attribute in the system. These tables generalize the group types data model in OpenACS 3.x. The <code class="computeroutput">acs_rel_types</code> table stores -information about relation types.</p><p>This part of the data model is somewhat analogous to the data dictionary +information about relation types.</p> + +<p>This part of the data model is somewhat analogous to the data dictionary in Oracle. The information stored here is primarily metadata that describes the data stored in the <a class="link" href="object-system-design.html#objects-design-op-level" title="Operational-level Data Model">operational level</a> of the data -model, which is discussed next.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-op-level"></a>Operational-level Data Model</h4></div></div></div><p>The operational level data model centers around the +model, which is discussed next.</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-op-level"></a>Operational-level Data Model</h4></div></div></div> + + +<p>The operational level data model centers around the <code class="computeroutput">acs_objects</code> table. This table contains a single row for every instance of the type <code class="computeroutput">acs_object</code>. The table contains the object's unique identifier, a reference to its type, security information, and generic auditing information. Here is what the table looks -like:</p><pre class="programlisting"> +like:</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table acs_objects ( object_id integer not null, object_type not null @@ -390,16 +642,25 @@ ); </code> -</pre><p>As we said in Section III, security contexts are hierarchical and also +</pre> + + +<p>As we said in Section III, security contexts are hierarchical and also modeled as objects. There is another table called -<code class="computeroutput">acs_object_context_index</code> that stores the context hierarchy.</p><p>Other tables in the core data model store additional information related +<code class="computeroutput">acs_object_context_index</code> that stores the context hierarchy.</p> + +<p>Other tables in the core data model store additional information related to objects. The table <code class="computeroutput">acs_attribute_values</code> and <code class="computeroutput">acs_static_attr_values</code> are used to store attribute values that are not stored in a helper table associated with the object's type. The former is used for instance attributes while the latter is used for class-wide "static" values. These tables have the same basic form, -so we'll only show the first:</p><pre class="programlisting"> +so we'll only show the first:</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table acs_attribute_values ( object_id not null references acs_objects (object_id) on delete cascade, @@ -410,9 +671,16 @@ ); </code> -</pre><p>Finally, the table <code class="computeroutput">acs_rels</code> <a name="object-system-design-acs-rels"></a>is used to store object pairs -that are instances of a relation type.</p><pre class="programlisting"> +</pre> + +<p>Finally, the table <code class="computeroutput">acs_rels</code> <a name="object-system-design-acs-rels"></a>is used to store object pairs +that are instances of a relation type.</p> + + + +<pre class="programlisting"> + <code class="computeroutput">create table acs_rels ( rel_id not null references acs_objects (object_id) @@ -427,30 +695,67 @@ ); </code> -</pre><p>This table is somewhat subtle:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">rel_id</code> is the ID of an <span class="emphasis"><em>instance</em></span> of some relation +</pre> + + +<p>This table is somewhat subtle:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">rel_id</code> is the ID of an <span class="emphasis"><em>instance</em></span> of some relation type. We do this so we can store all the mapping tables in this one table.</p></li><li class="listitem"><p><code class="computeroutput">rel_type</code> is the ID of the relation type to which this object -belongs.</p></li><li class="listitem"><p>The next two object IDs are the IDs of the objects being mapped.</p></li></ul></div><p>All this table does is store one row for every pair of objects that +belongs.</p></li><li class="listitem"><p>The next two object IDs are the IDs of the objects being mapped.</p></li></ul></div> + +<p>All this table does is store one row for every pair of objects that we'd like to attach with a relation. Any additional attributes that we'd like to attach to this pair of objects is specified in the attributes of the relation type, and could be stored in any number of places. As in the 3.x user/groups system, these places include helper tables or -generic skinny tables.</p><p>This table, along with <code class="computeroutput">acs_attributes</code> and +generic skinny tables.</p> + +<p>This table, along with <code class="computeroutput">acs_attributes</code> and <code class="computeroutput">acs_attribute_values</code> generalize the old user/group tables <code class="computeroutput">user_group_map</code>, <code class="computeroutput">user_group_member_fields_map</code> and -<code class="computeroutput">user_group_member_fields</code>.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-discussion"></a>Summary and Discussion</h4></div></div></div><p>The core tables in the OpenACS 4 data model store information about instances +<code class="computeroutput">user_group_member_fields</code>.</p> +</div> +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-discussion"></a>Summary and Discussion</h4></div></div></div> + + +<p>The core tables in the OpenACS 4 data model store information about instances of object types and relation types. The <code class="computeroutput">acs_object</code> table provides the central location that contains a single row for every object in the system. Services can use this table along with the metadata in stored in the knowledge level data model to create, manage, query and manipulate objects in a uniform manner. The <code class="computeroutput">acs_rels</code> table has an analogous -role in storing information on relations.</p><p>These are all the tables that we'll discuss in this document. The rest -of the Kernel data model is described in the documents for <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a>, the <a class="link" href="permissions-design.html" title="Permissions Design">permissions</a> system and for the <a class="link" href="groups-design.html" title="Groups Design">groups</a> system.</p><p>Some examples of how these tables are used in the system can be found in -the discussion of the API, which comes next.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-api"></a>API</h3></div></div></div><p>Now we'll examine each piece of the API in detail. Bear in mind that -the Object Model API is defined primarily through PL/SQL packages.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-object-types"></a>Object Types and Attributes</h4></div></div></div><p>The object system provides an API for creating new object types and then +role in storing information on relations.</p> + +<p>These are all the tables that we'll discuss in this document. The rest +of the Kernel data model is described in the documents for <a class="link" href="subsites-design.html" title="Subsites Design Document">subsites</a>, the <a class="link" href="permissions-design.html" title="Permissions Design">permissions</a> system and for the <a class="link" href="groups-design.html" title="Groups Design">groups</a> system.</p> + +<p>Some examples of how these tables are used in the system can be found in +the discussion of the API, which comes next.</p> +</div> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-api"></a>API</h3></div></div></div> + + + +<p>Now we'll examine each piece of the API in detail. Bear in mind that +the Object Model API is defined primarily through PL/SQL packages.</p> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-object-types"></a>Object Types and Attributes</h4></div></div></div> + + +<p>The object system provides an API for creating new object types and then attaching attributes to them. The procedures <code class="computeroutput">create_type</code> and -<code class="computeroutput">drop_type</code> are used to create and delete type definitions.</p><p>The two calls show up in the package <code class="computeroutput">acs_object_type</code>.</p><pre class="programlisting"> +<code class="computeroutput">drop_type</code> are used to create and delete type definitions.</p> +<p>The two calls show up in the package <code class="computeroutput">acs_object_type</code>.</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> procedure create_type ( object_type in acs_object_types.object_type%TYPE, pretty_name in acs_object_types.pretty_name%TYPE, @@ -472,10 +777,19 @@ ); </code> -</pre><p>Here the <code class="computeroutput">cascade_p</code> argument indicates whether dropping a type -should also remove all its subtypes from the system.</p><p>We define a similar interface for defining attributes in the package -<code class="computeroutput">acs_attribute</code>:</p><pre class="programlisting"> +</pre> + +<p>Here the <code class="computeroutput">cascade_p</code> argument indicates whether dropping a type +should also remove all its subtypes from the system.</p> + +<p>We define a similar interface for defining attributes in the package +<code class="computeroutput">acs_attribute</code>:</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> function create_attribute ( object_type in acs_attributes.object_type%TYPE, attribute_name in acs_attributes.attribute_name%TYPE, @@ -499,9 +813,16 @@ </code> -</pre><p>In addition, the following two calls are available for attaching extra -annotations onto attributes:</p><pre class="programlisting"> +</pre> + +<p>In addition, the following two calls are available for attaching extra +annotations onto attributes:</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> procedure add_description ( object_type in acs_attribute_descriptions.object_type%TYPE, attribute_name in acs_attribute_descriptions.attribute_name%TYPE, @@ -516,27 +837,45 @@ ); </code> -</pre><p>At this point, what you must do to hook into the object system from your -own data model becomes clear:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Create a table that will store the instances of the new type.</p></li><li class="listitem"><p>Call <code class="computeroutput">acs_object_type.create_type()</code> to fill in the metadata +</pre> + + +<p>At this point, what you must do to hook into the object system from your +own data model becomes clear:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Create a table that will store the instances of the new type.</p></li><li class="listitem"><p>Call <code class="computeroutput">acs_object_type.create_type()</code> to fill in the metadata table on this new type. If you want your objects to appear in the <code class="computeroutput">acs_objects</code> table, then your new type must be a subtype of <code class="computeroutput">acs_object</code>.</p></li><li class="listitem"><p>Call <code class="computeroutput">acs_attribute.create_attribute()</code> to fill in information -on the attributes that this type defines.</p></li></ul></div><p>So, suppose we are writing a new version of the ticket tracker for 4.0. We +on the attributes that this type defines.</p></li></ul></div> + +<p>So, suppose we are writing a new version of the ticket tracker for 4.0. We probably define a table to store tickets in, and each ticket might have an ID and a description. If we want each ticket to be an object, then <code class="computeroutput">ticket_id</code> must reference the <code class="computeroutput">object_id</code> column in -<code class="computeroutput">acs_objects</code>:</p><pre class="programlisting"> +<code class="computeroutput">acs_objects</code>:</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table tickets ( ticket_id references acs_objects (object_id), description varchar(512), ... ) ; </code> -</pre><p>In addition to defining the table, we need this extra PL/SQL code to hook -into the object type tables:</p><pre class="programlisting"> +</pre> + +<p>In addition to defining the table, we need this extra PL/SQL code to hook +into the object type tables:</p> + + + +<pre class="programlisting"> + <code class="computeroutput">declare attr_id acs_attributes.attribute_id%TYPE; begin @@ -564,22 +903,36 @@ end; </code> -</pre><p>Thus, with a small amount of extra code, the new ticket tracker will now +</pre> + + +<p>Thus, with a small amount of extra code, the new ticket tracker will now automatically be hooked into every generic object service that exists. Better still, this code need not be changed as new services are added. As an aside, the most important service that requires you to subtype -<code class="computeroutput">acs_object</code> is <a class="link" href="permissions-design.html" title="Permissions Design">permissions</a>.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-objects"></a>Objects</h4></div></div></div><p>The next important piece of the API is defined in the +<code class="computeroutput">acs_object</code> is <a class="link" href="permissions-design.html" title="Permissions Design">permissions</a>.</p> +</div> +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-objects"></a>Objects</h4></div></div></div> + + +<p>The next important piece of the API is defined in the <code class="computeroutput">acs_object</code> package, and is concerned with creating and managing objects. This part of the API is designed to take care of the mundane bookkeeping needed to create objects and query their attributes. Realistically however, limitations in PL/SQL and Oracle will make it hard to build generic procedures for doing large scale queries in the object system, so developers who need to do this will probably have to be fairly familiar -with the data model at a lower level.</p><p>The function <code class="computeroutput">acs_object.new()</code> makes a new object for you. The +with the data model at a lower level.</p> + +<p>The function <code class="computeroutput">acs_object.new()</code> makes a new object for you. The function <code class="computeroutput">acs_object.del()</code> deletes an object. As before, this is an abbreviated interface with all the long type specs removed. See the -data model or developer's guide for the full interface.</p><pre class="programlisting"> +data model or developer's guide for the full interface.</p> + + +<pre class="programlisting"> + <code class="computeroutput"> function new ( object_id in acs_objects.object_id%TYPE default null, object_type in acs_objects.object_type%TYPE @@ -597,12 +950,21 @@ ); </code> -</pre><p>Next, we define some generic functions to manipulate attributes. Again, +</pre> + + +<p>Next, we define some generic functions to manipulate attributes. Again, these interfaces are useful to an extent, but for large scale queries, it's likely that developers would have to query the data model directly, -and then encapsulate their queries in procedures.</p><p>For names, the <code class="computeroutput">default_name</code> function is used if you don't -want to define your own name function.</p><pre class="programlisting"> +and then encapsulate their queries in procedures.</p> +<p>For names, the <code class="computeroutput">default_name</code> function is used if you don't +want to define your own name function.</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> function name ( object_id in acs_objects.object_id%TYPE ) return varchar; @@ -613,9 +975,16 @@ </code> -</pre><p>The following functions tell you where attributes are stored, and fetch -single attributes for you.</p><pre class="programlisting"> +</pre> + +<p>The following functions tell you where attributes are stored, and fetch +single attributes for you.</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> procedure get_attribute_storage ( object_id_in in acs_objects.object_id%TYPE, attribute_name_in in acs_attributes.attribute_name%TYPE, @@ -636,14 +1005,23 @@ ); </code> -</pre><p>The main use of the <code class="computeroutput">acs_object</code> package is to create +</pre> + + +<p>The main use of the <code class="computeroutput">acs_object</code> package is to create application objects and make them available for services via the <code class="computeroutput">acs_objects</code> table. To do this, you just have to make sure you call <code class="computeroutput">acs_object.new()</code> on objects that you wish to appear in the <code class="computeroutput">acs_objects</code> table. In addition, all such objects must be -instances of some subtype of <code class="computeroutput">acs_object</code>.</p><p>Continuing the ticket example, we might define the following sort of -procedure for creating a new ticket:</p><pre class="programlisting"> +instances of some subtype of <code class="computeroutput">acs_object</code>.</p> +<p>Continuing the ticket example, we might define the following sort of +procedure for creating a new ticket:</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> function new_ticket ( package_id in tickets.ticket_id%TYPE default null, @@ -666,27 +1044,47 @@ end new_ticket; </code> -</pre><p>This function will typically be defined in the context of a PL/SQL -package, but we've left it stand-alone here for simplicity.</p><p>To summarize: in order to take advantage of OpenACS 4 services, a new -application need only do three things:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Define a data model to describe application objects. This can just be a +</pre> + + +<p>This function will typically be defined in the context of a PL/SQL +package, but we've left it stand-alone here for simplicity.</p> + +<p>To summarize: in order to take advantage of OpenACS 4 services, a new +application need only do three things:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Define a data model to describe application objects. This can just be a normal SQL table.</p></li><li class="listitem"><p>Create an object type, using code like in the example from the previous section.</p></li><li class="listitem"><p>Make sure application objects are created using <code class="computeroutput">acs_object.new()</code> in addition to whatever SQL code is needed to -insert a new row into the application data model.</p></li></ul></div><p>One of the design goals of OpenACS 4 was to provide a straightforward and +insert a new row into the application data model.</p></li></ul></div> + +<p>One of the design goals of OpenACS 4 was to provide a straightforward and consistent mechanism to provide applications with general services. What we have seen here is that three simple steps and minimal changes in the application data model are sufficient to make sure that application objects are represented in the <code class="computeroutput">acs_objects</code> table. Subsequently, all of the general services in OpenACS 4 (i.e. permissions, general comments, and so on) are written to work with any object that appears in <code class="computeroutput">acs_objects</code>. Therefore, in general these three steps are sufficient to make OpenACS 4 services -available to your application.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-relat-types"></a>Relation Types</h4></div></div></div><p>The relations system defines two packages: <code class="computeroutput">acs_rel_type</code> for +available to your application.</p> +</div> +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-relat-types"></a>Relation Types</h4></div></div></div> + + +<p>The relations system defines two packages: <code class="computeroutput">acs_rel_type</code> for creating and managing relation types, and <code class="computeroutput">acs_rel</code> for relating -objects.</p><p>These two procedures just insert and remove roles from the +objects.</p> + +<p>These two procedures just insert and remove roles from the <code class="computeroutput">acs_rel_roles</code> table. This table stores the legal relationship "roles" that can be used when creating relation types. Examples of -roles are, say, "member", or "employer".</p><pre class="programlisting"> +roles are, say, "member", or "employer".</p> + + +<pre class="programlisting"> + <code class="computeroutput"> procedure create_role ( role in acs_rel_roles.role%TYPE ); @@ -696,9 +1094,16 @@ ); </code> -</pre><p>The main functions in the <code class="computeroutput">acs_rel_type</code> package are used to -create and drop relation types.</p><pre class="programlisting"> +</pre> + +<p>The main functions in the <code class="computeroutput">acs_rel_type</code> package are used to +create and drop relation types.</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> procedure create_type ( rel_type in acs_rel_types.rel_type%TYPE, pretty_name in acs_object_types.pretty_name%TYPE, @@ -727,9 +1132,16 @@ ); </code> -</pre><p>Finally, the <code class="computeroutput">acs_rel</code> package provides an API that you use to -create and destroy instances of a relation type:</p><pre class="programlisting"> +</pre> + +<p>Finally, the <code class="computeroutput">acs_rel</code> package provides an API that you use to +create and destroy instances of a relation type:</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> function new ( rel_id in acs_rels.rel_id%TYPE default null, rel_type in acs_rels.rel_type%TYPE default 'relationship', @@ -745,12 +1157,19 @@ ); </code> -</pre><p>A good example of how to use relation types appears in the OpenACS 4 data +</pre> + + +<p>A good example of how to use relation types appears in the OpenACS 4 data model for <span class="emphasis"><em>groups</em></span>. As in 3.x, group membership is modeled using a mapping table, but now we create this mapping using relation types instead of explicitly creating a table. First, we create a helper table to store state -on each membership fact:</p><pre class="programlisting"> +on each membership fact:</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table membership_rels ( rel_id constraint membership_rel_rel_id_fk references acs_rels (rel_id) @@ -763,8 +1182,15 @@ ); </code> -</pre><p>Then, we create a new object type to describe groups.</p><pre class="programlisting"> +</pre> + +<p>Then, we create a new object type to describe groups.</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> acs_object_type.create_type ( object_type => 'group', pretty_name => 'Group', @@ -776,15 +1202,24 @@ ); </code> -</pre><p>In this example, we've made groups a subtype of +</pre> + + +<p>In this example, we've made groups a subtype of <code class="computeroutput">acs_object</code> to make the code simpler. The actual data model is somewhat different. Also, we've assumed that there is a helper table called <code class="computeroutput">groups</code> to store information on groups, and that there is a helper table called <code class="computeroutput">group_types</code> that has been defined to store -extra attributes on groups.</p><p>Now, assuming we have another object type called <code class="computeroutput">person</code> to +extra attributes on groups.</p> + +<p>Now, assuming we have another object type called <code class="computeroutput">person</code> to represent objects that can be group members, we define the following -relationship type for group membership:</p><pre class="programlisting"> +relationship type for group membership:</p> + + +<pre class="programlisting"> + <code class="computeroutput"> acs_rel_type.create_role ('member'); acs_rel_type.create_type ( @@ -800,13 +1235,20 @@ ); </code> -</pre><p>Now we can define the following procedure to add a new member to a group. +</pre> + + +<p>Now we can define the following procedure to add a new member to a group. All this function does is create a new instance of the membership relation type and then insert the membership state into the helper table that we define above. In the actual implementation, this function is implemented in the <code class="computeroutput">membership_rel</code> package. Here we just define an independent -function:</p><pre class="programlisting"> +function:</p> + + +<pre class="programlisting"> + <code class="computeroutput">function member_add ( rel_id in membership_rels.rel_id%TYPE default null, rel_type in acs_rels.rel_type%TYPE default 'membership_rel', @@ -836,9 +1278,16 @@ end; </code> -</pre><p>Another simple function can be defined to remove a member from a -group:</p><pre class="programlisting"> +</pre> + +<p>Another simple function can be defined to remove a member from a +group:</p> + + + +<pre class="programlisting"> + <code class="computeroutput"> procedure member_delete ( rel_id in membership_rels.rel_id%TYPE ) @@ -851,11 +1300,48 @@ end; </code> -</pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-discuss"></a>Summary and Discussion</h4></div></div></div><p>The Object Model's API and data model provides a small set of simple +</pre> + +</div> +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="objects-design-discuss"></a>Summary and Discussion</h4></div></div></div> + + +<p>The Object Model's API and data model provides a small set of simple procedures that allow applications to create object types, object instances, and object relations. Most of the data model is straightforward; the relation type mechanism is a bit more complex, but in return it provides functionality -on par with the old user/groups system in a more general way.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div><p>Nothing here yet.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-authors"></a>Authors</h3></div></div></div><p>Pete Su generated this document +on par with the old user/groups system in a more general way.</p> +</div> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div> + + + +<p>Nothing here yet.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-authors"></a>Authors</h3></div></div></div> + + + +<p>Pete Su generated this document from material culled from other documents by Michael Yoon, Richard Li and Rafael Schloming. But, any remaining lies -are his and his alone.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-revision-hist"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/09/2000</td><td>Pete Su</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta</td><td>9/30/2000</td><td>Kai Wu</td></tr><tr><td>0.3</td><td>Edited for ACS 4.0.1, fixed some mistakes, removed use of term -"OM"</td><td>11/07/2000</td><td>Pete Su</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Object Model Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Permissions Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +are his and his alone.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-design-revision-hist"></a>Revision History</h3></div></div></div> + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/09/2000</td><td>Pete Su</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta</td><td>9/30/2000</td><td>Kai Wu</td></tr><tr><td>0.3</td><td>Edited for ACS 4.0.1, fixed some mistakes, removed use of term +"OM"</td><td>11/07/2000</td><td>Pete Su</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Object Model Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Permissions Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="object-system-design" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="object-system-requirements" id="object-system-requirements"></a>Object Model Requirements</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="object-system-requirements" id="object-system-requirements"></a>Object Model Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="object-system-requirements-" id="object-system-requirements-"></a>I. Introduction</h3></div></div></div><p>A major goal in OpenACS 4 is to unify and normalize many of the core services of the system into a coherent common data model and Index: openacs-4/packages/acs-core-docs/www/object-system-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/object-system-requirements.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/object-system-requirements.html 7 Aug 2017 23:47:51 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/object-system-requirements.html 8 Nov 2017 09:42:11 -0000 1.36 @@ -1,18 +1,38 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Object Model Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="kernel-overview.html" title="Overview"><link rel="next" href="object-system-design.html" title="Object Model Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-system-requirements"></a>Object Model Requirements</h2></div></div></div><div class="authorblurb"><p>By Pete Su</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-"></a>I. Introduction</h3></div></div></div><p>A major goal in OpenACS 4 is to unify and normalize many of the core services +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Object Model Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="kernel-overview.html" title="Overview"><link rel="next" href="object-system-design.html" title="Object Model Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="object-system-requirements"></a>Object Model Requirements</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By Pete Su</p> +</authorblurb></span> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-"></a>I. Introduction</h3></div></div></div> + + + +<p>A major goal in OpenACS 4 is to unify and normalize many of the core services of the system into a coherent common data model and API. In the past, these services were provided to applications in an ad-hoc and irregular fashion. -Examples of such services include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>General Comments</p></li><li class="listitem"><p>User/groups</p></li><li class="listitem"><p>Attribute storage in user/groups</p></li><li class="listitem"><p>General Permissions</p></li><li class="listitem"><p>Site wide search</p></li><li class="listitem"><p>General Auditing</p></li></ul></div><p>All of these services involve relating extra information and services to -application data objects, examples of which include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bboard messages</p></li><li class="listitem"><p>A user home page</p></li><li class="listitem"><p>A ticket in the Ticket Tracker</p></li><li class="listitem"><p>A photograph in the PhotoDB</p></li></ul></div><p>In the past, developers had to use ad-hoc and inconsistent schemes to +Examples of such services include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>General Comments</p></li><li class="listitem"><p>User/groups</p></li><li class="listitem"><p>Attribute storage in user/groups</p></li><li class="listitem"><p>General Permissions</p></li><li class="listitem"><p>Site wide search</p></li><li class="listitem"><p>General Auditing</p></li></ul></div> + +<p>All of these services involve relating extra information and services to +application data objects, examples of which include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bboard messages</p></li><li class="listitem"><p>A user home page</p></li><li class="listitem"><p>A ticket in the Ticket Tracker</p></li><li class="listitem"><p>A photograph in the PhotoDB</p></li></ul></div> + +<p>In the past, developers had to use ad-hoc and inconsistent schemes to interface to the various "general" services mentioned above. Since each service used its own scheme for storing its metadata and mapping this data to application objects, we could not implement any kind of centralized management system or consistent administrative pages for all the services. Consequently, a large amount of duplicate code appeared throughout the system -for dealing with these services.</p><p>Unifying and "normalizing" these interfaces, to minimize the +for dealing with these services.</p> + +<p>Unifying and "normalizing" these interfaces, to minimize the amount of code repetition in applications, is a primary goal of OpenACS 4. Thus the Object Model (OM, also referred to later as the object system) is concerned primarily with the storage and management of <span class="emphasis"><em>metadata</em></span>, on @@ -21,16 +41,30 @@ of the application's data model - in order to enable certain generic services. The term "object" refers to any entity being represented within the OpenACS, and typically corresponds to a single row within the -relational database.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-vision"></a>Vision Statement</h3></div></div></div><p>The OpenACS 4 Object Model must address five high-level requirements that +relational database.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-vision"></a>Vision Statement</h3></div></div></div> + + + +<p>The OpenACS 4 Object Model must address five high-level requirements that repeatedly exhibit themselves in the context of existing services in OpenACS 3.x, -as described below.</p><p><span class="strong"><strong>Object Identifiers for General Services</strong></span></p><p>Generic services require a single unambiguous way of identifying +as described below.</p> + +<p><span class="strong"><strong>Object Identifiers for General Services</strong></span></p> + +<p>Generic services require a single unambiguous way of identifying application objects that they manage or manipulate. In OpenACS 3.x, there are several different idioms that construct object identifiers from other data. Many modules use a <code class="computeroutput">(user_id, group_id, scope)</code> triple combination for the purpose of recording ownership information on objects for access control. User/groups also uses <code class="computeroutput">(user_id, group_id)</code> pairs in its <code class="computeroutput">user_group_map</code> table as a way to identify data associated with a -single membership relation.</p><p>Also in OpenACS 3.x, many utility modules exist that do nothing more than +single membership relation.</p> + +<p>Also in OpenACS 3.x, many utility modules exist that do nothing more than attach some extra attributes to existing application data. For example, general comments maintains a mapping table that maps application "page" data (static or dynamic) to one or more user comments on the @@ -40,31 +74,55 @@ as the "(on_which_table + on_what_id)" method for identifying application data. General comments stores its map from pages to comments using a "(on_which_table + on_what_id)" key, plus the id of the -comment itself.</p><p>All of these composite key constructions are implicit object identifiers: +comment itself.</p> + +<p>All of these composite key constructions are implicit object identifiers: they build a unique ID out of other pieces of the data model. The problem is that their definition and use is ad-hoc and inconsistent. This makes the construction of generic application-independent services difficult. Therefore, the OpenACS 4 Object Model should provide a centralized and uniform -mechanism for tagging application objects with unique identifiers.</p><p><span class="strong"><strong>Support for Unified Access Control</strong></span></p><p>Access control should be as transparent as possible to the application +mechanism for tagging application objects with unique identifiers.</p> + +<p><span class="strong"><strong>Support for Unified Access Control</strong></span></p> + +<p>Access control should be as transparent as possible to the application developer. Until the implementation of the general permissions system, every OpenACS application had to manage access control to its data separately. Later on, a notion of "scoping" was introduced into the core data -model.</p><p>"Scope" is a term best explained by example. Consider some -hypothetical rows in the <code class="computeroutput">address_book</code> table:</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>...</strong></span></td><td><span class="strong"><strong><code class="computeroutput">scope</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">user_id</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">group_id</code></strong></span></td><td><span class="strong"><strong>...</strong></span></td></tr><tr><td>...</td><td><code class="computeroutput">user</code></td><td><code class="computeroutput">123</code></td><td> </td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">group</code></td><td> </td><td><code class="computeroutput">456</code></td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">public</code></td><td> </td><td> </td><td>...</td></tr></tbody></table></div><p>The first row represents an entry in User 123's personal address book, +model.</p> + +<p>"Scope" is a term best explained by example. Consider some +hypothetical rows in the <code class="computeroutput">address_book</code> table:</p> + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>...</strong></span></td><td><span class="strong"><strong><code class="computeroutput">scope</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">user_id</code></strong></span></td><td><span class="strong"><strong><code class="computeroutput">group_id</code></strong></span></td><td><span class="strong"><strong>...</strong></span></td></tr><tr><td>...</td><td><code class="computeroutput">user</code></td><td><code class="computeroutput">123</code></td><td> </td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">group</code></td><td> </td><td><code class="computeroutput">456</code></td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">public</code></td><td> </td><td> </td><td>...</td></tr></tbody></table></div> + +<p>The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address -book.</p><p>In this way, the scoping columns identify the security context in which a +book.</p> + +<p>In this way, the scoping columns identify the security context in which a given object belongs, where each context is <span class="emphasis"><em>either</em></span> a person <span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public (itself a group -of people).</p><p>The problem with this scheme is that we are limited to using only users +of people).</p> + +<p>The problem with this scheme is that we are limited to using only users and groups as scopes for access control, limiting applications to a single level of hierarchy. Worse, the scoping system demanded that every page needing access to a given application had to do an explicit scope check to make sure access was allowed - if a developer was careless on just one site -page, a security problem could result.</p><p>Thus the OpenACS 4 Object Model must support a more general access control +page, a security problem could result.</p> + +<p>Thus the OpenACS 4 Object Model must support a more general access control system that allows access control domains to be hierarchical, and specifiable with a single piece of data, instead of the old composite keys described -above.</p><p><span class="strong"><strong>Extensible Data Models</strong></span></p><p>Another problem with previous OpenACS data models is that many of the central +above.</p> + +<p><span class="strong"><strong>Extensible Data Models</strong></span></p> + +<p>Another problem with previous OpenACS data models is that many of the central tables in the system became bloated as they were extended to support an increasing number of modules. The <code class="computeroutput">users</code> table is the best case in point: it became full of columns that exist for various special @@ -75,34 +133,50 @@ would improve maintainability greatly. Furthermore, the ability to allow applications or users to define new extensions to existing tables, and have some central metadata facility for keeping track of what data belong to which -tables, would be very useful.</p><p>Thus the motivation for providing <span class="emphasis"><em>object types</em></span> and +tables, would be very useful.</p> + +<p>Thus the motivation for providing <span class="emphasis"><em>object types</em></span> and <span class="emphasis"><em>subtyping</em></span> in the OpenACS 4 Object Model. The OM should allow developers to define a hierarchy of metadata <span class="emphasis"><em>object types</em></span> with subtyping and inheritance. Developers can then use the framework to allow users to define custom extensions to the existing data models, and the OM does the bookkeeping necessary to make this easier, providing a generic API for object creation that automatically keeps track of the location and relationships -between data.</p><p><span class="strong"><strong>Design Note:</strong></span> While this doesn't really belong in a +between data.</p> + +<p><span class="strong"><strong>Design Note:</strong></span> While this doesn't really belong in a requirements document, the fact that we are constrained to using relational databases means that certain constraints on the overall design of the object -data model exist, which you can read about in <a class="xref" href="object-system-design.html#object-system-design-summary" title="Summary and Design Considerations">Summary and Design Considerations</a>.</p><p><span class="strong"><strong>Modifiable Data Models</strong></span></p><p>Another recurring applications problem is how to store a modifiable data +data model exist, which you can read about in <a class="xref" href="object-system-design.html#object-system-design-summary" title="Summary and Design Considerations">Summary and Design Considerations</a>.</p> + +<p><span class="strong"><strong>Modifiable Data Models</strong></span></p> + +<p>Another recurring applications problem is how to store a modifiable data model, or how to store information that may change extensively between releases or in different client installations. Furthermore, we want to avoid changes to an application's database queries in the face of any custom extensions, since such changes are difficult or dangerous to make at runtime, and can make updating the system difficult. Some example applications in OpenACS -3.x with modifiable data models include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User/groups: developers and users can attach custom data to group types, +3.x with modifiable data models include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User/groups: developers and users can attach custom data to group types, groups, and members of groups.</p></li><li class="listitem"><p>In the Ecommerce data model, the <code class="computeroutput">ec_custom_product_fields</code> table defines attributes for catalog products, and the <code class="computeroutput">ec_custom_product_field_values</code> table stores values for those attributes.</p></li><li class="listitem"><p>In the PhotoDB data model, the <code class="computeroutput">ph_custom_photo_fields</code> table defines attributes for the photographs owned by a specific user, and tables named according to the convention "<code class="computeroutput">ph_user_<user_id>_custom_info</code>" are used to -store values for those attributes.</p></li></ul></div><p>Thus the Object Model must provide a general mechanism for applications +store values for those attributes.</p></li></ul></div> + +<p>Thus the Object Model must provide a general mechanism for applications and developers to modify or extend data models, without requiring changes to the SQL schema of the system. This ensures that all applications use the same -base schema, resulting in a uniform and more maintainable system.</p><p><span class="strong"><strong>Generic Relations</strong></span></p><p>Many OpenACS applications define simple relationships between application +base schema, resulting in a uniform and more maintainable system.</p> + +<p><span class="strong"><strong>Generic Relations</strong></span></p> + +<p>Many OpenACS applications define simple relationships between application objects, and tag those relationships with extra data. In OpenACS 3.x, this was done using <span class="emphasis"><em>mapping tables</em></span>. The user/groups module has the most highly developed data model for this purpose, using a single table called @@ -115,153 +189,454 @@ historical note, in OpenACS 3.x, user/groups was the only part of the system that provided this kind of data model in a reusable way. Therefore, applications that needed this capability often hooked into user/groups for no other reason -than to use this part of its data model.</p><p>The OpenACS 4 data model must support generic relations by allowing developers +than to use this part of its data model.</p> + +<p>The OpenACS 4 data model must support generic relations by allowing developers to define a special kind of object type called a <span class="emphasis"><em>relation type</em></span>. Relation types are themselves object types that do nothing but represent relations. They can be used by applications that previously used user/groups for the same purpose, but without the extraneous, artificial -dependencies.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-system-overview"></a>System Overview</h3></div></div></div><p>The Object Model package is a combination of data model and a procedural +dependencies.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-system-overview"></a>System Overview</h3></div></div></div> + + + +<p>The Object Model package is a combination of data model and a procedural API for manipulating application objects within an OpenACS instance. The OM allows developers to describe a hierarchical system of <span class="emphasis"><em>object types</em></span> that store metadata on application objects. The object type system supports subtyping with inheritance, so new object types can be defined in terms of -existing object types.</p><p>The OM data model forms the main part of the OpenACS 4 Kernel data model. The -other parts of the Kernel data model include:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Parties and Groups</p></li><li class="listitem"><p>Permissions</p></li></ul></div><p>Each of these is documented elsewhere at length.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div></div><p>(Pending as of 8/27/00)</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-links"></a>Related Links</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="object-system-design.html" title="Object Model Design">OpenACS 4 Object Model Design</a></p></li><li class="listitem"><p><a class="xref" href="objects.html" title="OpenACS Data Models and the Object System">OpenACS Data Models and the Object System</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-data-model"></a>Requirements: Data Model</h3></div></div></div><p>The data model for the object system provides support for the following -kinds of schema patterns that are used by many existing OpenACS modules:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>10.0 Object Identification and Storage</strong></span></span></dt><dd><p>Object identification is a central mechanism in the new metadata system. +existing object types.</p> + +<p>The OM data model forms the main part of the OpenACS 4 Kernel data model. The +other parts of the Kernel data model include:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Parties and Groups</p></li><li class="listitem"><p>Permissions</p></li></ul></div> + +<p>Each of these is documented elsewhere at length.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div></div> + + + +<p>(Pending as of 8/27/00)</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-links"></a>Related Links</h3></div></div></div> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="object-system-design.html" title="Object Model Design">OpenACS 4 Object Model Design</a></p></li><li class="listitem"><p><a class="xref" href="objects.html" title="OpenACS Data Models and the Object System">OpenACS Data Models and the Object System</a></p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-data-model"></a>Requirements: Data Model</h3></div></div></div> + + + +<p>The data model for the object system provides support for the following +kinds of schema patterns that are used by many existing OpenACS modules:</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>10.0 Object Identification and Storage</strong></span></span></dt><dd> + +<p>Object identification is a central mechanism in the new metadata system. The fact that every object has a known unique identifier means that the core can deal with all objects in a generic way. Thus the only action required of an application to obtain any general service is to "hook into" the -object system.</p><p>In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for +object system.</p> + +<p>In OpenACS 3.x, modules use ad-hoc means to construct unique identifiers for objects that they manage. Generally, these unique IDs are built from other IDs that happen to be in the data model. Because there is no consistency in these implementations, every application must hook into every service -separately.</p><p>Examples of utilities that do this in OpenACS 3.x system are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User/groups: Information is attached to group membership relations.</p></li><li class="listitem"><p>General Comments: Comments are attached to objects representing some kind +separately.</p> + +<p>Examples of utilities that do this in OpenACS 3.x system are:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User/groups: Information is attached to group membership relations.</p></li><li class="listitem"><p>General Comments: Comments are attached to objects representing some kind of document.</p></li><li class="listitem"><p>General Permissions: Stores access control information on application data.</p></li><li class="listitem"><p>User Profiling: Maps users to pieces of content that they have looked at; content identifiers must be managed in a uniform way.</p></li><li class="listitem"><p>Site Wide Search: Stores all content in a single flat table, with object identifiers pointing to the object containing the content in the first place. This way, we can search the contents of many different types of objects in a -uniform way.</p></li></ul></div><p>The OM will support and unify this programming idiom by providing objects +uniform way.</p></li></ul></div> + +<p>The OM will support and unify this programming idiom by providing objects with unique identifiers (unique within a given OpenACS instance) and with information about where the application data associated with the object is stored. The identifier can be used to refer to collections of heterogeneous application data. More importantly, object identifiers will enable developers to readily build and use generic services that work globally across a -system.</p><p>The object identifiers should be subject to the following -requirements:</p><p><span class="strong"><strong>10.10 Uniqueness</strong></span></p><p>The object ID should be unique among all the IDs in the entire OpenACS system -in which the object lives.</p><p><span class="strong"><strong>10.20 Useful as a Reference</strong></span></p><p>Applications should be able to use the unique object ID as a reference, -with which they can fetch any or all of the object's attributes.</p><p><span class="strong"><strong>10.30 Storable</strong></span></p><p>Object IDs should be storable in tables. e.g. you should be able to use +system.</p> + +<p>The object identifiers should be subject to the following +requirements:</p> + +<p><span class="strong"><strong>10.10 Uniqueness</strong></span></p> + +<p>The object ID should be unique among all the IDs in the entire OpenACS system +in which the object lives.</p> + +<p><span class="strong"><strong>10.20 Useful as a Reference</strong></span></p> + +<p>Applications should be able to use the unique object ID as a reference, +with which they can fetch any or all of the object's attributes.</p> + +<p><span class="strong"><strong>10.30 Storable</strong></span></p> + +<p>Object IDs should be storable in tables. e.g. you should be able to use them to implement mapping tables between objects, to represent -relationships.</p><p><span class="strong"><strong>10.40 Moveable</strong></span></p><p>Objects should be mobile between databases. That is, information will +relationships.</p> + +<p><span class="strong"><strong>10.40 Moveable</strong></span></p> + +<p>Objects should be mobile between databases. That is, information will often need to be moved between multiple servers (development, staging, and production), so a mechanism for moving this data is necessary. In addition, a mechanism for tagging these objects in a way similar to CVS would be useful -in determining which objects need to be synchronized.</p></dd><dt><span class="term"><span class="strong"><strong>20.0 Object Types</strong></span></span></dt><dd><p>An <span class="emphasis"><em>object type</em></span> refers to a specification of one or more -attributes to be managed along with a piece of application data.</p><p>The object system should provide a data model for describing and +in determining which objects need to be synchronized.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>20.0 Object Types</strong></span></span></dt><dd> + +<p>An <span class="emphasis"><em>object type</em></span> refers to a specification of one or more +attributes to be managed along with a piece of application data.</p> + +<p>The object system should provide a data model for describing and representing object types. This data model is somewhat analogous to the Oracle data dictionary, which stores information about all user defined -tables in the system.</p><p>The canonical example of this kind of data model occurs in the current OpenACS +tables in the system.</p> + +<p>The canonical example of this kind of data model occurs in the current OpenACS 3.x user/groups module, which allows the developer to create new <span class="emphasis"><em>group types</em></span> that can contain not only generic system level attributes but also extended, developer-defined attributes. In addition, these attributes can either be attached to the group type itself, and shared by all instances, or they can be different for each instance. At its core, the OpenACS 4 object system is meant to be a generalization of this mechanism. The data model should allow developers to at least do everything they used to with user/groups, but -without its administrative hassles.</p><p>Therefore, the data model must be able to represent object types that have -the following characteristics:</p><p><span class="strong"><strong>20.10 Type Name</strong></span></p><p>A human readable name for the object type.</p><p><span class="strong"><strong>20.20 Type Attributes</strong></span></p><p>Attributes whose values are shared by all instances of the object -type.</p><p><span class="strong"><strong>20.30 Object Attributes</strong></span></p><p>Attributes that are specific to each particular object belonging to a -given type.</p><p>The data model must also enforce certain constraints on object types:</p><p><span class="strong"><strong>20.40 Type Uniqueness</strong></span></p><p>Object type names must be unique.</p><p><span class="strong"><strong>20.50 Attribute Name Uniqueness</strong></span></p><p>Attribute names must be unique in the scope of a single object type and -any of its parent types.</p></dd><dt><span class="term"><span class="strong"><strong>30.0 Type Extension</strong></span></span></dt><dd><p>The Object Model must support the definition of object types that are +without its administrative hassles.</p> + +<p>Therefore, the data model must be able to represent object types that have +the following characteristics:</p> + + +<p><span class="strong"><strong>20.10 Type Name</strong></span></p> + +<p>A human readable name for the object type.</p> + +<p><span class="strong"><strong>20.20 Type Attributes</strong></span></p> + +<p>Attributes whose values are shared by all instances of the object +type.</p> + +<p><span class="strong"><strong>20.30 Object Attributes</strong></span></p> + +<p>Attributes that are specific to each particular object belonging to a +given type.</p> + +<p>The data model must also enforce certain constraints on object types:</p> + +<p><span class="strong"><strong>20.40 Type Uniqueness</strong></span></p> + +<p>Object type names must be unique.</p> + +<p><span class="strong"><strong>20.50 Attribute Name Uniqueness</strong></span></p> + +<p>Attribute names must be unique in the scope of a single object type and +any of its parent types.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>30.0 Type Extension</strong></span></span></dt><dd> + +<p>The Object Model must support the definition of object types that are subtypes of existing types. A subtype inherits all the attributes of its parent type, and defines some attributes of its own. A critical aspect of the OM is parent types may be altered, and any such change must propagate to -child subtypes.</p><p>The OM data model must enforce constraints on subtypes that are similar to -the ones on general object types.</p><p><span class="strong"><strong>30.10 Subtype Uniqueness</strong></span></p><p>Subtype names must be unique (this parallels requirement 10.40).</p><p><span class="strong"><strong>30.20 Subtype Attribute Name Uniqueness</strong></span></p><p>Attribute names must be unique in the scope of a single object -subtype.</p><p><span class="strong"><strong>30.30 Parent Type Prerequisite</strong></span></p><p>Subtypes must be defined in terms of parent types that, in fact, already -exist.</p><p><span class="strong"><strong>30.40</strong></span></p><p>The extended attribute names in a subtype must not be the same as those in -its parent type.</p></dd><dt><span class="term"><span class="strong"><strong>35.0 Methods</strong></span></span></dt><dd><p><span class="strong"><strong>35.10 Method and Type Association</strong></span></p><p>The OM data model should define a mechanism for associating procedural +child subtypes.</p> + +<p>The OM data model must enforce constraints on subtypes that are similar to +the ones on general object types.</p> + + +<p><span class="strong"><strong>30.10 Subtype Uniqueness</strong></span></p> + +<p>Subtype names must be unique (this parallels requirement 10.40).</p> + +<p><span class="strong"><strong>30.20 Subtype Attribute Name Uniqueness</strong></span></p> + +<p>Attribute names must be unique in the scope of a single object +subtype.</p> + +<p><span class="strong"><strong>30.30 Parent Type Prerequisite</strong></span></p> + +<p>Subtypes must be defined in terms of parent types that, in fact, already +exist.</p> + +<p><span class="strong"><strong>30.40</strong></span></p> + +<p>The extended attribute names in a subtype must not be the same as those in +its parent type.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>35.0 Methods</strong></span></span></dt><dd> + + +<p><span class="strong"><strong>35.10 Method and Type Association</strong></span></p> + +<p>The OM data model should define a mechanism for associating procedural code, called <span class="emphasis"><em>methods</em></span>, with objects of a given type. Methods are associated with the each object <span class="emphasis"><em>type</em></span> - not each object -<span class="emphasis"><em>instance</em></span>.</p><p><span class="strong"><strong>35.20 Method Sharing</strong></span></p><p>All instances of a given object type should share the same set of defined -methods for that type.</p></dd><dt><span class="term"><span class="strong"><strong>40.0 Object Attribute Value Storage</strong></span></span></dt><dd><p>In addition to information on types, the OM data model provides for the +<span class="emphasis"><em>instance</em></span>.</p> + +<p><span class="strong"><strong>35.20 Method Sharing</strong></span></p> + +<p>All instances of a given object type should share the same set of defined +methods for that type.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>40.0 Object Attribute Value Storage</strong></span></span></dt><dd> + +<p>In addition to information on types, the OM data model provides for the centralized storage of object attribute values. This facility unifies the many ad-hoc attribute/value tables that exist in various OpenACS 3.x data models, -such as:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User groups: Each instance of a group type can have custom data.</p></li><li class="listitem"><p>Photo DB: Users can define their own custom metadata to attach to +such as:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>User groups: Each instance of a group type can have custom data.</p></li><li class="listitem"><p>Photo DB: Users can define their own custom metadata to attach to photograph objects.</p></li><li class="listitem"><p>Ecommerce: Vendors can attach custom fields to the data model describing -their products.</p></li></ul></div><p><span class="strong"><strong>40.10 Generic Retrieval</strong></span></p><p>Attributes should be stored so that they are retrievable in a way that is +their products.</p></li></ul></div> + + +<p><span class="strong"><strong>40.10 Generic Retrieval</strong></span></p> + +<p>Attributes should be stored so that they are retrievable in a way that is independent of the type of the object that they belong to. That is, the only data needed to retrieve an attribute should be the system-wide ID of an -object (see requirement 10.20 above) and the attribute name.</p><p><span class="strong"><strong>40.20 Inherited Attributes</strong></span></p><p>The system should allow for the automatic retrieval of inherited attribute -values, for an object belonging to a subtype.</p><p><span class="strong"><strong>40.30. Constraints on Attributes</strong></span></p><p>The system should allow the developer to put down constraints on the +object (see requirement 10.20 above) and the attribute name.</p> + +<p><span class="strong"><strong>40.20 Inherited Attributes</strong></span></p> + +<p>The system should allow for the automatic retrieval of inherited attribute +values, for an object belonging to a subtype.</p> + +<p><span class="strong"><strong>40.30. Constraints on Attributes</strong></span></p> + +<p>The system should allow the developer to put down constraints on the values that an attribute may hold, for the purposes of maintaining -application specific integrity rules.</p></dd><dt><span class="term"><span class="strong"><strong>50.0 Object Contexts</strong></span></span></dt><dd><p>In OpenACS 3.x, there was a notion of "scope" for application +application specific integrity rules.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>50.0 Object Contexts</strong></span></span></dt><dd> + +<p>In OpenACS 3.x, there was a notion of "scope" for application objects. An object could be belong to one of three scopes: public, group or user. This provided a crude way to associate objects with particular scopes -in the system, but it was awkward to use and limited in flexibility.</p><p>The OpenACS 4 Object Model provides a generalized notion of scope that allows +in the system, but it was awkward to use and limited in flexibility.</p> + +<p>The OpenACS 4 Object Model provides a generalized notion of scope that allows developers to represent a hierarchy of object <span class="emphasis"><em>contexts</em></span>. These contexts are used as the basis for the permissions system. In general, if an object has no explicit permissions attached to it, then it inherits -permissions from its context.</p><p>The context data model also forms the basis of the <a class="link" href="subsites-requirements.html" title="Subsites Requirements">subsites system</a>, and is +permissions from its context.</p> + +<p>The context data model also forms the basis of the <a class="link" href="subsites-requirements.html" title="Subsites Requirements">subsites system</a>, and is a basic part of the <a class="link" href="permissions-requirements.html" title="Permissions Requirements">permissions system</a>, -described in separate documents.</p><p>The context data model should provide the following facilities:</p><p><span class="strong"><strong>50.10 Unique ID</strong></span></p><p>Every context should have a unique ID in the system.</p><p><span class="strong"><strong>50.20 Tree Structure</strong></span></p><p>The data model should support a tree structured organization of contexts. +described in separate documents.</p> + +<p>The context data model should provide the following facilities:</p> + + +<p><span class="strong"><strong>50.10 Unique ID</strong></span></p> + +<p>Every context should have a unique ID in the system.</p> + +<p><span class="strong"><strong>50.20 Tree Structure</strong></span></p> + +<p>The data model should support a tree structured organization of contexts. That is, contexts can be logically "contained" within other contexts (i.e. contexts have parents) and contexts can contain other contexts -(i.e. contexts can have children).</p><p><span class="strong"><strong>50.30 Data Model Constraints</strong></span></p><p>All objects must have a context ID. This ID must refer to an existing +(i.e. contexts can have children).</p> + +<p><span class="strong"><strong>50.30 Data Model Constraints</strong></span></p> + +<p>All objects must have a context ID. This ID must refer to an existing context or be NULL. The meaning of a NULL context is determined by the -implementation.</p><p><span class="strong"><strong>Note:</strong></span></p><p>The current system interprets the NULL context as meaning the default +implementation.</p> + +<p><span class="strong"><strong>Note:</strong></span></p> + +<p>The current system interprets the NULL context as meaning the default "site-wide" context in some sense. I wanted to note this fact for others, but there is no need to make this a requirement of the system. I think it would be reasonable to have a NULL context be an error (psu -8/24/2000).</p></dd><dt><span class="term"><span class="strong"><strong>55.0 Object Relations</strong></span></span></dt><dd><p>The data model should include a notion of pair-wise relations between +8/24/2000).</p> + + +</dd><dt><span class="term"><span class="strong"><strong>55.0 Object Relations</strong></span></span></dt><dd> + +<p>The data model should include a notion of pair-wise relations between objects. Relations should be able to record simple facts of the form "object X is related to object Y by relationship R," and also be -able to attach attributes to these facts.</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-api"></a>Requirements: API</h3></div></div></div><p>The API should let programmers accomplish the following actions:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>60.0 Object Type Creation</strong></span></span></dt><dd><p><span class="strong"><strong>60.10 Create a New Object Type</strong></span></p><p>The object system API should provide a procedure call that creates a new +able to attach attributes to these facts.</p> +</dd></dl></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-api"></a>Requirements: API</h3></div></div></div> + + + +<p>The API should let programmers accomplish the following actions:</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><span class="strong"><strong>60.0 Object Type Creation</strong></span></span></dt><dd> + + +<p><span class="strong"><strong>60.10 Create a New Object Type</strong></span></p> + +<p>The object system API should provide a procedure call that creates a new object type by running the appropriate transactions on the object system data model. This API call is subject to the constraints laid out in the data -model. We call this operation "instantiating" an object.</p><p><span class="strong"><strong>60.20 Create a New Object Subtype</strong></span></p><p>The object system API should provide a procedure call for creating +model. We call this operation "instantiating" an object.</p> + +<p><span class="strong"><strong>60.20 Create a New Object Subtype</strong></span></p> + +<p>The object system API should provide a procedure call for creating subtypes of a given type. Operationally, this API is the same as requirement 60.10. Instances of subtypes automatically contain all attributes of the parent type in addition to all attributes of the subtype. This API is subject -to the constraints laid out in the data model.</p><p><span class="strong"><strong>60.30 Create a New Relation Type</strong></span></p><p>There should be an API call to create a new type of object relation. +to the constraints laid out in the data model.</p> + +<p><span class="strong"><strong>60.30 Create a New Relation Type</strong></span></p> + +<p>There should be an API call to create a new type of object relation. Relation types can be modeled as object types. The API below for manipulating -attributes can then be used to add attributes to relation types.</p></dd><dt><span class="term"><span class="strong"><strong>70.0 Update an Object Type</strong></span></span></dt><dd><p>The object system API must allow the programmer to modify, add, and delete +attributes can then be used to add attributes to relation types.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>70.0 Update an Object Type</strong></span></span></dt><dd> + +<p>The object system API must allow the programmer to modify, add, and delete attributes from any object type. Updates should be propagated to any child subtypes. This API is subject to the constraints laid out in the data -model.</p></dd><dt><span class="term"><span class="strong"><strong>80.0 Delete an Object Type</strong></span></span></dt><dd><p>The system provides an API call for deleting an object type.</p><p><span class="strong"><strong>80.10</strong></span></p><p>Deleting an object type destroys all instances of the type. It should be +model.</p> + +</dd><dt><span class="term"><span class="strong"><strong>80.0 Delete an Object Type</strong></span></span></dt><dd> + +<p>The system provides an API call for deleting an object type.</p> + + +<p><span class="strong"><strong>80.10</strong></span></p> + +<p>Deleting an object type destroys all instances of the type. It should be an error to delete types that have dependent subtypes. This API is subject to -the constraints laid out in the data model.</p><p><span class="strong"><strong>80.10.10</strong></span></p><p>However, the programmer should also be able to specify that all the +the constraints laid out in the data model.</p> + +<p><span class="strong"><strong>80.10.10</strong></span></p> + +<p>However, the programmer should also be able to specify that all the subtypes and instances of those subtypes be destroyed before destroying the object type. This is similar to a "delete cascade" constraint in -SQL.</p></dd><dt><span class="term"><span class="strong"><strong>90.0 Object Instance Creation and Destruction</strong></span></span></dt><dd><p>The system must provide API calls to manage the creation and destruction -of object instances.</p><p><span class="strong"><strong>90.10 Create an Instance of an Object Type</strong></span></p><p>The system should provide an API call for creating a new instance of a +SQL.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>90.0 Object Instance Creation and Destruction</strong></span></span></dt><dd> + +<p>The system must provide API calls to manage the creation and destruction +of object instances.</p> + + +<p><span class="strong"><strong>90.10 Create an Instance of an Object Type</strong></span></p> + +<p>The system should provide an API call for creating a new instance of a given object type. The new instance should be populated with values for each of the attributes specified in the definition of the type. In addition, it should be possible to create the new instance with an optional context ID -that refers to the default context that the object will live in.</p><p><span class="strong"><strong>90.20 Delete an Object Instance</strong></span></p><p>The OM should provide an API call for object deletion. Objects can be +that refers to the default context that the object will live in.</p> + +<p><span class="strong"><strong>90.20 Delete an Object Instance</strong></span></p> + +<p>The OM should provide an API call for object deletion. Objects can be deleted only when no other objects in the system refer to them. Since it might not be practical to provide a mechanism like "delete cascade" here in a reliable way, providing such a facility in the system is -optional.</p></dd><dt><span class="term"><span class="strong"><strong>94.0 Object Relation Creation and Destruction</strong></span></span></dt><dd><p>The system must provide API calls to manage the creation and destruction -of object relations.</p></dd><dt><span class="term"><span class="strong"><strong>94.10 Create an Object Relation</strong></span></span></dt><dd><p>The OM must provide an API call to declare that two objects are related to +optional.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>94.0 Object Relation Creation and Destruction</strong></span></span></dt><dd> + +<p>The system must provide API calls to manage the creation and destruction +of object relations.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>94.10 Create an Object Relation</strong></span></span></dt><dd> + +<p>The OM must provide an API call to declare that two objects are related to each other by a given relation type. This API call should also allow -programmers to attach attributes to this object relation.</p></dd><dt><span class="term"><span class="strong"><strong>94.20 Destroy an Object Relation</strong></span></span></dt><dd><p>There should be an API call for destroying object relations and their -attributes.</p></dd><dt><span class="term"><span class="strong"><strong>95.10 Create and Destroy Contexts</strong></span></span></dt><dd><p>The system should provide an API to create and destroy object -contexts.</p></dd><dt><span class="term"><span class="strong"><strong>100.10 Set Attribute Values for an Object</strong></span></span></dt><dd><p>The system should provide an API for updating the attribute values of a -particular instance of an object type.</p></dd><dt><span class="term"><span class="strong"><strong>110.10 Get Attribute Values for an Object</strong></span></span></dt><dd><p>The system should provide an API for retrieving attribute values from a -particular instance of an object type.</p></dd><dt><span class="term"><span class="strong"><strong>120.10 Efficiency</strong></span></span></dt><dd><p>The Object Model must support the efficient storage and retrieval of +programmers to attach attributes to this object relation.</p> + +</dd><dt><span class="term"><span class="strong"><strong>94.20 Destroy an Object Relation</strong></span></span></dt><dd> + +<p>There should be an API call for destroying object relations and their +attributes.</p> + + +</dd><dt><span class="term"><span class="strong"><strong>95.10 Create and Destroy Contexts</strong></span></span></dt><dd> + +<p>The system should provide an API to create and destroy object +contexts.</p> + +</dd><dt><span class="term"><span class="strong"><strong>100.10 Set Attribute Values for an Object</strong></span></span></dt><dd> + +<p>The system should provide an API for updating the attribute values of a +particular instance of an object type.</p> + +</dd><dt><span class="term"><span class="strong"><strong>110.10 Get Attribute Values for an Object</strong></span></span></dt><dd> + +<p>The system should provide an API for retrieving attribute values from a +particular instance of an object type.</p> + +</dd><dt><span class="term"><span class="strong"><strong>120.10 Efficiency</strong></span></span></dt><dd> + +<p>The Object Model must support the efficient storage and retrieval of object attributes. Since the OM is intended to form the core of many general services in the OpenACS, and these services will likely make extensive use of the OM tables, queries on these tables must be fast. The major problem here seems to be supporting subtyping and inheritance in a way that does not severely -impact query performance.</p></dd><dt><span class="term"><span class="strong"><strong>130.10 Ease of Use</strong></span></span></dt><dd><p>Most OpenACS packages will be expected to use the Object Model in one way or +impact query performance.</p> + +</dd><dt><span class="term"><span class="strong"><strong>130.10 Ease of Use</strong></span></span></dt><dd> + +<p>Most OpenACS packages will be expected to use the Object Model in one way or another. Since it is important that the largest audience of developers possible adopts and uses the OM, it must be easy to incorporate into applications, and it must not impose undue requirements on an application's data model. In other words, it should be easy to "hook into" the object model, and that ability should not have a major impact -on the application data model.</p><p><span class="strong"><strong>Note:</strong></span> Is the API the only way to obtain values? How does -this integrate with application level SQL queries?</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/10/2000</td><td>Bryan Quinn</td></tr><tr><td>0.2</td><td>Major re-write</td><td>08/11/2000</td><td>Pete Su</td></tr><tr><td>0.3</td><td>Draft completed after initial reviews</td><td>08/22/2000</td><td>Pete Su</td></tr><tr><td>0.4</td><td>Edited, updated to conform to requirements template, pending freeze</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td> </td><td>Final edits before freeze</td><td>08/24/2000</td><td>Pete Su</td></tr><tr><td>0.5</td><td>Edited for consistency</td><td>08/27/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>Put Object ID stuff first, because it makes more sense</td><td>08/28/2000</td><td>Pete Su</td></tr><tr><td>0.7</td><td>Added requirement that knowledge-level objects must be moveable between +on the application data model.</p> + +<p><span class="strong"><strong>Note:</strong></span> Is the API the only way to obtain values? How does +this integrate with application level SQL queries?</p> +</dd></dl></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="object-system-requirements-history"></a>Revision History</h3></div></div></div> + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/10/2000</td><td>Bryan Quinn</td></tr><tr><td>0.2</td><td>Major re-write</td><td>08/11/2000</td><td>Pete Su</td></tr><tr><td>0.3</td><td>Draft completed after initial reviews</td><td>08/22/2000</td><td>Pete Su</td></tr><tr><td>0.4</td><td>Edited, updated to conform to requirements template, pending freeze</td><td>08/23/2000</td><td>Kai Wu</td></tr><tr><td> </td><td>Final edits before freeze</td><td>08/24/2000</td><td>Pete Su</td></tr><tr><td>0.5</td><td>Edited for consistency</td><td>08/27/2000</td><td>Kai Wu</td></tr><tr><td>0.6</td><td>Put Object ID stuff first, because it makes more sense</td><td>08/28/2000</td><td>Pete Su</td></tr><tr><td>0.7</td><td>Added requirement that knowledge-level objects must be moveable between databases.</td><td>08/29/2000</td><td>Richard Li</td></tr><tr><td>0.8</td><td>Rewrote intro to match language and concepts in the design document. Also cleaned up usage a bit in the requirements section. Added short vague -requirements on relation types.</td><td>09/06/2000</td><td>Pete Su</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release.</td><td>09/30/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Object Model Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +requirements on relation types.</td><td>09/06/2000</td><td>Pete Su</td></tr><tr><td>0.9</td><td>Edited for ACS 4 Beta release.</td><td>09/30/2000</td><td>Kai Wu</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="kernel-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-system-design.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Object Model Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/objects.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/objects.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/objects.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="request-processor" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="objects" id="objects"></a>OpenACS Data Models and the Object System</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="objects" id="objects"></a>OpenACS Data Models and the Object System</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="objects-overview" id="objects-overview"></a>Overview</h3></div></div></div><p>Developing data models in OpenACS 5.9.0 is much like developing data models for OpenACS 3, save for the implementation. As usual, @@ -86,7 +83,7 @@ for the PG version) file created when we <a class="link" href="packages" title="OpenACS Packages">created the package</a>. Then, do the following:</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592100229608" id="idp140592100229608"></a>Describe the new type to the type +<a name="idp140623171536888" id="idp140623171536888"></a>Describe the new type to the type system</h4></div></div></div><p>First, add an entry to the <code class="computeroutput">acs_object_types</code> table with the following PL/SQL call:</p><pre class="programlisting"> begin @@ -142,7 +139,7 @@ attributes, so there is no need for us to define them.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592105765448" id="idp140592105765448"></a>Define a table in which to store your +<a name="idp140623171519720" id="idp140623171519720"></a>Define a table in which to store your objects</h4></div></div></div><p>The next thing we do is make a small modification to the data model to reflect the fact that each row in the <code class="computeroutput">notes</code> table represents something that is not only an object of type <code class="computeroutput">note</code>, but also an <code class="computeroutput">acs_object</code>. The new table definition looks @@ -166,7 +163,7 @@ <code class="computeroutput">acs_objects</code>.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592105775736" id="idp140592105775736"></a>Define a package for type specific +<a name="idp140623171394616" id="idp140623171394616"></a>Define a package for type specific procedures</h4></div></div></div><p>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:</p><pre class="programlisting"> @@ -213,7 +210,7 @@ only" by default. We'll talk about this more later.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592105783448" id="idp140592105783448"></a>Define a package body for type specific +<a name="idp140623171402712" id="idp140623171402712"></a>Define a package body for type specific procedures</h4></div></div></div><p>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 <code class="computeroutput">acs_object.new</code> @@ -365,8 +362,8 @@ <code class="computeroutput">acs_objects</code>. This means you should never use the fields in <code class="computeroutput">acs_objects</code> for application-specific purposes. This is especially true for the <code class="computeroutput">context_id</code> field.</p></li> -</ul></div><div class="cvstag">($‌Id: objects.xml,v 1.9.14.1 2016/06/23 -08:32:46 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: objects.xml,v 1.10 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/objects.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/objects.html,v diff -u -r1.53 -r1.54 --- openacs-4/packages/acs-core-docs/www/objects.html 7 Aug 2017 23:47:51 -0000 1.53 +++ openacs-4/packages/acs-core-docs/www/objects.html 8 Nov 2017 09:42:11 -0000 1.54 @@ -1,16 +1,25 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Data Models and the Object System</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="packages.html" title="OpenACS Packages"><link rel="next" href="request-processor.html" title="The Request Processor"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="objects"></a>OpenACS Data Models and the Object System</h2></div></div></div><div class="authorblurb"><p>By Pete Su</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-overview"></a>Overview</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Data Models and the Object System</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="packages.html" title="OpenACS Packages"><link rel="next" href="request-processor.html" title="The Request Processor"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="objects"></a>OpenACS Data Models and the Object System</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By Pete Su</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-overview"></a>Overview</h3></div></div></div> + +<p> Developing data models in OpenACS 5.9.0 is much like developing data models for OpenACS 3, save for the implementation. As usual, you need to examine how to model the information that the application must store and manipulate, and define a suitable set of SQL tables. In our Notes application, we have to be able to keep track of who entered a particular note, when they did it, and the actual text of the notes that users have entered. A simple data model might look like this: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> create table notes ( note_id integer primary key, owner_id integer references users(user_id), @@ -20,12 +29,21 @@ title varchar(255) not null, body varchar(1024) ) -</pre><p> +</pre> + + +<p> We've omitted constraint names for the purpose of clarity. -</p><p> +</p> + +<p> Thinking further ahead, we can imagine doing any of the following things with Notes as well: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: opencircle; "><li class="listitem" style="list-style-type: circle"><p>Define access control policies on notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Attach user comments on notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Allow users to define custom fields to store on their notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Automatically generate input forms or output displays for notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Allow other applications to use notes in ways we don't know of yet.</p></li></ul></div><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: opencircle; "><li class="listitem" style="list-style-type: circle"><p>Define access control policies on notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Attach user comments on notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Allow users to define custom fields to store on their notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Automatically generate input forms or output displays for notes.</p></li><li class="listitem" style="list-style-type: circle"><p>Allow other applications to use notes in ways we don't know of yet.</p></li></ul></div> + +<p> In OpenACS, the key to enabling these types of services on your application data is to take advantage of the Object System. The first question, then, is "Just what are objects, and what do @@ -37,7 +55,9 @@ table defines all the standard attributes that are stored on every object, including its system-wide unique ID, object type, and some generic auditing columns. -</p><p> +</p> + +<p> To make use of the object system, you as the application developer have to write your data model in a way that is slightly more complex than in the ACS 3.x days. What you get for this extra work includes: @@ -52,10 +72,18 @@ object and forget about it.</p></li><li class="listitem"><p>And most importantly, any future object-level service - from a general-comments replacement to personalized ranking - will become available to your application "for free."</p></li></ul></div><p> -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-how-to-use"></a>How to Use Objects</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-how-to-use"></a>How to Use Objects</h3></div></div></div> + +<p> Using ACS objects is straightforward: all that's required are a few extra steps in the design of your application data model. -</p><p> +</p> + +<p> In order to hook our Notes application into the object system, we make some calls to use our <code class="computeroutput">notes</code> table as the basis for a new <span class="emphasis"><em>object type</em></span>. Object types are analogous to classes in @@ -64,7 +92,9 @@ that run code. In OpenACS, we use one or more database tables to store the data attributes, and we define a stored procedure package to hold procedures to define the programming interface to the data model. -</p><p> +</p> + +<p> The object type itself is described using data in the <code class="computeroutput">acs_object_types</code> and <code class="computeroutput">acs_attributes</code> tables, which play a role @@ -75,13 +105,25 @@ keep everything consistent. Below you'll find the code needed to describe a new object type called <code class="computeroutput">notes</code> in your system. -</p><p> +</p> + +<p> Fire up your text editor and open the <code class="computeroutput">ROOT/packages/notes/sql/oracle/notes-create.sql</code> (<code class="computeroutput">ROOT/packages/notes/sql/postgresql/notes-create.sql</code> for the PG version) file created when we <a class="link" href="packages.html" title="OpenACS Packages">created the package</a>. Then, do the following: -</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592100229608"></a>Describe the new type to the type system</h4></div></div></div><p> +</p> + + + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623171536888"></a>Describe the new type to the type system</h4></div></div></div> + + + +<p> First, add an entry to the <code class="computeroutput">acs_object_types</code> table with the following PL/SQL call: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> begin acs_object_type.create_type ( supertype => 'acs_object', @@ -94,7 +136,9 @@ end; / show errors; -</pre><p> +</pre> + +<p> This PL/SQL call tells the system that we would like to use the table <code class="computeroutput">NOTES</code> as the basis for a new object type called <code class="computeroutput">note</code>. This type is a subtype of the @@ -103,13 +147,17 @@ some work on our part to make this happen, since Oracle can't do it automatically. In general, most basic applications will define types that are simple subtypes of <code class="computeroutput">acs_object</code>. -</p><p> +</p> + +<p> Add entries to the <code class="computeroutput">acs_attributes</code> table to describe the data attributes of the new type. This data can eventually be used to do things like automatically generate user interfaces to manipulate the <code class="computeroutput">notes</code> table, though that functionality isn't yet available. -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> declare attr_id acs_attributes.attribute_id%TYPE; begin @@ -131,28 +179,44 @@ end; / show errors; -</pre><p> +</pre> + +<p> We can stop here and not bother to register the usual OpenACS 3.x attributes of <code class="computeroutput">creation_user</code>, <code class="computeroutput">creation_date</code> and <code class="computeroutput">last_modified</code>, since the object type <code class="computeroutput">acs_object</code> already defines these attributes. Again, because the new type <code class="computeroutput">note</code> is a subtype of <code class="computeroutput">acs_object</code>, it will inherit these attributes, so there is no need for us to define them. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592105765448"></a>Define a table in which to store your objects</h4></div></div></div><p> +</p> + + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623171519720"></a>Define a table in which to store your objects</h4></div></div></div> + + +<p> The next thing we do is make a small modification to the data model to reflect the fact that each row in the <code class="computeroutput">notes</code> table represents something that is not only an object of type <code class="computeroutput">note</code>, but also an <code class="computeroutput">acs_object</code>. The new table definition looks like this: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> create table notes ( note_id integer references acs_objects(object_id) primary key, owner_id integer references users(user_id), title varchar(255) not null, body varchar(1024) ) -</pre><p> +</pre> + + +<p> The usual <code class="computeroutput">creation_date</code> and <code class="computeroutput">modified_date</code> columns are absent since they already exist in <code class="computeroutput">acs_objects</code>. Also, note the constraint we have added @@ -164,11 +228,21 @@ use the <code class="computeroutput">acs_objects</code> table to find objects will transparently find any objects that are instances of any subtype of <code class="computeroutput">acs_objects</code>. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592105775736"></a>Define a package for type specific procedures</h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623171394616"></a>Define a package for type specific procedures</h4></div></div></div> + + +<p> 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: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> create or replace package note as function new ( @@ -191,7 +265,10 @@ end note; / show errors -</pre><p> +</pre> + + +<p> You might be wondering what all the extra parameters are to these calls, since we haven't mentioned them before. These parameters are needed to fill out information that will be stored about the object @@ -202,7 +279,9 @@ self-explanatory and reflects attributes that existed in the earlier OpenACS 3.x data models, with the exception of the <code class="computeroutput">context_id</code> attribute. -</p><p> +</p> + +<p> The <code class="computeroutput">context_id</code> attribute stores the ID of an object that represents the default security domain to which the object belongs. It is used by the <a class="link" href="permissions.html" title="Groups, Context, Permissions">permissions</a> system in @@ -212,15 +291,24 @@ 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. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592105783448"></a>Define a package body for type specific procedures</h4></div></div></div><p> +</p> +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623171402712"></a>Define a package body for type specific procedures</h4></div></div></div> + + +<p> 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 <code class="computeroutput">acs_object.new</code> to insert a row into <code class="computeroutput">acs_objects</code>, before inserting a row into the <code class="computeroutput">notes</code>. Similarly, when we delete a row from <code class="computeroutput">note</code>, we have to be sure to delete the corresponding <code class="computeroutput">acs_object</code> row. -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> create or replace package body note as @@ -271,17 +359,24 @@ end note; / show errors; -</pre><p> +</pre> + +<p> That's pretty much it! As long as you use the <code class="computeroutput">note.new</code> function to create notes, and the <code class="computeroutput">note.delete</code> function to delete them, you'll be assured that the relationship each <code class="computeroutput">note</code> has with its corresponding <code class="computeroutput">acs_object</code> is preserved. -</p><p> +</p> + +<p> The last thing to do is to make a file <code class="computeroutput">ROOT/packages/notes/sql/notes-drop.sql</code> so it's easy to drop the data model when, say, you're testing: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> begin acs_object_type.drop_type ('note'); end; @@ -290,31 +385,56 @@ drop package note; drop table notes; -</pre></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-when-to-use-objects"></a>When to Use Objects</h3></div></div></div><p> +</pre> + + + +</div> + + +</div> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-when-to-use-objects"></a>When to Use Objects</h3></div></div></div> + +<p> While it is hard to give general design advice without knowing anything about a particular application, you should follow the following rule of thumb when deciding when to hook part of your data model to the object system: -</p><p> +</p> + +<p> Anything in your data model that needs to be available to general OpenACS services such as user comments, permissions, and so on should be a subtype of <code class="computeroutput">acs_object</code>. In addition, if you want your data model to take advantage of attributes that exist in some object type that is a subtype of <code class="computeroutput">acs_object</code>, then you should use the object system. -</p><p> +</p> + +<p> For example, for most applications, you will want to use objects to represent the data in your application that is user visible and thus requires access control. But other internal tables, views, mapping tables and so on probably don't need to be objects. As before, this kind of design decision is mostly made on an application-by-application basis, but this is a good baseline from which to start. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-design-guidance"></a>Design Guidance</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-design-guidance"></a>Design Guidance</h3></div></div></div> + +<p> In this section we cover some overall guidelines for designing data models that are meant to be integrated with the OpenACS object system. -</p><p> +</p> + +<p> There are two basic rules you should follow when designing OpenACS 5.9.0 data models: @@ -332,7 +452,9 @@ a very specific purpose by the permissions system, and using this field in <span class="emphasis"><em>any other way whatsoever</em></span> is guaranteed to make your application act strangely. -</p><p> +</p> + +<p> As we'll see later, the Notes example will point each note object's <code class="computeroutput">context_id</code> to the package instance in which the note was created. The idea will be that in a real site, the administrator would @@ -353,11 +475,15 @@ semantics of the data model are no longer independent of the application. This would make it impossible to build the generic tools that the data model is trying to support. -</p><p> +</p> + +<p> Another less important reason for these two rules is to not introduce any joins against the <code class="computeroutput">acs_objects</code> table in SQL queries in your application that you do not absolutely need. -</p><p> +</p> + +<p> In the Notes example, the result of applying these rules is that we are careful to define our own attribute for <code class="computeroutput">owner_id</code> rather than overloading <code class="computeroutput">creation_user</code> from the objects @@ -369,7 +495,13 @@ when to use inherited attributes is fairly straightforward, but requires a good amount of thought at design time even for simple applications. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-summary"></a>Summary</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="objects-summary"></a>Summary</h3></div></div></div> + +<p> Hooking into the OpenACS 5.9.0 object system brings the application developer numerous benefits, and doing it involves only four easy steps: @@ -394,4 +526,12 @@ especially true for the <code class="computeroutput">context_id</code> field. </p></li></ul></div><p> -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Packages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The Request Processor</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="packages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="request-processor.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Packages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The Request Processor</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/openacs-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-overview.html,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/openacs-overview.html 7 Aug 2017 23:47:51 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/openacs-overview.html 8 Nov 2017 09:42:11 -0000 1.31 @@ -1,20 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="previous" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="next" href="release-notes.html" title="OpenACS Release Notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs-overview"></a>Overview</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="previous" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="next" href="release-notes.html" title="OpenACS Release Notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs-overview"></a>Overview</h2></div></div></div> + + <p> OpenACS (Open Architecture Community System) is an advanced toolkit for building scalable, community-oriented web applications. If you're thinking of building an enterprise-level web application, OpenACS is a solid, scalable framework for building dynamic content driven sites. - </p><p> + </p> + + <p> OpenACS is a collection of pre-built applications and services that you can use to build your web site/application. Through a modular architecture, OpenACS has packages for user/groups management, content management, e-commerce, news, FAQs, calendar, forums, bug tracking, full-text searching, and <a class="ulink" href="http://openacs.org/packages/" target="_top">much more</a>. - </p><p> + </p> + + + <p> OpenACS relies on <a class="ulink" href="http://www.aolserver.com/" target="_top">AOLserver</a>, the free, multithreaded, scalable, Tcl-enabled, web/application server used by America Online for most of @@ -23,19 +30,25 @@ supports PostgreSQL, an open source RDBMS, and Oracle and is easily extensible to other databases which support a comparable feature set. - </p><p> + </p> + + <p> The OpenACS toolkit is derived from the ArsDigita Community System (ACS). ArsDigita (now part of Red Hat, Inc.) kindly made their work available under the <a class="ulink" href="http://www.gnu.org/licenses/gpl.txt" target="_top">GPL</a>, making all of this possible. - </p><p> + </p> + + <p> The OpenACS project was born when Don Baccus, Ben Adida, and others decided to port ACS from Oracle to PostgreSQL, thus making it a fully open-source solution. With OpenACS 4, Oracle and PostgreSQL support were combined in one code base and with OpenACS 5, support for internationalization and localization has been added. - </p><p> + </p> + + <p> A vibrant and productive community has sprung up around the OpenACS software and there are many volunteer contributors as well as a commercial companies able to provide support, @@ -44,9 +57,12 @@ project. Formal, consensus driven governance has been established (with semi-annual elections) which ensures the project serves the needs of it's constituents. - </p><p> + </p> + + <p> The OpenACS community would like to hear your comments and can help you in your endeavors with the system. Visit our <a class="ulink" href="http://openacs.org/" target="_top">web site</a> and feel free to <a class="ulink" href="http://openacs.org/forums/" target="_top">ask questions or provide feedback</a>. - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 1. High level information: What is OpenACS? </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> OpenACS Release Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="general-documents.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="release-notes.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 1. High level information: What is OpenACS? </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> OpenACS Release Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/openacs-unpack.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/openacs-unpack.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -14,8 +14,8 @@ of the packages listed below. In order to access those files, unpack the tarball now.</p><pre class="screen"> [root root]# <strong class="userinput"><code>cd /tmp</code></strong> -[root tmp]# <strong class="userinput"><code>tar xzf openacs-5.9.0.tgz</code></strong><span class="action"><span class="action">cd /tmp -tar xzf openacs-5.9.0.tgz</span></span> +[root tmp]# <strong class="userinput"><code>tar xzf openacs-5.9.0.tgz</code></strong><span class="action">cd /tmp +tar xzf openacs-5.9.0.tgz</span> </pre><p>If you are installing from a different method and just need the configuration files, you can instead get them from CVS:</p><pre class="screen"> [root root]# <strong class="userinput"><code>cd /tmp</code></strong> @@ -26,9 +26,9 @@ <span class="emphasis"><em>(many lines omitted)</em></span> U openacs-4/packages/acs-core-docs/www/files/template-ini.ini U openacs-4/packages/acs-core-docs/www/files/winnsd.txt -[root tmp]# <strong class="userinput"><code>mv openacs-4 openacs-5.9.0</code></strong><span class="action"><span class="action">cd /tmp +[root tmp]# <strong class="userinput"><code>mv openacs-4 openacs-5.9.0</code></strong><span class="action">cd /tmp cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ -mv openacs-4 openacs-5.0.0a4</span></span> +mv openacs-4 openacs-5.0.0a4</span> </pre> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/openacs-unpack.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs-unpack.html,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/openacs-unpack.html 7 Aug 2017 23:47:51 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/openacs-unpack.html 8 Nov 2017 09:42:11 -0000 1.31 @@ -1,10 +1,15 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Unpack the OpenACS tarball</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="next" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs-unpack"></a>Unpack the OpenACS tarball</h2></div></div></div><p>The OpenACS tarball contains sample configuration files +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Unpack the OpenACS tarball</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="next" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs-unpack"></a>Unpack the OpenACS tarball</h2></div></div></div> + + <p>The OpenACS tarball contains sample configuration files for some of the packages listed below. In order to access those - files, unpack the tarball now.</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /tmp</code></strong> + files, unpack the tarball now.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>cd /tmp</code></strong> [root tmp]# <strong class="userinput"><code>tar xzf openacs-5.9.0.tgz</code></strong> -<span class="action"><span class="action">cd /tmp -tar xzf openacs-5.9.0.tgz</span></span></pre><p>If you are installing from a different method and just need the configuration files, you can instead get them from CVS:</p><pre class="screen">[root root]# <strong class="userinput"><code>cd /tmp</code></strong> +<span class="action">cd /tmp +tar xzf openacs-5.9.0.tgz</span></pre> + <p>If you are installing from a different method and just need the configuration files, you can instead get them from CVS:</p> +<pre class="screen">[root root]# <strong class="userinput"><code>cd /tmp</code></strong> [root tmp]# <strong class="userinput"><code>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/</code></strong> cvs checkout: warning: failed to open /root/.cvspass for reading: No such file or directory cvs server: Updating openacs-4/packages/acs-core-docs/www/files @@ -13,6 +18,7 @@ U openacs-4/packages/acs-core-docs/www/files/template-ini.ini U openacs-4/packages/acs-core-docs/www/files/winnsd.txt [root tmp]# <strong class="userinput"><code>mv openacs-4 openacs-5.9.0</code></strong> -<span class="action"><span class="action">cd /tmp +<span class="action">cd /tmp cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co openacs-4/packages/acs-core-docs/www/files/ -mv openacs-4 openacs-5.0.0a4</span></span></pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix B. Install additional supporting software </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Initialize CVS (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +mv openacs-4 openacs-5.0.0a4</span></pre> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-more-software.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Appendix B. Install additional supporting software </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Initialize CVS (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/openacs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/openacs.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/openacs.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="win2k-installation" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="openacs" id="openacs"></a>Install OpenACS 5.9.0</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="openacs" id="openacs"></a>Install OpenACS 5.9.0</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="install-aolserver-user-accounts" id="install-aolserver-user-accounts"></a>Set up a user account for each site.</h3></div></div></div><p>AOLserver needs to be started as the root user if you want to @@ -28,32 +25,33 @@ different service. A service name should be a single word, <span class="emphasis"><em>letters and numbers only</em></span>. If the name of your site is one word, that would be a good choice. For -example "<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>" might be -the service name for the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.net +example "<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>" might +be the service name for the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.net community.</p><p>We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put it in -the <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> group so -that it can use database and server commands associated with that -group. (If you don't know how to do this, type <strong class="userinput"><code>man usermod</code></strong>. You can type -<strong class="userinput"><code>groups</code></strong> to find out -which groups a user is a part of)</p><pre class="screen"> -[root root]# <strong class="userinput"><code>useradd <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +the <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> group +so that it can use database and server commands associated with +that group. (If you don't know how to do this, type +<strong class="userinput"><code>man usermod</code></strong>. You +can type <strong class="userinput"><code>groups</code></strong> to +find out which groups a user is a part of)</p><pre class="screen"> +[root root]# <strong class="userinput"><code>useradd <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre><p>You also need to set up a group called web.</p><pre class="screen"> [root root]# <strong class="userinput"><code>groupadd web</code></strong> </pre><p>Then change the user to be a part of this group:</p><pre class="screen"> -[root root]# <strong class="userinput"><code>usermod -g web <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>usermod -g web <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre><p>FreeBSD creates the user this way:</p><pre class="screen"> -[root root]# <strong class="userinput"><code>mkdir -p /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>mkdir -p /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[root root]# <strong class="userinput"><code>pw useradd -n <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -g web -d /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -s /bin/bash</code></strong> +[root root]# <strong class="userinput"><code>pw useradd -n <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -g web -d /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -s /bin/bash</code></strong> [root root]# -<span class="action"><span class="action">mkdir -p /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -pw useradd -n <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -g web -d /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -s /bin/bash -</span></span> +<span class="action">mkdir -p /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +pw useradd -n <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -g web -d /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -s /bin/bash +</span> </pre> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -68,9 +66,9 @@ [root root]# <strong class="userinput"><code>chgrp web /var/lib/aolserver</code></strong> [root root]# <strong class="userinput"><code>chmod 770 /var/lib/aolserver</code></strong> [root root]# -<span class="action"><span class="action">mkdir /var/lib/aolserver +<span class="action">mkdir /var/lib/aolserver chgrp web /var/lib/aolserver -chmod 770 /var/lib/aolserver</span></span> +chmod 770 /var/lib/aolserver</span> </pre> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -86,7 +84,7 @@ directory in the home directory of the service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target location.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install</code></strong> cvs server: Updating install @@ -97,7 +95,7 @@ U install/tcl/user-procs.tcl [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd install</code></strong> [$OPENACS_SERVICE_NAME install]$ <strong class="userinput"><code>emacs install.tcl</code></strong> -</pre><p>Edit the installation configuration file, <code class="computeroutput">/home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/install/install.tcl</code> +</pre><p>Edit the installation configuration file, <code class="computeroutput">/home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/install/install.tcl</code> and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's <code class="computeroutput">config.tcl</code> file. @@ -109,7 +107,7 @@ default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.</p><p>Run the install script <code class="computeroutput">install.sh</code> as root:</p><pre class="screen"> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> -[root root]# <strong class="userinput"><code>sh /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/install/install.sh</code></strong> +[root root]# <strong class="userinput"><code>sh /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/install/install.sh</code></strong> /home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file /home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/ $OPENACS_SERVICE_NAME, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, @@ -132,25 +130,23 @@ <a class="link" href="individual-programs">download the OpenACS tarball</a> and save it in <code class="computeroutput">/var/tmp</code> and proceed:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> -<p> -<a name="install-openacs-download" id="install-openacs-download"></a>Unpack the OpenACS tarball and -rename it to <code class="computeroutput">$OPENACS_SERVICE_NAME</code>. Secure the directory +<p>Unpack the OpenACS tarball and rename it to <code class="computeroutput">$OPENACS_SERVICE_NAME</code>. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.</p><p>FreeBSD note: Change the period in <strong class="userinput"><code>chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME</code></strong> to a colon: <strong class="userinput"><code>chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME</code></strong> </p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>tar xzf /var/tmp/openacs-5.9.0.tgz</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-5.9.0 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-5.9.0 <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>ls -al</code></strong> total 3 @@ -160,13 +156,13 @@ [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>exit</code></strong> logout [root root]# -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME +<span class="action">su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver tar xzf /var/tmp/openacs-5.9.0.tgz mv openacs-5.9.0 $OPENACS_SERVICE_NAME chmod -R 755 $OPENACS_SERVICE_NAME chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME -exit</span></span> +exit</span> </pre> </li><li class="listitem"><p> <a class="link" href="cvs-tips" title="Add the Service to CVS - OPTIONAL">Add the Service to CVS</a> @@ -175,19 +171,19 @@ <li class="listitem"> <p> <a name="install-openacs-prepare-oracle" id="install-openacs-prepare-oracle"></a><strong>Prepare Oracle for -OpenACS. </strong>If you won't be using Oracle, +OpenACS. </strong> If you won't be using Oracle, skip to <a class="xref" href="openacs" title="Prepare PostgreSQL for an OpenACS Service">Prepare PostgreSQL for an OpenACS Service</a> -</p><p>You should be sure that your user account (e.g. <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code>) is in the -<code class="computeroutput">dba</code> group.</p><div class="orderedlist"><ol class="orderedlist" type="a"> +</p><p>You should be sure that your user account (e.g. <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code>) is in +the <code class="computeroutput">dba</code> group.</p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> <p>Verify membership by typing <code class="computeroutput">groups</code> when you login:</p><pre class="programlisting"> [$OPENACS_SERVICE_NAME ~]$ groups dba web </pre><p>If you do not see these groups, take the following action:</p><pre class="programlisting"> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>su -</code></strong> Password: ************ -[root ~]# <strong class="userinput"><code>adduser <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> dba</code></strong> +[root ~]# <strong class="userinput"><code>adduser <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> dba</code></strong> </pre><p>If you get an error about an undefined group, then add that group manually:</p><pre class="programlisting"> [root ~]# <strong class="userinput"><code>groupadd dba</code></strong> @@ -230,7 +226,7 @@ [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>su -</code></strong> Password: ************ [root ~]# <strong class="userinput"><code>mkdir -p /ora8/m02/oradata/ora8/</code></strong> -[root ~]# <strong class="userinput"><code>chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>:web /ora8/m02/oradata/ora8</code></strong> +[root ~]# <strong class="userinput"><code>chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>:web /ora8/m02/oradata/ora8</code></strong> [root ~]# <strong class="userinput"><code>chmod 775 /ora8/m02/oradata/ora8</code></strong> [root ~]# <strong class="userinput"><code>exit</code></strong> [$OPENACS_SERVICE_NAME ~]$ @@ -245,8 +241,8 @@ ability to automatically coalesce free space in the tablespace.</p><pre class="programlisting"> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>svrmgrl</code></strong> SVRMGR> <strong class="userinput"><code>connect internal;</code></strong> -SVRMGR> <strong class="userinput"><code>create tablespace <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> - datafile '/ora8/m02/oradata/ora8/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>01.dbf' +SVRMGR> <strong class="userinput"><code>create tablespace <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> + datafile '/ora8/m02/oradata/ora8/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>01.dbf' size 50M autoextend on next 10M @@ -256,17 +252,17 @@ </pre> </li><li class="listitem"> <p>Create a database user for this service. Give the user access to -the tablespace and rights to connect. We'll use <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span></code> as -our password.</p><p>Write down what you specify as <span class="emphasis"><em>service_name</em></span> (i.e. <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code>) and +the tablespace and rights to connect. We'll use <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em></code> +as our password.</p><p>Write down what you specify as <span class="emphasis"><em>service_name</em></span> (i.e. <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code>) and <span class="emphasis"><em>database_password</em></span> (i.e. -<code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span></code>). +<code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em></code>). You will need this information for configuring exports and AOLserver.</p><pre class="programlisting"> -SVRMGR> <strong class="userinput"><code>create user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> identified by <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span> default tablespace <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> - temporary tablespace temp quota unlimited on <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>grant connect, resource, ctxapp, javasyspriv, query rewrite to <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>revoke unlimited tablespace from <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>alter user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> quota unlimited on <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> +SVRMGR> <strong class="userinput"><code>create user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> identified by <em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em> default tablespace <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> + temporary tablespace temp quota unlimited on <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>grant connect, resource, ctxapp, javasyspriv, query rewrite to <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>revoke unlimited tablespace from <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>alter user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> quota unlimited on <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> SVRMGR> <strong class="userinput"><code>exit;</code></strong> </pre><p>Your table space is now ready. In case you are trying to delete a previous OpenACS installation, consult these commands in @@ -275,7 +271,7 @@ below.</p> </li><li class="listitem"> <p>Make sure that you can login to Oracle using your <span class="emphasis"><em>service_name</em></span> account:</p><pre class="programlisting"> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>sqlplus <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>sqlplus <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/<em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em> </code></strong> SQL> <strong class="userinput"><code>select sysdate from dual;</code></strong> SYSDATE @@ -297,46 +293,44 @@ for an OpenACS Service. </strong> </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"> -<p> -<a name="create-service-db-user" id="create-service-db-user"></a>PostgreSQL:</p><p>Create a user in the database matching the service name. With +<p>PostgreSQL:</p><p>Create a user in the database matching the service name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the OpenACS system accounts on a machine has full access to all postgresql databases on that machine.</p><pre class="screen"> [root root]# <strong class="userinput"><code>su - postgres</code></strong> -[postgres pgsql]$ <strong class="userinput"><code>createuser -a -d <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[postgres pgsql]$ <strong class="userinput"><code>createuser -a -d <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> CREATE USER [postgres pgsql]$ <strong class="userinput"><code>exit</code></strong> logout [root root]# </pre> </li><li class="listitem"> -<p> -<a name="create-database" id="create-database"></a>Create a -database with the same name as our service name, <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>. The full -pathname for <code class="computeroutput">createdb</code> needs to -be used, since the pgsql directory has not been added to the -$OPENACS_SERVICE_NAME bash profile.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<p>Create a database with the same name as our service name, +<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>. +The full pathname for <code class="computeroutput">createdb</code> +needs to be used, since the pgsql directory has not been added to +the $OPENACS_SERVICE_NAME bash profile.</p><pre class="screen"> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/pgsql/bin/createdb -E UNICODE <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/pgsql/bin/createdb -E UNICODE <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> CREATE DATABASE [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ -<span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -/usr/local/pgsql/bin/createdb -E UNICODE <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</span></span> +<span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +/usr/local/pgsql/bin/createdb -E UNICODE <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</span> </pre> </li><li class="listitem"> <p>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: <code class="computeroutput">VACUUM ANALYZE</code> every hour and <code class="computeroutput">VACUUM FULL -ANALYZE</code> every day.</p><a class="indexterm" name="idp140592104083832" id="idp140592104083832"></a><pre class="screen"> +ANALYZE</code> every day.</p><a class="indexterm" name="idp140623178583368" id="idp140623178583368"></a><pre class="screen"> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>export EDITOR=emacs;crontab -e</code></strong> </pre><p>Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve @@ -345,35 +339,32 @@ 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 <code class="computeroutput">man 5 crontab</code> for more information.</p><pre class="programlisting"> -0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </pre><p>Depending on your distribution, you may receive email when the crontab items are executed. If you don't want to receive email for those crontab items, you can add <code class="computeroutput">> /dev/null 2>&1</code> to the end of each crontab line</p> </li><li class="listitem"><p> -<a class="link" href="install-full-text-search-openfts" title="Install OpenFTS prerequisites in PostgreSQL instance">Add -Full Text Search Support</a> (OPTIONAL)</p></li><li class="listitem"><p> -<a name="db-setup-exit" id="db-setup-exit"></a> At this point -the database should be ready for installing OpenACS.</p></li> +<a class="link" href="">Add Full Text Search Support</a> +(OPTIONAL)</p></li><li class="listitem"><p>At this point the database should be ready for installing +OpenACS.</p></li> </ul></div> </li> </ul></div> </li><li class="listitem"> <a name="install-openacs-configure-aol" id="install-openacs-configure-aol"></a><p><strong>Configure an AOLserver Service for OpenACS. </strong></p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> -<p> -<a name="configure-config-tcl" id="configure-config-tcl"></a> -The AOLserver architecture lets you run an arbitrary number of +<p>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, <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl</code>. -Open it in an editor to adjust the parameters.</p><a class="indexterm" name="idp140592101013272" id="idp140592101013272"></a><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +configuration file included in the OpenACS tarball, <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl</code>. +Open it in an editor to adjust the parameters.</p><a class="indexterm" name="idp140623178345544" id="idp140623178345544"></a><pre class="screen"> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc</code></strong> [$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>emacs config.tcl</code></strong> </pre><p>You can continue without changing any values in the file. However, if you don't change <code class="computeroutput">address</code> to match the computer's ip @@ -398,7 +389,7 @@ keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in -various dependent places. The Reference Platform uses <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.</p></li><li class="listitem"><p> +various dependent places. The Reference Platform uses <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.</p></li><li class="listitem"><p> <span class="emphasis"><em>db_name</em></span> - In almost all cases, this can be kept as a reference to $server. If for some reason, the tablespace you are using is different than your @@ -415,53 +406,48 @@ </ul></div> </li><li class="listitem"><p>AOLserver is very configurable. These settings should get you started, but for more options, read the <a class="ulink" href="http://aolserver.com/docs/admin/config.html" target="_top">AOLserver docs</a>.</p></li><li class="listitem"><p> -<a class="link" href="install-full-text-search-openfts" title="Enable OpenFTS in config.tcl">Enable OpenFTS Full Text Search</a> +<a class="link" href="">Enable OpenFTS Full Text Search</a> (OPTIONAL)</p></li><li class="listitem"><p> <a class="link" href="install-ssl" title="Installing SSL Support for an OpenACS service">Install nsopenssl for SSL support.</a> (OPTIONAL)</p></li> </ol></div> </li><li class="listitem"> <a name="verify-aolserver-startup" id="verify-aolserver-startup"></a><p><strong>Verify AOLserver startup. </strong></p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> -<p> -<a name="start-aolserver" id="start-aolserver"></a> 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, <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/run</code>. +<p>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, <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/run</code>. If you are not using the default file paths and names, you will need to edit <code class="computeroutput">run</code>.</p><p>If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the -<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> user via -<code class="computeroutput">grep <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +user via <code class="computeroutput">grep <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /etc/passwd</code> and then put those numbers into the command line -via <code class="computeroutput">-u <span class="replaceable"><span class="replaceable">501</span></span> -g -<span class="replaceable"><span class="replaceable">502</span></span> -</code>. In AOLserver 4, you must -also send a <code class="computeroutput">-b</code> flag. Do this by -editing the <code class="computeroutput">run</code> file as +via <code class="computeroutput">-u <em class="replaceable"><code>501</code></em> -g <em class="replaceable"><code>502</code></em> +</code>. In AOLserver 4, you +must also send a <code class="computeroutput">-b</code> flag. Do +this by editing the <code class="computeroutput">run</code> file as indicated in the comments.</p><p>If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do <code class="computeroutput">ps -auxw | grep nsd</code> and selectively kill by job number.</p><pre class="screen"> [$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>killall nsd</code></strong> nsd: no process killed -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file... [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file. </pre> </li><li class="listitem"> -<p> -<a name="connect-to-aolserver" id="connect-to-aolserver"></a> -Attempt to connect to the service from a web browser. You should -specify a URL like: <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>:8000</code> +<p>Attempt to connect to the service from a web browser. You should +specify a URL like: <code class="computeroutput">http://<em class="replaceable"><code>yourserver.test</code></em>:8000</code> </p><p>You should see a page that looks like <a class="ulink" href="files/openacs-start" target="_top">this</a>. If you <a class="link" href="cvs-tips" title="Add the Service to CVS - OPTIONAL">imported your files into cvs</a>, now that you know it worked you can erase the temp directory with <code class="computeroutput">rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig</code>.</p><p>If you don't see the login page, view your error log -(<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-error.log</code>) +(<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-error.log</code>) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and AOLserver @@ -511,7 +497,7 @@ AOLserver to restart itself (ie. <a class="link" href="install-openacs-keepalive" title="Starting and Stopping an OpenACS instance.">inittab or daemontools</a>), you'll need to manually restart your service.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/config.tcl</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/config.tcl</code></strong> </pre> </li><li class="listitem"><p>Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login @@ -537,10 +523,9 @@ <li class="listitem"><p>Use daemontools <code class="computeroutput">supervise</code> and <code class="computeroutput">svc</code>, or <code class="computeroutput">inittab</code>, to <a class="link" href="install-openacs-inittab" title="AOLserver keepalive with inittab">automate server startup and shutdown.</a> -</p></li><li class="listitem"><p>Install Full Text Search (OPTIONAL). If you have <a class="link" href="install-full-text-search-openfts" title="Install OpenFTS module">installed OpenFTS</a> and enabled OpenFTS, -you can now <a class="link" href="install-full-text-search-tsearch2" title="Install Full Text Search Engine Package in OpenACS">install</a> -the OpenFTS Driver package and Full Text Search Engine package in -the OpenACS service.</p></li><li class="listitem"><p>This is a good time to make a <a class="link" href="snapshot-backup" title="Manual backup and recovery">backup</a> of your service. If this is +</p></li><li class="listitem"><p>Install Full Text Search (OPTIONAL). If you have <a class="link" href="">installed OpenFTS</a> and enabled OpenFTS, you can now +<a class="link" href="">install</a> the OpenFTS Driver package and +Full Text Search Engine package in the OpenACS service.</p></li><li class="listitem"><p>This is a good time to make a <a class="link" href="snapshot-backup" title="Manual backup and recovery">backup</a> of your service. If this is a production site, you should set up <a class="link" href="automated-backup" title="Automated Backup">automatic nightly backups</a>.</p></li><li class="listitem"><p>If you want traffic reports, <a class="link" href="analog-setup" title="Set up Log Analysis Reports">set up analog</a> or another log processing program.</p></li><li class="listitem"><p>Follow the instruction on the home page to change the appearance @@ -554,7 +539,7 @@ run-time connection with the database, because those environmental variables are set by the wrapper scripts nsd-postgres and nsd-oracle.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>emacs .bashrc</code></strong> </pre><p>Put in the appropriate lines for the database you are running. @@ -571,19 +556,19 @@ appropriately. Also, make sure that the '8.1.7' matches your Oracle version.</p><pre class="programlisting"> export ORACLE_BASE=/ora8/m01/app/oracle -export ORACLE_HOME=$ORACLE_BASE/product/<span class="replaceable"><span class="replaceable">8.1.7</span></span> +export ORACLE_HOME=$ORACLE_BASE/product/<em class="replaceable"><code>8.1.7</code></em> export PATH=$PATH:$ORACLE_HOME/bin export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib export ORACLE_SID=ora8 export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data </pre> </li> -</ul></div><p>Test this by logging out and back in as <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> and +</ul></div><p>Test this by logging out and back in as <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> and checking the paths.</p><pre class="screen"> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> logout -[root src]# <strong class="userinput"><code>su - <strong class="userinput"><code><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[root src]# <strong class="userinput"><code>su - <strong class="userinput"><code><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> </code></strong> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>env</code></strong> </pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> @@ -610,8 +595,8 @@ recovery</a> procedure.</p></li><li class="listitem"><p>Set up <a class="xref" href="uptime" title="External uptime validation">the section called “External uptime validation”</a>.</p></li> -</ul></div><div class="cvstag">($‌Id: openacs.xml,v 1.31.14.4 2017/06/11 -08:42:13 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: openacs.xml,v 1.32 2017/08/07 +23:47:55 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/openacs.html,v diff -u -r1.52 -r1.53 --- openacs-4/packages/acs-core-docs/www/openacs.html 7 Aug 2017 23:47:51 -0000 1.52 +++ openacs-4/packages/acs-core-docs/www/openacs.html 8 Nov 2017 09:42:11 -0000 1.53 @@ -1,62 +1,99 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install OpenACS 5.9.0</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="aolserver4.html" title="Install AOLserver 4"><link rel="next" href="win2k-installation.html" title="OpenACS Installation Guide for Windows"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver4.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs"></a>Install OpenACS 5.9.0</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-aolserver-user-accounts"></a>Set up a user account for each site.</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install OpenACS 5.9.0</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="aolserver4.html" title="Install AOLserver 4"><link rel="next" href="win2k-installation.html" title="OpenACS Installation Guide for Windows"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="aolserver4.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="openacs"></a>Install OpenACS 5.9.0</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-aolserver-user-accounts"></a>Set up a user account for each site.</h3></div></div></div> + + <p> AOLserver needs to be started as the root user if you want to use port 80. Once it starts, though, it will drop the root privileges and run as another user, which you must specify on the command line. It's important that this user has as few privileges as possible. Why? Because if an intruder somehow breaks in through AOLserver, you don't want her to have any ability to do damage to the rest of your - server.</p><p>At the same time, AOLserver needs to have write access to + server.</p> + + <p>At the same time, AOLserver needs to have write access to some files on your system in order for OpenACS to function properly. So, we'll run AOLserver with a different user account for each different service. A service name should be a single word, <span class="emphasis"><em>letters and numbers only</em></span>. If the name of your site is one word, that would be a good choice. For - example "<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>" might be the service name for the - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.net community.</p><p>We'll leave the password blank, which prevents login by + example "<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>" might be the service name for the + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.net community.</p> + + <p>We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put - it in the <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> group so that it + it in the <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> group so that it can use database and server commands associated with that group. (If you don't know how to do this, type <strong class="userinput"><code>man usermod</code></strong>. You can type <strong class="userinput"><code>groups</code></strong> to find out which groups a user is a part of) - </p><pre class="screen"> -[root root]# <strong class="userinput"><code>useradd <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -</pre><p>You also need to set up a group called web.</p><pre class="screen"> + </p> + +<pre class="screen"> +[root root]# <strong class="userinput"><code>useradd <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +</pre> + + <p>You also need to set up a group called web.</p> + + <pre class="screen"> [root root]# <strong class="userinput"><code>groupadd web</code></strong> - </pre><p> + </pre> + + <p> Then change the user to be a part of this group: - </p><pre class="screen"> -[root root]# <strong class="userinput"><code>usermod -g web <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> - </pre><p>FreeBSD creates the user this way:</p><pre class="screen"> -[root root]# <strong class="userinput"><code>mkdir -p /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[root root]# <strong class="userinput"><code>pw useradd -n <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -g web -d /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -s /bin/bash</code></strong> + </p> + + <pre class="screen"> +[root root]# <strong class="userinput"><code>usermod -g web <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> + </pre> + <p>FreeBSD creates the user this way:</p> +<pre class="screen"> +[root root]# <strong class="userinput"><code>mkdir -p /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[root root]# <strong class="userinput"><code>pw useradd -n <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -g web -d /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -s /bin/bash</code></strong> [root root]# -<span class="action"><span class="action">mkdir -p /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -pw useradd -n <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -g web -d /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -s /bin/bash -</span></span></pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="openacs-setup"></a>Set up the file system for one or more OpenACS Sites</h3></div></div></div><p>For Linux Standard Base compliance and ease of backup, +<span class="action">mkdir -p /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +pw useradd -n <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -g web -d /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -s /bin/bash +</span></pre> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="openacs-setup"></a>Set up the file system for one or more OpenACS Sites</h3></div></div></div> + + <p>For Linux Standard Base compliance and ease of backup, all of the files in each OpenACS site are stored in a subdirectory of <code class="computeroutput">/var/lib/aolserver</code>, one subdirectory per site. The first time you install an OpenACS - site on a server, you must create the parent directory and set its permissions:</p><pre class="screen">[root root]# <strong class="userinput"><code>mkdir /var/lib/aolserver</code></strong> + site on a server, you must create the parent directory and set its permissions:</p> + <pre class="screen">[root root]# <strong class="userinput"><code>mkdir /var/lib/aolserver</code></strong> [root root]# <strong class="userinput"><code>chgrp web /var/lib/aolserver</code></strong> [root root]# <strong class="userinput"><code>chmod 770 /var/lib/aolserver</code></strong> [root root]# -<span class="action"><span class="action">mkdir /var/lib/aolserver +<span class="action">mkdir /var/lib/aolserver chgrp web /var/lib/aolserver -chmod 770 /var/lib/aolserver</span></span></pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-with-script"></a>Installation Option 1: Use automated script</h3></div></div></div><p>A bash script is available to automate all of the steps for the rest of this section. It requires <a class="link" href="install-tclwebtest.html" title="Install tclwebtest.">tclwebtest</a>. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a <a class="link" href="openacs.html#install-from-tarball" title="Installation Option 2: Install from tarball">manual installation</a>.</p><p>Get the install script from CVS. It is located within +chmod 770 /var/lib/aolserver</span></pre> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-with-script"></a>Installation Option 1: Use automated script</h3></div></div></div> + + <p>A bash script is available to automate all of the steps for the rest of this section. It requires <a class="link" href="install-tclwebtest.html" title="Install tclwebtest.">tclwebtest</a>. The automated script can greatly accelerate the install process, but is very sensitive to the install environment. We recommend that you run the automated install and, if it does not work the first time, consider switching to a <a class="link" href="openacs.html#install-from-tarball" title="Installation Option 2: Install from tarball">manual installation</a>.</p> + <p>Get the install script from CVS. It is located within the main cvs tree, at /etc/install. Use anonymous CVS checkout to get that directory in the home directory of the service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target - location.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + location.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot co -d install openacs-4/etc/install</code></strong> cvs server: Updating install U install/README @@ -66,8 +103,11 @@ U install/tcl/user-procs.tcl [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd install</code></strong> [$OPENACS_SERVICE_NAME install]$ <strong class="userinput"><code>emacs install.tcl</code></strong> -</pre><p>Edit the installation configuration file, <code class="computeroutput">/home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/install/install.tcl</code> and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's <code class="computeroutput">config.tcl</code> file. If your system is different from the one described in the previous sections, check the file paths as well. Set <code class="computeroutput">do_checkout=yes</code> to create a new OpenACS site directly from a CVS checkout, or <code class="computeroutput">=no</code> if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.</p><p>Run the install script <code class="computeroutput">install.sh</code> as root:</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> -[root root]# <strong class="userinput"><code>sh /home/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/install/install.sh</code></strong> +</pre> + <p>Edit the installation configuration file, <code class="computeroutput">/home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/install/install.tcl</code> and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's <code class="computeroutput">config.tcl</code> file. If your system is different from the one described in the previous sections, check the file paths as well. Set <code class="computeroutput">do_checkout=yes</code> to create a new OpenACS site directly from a CVS checkout, or <code class="computeroutput">=no</code> if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000.</p> + <p>Run the install script <code class="computeroutput">install.sh</code> as root:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> +[root root]# <strong class="userinput"><code>sh /home/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/install/install.sh</code></strong> /home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file /home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/ $OPENACS_SERVICE_NAME, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, @@ -79,17 +119,27 @@ admin email : admin@yourserver.net admin password: xxxx ###################################################################### -[root root]#</pre><p>You can proceed to <a class="xref" href="openacs.html#install-next-steps" title="Next Steps">the section called “Next Steps”</a>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-from-tarball"></a>Installation Option 2: Install from tarball</h3></div></div></div><p>You should already have downloaded the OpenACS tarball +[root root]#</pre> + <p>You can proceed to <a class="xref" href="openacs.html#install-next-steps" title="Next Steps">the section called “Next Steps”</a>.</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-from-tarball"></a>Installation Option 2: Install from tarball</h3></div></div></div> + + <p>You should already have downloaded the OpenACS tarball to the <code class="computeroutput">/var/tmp</code> directory. If not, <a class="link" href="individual-programs.html#openacs-download">download the OpenACS tarball</a> and save it in - <code class="computeroutput">/var/tmp</code> and proceed:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><a name="install-openacs-download"></a>Unpack the OpenACS tarball and rename it to <code class="computeroutput">$OPENACS_SERVICE_NAME</code>. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.</p><p>FreeBSD note: Change the period in <strong class="userinput"><code>chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME</code></strong> to a colon: <strong class="userinput"><code>chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME</code></strong> - </p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + <code class="computeroutput">/var/tmp</code> and proceed:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Unpack the OpenACS tarball and rename it to <code class="computeroutput">$OPENACS_SERVICE_NAME</code>. Secure the directory so that only the owner can access it. Check the permissions by listing the directory.</p> + <p>FreeBSD note: Change the period in <strong class="userinput"><code>chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME</code></strong> to a colon: <strong class="userinput"><code>chown -R $OPENACS_SERVICE_NAME:$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME</code></strong> + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>tar xzf /var/tmp/openacs-5.9.0.tgz</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-5.9.0 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>.<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-5.9.0 <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>.<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>ls -al</code></strong> total 3 drwxrwx--- 3 root web 1024 Mar 29 16:41 . @@ -98,17 +148,28 @@ [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>exit</code></strong> logout [root root]# -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME +<span class="action">su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver tar xzf /var/tmp/openacs-5.9.0.tgz mv openacs-5.9.0 $OPENACS_SERVICE_NAME chmod -R 755 $OPENACS_SERVICE_NAME chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME -exit</span></span></pre></li><li class="listitem"><p><a class="link" href="cvs-tips.html#cvs-service-import" title="Add the Service to CVS - OPTIONAL">Add the Service to CVS</a> (OPTIONAL)</p></li><li class="listitem"><p>Prepare the database</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="install-openacs-prepare-oracle"></a><b>Prepare Oracle for OpenACS. </b>If you won't be using Oracle, skip to <a class="xref" href="openacs.html#install-openacs-prepare-postgres" title="Prepare PostgreSQL for an OpenACS Service">Prepare PostgreSQL for an OpenACS Service</a></p><p> +exit</span></pre> + </li><li class="listitem"> + <p><a class="link" href="cvs-tips.html#cvs-service-import" title="Add the Service to CVS - OPTIONAL">Add the Service to CVS</a> (OPTIONAL)</p> + </li><li class="listitem"> + <p>Prepare the database</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><a name="install-openacs-prepare-oracle"></a> + <b>Prepare Oracle for OpenACS. </b> + If you won't be using Oracle, skip to <a class="xref" href="openacs.html#install-openacs-prepare-postgres" title="Prepare PostgreSQL for an OpenACS Service">Prepare PostgreSQL for an OpenACS Service</a> + </p> + <p> You should be sure that your user account - (e.g. <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code>) is in the + (e.g. <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code>) is in the <code class="computeroutput">dba</code> group. - </p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> Verify membership by typing <code class="computeroutput">groups</code> when you login: @@ -119,7 +180,7 @@ </p><pre class="programlisting">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>su -</code></strong> Password: ************ -[root ~]# <strong class="userinput"><code>adduser <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> dba</code></strong></pre><p> +[root ~]# <strong class="userinput"><code>adduser <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> dba</code></strong></pre><p> If you get an error about an undefined group, then add that group manually: @@ -166,15 +227,18 @@ </p></li><li class="listitem"><p> Create the directory for the datafile; to do this, exit from <code class="computeroutput">svrmgrl</code> and login as - <code class="computeroutput">root</code> for this step: </p><pre class="programlisting"> + <code class="computeroutput">root</code> for this step: </p> + + <pre class="programlisting"> SVRMGR> <strong class="userinput"><code>exit</code></strong> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>su -</code></strong> Password: ************ [root ~]# <strong class="userinput"><code>mkdir -p /ora8/m02/oradata/ora8/</code></strong> -[root ~]# <strong class="userinput"><code>chown <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>:web /ora8/m02/oradata/ora8</code></strong> +[root ~]# <strong class="userinput"><code>chown <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>:web /ora8/m02/oradata/ora8</code></strong> [root ~]# <strong class="userinput"><code>chmod 775 /ora8/m02/oradata/ora8</code></strong> [root ~]# <strong class="userinput"><code>exit</code></strong> -[$OPENACS_SERVICE_NAME ~]$</pre></li><li class="listitem"><p> +[$OPENACS_SERVICE_NAME ~]$</pre> + </li><li class="listitem"><p> Create a tablespace for the service. It is important that the tablespace can <code class="computeroutput">autoextend</code>. This @@ -185,134 +249,227 @@ Oracle's ability to automatically coalesce free space in the tablespace. - </p><pre class="programlisting">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>svrmgrl</code></strong> + </p> + <pre class="programlisting">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>svrmgrl</code></strong> SVRMGR> <strong class="userinput"><code>connect internal;</code></strong> -SVRMGR> <strong class="userinput"><code>create tablespace <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> - datafile '/ora8/m02/oradata/ora8/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>01.dbf' +SVRMGR> <strong class="userinput"><code>create tablespace <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> + datafile '/ora8/m02/oradata/ora8/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>01.dbf' size 50M autoextend on next 10M maxsize 300M extent management local - uniform size 32K;</code></strong></pre></li><li class="listitem"><p> + uniform size 32K;</code></strong></pre> + </li><li class="listitem"><p> Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use - <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span></code> as our password.</p><p> + <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em></code> as our password.</p> + + <p> Write down what you specify as <span class="emphasis"><em>service_name</em></span> - (i.e. <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code>) + (i.e. <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code>) and <span class="emphasis"><em>database_password</em></span> - (i.e. <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span></code>). You + (i.e. <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em></code>). You will need this information for configuring exports and AOLserver. - </p><pre class="programlisting"> -SVRMGR> <strong class="userinput"><code>create user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> identified by <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span> default tablespace <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> - temporary tablespace temp quota unlimited on <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>grant connect, resource, ctxapp, javasyspriv, query rewrite to <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>revoke unlimited tablespace from <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>alter user <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> quota unlimited on <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>;</code></strong> -SVRMGR> <strong class="userinput"><code>exit;</code></strong></pre><p> + </p> + + <pre class="programlisting"> +SVRMGR> <strong class="userinput"><code>create user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> identified by <em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em> default tablespace <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> + temporary tablespace temp quota unlimited on <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>grant connect, resource, ctxapp, javasyspriv, query rewrite to <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>revoke unlimited tablespace from <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>alter user <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> quota unlimited on <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>;</code></strong> +SVRMGR> <strong class="userinput"><code>exit;</code></strong></pre> + + <p> Your table space is now ready. In case you are trying to delete a previous OpenACS installation, consult these commands in <a class="xref" href="install-openacs-delete-tablespace.html" title="Deleting a tablespace">the section called “Deleting a tablespace”</a> below. </p></li><li class="listitem"><p> Make sure that you can login to Oracle using your - <span class="emphasis"><em>service_name</em></span> account: </p><pre class="programlisting">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>sqlplus <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAMEpassword</span></span></code></strong> + <span class="emphasis"><em>service_name</em></span> account: </p> + + <pre class="programlisting">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>sqlplus <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/<em class="replaceable"><code>$OPENACS_SERVICE_NAMEpassword</code></em></code></strong> SQL> <strong class="userinput"><code>select sysdate from dual;</code></strong> SYSDATE ---------- 2001-12-20 -SQL> <strong class="userinput"><code>exit;</code></strong></pre><p> +SQL> <strong class="userinput"><code>exit;</code></strong></pre> + + <p> You should see today's date in a format 'YYYY-MM-DD.' If you can't login, try redoing step 1 again. If the date is in the wrong format, make sure you followed the steps outlined in <a class="xref" href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">the section called “Troubleshooting Oracle Dates”</a> - </p></li></ol></div></li><li class="listitem"><p><a name="install-openacs-prepare-postgres"></a><b>Prepare PostgreSQL for an OpenACS Service. </b></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><a name="create-service-db-user"></a>PostgreSQL:</p><p>Create a user in the database matching the service - name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the OpenACS system accounts on a machine has full access to all postgresql databases on that machine.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - postgres</code></strong> -[postgres pgsql]$ <strong class="userinput"><code>createuser -a -d <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + </p></li></ol></div> + </li><li class="listitem"> + <p><a name="install-openacs-prepare-postgres"></a> + <b>Prepare PostgreSQL for an OpenACS Service. </b> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p>PostgreSQL:</p> + <p>Create a user in the database matching the service + name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the OpenACS system accounts on a machine has full access to all postgresql databases on that machine.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - postgres</code></strong> +[postgres pgsql]$ <strong class="userinput"><code>createuser -a -d <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> CREATE USER [postgres pgsql]$ <strong class="userinput"><code>exit</code></strong> logout -[root root]#</pre></li><li class="listitem"><p><a name="create-database"></a>Create a database with the same name as our service name, <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>. The full pathname for <code class="computeroutput">createdb</code> needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/pgsql/bin/createdb -E UNICODE <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[root root]#</pre> + </li><li class="listitem"> + <p>Create a database with the same name as our service name, <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>. The full pathname for <code class="computeroutput">createdb</code> needs to be used, since the pgsql directory has not been added to the $OPENACS_SERVICE_NAME bash profile.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/pgsql/bin/createdb -E UNICODE <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> CREATE DATABASE [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ -<span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -/usr/local/pgsql/bin/createdb -E UNICODE <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></span></span></pre></li><li class="listitem"><p>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: <code class="computeroutput">VACUUM ANALYZE</code> every hour and <code class="computeroutput">VACUUM FULL ANALYZE</code> every day.</p><a class="indexterm" name="idp140592104083832"></a><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>export EDITOR=emacs;crontab -e</code></strong></pre><p>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 <code class="computeroutput">man 5 crontab</code> for more information.</p><pre class="programlisting">0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></pre><p>Depending on your distribution, you may receive +<span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +/usr/local/pgsql/bin/createdb -E UNICODE <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></span></pre> + </li><li class="listitem"> + <p>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: <code class="computeroutput">VACUUM ANALYZE</code> every hour and <code class="computeroutput">VACUUM FULL ANALYZE</code> every day.</p> + <a class="indexterm" name="idp140623178583368"></a> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>export EDITOR=emacs;crontab -e</code></strong></pre> + <p>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 <code class="computeroutput">man 5 crontab</code> for more information.</p> + <pre class="programlisting">0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></pre> + + <p>Depending on your distribution, you may receive email when the crontab items are executed. If you don't want to receive email for those crontab items, you can add <code class="computeroutput">> /dev/null 2>&1</code> to the end of each crontab - line</p></li><li class="listitem"><p><a class="link" href="install-full-text-search-openfts.html#install-openfts-postgres" title="Install OpenFTS prerequisites in PostgreSQL instance">Add Full Text Search Support</a> (OPTIONAL)</p></li><li class="listitem"><p><a name="db-setup-exit"></a> At this point the database should be ready for installing OpenACS.</p></li></ul></div></li></ul></div></li><li class="listitem"><a name="install-openacs-configure-aol"></a><p><b>Configure an AOLserver Service for OpenACS. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p><a name="configure-config-tcl"></a> + line</p> + + </li><li class="listitem"> + <p><a class="link" href="">Add Full Text Search Support</a> (OPTIONAL)</p> + </li><li class="listitem"> + <p> At this point the database should be ready for installing OpenACS.</p> + </li></ul></div> + </li></ul></div> + </li><li class="listitem"><a name="install-openacs-configure-aol"></a> + <p> + <b>Configure an AOLserver Service for OpenACS. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p> 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, - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl</code>. - Open it in an editor to adjust the parameters.</p><a class="indexterm" name="idp140592101013272"></a><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc</code></strong> + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl</code>. + Open it in an editor to adjust the parameters.</p> + <a class="indexterm" name="idp140623178345544"></a> + + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc</code></strong> [$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>emacs config.tcl</code></strong> -</pre><p> +</pre> + <p> You can continue without changing any values in the file. However, if you don't change <code class="computeroutput">address</code> to match the computer's ip address, you won't be able to browse to your server from other machines. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>httpport</em></span> - If you want your - server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.</p></li><li class="listitem"><p><span class="emphasis"><em>httpsport</em></span> - This is the + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="emphasis"><em>httpport</em></span> - If you want your + server on a different port, enter it here. The Reference Platform port is 8000, which is suitable for development use. Port 80 is the standard http port - it's the port used by your browser when you enter http://yourserver.test. So you should use port 80 for your production site.</p></li><li class="listitem"> + <p><span class="emphasis"><em>httpsport</em></span> - This is the port for https requests. The Reference Platform https port is 8443. If http port is set to 80, httpsport should be 443 to - match the standard.</p></li><li class="listitem"><p> - <span class="emphasis"><em>address</em></span> - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.</p></li><li class="listitem"><p><span class="emphasis"><em>server</em></span> - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>. + match the standard.</p> + </li><li class="listitem"><p> + <span class="emphasis"><em>address</em></span> - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses.</p> + </li><li class="listitem"> + <p><span class="emphasis"><em>server</em></span> - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>. </p></li><li class="listitem"><p><span class="emphasis"><em>db_name</em></span> - In almost all cases, this can be kept as a reference to $server. If for some reason, the tablespace you are using is different than your servername, then you can set it here. You should have a good reason for doing this. </p></li><li class="listitem"><p> - <span class="emphasis"><em>servername</em></span> - This is just a *pretty* name for your server.</p></li><li class="listitem"><p><span class="emphasis"><em>user_account</em></span> - The account that + <span class="emphasis"><em>servername</em></span> - This is just a *pretty* name for your server.</p> + </li><li class="listitem"> + <p><span class="emphasis"><em>user_account</em></span> - The account that will both own OpenACS files and connect to the database (for - Postgresql).</p></li><li class="listitem"><p><span class="emphasis"><em>debug</em></span> - Set to true for a very verbose error log, including many lines for every page view, success or failure.</p></li></ul></div></li><li class="listitem"><p> + Postgresql).</p> + </li><li class="listitem"> + <p><span class="emphasis"><em>debug</em></span> - Set to true for a very verbose error log, including many lines for every page view, success or failure.</p> + </li></ul></div> + </li><li class="listitem"> + <p> AOLserver is very configurable. These settings should get you started, but for more options, read the <a class="ulink" href="http://aolserver.com/docs/admin/config.html" target="_top">AOLserver docs</a>. - </p></li><li class="listitem"><p><a class="link" href="install-full-text-search-openfts.html#enable-openfts" title="Enable OpenFTS in config.tcl">Enable OpenFTS Full Text Search</a> (OPTIONAL)</p></li><li class="listitem"><p><a class="link" href="install-ssl.html" title="Installing SSL Support for an OpenACS service">Install nsopenssl - for SSL support.</a> (OPTIONAL)</p></li></ol></div></li><li class="listitem"><a name="verify-aolserver-startup"></a><p><b>Verify AOLserver startup. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p><a name="start-aolserver"></a> + </p> + </li><li class="listitem"> + <p><a class="link" href="">Enable OpenFTS Full Text Search</a> (OPTIONAL)</p> + </li><li class="listitem"> + <p><a class="link" href="install-ssl.html" title="Installing SSL Support for an OpenACS service">Install nsopenssl + for SSL support.</a> (OPTIONAL)</p> + </li></ol></div> + </li><li class="listitem"><a name="verify-aolserver-startup"></a> + <p> + <b>Verify AOLserver startup. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p> 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, <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/run</code>. If you are not using the default file paths and names, you will need to edit <code class="computeroutput">run</code>.</p><p>If you want to use port 80, there are complications. AOLserver must be root to use system ports such as + one. The recommended way to start an AOLserver process is by running the included script, <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/run</code>. If you are not using the default file paths and names, you will need to edit <code class="computeroutput">run</code>.</p> + <p>If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> user via - <code class="computeroutput">grep <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> user via + <code class="computeroutput">grep <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> /etc/passwd</code> and then put those numbers into the command line via <code class="computeroutput">-u - <span class="replaceable"><span class="replaceable">501</span></span> -g - <span class="replaceable"><span class="replaceable">502</span></span></code>. In AOLserver 4, you must also send a <code class="computeroutput">-b</code> flag. Do this by editing the <code class="computeroutput">run</code> file as indicated in the comments. </p><p>If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do <code class="computeroutput">ps -auxw | grep - nsd</code> and selectively kill by job number.</p><pre class="screen">[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>killall nsd</code></strong> + <em class="replaceable"><code>501</code></em> -g + <em class="replaceable"><code>502</code></em></code>. In AOLserver 4, you must also send a <code class="computeroutput">-b</code> flag. Do this by editing the <code class="computeroutput">run</code> file as indicated in the comments. </p> + <p>If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do <code class="computeroutput">ps -auxw | grep + nsd</code> and selectively kill by job number.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME etc]$ <strong class="userinput"><code>killall nsd</code></strong> nsd: no process killed -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$<strong class="userinput"><code> /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl</code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file... -[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.</pre></li><li class="listitem"><p><a name="connect-to-aolserver"></a> - Attempt to connect to the service from a web browser. You should specify a URL like: <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>:8000</code></p><p> +[08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file.</pre> + </li><li class="listitem"> + <p> + Attempt to connect to the service from a web browser. You should specify a URL like: <code class="computeroutput">http://<em class="replaceable"><code>yourserver.test</code></em>:8000</code></p> + + <p> You should see a page that looks like <a class="ulink" href="files/openacs-start.html" target="_top">this</a>. If you <a class="link" href="cvs-tips.html#cvs-service-import" title="Add the Service to CVS - OPTIONAL">imported your files into cvs</a>, now that you know it worked you can erase the temp directory with <code class="computeroutput">rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig</code>. - </p><p> + </p> + <p> + If you don't see the login page, view your error log - (<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-error.log</code>) + (<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-error.log</code>) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of a firewall, and AOLserver failing to start due to permissions errors or missing files. If you need to make changes, don't forget to kill any running servers with <strong class="userinput"><code>killall nsd</code></strong>. - </p></li><li class="listitem"><p><a class="link" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance.">Automate - AOLserver keepalive</a> (OPTIONAL)</p></li></ol></div></li><li class="listitem"><a name="install-openacs-using-installer"></a><p><b>Configure a Service with the OpenACS + </p> + </li><li class="listitem"> + <p><a class="link" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance.">Automate + AOLserver keepalive</a> (OPTIONAL)</p> + </li></ol></div> + </li><li class="listitem"><a name="install-openacs-using-installer"></a> + <p> + <b>Configure a Service with the OpenACS Installer. </b> + Now that you've got AOLserver up and running, let's install OpenACS 5.9.0. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> You should see a page from the webserver titled <code class="computeroutput">OpenACS Installation: Welcome</code>. You will be warned if your version of @@ -329,14 +486,19 @@ should see a string of output messages from the database as the datamodel is created. You'll see the line: - </p><pre class="programlisting"> -Loading package .info files ... this will take a few minutes</pre><p> + </p> + <pre class="programlisting"> +Loading package .info files ... this will take a few minutes</pre> + + <p> + This will really take a few minutes. Have faith! Finally, another <code class="computeroutput">Next</code> button will appear at the bottom - click it. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> The following page shows the results of loading the core package data models. You should see positive results for each of the @@ -363,55 +525,107 @@ being restarted; note that unless you already set up a way for AOLserver to restart itself (ie. <a class="link" href="install-openacs-keepalive.html" title="Starting and Stopping an OpenACS instance.">inittab or daemontools</a>), you'll need to manually restart your service. - </p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/config.tcl</code></strong></pre></li><li class="listitem"><p> + </p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>/usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/config.tcl</code></strong></pre> + </li><li class="listitem"><p> Give the server a few minutes to start up. Then reload the final page above. You should see the front page, with an area to login near the upper right. Congratulations, OpenACS 5.9.0 is now up and running! - </p></li></ul></div></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-from-cvs"></a>Installation Option 3: Install from CVS</h3></div></div></div><p>If you want to track fresh code developments between + </p></li></ul></div> + </li></ol></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-from-cvs"></a>Installation Option 3: Install from CVS</h3></div></div></div> + + <p>If you want to track fresh code developments between releases, or you are an OpenACS core developer, you may want to install from CVS. This is identical to Option 2 except that you get the files from CVS instead of the tarball: <a class="ulink" href="/xowiki/Get_the_Code" target="_top">CVS Checkout Instructions</a>. In short, instead of <code class="computeroutput"><strong class="userinput"><code>tar xzf /var/tmp/openacs-5.9.0.tgz</code></strong></code>, use <code class="computeroutput"><strong class="userinput"><code>cvs -z3 -d :pserver:anonymous@openacs.org:/cvsroot co - acs-core</code></strong></code> to obtain an ACS core installation.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-next-steps"></a>Next Steps</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Use daemontools <code class="computeroutput">supervise</code> and <code class="computeroutput">svc</code>, or <code class="computeroutput">inittab</code>, to <a class="link" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab">automate server startup and shutdown.</a></p></li><li class="listitem"><p>Install Full Text Search (OPTIONAL). If you have <a class="link" href="install-full-text-search-openfts.html#install-openfts" title="Install OpenFTS module">installed OpenFTS</a> and enabled - OpenFTS, you can now <a class="link" href="install-full-text-search-tsearch2.html#install-fts-engine" title="Install Full Text Search Engine Package in OpenACS">install</a> the OpenFTS Driver package and - Full Text Search Engine package in the OpenACS service.</p></li><li class="listitem"><p>This is a good time to make a <a class="link" href="snapshot-backup.html" title="Manual backup and recovery">backup</a> of your service. If this is a - production site, you should set up <a class="link" href="automated-backup.html" title="Automated Backup">automatic nightly backups</a>.</p></li><li class="listitem"><p>If you want traffic reports, <a class="link" href="analog-setup.html" title="Set up Log Analysis Reports">set up analog</a> or another log - processing program.</p></li><li class="listitem"><p>Follow the instruction on the home page to + acs-core</code></strong></code> to obtain an ACS core installation.</p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-next-steps"></a>Next Steps</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Use daemontools <code class="computeroutput">supervise</code> and <code class="computeroutput">svc</code>, or <code class="computeroutput">inittab</code>, to <a class="link" href="install-openacs-inittab.html" title="AOLserver keepalive with inittab">automate server startup and shutdown.</a></p> + </li><li class="listitem"> + <p>Install Full Text Search (OPTIONAL). If you have <a class="link" href="">installed OpenFTS</a> and enabled + OpenFTS, you can now <a class="link" href="">install</a> the OpenFTS Driver package and + Full Text Search Engine package in the OpenACS service.</p> + </li><li class="listitem"> + <p>This is a good time to make a <a class="link" href="snapshot-backup.html" title="Manual backup and recovery">backup</a> of your service. If this is a + production site, you should set up <a class="link" href="automated-backup.html" title="Automated Backup">automatic nightly backups</a>.</p> + </li><li class="listitem"> + <p>If you want traffic reports, <a class="link" href="analog-setup.html" title="Set up Log Analysis Reports">set up analog</a> or another log + processing program.</p> + </li><li class="listitem"><p>Follow the instruction on the home page to change the appearance of your service or add more - packages. (<a class="link" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site">more information</a>)</p></li><li class="listitem"><p>Proceed to the <a class="link" href="tutorial.html" title="Chapter 9. Development Tutorial">tutorial</a> to learn how to develop your own packages.</p></li><li class="listitem"><p>Set up database environment variables for the site + packages. (<a class="link" href="configuring-new-site.html" title="Chapter 4. Configuring a new OpenACS Site">more information</a>)</p> + </li><li class="listitem"><p>Proceed to the <a class="link" href="tutorial.html" title="Chapter 9. Development Tutorial">tutorial</a> to learn how to develop your own packages.</p> + </li><li class="listitem"> + <p>Set up database environment variables for the site user. Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the database while logged in as the service user. They do not directly affect the service's run-time connection with the database, because those environmental variables are set by the - wrapper scripts nsd-postgres and nsd-oracle.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>emacs .bashrc</code></strong></pre><p>Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>PostgreSQL:</p><pre class="programlisting">export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib -export PATH=$PATH:/usr/local/pgsql/bin</pre></li><li class="listitem"><p>Oracle. These environment variables are specific for a local Oracle + wrapper scripts nsd-postgres and nsd-oracle.</p> + + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>emacs .bashrc</code></strong></pre> + <p>Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p>PostgreSQL:</p> + <pre class="programlisting">export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib +export PATH=$PATH:/usr/local/pgsql/bin</pre> + </li><li class="listitem"> + <p>Oracle. These environment variables are specific for a local Oracle installation communicating via IPC. If you are connecting to a remote Oracle installation, you'll need to adjust these appropriately. Also, make sure that the '8.1.7' matches your Oracle version. -</p><pre class="programlisting">export ORACLE_BASE=/ora8/m01/app/oracle -export ORACLE_HOME=$ORACLE_BASE/product/<span class="replaceable"><span class="replaceable">8.1.7</span></span> +</p> + <pre class="programlisting">export ORACLE_BASE=/ora8/m01/app/oracle +export ORACLE_HOME=$ORACLE_BASE/product/<em class="replaceable"><code>8.1.7</code></em> export PATH=$PATH:$ORACLE_HOME/bin export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib export ORACLE_SID=ora8 export ORACLE_TERM=vt100 -export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre></li></ul></div><p>Test this by logging out and back in as - <code class="computeroutput"><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code> and checking the paths.</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> +export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre> + </li></ul></div> + + <p>Test this by logging out and back in as + <code class="computeroutput"><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code> and checking the paths.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> logout -[root src]# <strong class="userinput"><code>su - <strong class="userinput"><code><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></code></strong> +[root src]# <strong class="userinput"><code>su - <strong class="userinput"><code><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></code></strong> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>env</code></strong> -</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>For PostgreSQL, you should see:</p><pre class="screen"> +</pre> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p>For PostgreSQL, you should see:</p> + <pre class="screen"> LD_LIBRARY_PATH=:/usr/local/pgsql/lib PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\ - /root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin</pre></li><li class="listitem"><p>For Oracle:</p><pre class="screen">ORACLE_BASE=/ora8/m01/app/oracle + /root/bin:/usr/local/pgsql/bin:/usr/local/pgsql/bin</pre> + </li><li class="listitem"> + <p>For Oracle:</p> + <pre class="screen">ORACLE_BASE=/ora8/m01/app/oracle ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7 PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin:/usr/bin/X11:/usr/X11R6/bin:\ /root/bin:/ora8/m01/app/oracle/product/8.1.7/bin LD_LIBRARY_PATH=/ora8/m01/app/oracle/product/8.1.7/lib:/lib:/usr/lib ORACLE_SID=ora8 ORACLE_TERM=vt100 -ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre></li></ul></div></li><li class="listitem"><p>Test your <a class="link" href="backup-recovery.html" title="Chapter 8. Backup and Recovery">backup and recovery</a> procedure.</p></li><li class="listitem"><p>Set up <a class="xref" href="uptime.html" title="External uptime validation">the section called “External uptime validation”</a>.</p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="aolserver4.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Install AOLserver 4 </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Windows</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data</pre> + </li></ul></div> + + </li><li class="listitem"><p>Test your <a class="link" href="backup-recovery.html" title="Chapter 8. Backup and Recovery">backup and recovery</a> procedure.</p> + </li><li class="listitem"><p>Set up <a class="xref" href="uptime.html" title="External uptime validation">the section called “External uptime validation”</a>.</p> + </li></ul></div> + + <p><span class="cvstag">($Id$)</span></p> + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="aolserver4.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="win2k-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Install AOLserver 4 </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Windows</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/oracle.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/oracle.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/oracle.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="postgres" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="oracle" id="oracle"></a>Install Oracle 8.1.7</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>If you are installing PostGreSQL instead of Oracle, skip this +<a name="oracle" id="oracle"></a>Install Oracle 8.1.7</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> +</span></p><span style="color: red"></authorblurb></span><p>If you are installing PostGreSQL instead of Oracle, skip this section.</p><p>OpenACS 5.9.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See <a class="ulink" href="http://www.piskorski.com/docs/oracle.html" target="_top">Andrew Piskorski's Oracle 9i notes</a> for @@ -963,8 +960,8 @@ access to the Oracle system.</td> </tr> </tbody> -</table></div><div class="cvstag">($‌Id: oracle.xml,v 1.21.14.6 2017/06/17 -08:29:28 gustafn Exp $)</div> +</table></div><p><span class="cvstag">($‌Id: oracle.xml,v 1.22 2017/08/07 23:47:55 +gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/oracle.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/oracle.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/oracle.html 7 Aug 2017 23:47:51 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/oracle.html 8 Nov 2017 09:42:11 -0000 1.51 @@ -1,75 +1,132 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Oracle 8.1.7</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="unix-installation.html" title="Install a Unix-like system and supporting software"><link rel="next" href="postgres.html" title="Install PostgreSQL"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="unix-installation.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="oracle"></a>Install Oracle 8.1.7</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install Oracle 8.1.7</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="unix-installation.html" title="Install a Unix-like system and supporting software"><link rel="next" href="postgres.html" title="Install PostgreSQL"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="unix-installation.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="oracle"></a>Install Oracle 8.1.7</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> + </authorblurb></span> + + <p> If you are installing PostGreSQL instead of Oracle, skip this section. - </p><p> + </p> + <p> OpenACS 5.9.0 will install with Oracle 9i but has not been extensively tested so may still have bugs or tuning issues. See <a class="ulink" href="http://www.piskorski.com/docs/oracle.html" target="_top">Andrew Piskorski's Oracle 9i notes</a> for guidance. - </p><p> + </p> + + <p> This installation guide attempts to present all of the information necessary to complete an OpenACS installation. We try hard to make all of the steps possible in one pass, rather than having a step which amounts to "go away and develop a profound understanding of software X and then come back and, in 99% of all cases, type these two lines." The exception to our rule is Oracle production systems. This page describes a set of steps to get a working Oracle development server, but it is <span class="strong"><strong>unsuitable for production systems</strong></span>. If you will be using OpenACS on Oracle in a production environment, you will experience many problems unless you develop a basic understanding of Oracle which is outside the scope of this document. T - </p><p> + </p> + + <p> This document assumes that you'll be installing Oracle on the same box as AOLserver. For more details on a remote Oracle installation, see Daryl Biberdorf's <a class="ulink" href="http://openacs.org/new-file-storage/one-file?file_id=273" target="_top">document</a>. - </p><p> + </p> + <p> - Useful links to find help on how to set up Oracle under Linux are:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="ulink" href="https://www.dizwell.com/wordpress/technical-articles/oracle/" target="_top">Dizwell - - on Oracle on Linux</a></p></li><li class="listitem"><p><a class="ulink" href="http://puschitz.com/" target="_top">Werner Puschitz - Oracle on Red Hat Linux</a></p></li><li class="listitem"><p><a class="ulink" href="http://www.suse.com/us/business/certifications/certified_software/oracle/" target="_top">SuSE/Oracle Support matrix</a></p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-getit"></a>Acquire Oracle</h3></div></div></div><p> + Useful links to find help on how to set up Oracle under Linux are:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + + + <p><a class="ulink" href="https://www.dizwell.com/wordpress/technical-articles/oracle/" target="_top">Dizwell + - on Oracle on Linux</a></p> + </li><li class="listitem"> + <p><a class="ulink" href="http://puschitz.com/" target="_top">Werner Puschitz - Oracle on Red Hat Linux</a></p> + </li><li class="listitem"> + + <p><a class="ulink" href="http://www.suse.com/us/business/certifications/certified_software/oracle/" target="_top">SuSE/Oracle Support matrix</a></p> + </li></ul></div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-getit"></a>Acquire Oracle</h3></div></div></div> + + + <p> Production Oracle systems should run on certified platforms. Follow the <a class="ulink" href="http://metalink.oracle.com/metalink/plsql/ml2_documents.showDocument?p_database_id=NOT&p_id=223718.1" target="_top">metalink note 223718.1</a>to find certified platforms. If you don't have metalink access, take a look at the Oracle on Linux FAQ: <a class="ulink" href="http://www.orafaq.com/wiki/Linux_FAQ" target="_top">Which Linux Distributions Are Directly Supported By Oracle?</a>. In summary, free and inexpensive Linux distributions are not certified. - </p><p> + </p> + + <p> You can download the Oracle software from the <a class="ulink" href="https://www.oracle.com/downloads/index.html" target="_top"> Oracle Downloads</a> page. - </p><p> + </p> + + + <p> Each Oracle release comes with extensive and usually quite well-written documentation. Your first step should be to thoroughly read the release notes for your operating system and your Oracle version. Find the docs - here:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + here:</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> <a class="ulink" href="http://www.oracle.com/technetwork/documentation/oracle8i-085806.html" target="_top">Oracle 8i - Release Documentation</a></p></li><li class="listitem"><p> + Release Documentation</a></p> + </li><li class="listitem"> + <p> <a class="ulink" href="https://docs.oracle.com/cd/B10501_01/server.920/a96531/ch4_doc.htm" target="_top">Oracle 9i Release Documentation</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> <a class="ulink" href="https://docs.oracle.com/cd/B19306_01/server.102/b14214/chapter2.htm#g62359" target="_top">Oracle - 10g Release Documentation</a></p></li></ul></div><p> It is generally useful to run a particular Oracle version with its + 10g Release Documentation</a></p> + </li></ul></div> + + <p> It is generally useful to run a particular Oracle version with its latest patchset. At the time of writing these were 8.1.7.4 and 9.2.0.5, both of which are considered to be very stable. - </p><p> + </p> + + <p> To be able to download a patchset, you need a (to-pay-for) account on <a class="ulink" href="http://metalink.oracle.com" target="_top">Metalink</a>. You may find the appropriate patchset by following <a class="ulink" href="http://openacs.org/forums/message-view?message_id=33004" target="_top">Andrew's suggestion</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-keepinmind"></a>Things to Keep in Mind</h3></div></div></div><p> + </p> + +</div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-keepinmind"></a>Things to Keep in Mind</h3></div></div></div> + + + <p> Oracle is very well-documented software, the <a class="ulink" href="http://tahiti.oracle.com" target="_top">online documentation</a> comes with printable PDFs and full-text search. Altogether there is more than 20.000 pages of documentation, so do not expect to understand Oracle within in a few hours. The best starting pointing into Oracle is the Concepts book. Here's the <a class="ulink" href="http://otn.oracle.com/pls/tahiti/tahiti.to_toc?pathname=server.817%2Fa76965%2Ftoc.htm&remark=docindex" target="_top">8i version</a> and the <a class="ulink" href="http://otn.oracle.com/pls/db92/db92.to_toc?pathname=server.920%2Fa96524%2Ftoc.htm&remark=docindex" target="_top">9.2 version</a>. - </p><p> + </p> + + + <p> To give you an idea of how configurable Oracle is and how much thought you may need to put into buying the proper hardware and creating a sane setup, you should thoroughly read Cary Millsap's <a class="ulink" href="http://www.miracleas.dk/BAARF/0.Millsap1996.08.21-VLDB.pdf" target="_top">Configuring Oracle Server for VLDB</a> and the <a class="ulink" href="https://en.wikipedia.org/wiki/Optimal_Flexible_Architecture" target="_top">Optimal Flexible Architecture</a> standard. - </p><p> + </p> + + + <p> Throughout these instructions, we will refer to a number of configurable settings and advise certain defaults. With the exception of passwords, we advise you to follow these defaults unless you know what you are doing. Subsequent documents will expect that you used the defaults, so a change made here will necessitate further changes later. For a guide to the defaults, please see <a class="xref" href="oracle.html#install-oracle-defaults" title="Defaults">the section called “Defaults”</a>. - </p><p> + </p> + +<p> In order for OpenACS to work properly you need to set the environment appropriately. -</p><pre class="programlisting"> +</p> + <pre class="programlisting"> export ORACLE_BASE=/ora8/m01/app/oracle export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 export PATH=$PATH:$ORACLE_HOME/bin @@ -78,25 +135,40 @@ export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data -umask 022</pre><pre class="programlisting"> -open_cursors = 500</pre><pre class="programlisting"> -nls_date_format = "YYYY-MM-DD"</pre><p> +umask 022</pre> + <pre class="programlisting"> +open_cursors = 500</pre> + <pre class="programlisting"> +nls_date_format = "YYYY-MM-DD"</pre> + + + <p> + For additional resources/documentation, please see this <a class="ulink" href="http://openacs.org/forums/message-view?message_id=28829" target="_top">thread</a> and <a class="ulink" href="http://openacs.org/forums/message-view?message_id=67108" target="_top">Andrew Piskorski's mini-guide</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-preinstall"></a>Pre-Installation Tasks</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-preinstall"></a>Pre-Installation Tasks</h3></div></div></div> + + + <p> + Though Oracle 8.1.7 has an automated installer, we still need to perform several manual, administrative tasks before we can launch it. You must perform all of these steps as the <code class="computeroutput">root</code> user. We recommend entering the X window system as a normal user and then doing a <code class="computeroutput">su -</code>. This command gives you full root access. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + Login as a non-root user and start X by typing <code class="computeroutput">startx</code> @@ -117,84 +189,117 @@ Create and setup the <code class="computeroutput">oracle</code> group and <code class="computeroutput">oracle</code> account - </p><p> + </p> + <p> + We need to create a user <code class="computeroutput">oracle</code>, which is used to install the product, as well as starting and stopping the database. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [root ~]# groupadd dba [root ~]# groupadd oinstall [root ~]# groupadd oracle [root ~]# useradd -g dba -G oinstall,oracle -m oracle -[root ~]# passwd oracle</pre><p> +[root ~]# passwd oracle</pre> + <p> + You will be prompted for the New Password and Confirmation of that password. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has adopted <code class="computeroutput">/ora8</code> as the base directory. - </p><p> + </p> + <p> + <span class="strong"><strong>Note:</strong></span> the Oracle install needs about 1 GB free on <code class="computeroutput">/ora8</code> to install successfully. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [root ~]# mkdir /ora8 root:/ora8# cd /ora8 root:/ora8# mkdir -p m01 m02 m03/oradata/ora8 root:/ora8# chown -R oracle.dba /ora8 -root:/ora8# exit</pre></li><li class="listitem"><p> +root:/ora8# exit</pre> + </li><li class="listitem"><p> Set up the <code class="computeroutput">oracle</code> user's environment - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + Log in as the user <code class="computeroutput">oracle</code> by typing the following: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ su - oracle -Password: ********</pre></li><li class="listitem"><p> +Password: ********</pre> + </li><li class="listitem"><p> Use a text editor to edit the <code class="computeroutput">.bash_profile</code> file in the <code class="computeroutput">oracle</code> account home directory. - </p><pre class="programlisting"> -[oracle ~]$ emacs .bash_profile</pre><p> + </p> + <pre class="programlisting"> +[oracle ~]$ emacs .bash_profile</pre> + + <p> + You may get this error trying to start emacs: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> Xlib: connection to ":0.0" refused by server Xlib: Client is not authorized to connect to Server emacs: Cannot connect to X server :0. Check the DISPLAY environment variable or use `-d'. Also use the `xhost' program to verify that it is set to permit -connections from your machine.</pre><p> +connections from your machine.</pre> + <p> + If so, open a new terminal window and do the following: - </p><pre class="programlisting"> -[joeuser ~]$ xhost +localhost</pre><p> + </p> + <pre class="programlisting"> +[joeuser ~]$ xhost +localhost</pre> + + <p> + Now, back in the oracle terminal: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [oracle ~]$ export DISPLAY=localhost:0.0 -[oracle ~]$ emacs .bash_profile</pre><p> +[oracle ~]$ emacs .bash_profile</pre> + <p> + Try this procedure anytime you get an Xlib connection refused error. @@ -204,7 +309,9 @@ Oracle version number as needed) to <code class="computeroutput">.bash_profile</code>: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> export ORACLE_BASE=/ora8/m01/app/oracle export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 export PATH=$PATH:$ORACLE_HOME/bin @@ -213,32 +320,45 @@ export ORACLE_TERM=vt100 export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data -umask 022</pre><p> +umask 022</pre> + <p> + Save the file by typing <code class="computeroutput">CTRL-X CTRL-S</code> and then exit by typing <code class="computeroutput">CTRL-X CTRL-C</code>. Alternatively, use the menus. - </p></li></ul></div><p> + </p> + </li></ul></div> + <p> + Make sure that you do <span class="strong"><strong>not</strong></span> add any lines like the following - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> # NLS_LANG=american -# export NLS_LANG</pre><p> +# export NLS_LANG</pre> + <p> + These lines will change the Oracle date settings and will break OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD dates. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Log out as oracle - </p><pre class="programlisting"> -[oracle ~]$ exit</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +[oracle ~]$ exit</pre> + </li><li class="listitem"><p> Log back in as <code class="computeroutput">oracle</code> and double check that your environment variables are as intended. The @@ -247,19 +367,27 @@ <code class="computeroutput">grep</code> shows you just the lines you want (those with ORA in it). - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ su - oracle -[oracle ~]$ env | grep ORA</pre><p> +[oracle ~]$ env | grep ORA</pre> + <p> + If it worked, you should see: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> ORACLE_SID=ora8 ORACLE_BASE=/ora8/m01/app/oracle ORACLE_TERM=vt100 ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7 -ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data</pre><p> +ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data</pre> + <p> + If not, try adding the files to <code class="computeroutput">~/.bashrc</code> instead of <code class="computeroutput">.bash_profile</code>. Then logout and @@ -271,93 +399,141 @@ <code class="computeroutput">.bash_profile</code> will be evaluated. - </p><p> + </p> + <p> + Make sure that <code class="computeroutput">/bin</code>, <code class="computeroutput">/usr/bin</code>, and <code class="computeroutput">/usr/local/bin</code> are in your path by typing: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [oracle ~]$ echo $PATH -/bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin</pre><p> +/bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin</pre> + <p> + If they are not, then add them to the <code class="computeroutput">.bash_profile</code> by changing the PATH statement above to <code class="computeroutput">PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin</code> - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-install"></a>Installing Oracle 8.1.7 Server</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-install"></a>Installing Oracle 8.1.7 Server</h3></div></div></div> + + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Log in as <code class="computeroutput">oracle</code> and start X if not already running. Start a new terminal: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ xhost +localhost [joeuser ~]$ su - oracle Password: ********** -[oracle ~]$ export DISPLAY=localhost:0.0</pre></li><li class="listitem"><p> +[oracle ~]$ export DISPLAY=localhost:0.0</pre> + </li><li class="listitem"><p> Find the <code class="computeroutput">runInstaller</code> script - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + If you are installing Oracle from a CD-ROM, it is located in the <code class="computeroutput">install/linux</code> path from the cd-rom mount point - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [oracle ~]$ su - root [root ~]# mount -t iso9660 /dev/cdrom /mnt/cdrom [root ~]# exit -[oracle ~]$ cd /mnt/cdrom</pre></li><li class="listitem"><p> +[oracle ~]$ cd /mnt/cdrom</pre> + </li><li class="listitem"><p> If you are installing from the tarball, the install script is located in the <code class="computeroutput">Oracle8iR2</code> directory that was created when you expanded the archive. - </p><pre class="programlisting"> -[oracle ~]$ cd /where/oracle/Disk1</pre></li></ul></div><p> + </p> + <pre class="programlisting"> +[oracle ~]$ cd /where/oracle/Disk1</pre> + </li></ul></div> + + <p> + Check to make sure the file is there. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> oracle:/where/oracle/Disk1$ ls -doc index.htm install runInstaller stage starterdb</pre><p> +doc index.htm install runInstaller stage starterdb</pre> + <p> + If you don't see <code class="computeroutput">runInstaller</code>, you are in the wrong directory. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Run the installer - </p><pre class="programlisting"> -oracle:/where/oracle/Disk1$ ./runInstaller</pre><p> + </p> + <pre class="programlisting"> +oracle:/where/oracle/Disk1$ ./runInstaller</pre> + + <p> + A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on "<code class="computeroutput">Next</code>" - </p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p> + </p> + + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3> + <p> Some people have had trouble with this step on RedHat 7.3 and 8.0. If so, try the following steps before calling <span class="command"><strong>./runInstaller</strong></span>: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> Execute the following command: <span class="command"><strong>/usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh</strong></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Type <span class="command"><strong>export LD_ASSUME_KERNEL=2.2.5</strong></span> - </p></li></ol></div></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </div> + </li><li class="listitem"><p> The "File Locations" screen in the OUI: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + "Source" path should have been prefilled with "(wherever you mounted the CDROM)<code class="computeroutput">/stage/products.jar</code>" @@ -367,26 +543,32 @@ "destination" path says "<code class="computeroutput">/ora8/m01/app/oracle/product/8.1.7</code>" - </p><p> + </p> + <p> + If the destination is not correct it is because your environment variables are not set properly. Make sure you logged on as <code class="computeroutput">oracle</code> using <code class="computeroutput">su - oracle</code>. If so, edit the <code class="computeroutput">~/.bash_profile</code> as you did in <a class="xref" href="oracle.html#install-oracle-preinstall" title="Pre-Installation Tasks">the section called “Pre-Installation Tasks”</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Click "Next" (a pop up window will display Loading Product information). - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Unix Group Name" screen in the OUI: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + The Unix Group name needs to be set to '<code class="computeroutput">oinstall</code>' ( we made this Unix group earlier ). @@ -395,64 +577,95 @@ Click "Next" - </p></li><li class="listitem"><p> + </p></li><li class="listitem"> + <p> A popup window appears instantly, requesting you to run a script as root: - </p></li><li class="listitem"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p> + </p> + </li><li class="listitem"> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"> + <p> Debian users need to link <code class="computeroutput">/bin/awk</code> to <code class="computeroutput">/usr/bin/awk</code> before running the script below - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> [joueser ~]$ su - -[root ~]# ln -s /usr/bin/awk /bin/awk</pre></li></ul></div></li><li class="listitem"><p> +[root ~]# ln -s /usr/bin/awk /bin/awk</pre> + </li></ul></div> + </li><li class="listitem"> + <p> Open a new terminal window, then type: - </p><pre class="programlisting">[joeuser ~]$ su - + </p> + + <pre class="programlisting">[joeuser ~]$ su - [root ~]# cd /ora8/m01/app/oracle/product/8.1.7 [root ~]# ./orainstRoot.sh ; You should see: Creating Oracle Inventory pointer file (/etc/oraInst.loc) Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall. [root ~]# mkdir -p /usr/local/java [root ~]# exit -[joeuser ~]$ exit</pre></li><li class="listitem"><p> +[joeuser ~]$ exit</pre> + + </li><li class="listitem"><p> Click "Retry" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"> + <p> The "Available Products" screen in the OUI: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "Oracle 8i Enterprise Edition 8.1.7.1.0" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"> + <p> The "Installation Types" screen - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p> Select the "Custom" installation type. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Available Product Components" screen - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> In addition to the defaults, make sure that "Oracle SQLJ 8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and "Linux Documentation 8.1.7.0.0" are also checked. </p></li><li class="listitem"><p> Click "Next" </p></li><li class="listitem"><p> A progress bar will appear for about 1 minute. - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Component Locations" screen in the OUI - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Click on the "Java Runtime Environment 1.1.8" It should have the path "<code class="computeroutput">/ora8/m01/app/oracle/jre/1.1.8</code>" </p></li><li class="listitem"><p> Click "Next" </p></li><li class="listitem"><p> A progress bar will appear for about 1 minute. - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Privileged Operation System Groups" screen in the OUI - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Enter "dba" for "Database Administrator (OSDBA) Group" </p></li><li class="listitem"><p> @@ -462,27 +675,34 @@ Click "Next" </p></li><li class="listitem"><p> A progress bar will appear for about 1 minute. - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Authentication Methods" screen - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The next screen is "Choose JDK home directory" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Keep the default path: <code class="computeroutput">/usr/local/java</code> </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Create a Database" screen in the OUI - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "No" as we will do this later, after some important configuration changes. @@ -491,11 +711,14 @@ Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The next screen is "Oracle Product Support" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> TCP should be checked with "Status" listed as Required @@ -504,11 +727,14 @@ Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Summary" screen in the OUI - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Check the "Space Requirements" section to verify you have enough disk space for the install. @@ -530,7 +756,9 @@ to set the environment appropriately and then do <span class="command"><strong>su</strong></span> to get root privileges, while keeping the oracle user's environment. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ su - oracle Password: ********* [oracle ~]$ su @@ -561,22 +789,31 @@ created by the Oracle Enterprise Manager Intelligent Agent. These files may be found in the directories you use for storing other Net8 log and trace files. - If such files exist, the OEM IA may not restart.</pre></li><li class="listitem"><p> + If such files exist, the OEM IA may not restart.</pre> + </li><li class="listitem"><p> Do not follow the instructions on deleting trace and log files, it is not necessary. - </p></li></ul></div><pre class="programlisting"> + </p></li></ul></div> + + <pre class="programlisting"> [root ~]# exit -[joeuser ~]$ exit</pre></li><li class="listitem"><p> +[joeuser ~]$ exit</pre> + </li><li class="listitem"><p> Go back to the pop-up window and click "OK" </p></li><li class="listitem"><p> The "Configuration Tools" screen in the OUI - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> This window displays the config tools that will automatically be launched. - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Welcome" screen in the "net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Make sure the "Perform Typical installation" is <span class="strong"><strong>not</strong></span> selected. </p></li><li class="listitem"><p> @@ -588,104 +825,156 @@ Select "No" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Listener Configuration, Listener Name" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Accept the default listener name of "LISTENER" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Listener Configuration, Select Protocols" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> The only choice in "Select protocols:" should be "TCP/IP" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Listener Configuration TCP/IP Protocol" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Default Port should be 1521 and selected. </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Listener Configuration, More Listeners" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "No" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Listener Configuration Done" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Naming Methods Configuration" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "No" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Done" screen in the "Net 8 Configuration Assistant" - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Click "Finish" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "End of Installation" screen in the OUI - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Click "Exit" </p></li><li class="listitem"><p> Click "Yes" on the confirmation pop up window. </p></li><li class="listitem"><p> The Oracle Universal Installer window should have disappeared! - </p></li></ul></div></li></ul></div><p> + </p></li></ul></div> + </li></ul></div> + + <p> Congratulations, you have just installed Oracle 8.1.7 Server! However, you still need to create a database which can take about an hour of non-interactive time, so don't quit yet. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-create"></a>Creating the First Database</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-create"></a>Creating the First Database</h3></div></div></div> + + + <p> This step will take you through the steps of creating a customized database. Be warned that this process takes about an hour on a Pentium II with 128 MB of RAM. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Make sure you are running X. Open up a terminal and <code class="computeroutput">su</code> to oracle and then run the <code class="computeroutput">dbassist</code> program. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ xhost +localhost [joeuser ~]$ su - oracle Password: ********* [oracle ~]$ export DISPLAY=localhost:0.0 -[oracle ~]$ dbassist</pre></li><li class="listitem"><p> +[oracle ~]$ dbassist</pre> + + </li><li class="listitem"><p> The "Welcome" screen in the Oracle Database Configuration Agent (ODCA) - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "Create a database" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Select database type" screen in the ODCA - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "Custom" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "Primary Database Type" window in ODCA - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "Multipurpose" </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> The "concurrent users" screen of the ODCA - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Select "60" concurrent users. </p></li><li class="listitem"><p> Click "Next" - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + + </li><li class="listitem"><p> Select "<code class="computeroutput">Dedicated Server Mode</code>", click "<code class="computeroutput">Next</code>" @@ -757,20 +1046,29 @@ of <code class="computeroutput">/ora8/m01/app/oracle/product/8.1.7</code>, the following will open the file for editing. - </p><pre class="programlisting"> -[oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +[oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora</pre> + </li><li class="listitem"><p> Add the following line to the end: - </p><pre class="programlisting"> -nls_date_format = "YYYY-MM-DD"</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +nls_date_format = "YYYY-MM-DD"</pre> + </li><li class="listitem"><p> Now find the <code class="computeroutput">open_cursors</code> line in the file. If you're using <code class="computeroutput">emacs</code> scroll up to the top of the buffer and do <code class="computeroutput">CTRL-S</code> and type <code class="computeroutput">open_cursors</code> to find the line. The default is <code class="computeroutput">100</code>. Change it to <code class="computeroutput">500</code>. - </p><pre class="programlisting"> -open_cursors = 500</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +open_cursors = 500</pre> + </li><li class="listitem"><p> Save the file. In emacs, do <code class="computeroutput">CTRL-X CTRL-S</code> to save followed by <code class="computeroutput">CTRL-X CTRL-C</code> to exit or use @@ -788,9 +1086,13 @@ </p></li><li class="listitem"><p> Change to the directory where the database creation script is and run it: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [oracle ~]$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib -oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh</pre><p> +oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh</pre> + + <p> In some instances, Oracle will save the file to <code class="computeroutput">/ora8/m01/app/oracle/product/8.1.7/assistants/dbca</code> Try running the script there if your first attempt does not @@ -800,49 +1102,79 @@ fooling. You will see lots of errors scroll by (like: "ORA-01432: public synonym to be dropped does not exist") Fear not, this is normal. - </p><p> + </p> + + <p> Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="istall-oracle-test"></a>Acceptance Test</h3></div></div></div><p> + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="istall-oracle-test"></a>Acceptance Test</h3></div></div></div> + + + <p> For this step, open up a terminal and <code class="computeroutput">su</code> to <code class="computeroutput">oracle</code> as usual. You should be running X and Netscape (or other web browser) for this phase. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> You need to download the "Oracle Acceptance Test" file. It's available <a class="ulink" href="files/acceptance-sql.txt" target="_top">here</a> and at <a class="ulink" href="http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt" target="_top">http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt</a>. Save the file to <code class="computeroutput">/var/tmp</code> </p></li><li class="listitem"><p> In the oracle shell, copy the file. - </p><pre class="programlisting"> -[oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +[oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql</pre> + </li><li class="listitem"><p> Once you've got the acceptance test file all set, stay in your term and type the following: - </p><pre class="programlisting"> -[oracle ~]$ sqlplus system/manager</pre><p> + </p> + + <pre class="programlisting"> +[oracle ~]$ sqlplus system/manager</pre> + + <p> SQL*Plus should startup. If you get an <code class="computeroutput">ORA-01034: Oracle not Available</code> error, it is because your Oracle instance is not running. You can manually start it as - the <code class="computeroutput">oracle</code> user.</p><pre class="programlisting"> + the <code class="computeroutput">oracle</code> user.</p> + + <pre class="programlisting"> [oracle ~]$ svrmgrl SVRMGR> connect internal -SVRMGR> startup</pre></li><li class="listitem"><p> +SVRMGR> startup</pre> + </li><li class="listitem"><p> Now that you're into SQL*Plus, change the default passwords for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember): - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> SQL> alter user system identified by alexisahunk; SQL> alter user sys identified by alexisahunk; -SQL> alter user ctxsys identified by alexisahunk;</pre></li><li class="listitem"><p> +SQL> alter user ctxsys identified by alexisahunk;</pre> + </li><li class="listitem"><p> Verify that your date settings are correct. - </p><pre class="programlisting"> -SQL> select sysdate from dual;</pre><p> + </p> + + <pre class="programlisting"> +SQL> select sysdate from dual;</pre> + + <p> If you don't see a date that fits the format <code class="computeroutput">YYYY-MM-DD</code>, please read <a class="xref" href="oracle.html#install-oracle-troubleshooting" title="Troubleshooting Oracle Dates">the section called “Troubleshooting Oracle Dates”</a>. </p></li><li class="listitem"><p> At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> SQL> @ /var/tmp/acceptance.sql ; A bunch of lines will scroll by. You'll know if the test worked if @@ -852,12 +1184,18 @@ ---------- 2000-06-10 -SQL></pre><p> +SQL></pre> + + <p> Many people encounter an error regarding <code class="computeroutput">maximum key length</code>: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> ERROR at line 1: -ORA-01450: maximum key length (758) exceeded</pre><p> +ORA-01450: maximum key length (758) exceeded</pre> + + <p> This error occurs if your database block size is wrong and is usually suffered by people trying to load OpenACS into a pre-existing database. Unfortunately, the only solution is to @@ -868,14 +1206,25 @@ <code class="computeroutput">dbassist</code> program or by setting the <code class="computeroutput">DB_BLOCK_SIZE</code> parameter in your database's creation script. - </p><p> + </p> + + <p> If there were no errors, then consider yourself fortunate. Your Oracle installation is working. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-automating"></a>Automating Startup & Shutdown</h3></div></div></div><p> + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-automating"></a>Automating Startup & Shutdown</h3></div></div></div> + + + <p> You will want to automate the database startup and shutdown process. It's probably best to have Oracle spring to life when you boot up your machine. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Oracle includes a script called <code class="computeroutput">dbstart</code> that can be used to automatically start the database. Unfortunately, the script @@ -884,46 +1233,68 @@ it. First, save <a class="ulink" href="files/dbstart.txt" target="_top">dbstart</a> to <code class="computeroutput">/var/tmp</code>. Then, as <code class="computeroutput">oracle</code>, do the following: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart -[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart</pre></li><li class="listitem"><p> +[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart</pre> + </li><li class="listitem"><p> While you're logged in as <code class="computeroutput">oracle</code>, you should configure the <code class="computeroutput">oratab</code> file to load your database at start. Edit the file <code class="computeroutput">/etc/oratab</code>: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>You will see this line. </p><pre class="programlisting"> -ora8:/ora8/m01/app/oracle/product/8.1.7:N</pre><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>You will see this line. </p> + + <pre class="programlisting"> +ora8:/ora8/m01/app/oracle/product/8.1.7:N</pre> + + <p> By the way, if you changed the service name or have multiple databases, the format of this file is: - </p><p> + </p> + + <p> <span class="emphasis"><em><code class="computeroutput">service_name:$ORACLE_HOME:Y || N (for autoload)</code></em></span> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> Change the last letter from "N" to "Y". This tells Oracle that you want the database to start when the machine boots. It should look like this. - </p><pre class="programlisting"> -ora8:/ora8/m01/app/oracle/product/8.1.7:Y</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +ora8:/ora8/m01/app/oracle/product/8.1.7:Y</pre> + + </li><li class="listitem"><p> Save the file & quit the terminal. - </p></li></ul></div></li><li class="listitem"><p> + </p></li></ul></div> + </li><li class="listitem"><p> You need a script to automate startup and shutdown. Save <a class="ulink" href="files/oracle8i.txt" target="_top">oracle8i.txt</a> in <code class="computeroutput">/var/tmp</code>. Then login as <code class="computeroutput">root</code> and install the script. (Debian users: substitute <code class="computeroutput">/etc/init.d</code> for <code class="computeroutput">/etc/rc.d/init.d</code> throughout this section) - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [oracle ~]$ su - [root ~]# cp /var/tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i [root ~]# chown root.root /etc/rc.d/init.d/oracle8i -[root ~]# chmod 755 /etc/rc.d/init.d/oracle8i</pre></li><li class="listitem"><p> +[root ~]# chmod 755 /etc/rc.d/init.d/oracle8i</pre> + </li><li class="listitem"><p> Test the script by typing the following commands and checking the output. (Debian Users: as root, do <code class="computeroutput">mkdir /var/lock/subsys</code> first) - </p><pre class="programlisting"> + </p> + +<pre class="programlisting"> [root ~]# /etc/rc.d/init.d/oracle8i stop Oracle 8i auto start/stop Shutting Oracle8i: @@ -966,15 +1337,21 @@ Database "ora8" warm started. -Database "ora8" warm started.</pre></li><li class="listitem"><p> +Database "ora8" warm started.</pre> + </li><li class="listitem"><p> If it worked, then run these commands to make the startup and shutdown automatic. - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Red Hat users:</p><pre class="programlisting"> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Red Hat users:</p> + <pre class="programlisting"> [root ~]# cd /etc/rc.d/init.d/ [root ~]# chkconfig --add oracle8i [root ~]# chkconfig --list oracle8i ; You should see: -oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre></li><li class="listitem"><p>Debian users:</p><pre class="programlisting"> +oracle8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre> + </li><li class="listitem"><p>Debian users:</p> + <pre class="programlisting"> [root ~]# update-rc.d oracle8i defaults Adding system startup for /etc/init.d/oracle8i ... /etc/rc0.d/K20oracle8i -> ../init.d/oracle8i @@ -983,7 +1360,9 @@ /etc/rc2.d/S20oracle8i -> ../init.d/oracle8i /etc/rc3.d/S20oracle8i -> ../init.d/oracle8i /etc/rc4.d/S20oracle8i -> ../init.d/oracle8i - /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i</pre></li><li class="listitem"><p>SuSE users:</p><pre class="programlisting"> + /etc/rc5.d/S20oracle8i -> ../init.d/oracle8i</pre> + </li><li class="listitem"><p>SuSE users:</p> + <pre class="programlisting"> [root ~]# cd /etc/rc.d/init.d root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i K20oracle8i root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/oracle8i S20oracle8i @@ -1023,25 +1402,36 @@ Executing /sbin/conf.d/SuSEconfig.tetex... Executing /sbin/conf.d/SuSEconfig.ypclient... Processing index files of all manpages... -Finished.</pre></li></ul></div></li><li class="listitem"><p> +Finished.</pre> + </li></ul></div> + + </li><li class="listitem"><p> You also need some scripts to automate startup and shutdown of the Oracle8i listener. The listener is a name server that allows your Oracle programs to talk to local and remote databases using a standard naming convention. It is required for Intermedia Text and full site search. - </p><p> + </p> + + <p> Download these three scripts into <code class="computeroutput">/var/tmp</code> - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> <a class="ulink" href="files/startlsnr.txt" target="_top">startlsnr.txt</a> </p></li><li class="listitem"><p> <a class="ulink" href="files/stoplsnr.txt" target="_top">stoplsnr.txt</a> </p></li><li class="listitem"><p> <a class="ulink" href="files/listener8i.txt" target="_top">listener8i.txt</a> - </p></li></ul></div><p> + </p></li></ul></div> + + <p> Now issue the following commands (still as <code class="computeroutput">root</code>). - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [root ~]# su - oracle [oracle ~]$ cp /var/tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr [oracle ~]$ cp /var/tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr @@ -1050,10 +1440,14 @@ [oracle ~]$ exit [root ~]# cp /var/tmp/listener8i.txt /etc/rc.d/init.d/listener8i [root ~]# cd /etc/rc.d/init.d -root:/etc/rc.d/init.d# chmod 755 listener8i</pre><p> +root:/etc/rc.d/init.d# chmod 755 listener8i</pre> + + <p> Test the listener automation by running the following commands and checking the output. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> root:/etc/rc.d/init.d# ./listener8i stop Oracle 8i listener start/stop Shutting down Listener for 8i: @@ -1095,14 +1489,20 @@ Services Summary... PLSExtProc has 1 service handler(s) ora8 has 1 service handler(s) -The command completed successfully</pre><p> +The command completed successfully</pre> + + <p> This test will verify that the listener is operating normally. Login into the database using the listener naming convention. - </p><p> + </p> + + <p> <code class="computeroutput">sqlplus</code> <span class="emphasis"><em><code class="computeroutput">username/password/@SID</code></em></span> - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [root ~]# su - oracle [oracle ~]$ sqlplus system/alexisahunk@ora8 @@ -1114,17 +1514,24 @@ SQL> exit [oracle ~]$ exit -[root ~]#</pre><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>RedHat users:</p><p> +[root ~]#</pre> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>RedHat users:</p> + <p> Now run <code class="computeroutput">chkconfig</code> on the <code class="computeroutput">listener8i</code> script. - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> [root ~]# cd /etc/rc.d/init.d/ root:/etc/rc.d/init.d# chkconfig --add listener8i root:/etc/rc.d/init.d# chkconfig --list listener8i -listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre></li><li class="listitem"><p>Debian users:</p><p> +listener8i 0:off 1:off 2:off 3:on 4:on 5:on 6:off</pre> + </li><li class="listitem"><p>Debian users:</p> + <p> Now run <code class="computeroutput">update-rc.d</code> on the <code class="computeroutput">listener8i</code> script. - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> [root ~]# update-rc.d listener8i defaults 21 19 Adding system startup for /etc/init.d/listener8i ... /etc/rc0.d/K19listener8i -> ../init.d/listener8i @@ -1133,54 +1540,89 @@ /etc/rc2.d/S21listener8i -> ../init.d/listener8i /etc/rc3.d/S21listener8i -> ../init.d/listener8i /etc/rc4.d/S21listener8i -> ../init.d/listener8i - /etc/rc5.d/S21listener8i -> ../init.d/listener8i</pre></li></ul></div></li><li class="listitem"><p> + /etc/rc5.d/S21listener8i -> ../init.d/listener8i</pre> + </li></ul></div> + </li><li class="listitem"><p> Test the automation - </p><p> + </p> + + <p> As a final test, reboot your computer and make sure Oracle comes up. You can do this by typing - </p><pre class="programlisting"> -[root ~]# /sbin/shutdown -r -t 0 now</pre><p> + </p> + + <pre class="programlisting"> +[root ~]# /sbin/shutdown -r -t 0 now</pre> + + <p> Log back in and ensure that Oracle started automatically. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ su - oracle [oracle ~]$ sqlplus system/alexisahunk@ora8 -SQL> exit</pre></li></ul></div><p> +SQL> exit</pre> + </li></ul></div> + + <p> Congratulations, your installation of Oracle 8.1.7 is complete. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-troubleshooting"></a>Troubleshooting Oracle Dates</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-troubleshooting"></a>Troubleshooting Oracle Dates</h3></div></div></div> + + + <p> Oracle has an internal representation for storing the data based on the number of seconds elapsed since some date. However, for the purposes of inputing dates into Oracle and getting them back out, Oracle needs to be told to use a specific date format. By default, it uses an Oracle-specific format which isn't copacetic. You want Oracle to use the ANSI-compliant date format which is of form <code class="computeroutput">'YYYY-MM-DD'</code>. - </p><p> + </p> + + <p> To fix this, you should include the following line in <code class="computeroutput">$ORACLE_HOME/dbs/init</code><span class="emphasis"><em>SID</em></span><code class="computeroutput">.ora</code> or for the default case, <code class="computeroutput">$ORACLE_HOME/dbs/initora8.ora</code> - </p><pre class="programlisting"> -nls_date_format = "YYYY-MM-DD"</pre><p> + </p> + + <pre class="programlisting"> +nls_date_format = "YYYY-MM-DD"</pre> + + <p> You test whether this solved the problem by firing up <code class="computeroutput">sqlplus</code> and typing: - </p><pre class="programlisting"> -SQL> select sysdate from dual;</pre><p> + </p> + + <pre class="programlisting"> +SQL> select sysdate from dual;</pre> + + <p> You should see back a date like <code class="computeroutput">2000-06-02</code>. If some of the date is chopped off, i.e. like <code class="computeroutput">2000-06-0</code>, everything is still fine. The problem here is that <code class="computeroutput">sqlplus</code> is simply truncating the output. You can fix this by typing: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> SQL> column sysdate format a15 -SQL> select sysdate from dual;</pre><p> +SQL> select sysdate from dual;</pre> + + <p> If the date does not conform to this format, double-check that you included the necessary line in the init scripts. If it still isn't working, make sure that you have restarted the database since adding the line: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> [joeuser ~]$ svrmgrl SVRMGR> connect internal Connected. @@ -1189,41 +1631,91 @@ Database dismounted. ORACLE instance shut down. SVRMGR> startup -ORACLE instance started.</pre><p> +ORACLE instance started.</pre> + + <p> If you're sure that you have restarted the database since adding the line, check your initialization scripts. Make sure that the following line is not included: - </p><pre class="programlisting"> -export nls_lang = american</pre><p> + </p> + + <pre class="programlisting"> +export nls_lang = american</pre> + + <p> Setting this environment variable will override the date setting. Either delete this line and login again or add the following entry to your login scripts <span class="emphasis"><em>after</em></span> the <code class="computeroutput">nls_lang</code> line: - </p><pre class="programlisting"> -export nls_date_format = 'YYYY-MM-DD'</pre><p> + </p> + + <pre class="programlisting"> +export nls_date_format = 'YYYY-MM-DD'</pre> + + <p> Log back in again. If adding the <code class="computeroutput">nls_date_format</code> line doesn't help, you can ask for advice in our <a class="ulink" href="http://www.openacs.org/forums/" target="_top">OpenACS forums</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-procs"></a>Useful Procedures</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-procs"></a>Useful Procedures</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Dropping a tablespace - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Run sqlplus as the dba: - </p><pre class="programlisting"> -[oracle ~]$ sqlplus system/changeme</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +[oracle ~]$ sqlplus system/changeme</pre> + </li><li class="listitem"><p> To drop a user and all of the tables and data owned by that user: - </p><pre class="programlisting"> -SQL> drop user <span class="emphasis"><em>oracle_user_name</em></span> cascade;</pre></li><li class="listitem"><p> + </p> + + <pre class="programlisting"> +SQL> drop user <span class="emphasis"><em>oracle_user_name</em></span> cascade;</pre> + </li><li class="listitem"><p> To drop the tablespace: This will delete everything in the tablespace overriding any referential integrity constraints. Run this command only if you want to clean out your database entirely. - </p><pre class="programlisting"> -SQL> drop tablespace <span class="emphasis"><em>table_space_name</em></span> including contents cascade constraints;</pre></li></ul></div></li></ul></div><p> + </p> + <pre class="programlisting"> +SQL> drop tablespace <span class="emphasis"><em>table_space_name</em></span> including contents cascade constraints;</pre> + </li></ul></div> + </li></ul></div> + + <p> For more information on Oracle, please consult the <a class="ulink" href="https://docs.oracle.com/en/database/" target="_top">documentation</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="oracle-next-steps"></a>Oracle Next Steps</h3></div></div></div><p><a class="xref" href="maint-performance.html#install-oracle-monitoring" title="Creating an appropriate tuning and monitoring environment">the section called “Creating an appropriate tuning and monitoring environment”</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-defaults"></a>Defaults</h3></div></div></div><p>We used the following defaults while installing Oracle.</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Value</th><th>Reason</th></tr></thead><tbody><tr><td>ORACLE_HOME</td><td>/ora8/m01/app/oracle/product/8.1.7</td><td>This is the default Oracle installation directory.</td></tr><tr><td>ORACLE_SERVICE</td><td>ora8</td><td>The service name is a domain-qualified identifier for + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="oracle-next-steps"></a>Oracle Next Steps</h3></div></div></div> + + <p><a class="xref" href="maint-performance.html#install-oracle-monitoring" title="Creating an appropriate tuning and monitoring environment">the section called “Creating an appropriate tuning and monitoring environment”</a></p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-oracle-defaults"></a>Defaults</h3></div></div></div> + + + <p>We used the following defaults while installing Oracle.</p> + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>Variable</th><th>Value</th><th>Reason</th></tr></thead><tbody><tr><td>ORACLE_HOME</td><td>/ora8/m01/app/oracle/product/8.1.7</td><td>This is the default Oracle installation directory.</td></tr><tr><td>ORACLE_SERVICE</td><td>ora8</td><td>The service name is a domain-qualified identifier for your Oracle server.</td></tr><tr><td>ORACLE_SID</td><td>ora8</td><td>This is an identifier for your Oracle server.</td></tr><tr><td>ORACLE_OWNER</td><td>oracle</td><td>The user who owns all of the oracle files.</td></tr><tr><td>ORACLE_GROUP</td><td>dba</td><td>The special oracle group. Users in the dba group are authorized to do a <code class="computeroutput">connect internal</code> within <code class="computeroutput">svrmgrl</code> to gain full system - access to the Oracle system.</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unix-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr><tr><td width="40%" align="left">Install a Unix-like system and supporting software </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install PostgreSQL</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + access to the Oracle system.</td></tr></tbody></table> + </div> + + <p><span class="cvstag">($Id$)</span></p> + </div> + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="unix-installation.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="postgres.html">Next</a></td></tr><tr><td width="40%" align="left">Install a Unix-like system and supporting software </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install PostgreSQL</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/os-install.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-install.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/os-install.html 7 Aug 2017 23:47:51 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/os-install.html 8 Nov 2017 09:42:11 -0000 1.18 @@ -1,5 +1,9 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Linux Install Guides</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="install-origins.html" title="Where did this document come from?"><link rel="next" href="os-security.html" title="Security Information"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-origins.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="os-security.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="os-install"></a>Linux Install Guides</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Linux Install Guides</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="install-origins.html" title="Where did this document come from?"><link rel="next" href="os-security.html" title="Security Information"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-origins.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="os-security.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="os-install"></a>Linux Install Guides</h2></div></div></div> + + <p> Here's a list of some helpful documentation for <a class="ulink" href="http://openacs.org/xowiki/openacs-system-install" target="_top">installing OpenACS on various operating systems</a> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-origins.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="os-security.html">Next</a></td></tr><tr><td width="40%" align="left">Where did this document come from? </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Security Information</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-origins.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="os-security.html">Next</a></td></tr><tr><td width="40%" align="left">Where did this document come from? </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Security Information</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/os-security.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/os-security.html,v diff -u -r1.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/os-security.html 7 Aug 2017 23:47:51 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/os-security.html 8 Nov 2017 09:42:11 -0000 1.18 @@ -1,5 +1,7 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Information</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="os-install.html" title="Linux Install Guides"><link rel="next" href="install-resources.html" title="Resources"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="os-install.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="install-resources.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="os-security"></a>Security Information</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Information</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="credits.html" title="Appendix C. Credits"><link rel="previous" href="os-install.html" title="Linux Install Guides"><link rel="next" href="install-resources.html" title="Resources"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="os-install.html">Prev</a> </td><th width="60%" align="center">Appendix C. Credits</th><td width="20%" align="right"> <a accesskey="n" href="install-resources.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="os-security"></a>Security Information</h2></div></div></div> + + <p> Once you get your OS installed, it's imperative that you secure your installation. As Jon Griffin repeatedly warns us, "No distribution is secure out of the box." The Reference Platform implements @@ -9,9 +11,13 @@ security, such as monitoring the state of a computer, maintaining patch levels, and keeping backups. We recommend these resources: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> <a class="ulink" href="http://www.openna.com/products/books/sol/solus.php" target="_top">Securing and Optimizing Linux - version 2.0</a> - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"><p> <a class="ulink" href="https://web.archive.org/web/20060622032854/http://jongriffin.com/static/linuxnotes" target="_top">Jon Griffin's notes</a> </p></li><li class="listitem"><p> @@ -23,4 +29,6 @@ </p></li><li class="listitem"><p> <a class="ulink" href="http://www.counterpane.com/crypto-gram.html" target="_top">Bruce Schneier's Crypto-Gram</a>, especially <a class="ulink" href="http://www.counterpane.com/crypto-gram-0103.html#1" target="_top">The - security patch treadmill</a> and <a class="ulink" href="http://www.counterpane.com/crypto-gram-0107.html#5" target="_top">Monitoring First</a>.</p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="os-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-resources.html">Next</a></td></tr><tr><td width="40%" align="left">Linux Install Guides </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Resources</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + security patch treadmill</a> and <a class="ulink" href="http://www.counterpane.com/crypto-gram-0107.html#5" target="_top">Monitoring First</a>.</p> + </li></ul></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="os-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-resources.html">Next</a></td></tr><tr><td width="40%" align="left">Linux Install Guides </td><td width="20%" align="center"><a accesskey="u" href="credits.html">Up</a></td><td width="40%" align="right"> Resources</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/packages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/packages.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/packages.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="objects" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="packages" id="packages"></a>OpenACS Packages</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su and Bryan Quinn</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="packages" id="packages"></a>OpenACS Packages</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su and Bryan Quinn</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="packages-overview" id="packages-overview"></a>Overview</h3></div></div></div><p>This document is a guide on how to write a software package for OpenACS. OpenACS packages are installed and maintained with the @@ -25,7 +22,7 @@ <div class="titlepage"><div><div><h3 class="title"> <a name="server-file-layout" id="server-file-layout"></a>Server file layout</h3></div></div></div><p>Here is how an OpenACS 5 server is laid out starting from the Server root (ROOT):</p><div class="figure"> -<a name="idp140592107056328" id="idp140592107056328"></a><p class="title"><strong>Figure 11.1. Server file layout +<a name="idp140623177082456" id="idp140623177082456"></a><p class="title"><strong>Figure 11.1. Server file layout diagram</strong></p><div class="figure-contents"><pre class="programlisting"> ROOT/ bin/ @@ -65,7 +62,7 @@ <a class="indexterm" name="baby" id="baby"></a> To illustrate the general structure of a package, let's see what the package for the "notes" application should look like.</p><div class="figure"> -<a name="idp140592107063624" id="idp140592107063624"></a><p class="title"><strong>Figure 11.2. Package file layout +<a name="idp140623172256280" id="idp140623172256280"></a><p class="title"><strong>Figure 11.2. Package file layout diagram</strong></p><div class="figure-contents"><pre class="programlisting"> ROOT/ +-- packages/ APM Root @@ -129,14 +126,14 @@ this case is <code class="computeroutput">ROOT/packages/notes</code>. The following table describes in detail what each of the files up in the diagram contain.</p><p>A special note on the <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">PACKAGE-KEY</span></span>/www/resources</code> -directory. Files in this directory are available at <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/resources/<span class="replaceable"><span class="replaceable">PACKAGE-KEY</span></span>/...</code> and are returned -without any permissions checking or even checks that the package is -installed or mounted. Files are returned directly, so .tcl or .adp -files are not sourced in these directories. This makes it suitable -for storing icons, css files, javascript, and other static content -which can be treated this way.</p><div class="table"> -<a name="idp140592107069416" id="idp140592107069416"></a><p class="title"><strong>Table 11.1. Package +<em class="replaceable"><code>PACKAGE-KEY</code></em>/www/resources</code> +directory. Files in this directory are available at <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/resources/<em class="replaceable"><code>PACKAGE-KEY</code></em>/...</code> and are +returned without any permissions checking or even checks that the +package is installed or mounted. Files are returned directly, so +.tcl or .adp files are not sourced in these directories. This makes +it suitable for storing icons, css files, javascript, and other +static content which can be treated this way.</p><div class="table"> +<a name="idp140623177767000" id="idp140623177767000"></a><p class="title"><strong>Table 11.1. Package files</strong></p><div class="table-contents"><table class="table" summary="Package files" cellspacing="0" border="1"> <colgroup> <col><col><col> @@ -377,7 +374,7 @@ to add a new sub-folder called <code class="computeroutput">notes</code> to the root of the site, then click "new application" to mount a new instance of the <code class="computeroutput">notes</code> application to the site. -Name the new instance <code class="computeroutput">notes-1</code>.</p><p>Then type this URL into your browser: <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/notes/hello.html</code> +Name the new instance <code class="computeroutput">notes-1</code>.</p><p>Then type this URL into your browser: <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/notes/hello.html</code> </p><p>Now you should see the contents of the page that you added. What has happened is that all URLs that start with <code class="computeroutput">/notes</code> have been mapped in such a way as to serve content from the directory <code class="computeroutput">ROOT/packages/notes/www</code>. At this point, you @@ -401,8 +398,8 @@ <a name="packages-add-reading" id="packages-add-reading"></a>Additional Reading</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p><a class="xref" href="apm-design" title="Package Manager Design">Package Manager Design</a></p></li><li class="listitem"><p><a class="xref" href="apm-requirements" title="Package Manager Requirements">Package Manager Requirements</a></p></li><li class="listitem"><p><a class="link" href="tutorial-newpackage" title="Creating an Application Package">package development tutorial</a></p></li> -</ul></div><div class="cvstag">($‌Id: packages.xml,v 1.9.14.4 2017/06/16 -17:19:52 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: packages.xml,v 1.10 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/packages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/packages.html,v diff -u -r1.52 -r1.53 --- openacs-4/packages/acs-core-docs/www/packages.html 7 Aug 2017 23:47:51 -0000 1.52 +++ openacs-4/packages/acs-core-docs/www/packages.html 8 Nov 2017 09:42:11 -0000 1.53 @@ -1,19 +1,35 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Packages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="next" href="objects.html" title="OpenACS Data Models and the Object System"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packages"></a>OpenACS Packages</h2></div></div></div><div class="authorblurb"><p>By Pete Su and Bryan Quinn</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-overview"></a>Overview</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Packages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="next" href="objects.html" title="OpenACS Data Models and the Object System"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="packages"></a>OpenACS Packages</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>By Pete Su and Bryan Quinn</p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-overview"></a>Overview</h3></div></div></div> + + <p> This document is a guide on how to write a software package for OpenACS. OpenACS packages are installed and maintained with the OpenACS Package Manager (APM) which is part of the acs-admin package. This document presents reasons for packaging software, conventions for the file system and naming that must be followed, and step by step instructions for creating a new package for the "Notes" example package. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="server-file-layout"></a>Server file layout</h3></div></div></div><p> + </p> + + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="server-file-layout"></a>Server file layout</h3></div></div></div> + + <p> Here is how an OpenACS 5 server is laid out starting from the Server root (ROOT): - </p><div class="figure"><a name="idp140592107056328"></a><p class="title"><b>Figure 11.1. Server file layout diagram</b></p><div class="figure-contents"><pre class="programlisting"> + </p> + <div class="figure"><a name="idp140623177082456"></a><p class="title"><b>Figure 11.1. Server file layout diagram</b></p><div class="figure-contents"> + + <pre class="programlisting"> ROOT/ bin/ Various executables and scripts for server maintanence. @@ -31,27 +47,43 @@ tcl/ bootstrap code www/ - Pages not in packages (static content, customized pages)</pre></div></div><br class="figure-break"></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-looks"></a>What a Package Looks Like</h3></div></div></div><p> + Pages not in packages (static content, customized pages)</pre> + </div></div><br class="figure-break"> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-looks"></a>What a Package Looks Like</h3></div></div></div> + + + <p> Each package encapsulates all of its data model, library code, logic, administration pages and user pages in a single part of the file tree. This means developers can track down <span class="emphasis"><em>everything</em></span> that is related to a particular package without hunting all over the file system. Encapsulating everything about a package in one place also makes it much easier to distribute packages independently from the OpenACS Core. - </p><p> + </p> + + <p> In order to make this work, we need a system that keeps track of the packages that have been installed in the server, where those packages have been installed, and a standard way to map URLs that a client sends to our server to the right page in the appropriate package. While we're at it, this tool should also automate package installation, dependency checking, upgrades, and package removal. In OpenACS 5, this tool is called the <a class="link" href="packages.html#packages-apm" title="The APM">APM</a>. - </p><p> + </p> + + <p> <a class="indexterm" name="baby"></a> To illustrate the general structure of a package, let's see what the package for the "notes" application should look like. - </p><div class="figure"><a name="idp140592107063624"></a><p class="title"><b>Figure 11.2. Package file layout diagram</b></p><div class="figure-contents"><pre class="programlisting"> + </p> + + <div class="figure"><a name="idp140623172256280"></a><p class="title"><b>Figure 11.2. Package file layout diagram</b></p><div class="figure-contents"> + + <pre class="programlisting"> ROOT/ +-- packages/ APM Root | @@ -108,23 +140,31 @@ | | +-- *.adp UI Templates | | +-- *-oracle.xql Oracle-specific Queries | | +-- *-postgresql.xql PostgreSQL-specific Queries - +-- Other package directories.</pre></div></div><br class="figure-break"><p> + +-- Other package directories.</pre> + </div></div><br class="figure-break"> + <p> All file locations are relative to the package root, which in this case is <code class="computeroutput">ROOT/packages/notes</code>. The following table describes in detail what each of the files up in the diagram contain. - </p><p> + </p> + + <p> A special note on the - <code class="computeroutput"><span class="replaceable"><span class="replaceable">PACKAGE-KEY</span></span>/www/resources</code> + <code class="computeroutput"><em class="replaceable"><code>PACKAGE-KEY</code></em>/www/resources</code> directory. Files in this directory are available at - <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/resources/<span class="replaceable"><span class="replaceable">PACKAGE-KEY</span></span>/...</code> + <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/resources/<em class="replaceable"><code>PACKAGE-KEY</code></em>/...</code> and are returned without any permissions checking or even checks that the package is installed or mounted. Files are returned directly, so .tcl or .adp files are not sourced in these directories. This makes it suitable for storing icons, css files, javascript, and other static content which can be treated this way. - </p><div class="table"><a name="idp140592107069416"></a><p class="title"><b>Table 11.1. Package files</b></p><div class="table-contents"><table class="table" summary="Package files" cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>File Type</th><th>Its Use</th><th>Naming Convention</th></tr></thead><tbody><tr><td>Package Specification File</td><td>The package specification file is an XML file generated and + </p> + + <div class="table"><a name="idp140623177767000"></a><p class="title"><b>Table 11.1. Package files</b></p><div class="table-contents"> + + <table class="table" summary="Package files" cellspacing="0" border="1"><colgroup><col><col><col></colgroup><thead><tr><th>File Type</th><th>Its Use</th><th>Naming Convention</th></tr></thead><tbody><tr><td>Package Specification File</td><td>The package specification file is an XML file generated and maintained by the OpenACS Package Manager (APM). It specifies information about the package including its parameters and its files.</td><td><code class="computeroutput">notes.info</code></td></tr><tr><td>Data Model Creation Script</td><td> @@ -225,13 +265,25 @@ Templates receive a set of data sources from the logic scripts and prepare them for display to the browser.</td><td><code class="computeroutput">www/*.adp</code></td></tr><tr><td>UI Index Page</td><td>The UI must have an index page composed of a logic script called <code class="computeroutput">index.tcl</code> and a template called - <code class="computeroutput">index.adp</code>.</td><td><code class="computeroutput">www/index.tcl</code></td></tr></tbody></table></div></div><br class="table-break"></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-apm"></a>The APM</h3></div></div></div><p> + <code class="computeroutput">index.adp</code>.</td><td><code class="computeroutput">www/index.tcl</code></td></tr></tbody></table> + </div></div><br class="table-break"> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-apm"></a>The APM</h3></div></div></div> + + + <p> The APM is used to create, maintain, and install packages. It takes care of copying all of the files and registering the package in the system. The APM is responsible for: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Package registration</p></li><li class="listitem"><p>Automatic installation of packages: loading data models, code + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Package registration</p></li><li class="listitem"><p>Automatic installation of packages: loading data models, code libraries, and so on.</p></li><li class="listitem"><p>Checking what packages depend on what other packages.</p></li><li class="listitem"><p>Storing information on the package including ownership and a file - list.</p></li></ol></div><p> + list.</p></li></ol></div> + + <p> In addition for packages that are applications, the APM is responsible for keeping track of where in the site a user must go in order to use the application. To do this, the APM defines a set of objects that we @@ -243,19 +295,34 @@ running copies of a single program. Each instance can be independently administered and each instance maintains its own set of application parameters and options. - </p><p> + </p> + + <p> The following sections will show you how to make a package for the Notes application. In addition, they will discuss some site management features in OpenACS 5 that take advantage of the APM's package instance model. The two most important of these are <span class="emphasis"><em>subsites</em></span>, and the <span class="emphasis"><em>site map</em></span> tool, which can be used to map applications to one or more arbitrary URLs in a running site. - </p><p> + </p> + + <p> We will also discuss how to organize your files and queries so they work with the OpenACS Query Dispatcher. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-making-a-package"></a>Making a Package</h3></div></div></div><p> + </p> + + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-making-a-package"></a>Making a Package</h3></div></div></div> + + + + <p> Here is how you make a package. - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Login as a site-wide administrator on your web service. + </p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Login as a site-wide administrator on your web service. </p></li><li class="listitem"><p>Go to the package manager on your server. The URL is <a class="ulink" href="/acs-admin/apm" target="_top">/acs-admin/apm</a>. </p></li><li class="listitem"><p>Click on the link <a class="ulink" href="/acs-admin/apm/package-add" target="_top">/acs-admin/apm/package-add</a>. </p></li><li class="listitem"><p>Fill out the form for adding a new package. The form explains what @@ -324,7 +391,9 @@ <code class="computeroutput">ROOT/packages/notes/sql/postgresql/notes-create.sql</code> and <code class="computeroutput">ROOT/packages/notes/sql/postgresql/notes-drop.sql</code>. - </p><p> + </p> + + <p> After you do this, go back to the main APM page. From there, click the link called "notes" to go to the management page for the new package. Now click the link called "Manage @@ -334,7 +403,9 @@ the file system for new files. This will bring you do a page that lists all the files you just added and lets you add them to the <code class="computeroutput">notes</code> package. - </p><p> + </p> + + <p> Note that while the <code class="computeroutput">.sql</code> files have been added to the packge, they <span class="emphasis"><em>have not</em></span> been loaded into the database. For the purposes of development, @@ -350,7 +421,10 @@ I'll assume that you have set up your development repository according to the standards described in <a class="link" href="cvs-tips.html#cvs-service-import" title="Add the Service to CVS - OPTIONAL">this appendix</a>. If so, then you just do this: - </p><pre class="programlisting">% cd ROOT/packages + </p> + + + <pre class="programlisting">% cd ROOT/packages % cvs add notes % cd notes % cvs add notes.info @@ -359,10 +433,23 @@ % cvs add *.sql % cd ROOT/packages/notes % cvs commit -m "add new package for notes" - </pre></li><li class="listitem"><p> + </pre> + + + + </li><li class="listitem"><p> Now you can start developing the package. In addition to writing code, you should also consider the tasks outlined in the <a class="link" href="tutorial-newpackage.html" title="Creating an Application Package">package development tutorial</a>. - </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-subsites"></a>The Site Map and Package Instances</h3></div></div></div><p> + </p></li></ol></div> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-subsites"></a>The Site Map and Package Instances</h3></div></div></div> + + + + <p> At this point, you are probably excited to see your new package in action. But, we haven't added any user visible pages yet. By convention, user visible pages go in the @@ -373,7 +460,9 @@ own. What we have to do is <span class="emphasis"><em>mount</em></span> the application into the site map. That is, we have to define the URL from which the application will serve its pages. - </p><p> + </p> + + <p> In OpenACS 5, administrators can define an arbitrary mapping between the URLs the user types and the actual file in the file system that is served. This mapping is called the <span class="emphasis"><em>site map</em></span> and entries in the @@ -391,7 +480,9 @@ you how OpenACS figures out which instance of your application was requested by the user at any given time. The <a class="link" href="subsites.html" title="Writing OpenACS Application Pages">page development</a> tutorial shows you how to use this information in your user interface. - </p><p> + </p> + + <p> In order to make the new <code class="computeroutput">notes</code> application visible to users, we have to mount it in the site map. You do this by going to the <a class="ulink" href="/admin/site-map" target="_top">Site Map</a> page, which is by @@ -400,9 +491,13 @@ the root of the site, then click "new application" to mount a new instance of the <code class="computeroutput">notes</code> application to the site. Name the new instance <code class="computeroutput">notes-1</code>. - </p><p> - Then type this URL into your browser: <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/notes/hello.html</code> - </p><p> + </p> + + <p> + Then type this URL into your browser: <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/notes/hello.html</code> + </p> + + <p> Now you should see the contents of the page that you added. What has happened is that all URLs that start with <code class="computeroutput">/notes</code> have been mapped in such a way as to serve content from the directory @@ -412,9 +507,19 @@ later document, we'll see how to write your application so that the code can detect from what URL it was invoked. This is the key to supporting <a class="link" href="subsites.html" title="Writing OpenACS Application Pages">subsites</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-summary"></a>Summary</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-summary"></a>Summary</h3></div></div></div> + + + + <p> The APM performs the following tasks in an OpenACS site: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Manages creation, installation, and removal of packages from the server. Also keeps track of what files belong to which packages. </p></li><li class="listitem"><p> @@ -427,4 +532,18 @@ </p></li><li class="listitem"><p> Writes out package distribution files for other people to download and install. We'll cover this later. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-add-reading"></a>Additional Reading</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="apm-design.html" title="Package Manager Design">Package Manager Design</a></p></li><li class="listitem"><p><a class="xref" href="apm-requirements.html" title="Package Manager Requirements">Package Manager Requirements</a></p></li><li class="listitem"><p><a class="link" href="tutorial-newpackage.html" title="Creating an Application Package">package development tutorial</a></p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 11. Development Reference </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS Data Models and the Object System</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p></li></ul></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="packages-add-reading"></a>Additional Reading</h3></div></div></div> + + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="apm-design.html" title="Package Manager Design">Package Manager Design</a></p></li><li class="listitem"><p><a class="xref" href="apm-requirements.html" title="Package Manager Requirements">Package Manager Requirements</a></p></li><li class="listitem"><p><a class="link" href="tutorial-newpackage.html" title="Creating an Application Package">package development tutorial</a></p></li></ul></div> + + <p><span class="cvstag">($Id$)</span></p> + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="dev-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="objects.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 11. Development Reference </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS Data Models and the Object System</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/parties.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/parties.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/parties.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="permissions-tediously-explained" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="parties" id="parties"></a>Parties in OpenACS</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="parties" id="parties"></a>Parties in OpenACS</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. +Schloming</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="parties-intro" id="parties-intro"></a>Introduction</h3></div></div></div><p>While many applications must deal with individuals and many applications must deal with groups, most applications must deal @@ -323,8 +321,8 @@ a membership relation is an ordinary acs object with <a class="ulink" href="object-identity" target="_top">object identity</a>, it is as easy to extend the membership relation to store extra information as it is to extend the users table or the -groups table.</p><div class="cvstag">($‌Id: parties.xml,v 1.9 2006/09/25 20:32:37 -byronl Exp $)</div> +groups table.</p><p><span class="cvstag">($‌Id: parties.xml,v 1.9 2006/09/25 20:32:37 +byronl Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/parties.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/parties.html,v diff -u -r1.52 -r1.53 --- openacs-4/packages/acs-core-docs/www/parties.html 7 Aug 2017 23:47:51 -0000 1.52 +++ openacs-4/packages/acs-core-docs/www/parties.html 8 Nov 2017 09:42:11 -0000 1.53 @@ -1,8 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Parties in OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="subsites.html" title="Writing OpenACS Application Pages"><link rel="next" href="permissions-tediously-explained.html" title="OpenACS Permissions Tediously Explained"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="parties"></a>Parties in OpenACS</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-intro"></a>Introduction</h3></div></div></div><p>While many applications must deal with individuals and many applications +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Parties in OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="subsites.html" title="Writing OpenACS Application Pages"><link rel="next" href="permissions-tediously-explained.html" title="OpenACS Permissions Tediously Explained"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="parties"></a>Parties in OpenACS</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a></p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-intro"></a>Introduction</h3></div></div></div> + + + + +<p>While many applications must deal with individuals and many applications must deal with groups, most applications must deal with individuals <span class="emphasis"><em>or</em></span> groups. It is often the case with such applications that @@ -11,19 +20,38 @@ practical way to manage both. This concept is so mundane that there is no need to invent special terminology. This -supertype is called a "party".</p><p>A classic example of the "party" supertype is evident +supertype is called a "party".</p> + +<p>A classic example of the "party" supertype is evident in address books. A typical address book might contain the address of a doctor, grocery store, and friend. The first field in an entry in the address book is not labeled a person or company, but a "party". -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-data-model"></a>The Data Model</h3></div></div></div><p>The parties developer guide begins with +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-data-model"></a>The Data Model</h3></div></div></div> + + + + +<p>The parties developer guide begins with an introduction to the parties data model, since OpenACS -community applications likely require using it in some way.</p><p><span class="strong"><strong>Parties</strong></span></p><p>The central table in the parties data model is the parties table itself. +community applications likely require using it in some way.</p> + +<p><span class="strong"><strong>Parties</strong></span></p> + +<p>The central table in the parties data model is the parties table itself. Every party has exactly one row in this table. Every party has an optional unique email address and an optional url. A party is an acs object, so permissions may be granted and revoked on parties and auditing information is -stored in the acs objects table.</p><pre class="programlisting"> +stored in the acs objects table.</p> + + +<pre class="programlisting"> + <code class="computeroutput"> create table parties ( party_id not null @@ -36,22 +64,33 @@ ); </code> -</pre><p>The <code class="computeroutput">persons</code> and +</pre> + + +<p>The <code class="computeroutput">persons</code> and <code class="computeroutput">groups</code> tables extend the <code class="computeroutput">parties</code> table. A row in the persons table represents the most generic form of individual modeled. An individual need not be known to the system as a user. A user is a further specialized form of an individual (discussed later). A row in the groups table represents the most generic form of group modeled, where a group is an aggregation of zero or more -individuals.</p><p><span class="strong"><strong>Persons</strong></span></p><p>If a party is an individual then there will be a row in the persons table +individuals.</p> + +<p><span class="strong"><strong>Persons</strong></span></p> + +<p>If a party is an individual then there will be a row in the persons table containing <code class="computeroutput">first_names</code> and <code class="computeroutput">last_name</code> for that individual. The primary key of the persons table (<code class="computeroutput">person_id</code>) references the primary key of the parties table (<code class="computeroutput">party_id</code>), so that there is a corresponding row in the parties table when there is a row in the persons table. -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table persons ( person_id not null constraint persons_person_id_fk @@ -62,25 +101,36 @@ ); </code> -</pre><p><span class="strong"><strong>Users</strong></span></p><p>The <code class="computeroutput">users</code> table is a more +</pre> + + +<p><span class="strong"><strong>Users</strong></span></p> + +<p>The <code class="computeroutput">users</code> table is a more specialized form of <code class="computeroutput">persons</code> table. A row in <code class="computeroutput">users</code> table represents an individual that has login access to the system. The primary key of the users table references the primary key of the persons table. This guarantees that if there is a row in <code class="computeroutput">users</code> table then there must be a corresponding row in <code class="computeroutput">persons</code> -and <code class="computeroutput">parties</code> tables.</p><p>Decomposing all the information +and <code class="computeroutput">parties</code> tables.</p> + +<p>Decomposing all the information associated with a user into the four tables (acs_objects, parties, persons, users) has some immediate benefits. For instance, it is possible to remove access to a user from a live system by removing his entry from the users table, while leaving the rest of his information present (i.e. turning him from a user into a -person).</p><p>Wherever possible the OpenACS data model references the <code class="computeroutput">persons</code> or +person).</p> +<p>Wherever possible the OpenACS data model references the <code class="computeroutput">persons</code> or <code class="computeroutput">parties</code> table, <span class="strong"><strong>not</strong></span> the <code class="computeroutput">users</code> table. Developers should be careful to only reference the users table in situations where it is clear that the reference is to a user for all cases and not to any other individual -for any case.</p><pre class="programlisting"> +for any case.</p> + +<pre class="programlisting"> + <code class="computeroutput">create table users ( user_id not null constraint users_user_id_fk @@ -108,12 +158,21 @@ ); </code> -</pre><p><span class="strong"><strong>Groups</strong></span></p><p>The final piece of the parties data model is the groups data model. A +</pre> + + +<p><span class="strong"><strong>Groups</strong></span></p> + +<p>The final piece of the parties data model is the groups data model. A group is a specialization of a party that represents an aggregation of zero or more other parties. The only extra information directly associated with a group (beyond -that in the parties table) is the name of the group:</p><pre class="programlisting"> +that in the parties table) is the name of the group:</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table groups ( group_id not null constraint groups_group_id_fk @@ -123,13 +182,19 @@ ); </code> -</pre><p> +</pre> +<p> There is another piece to the groups data model that records relations between parties and groups. -</p><p><span class="strong"><strong>Group Relations</strong></span></p><p>Two types of group relations are represented in the data model: +</p> + +<p><span class="strong"><strong>Group Relations</strong></span></p> + +<p>Two types of group relations are represented in the data model: membership relations and composite relations. The full range of sophisticated group structures that exist in the real -world can be modelled in OpenACS by these two relationship types.</p><p>Membership relations represent direct membership relation between parties and groups. A party may be +world can be modelled in OpenACS by these two relationship types.</p> +<p>Membership relations represent direct membership relation between parties and groups. A party may be a "member" of a group. Direct membership relations are common in administrative practices, and do not follow basic set theory rules. If A is a member of B, and B is a member of C, A is @@ -153,7 +218,11 @@ the MC, i.e., membership <span class="emphasis"><em>is</em></span> transitive with respect to composition. Furthermore, a member of a European (or other) office of the MC is automatically a member of the MC. -</p><p><span class="strong"><strong>Group Membership</strong></span></p><p>Group memberships can be created and manipulated using the membership_rel +</p> + +<p><span class="strong"><strong>Group Membership</strong></span></p> + +<p>Group memberships can be created and manipulated using the membership_rel package. Only one membership object can be created for a given group, party pair. </p><p> @@ -164,8 +233,11 @@ For example, a person might be listed in a system as both an individual (direct membership) and a member of a household (indirect membership) at a video rental store. -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + <code class="computeroutput"> # sql code create or replace package membership_rel @@ -210,14 +282,21 @@ show errors </code> -</pre><p><span class="strong"><strong>Group Composition</strong></span></p><p>Composition relations can be created or destroyed using the +</pre> + + +<p><span class="strong"><strong>Group Composition</strong></span></p> + +<p>Composition relations can be created or destroyed using the composition_rel package. The only restriction on compositions is that there cannot be a reference loop, i.e., a group cannot be a component of itself either directly or indirectly. This constraint is maintained for you by the API. So users do not see some random PL/SQL error message, do not give them the option to create a composition relation that -would result in a circular reference.</p><pre class="programlisting"> +would result in a circular reference.</p> +<pre class="programlisting"> + <code class="computeroutput"> # sql code create or replace package composition_rel @@ -241,7 +320,18 @@ show errors </code> -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-views"></a>Views</h3></div></div></div><p>The parties data model does a reasonable job of representing many +</pre> + + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-views"></a>Views</h3></div></div></div> + + + + +<p>The parties data model does a reasonable job of representing many of the situations one is likely to encounter when modeling organizational structures. We still need to be able to efficiently answer questions like "what members are in this group and all of its components?", and @@ -250,7 +340,9 @@ Directed Acyclic Graph (DAG) between a group and its components. For these reasons the party system provides a bunch of views that take advantage of the internal representation of group relations to answer questions like these -very quickly.</p><p>The <code class="computeroutput">group_component_map</code> +very quickly.</p> + +<p>The <code class="computeroutput">group_component_map</code> view returns all the subcomponents of a group including components of sub components and so forth. The <code class="computeroutput">container_id</code> column is the <code class="computeroutput">group_id</code> of the group in which <code class="computeroutput">component_id</code> is directly contained. This allows you to easily @@ -260,67 +352,115 @@ <code class="computeroutput">group_id</code>, <code class="computeroutput">component_id</code>, and <code class="computeroutput">container_id</code>. The <code class="computeroutput">rel_id</code> column points to the row in <code class="computeroutput">acs_rels</code> table that contains the relation object that relates <code class="computeroutput">component_id</code> to <code class="computeroutput">container_id</code>. The <code class="computeroutput">rel_id</code> might be useful for retrieving or updating standard -auditing info for the relation.</p><pre class="programlisting"> +auditing info for the relation.</p> + + +<pre class="programlisting"> + <code class="computeroutput">create or replace view group_component_map as select group_id, component_id, container_id, rel_id ... </code> -</pre><p>The <code class="computeroutput">group_member_map</code> view is similar to <code class="computeroutput">group_component_map</code> except for membership relations. -This view returns all membership relations regardless of membership state.</p><pre class="programlisting"> +</pre> + +<p>The <code class="computeroutput">group_member_map</code> view is similar to <code class="computeroutput">group_component_map</code> except for membership relations. +This view returns all membership relations regardless of membership state.</p> + + + +<pre class="programlisting"> + <code class="computeroutput">create or replace view group_member_map as select group_id, member_id, container_id, rel_id ... </code> -</pre><p>The <code class="computeroutput">group_approved_member_map</code> +</pre> + + +<p>The <code class="computeroutput">group_approved_member_map</code> view is the same as <code class="computeroutput">group_member_map</code> except -it only returns entries that relate to approved members.</p><pre class="programlisting"> +it only returns entries that relate to approved members.</p> + + +<pre class="programlisting"> + <code class="computeroutput">create or replace view group_approved_member_map as select group_id, member_id, container_id, rel_id ... </code> -</pre><p>The <code class="computeroutput">group_distinct_member_map</code> +</pre> + + +<p>The <code class="computeroutput">group_distinct_member_map</code> view is a useful view if you do not care about the distinction between direct membership and indirect membership. It returns all members of a -group including members of components --the transitive closure.</p><pre class="programlisting"> +group including members of components --the transitive closure.</p> + + +<pre class="programlisting"> + <code class="computeroutput">create or replace view group_distinct_member_map as select group_id, member_id ... </code> -</pre><p>The <code class="computeroutput">party_member_map</code> view is the same as <code class="computeroutput">group_distinct_member_map</code>, except it includes the +</pre> + + +<p>The <code class="computeroutput">party_member_map</code> view is the same as <code class="computeroutput">group_distinct_member_map</code>, except it includes the identity mapping. It maps from a party to the fully expanded list of parties represented by that party including the party itself. So if a party is an individual, this view will have exactly one mapping that is from that party to itself. If a view is a group containing three individuals, this view will have four rows for that party, one for each member, and one from -the party to itself.</p><pre class="programlisting"> +the party to itself.</p> + + +<pre class="programlisting"> + <code class="computeroutput">create or replace view party_member_map as select party_id, member_id ... </code> -</pre><p>The <code class="computeroutput">party_approved_member_map</code> view is the same as <code class="computeroutput">party_member_map</code> except that when it expands groups, it only -pays attention to approved members.</p><pre class="programlisting"> +</pre> + +<p>The <code class="computeroutput">party_approved_member_map</code> view is the same as <code class="computeroutput">party_member_map</code> except that when it expands groups, it only +pays attention to approved members.</p> + +<pre class="programlisting"> + <code class="computeroutput">create or replace view party_approved_member_map as select party_id, member_id ... </code> -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-extending-data-model"></a>Extending The Parties Data Model</h3></div></div></div><p>The parties data model can represent some fairly sophisticated real +</pre> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="parties-extending-data-model"></a>Extending The Parties Data Model</h3></div></div></div> + + +<p>The parties data model can represent some fairly sophisticated real world situations. Still, it would be foolish to assume that this data model is sufficiently efficient for every application. This section describes some -of the more common ways to extend the parties data model.</p><p><span class="strong"><strong>Specializing Users</strong></span></p><p>Some applications will want to collect more +of the more common ways to extend the parties data model.</p> + +<p><span class="strong"><strong>Specializing Users</strong></span></p> + +<p>Some applications will want to collect more detailed information for people using the system. If there can be only one such piece of information per user, then it might make sense to create another type of individual that is a further specialization @@ -331,12 +471,20 @@ have a primary key that references the users table, thereby guaranteeing that each row in the chess_club_users table has a corresponding row in each of the users, persons, parties, and acs_objects tables. This child table could then -store any extra information relevant to the Chess Club community.</p><p><span class="strong"><strong>Specializing Groups</strong></span></p><p>If one were to build an intranet application on top of the party +store any extra information relevant to the Chess Club community.</p> + +<p><span class="strong"><strong>Specializing Groups</strong></span></p> + +<p>If one were to build an intranet application on top of the party system, it is likely that one would want to take advantage of the systems efficient representation of sophisticated organizational structures, but there would be much more specialized information associated with each group. In this case it would make sense to specialize the group party type into a -company party type in the same manner as Specializing Users.</p><p><span class="strong"><strong>Specializing Membership Relations</strong></span></p><p>The final portion of the parties data model that is designed to be +company party type in the same manner as Specializing Users.</p> + +<p><span class="strong"><strong>Specializing Membership Relations</strong></span></p> + +<p>The final portion of the parties data model that is designed to be extended is the membership relationship. Consider the intranet example again. It is likely that a membership in a company would have more information associated with it than a membership in an ordinary group. An obvious example @@ -345,4 +493,10 @@ single integer primary key in what could be thought of as a pure relation. Because a membership relation is an ordinary acs object with <a class="ulink" href="object-identity.html" target="_top">object identity</a>, it is as easy to extend the membership relation to store extra information as it is to extend the users -table or the groups table.</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr><tr><td width="40%" align="left">Writing OpenACS Application Pages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS Permissions Tediously Explained</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +table or the groups table.</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-tediously-explained.html">Next</a></td></tr><tr><td width="40%" align="left">Writing OpenACS Application Pages </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> OpenACS Permissions Tediously Explained</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/permissions-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions-design.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions-design.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="groups-requirements" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="permissions-design" id="permissions-design"></a>Permissions Design</h2></div></div></div><div class="authorblurb"> -<p>By John Prevost and <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="permissions-design" id="permissions-design"></a>Permissions Design</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By John Prevost and <a class="ulink" href="http://planitia.org" target="_top">Rafael H. +Schloming</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="permissions-design-essentials" id="permissions-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Tcl in <code class="computeroutput">packages/acs-kernel</code> Index: openacs-4/packages/acs-core-docs/www/permissions-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-design.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/permissions-design.html 7 Aug 2017 23:47:51 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/permissions-design.html 8 Nov 2017 09:42:11 -0000 1.36 @@ -1,11 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Permissions Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="permissions-requirements.html" title="Permissions Requirements"><link rel="next" href="groups-requirements.html" title="Groups Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-design"></a>Permissions Design</h2></div></div></div><div class="authorblurb"><p>By John Prevost and <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl in <code class="computeroutput">packages/acs-kernel</code></p></li><li class="listitem"><p><a class="xref" href="permissions-requirements.html" title="Permissions Requirements">OpenACS 4 Permissions Requirements</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Permissions Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="permissions-requirements.html" title="Permissions Requirements"><link rel="next" href="groups-requirements.html" title="Groups Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-design"></a>Permissions Design</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By John Prevost and <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-essentials"></a>Essentials</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl in <code class="computeroutput">packages/acs-kernel</code></p></li><li class="listitem"><p><a class="xref" href="permissions-requirements.html" title="Permissions Requirements">OpenACS 4 Permissions Requirements</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top"> SQL file</a></p></li><li class="listitem"><p><a class="ulink" href="images/permissions-er.png" target="_top">ER diagram</a> -</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-intro"></a>Introduction</h3></div></div></div><p>The goal of the Permissions system is to provide generic means to both +</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-intro"></a>Introduction</h3></div></div></div> + + + +<p>The goal of the Permissions system is to provide generic means to both programmers and site administrators to designate operations (methods) as requiring permissions, and then to check, grant, or revoke permissions via a consistent interface. For example, we might decide that the transaction that @@ -14,35 +30,75 @@ that viewing a certain set of pages within the application is an operation to be individually granted or revoked from a user. It's expected that the Permissions system will be seeing a lot of use - almost every page will make -at least one permissions API call, and some will make several.</p><p>For programmers, the Permissions API provides a means to work with access +at least one permissions API call, and some will make several.</p> + +<p>For programmers, the Permissions API provides a means to work with access control in a consistent manner. If a programmer's OpenACS package defines new methods for itself, the Permissions API must provide simple calls to determine whether the current user is authorized to perform the given method. In addition, using the Permissions API, queries should easily select only -those package objects on which a user has certain permissions.</p><p>For site administrators and other authorized users, the Permissions UI +those package objects on which a user has certain permissions.</p> + +<p>For site administrators and other authorized users, the Permissions UI provides a means to aggregate the primitive operations (methods) made available by the programmer into logical privileges (like read, write, and -admin) that can be granted and revoked.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-history"></a>Historical Considerations</h3></div></div></div><p>In earlier versions of the OpenACS, permissions and access control was handled +admin) that can be granted and revoked.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-history"></a>Historical Considerations</h3></div></div></div> + + + +<p>In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules used "roles", while others did not. Other modules did all access control based simply on coded rules regarding who can act on a given database -row based on the information in that row.</p><p>Problems resulting from this piecemeal approach to permissions and access +row based on the information in that row.</p> + +<p>Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that both programmers and administrators can -readily use.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-competitors"></a>Competitive Analysis</h3></div></div></div><p><span class="emphasis"><em>None available as of 10/2000.</em></span></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div><p>The core of the permissions data model is quite simple. Unfortunately, the +readily use.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-competitors"></a>Competitive Analysis</h3></div></div></div> + + + +<p><span class="emphasis"><em>None available as of 10/2000.</em></span></p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div> + + + +<p>The core of the permissions data model is quite simple. Unfortunately, the hierarchical nature of default permissions entails quite a number of tree queries which could slow the system down. Since every page will have at least one permissions check, a number of views and auxiliary tables (de-normalizations of the data model) have been created to speed up access queries. As a consequence, speed of updates are decreased and requirements -for additional storage space increase.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-data-model"></a>Data Model Discussion</h3></div></div></div><p>As described in section V., the core of the permissions data model is +for additional storage space increase.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-data-model"></a>Data Model Discussion</h3></div></div></div> + + + +<p>As described in section V., the core of the permissions data model is simple, though a number of views and auxiliary tables exist to ensure -adequate performance. The core model consists of five tables:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">acs_methods</code> +adequate performance. The core model consists of five tables:</p> +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">acs_methods</code> + </span></dt><dd><p>The set of all defined methods.</p></dd><dt><span class="term"><code class="computeroutput">acs_privileges</code> </span></dt><dd><p>The set of all defined privileges.</p></dd><dt><span class="term"><code class="computeroutput">acs_privilege_method_rules</code> @@ -57,14 +113,20 @@ row for every privilege <span class="strong"><strong>directly</strong></span> granted on any object in the system - this is a denormalization of <code class="computeroutput">acs_privilege_method_rules</code> and -<code class="computeroutput">acs_privilege_hierarchy</code></p></dd></dl></div><p>There are also a number of views to make it easier to ask specific +<code class="computeroutput">acs_privilege_hierarchy</code></p></dd></dl></div> + +<p>There are also a number of views to make it easier to ask specific questions about permissions. For example, a number of the above tables describe "direct" or explicit permissions. Inheritance and default values can, however, introduce permissions which are not directly specified. (For example, read access on a forum allows read access on all the messages -in the forum.)</p><p>The following views provide flattened versions of inherited -information:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">acs_privilege_method_map</code> +in the forum.)</p> +<p>The following views provide flattened versions of inherited +information:</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">acs_privilege_method_map</code> + </span></dt><dd><p>Map of privileges to the methods they contain either directly or because of another privilege which is included (at any depth).</p></dd><dt><span class="term"><code class="computeroutput">acs_object_grantee_priv_map</code> @@ -77,110 +139,243 @@ a party is a member of a group (at any depth).</p></dd><dt><span class="term"><code class="computeroutput">acs_object_party_method_map</code> </span></dt><dd><p>Relation with every (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>method</em></span>) -tuple implied by the above trees.</p></dd></dl></div><p>In general, <span class="strong"><strong>only <code class="computeroutput">acs_object_party_method_map</code></strong></span> +tuple implied by the above trees.</p></dd></dl></div> + +<p>In general, <span class="strong"><strong>only <code class="computeroutput">acs_object_party_method_map</code></strong></span> should be used for queries from other modules. The other views are -intermediate steps in building that query.</p><p>The data model also includes two simple PL/SQL procedures +intermediate steps in building that query.</p> + +<p>The data model also includes two simple PL/SQL procedures (<code class="computeroutput">acs_permission.grant_permission</code> and <code class="computeroutput">acs_permission.revoke_permission</code>) for granting and revoking a -specific privilege for a specific user on a specific object.</p><p>To sum up, the PL/SQL procedures are meant to be used to grant or revoke +specific privilege for a specific user on a specific object.</p> + +<p>To sum up, the PL/SQL procedures are meant to be used to grant or revoke permissions. The five base tables represent the basic data model of the system, with a set of views provided to convert them into a format suitable for joining to answer specific questions. The exact means by which this transformation takes place should not be depended on, since they may change -for efficiency reasons.</p><p>The transformations done create a set of default permissions, in -which:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>parties get the privileges of any groups they are directly or indirectly +for efficiency reasons.</p> + +<p>The transformations done create a set of default permissions, in +which:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>parties get the privileges of any groups they are directly or indirectly a member of</p></li><li class="listitem"><p>privileges get associated with the methods of any other privileges they have taken methods from (at any level) (see <code class="computeroutput">acs_privilege_hierarchy</code>)</p></li><li class="listitem"><p>objects get access control from direct grants, or inherit permissions from their context (unless the "don't inherit" flag is -set)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-transactions"></a>Legal Transactions</h3></div></div></div><p>There are three essential areas in which all transactions in the -permissions system fall:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Modification of methods and privileges</p></li><li class="listitem"><p>Modification of permissions</p></li><li class="listitem"><p>Queries on permissions</p></li></ul></div><p><span class="strong"><strong>"Modification of methods and privileges."</strong></span> This +set)</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-transactions"></a>Legal Transactions</h3></div></div></div> + + + +<p>There are three essential areas in which all transactions in the +permissions system fall:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Modification of methods and privileges</p></li><li class="listitem"><p>Modification of permissions</p></li><li class="listitem"><p>Queries on permissions</p></li></ul></div> + +<p><span class="strong"><strong>"Modification of methods and privileges."</strong></span> This refers to actions that happen mainly at package installation time - a package will create a number of methods for its own use, then associate them with the system's standard privileges, or new privileges which the package has created. The association step might also happen later, if the site-wide -administrator chooses to change permissions policy.</p><p>These steps involve directly manipulating the <code class="computeroutput">acs_methods</code>, +administrator chooses to change permissions policy.</p> + +<p>These steps involve directly manipulating the <code class="computeroutput">acs_methods</code>, <code class="computeroutput">acs_privileges</code>, and <code class="computeroutput">acs_privilege_method_rules</code> tables. A web page for manipulating these features should be limited to site-wide -administrators.</p><p><span class="strong"><strong>"Modification of permissions"</strong></span> - involves fairly +administrators.</p> + +<p><span class="strong"><strong>"Modification of permissions"</strong></span> - involves fairly common operations. Users are typically able to administer permissions for objects they themselves create. The two basic operations here are "grant" and "revoke". Granting permissions is done via <code class="computeroutput">acs_permissions.grant_permission</code>, and revocation via <code class="computeroutput">acs_permissions.revoke_permission</code>. These directly manipulate the -<code class="computeroutput">acs_permissions</code> table.</p><p>Web pages for making these changes are available to all users, so they +<code class="computeroutput">acs_permissions</code> table.</p> + +<p>Web pages for making these changes are available to all users, so they should not be in an admin area. In order to grant and revoke permissions on an object, the user must have the <code class="computeroutput">administer_privileges</code> method -permission on that object.</p><p><span class="strong"><strong>"Queries on permissions"</strong></span> - by far the most +permission on that object.</p> + +<p><span class="strong"><strong>"Queries on permissions"</strong></span> - by far the most common operation is querying the permissions database. Several kinds of questions are commonly asked: First, and most commonly, "Can this party perform this method on this object?" Two Tcl functions are provided to answer this - one which returns a boolean, the other of which results in an error page. These Tcl functions directly access the -<code class="computeroutput">acs_object_party_method_map</code>.</p><p>The second most commonly asked question occurs when a list of objects is +<code class="computeroutput">acs_object_party_method_map</code>.</p> + +<p>The second most commonly asked question occurs when a list of objects is being displayed, often in order to provide appropriate UI functionality: "For this party, what methods are available on these objects?" Here, the SQL query needs to filter based on whether the party/user can perform some operation on the object. This is done via a join or sub-select against <code class="computeroutput">acs_object_party_method_map</code>, or by calling the Tcl functions -for appropriate methods.</p><p>Finally, when administering the permissions for an object, a web page +for appropriate methods.</p> + +<p>Finally, when administering the permissions for an object, a web page needs to know all permissions directly granted on that object. This is done -by querying against <code class="computeroutput">acs_permissions</code>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-api"></a>API</h3></div></div></div><p>The API to the permissions system consists of a few well-known tables, -plus a pair of PL/SQL procedures and a pair of Tcl functions.</p><p><span class="strong"><strong>Tables</strong></span></p><p><code class="computeroutput">acs_methods</code>, <code class="computeroutput">acs_privileges</code>, and +by querying against <code class="computeroutput">acs_permissions</code>.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-api"></a>API</h3></div></div></div> + + + +<p>The API to the permissions system consists of a few well-known tables, +plus a pair of PL/SQL procedures and a pair of Tcl functions.</p> + +<p><span class="strong"><strong>Tables</strong></span></p> + +<p><code class="computeroutput">acs_methods</code>, <code class="computeroutput">acs_privileges</code>, and <code class="computeroutput">acs_privilege_method_rules</code> manage the set of permissions in the system. At installation time, a package will add to these three tables to -introduce new permissions into the system.</p><p>The main table for queries is <code class="computeroutput">acs_object_party_method_map</code>, which +introduce new permissions into the system.</p> + +<p>The main table for queries is <code class="computeroutput">acs_object_party_method_map</code>, which contains (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>method</em></span>) triples for all -allowed operations in the system.</p><p>Also of interest for queries is <code class="computeroutput">acs_permissions</code>, which lists +allowed operations in the system.</p> + +<p>Also of interest for queries is <code class="computeroutput">acs_permissions</code>, which lists directly granted privileges. Neither <code class="computeroutput">acs_object_party_method_map</code> (which is a view) nor <code class="computeroutput">acs_permissions</code> should be updated -directly.</p><p><span class="strong"><strong>PL/SQL Procedures</strong></span></p><p><code class="computeroutput">acs_permissions.grant_permission</code> introduces new permissions for +directly.</p> + +<p><span class="strong"><strong>PL/SQL Procedures</strong></span></p> + +<p><code class="computeroutput">acs_permissions.grant_permission</code> introduces new permissions for an object. It should be given an (<span class="emphasis"><em>object</em></span>, <span class="emphasis"><em>party</em></span>, <span class="emphasis"><em>privilege</em></span>) triple, and will always succeed. If the permission is already in the system, no change occurs. The interface for this procedure -is:</p><pre class="programlisting"> +is:</p> + +<pre class="programlisting"> procedure grant_permission ( object_id acs_permissions.object_id%TYPE, grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE ); -</pre><p><code class="computeroutput">acs_permissions.revoke_permission</code> removes a permission entry +</pre> + +<p><code class="computeroutput">acs_permissions.revoke_permission</code> removes a permission entry given a triple. It always succeeds--if a permission does not exist, nothing -changes. The interface for this procedure is:</p><pre class="programlisting"> +changes. The interface for this procedure is:</p> + +<pre class="programlisting"> procedure revoke_permission ( object_id acs_permissions.object_id%TYPE, grantee_id acs_permissions.grantee_id%TYPE, privilege acs_permissions.privilege%TYPE ); -</pre><p>These procedures are defined in <a class="ulink" href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top"> -<code class="computeroutput">permissions-create.sql</code></a></p><p><span class="strong"><strong>Tcl Procedures</strong></span></p><p>Two Tcl procedures provide a simple call for the query, "Can this +</pre> + +<p>These procedures are defined in <a class="ulink" href="/doc/sql/display-sql?url=acs-permissions-create.sql&package_key=acs-kernel" target="_top"> +<code class="computeroutput">permissions-create.sql</code></a></p> + +<p><span class="strong"><strong>Tcl Procedures</strong></span></p> + +<p>Two Tcl procedures provide a simple call for the query, "Can this user perform this method on this object?" One returns true or false, the -other presents an error page.</p><p>To receive a true or false value, Tcl code should call:</p><pre class="programlisting"> +other presents an error page.</p> + +<p>To receive a true or false value, Tcl code should call:</p> + +<pre class="programlisting"> permission::permission_p -object_id $object_id -party_id $user_id -privilege $method -</pre><p>If the <code class="computeroutput">user_id</code> argument is left out, then the currently logged in -user is checked. To create an error page, Tcl code should call:</p><pre class="programlisting"> +</pre> + +<p>If the <code class="computeroutput">user_id</code> argument is left out, then the currently logged in +user is checked. To create an error page, Tcl code should call:</p> + +<pre class="programlisting"> permission::require_permission -object_id $object_id -privilege $method -</pre><p>These procedures are defined in <code class="computeroutput">acs-permissions-procs.tcl</code>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-ui"></a>User Interface</h3></div></div></div><p>All users of the permissions system are the same at the user-interface +</pre> + +<p>These procedures are defined in <code class="computeroutput">acs-permissions-procs.tcl</code>.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-ui"></a>User Interface</h3></div></div></div> + + + +<p>All users of the permissions system are the same at the user-interface level. If you have the <code class="computeroutput">administer_privileges</code> method permission on an -object, then you may edit privileges for that object with the UI.</p><p>The UI currently provides a list of all granted permissions on the object. +object, then you may edit privileges for that object with the UI.</p> + +<p>The UI currently provides a list of all granted permissions on the object. If the user wishes to revoke privileges, she may select a set of grants, choose revoke, confirm their deletion, and be returned to the same page after -those privileges have been revoked.</p><p>Granting permissions currently (as of 10/2000) works by providing a list +those privileges have been revoked.</p> + +<p>Granting permissions currently (as of 10/2000) works by providing a list of all possible permissions and a list of all parties in the system. (For large sites, some future search mechanism will be necessary.) After choosing privileges to grant, the user is returned to the "edit privileges for -one object" screen.</p><p>If it makes sense, the system will also display a checkbox which the user +one object" screen.</p> + +<p>If it makes sense, the system will also display a checkbox which the user may select to toggle whether permissions are inherited from the object's -context.</p><p>There are a number of potential future enhancements for the permissions -UI, outlined below.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-configure"></a>Configuration/Parameters</h3></div></div></div><p>There are no configuration options for the permissions system.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div><p>The most important future changes to the Permissions system are likely to -be in the UI:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>There should be a page displaying a list of all objects for which the +context.</p> + +<p>There are a number of potential future enhancements for the permissions +UI, outlined below.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-configure"></a>Configuration/Parameters</h3></div></div></div> + + + +<p>There are no configuration options for the permissions system.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div> + + + +<p>The most important future changes to the Permissions system are likely to +be in the UI:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>There should be a page displaying a list of all objects for which the current user is allowed to administer privileges.</p></li><li class="listitem"><p>Users should be able to view the permissions on any object, or perhaps on objects which they have the "read_permissions" method. This would allow them to see what grants are affecting their objects through -inheritance.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-authors"></a>Authors</h3></div></div></div><div class="variablelist"><dl class="variablelist"><dt><span class="term">System creator +inheritance.</p></li></ul></div> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-authors"></a>Authors</h3></div></div></div> + + + +<div class="variablelist"><dl class="variablelist"><dt><span class="term">System creator + </span></dt><dd><p><a class="ulink" href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">System owner </span></dt><dd><p><a class="ulink" href="mailto:rhs@mit.edu" target="_top">Rafael H. Schloming</a></p></dd><dt><span class="term">Documentation author -</span></dt><dd><p>John Prevost</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/11/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta release</td><td>10/04/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Permissions Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Groups Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</span></dt><dd><p>John Prevost</p></dd></dl></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-design-rev-history"></a>Revision History</h3></div></div></div> + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>9/11/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Edited for ACS 4 Beta release</td><td>10/04/2000</td><td>Kai Wu</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="groups-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Permissions Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Groups Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="permissions-design" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="permissions-requirements" id="permissions-requirements"></a>Permissions Requirements</h2></div></div></div><div class="authorblurb"> -<p>By John McClary Prevost</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="permissions-requirements" id="permissions-requirements"></a>Permissions Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By John McClary Prevost</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="permissions-requirements-intro" id="permissions-requirements-intro"></a>Introduction</h3></div></div></div><p>This document records requirements for the OpenACS 4 Permissions system, a component of the OpenACS 4 Kernel. The Permissions system Index: openacs-4/packages/acs-core-docs/www/permissions-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-requirements.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/permissions-requirements.html 7 Aug 2017 23:47:51 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/permissions-requirements.html 8 Nov 2017 09:42:11 -0000 1.36 @@ -1,10 +1,26 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Permissions Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="object-system-design.html" title="Object Model Design"><link rel="next" href="permissions-design.html" title="Permissions Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-requirements"></a>Permissions Requirements</h2></div></div></div><div class="authorblurb"><p>By John McClary Prevost</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-intro"></a>Introduction</h3></div></div></div><p>This document records requirements for the OpenACS 4 Permissions system, a +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Permissions Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="object-system-design.html" title="Object Model Design"><link rel="next" href="permissions-design.html" title="Permissions Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-requirements"></a>Permissions Requirements</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By John McClary Prevost</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-intro"></a>Introduction</h3></div></div></div> + + + +<p>This document records requirements for the OpenACS 4 Permissions system, a component of the OpenACS 4 Kernel. The Permissions system is meant to unify and -centralize the handling of access and control on a given OpenACS 4 system.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-vision"></a>Vision Statement</h3></div></div></div><p>Any multi-user software system must address the general problem of +centralize the handling of access and control on a given OpenACS 4 system.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-vision"></a>Vision Statement</h3></div></div></div> + + + +<p>Any multi-user software system must address the general problem of permissions, or "who can do what, on what." On web services, which typically involve large numbers of users belonging to different groups, permissions handling is a critical need: access to content, services, and @@ -14,78 +30,220 @@ manner reduces both cost and risk: cost, in that less code has to be written and maintained for dealing with recurring permissions situations; risk, in that we need not rely on any single programmer's diligence to ensure -access control is implemented and enforced correctly.</p><p><span class="strong"><strong>Historical Motivations</strong></span></p><p>In earlier versions of the OpenACS, permissions and access control was handled +access control is implemented and enforced correctly.</p> + +<p><span class="strong"><strong>Historical Motivations</strong></span></p> + +<p>In earlier versions of the OpenACS, permissions and access control was handled on a module-by-module basis, often even on a page-by-page basis. For example, a typical module might allow any registered user to access its pages read-only, but only allow members of a certain group to make changes. The way this group was determined also varied greatly between modules. Some modules used "roles", while others did not. Other modules did all access control based simply on coded rules regarding who can act on a given database -row based on the information in that row.</p><p>Problems resulting from this piecemeal approach to permissions and access +row based on the information in that row.</p> + +<p>Problems resulting from this piecemeal approach to permissions and access control were many, the two major ones being inconsistency, and repeated/redundant code. Thus the drive in OpenACS 4 to provide a unified, consistent permissions system that both programmers and administrators can -readily use.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-system-overview"></a>System Overview</h3></div></div></div><p>The OpenACS 4 Permissions system has two main pieces: first, an API for +readily use.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-system-overview"></a>System Overview</h3></div></div></div> + + + +<p>The OpenACS 4 Permissions system has two main pieces: first, an API for developers to readily handle access control in their applications. The second piece of the system is a UI meant primarily for (subsite) administrators to -grant and revoke permissions to system entities under their control.</p><p>Consistency is a key characteristic of the Permissions system - both for a +grant and revoke permissions to system entities under their control.</p> + +<p>Consistency is a key characteristic of the Permissions system - both for a common administrative interface, and easily deployed and maintained access control. The system must be flexible enough to support every access model required in OpenACS applications, but not so flexible that pieces will go unused -or fall outside the common administrative interfaces.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-"></a>Use Cases and User Scenarios</h3></div></div></div><p><span class="strong"><strong>Terminology</strong></span></p><p>The primary question an access control system must answer is a three-way +or fall outside the common administrative interfaces.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-"></a>Use Cases and User Scenarios</h3></div></div></div> + + + +<p><span class="strong"><strong>Terminology</strong></span></p> + +<p>The primary question an access control system must answer is a three-way relation, like that between the parts of most simple sentences. A simple sentence generally has three parts, a subject, an object, and a verb - in the context of OpenACS Permissions, our simple sentence is, "Can this party -perform this operation on this target?" Definitions:</p><p>The subject of the sentence is "<span class="strong"><strong>party</strong></span>" - a +perform this operation on this target?" Definitions:</p> + + +<p>The subject of the sentence is "<span class="strong"><strong>party</strong></span>" - a distinguishable actor whose access may be controlled, this special word is used because one person may be represented by several parties, and one party -may represent many users (or no users at all).</p><p>The object of the sentence is "<span class="strong"><strong>target</strong></span>" - this +may represent many users (or no users at all).</p> + +<p>The object of the sentence is "<span class="strong"><strong>target</strong></span>" - this is an entity, or object, that the party wishes to perform some action on. An -entity/object here is anything that can be put under access control.</p><p>The verb of the sentence is "operation" - a behavior on the OpenACS +entity/object here is anything that can be put under access control.</p> + +<p>The verb of the sentence is "operation" - a behavior on the OpenACS system subject to control, this word is used to represent the fact that a single operation may be part of many larger actions the system wants to perform. If "foo" is an operation, than we sometimes refer to the foo "privilege" to mean that a user has the privilege to perform -that operation.</p><p>Examples of the essential question addressed by the Permissions system: +that operation.</p> + + +<p>Examples of the essential question addressed by the Permissions system: Can jane@attacker.com delete the web security forum? Can the Boston office (a party) within the VirtuaCorp intranet/website create its own news -instance?</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-links"></a>Related Links</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="permissions-design.html" title="Permissions Design">OpenACS 4 Permissions Design</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-func-req"></a>Functional Requirements</h3></div></div></div><p><span class="strong"><strong>10.0 Granularity</strong></span></p><p>The system must support access control down to the level of a single +instance?</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-links"></a>Related Links</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="permissions-design.html" title="Permissions Design">OpenACS 4 Permissions Design</a></p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-func-req"></a>Functional Requirements</h3></div></div></div> + + + +<p><span class="strong"><strong>10.0 Granularity</strong></span></p> + +<p>The system must support access control down to the level of a single entity (this would imply down to the level of a row in the OpenACS Objects data -model).</p><p><span class="strong"><strong>20.0 Operations</strong></span></p><p>The system itself must be able to answer the essential permissions -question as well as several derived questions.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.10 Basic Access Check</strong></span></p><p>The system must be able to answer the question, "May party P perform -operation O on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.20 Allowed Parties Check</strong></span></p><p>The system must be able to answer the question, "Which parties may -perform operation O on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.30 Allowed Operations Check</strong></span></p><p>The system must be able to answer the question, "Which operations may -party P perform on target T?"</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.40 Allowed Targets Check</strong></span></p><p>The system must be able to answer the question, "Upon which targets -may party P perform operation O?"</p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-behave-req"></a>Behavioral Requirements</h3></div></div></div><p><span class="strong"><strong>40.0 Scale of Privileges</strong></span></p><p>Privileges must be designed with appropriate scope for a given OpenACS +model).</p> + +<p><span class="strong"><strong>20.0 Operations</strong></span></p> + +<p>The system itself must be able to answer the essential permissions +question as well as several derived questions.</p> + +<div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.10 Basic Access Check</strong></span></p> + +<p>The system must be able to answer the question, "May party P perform +operation O on target T?"</p> + +</blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.20 Allowed Parties Check</strong></span></p> + +<p>The system must be able to answer the question, "Which parties may +perform operation O on target T?"</p> + +</blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.30 Allowed Operations Check</strong></span></p> + +<p>The system must be able to answer the question, "Which operations may +party P perform on target T?"</p> + +</blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.40 Allowed Targets Check</strong></span></p> + +<p>The system must be able to answer the question, "Upon which targets +may party P perform operation O?"</p> +</blockquote></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-behave-req"></a>Behavioral Requirements</h3></div></div></div> + + + +<p><span class="strong"><strong>40.0 Scale of Privileges</strong></span></p> + +<p>Privileges must be designed with appropriate scope for a given OpenACS package. Some privileges are of general utility (e.g. "read" and "write"). Others are of more limited use (e.g. "moderate" - applies mainly to a package like forum, where many users are contributing content simultaneously). A package defining its own privileges should do so with moderation, being careful not to overload a privilege like -"read" to mean too many things.</p><p><span class="strong"><strong>50.0 Aggregation of Operations (Privileges)</strong></span></p><p>For user interface purposes, it can be appropriate to group certain +"read" to mean too many things.</p> + +<p><span class="strong"><strong>50.0 Aggregation of Operations (Privileges)</strong></span></p> + +<p>For user interface purposes, it can be appropriate to group certain privileges under others. For example, anyone with the "admin" privilege may also automatically receive "read", "write", -"delete", etc. privileges.</p><p><span class="strong"><strong>60.0 Aggregation of Parties (Groups)</strong></span></p><p>The system must allow aggregation of parties. The exact method used for +"delete", etc. privileges.</p> + +<p><span class="strong"><strong>60.0 Aggregation of Parties (Groups)</strong></span></p> + +<p>The system must allow aggregation of parties. The exact method used for aggregation will probably be addressed by the OpenACS 4 "Groups" system. Regardless of the exact behavior of aggregate parties, if an aggregate party exists, then access which is granted to the aggregate party -should be available to all members of that aggregate.</p><p><span class="strong"><strong>70.0 Scope of Access Control</strong></span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.10 Context</strong></span></p><p>There must be a method for objects to receive default access control from +should be available to all members of that aggregate.</p> + +<p><span class="strong"><strong>70.0 Scope of Access Control</strong></span></p> + +<div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.10 Context</strong></span></p> + +<p>There must be a method for objects to receive default access control from some context. For example, if you do not have read access to a forum, you -should not have read access to a message in that forum.</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.20 Overriding</strong></span></p><p>It must be possible to override defaults provided by the context of an -object (as in 70.10), in both a positive and negative manner.</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.20.10 Positive Overriding</strong></span></p><p>It must be possible to allow a party more access to some target than they +should not have read access to a message in that forum.</p> + +</blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.20 Overriding</strong></span></p> + +<p>It must be possible to override defaults provided by the context of an +object (as in 70.10), in both a positive and negative manner.</p> +</blockquote></div> + +<div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.20.10 Positive Overriding</strong></span></p> + +<p>It must be possible to allow a party more access to some target than they would get by default. (For example, a user does not have the right to edit any message on a forum. But a user does possibly have the right to edit -their own messages.)</p></blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.20.20 Negative Overriding</strong></span></p><p>It must be possible to deny a party access to some target that their +their own messages.)</p> + +</blockquote></div><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>70.20.20 Negative Overriding</strong></span></p> + +<p>It must be possible to deny a party access to some target that their inherited privileges would have allowed. (For example, a subdirectory in the file-storage might normally have its parent directory as context. It should -be possible, however, to make a subdirectory private to some group.)</p></blockquote></div><p><span class="strong"><strong>100.0 Efficiency</strong></span></p><p>At least the basic access check (20.10) and the allowed targets check +be possible, however, to make a subdirectory private to some group.)</p> +</blockquote></div> + + +<p><span class="strong"><strong>100.0 Efficiency</strong></span></p> + +<p>At least the basic access check (20.10) and the allowed targets check (20.40) must be efficient enough for general use, i.e. scalable under fairly heavy website traffic. It can be expected that almost every page will contain at least one basic access check, and most pages will contain an allowed -targets check (20.40).</p><p>In particular, constraining a <code class="computeroutput">SELECT</code> to return only rows the +targets check (20.40).</p> + +<p>In particular, constraining a <code class="computeroutput">SELECT</code> to return only rows the current user has access to should not be much slower than the <code class="computeroutput">SELECT</code> -on its own.</p><p><span class="strong"><strong>120.0 Ease of Use</strong></span></p><p>Since most SQL queries will contain an allowed target check in the where +on its own.</p> + +<p><span class="strong"><strong>120.0 Ease of Use</strong></span></p> + +<p>Since most SQL queries will contain an allowed target check in the where clause, whatever mechanism is used to make checks in SQL should be fairly -small and simple.</p><p>In particular, constraining a <code class="computeroutput">SELECT</code> to return only rows the -current user has access to should not add more than one line to a query.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/17/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Revised, updated with new terminology</td><td>8/25/2000</td><td>John Prevost</td></tr><tr><td>0.3</td><td>Edited, reformatted to conform to requirements template, pending -freeze.</td><td>8/26/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Edited for ACS 4 Beta release.</td><td>10/03/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr><tr><td width="40%" align="left">Object Model Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Permissions Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +small and simple.</p> + +<p>In particular, constraining a <code class="computeroutput">SELECT</code> to return only rows the +current user has access to should not add more than one line to a query.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-requirements-history"></a>Revision History</h3></div></div></div> + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>8/17/2000</td><td>John Prevost</td></tr><tr><td>0.2</td><td>Revised, updated with new terminology</td><td>8/25/2000</td><td>John Prevost</td></tr><tr><td>0.3</td><td>Edited, reformatted to conform to requirements template, pending +freeze.</td><td>8/26/2000</td><td>Kai Wu</td></tr><tr><td>0.4</td><td>Edited for ACS 4 Beta release.</td><td>10/03/2000</td><td>Kai Wu</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-system-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions-design.html">Next</a></td></tr><tr><td width="40%" align="left">Object Model Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Permissions Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -130,7 +130,7 @@ <a name="permissions-tedious-context-hierarchy" id="permissions-tedious-context-hierarchy"></a>Context Hierarchy</h3></div></div></div><p>Suppose objects <span class="emphasis"><em>A</em></span>, <span class="emphasis"><em>B</em></span>, ..., and <span class="emphasis"><em>F</em></span> form the following hierarchy.</p><div class="table"> -<a name="idp140592100090856" id="idp140592100090856"></a><p class="title"><strong>Table 11.2. Context Hierarchy +<a name="idp140623163017608" id="idp140623163017608"></a><p class="title"><strong>Table 11.2. Context Hierarchy Example</strong></p><div class="table-contents"><table class="table" summary="Context Hierarchy Example" cellspacing="0" border="1"> <colgroup> <col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"> @@ -156,7 +156,7 @@ </table></div> </div><br class="table-break"><p>This can be represented in the <a class="xref" href="permissions-tediously-explained">acs_objects</a> table by the following entries:</p><div class="table"> -<a name="idp140592100109768" id="idp140592100109768"></a><p class="title"><strong>Table 11.3. acs_objects example +<a name="idp140623167583592" id="idp140623167583592"></a><p class="title"><strong>Table 11.3. acs_objects example data</strong></p><div class="table-contents"><table class="table" summary="acs_objects example data" cellspacing="0" border="1"> <colgroup> <col align="center" class="c1"><col align="center" class="c2"> Index: openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html,v diff -u -r1.47 -r1.48 --- openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 7 Aug 2017 23:47:51 -0000 1.47 +++ openacs-4/packages/acs-core-docs/www/permissions-tediously-explained.html 8 Nov 2017 09:42:11 -0000 1.48 @@ -1,11 +1,21 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Permissions Tediously Explained</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="parties.html" title="Parties in OpenACS"><link rel="next" href="object-identity.html" title="Object Identity"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-tediously-explained"></a>OpenACS Permissions Tediously Explained</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Permissions Tediously Explained</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="parties.html" title="Parties in OpenACS"><link rel="next" href="object-identity.html" title="Object Identity"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions-tediously-explained"></a>OpenACS Permissions Tediously Explained</h2></div></div></div> + + <p> by Vadim Nasardinov. Modified and converted to Docbook XML by Roberto Mello - </p><p>The code has been modified since this document was written so it is now out of date. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=121807" target="_top">this forum thread</a>.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-overview"></a>Permissions Overview</h3></div></div></div><p><span class="strong"><strong>Who + </p> + + <p>The code has been modified since this document was written so it is now out of date. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=121807" target="_top">this forum thread</a>.</p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-overview"></a>Permissions Overview</h3></div></div></div> + + + <p><span class="strong"><strong>Who (<code class="computeroutput">grantee_id</code>) can do what (<code class="computeroutput">privilege</code>) on which object (<code class="computeroutput">object_id</code>). - </strong></span></p><p> + </strong></span></p> + <p> The general permissions system has a flexible (and relatively complex) data model in OpenACS. Developers who have not had the time to learn the internals of the data model may end up writing seemingly correct code that crashes their system in @@ -17,12 +27,16 @@ Groups, Context, Permissions documentation</a>, but who have not had the opportunity to take a long, careful look at the system internals. - </p><p> + </p> + + <p> In OpenACS, most of the interesting tables are expected to extend (subtype) the <code class="computeroutput">acs_objects</code> table, i.e. they are expected to have an integer primary key column that references the <code class="computeroutput">object_id</code> column of <code class="computeroutput">acs_objects</code>. - </p><a name="acs_objects"></a><pre class="programlisting"> + </p> + + <a name="acs_objects"></a><pre class="programlisting"> create table <span class="bold"><strong>acs_objects</strong></span> ( object_id integer not null @@ -45,24 +59,33 @@ constraint acs_objects_context_object_un unique (context_id, object_id) disable ); - </pre><p> + </pre> + + <p> This means that items that want to use the features of the OpenACS object system needs to have an entry in the <code class="computeroutput">acs_objects</code>. This allows developers to define relationships between any two entities <span class="emphasis"><em>A</em></span> and <span class="emphasis"><em>B</em></span> by defining a relationship between their corresponding entries in the <code class="computeroutput">acs_objects</code> table. One of the applications of this powerful capability is the general permissions system. - </p><p> + </p> + + <p> At the heart of the permission system are two tables: <code class="computeroutput">acs_privileges</code> and <code class="computeroutput">acs_permissions</code>. - </p><a name="acs_privileges"></a><pre class="programlisting"> + </p> + + + <a name="acs_privileges"></a><pre class="programlisting"> create table <span class="bold"><strong>acs_privileges</strong></span> ( privilege varchar2(100) not null constraint acs_privileges_pk primary key, pretty_name varchar2(100), pretty_plural varchar2(100) ); - </pre><a name="acs_permissions"></a><pre class="programlisting"> + </pre> + + <a name="acs_permissions"></a><pre class="programlisting"> create table <span class="bold"><strong>acs_permissions</strong></span> ( object_id not null @@ -76,36 +99,59 @@ constraint acs_permissions_pk primary key (object_id, grantee_id, privilege) ); - </pre><p> + </pre> + + <p> The <code class="computeroutput">acs_privileges</code> table stores named privileges like <span class="emphasis"><em>read</em></span>, <span class="emphasis"><em>write</em></span>, <span class="emphasis"><em>delete</em></span>, <span class="emphasis"><em>create</em></span>, and <span class="emphasis"><em>admin</em></span>. The <code class="computeroutput">acs_permissions</code> table stores assertions of the form: - </p><p> + </p> + + <p> Who (<code class="computeroutput">grantee_id</code>) can do what (<code class="computeroutput">privilege</code>) on which object (<code class="computeroutput">object_id</code>). - </p><p> + </p> + + <p> The micromanaging approach to system security would be to require application developers to store permission information explicitly about every object, i.e. if the system has 100,000 and 1,000 users who have the <span class="emphasis"><em>read</em></span> privilege on all objects, then we would need to store 100,000,000 entries of the form: - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center">object_id</th><th align="center">grantee_id</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">object_id_1</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_n</td><td align="center">'read'</td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center">object_id</th><th align="center">grantee_id</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">object_id_1</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_1</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_2</td><td align="center">user_id_n</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_1</td><td align="center">'read'</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_2</td><td align="center">'read'</td></tr><tr><td colspan="3" align="center">...</td></tr><tr><td align="center">object_id_m</td><td align="center">user_id_n</td><td align="center">'read'</td></tr></tbody></table> + </div> + + <p> Although quite feasible, this approach fails to take advantage of the fact that objects in the system are commonly organized hierarchally, and permissions usually follow the hierarchical structure, so that if user <span class="emphasis"><em>X</em></span> has the <span class="emphasis"><em>read</em></span> privilege on object <span class="emphasis"><em>A</em></span>, she typically also has the <span class="emphasis"><em>read</em></span> privilege on all objects attached under <span class="emphasis"><em>A</em></span>. - </p><p> + </p> + <p> The general permission system takes advantage of the hierarchical organization of objects to unburden developers of the necessity to explicitly maintain security information for every single object. There are three kinds of hierarchies involved. These are discussed in the following sections. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-context-hierarchy"></a>Context Hierarchy</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-context-hierarchy"></a>Context Hierarchy</h3></div></div></div> + + + <p> Suppose objects <span class="emphasis"><em>A</em></span>, <span class="emphasis"><em>B</em></span>, ..., and <span class="emphasis"><em>F</em></span> form the following hierarchy. - </p><div class="table"><a name="idp140592100090856"></a><p class="title"><b>Table 11.2. Context Hierarchy Example</b></p><div class="table-contents"><table class="table" summary="Context Hierarchy Example" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><tbody><tr><td colspan="3" align="center"> + </p> + + <div class="table"><a name="idp140623163017608"></a><p class="title"><b>Table 11.2. Context Hierarchy Example</b></p><div class="table-contents"> + + <table class="table" summary="Context Hierarchy Example" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><tbody><tr><td colspan="3" align="center"> <span class="bold"><strong>A</strong></span> <p> <code class="computeroutput">object_id=10</code> @@ -135,38 +181,68 @@ <p> <code class="computeroutput">object_id=60</code> </p> - </td></tr></tbody></table></div></div><br class="table-break"><p> + </td></tr></tbody></table> + </div></div><br class="table-break"> + + <p> This can be represented in the <a class="xref" href="permissions-tediously-explained.html#acs_objects">acs_objects</a> table by the following entries: - </p><div class="table"><a name="idp140592100109768"></a><p class="title"><b>Table 11.3. acs_objects example data</b></p><div class="table-contents"><table class="table" summary="acs_objects example data" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"></colgroup><thead><tr><th align="center">object_id</th><th align="center">context_id</th></tr></thead><tbody><tr><td align="center">20</td><td align="center">10</td></tr><tr><td align="center">30</td><td align="center">10</td></tr><tr><td align="center">40</td><td align="center">20</td></tr><tr><td align="center">50</td><td align="center">20</td></tr><tr><td align="center">60</td><td align="center">30</td></tr></tbody></table></div></div><br class="table-break"><p> + </p> + + <div class="table"><a name="idp140623167583592"></a><p class="title"><b>Table 11.3. acs_objects example data</b></p><div class="table-contents"> + + <table class="table" summary="acs_objects example data" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"></colgroup><thead><tr><th align="center">object_id</th><th align="center">context_id</th></tr></thead><tbody><tr><td align="center">20</td><td align="center">10</td></tr><tr><td align="center">30</td><td align="center">10</td></tr><tr><td align="center">40</td><td align="center">20</td></tr><tr><td align="center">50</td><td align="center">20</td></tr><tr><td align="center">60</td><td align="center">30</td></tr></tbody></table> + </div></div><br class="table-break"> + + <p> 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 <a class="ulink" href="http://www.oradoc.com/ora817/server.817/a85397/expressi.htm#1023748" target="_top">CONNECT BY</a> query, we can compute that object 40 is the second-generation descendant of object 10. With this in mind, if we want to record the fact that user Joe has the <span class="emphasis"><em>read</em></span> privilege on objects <span class="emphasis"><em>A</em></span>, ..., <span class="emphasis"><em>F</em></span>, we only need to record one entry in the <a class="xref" href="permissions-tediously-explained.html#acs_permissions">acs_permissions</a> table. - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center">object</th><th align="center">grantee</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">Joe</td><td align="center">read</td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center">object</th><th align="center">grantee</th><th align="center">privilege</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">Joe</td><td align="center">read</td></tr></tbody></table> + </div> + + <p> The fact that Joe can also read <span class="emphasis"><em>B</em></span>, <span class="emphasis"><em>C</em></span>, ..., and <span class="emphasis"><em>F</em></span> can be derived by ascertaining that these objects are children of <span class="emphasis"><em>A</em></span> by traversing the context hierarchy. As it turns out, hierarchical queries are expensive. As Rafael Schloming put it so aptly, <span class="emphasis"><em>Oracle can't deal with hierarchies for shit.</em></span> - </p><p> + </p> + + <p> One way to solve this problem is to cache a flattened view of the context tree like so: - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center">object</th><th align="center">ancestor</th><th align="center">n_generations</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">A</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">B</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">C</td><td align="center">C</td><td align="center">0</td></tr><tr><td align="center">C</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">D</td><td align="center">0</td></tr><tr><td align="center">D</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">E</td><td align="center">E</td><td align="center">0</td></tr><tr><td align="center">E</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">E</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">F</td><td align="center">F</td><td align="center">0</td></tr><tr><td align="center">F</td><td align="center">C</td><td align="center">1</td></tr><tr><td align="center">F</td><td align="center">A</td><td align="center">2</td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center">object</th><th align="center">ancestor</th><th align="center">n_generations</th></tr></thead><tbody><tr><td align="center">A</td><td align="center">A</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">B</td><td align="center">0</td></tr><tr><td align="center">B</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">C</td><td align="center">C</td><td align="center">0</td></tr><tr><td align="center">C</td><td align="center">A</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">D</td><td align="center">0</td></tr><tr><td align="center">D</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">D</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">E</td><td align="center">E</td><td align="center">0</td></tr><tr><td align="center">E</td><td align="center">B</td><td align="center">1</td></tr><tr><td align="center">E</td><td align="center">A</td><td align="center">2</td></tr><tr><td align="center">F</td><td align="center">F</td><td align="center">0</td></tr><tr><td align="center">F</td><td align="center">C</td><td align="center">1</td></tr><tr><td align="center">F</td><td align="center">A</td><td align="center">2</td></tr></tbody></table> + </div> + + <p> Note that the number of entries in the flattened view grows exponentially with respect to the depth of the context tree. For instance, if you have a fully populated binary tree with a depth of <span class="emphasis"><em>n</em></span>, then the number of entries in its flattened view is - </p><p> - 1 + 2*2 + 3*4 + 4*8 + 5*16 + ... + (n+1)*2<sup>n</sup> = n*2<sup>n+1</sup> + 1</p><p> + </p> + + <p> + 1 + 2*2 + 3*4 + 4*8 + 5*16 + ... + (n+1)*2<sup>n</sup> = n*2<sup>n+1</sup> + 1</p> + + <p> Despite its potentially great storage costs, maintaining a flattened representation of the context tree is exactly what OpenACS does. The flattened context tree is stored in the <code class="computeroutput">acs_object_context_index</code> table. - </p><a name="acs_object_context_index"></a><pre class="programlisting"> + </p> + + <a name="acs_object_context_index"></a><pre class="programlisting"> create table <span class="bold"><strong>acs_object_context_index</strong></span> ( object_id not null @@ -180,7 +256,9 @@ constraint acs_object_context_index_pk primary key (object_id, ancestor_id) ) organization index; - </pre><p> + </pre> + + <p> A few things to note about this table are these. Number one, it is an <a class="ulink" href="http://www.oradoc.com/ora817/server.817/a85397/statem3e.htm#2061922" target="_top">index-organized table</a>, which means it is substantially optimized for access by primary key. @@ -189,11 +267,15 @@ with respect to the average number of descendants that an object has, and <span class="strong"><strong>exponentially</strong></span> with respect to the depth of the context tree. - </p><p> + </p> + + <p> The <code class="computeroutput">acs_object_context_index</code> is kept in sync with the <a class="xref" href="permissions-tediously-explained.html#acs_objects">acs_objects</a> table by triggers like this: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> create or replace trigger acs_objects_context_id_in_tr after insert on <a class="xref" href="permissions-tediously-explained.html#acs_objects">acs_objects</a> for each row @@ -220,13 +302,18 @@ (:new.object_id, 0, 1); end if; end; -</pre><p> +</pre> + + <p> One final note about <a class="xref" href="permissions-tediously-explained.html#acs_objects">acs_objects</a>. By setting an object's <code class="computeroutput">security_inherit_p</code> column to 'f', you can stop permissions from cascading down the context tree. In the following example, Joe does not have the read permissions on <span class="emphasis"><em>C</em></span> and <span class="emphasis"><em>F</em></span>. - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><tbody><tr><td colspan="3" align="center"> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><tbody><tr><td colspan="3" align="center"> <div class="literallayout"><p><br> <span class="bold"><strong>A</strong></span><br> <code class="computeroutput">object_id=10</code><br> @@ -262,12 +349,22 @@ security_inherit_p = 'f'<br> <span class="emphasis"><em>not readable by Joe</em></span><br> </p></div> - </td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-privilege-hierarchy"></a>Privilege Hierarchy</h3></div></div></div><p> + </td></tr></tbody></table> + </div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-privilege-hierarchy"></a>Privilege Hierarchy</h3></div></div></div> + + + <p> Privileges are also organized hierarchically. In addition to the five main system privileges defined in the ACS Kernel data model, application developers may define their own. Note, however, that this is no longer recommended practice. - </p><p> + </p> + + <p> By defining parent-child relationship between privileges, the OpenACS data model makes it easier for developers to manage permissions. Instead of granting a user explicit @@ -276,14 +373,24 @@ privileges on an object, it is sufficient to grant the user the <span class="emphasis"><em>admin</em></span> privilege to which the first four privileges are tied. Privileges are structured as follows. - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"><col align="center" class="c4"></colgroup><tbody><tr><td colspan="4" align="center">admin</td></tr><tr><td align="center">create</td><td align="center">delete</td><td align="center">read</td><td align="center">write</td></tr></tbody></table></div><p> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"><col align="center" class="c4"></colgroup><tbody><tr><td colspan="4" align="center">admin</td></tr><tr><td align="center">create</td><td align="center">delete</td><td align="center">read</td><td align="center">write</td></tr></tbody></table> + </div> + + <p> Note that <code class="computeroutput">admin</code> privileges are greater than read, write, create and delete privileges combined. Issuing someone read, write, create and delete privileges will not result in the person getting - <code class="computeroutput">admin</code> privileges.</p><p>The parent-child relationship between privileges is represented in + <code class="computeroutput">admin</code> privileges.</p> + <p>The parent-child relationship between privileges is represented in the <code class="computeroutput">acs_privilege_hierarchy</code> table: - </p><a name="acs_privilege_hierarchy"></a><pre class="programlisting"> + </p> + + + <a name="acs_privilege_hierarchy"></a><pre class="programlisting"> create table <span class="bold"><strong>acs_privilege_hierarchy</strong></span> ( privilege not null @@ -294,10 +401,14 @@ constraint acs_privilege_hierarchy_pk primary key (privilege, child_privilege) ); - </pre><p> + </pre> + + <p> As in the case of the context hierarchy, it is convenient to have a flattened representation of this hierarchal structure. This is accomplished by defining the following view. - </p><a name="acs_privilege_descendant_map"></a><pre class="programlisting"> + </p> + + <a name="acs_privilege_descendant_map"></a><pre class="programlisting"> create or replace view <span class="bold"><strong>acs_privilege_descendant_map</strong></span> as select @@ -318,23 +429,38 @@ prior child_privilege = privilege ) or p2.privilege = p1.privilege; - </pre><p> + </pre> + + <p> As the number of different privileges in the system is expected to be reasonably small, there is no pressing need to cache the flattened ansector-descendant view of the privilege hierarchy in a specially maintained table like it is done in the case of the context hierarchy. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-party-hierarchy"></a>Party Hierarchy</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-party-hierarchy"></a>Party Hierarchy</h3></div></div></div> + + + <p> Now for the third hierarchy playing a promiment role in the permission system. The party data model is set up as follows. - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"></colgroup><tbody><tr><td colspan="2" align="center"> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"></colgroup><tbody><tr><td colspan="2" align="center"> <a class="xref" href="permissions-tediously-explained.html#tedious-parties">parties</a> </td></tr><tr><td align="center"> <a class="xref" href="permissions-tediously-explained.html#persons">persons</a> </td><td rowspan="2" align="center" valign="top"> <a class="xref" href="permissions-tediously-explained.html#groups">groups</a> </td></tr><tr><td align="center"> <a class="xref" href="permissions-tediously-explained.html#users">users</a> - </td></tr></tbody></table></div><a name="tedious-parties"></a><pre class="programlisting"> + </td></tr></tbody></table> + </div> + + <a name="tedious-parties"></a><pre class="programlisting"> create table <span class="bold"><strong>parties</strong></span> ( party_id not null @@ -344,7 +470,9 @@ constraint parties_email_un unique, url varchar2(200) ); - </pre><a name="persons"></a><pre class="programlisting"> + </pre> + + <a name="persons"></a><pre class="programlisting"> create table <span class="bold"><strong>persons</strong></span> ( person_id not null @@ -355,7 +483,9 @@ last_name varchar2(100) not null ); - </pre><a name="users"></a><pre class="programlisting"> + </pre> + + <a name="users"></a><pre class="programlisting"> create table <span class="bold"><strong>users</strong></span> ( user_id not null @@ -364,30 +494,38 @@ password char(40), -- other attributes ); - </pre><a name="groups"></a><pre class="programlisting"> + </pre> + + <a name="groups"></a><pre class="programlisting"> create table <span class="bold"><strong>groups</strong></span> ( group_id not null constraint groups_group_id_fk references <a class="xref" href="permissions-tediously-explained.html#tedious-parties">parties</a> (party_id) constraint groups_pk primary key, group_name varchar2(100) not null ); - </pre><p> + </pre> + + <p> Recall that the <code class="computeroutput">grantee_id</code> column of the <a class="xref" href="permissions-tediously-explained.html#acs_permissions">acs_permissions</a> table references <code class="computeroutput">parties.party_id</code>. This means that you can grant a privilege on an object to a party, person, user, or group. Groups represent aggregations of parties. The most common scenario that you are likely to encounter is a group that is a collection of users, although you could also have collections of persons, groups, parties, or any mix thereof. - </p><p> + </p> + + <p> Given that the most common use of groups is to partition users, how do you build groups? One way is to grant membership explicitly. If you have a group named <span class="emphasis"><em>Pranksters</em></span>, you can assign membership to Pete, Poly, and Penelope. The fact that these users are members of the <span class="emphasis"><em>Pranksters</em></span> group will be recorded in the <code class="computeroutput">membership_rels</code> and <code class="computeroutput">acs_rels</code> tables: - </p><a name="acs_rels"></a><pre class="programlisting"> + </p> + + <a name="acs_rels"></a><pre class="programlisting"> create table <span class="bold"><strong>acs_rels</strong></span> ( rel_id not null @@ -405,7 +543,9 @@ constraint acs_object_rels_un unique (rel_type, object_id_one, object_id_two) ); - </pre><a name="membership_rels"></a><pre class="programlisting"> + </pre> + + <a name="membership_rels"></a><pre class="programlisting"> create table <span class="bold"><strong>membership_rels</strong></span> ( rel_id constraint membership_rel_rel_id_fk references <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a> (rel_id) @@ -415,10 +555,15 @@ constraint membership_rel_mem_ck check (member_state in ('approved', 'banned', 'rejected', 'deleted')) ); - </pre><p> + </pre> + + <p> The <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a> table entries would look like so: - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center"> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center"> <code class="computeroutput">rel_type</code> </th><th align="center"> <code class="computeroutput">object_one</code> @@ -442,28 +587,38 @@ Pranksters </td><td align="center"> Penelope - </td></tr></tbody></table></div><p>Read <code class="computeroutput">acs_rels</code>: right-side is a + </td></tr></tbody></table> + </div> +<p>Read <code class="computeroutput">acs_rels</code>: right-side is a subset of left-side, ie <code class="computeroutput">object2</code> is a part of <code class="computeroutput">object1</code>. -</p><p> +</p> + <p> Another way of building up groups is by adding subgroups. Suppose we define <span class="emphasis"><em>Merry Pranksters</em></span> and <span class="emphasis"><em>Sad Pranksters</em></span> as subgroups of <span class="emphasis"><em>Pranksters</em></span>. We say that the <span class="emphasis"><em>Pranksters</em></span> group is <span class="strong"><strong>composed</strong></span> of groups <span class="emphasis"><em>Merry Pranksters</em></span> and <span class="emphasis"><em>Sad Pranksters</em></span>. This information is stored in the <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a> and <code class="computeroutput">composition_rels</code> tables. - </p><a name="composition_rels"></a><pre class="programlisting"> + </p> + + <a name="composition_rels"></a><pre class="programlisting"> create table <span class="bold"><strong>composition_rels</strong></span> ( rel_id constraint composition_rels_rel_id_fk references <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a> (rel_id) constraint composition_rels_rel_id_pk primary key ); - </pre><p> + </pre> + + <p> The relevant entries in the <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a> look like so. - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center"> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center"> <code class="computeroutput">rel_type</code> </th><th align="center"> <code class="computeroutput">object_one</code> @@ -481,7 +636,10 @@ Pranksters </td><td align="center"> Sad Pranksters - </td></tr></tbody></table></div><p> + </td></tr></tbody></table> + </div> + + <p> The composition relationship means that if I add Matt, Mel, and Mary to the <span class="emphasis"><em>Merry Pranksters</em></span>, they should also automatically become members of the <span class="emphasis"><em>Pranksters</em></span> group. @@ -492,13 +650,17 @@ <span class="emphasis"><em>G1</em></span> is a subgroup of <span class="emphasis"><em>G2</em></span>, and <span class="emphasis"><em>G2</em></span> is a subgroup of <span class="emphasis"><em>G3</em></span>, then <span class="emphasis"><em>G1</em></span> is a subgroup of <span class="emphasis"><em>G3</em></span>; that is, any member of <span class="emphasis"><em>G1</em></span> is also a member of <span class="emphasis"><em>G3</em></span>. - </p><p> + </p> + + <p> Traversing the group composition hierarchy requires running <a class="ulink" href="http://www.oradoc.com/ora817/server.817/a85397/expressi.htm#1023748" target="_top">hierarchical queries</a>, which are expensive in Oracle. As we saw in the <span class="emphasis"><em>Context Hierarchy</em></span> section, one way of reducing the performance hit incurred by hierarchical queries is to cache query results in a table maintained by triggers. The OpenACS data model defines two such tables: - </p><a name="group_component_index"></a><pre class="programlisting"> + </p> + + <a name="group_component_index"></a><pre class="programlisting"> create table <span class="bold"><strong>group_component_index</strong></span> ( group_id not null constraint group_comp_index_group_id_fk @@ -517,7 +679,9 @@ constraint group_component_index_pk primary key (group_id, component_id, rel_id) ) organization index; - </pre><a name="group_member_index"></a><pre class="programlisting"> + </pre> + + <a name="group_member_index"></a><pre class="programlisting"> create table <span class="bold"><strong>group_member_index</strong></span> ( group_id not null @@ -534,11 +698,16 @@ constraint group_member_index_pk primary key (member_id, group_id, rel_id) ) organization index; - </pre><p> + </pre> + + <p> The <code class="computeroutput">group_component_index</code> table stores a flattened representation of the group composition hierarchy that is maintained in sync with the <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a> and <code class="computeroutput">composition_rels</code> tables through triggers. - </p><p><span class="strong"><strong>additional comments</strong></span></p><p> + </p> + + <p><span class="strong"><strong>additional comments</strong></span></p> + <p> As far as the <code class="computeroutput">group_member_index</code> table goes, I am not sure I understand its purpose. It maintains group-member relationships that are resolved with respect to group composition. Note that information stored in @@ -547,7 +716,9 @@ <a class="xref" href="permissions-tediously-explained.html#acs_rels">acs_rels</a>, and <a class="xref" href="permissions-tediously-explained.html#group_component_index">group_component_index</a>. Here is a view that does it. (This view is <span class="emphasis"><em>not</em></span> part of the OpenACS Kernel data model.) - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> create or replace view group_member_view as select @@ -569,11 +740,15 @@ where mr.rel_id = r.rel_id and r.object_id_one = gci.component_id; - </pre><p> + </pre> + + <p> A heuristic way to verify that <code class="computeroutput">group_member_view</code> is essentially identical to <a class="xref" href="permissions-tediously-explained.html#group_member_index">group_member_index</a> is to compute the symmetric difference between the two: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> select group_id, member_id from @@ -591,18 +766,29 @@ minus select group_id, member_id from group_member_view ) - </pre><p> + </pre> + + <p> The query returns no rows. The important point is, if we have a flattened view of the composition hierarchy -- like one provided by the <a class="xref" href="permissions-tediously-explained.html#group_component_index">group_component_index</a> table -- membership relationship resolution can be computed trivially with no hierarchical queries involved. There is no need to keep the view in a denormalized table, unless doing so results in substantial performance gains. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-putting-all-together"></a>Putting It All Together</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-putting-all-together"></a>Putting It All Together</h3></div></div></div> + + + <p> Security information is queried by calling the <code class="computeroutput">acs_permission.permission_p</code> function in OpenACS. This is accessible from Tcl via the <code class="computeroutput">permission::permission_p</code> procedure. - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> create or replace package body acs_permission as -- some stuff removed for the sake of brevity @@ -625,7 +811,9 @@ end; end acs_permission; - </pre><p><span class="strong"><strong>problem avoidance</strong></span></p><p> + </pre> +<p><span class="strong"><strong>problem avoidance</strong></span></p> + <p> The function queries <a class="xref" href="permissions-tediously-explained.html#acs_object_party_privilege_map">acs_object_party_privilege_map</a>, which is a humongous view that joins three flattened hierarchies: @@ -636,14 +824,22 @@ performed by the <code class="computeroutput">acs_permission.permission_p</code> function. Anything other than that would take forever to finish or would ultimately result in a query error. - </p><p> + </p> + + <p> For example, do not try to do things like - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> select count(*) from <a class="xref" href="permissions-tediously-explained.html#acs_object_party_privilege_map">acs_object_party_privilege_map</a>; - </pre><p> + </pre> + + <p> To give another example of things to avoid, I have seen code like this: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> declare cursor cur is select @@ -668,20 +864,29 @@ end; / - </pre><p> + </pre> + + <p> The <code class="computeroutput">acs_permission.revoke_permission</code> function merely runs a delete statement like so: - </p><pre class="programlisting"> + </p> + + <pre class="programlisting"> delete from acs_permissions where object_id = revoke_permission.object_id and grantee_id = revoke_permission.grantee_id and privilege = revoke_permission.privilege; - </pre><p> + </pre> + + <p> Note that in the above example, <code class="computeroutput">acs_permissions</code> had only one entry that needed to be deleted: - </p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center"> + </p> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col align="center" class="c1"><col align="center" class="c2"><col align="center" class="c3"></colgroup><thead><tr><th align="center"> <code class="computeroutput">object_id</code> </th><th align="center"> <code class="computeroutput">grantee_id</code> @@ -693,11 +898,21 @@ registered_users </td><td align="center"> foo_create - </td></tr></tbody></table></div><p> + </td></tr></tbody></table> + </div> + + <p> The above script would never get around to deleting this entry because it had to loop through a gazillion rows in the humongous <code class="computeroutput">acs_object_party_privilege_map</code> view. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-appendix"></a>Appendix: Various View Definitions</h3></div></div></div><a name="acs_object_party_privilege_map"></a><pre class="programlisting"> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-tedious-appendix"></a>Appendix: Various View Definitions</h3></div></div></div> + + + <a name="acs_object_party_privilege_map"></a><pre class="programlisting"> create or replace view <span class="bold"><strong>acs_object_party_privilege_map</strong></span> as select @@ -716,7 +931,9 @@ privilege from <a class="xref" href="permissions-tediously-explained.html#acs_object_grantee_priv_map">acs_object_grantee_priv_map</a>; - </pre><a name="acs_object_grantee_priv_map"></a><pre class="programlisting"> + </pre> + + <a name="acs_object_grantee_priv_map"></a><pre class="programlisting"> create or replace view <span class="bold"><strong>acs_object_grantee_priv_map</strong></span> as select @@ -728,7 +945,10 @@ <a class="xref" href="permissions-tediously-explained.html#acs_privilege_descendant_map">acs_privilege_descendant_map</a> m where a.privilege = m.privilege; - </pre><a name="acs_permissions_all"></a><pre class="programlisting"> + </pre> + + + <a name="acs_permissions_all"></a><pre class="programlisting"> create or replace view <span class="bold"><strong>acs_permissions_all</strong></span> as select @@ -740,7 +960,9 @@ <a class="xref" href="permissions-tediously-explained.html#acs_permissions">acs_permissions</a> p where op.ancestor_id = p.object_id; - </pre><a name="acs_object_paths"></a><pre class="programlisting"> + </pre> + + <a name="acs_object_paths"></a><pre class="programlisting"> create or replace view <span class="bold"><strong>acs_object_paths</strong></span> as select @@ -749,8 +971,10 @@ n_generations from <a class="xref" href="permissions-tediously-explained.html#acs_object_context_index">acs_object_context_index</a>; - </pre><a name="group_member_map"></a><pre class="programlisting"> + </pre> + <a name="group_member_map"></a><pre class="programlisting"> + create or replace view <span class="bold"><strong>group_member_map</strong></span> as select @@ -760,4 +984,8 @@ container_id from <a class="xref" href="permissions-tediously-explained.html#group_member_index">group_member_index</a>; - </pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr><tr><td width="40%" align="left">Parties in OpenACS </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Object Identity</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="parties.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="object-identity.html">Next</a></td></tr><tr><td width="40%" align="left">Parties in OpenACS </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Object Identity</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/permissions.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/permissions.adp 7 Aug 2017 23:47:51 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/permissions.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="subsites" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="permissions" id="permissions"></a>Groups, Context, Permissions</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="permissions" id="permissions"></a>Groups, Context, Permissions</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="permissions-overview" id="permissions-overview"></a>Overview</h3></div></div></div><p>The OpenACS 5.9.0 Permissions system allows developers and administrators to set access control policies at the object level, @@ -196,8 +193,8 @@ user rights.</p></li><li class="listitem"><p>The Context hierarchy allows you to define organize default permissions in a hierarchical fashion.</p></li> </ol></div><p>A PL/SQL or Tcl API is then used to check permissions in -application pages.</p><div class="cvstag">($‌Id: permissions.xml,v 1.17.6.1 2016/06/23 -08:32:46 gustafn Exp $)</div> +application pages.</p><p><span class="cvstag">($‌Id: permissions.xml,v 1.18 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/permissions.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/permissions.html,v diff -u -r1.51 -r1.52 --- openacs-4/packages/acs-core-docs/www/permissions.html 7 Aug 2017 23:47:51 -0000 1.51 +++ openacs-4/packages/acs-core-docs/www/permissions.html 8 Nov 2017 09:42:11 -0000 1.52 @@ -1,44 +1,80 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Groups, Context, Permissions</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="templates.html" title="Using Templates in OpenACS"><link rel="next" href="subsites.html" title="Writing OpenACS Application Pages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions"></a>Groups, Context, Permissions</h2></div></div></div><div class="authorblurb"><p>By Pete Su</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-overview"></a>Overview</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Groups, Context, Permissions</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="templates.html" title="Using Templates in OpenACS"><link rel="next" href="subsites.html" title="Writing OpenACS Application Pages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="permissions"></a>Groups, Context, Permissions</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Pete Su</p> +</authorblurb></span> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-overview"></a>Overview</h3></div></div></div> + + + +<p> The OpenACS 5.9.0 Permissions system allows developers and administrators to set access control policies at the object level, that is, any application or system object represented by a row in the <code class="computeroutput">acs_objects</code> table can be access-controlled via a PL/SQL or Tcl interface. The permissions system manages a data model that then allows scripts to check permissions using another API call. -</p><p> +</p> + +<p> Although object level permissions seems appropriate, no developer or administrator wants to <span class="emphasis"><em>explicitly</em></span> set access control rights for <span class="emphasis"><em>every user</em></span> and <span class="emphasis"><em>every object</em></span> on a site. Therefore, OpenACS has two auxiliary mechanisms for making this -easier:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>the Groups system allows users to be grouped together +easier:</p> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>the Groups system allows users to be grouped together in flexible ways.</p></li><li class="listitem"><p>the object model defines a notion of <span class="emphasis"><em>object context</em></span>, which allows applications to group objects together into larger security domains. -</p></li></ol></div><p>The rest of this document discusses each of these parts, and how they fit together with the +</p></li></ol></div> +<p>The rest of this document discusses each of these parts, and how they fit together with the permissions system. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-groups"></a>Groups</h3></div></div></div><p> +</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-groups"></a>Groups</h3></div></div></div> + + + + +<p> OpenACS 5.9.0 has an abstraction called a <span class="emphasis"><em>party</em></span>. Parties have a recursive definition. We can illustrate how it works with the following simplified data model. First, we define the <code class="computeroutput">parties</code> table, where each party has an email address and a URL for contact information. -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + create table parties ( party_id integer not null references acs_objects(object_id), email varchar(100), url varchar(100) ) -</pre><p> +</pre> + + +<p> Now we define two subtypes of party, one for persons, and one for groups: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + create table groups ( group_id not null references parties(party_id), group_name varchar(100) not null @@ -50,36 +86,59 @@ last_name varchar(100) not null ) -</pre><p> +</pre> + + +<p> The <code class="computeroutput">users</code> table is also defined in this data model as a subtype of <code class="computeroutput">person</code>. -</p><p> +</p> + +<p> Finally, we define two relations, one for group <span class="emphasis"><em>membership</em></span> and one for group <span class="emphasis"><em>composition</em></span>. -</p><p>The composition relation expresses that every member of group A should also be a +</p> +<p>The composition relation expresses that every member of group A should also be a member of group B. This relation allows us to define a hierarchy of groups. -</p><p> +</p> + +<p> The membership relation maps groups to <span class="emphasis"><em>parties</em></span>. Each member of a group is a party rather than just a user. That is, groups consist of members that are either a person or an entire group. This allows us to say that group A should be a member of another group B. -</p><p> +</p> + +<p> The groups data model is recursive. Modelling parties as either a person or a group provides a way to model complex hierarchical groupings of persons and groups. -</p><p> +</p> + +<p> The full details of the groups data model is beyond the scope of this tutorial. See <a class="xref" href="parties.html" title="Parties in OpenACS">Parties in OpenACS</a> or <a class="xref" href="groups-design.html" title="Groups Design">OpenACS 4 Groups Design</a> for more details. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-permissions"></a>Permissions</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-permissions"></a>Permissions</h3></div></div></div> + + +<p> NOTE: Much more detailed information about the permissions system and how to use it is available in the <a class="xref" href="permissions-tediously-explained.html" title="OpenACS Permissions Tediously Explained">OpenACS Permissions Tediously Explained</a> document. -</p><p> +</p> + +<p> The permissions data model is a mapping between <span class="emphasis"><em>privileges</em></span>, parties and objects. Parties and objects have already been discussed. Now we focus on privileges. -</p><p> +</p> + +<p> In OpenACS, a privilege describes the right to perform some operation on some object. Privileges are the basic units out of which we build access control policies. For example in the Unix filesystem, access is controlled by granting users some combination of @@ -93,7 +152,10 @@ automatically granted all the child privileges that the privilege contains. The OpenACS 5.9.0 kernel data model defines these privileges: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> # begin acs_privilege.create_privilege('read'); @@ -110,62 +172,92 @@ commit; end; -</pre><p> +</pre> +<p> Note that a user does not gain admin privileges when granted read, write, create and delete privileges, because some operations explicitly require admin privileges. No substitutions. -</p><p> +</p> + +<p> To give a user permission to perform a particular operation on a particular object you call <code class="computeroutput">acs_permission.grant_permission</code> like this: - </p><pre class="programlisting"> + </p> + +<pre class="programlisting"> # sql code acs_permission.grant_permission ( object_id => some_object_id, grantee_id => some_party_id, privilege => 'some_privilege_name' ); -</pre><p> +</pre> + + +<p> Using just these mechanisms is enough for developers and administrators to effectively define access control for every object in a system. -</p><p>Explicitly defining permissions to every object individually +</p> +<p>Explicitly defining permissions to every object individually would become very tedious. OpenACS provides a object contexts as a means for controlling permissions of a large group of objects at the same time. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-object-context"></a>Object Context</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-object-context"></a>Object Context</h3></div></div></div> + + + +<p> In OpenACS 5.9.0, object context is a scoping mechanism. "Scoping" and "scope" are terms best explained by example: consider some hypothetical rows in the <code class="computeroutput">address_book</code> table: -</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>...</th><th><code class="computeroutput">scope</code></th><th><code class="computeroutput">user_id</code></th><th><code class="computeroutput">group_id</code></th><th>...</th></tr></thead><tbody><tr><td>...</td><td><code class="computeroutput">user</code></td><td><code class="computeroutput">123</code></td><td> </td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">group</code></td><td> </td><td><code class="computeroutput">456</code></td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">public</code></td><td> </td><td> </td><td>...</td></tr></tbody></table></div><p> +</p> + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><thead><tr><th>...</th><th><code class="computeroutput">scope</code></th><th><code class="computeroutput">user_id</code></th><th><code class="computeroutput">group_id</code></th><th>...</th></tr></thead><tbody><tr><td>...</td><td><code class="computeroutput">user</code></td><td><code class="computeroutput">123</code></td><td> </td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">group</code></td><td> </td><td><code class="computeroutput">456</code></td><td>...</td></tr><tr><td>...</td><td><code class="computeroutput">public</code></td><td> </td><td> </td><td>...</td></tr></tbody></table> +</div> + +<p> The first row represents an entry in User 123's personal address book, the second row represents an entry in User Group 456's shared address book, and the third row represents an entry in the site's public address book. In this way, the scoping columns identify the security context in which a given object belongs, where each context is <span class="emphasis"><em>either</em></span> a person <span class="emphasis"><em>or</em></span> a group of people <span class="emphasis"><em>or</em></span> the general public (itself a group of people). -</p><p> +</p> + +<p> Every object lives in a single <span class="emphasis"><em>context</em></span>. A context is just an another object that represents the security domain to which the object belongs. By convention, if an object A does not have any permissions explicitly attached to it, then the system will look at the <code class="computeroutput">context_id</code> column in <code class="computeroutput">acs_objects</code> and check the context object there for permissions. Two things control the scope -of this search:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>the structure of the context hierarchy +of this search:</p> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>the structure of the context hierarchy itself, and </p></li><li class="listitem"><p> the value of the <code class="computeroutput">security_inherit_p</code> flag in each object. -</p></li></ol></div><p>If +</p></li></ol></div> +<p>If <code class="computeroutput">security_inherit_p</code> flag is set to <code class="computeroutput">'t'</code>, then the automatic search through the context happens, otherwise it does not. You might set this field to <code class="computeroutput">'f'</code> if you want to override the default permissions in a subtree of some context. -</p><p>For an example of how to use context hierarchy, consider the forums +</p> + +<p>For an example of how to use context hierarchy, consider the forums application. With only row-level permissions it is not obvious how to reasonably initialize the access control list when creating a message. At best, we have to explicitly grant various read and write @@ -178,12 +270,20 @@ checks permissions on the message's context. To allow the creator of the message to change the message after it has been posted we grant the user write-access on the message, and we are done. -</p><p> +</p> + +<p> This mechanism allows developers and administrators to define a hierarchy that matches the structure they need for access control in their application. The following picture shows a typical context hierarchy for a hypothetical site: -</p><div class="blockquote"><blockquote class="blockquote"><div><img src="images/context-hierarchy.gif"></div></blockquote></div><p> +</p> + +<div class="blockquote"><blockquote class="blockquote"> +<div><img src="images/context-hierarchy.gif"></div> +</blockquote></div> + +<p> The top two contexts in the diagram are called "magic" numbers, because in some sense, they are created by default by OpenACS for a specific purpose. The object <code class="computeroutput">default_context</code> @@ -196,11 +296,21 @@ some object has no permissions attached to it, and its value for <code class="computeroutput">security_inherit_p</code> is <code class="computeroutput">'f'</code>, or <code class="computeroutput">context_id</code> is null, this context is used by default. -</p><p>See the package developer tutorials for examples on how to use +</p> +<p>See the package developer tutorials for examples on how to use permissions code. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-summary"></a>Summary</h3></div></div></div><p> +</p> +</div> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="permissions-summary"></a>Summary</h3></div></div></div> + + + +<p> OpenACS 5.9.0 defines three separate mechanisms for specifying access control -in applications. </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> +in applications. </p> +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> The Groups data model allows you to define hierarchical organizations of users and groups of users. </p></li><li class="listitem"><p> @@ -209,6 +319,13 @@ </p></li><li class="listitem"><p> The Context hierarchy allows you to define organize default permissions in a hierarchical fashion. -</p></li></ol></div><p>A PL/SQL or Tcl API is +</p></li></ol></div> +<p>A PL/SQL or Tcl API is then used to check permissions in application pages. -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr><tr><td width="40%" align="left">Using Templates in OpenACS </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Writing OpenACS Application Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites.html">Next</a></td></tr><tr><td width="40%" align="left">Using Templates in OpenACS </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Writing OpenACS Application Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/postgres.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/postgres.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/postgres.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="aolserver4" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="postgres" id="postgres"></a>Install PostgreSQL</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Skip this section if you will run only Oracle.</p><p>OpenACS 5.9.0 will run with <a class="link" href="individual-programs" title="PostgreSQL 7.4.x (Either this or Oracle is REQUIRED)">PostgreSQL</a> +<a name="postgres" id="postgres"></a>Install PostgreSQL</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:vinod\@kurup.com" target="_top">Vinod Kurup</a> +</span></p><span style="color: red"></authorblurb></span><p>Skip this section if you will run only Oracle.</p><p>OpenACS 5.9.0 will run with <a class="link" href="individual-programs" title="PostgreSQL 7.4.x (Either this or Oracle is REQUIRED)">PostgreSQL</a> 9.0 or newer. 9.5 is currently the recommended version of PostgreSQL.</p><p>It is recommend to use a prepackaged version of PostgreSQL, which are available in source and binary formats from <a class="ulink" href="https://www.postgresql.org/download" target="_top">www.postgresql.org/download/</a>.</p><p>Larger installations might want to tune the PostgreSQL Index: openacs-4/packages/acs-core-docs/www/postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/postgres.html,v diff -u -r1.52 -r1.53 --- openacs-4/packages/acs-core-docs/www/postgres.html 7 Aug 2017 23:47:52 -0000 1.52 +++ openacs-4/packages/acs-core-docs/www/postgres.html 8 Nov 2017 09:42:11 -0000 1.53 @@ -1,16 +1,31 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install PostgreSQL</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="oracle.html" title="Install Oracle 8.1.7"><link rel="next" href="aolserver4.html" title="Install AOLserver 4"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="aolserver4.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="postgres"></a>Install PostgreSQL</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Skip this section if you will run only Oracle.</p><p>OpenACS 5.9.0 will run with <a class="link" href="individual-programs.html#source-postgresql" title="PostgreSQL 7.4.x (Either this or Oracle is REQUIRED)">PostgreSQL</a> 9.0 or newer. 9.5 is currently - the recommended version of PostgreSQL.</p><p>It is recommend to use a prepackaged version of PostgreSQL, +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install PostgreSQL</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="oracle.html" title="Install Oracle 8.1.7"><link rel="next" href="aolserver4.html" title="Install AOLserver 4"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="aolserver4.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="postgres"></a>Install PostgreSQL</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:vinod@kurup.com" target="_top">Vinod Kurup</a></p> + </authorblurb></span> + + <p>Skip this section if you will run only Oracle.</p> + + <p>OpenACS 5.9.0 will run with <a class="link" href="individual-programs.html#source-postgresql" title="PostgreSQL 7.4.x (Either this or Oracle is REQUIRED)">PostgreSQL</a> 9.0 or newer. 9.5 is currently + the recommended version of PostgreSQL.</p> + + <p>It is recommend to use a prepackaged version of PostgreSQL, which are available in source and binary formats from <a class="ulink" href="https://www.postgresql.org/download" target="_top">www.postgresql.org/download/</a>. - </p><p>Larger installations might want to tune the PostgreSQL + </p> + + <p>Larger installations might want to tune the PostgreSQL installation with e.g. the utility <a class="ulink" href="https://github.com/gregs1104/pgtune" target="_top">pgtune</a>, which is also available via <strong class="userinput"><code>apt-get install pgtune</code></strong> or <strong class="userinput"><code>dnf install pgtune</code></strong> on Debian/Ubuntu or RedHat systems. - </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-postgres-moreinfo"></a>More information about PostgreSQL</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="install-postgres-moreinfo"></a>More information about PostgreSQL</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <a class="ulink" href="https://www.postgresql.org/docs/" target="_top">Official PostgreSQL Docs</a> @@ -24,4 +39,6 @@ <a class="ulink" href="https://wiki.postgresql.org/wiki/Performance_Optimization" target="_top">PostgreSQL Performance Tuning</a> - </p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="aolserver4.html">Next</a></td></tr><tr><td width="40%" align="left">Install Oracle 8.1.7 </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install AOLserver 4</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p></li></ul></div> + </div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="oracle.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="aolserver4.html">Next</a></td></tr><tr><td width="40%" align="left">Install Oracle 8.1.7 </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install AOLserver 4</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/profile-code.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/profile-code.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/profile-code.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/profile-code.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="tutorial-distribute" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="profile-code" id="profile-code"></a>Profile your code</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>There are several facilities for profiling your code in OpenACS. +<a name="profile-code" id="profile-code"></a>Profile your code</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><p>There are several facilities for profiling your code in OpenACS. The first thing to do is to install the developer-support package and play around with it. But there is also support in the API for profiling your code: <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161324" target="_top">profiling your code using ds_profile</a> Index: openacs-4/packages/acs-core-docs/www/profile-code.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/profile-code.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/profile-code.html 7 Aug 2017 23:47:52 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/profile-code.html 8 Nov 2017 09:42:11 -0000 1.16 @@ -1,11 +1,16 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Profile your code</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-categories.html" title="Categories"><link rel="next" href="tutorial-distribute.html" title="Prepare the package for distribution."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-categories.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-distribute.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="profile-code"></a>Profile your code</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>There are several facilities for profiling your code in +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Profile your code</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-categories.html" title="Categories"><link rel="next" href="tutorial-distribute.html" title="Prepare the package for distribution."></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-categories.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-distribute.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="profile-code"></a>Profile your code</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + + <p>There are several facilities for profiling your code in OpenACS. The first thing to do is to install the developer-support package and play around with it. But there is also support in the API for profiling your code: <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161324" target="_top">profiling your code using ds_profile</a> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-categories.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-distribute.html">Next</a></td></tr><tr><td width="40%" align="left">Categories </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Prepare the package for distribution.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-categories.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-distribute.html">Next</a></td></tr><tr><td width="40%" align="left">Categories </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Prepare the package for distribution.</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="form-builder" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="programming-with-aolserver" id="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div></div><div class="authorblurb"> -<p>By Michael Yoon, Jon Salz and Lars Pind.</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="programming-with-aolserver" id="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Michael Yoon, Jon Salz and Lars +Pind.</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="programming-aolserver-global" id="programming-aolserver-global"></a>The <code class="computeroutput">global</code> command</h3></div></div></div><p>When using AOLserver, remember that there are effectively <span class="emphasis"><em>two</em></span> types of global @@ -230,8 +228,8 @@ However, when using <code class="computeroutput">ns_set get</code> to perform lookup by name, they perform a linear lookup, whereas arrays use a hash table, so <code class="computeroutput">ns_set</code>s are slower than arrays when the -number of entries is large.</p><div class="cvstag">($‌Id: programming-with-aolserver.xml,v 1.7.2.1 -2017/06/17 10:28:29 gustafn Exp $)</div> +number of entries is large.</p><p><span class="cvstag">($‌Id: programming-with-aolserver.xml,v 1.8 +2017/08/07 23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 7 Aug 2017 23:47:52 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/programming-with-aolserver.html 8 Nov 2017 09:42:11 -0000 1.51 @@ -1,11 +1,21 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Programming with AOLserver</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="object-identity.html" title="Object Identity"><link rel="next" href="form-builder.html" title="Using Form Builder: building html forms dynamically"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="form-builder.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div></div><div class="authorblurb"><p>By Michael Yoon, Jon Salz and Lars Pind.</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-global"></a>The <code class="computeroutput">global</code> command</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Programming with AOLserver</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="object-identity.html" title="Object Identity"><link rel="next" href="form-builder.html" title="Using Form Builder: building html forms dynamically"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="form-builder.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="programming-with-aolserver"></a>Programming with AOLserver</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Michael Yoon, Jon Salz and Lars Pind.</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-global"></a>The <code class="computeroutput">global</code> command</h3></div></div></div> + + +<p> When using AOLserver, remember that there are effectively <span class="emphasis"><em>two</em></span> types of global namespace, not one: -</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Server</em></span>-global: As you'd expect, there is +</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><span class="emphasis"><em>Server</em></span>-global: As you'd expect, there is only one server-global namespace per server, and variables set within it can be accessed by any Tcl code running subsequently, in any of the server's threads. To set/get server-global variables, use AOLserver 3's <a class="ulink" href="http://www.aolserver.com/docs/nsv.adp" target="_top"><code class="computeroutput">nsv</code> API</a> @@ -15,34 +25,60 @@ own global namespace. Any variable set in the top level of a script is, by definition, script-global, meaning that it is accessible only by subsequent code in the same script and only for the duration of the current script -execution.</p></li></ol></div><p> +execution.</p></li></ol></div> + +<p> The Tcl built-in command <a class="ulink" href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/global.htm" target="_top"><code class="computeroutput">global</code></a> accesses script-global, <span class="emphasis"><em>not</em></span> server-global, variables from within a procedure. This distinction is important to understand in order to use <code class="computeroutput">global</code> correctly when programming AOLserver. -</p><p>Also, AOLserver purges all script-global variables in a thread (i.e., Tcl +</p> + +<p>Also, AOLserver purges all script-global variables in a thread (i.e., Tcl interpreter) between HTTP requests. If it didn't, that would affect (and complicate) our use of script-global variables dramatically, which would then be better described as <span class="emphasis"><em>thread</em></span>-global variables. Given AOLserver's behaviour, however, "script-global" is a more -appropriate term.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-sched-procs"></a>Threads and Scheduled Procedures</h3></div></div></div><p> +appropriate term.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-sched-procs"></a>Threads and Scheduled Procedures</h3></div></div></div> + + +<p> <code class="computeroutput">ns_schedule_proc</code> and <code class="computeroutput">ad_schedule_proc</code> each take a <code class="computeroutput">-thread</code> flag to cause a scheduled procedure to run asychronously, in its own thread. It almost always seems like a good idea to specify this switch, but there's a problem. -</p><p>It turns out that whenever a task scheduled with <code class="computeroutput">ns_schedule_proc +</p> + +<p>It turns out that whenever a task scheduled with <code class="computeroutput">ns_schedule_proc -thread</code> or <code class="computeroutput">ad_schedule_proc -thread t</code> is run, AOLserver creates a brand new thread and a brand new interpreter, and reinitializes the procedure table (essentially, loads all procedures that were created during server initialization into the new interpreter). This happens <span class="emphasis"><em>every time</em></span> the task is executed - and it is a very expensive process that -should not be taken lightly!</p><p>The moral: if you have a lightweight scheduled procedure +should not be taken lightly!</p> + +<p>The moral: if you have a lightweight scheduled procedure which runs frequently, don't use the <code class="computeroutput">-thread</code> -switch.</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>Note also that thread is initialized with a copy of what was +switch.</p> + + + +<div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>Note also that thread is initialized with a copy of what was installed during server startup, so if the procedure table have changed since startup (e.g. using the <a class="link" href="apm-design.html" title="Package Manager Design">APM</a> watch facility), that will not be reflected in the scheduled -thread.</em></span></p></blockquote></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-return"></a>Using <code class="computeroutput">return</code></h3></div></div></div><p> +thread.</em></span></p></blockquote></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-return"></a>Using <code class="computeroutput">return</code></h3></div></div></div> + + +<p> The <code class="computeroutput">return</code> command in Tcl returns control to the caller procedure. This definition allows nested procedures to work properly. However, this definition also means that nested procedures cannot use <code class="computeroutput">return</code> to @@ -59,7 +95,14 @@ executed because the thread was not stopped. Note that <code class="computeroutput">return -code return</code> can be used in circumstances where the procedure will only be called from two levels deep. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-more-values"></a>Returning More Than One Value From a Function</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="programming-aolserver-more-values"></a>Returning More Than One Value From a Function</h3></div></div></div> + + +<p> Many functions have a single return value. For instance, <a class="ulink" href="/api-doc/proc-view?proc=util_email_valid_p" target="_top"><code class="computeroutput">util_email_valid_p</code></a> returns a number: 1 or 0. Other functions need to return a composite value. For instance, consider a function that looks up a user's name and email @@ -68,17 +111,30 @@ contains the email address. The problem with this technique is that, because Tcl does not support constants, calling procedures that returns lists in this way necessitates the use of magic numbers, e.g.: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> set user_info [ad_get_user_info $user_id] set first_name [lindex $user_info 0] set email [lindex $user_info 1] -</pre><p>AOLserver/Tcl generally has three mechanisms that we like, for returning +</pre> + + +<p>AOLserver/Tcl generally has three mechanisms that we like, for returning more than one value from a function. When to use which depends on the -circumstances.</p><p>Using Arrays and Pass-By-Value</p><p> +circumstances.</p> + +<p>Using Arrays and Pass-By-Value</p> + +<p> The one we generally prefer is returning an <a class="ulink" href="http://aolserver.com/docs/tcl/tcl8.3/TclCmd/array.htm#M8" target="_top"><code class="computeroutput">array get</code></a>-formatted list. It has all the nice properties of pass-by-value, and it uses Tcl arrays, which have good native support. -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> ad_proc ad_get_user_info { user_id } { db_1row user_info { select first_names, last_name, email from users where user_id = :user_id } return [list \ @@ -91,11 +147,16 @@ array set user_info [ad_get_user_info $user_id] doc_body_append "$user_info(namelink) ($user_info(emaillink))" -</pre><p> +</pre> + +<p> You could also have done this by using an array internally and using <code class="computeroutput">array get</code>: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + ad_proc ad_get_user_info { user_id } { db_1row user_info { select first_names, last_name, email from users where user_id = :user_id } set user_info(name) "$first_names $last_name" @@ -105,21 +166,33 @@ return [array get user_info] } -</pre><p>Using Arrays and Pass-By-Reference</p><p> +</pre> + + +<p>Using Arrays and Pass-By-Reference</p> + +<p> Sometimes pass-by-value incurs too much overhead, and you'd rather pass-by-reference. Specifically, if you're writing a proc that uses arrays internally to build up some value, there are many entries in the array, and you're planning on iterating over the proc many times. In this case, pass-by-value is expensive, and you'd use pass-by-reference. -</p><div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>The transformation of the array into a list and back to an +</p> + +<div class="blockquote"><blockquote class="blockquote"><p><span class="emphasis"><em>The transformation of the array into a list and back to an array takes, in our test environment, approximately 10 microseconds per entry of 100 character's length. Thus you can process about 100 entries per milisecond. The time depends almost completely on the number of entries, and -almost not at all on the size of the entries.</em></span></p></blockquote></div><p> +almost not at all on the size of the entries.</em></span></p></blockquote></div> + +<p> You implement pass-by-reference in Tcl by taking the name of an array as an argument and <code class="computeroutput">upvar</code> it. -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + ad_proc ad_get_user_info { -array:required user_id @@ -136,23 +209,38 @@ doc_body_append "$user_info(namelink) ($user_info(emaillink))" -</pre><p>We prefer pass-by-value over pass-by-reference. Pass-by-reference makes +</pre> + + +<p>We prefer pass-by-value over pass-by-reference. Pass-by-reference makes the code harder to read and debug, because changing a value in one place has side effects in other places. Especially if have a chain of <code class="computeroutput">upvar</code>s through several layers of the call stack, you'll have -a hard time debugging.</p><p>Multisets: Using <code class="computeroutput">ns_set</code>s and Pass-By-Reference</p><p> +a hard time debugging.</p> + +<p>Multisets: Using <code class="computeroutput">ns_set</code>s and Pass-By-Reference</p> + +<p> An array is a type of <span class="emphasis"><em>set</em></span>, which means you can't have multiple entries with the same key. Data structures that can have multiple entries for the same key are known as a <span class="emphasis"><em>multiset</em></span> or <span class="emphasis"><em>bag</em></span>. -</p><p>If your data can have multiple entries with the same key, +</p> + +<p>If your data can have multiple entries with the same key, you should use the AOLserver built-in <a class="ulink" href="http://www.aolserver.com/docs/tcldev/tapi-120.htm#197598" target="_top"><code class="computeroutput"> ns_set</code></a>. You can also do a case-insensitive lookup on an <code class="computeroutput">ns_set</code>, something you can't easily do on an array. This is especially useful for things like HTTP headers, which happen to have these -exact properties.</p><p>You always use pass-by-reference with <code class="computeroutput">ns_set</code>s, since they +exact properties.</p> + +<p>You always use pass-by-reference with <code class="computeroutput">ns_set</code>s, since they don't have any built-in way of generating and reconstructing themselves -from a string representation. Instead, you pass the handle to the set.</p><pre class="programlisting"> +from a string representation. Instead, you pass the handle to the set.</p> + + +<pre class="programlisting"> + ad_proc ad_get_user_info { -set:required user_id @@ -169,14 +257,22 @@ doc_body_append "[ns_set get $user_info namelink] ([ns_set get $user_info emaillink])" -</pre><p> +</pre> + +<p> We don't recommend <code class="computeroutput">ns_set</code> as a general mechanism for passing sets (as opposed to multisets) of data. Not only do they inherently use pass-by-reference, which we dis-like, they're also somewhat clumsy to use, since Tcl doesn't have built-in syntactic support for them. -</p><p>Consider for example a loop over the entries in a <code class="computeroutput">ns_set</code> as -compared to an array:</p><pre class="programlisting"> +</p> +<p>Consider for example a loop over the entries in a <code class="computeroutput">ns_set</code> as +compared to an array:</p> + + + +<pre class="programlisting"> + # ns_set variant set size [ns_set size $myset] for { set i 0 } { $i < $size } { incr i } { @@ -188,10 +284,15 @@ puts "$myarray($name) = $myarray($name)" } -</pre><p> +</pre> + +<p> And this example of constructing a value: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + # ns_set variant set myset [ns_set create] ns_set put $myset foo $foo @@ -204,10 +305,18 @@ baz $baz ] -</pre><p> +</pre> + +<p> <code class="computeroutput">ns_set</code>s are designed to be lightweight, so memory consumption should not be a problem. However, when using <code class="computeroutput">ns_set get</code> to perform lookup by name, they perform a linear lookup, whereas arrays use a hash table, so <code class="computeroutput">ns_set</code>s are slower than arrays when the number of entries is large. -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="form-builder.html">Next</a></td></tr><tr><td width="40%" align="left">Object Identity </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Form Builder: building html forms dynamically</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="object-identity.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="form-builder.html">Next</a></td></tr><tr><td width="40%" align="left">Object Identity </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Using Form Builder: building html forms dynamically</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -12,20 +12,20 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="psgml-for-emacs" id="psgml-for-emacs"></a>Add PSGML commands to emacs init file (OPTIONAL)</h2></div></div></div><p> -<a class="indexterm" name="idp140592107200216" id="idp140592107200216"></a> If you plan to write or edit any +<a class="indexterm" name="idp140623161896472" id="idp140623161896472"></a> If you plan to write or edit any documentation with emacs, install a customized emacs configuration file with DocBook commands in the skeleton directory, so it will be used for all new users. The file also fixes the backspace -> help mis-mapping that often occurs in terminals.</p><pre class="screen"> [root tmp]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs</code></strong> cp: overwrite `/etc/skel/.emacs'? <strong class="userinput"><code>y</code></strong> [root tmp]# -</pre><p>Debian users:</p><pre class="screen"><span class="action"><span class="action">apt-get install psgml</span></span></pre><p>Note: The new nxml mode for emacs, when used in combination with +</pre><p>Debian users:</p><pre class="screen"><span class="action">apt-get install psgml</span></pre><p>Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For -debian, <code class="computeroutput">apt-get install +Debian, <code class="computeroutput">apt-get install nxml</code>.</p> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html,v diff -u -r1.42 -r1.43 --- openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 7 Aug 2017 23:47:52 -0000 1.42 +++ openacs-4/packages/acs-core-docs/www/psgml-for-emacs.html 8 Nov 2017 09:42:11 -0000 1.43 @@ -1,9 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Add PSGML commands to emacs init file (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"><link rel="next" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-for-emacs"></a>Add PSGML commands to emacs init file (OPTIONAL)</h2></div></div></div><p><a class="indexterm" name="idp140592107200216"></a> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Add PSGML commands to emacs init file (OPTIONAL)</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="install-more-software.html" title="Appendix B. Install additional supporting software"><link rel="previous" href="install-cvs.html" title="Initialize CVS (OPTIONAL)"><link rel="next" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><th width="60%" align="center">Appendix B. Install additional supporting software</th><td width="20%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-for-emacs"></a>Add PSGML commands to emacs init file (OPTIONAL)</h2></div></div></div> + + <p><a class="indexterm" name="idp140623161896472"></a> If you plan to write or edit any documentation with emacs, install a customized emacs configuration file with DocBook commands in the skeleton directory, so it will be used for all new users. The file also fixes the backspace -> help mis-mapping that often occurs in - terminals.</p><pre class="screen">[root tmp]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs</code></strong> + terminals.</p> + + <pre class="screen">[root tmp]# <strong class="userinput"><code>cp /tmp/openacs-5.9.0/packages/acs-core-docs/www/files/emacs.txt /etc/skel/.emacs</code></strong> cp: overwrite `/etc/skel/.emacs'? <strong class="userinput"><code>y</code></strong> -[root tmp]# </pre><p>Debian users:</p><pre class="screen"><span class="action"><span class="action">apt-get install psgml</span></span></pre><p>Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For debian, <code class="computeroutput">apt-get install nxml</code>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr><tr><td width="40%" align="left">Initialize CVS (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Daemontools (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +[root tmp]# </pre> + <p>Debian users:</p> + <pre class="screen"><span class="action">apt-get install psgml</span></pre> + <p>Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For Debian, <code class="computeroutput">apt-get install nxml</code>.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-daemontools.html">Next</a></td></tr><tr><td width="40%" align="left">Initialize CVS (OPTIONAL) </td><td width="20%" align="center"><a accesskey="u" href="install-more-software.html">Up</a></td><td width="40%" align="right"> Install Daemontools (OPTIONAL)</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/psgml-mode.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/psgml-mode.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="nxml-mode" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="psgml-mode" id="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div></div><div class="authorblurb"> -<p>By David Lutterkort</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Note: <code class="computeroutput">nxml</code> mode replaces +<a name="psgml-mode" id="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By David Lutterkort</span></p><span style="color: red"></authorblurb></span><p>Note: <code class="computeroutput">nxml</code> mode replaces and/or complements psgml mode. <a class="ulink" href="http://www.xmlhack.com/read.php?item=2061" target="_top">More information</a>.</p><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> @@ -145,8 +142,8 @@ <a name="psgml-mode-reading" id="psgml-mode-reading"></a>Further reading</h3></div></div></div><p>Start with the <a class="xref" href="docbook-primer" title="OpenACS Documentation Guide">the section called “OpenACS Documentation Guide”</a> -</p><div class="cvstag">($‌Id: psgml-mode.xml,v 1.8.14.1 2017/06/15 -13:56:42 gustafn Exp $)</div> +</p><p><span class="cvstag">($‌Id: psgml-mode.xml,v 1.9 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/psgml-mode.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/psgml-mode.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/psgml-mode.html 7 Aug 2017 23:47:52 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/psgml-mode.html 8 Nov 2017 09:42:11 -0000 1.50 @@ -1,42 +1,97 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using PSGML mode in Emacs</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="next" href="nxml-mode.html" title="Using nXML mode in Emacs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="nxml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div></div><div class="authorblurb"><p>By David Lutterkort</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Note: <code class="computeroutput">nxml</code> mode replaces and/or complements psgml mode. <a class="ulink" href="http://www.xmlhack.com/read.php?item=2061" target="_top">More information</a>.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-whatisit"></a>What it is</h3></div></div></div><p>PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using PSGML mode in Emacs</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="docbook-primer.html" title="OpenACS Documentation Guide"><link rel="next" href="nxml-mode.html" title="Using nXML mode in Emacs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="nxml-mode.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="psgml-mode"></a>Using PSGML mode in Emacs</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By David Lutterkort</p> +</authorblurb></span> + + <p>Note: <code class="computeroutput">nxml</code> mode replaces and/or complements psgml mode. <a class="ulink" href="http://www.xmlhack.com/read.php?item=2061" target="_top">More information</a>.</p> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-whatisit"></a>What it is</h3></div></div></div> + + + +<p>PSGML Mode is a mode for editing, umm, SGML and XML documents in emacs. It can parse a DTD and help you insert the right tags in the right place, knows about tags' attributes and can tell you in which contexts a tag can be used. <span class="emphasis"><em>If</em></span> you give it the right DTD, that is. But even without a DTD, it can save you some typing since pressing <code class="computeroutput">C-c/</code> will close an open -tag automatically.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-getit"></a>Where to get it</h3></div></div></div><p>Most newer emacsen come with PSGML mode preinstalled. You can find out +tag automatically.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-getit"></a>Where to get it</h3></div></div></div> + + + +<p>Most newer emacsen come with PSGML mode preinstalled. You can find out whether your emacs has it with the <code class="computeroutput">locate-library</code> command. In Emacs, type <code class="computeroutput">M-x locate-library</code> and enter <code class="computeroutput">psgml</code>. Emacs will tell -you if it found it or not.</p><p>If you don't have PSGML preinstalled in your Emacs, there are two -things you can do:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>On Linux: Get the <a class="ulink" href="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm" target="_top"> +you if it found it or not.</p> + +<p>If you don't have PSGML preinstalled in your Emacs, there are two +things you can do:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>On Linux: Get the <a class="ulink" href="ftp://sourceware.cygnus.com:/pub/docbook-tools/docware/RPMS/noarch/psgml-1.2.1-1.noarch.rpm" target="_top"> psgml rpm</a> from <a class="ulink" href="http://sources.redhat.com/docbook-tools/" target="_top">RedHat's docbook-tools</a> and install it as usual.</p></li><li class="listitem"><p>On other systems: Get the tarball from the <a class="ulink" href="https://www.emacswiki.org/emacs/PsgmlMode" target="_top">PSGML Website.</a> -Unpack it and follow the install instructions.</p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-catalogs"></a>Using <code class="computeroutput">CATALOG</code> files</h3></div></div></div><p>The easiest way to teach PSGML mode about a DTD is by adding it to your +Unpack it and follow the install instructions.</p></li></ol></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-catalogs"></a>Using <code class="computeroutput">CATALOG</code> files</h3></div></div></div> + + + +<p>The easiest way to teach PSGML mode about a DTD is by adding it to your own <code class="computeroutput">CATALOG</code>. Here is an example of how you can set that up for the -Docbook XML DTD.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Get the <a class="ulink" href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a> -zip archive from <a class="ulink" href="http://docbook.org/" target="_top">docbook.org</a></p></li><li class="listitem"><p>Go somewhere in your working directory and do </p><pre class="programlisting"> +Docbook XML DTD.</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Get the <a class="ulink" href="http://docbook.org/xml/index.html" target="_top">Docbook XML DTD</a> +zip archive from <a class="ulink" href="http://docbook.org/" target="_top">docbook.org</a></p></li><li class="listitem"><p>Go somewhere in your working directory and do </p> + +<pre class="programlisting"> mkdir -p dtd/docbook-xml cd dtd/docbook-xml unzip -a <docbook XML DTD zip archive> -</pre></li><li class="listitem"><p>Create a file with the name <code class="computeroutput">CATALOG</code> in the <code class="computeroutput">dtd</code> -directory and put the line </p><pre class="programlisting"> +</pre> +</li><li class="listitem"><p>Create a file with the name <code class="computeroutput">CATALOG</code> in the <code class="computeroutput">dtd</code> +directory and put the line </p> + +<pre class="programlisting"> CATALOG "docbook-xml/docbook.cat" -</pre><p> +</pre> + +<p> in it. By maintaining your own <code class="computeroutput">CATALOG</code>, it is easy to add more DTD's without changing your emacs settings. (<span class="emphasis"><em>How about that HTML 4.01 DTD you always wanted to get from <a class="ulink" href="http://www.w3.org/TR/html4/" target="_top">W3C</a> ? The -DTD is in the zip archives and tarballs available on the site.</em></span>)</p></li></ol></div><p>That's it. Now you are ready to tell emacs all about PSGML mode and -that funky <code class="computeroutput">CATALOG</code></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div></div><p>If you installed PSGML mode in a non-standard location, e.g., somewhere in +DTD is in the zip archives and tarballs available on the site.</em></span>)</p></li></ol></div> + +<p>That's it. Now you are ready to tell emacs all about PSGML mode and +that funky <code class="computeroutput">CATALOG</code></p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-tell-emacs"></a>What to tell emacs</h3></div></div></div> + + + +<p>If you installed PSGML mode in a non-standard location, e.g., somewhere in your home directory, you need to add this to the <code class="computeroutput">load-path</code> by adding -this line to your <code class="computeroutput">.emacs</code> file:</p><pre class="programlisting"> +this line to your <code class="computeroutput">.emacs</code> file:</p> + +<pre class="programlisting"> (add-to-list 'load-path "/some/dir/that/contains/psgml.elc") -</pre><p>To let PSGML mode find your <code class="computeroutput">CATALOG</code> and to enable PSGML mode for -all your editing, add these lines to your <code class="computeroutput">.emacs</code>:</p><pre class="programlisting"> +</pre> + +<p>To let PSGML mode find your <code class="computeroutput">CATALOG</code> and to enable PSGML mode for +all your editing, add these lines to your <code class="computeroutput">.emacs</code>:</p> + +<pre class="programlisting"> (require 'psgml) (add-to-list 'auto-mode-alist '("\\.html" . sgml-mode)) @@ -46,8 +101,12 @@ (add-to-list 'sgml-catalog-files "/path/to/your/dtd/CATALOG") -</pre><p>If you want font-locking and indentation, you can also add these lines -into the <code class="computeroutput">.emacs</code> file:</p><pre class="programlisting"> +</pre> + +<p>If you want font-locking and indentation, you can also add these lines +into the <code class="computeroutput">.emacs</code> file:</p> + +<pre class="programlisting"> (setq sgml-markup-faces '((start-tag . font-lock-function-name-face) (end-tag . font-lock-function-name-face) (comment . font-lock-comment-face) @@ -63,24 +122,66 @@ (define-key sgml-mode-map "\C-c\C-x\C-i" 'sgml-general-dtd-info) (define-key sgml-mode-map "\C-c\C-x\C-t" 'sgml-describe-entity) -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-doctype"></a>What is a <code class="computeroutput">DOCTYPE</code> ?</h3></div></div></div><p>All SGML and XML documents that should conform to a DTD have to declare a +</pre> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-doctype"></a>What is a <code class="computeroutput">DOCTYPE</code> ?</h3></div></div></div> + + + +<p>All SGML and XML documents that should conform to a DTD have to declare a doctype. For the docbook XML, all your <code class="computeroutput">.xml</code> files whould start with -the line</p><pre class="programlisting"> +the line</p> + +<pre class="programlisting"> <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "docbookx.dtd"> -</pre><p>If your document is only part of a larger XML document, you can tell PSGML +</pre> + +<p>If your document is only part of a larger XML document, you can tell PSGML mode about it by <span class="emphasis"><em>appending</em></span> the following lines to your file. In this -case, do <span class="emphasis"><em>not</em></span> include a DOCTYPE declaration in your file.</p><pre class="programlisting"> +case, do <span class="emphasis"><em>not</em></span> include a DOCTYPE declaration in your file.</p> + +<pre class="programlisting"> <!-- Local Variables: sgml-parent-document: ("top.xml" "book" "sect1") End: --> -</pre><p>Which says that the parent of this document can be found in the file +</pre> + +<p>Which says that the parent of this document can be found in the file <code class="computeroutput">top.xml</code>, that the element in the parent that will enclose the current document is a <code class="computeroutput">book</code> and that the current file's topmost -element is a <code class="computeroutput">sect1</code>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-usage"></a>How to use it</h3></div></div></div><p>Of course, you should read the emacs texinfo pages that come with PSGML -mode from start to finish. Barring that, here are some handy commands:</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="0"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Command</th></tr></thead><tbody><tr><td><code class="computeroutput">C-c C-e</code></td><td>Insert an element. Uses completion and only lets you insert elements that +element is a <code class="computeroutput">sect1</code>.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-usage"></a>How to use it</h3></div></div></div> + + + +<p>Of course, you should read the emacs texinfo pages that come with PSGML +mode from start to finish. Barring that, here are some handy commands:</p> + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="0"><colgroup><col><col></colgroup><thead><tr><th>Key</th><th>Command</th></tr></thead><tbody><tr><td><code class="computeroutput">C-c C-e</code></td><td>Insert an element. Uses completion and only lets you insert elements that are valid</td></tr><tr><td><code class="computeroutput">C-c C-a</code></td><td>Edit attributes of enclosing element.</td></tr><tr><td><code class="computeroutput">C-c C-x C-i</code></td><td>Show information about the document's DTD.</td></tr><tr><td><code class="computeroutput">C-c C-x C-e</code></td><td>Describe element. Shows for one element which elements can be parents, -what its contents can be and lists its attributes.</td></tr></tbody></table></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-reading"></a>Further reading</h3></div></div></div><p>Start with the <a class="xref" href="docbook-primer.html" title="OpenACS Documentation Guide">the section called “OpenACS Documentation Guide”</a></p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="nxml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation Guide </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Using nXML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +what its contents can be and lists its attributes.</td></tr></tbody></table></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="psgml-mode-reading"></a>Further reading</h3></div></div></div> + + + +<p>Start with the <a class="xref" href="docbook-primer.html" title="OpenACS Documentation Guide">the section called “OpenACS Documentation Guide”</a></p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="docbook-primer.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="nxml-mode.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Documentation Guide </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Using nXML mode in Emacs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/release-notes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/release-notes.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/release-notes.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -819,20 +819,20 @@ 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/* *~")</p></li> -</ul></div><div class="cvstag">($‌Id: release-notes.xml,v 1.30.2.10 2017/08/05 -13:14:31 gustafn Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: release-notes.xml,v 1.31 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592099710520" id="idp140592099710520"></a>Release 4.6.3</h3></div></div></div><p><a class="ulink" href="release-notes-4-6-3" target="_top">Release Notes for 4.6.3</a></p> +<a name="idp140623178188216" id="idp140623178188216"></a>Release 4.6.3</h3></div></div></div><p><a class="ulink" href="release-notes-4-6-3" target="_top">Release Notes for 4.6.3</a></p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592099712024" id="idp140592099712024"></a>Release 4.6.2</h3></div></div></div><p><a class="ulink" href="release-notes-4-6-2" target="_top">Release Notes for 4.6.2</a></p> +<a name="idp140623178401176" id="idp140623178401176"></a>Release 4.6.2</h3></div></div></div><p><a class="ulink" href="release-notes-4-6-2" target="_top">Release Notes for 4.6.2</a></p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592099713528" id="idp140592099713528"></a>Release 4.6</h3></div></div></div><p><a class="ulink" href="release-notes-4-6" target="_top">Release Notes for 4.6</a></p> +<a name="idp140623178402712" id="idp140623178402712"></a>Release 4.6</h3></div></div></div><p><a class="ulink" href="release-notes-4-6" target="_top">Release Notes for 4.6</a></p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592099715032" id="idp140592099715032"></a>Release 4.5</h3></div></div></div><p><a class="ulink" href="release-notes-4-5" target="_top">Release Notes for 4.5</a></p> +<a name="idp140623178404344" id="idp140623178404344"></a>Release 4.5</h3></div></div></div><p><a class="ulink" href="release-notes-4-5" target="_top">Release Notes for 4.5</a></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/release-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/release-notes.html,v diff -u -r1.56 -r1.57 --- openacs-4/packages/acs-core-docs/www/release-notes.html 7 Aug 2017 23:47:52 -0000 1.56 +++ openacs-4/packages/acs-core-docs/www/release-notes.html 8 Nov 2017 09:42:11 -0000 1.57 @@ -1,5 +1,14 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Release Notes</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="previous" href="openacs-overview.html" title="Overview"><link rel="next" href="acs-admin.html" title="Part II. Administrator's Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="release-notes"></a>OpenACS Release Notes</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-9-1"></a>Release 5.9.2</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Release Notes</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="general-documents.html" title="Chapter 1. High level information: What is OpenACS?"><link rel="previous" href="openacs-overview.html" title="Overview"><link rel="next" href="acs-admin.html" title="Part II. Administrator's Guide"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 1. High level information: What is OpenACS?</th><td width="20%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="release-notes"></a>OpenACS Release Notes</h2></div></div></div> + + + + + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-9-1"></a>Release 5.9.2</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> The release of OpenACS 5.9.1 contains the 88 packages of the oacs-5-9 branch. These packages include the OpenACS core packages, the major application packages (e.g. most the ones used on OpenACS.org), and @@ -157,7 +166,8 @@ CR hygienics (reduce cr bloat) </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p> Provided means to avoid insert/update/delete operations in the - search queue:</p><p>OpenACS adds for every new revision often multiple + search queue:</p> + <p>OpenACS adds for every new revision often multiple entries to the search_queue, without providing any means to prevent this. This requires for busy sites very short intervals between queue sweeps (otherwise too many entries pile up). Another @@ -167,10 +177,12 @@ content that should not be provided via search. The changed behavior should honors a publish-date set to the future, since it will not add any content with future publish dates to the - search-queue.</p></li><li class="listitem"><p> + search-queue.</p> + </li><li class="listitem"><p> Reduced number of insert cr_child_rels operations, just when needed: - </p><p>cr_child_rels provide only little benefit (allow to use + </p> + <p>cr_child_rels provide only little benefit (allow to use roles in a child-rel), but the common operation is a well available in cr_items via the parent_id. cr_child_rels do not help for recursive queries either. One option would be to add an additional @@ -408,7 +420,8 @@ </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Get rid of "acs_object_context_index " (and therefore on "acs_object_party_privilege_map " as well) on PostgreSQL. - </p><p> Reasons: + </p> + <p> Reasons: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>huge table,</p></li><li class="listitem"><p>expensive maintenance, used only in a few places,</p></li></ul></div><p> </p></li></ul></div><p> </p></li><li class="listitem"><p> @@ -698,7 +711,10 @@ </p></li></ul></div><p> </p></li></ul></div><p> </p></li></ul></div><p> - </p></li></ul></div><p> Altogether, OpenACS 5.9.1 differs from OpenACS 5.9.1 by the + </p></li></ul></div> + + + <p> Altogether, OpenACS 5.9.1 differs from OpenACS 5.9.1 by the following statistics </p><pre class="programlisting"> 3548 files changed, 113292 insertions(+), 90507 deletions(-) @@ -708,10 +724,17 @@ (Frank Bergmann, Günter Ernst, Brian Fenton, Felix Mödritscher, Marcus Moser, Franz Penz, Stefan Sobernig, Michael Steigman). All packages of the release were tested with PostgreSQL 9.6.* and Tcl 8.5.*. - </p><p> + </p> + <p> For more details, consult the <a class="ulink" href="" target="_top">raw ChangeLog</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-9-0"></a>Release 5.9.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> +</div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-9-0"></a>Release 5.9.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> The release of OpenACS 5.9.0 contains the 78 packages of the oacs-5-9 branch. These packages include the OpenACS core packages, the major application packages (e.g. most the ones used on OpenACS.org), and @@ -856,7 +879,9 @@ notifications, xowiki. </p></li></ul></div><p> </p></li></ul></div><p> - </p></li></ul></div><p> Altogether, OpenACS 5.9.0 differs from OpenACS 5.8.1 by the + </p> </li></ul></div> + + <p> Altogether, OpenACS 5.9.0 differs from OpenACS 5.8.1 by the following statistics </p><pre class="programlisting"> 3658 files changed, 120800 insertions(+), 97617 deletions(-) @@ -867,10 +892,18 @@ These are significantly more changes as the differences in the last releases. All packages of the release were tested with PostgreSQL 9.4.* and Tcl 8.5.*. - </p><p> + </p> + <p> For more details, consult the <a class="ulink" href="" target="_top">raw ChangeLog</a>. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-8-1"></a>Release 5.8.1</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + </div> + + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-8-1"></a>Release 5.8.1</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> The release contains the 78 packages of the oacs-5-8 branch. These packages contain the OpenACS core packages, major application packages (e.g. most the ones used on OpenACS.org), and @@ -962,23 +995,45 @@ </p></li></ul></div><p> </p></li></ul></div><p> </p></li></ul></div><p> - </p></li></ul></div><p> Altogether, OpenACS 5.8.1 differs from OpenACS 5.8.0 in + </p> </li></ul></div> + <p> Altogether, OpenACS 5.8.1 differs from OpenACS 5.8.0 in about 100,000 modifications (6145 commits) contributed by 5 committers. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-8-0"></a>Release 5.8.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-8-0"></a>Release 5.8.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Compatibility with PostgreSQL 9.2: The new version installs without any need for special parameter settings in new PostgreSQL versions. This makes it easier to use e.g. shared or packaged PostgreSQL installations. - </p></li><li class="listitem"><p>Compatibility with NaviServer 4.99.5 or newer</p></li><li class="listitem"><p>Performance and scalability improvements</p></li><li class="listitem"><p>Various bug fixes </p></li></ul></div><p> Altogether, OpenACS 5.8.0 differs from OpenACS 5.7.0 in + </p></li><li class="listitem"><p>Compatibility with NaviServer 4.99.5 or newer</p></li><li class="listitem"><p>Performance and scalability improvements</p></li><li class="listitem"><p>Various bug fixes </p></li></ul></div> + <p> Altogether, OpenACS 5.8.0 differs from OpenACS 5.7.0 in more than 18.000 modifications (781 commits) contributed by 7 committers. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-7-0"></a>Release 5.7.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-7-0"></a>Release 5.7.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Made changes that extend acs-kernel's create_type and create_attribute procs, so they're optionally able to create sql tables and columns. Optional metadata params allow for the automatic generation of foreign key references, check exprs, etc. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-6-0"></a>Release 5.6.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + </li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-6-0"></a>Release 5.6.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Added new package dependency type, "embeds". This is a variant of the "extends" package dependency type added in OpenACS 5.5.0. It allows one to write embeddable packages, with scripts made visible in client packages @@ -990,112 +1045,313 @@ that might be associated with a community. Using "embeds", a rewritten package would run in the client package's context, maintaining theming and automatically associating attachments with the client package. - </p><p> + </p> + <p> Added global package parameters - parameters can now have scope "local" or "global", with "local" being the default.. - </p><p> + </p> + <p> Fixes for ns_proxy handling - </p><p> + </p> + <p> Significant speedup for large sites - </p><p> + </p> + <p> Optional support for selenium remote control (acs-automated-tests) - </p><p> + </p> + <p> New administration UI to manage mime types and extension map - </p><p> + </p> + <p> Added acs-mail-lite package params for rollout support - </p><p> + </p> + <p> Support for 3-chars language codes in acs-lang - </p><p> + </p> + <p> Added OOXML mime types in acs-content-repository - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-5-0"></a>Release 5.5.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>PostgreSQL 8.3 is now fully supported, including the use of the built-in + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-5-0"></a>Release 5.5.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>PostgreSQL 8.3 is now fully supported, including the use of the built-in standard version of tsearch2. - </p><p>TinyMCE has been upgraded to 3.2.4.1 with language pack support. - </p><p>acs-mail-lite now correctly implements rollout support. - </p><p> + </p> + <p>TinyMCE has been upgraded to 3.2.4.1 with language pack support. + </p> + <p>acs-mail-lite now correctly implements rollout support. + </p> + <p> Added new package dependency type, "extends". Implements a weak form of package inheritance (parameters and, optionally, templates). Multiple inheritance is supported. For instance, the non-core "layout-managed-subsite" extends the "acs-subsite" and "layout-manager" packages, resulting in a package that combines the semantics of both. - </p><p> + </p> + <p> Added new package attribute "implements-subsite-p" (default "f"). If true, this package may be mounted as a subsite and is expected to implement subsite semantics. Typically used by packages which extend acs-subsite. - </p><p> + </p> + <p> Added new package attribute "inherit-templates-p" (default "t"). If true, the package inherits templates defined in the packages it extends. This means that the package only needs to specify templates where the UI of an extended package is modified or extended. This greatly reduces the need to fork base packages when one needs to customize it. Rather than modify the package directly, use "extends" rather than "requires" then rewrite those templates you need to customize. - </p><p> + </p> + <p> Added a simple mechanism for defining subsite themes, removing the hard-wired choices implemented in earlier versions of OpenACS. The default theme has been moved into a new package, "openacs-default-theme". Simplifies the customization of the look and feel of OpenACS sites and subsites. - </p><p> + </p> + <p> The install xml facility has been enhanced to allow the calling of arbitrary Tcl procedures and includes various other enhancements written by Xarg. Packages can extend the facility, too. As an example of what can be done, the configuration of .LRN communities could be moved from a set of interacting parameters to a cleaner XML description of how to build classes and clubs, etc. - </p><p> + </p> + <p> Notifications now calls lang::util::localize on the message subject and body before sending the message out, using the recipient locale if set, the site-wide one if not. This will cause message keys (entered as <span style="color: red"><span>#</span></span>....# strings) to be replaced with the language text for the chosen locale. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-4-2"></a>Release 5.4.2</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>This is a minor bugfix release. - </p><p>Site node caching was removed as doesn't work correctly</p><p>Critical issues with search on oracle were fixed</p><p>More html strict work etc</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-4-1"></a>Release 5.4.1</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>This is a minor bugfix release. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-4-0"></a>Release 5.4.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>New Templating API added to add scripts, css, etc to the HTML HEAD and BODY + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-4-2"></a>Release 5.4.2</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>This is a minor bugfix release. + </p> + <p>Site node caching was removed as doesn't work correctly</p> + <p>Critical issues with search on oracle were fixed</p> + <p>More html strict work etc</p> + </li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-4-1"></a>Release 5.4.1</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>This is a minor bugfix release. + </p> + </li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-4-0"></a>Release 5.4.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>New Templating API added to add scripts, css, etc to the HTML HEAD and BODY sections of the generated HTML document. Please see /packages/acs-templating/tcl/head-procs.tcl or visit the template::head procs in the API browser for details. - </p><p>Templates have been modified to comply with HTML strict</p><p>The Search package's results page has been improved</p><p>TinyMCE WYSIWYG support has been added, RTE and HTMLArea support dropped</p><p>acs-mail-lite's send has been cleaned up to properly encode content, to handle + </p> + <p>Templates have been modified to comply with HTML strict</p> + <p>The Search package's results page has been improved</p> + <p>TinyMCE WYSIWYG support has been added, RTE and HTMLArea support dropped</p> + <p>acs-mail-lite's send has been cleaned up to properly encode content, to handle file attachments, etc. "complex-send" will disappear from acs-core in a future - release.</p></li></ul></div></div><p>The ChangeLogs include an annotated list of changes (<a class="xref" href="">???</a>) since the last release and in the - entire 5.9 release sequence <a class="xref" href="">???</a>.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-3-1"></a>Release 5.3.1</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes.</p><p>New TIPs implemented.</p><p>All Core Automated Tests for Postgres pass.</p><p>New Site and Blank master templates and CSS compatible with the .LRN Zen - work. Compatibility master templates are provided for existing sites.</p></li></ul></div></div><p>The ChangeLogs include an annotated list of changes (<a class="xref" href="">???</a>) since the last release and in the - entire 5.9 release sequence <a class="xref" href="">???</a>.</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-3-0"></a>Release 5.3.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes.</p><p>New TIPs implemented.</p><p>All Core Automated Tests for Postgres pass.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-2-0"></a>Release 5.2.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes.</p><p>New TIPs implemented.</p><p>This release does <span class="strong"><strong>not</strong></span> include new translations.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-4"></a>Release 5.1.4</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes.</p><p>The missing CR Tcl API has been filled in, thanks to Rocael and - his team and Dave Bauer.</p><p>This release does <span class="strong"><strong>not</strong></span> include new translations.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-3"></a>Release 5.1.3</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes, primarily for .LRN compatibility in support of upcoming .LRN 2.1.0 releases. This release does <span class="strong"><strong>not</strong></span> include new translations since 5.1.2. - </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-2"></a>Release 5.1.2</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Translations syncronized with the translation server. + release.</p> + </li></ul></div> + </div> + + + <p>The ChangeLogs include an annotated list of changes (<a class="xref" href="">???</a>) since the last release and in the + entire 5.9 release sequence <a class="xref" href="">???</a>.</p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-3-1"></a>Release 5.3.1</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes.</p> + <p>New TIPs implemented.</p> + <p>All Core Automated Tests for Postgres pass.</p> + <p>New Site and Blank master templates and CSS compatible with the .LRN Zen + work. Compatibility master templates are provided for existing sites.</p> + </li></ul></div> + </div> + + + <p>The ChangeLogs include an annotated list of changes (<a class="xref" href="">???</a>) since the last release and in the + entire 5.9 release sequence <a class="xref" href="">???</a>.</p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-3-0"></a>Release 5.3.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes.</p> + <p>New TIPs implemented.</p> + <p>All Core Automated Tests for Postgres pass.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-2-0"></a>Release 5.2.0</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes.</p> + <p>New TIPs implemented.</p> + <p>This release does <span class="strong"><strong>not</strong></span> include new translations.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-4"></a>Release 5.1.4</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes.</p> + <p>The missing CR Tcl API has been filled in, thanks to Rocael and + his team and Dave Bauer.</p> + <p>This release does <span class="strong"><strong>not</strong></span> include new translations.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-3"></a>Release 5.1.3</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes, primarily for .LRN compatibility in support of upcoming .LRN 2.1.0 releases. This release does <span class="strong"><strong>not</strong></span> include new translations since 5.1.2. + </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-2"></a>Release 5.1.2</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Translations syncronized with the translation server. Basque and Catalan added. - </p></li><li class="listitem"><p>For a complete change list, see the Change list since - 5.1.0 in <a class="xref" href="">???</a>.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-1"></a>Release 5.1.1</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>This is the first release using the newest adjustment to the versioning convention. The OpenACS 5.1.1 tag will apply to OpenACS core as well as to the most recent released version of every package, including .LRN.</p></li><li class="listitem"><p>Translations syncronized with the translation server. - </p></li><li class="listitem"><p><a class="ulink" href="http://openacs.org/bugtracker/openacs/com/acs-lang/bug?bug%5fnumber=1519" target="_top">Bug + </p> + </li><li class="listitem"> + <p>For a complete change list, see the Change list since + 5.1.0 in <a class="xref" href="">???</a>.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-1"></a>Release 5.1.1</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>This is the first release using the newest adjustment to the versioning convention. The OpenACS 5.1.1 tag will apply to OpenACS core as well as to the most recent released version of every package, including .LRN.</p> + </li><li class="listitem"> + <p>Translations syncronized with the translation server. + </p> + </li><li class="listitem"> + <p><a class="ulink" href="http://openacs.org/bugtracker/openacs/com/acs-lang/bug?bug%5fnumber=1519" target="_top">Bug 1519</a> fixed. This involved renaming all catalog files for ch_ZH, TH_TH, AR_EG, AR_LB, ms_my, RO_RO, FA_IR, and HR_HR. If you work with any of those locales, you should do a full catalog export and then import (via <a class="ulink" href="/acs-lang/admin" target="_top">/acs-lang/admin</a>) after upgrading acs-lang. (And, of course, make a backup of both - the files and database before upgrading.)</p></li><li class="listitem"><p>Other bug fixes since 5.1.0: <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug_number=1785" target="_top">1785</a>, + the files and database before upgrading.)</p> + </li><li class="listitem"> + <p>Other bug fixes since 5.1.0: <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug_number=1785" target="_top">1785</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug_number=1793" target="_top">1793</a>, - and over a dozen additional bug fixes.</p></li><li class="listitem"><p>For a complete change list, see the Change list since - 5.0.0 in <a class="xref" href="">???</a>.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-0"></a>Release 5.1.0</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Lots of little tweaks and fixes</p></li><li class="listitem"><p>Complete Change list since 5.0.0 in Changelog</p></li><li class="listitem"><p><a class="ulink" href="http://openacs.org/bugtracker/openacs/core?filter%2efix%5ffor%5fversion=125273&filter%2estatus=closed" target="_top">Many Bug fixes</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-4"></a>Release 5.0.4</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>New translations, including for .LRN 2.0.2.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-3"></a>Release 5.0.3</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes: <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1560" target="_top">1560</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1556" target="_top">#1556. Site becomes unresponsive, requires restart</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-2"></a>Release 5.0.2</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Bug fixes: <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1495" target="_top">#1495. Croatian enabled by default</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1496" target="_top">#1496. APM automated install fails if files have spaces in their names</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1494" target="_top">#1494. automated upgrade crashes (halting the upgrade process)</a></p></li><li class="listitem"><p>Complete Change list since 5.0.0 in Changelog</p></li><li class="listitem"><p>File tagging scheme in CVS changed to follow <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161375" target="_top">TIP #46: (Approved) Rules for Version Numbering and CVS tagging of Packages</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-1"></a>Release 5.0.1</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>All work on the translation server from 7 Nov 2003 to 7 Feb 2004 is now included in catalogs.</p></li><li class="listitem"><p>One new function in acs-tcl, util::age_pretty</p></li><li class="listitem"><p>Complete Change list since 5.0.0 in Changelog</p></li><li class="listitem"><p>Many documentation updates and doc bug fixes </p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-0"></a>Release 5.0.0</h3></div></div></div><p> + and over a dozen additional bug fixes.</p> + </li><li class="listitem"> + <p>For a complete change list, see the Change list since + 5.0.0 in <a class="xref" href="">???</a>.</p> + </li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-1-0"></a>Release 5.1.0</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Lots of little tweaks and fixes</p> + </li><li class="listitem"> + <p>Complete Change list since 5.0.0 in Changelog</p> + </li><li class="listitem"><p><a class="ulink" href="http://openacs.org/bugtracker/openacs/core?filter%2efix%5ffor%5fversion=125273&filter%2estatus=closed" target="_top">Many Bug fixes</a></p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-4"></a>Release 5.0.4</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>New translations, including for .LRN 2.0.2.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-3"></a>Release 5.0.3</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes: <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1560" target="_top">1560</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1556" target="_top">#1556. Site becomes unresponsive, requires restart</a></p> + </li></ul></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-2"></a>Release 5.0.2</h3></div></div></div> + + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Bug fixes: <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1495" target="_top">#1495. Croatian enabled by default</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1496" target="_top">#1496. APM automated install fails if files have spaces in their names</a>, <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug%5fnumber=1494" target="_top">#1494. automated upgrade crashes (halting the upgrade process)</a></p> + </li><li class="listitem"> + <p>Complete Change list since 5.0.0 in Changelog</p> + </li><li class="listitem"> + <p>File tagging scheme in CVS changed to follow <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161375" target="_top">TIP #46: (Approved) Rules for Version Numbering and CVS tagging of Packages</a></p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-1"></a>Release 5.0.1</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>All work on the translation server from 7 Nov 2003 to 7 Feb 2004 is now included in catalogs.</p> + </li><li class="listitem"> + <p>One new function in acs-tcl, util::age_pretty</p> + </li><li class="listitem"> + <p>Complete Change list since 5.0.0 in Changelog</p> + </li><li class="listitem"> + <p>Many documentation updates and doc bug fixes </p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="release-notes-5-0-0"></a>Release 5.0.0</h3></div></div></div> + + + <p> This is OpenACS 5.0.0. This version contains no known security, data loss, or crashing bugs, nor any bugs judged release blockers. This version has received manual testing. It has passed current automated testing, which is not comprehensive. This release contains work done on the translation server http://translate.openacs.org through 7 Nov 2003. - </p><p> + </p> + + <p> Please report bugs using our <a class="ulink" href="http://openacs.org/bugtracker/openacs/" target="_top"> Bug Tracker</a> at the <a class="ulink" href="http://openacs.org/" target="_top">OpenACS website</a>. - </p><p> + </p> + + <p> You may want to begin by reading our installation documentation for <a class="xref" href="unix-installation.html#unix-install" title="a Unix-like system">the section called “a Unix-like system”</a>. Note that the Windows documentation is not current for OpenACS 5.9.0, but an alternative is to use John Sequeira's <a class="ulink" href="http://www.jsequeira.com/oasis/about.html" target="_top">Oasis VM project</a>. - </p><p> + </p> + + <p> After installation, the full documentation set can be found by visiting <code class="filename">http://yourserver/doc</code>. - </p><p> + </p> + + <p> New features in this release: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> Internationalization support. A message catalog to store translated text, localization of dates, number formatting, timezone conversion, etc. Allows you to serve your users in their language. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> External authenticaiton. Integrate with outside user databases through e.g. LDAP, RADIUS, Kerberos, MS Active Directory. @@ -1106,7 +1362,9 @@ user's identity being completely lost. You can set login to expire after a certain period (e.g. 8 hours, then password must be refreshed), or you can have all issues login cookies expired at once, e.g. if you have left a permanent login cookie on a public machine somewhere. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> User interface enhancements. All pages, including site-wide and subsite admin pages, will be @@ -1136,37 +1394,95 @@ actions on multiple rows with checkboxes, etc. Most of all, it's fast to use, and results in consistently-looking, consistently-behaving, templated tables. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Automated testing. The automated testing framework has been improved significantly, and there are automated tests for a number of packages. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Security enhancements. HTML quoting now happens in the templating system, greatly minimizing the chance that users can sneak malicious HTML into the pages of other users. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Oracle 9i support. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Who's online feature. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> Spell checking. - </p></li></ul></div><p> + </p> + </li></ul></div> + + + <p> Potential incompatibilities: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> With the release of OpenACS 5, PostgreSQL 7.2 is no longer supported. Upgrades are supported from OpenACS 4.6.3 under Oracle or PostgreSQL 7.3. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The undocumented special handling of ~ and +variable+ in formtemplates, found in <code class="filename">packages/acs-templating/resources/*</code>, has been removed in favor of using <noparse> and \@variable\@ (the standard templating mechanisms). Locally provided formtemplate styles still using these mechanisms will break. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> 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/* *~") - </p></li></ul></div><div class="cvstag">($Id$)</div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592099710520"></a>Release 4.6.3</h3></div></div></div><p><a class="ulink" href="release-notes-4-6-3.html" target="_top">Release Notes for 4.6.3</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592099712024"></a>Release 4.6.2</h3></div></div></div><p><a class="ulink" href="release-notes-4-6-2.html" target="_top">Release Notes for 4.6.2</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592099713528"></a>Release 4.6</h3></div></div></div><p><a class="ulink" href="release-notes-4-6.html" target="_top">Release Notes for 4.6</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592099715032"></a>Release 4.5</h3></div></div></div><p><a class="ulink" href="release-notes-4-5.html" target="_top">Release Notes for 4.5</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> Part II. Administrator's Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li></ul></div> + + + + <p><span class="cvstag">($Id$)</span></p> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178188216"></a>Release 4.6.3</h3></div></div></div> + + <p><a class="ulink" href="release-notes-4-6-3.html" target="_top">Release Notes for 4.6.3</a></p> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178401176"></a>Release 4.6.2</h3></div></div></div> + + <p><a class="ulink" href="release-notes-4-6-2.html" target="_top">Release Notes for 4.6.2</a></p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178402712"></a>Release 4.6</h3></div></div></div> + + <p><a class="ulink" href="release-notes-4-6.html" target="_top">Release Notes for 4.6</a></p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178404344"></a>Release 4.5</h3></div></div></div> + + <p><a class="ulink" href="release-notes-4-5.html" target="_top">Release Notes for 4.5</a></p> + </div> + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="acs-admin.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="general-documents.html">Up</a></td><td width="40%" align="right"> Part II. Administrator's Guide</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs-core.adp 8 Nov 2017 09:42:11 -0000 1.3 @@ -17,19 +17,20 @@ translations”</a> </p></li><li class="listitem"> <p> -<strong>Rebuild the Changelog. </strong>Rebuild the +<strong>Rebuild the Changelog. </strong> Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS -5.0.2:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME -cvs2cl -F <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> --delta <span class="replaceable"><span class="replaceable">openacs-5-0-0-final</span></span>:<span class="replaceable"><span class="replaceable">oacs-5-0</span></span> -f ChangeLog -cvs2cl -F <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> --delta <span class="replaceable"><span class="replaceable">openacs-5-0-1-final</span></span>:<span class="replaceable"><span class="replaceable">oacs-5-0</span></span> -f ChangeLog-recent</span></span></pre> +5.0.2:</p><pre class="screen"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +cvs2cl -F <em class="replaceable"><code>oacs-5-0</code></em> --delta <em class="replaceable"><code>openacs-5-0-0-final</code></em>:<em class="replaceable"><code>oacs-5-0</code></em> -f ChangeLog +cvs2cl -F <em class="replaceable"><code>oacs-5-0</code></em> --delta <em class="replaceable"><code>openacs-5-0-1-final</code></em>:<em class="replaceable"><code>oacs-5-0</code></em> -f ChangeLog-recent</span></pre> </li><li class="listitem"> <p> -<strong>Update Version Numbers. </strong>The version -numbers in the documentation and in the packages must be updated. -This should only happen after a release candidate is approved.</p><p class="remark"><em><span class="remark">.LRN: this must be +<strong>Update Version Numbers. </strong> The +version numbers in the documentation and in the packages must be +updated. This should only happen after a release candidate is +approved.</p><p class="remark"><em><span class="remark">.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in OpenACS cvs tree). My current working model is that I @@ -55,14 +56,14 @@ with the new version number and the release date as arguments. Run it from /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages:</p><pre class="screen"> cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages - ./acs-core-docs/www/files/update-info <span class="replaceable"><span class="replaceable">5.2.1</span></span><span class="replaceable"><span class="replaceable">2006-01-16</span></span> + ./acs-core-docs/www/files/update-info <em class="replaceable"><code>5.2.1</code></em><em class="replaceable"><code>2006-01-16</code></em> </pre> </li><li class="listitem"><p>Install a new site using the modified code and verify that the automated tests pass.</p></li><li class="listitem"><p>Commit changes to CVS</p></li> </ol></div> </li><li class="listitem"> <p> -<strong>Tag the files in CVS. </strong>The steps to +<strong>Tag the files in CVS. </strong> The steps to this point should have ensured that the head of the current branch contains the full set of code to release. Now we need to tag it as the code to be released.</p><div class="orderedlist"><ol class="orderedlist" type="a"> @@ -71,19 +72,19 @@ cvs account with write access and should be a checkout from the release branch. In this example, we are assuming this is being done as a local user on openacs.org (which make the checkout and tagging -operations much faster).</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp -cvs -d /cvsroot checkout -r <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> acs-core</span></span></pre><p>If doing .LRN, repeat with the dotlrn cvs tree.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp +operations much faster).</p><pre class="screen"><span class="action">cd /var/tmp +cvs -d /cvsroot checkout -r <em class="replaceable"><code>oacs-5-0</code></em> acs-core</span></pre><p>If doing .LRN, repeat with the dotlrn cvs tree.</p><pre class="screen"><span class="action">cd /var/tmp mkdir dotlrn-packages cd dotlrn-packages -cvs -d /dotlrn-cvsroot checkout -r <span class="replaceable"><span class="replaceable">dotlrn-2-0</span></span> dotlrn-all -</span></span></pre> +cvs -d /dotlrn-cvsroot checkout -r <em class="replaceable"><code>dotlrn-2-0</code></em> dotlrn-all +</span></pre> </li><li class="listitem"> <p>Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if -releasing 5.0.3 final, move the openacs-5-0-compat flag.)</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/openacs-4 -cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> -cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-compat</span></span> -</span></span></pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> +releasing 5.0.3 final, move the openacs-5-0-compat flag.)</p><pre class="screen"><span class="action">cd /var/tmp/openacs-4 +cvs tag -F <em class="replaceable"><code>openacs-5-0-0a1</code></em> +cvs tag -F <em class="replaceable"><code>openacs-5-0-compat</code></em> +</span></pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Branching</h3><p>When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the @@ -96,88 +97,88 @@ the flag and slightly different tag nomenclature. To see the list of old branches, <code class="computeroutput">cvs status -v somefile</code>.</p><pre class="screen"> -cvs tag -b <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> +cvs tag -b <em class="replaceable"><code>oacs-5-0</code></em> </pre> </div><p>If doing .LRN: Since the .LRN packages aren't all in one module, we iterate through all of the modules. Log in first (cvs -login) so that you don't have to log in for each module.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/dotlrn-packages -for dir in *; do ( cd $dir && cvs tag <span class="replaceable"><span class="replaceable">dotlrn-2-0-2-final</span></span> ); done -for dir in *; do ( cd $dir && cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-compat</span></span> ); done -</span></span></pre><p>Note that for the compat tag we use the <span class="action"><span class="action">-F</span></span> flag which will -force the tag to the new version (just in case someone has created -the tag already on another version). Exercise care when doing this -since you don't want to inadvertently move a prior release tag. -Also if the tagging goes horribly wrong for some reason you can -delete the tag via <span class="command"><strong>cvs tag -d +login) so that you don't have to log in for each module.</p><pre class="screen"><span class="action">cd /var/tmp/dotlrn-packages +for dir in *; do ( cd $dir && cvs tag <em class="replaceable"><code>dotlrn-2-0-2-final</code></em> ); done +for dir in *; do ( cd $dir && cvs tag -F <em class="replaceable"><code>openacs-5-0-compat</code></em> ); done +</span></pre><p>Note that for the compat tag we use the <span class="action">-F</span> flag which will force the tag to the new version +(just in case someone has created the tag already on another +version). Exercise care when doing this since you don't want to +inadvertently move a prior release tag. Also if the tagging goes +horribly wrong for some reason you can delete the tag via +<span class="command"><strong>cvs tag -d <symbolic_tag></strong></span>.</p> </li><li class="listitem"> <p>Apply the <code class="computeroutput">final</code> tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply -done on openacs.org:</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp -cvs -d /cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> openacs-4 +done on openacs.org:</p><pre class="screen"><span class="action">cd /var/tmp +cvs -d /cvsroot checkout -r <em class="replaceable"><code>openacs-5-1-compat</code></em> openacs-4 cd openacs-4 -cvs tag <span class="replaceable"><span class="replaceable">openacs-5-1-2-final</span></span> -</span></span></pre> +cvs tag <em class="replaceable"><code>openacs-5-1-2-final</code></em> +</span></pre> </li> </ol></div> </li><li class="listitem"> <p><strong>Make the tarball(s). </strong></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> <p><strong>openacs-core. </strong></p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> -<p>Go to a new working space and export the tagged files.</p><pre class="screen"><span class="action"><span class="action">mkdir /var/tmp/tarball +<p>Go to a new working space and export the tagged files.</p><pre class="screen"><span class="action">mkdir /var/tmp/tarball cd /var/tmp/tarball -cvs -d /cvsroot export -r <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> acs-core</span></span></pre> +cvs -d /cvsroot export -r <em class="replaceable"><code>openacs-5-0-0a1</code></em> acs-core</span></pre> </li><li class="listitem"> -<p>Generate the tarball.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/tarball -mv openacs-4 openacs-<span class="replaceable"><span class="replaceable">5.0.0a1</span></span> -tar cz -f <span class="replaceable"><span class="replaceable">openacs-5.0.0a1.tar.gz</span></span> openacs-<span class="replaceable"><span class="replaceable">5.0.0a1</span></span> -</span></span></pre> +<p>Generate the tarball.</p><pre class="screen"><span class="action">cd /var/tmp/tarball +mv openacs-4 openacs-<em class="replaceable"><code>5.0.0a1</code></em> +tar cz -f <em class="replaceable"><code>openacs-5.0.0a1.tar.gz</code></em> openacs-<em class="replaceable"><code>5.0.0a1</code></em> +</span></pre> </li> </ol></div> </li><li class="listitem"> <p><strong>dotlrn. </strong></p><div class="orderedlist"><ol class="orderedlist" type="a"> <li class="listitem"> <p>Go to a new working space and export the tagged files. (was getting errors here trying to use -d, so gave up and just moved -things from openacs-4 to OpenACS at the end)</p><pre class="screen"><span class="action"><span class="action">mkdir /var/tmp/dotlrn-tarball +things from openacs-4 to OpenACS at the end)</p><pre class="screen"><span class="action">mkdir /var/tmp/dotlrn-tarball cd /var/tmp/dotlrn-tarball -cvs -d /cvsroot export -r <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> acs-core +cvs -d /cvsroot export -r <em class="replaceable"><code>openacs-5-0-0a1</code></em> acs-core cd /var/tmp/dotlrn-tarball/openacs-4/packages -cvs -d /cvsroot export -r <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> dotlrn-prereq -cvs -d /dotlrn-cvsroot export -r <span class="replaceable"><span class="replaceable">dotlrn-2-0-0a1</span></span> dotlrn-core -</span></span></pre> +cvs -d /cvsroot export -r <em class="replaceable"><code>openacs-5-0-0a1</code></em> dotlrn-prereq +cvs -d /dotlrn-cvsroot export -r <em class="replaceable"><code>dotlrn-2-0-0a1</code></em> dotlrn-core +</span></pre> </li><li class="listitem"> <p>Copy the dotlrn install.xml file, which controls which packages -are installed on setup, to the root location:</p><pre class="screen"><span class="action"><span class="action">cp /var/tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml \ +are installed on setup, to the root location:</p><pre class="screen"><span class="action">cp /var/tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml \ /var/tmp/dotlrn-tarball/openacs-4 -</span></span></pre> +</span></pre> </li><li class="listitem"> -<p>Generate the tarball</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/dotlrn-tarball -mv openacs-4 dotlrn-<span class="replaceable"><span class="replaceable">2.0.0a1</span></span> -tar cz -f <span class="replaceable"><span class="replaceable">dotlrn-2.0.0a1.tar.gz</span></span> dotlrn-<span class="replaceable"><span class="replaceable">2.0.0a1</span></span> -</span></span></pre> +<p>Generate the tarball</p><pre class="screen"><span class="action">cd /var/tmp/dotlrn-tarball +mv openacs-4 dotlrn-<em class="replaceable"><code>2.0.0a1</code></em> +tar cz -f <em class="replaceable"><code>dotlrn-2.0.0a1.tar.gz</code></em> dotlrn-<em class="replaceable"><code>2.0.0a1</code></em> +</span></pre> </li> </ol></div> </li> </ul></div> </li><li class="listitem"><p> -<strong>Test the new tarball(s). </strong>Download +<strong>Test the new tarball(s). </strong> Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass.</p></li><li class="listitem"> <p> -<strong>Update Web site. </strong>Update the +<strong>Update Web site. </strong> Update the different places on OpenACS.org where we track status.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones</p></li><li class="listitem"><p>Home page of openacs.org</p></li><li class="listitem"><p>Post a new news item</p></li> </ul></div> </li><li class="listitem"> <p> -<strong>Clean Up. </strong>Clean up after -yourself.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp -rm -rf tarball dotlrn-tarball dotlrn-packages openacs-<span class="replaceable"><span class="replaceable">5.0.0a1</span></span> -rm -rf /var/tmp/openacs-4</span></span></pre> +<strong>Clean Up. </strong> Clean up after +yourself.</p><pre class="screen"><span class="action">cd /var/tmp +rm -rf tarball dotlrn-tarball dotlrn-packages openacs-<em class="replaceable"><code>5.0.0a1</code></em> +rm -rf /var/tmp/openacs-4</span></pre> </li> </ol></div><p>Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been @@ -264,8 +265,8 @@ # Clean up after ourselves... cd $BASE && rm -rf dotlrn-tarball tarball openacs-4 dotlrn-packages -</pre><div class="cvstag">($‌Id: releasing-openacs.xml,v 1.22.2.5 -2017/04/22 17:18:48 gustafn Exp $)</div> +</pre><p><span class="cvstag">($‌Id: releasing-openacs.xml,v 1.23 +2017/08/07 23:47:54 gustafn Exp $)</span></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="releasing-openacs" leftLabel="Prev" leftTitle=" Index: openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html,v diff -u -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html 7 Aug 2017 23:47:52 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs-core.html 8 Nov 2017 09:42:11 -0000 1.22 @@ -1,65 +1,186 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Core and .LRN</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="next" href="update-repository.html" title="How to Update the OpenACS.org repository"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="releasing-openacs.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="update-repository.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="releasing-openacs-core"></a>OpenACS Core and .LRN</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Update Translations. </b><a class="xref" href="update-translations.html" title="How to Update the translations">the section called “How to Update the translations”</a></p></li><li class="listitem"><p><b>Rebuild the Changelog. </b>Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS 5.0.2:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME -cvs2cl -F <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> --delta <span class="replaceable"><span class="replaceable">openacs-5-0-0-final</span></span>:<span class="replaceable"><span class="replaceable">oacs-5-0</span></span> -f ChangeLog -cvs2cl -F <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> --delta <span class="replaceable"><span class="replaceable">openacs-5-0-1-final</span></span>:<span class="replaceable"><span class="replaceable">oacs-5-0</span></span> -f ChangeLog-recent</span></span></pre></li><li class="listitem"><p><b>Update Version Numbers. </b>The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved.</p><p class="remark"><em><span class="remark">.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in OpenACS cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and <a class="link" href="releasing-package.html" title="How to package and release an OpenACS Package">release those packages</a> when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.</span></em></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number. - </p></li><li class="listitem"><p>Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml -</p></li><li class="listitem"><p>Regenerate all HTML docs</p><pre class="screen">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml -make</pre></li><li class="listitem"><p>Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number</p></li><li class="listitem"><p>Update version number and release date in all of the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Core and .LRN</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="next" href="update-repository.html" title="How to Update the OpenACS.org repository"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="releasing-openacs.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="update-repository.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="releasing-openacs-core"></a>OpenACS Core and .LRN</h2></div></div></div> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Update Translations. </b> + <a class="xref" href="update-translations.html" title="How to Update the translations">the section called “How to Update the translations”</a> + </p> + </li><li class="listitem"> + <p> + <b>Rebuild the Changelog. </b> + Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir. We generate two changelogs, one for the minor branch and one for the most recent release. The example below is for OpenACS 5.0.2: + </p> + <pre class="screen"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +cvs2cl -F <em class="replaceable"><code>oacs-5-0</code></em> --delta <em class="replaceable"><code>openacs-5-0-0-final</code></em>:<em class="replaceable"><code>oacs-5-0</code></em> -f ChangeLog +cvs2cl -F <em class="replaceable"><code>oacs-5-0</code></em> --delta <em class="replaceable"><code>openacs-5-0-1-final</code></em>:<em class="replaceable"><code>oacs-5-0</code></em> -f ChangeLog-recent</span></pre> + </li><li class="listitem"> + <p> + <b>Update Version Numbers. </b> + The version numbers in the documentation and in the packages must be updated. This should only happen after a release candidate is approved. + </p> + <p class="remark"><em><span class="remark">.LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in OpenACS cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and <a class="link" href="releasing-package.html" title="How to package and release an OpenACS Package">release those packages</a> when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations.</span></em></p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number. + </p> + </li><li class="listitem"> + <p>Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml +</p> + </li><li class="listitem"> + <p>Regenerate all HTML docs</p> + <pre class="screen">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml +make</pre> + </li><li class="listitem"> + <p>Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number</p> + </li><li class="listitem"> + <p>Update version number and release date in all of the core packages. Use /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/update-info.sh with the new version number and the release date as arguments. - Run it from /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages:</p><pre class="screen">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages - ./acs-core-docs/www/files/update-info <span class="replaceable"><span class="replaceable">5.2.1</span></span> <span class="replaceable"><span class="replaceable">2006-01-16</span></span></pre></li><li class="listitem"><p>Install a new site using the modified code and verify that the automated tests pass.</p></li><li class="listitem"><p>Commit changes to CVS</p></li></ol></div></li><li class="listitem"><p><b>Tag the files in CVS. </b>The steps to this point should have ensured that the head of the current branch contains the full set of code to release. Now we need to tag it as the code to be released.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Check out OpenACS Core. The files must be checked + Run it from /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages:</p> + <pre class="screen">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages + ./acs-core-docs/www/files/update-info <em class="replaceable"><code>5.2.1</code></em> <em class="replaceable"><code>2006-01-16</code></em></pre> + </li><li class="listitem"> + <p>Install a new site using the modified code and verify that the automated tests pass.</p> + </li><li class="listitem"> + <p>Commit changes to CVS</p> + </li></ol></div> + </li><li class="listitem"> + <p> + <b>Tag the files in CVS. </b> + The steps to this point should have ensured that the head of the current branch contains the full set of code to release. Now we need to tag it as the code to be released. + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Check out OpenACS Core. The files must be checked out through a cvs account with write access and should be a checkout from the release branch. In this example, we are assuming this is being done as a local user on openacs.org (which make the - checkout and tagging operations much faster).</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp -cvs -d /cvsroot checkout -r <span class="replaceable"><span class="replaceable">oacs-5-0</span></span> acs-core</span></span></pre><p>If doing .LRN, repeat with the dotlrn cvs tree.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp + checkout and tagging operations much faster).</p> + <pre class="screen"><span class="action">cd /var/tmp +cvs -d /cvsroot checkout -r <em class="replaceable"><code>oacs-5-0</code></em> acs-core</span></pre> + <p>If doing .LRN, repeat with the dotlrn cvs tree.</p> + <pre class="screen"><span class="action">cd /var/tmp mkdir dotlrn-packages cd dotlrn-packages -cvs -d /dotlrn-cvsroot checkout -r <span class="replaceable"><span class="replaceable">dotlrn-2-0</span></span> dotlrn-all -</span></span></pre></li><li class="listitem"><p>Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/openacs-4 -cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> -cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-compat</span></span> -</span></span></pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Branching</h3><p>When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, <code class="computeroutput">cvs status -v somefile</code>.</p><pre class="screen">cvs tag -b <span class="replaceable"><span class="replaceable">oacs-5-0</span></span></pre></div><p>If doing .LRN: Since the .LRN packages aren't all in one +cvs -d /dotlrn-cvsroot checkout -r <em class="replaceable"><code>dotlrn-2-0</code></em> dotlrn-all +</span></pre> + </li><li class="listitem"> + <p>Tag the tree. If it's a final release of core, move or create the appropriate openacs-major-minor-compat tag. (Ie, if releasing 5.0.3 final, move the openacs-5-0-compat flag.)</p> + <pre class="screen"><span class="action">cd /var/tmp/openacs-4 +cvs tag -F <em class="replaceable"><code>openacs-5-0-0a1</code></em> +cvs tag -F <em class="replaceable"><code>openacs-5-0-compat</code></em> +</span></pre> + <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Branching</h3> + + <p>When we feature-freeze on HEAD as part of the release process, we are blocking new development. To avoid this, we branch the code at this point, so that new work can continue on HEAD while the branch is stabilized for release. However, branching means that bug fixes have to be synchronized between HEAD and the branch, and bug fixes tend to be more frequent right at this time. Therefore, our actual branch point is as late as possible - essentially, we do not branch until and unless new feature work is actively blocked by the feature freeze. Branching is almost the same as tagging, except for the flag and slightly different tag nomenclature. To see the list of old branches, <code class="computeroutput">cvs status -v somefile</code>.</p> + <pre class="screen">cvs tag -b <em class="replaceable"><code>oacs-5-0</code></em></pre> + </div> + <p>If doing .LRN: Since the .LRN packages aren't all in one module, we iterate through all of the modules. Log in first (cvs login) so that you don't have to log in for each - module.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/dotlrn-packages -for dir in *; do ( cd $dir && cvs tag <span class="replaceable"><span class="replaceable">dotlrn-2-0-2-final</span></span> ); done -for dir in *; do ( cd $dir && cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-compat</span></span> ); done -</span></span></pre><p>Note that for the compat tag we use the <span class="action"><span class="action">-F</span></span> flag which will force the tag to the new version (just in + module.</p> + <pre class="screen"><span class="action">cd /var/tmp/dotlrn-packages +for dir in *; do ( cd $dir && cvs tag <em class="replaceable"><code>dotlrn-2-0-2-final</code></em> ); done +for dir in *; do ( cd $dir && cvs tag -F <em class="replaceable"><code>openacs-5-0-compat</code></em> ); done +</span></pre> + <p>Note that for the compat tag we use the <span class="action">-F</span> flag which will force the tag to the new version (just in case someone has created the tag already on another version). Exercise care when doing this since you don't want to inadvertently move a prior release tag. Also if the tagging goes horribly wrong - for some reason you can delete the tag via <span class="command"><strong>cvs tag -d <symbolic_tag></strong></span>.</p></li><li class="listitem"><p>Apply the <code class="computeroutput">final</code> tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply done on openacs.org:</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp -cvs -d /cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> openacs-4 + for some reason you can delete the tag via <span class="command"><strong>cvs tag -d <symbolic_tag></strong></span>.</p> + </li><li class="listitem"> + <p>Apply the <code class="computeroutput">final</code> tag across the tree. First, check out the entire OpenACS tree, getting the most recent stable version of each package. This is most simply done on openacs.org:</p> + <pre class="screen"><span class="action">cd /var/tmp +cvs -d /cvsroot checkout -r <em class="replaceable"><code>openacs-5-1-compat</code></em> openacs-4 cd openacs-4 -cvs tag <span class="replaceable"><span class="replaceable">openacs-5-1-2-final</span></span></span></span></pre></li></ol></div></li><li class="listitem"><p><b>Make the tarball(s). </b></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>openacs-core. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Go to a new working space and export the tagged files.</p><pre class="screen"><span class="action"><span class="action">mkdir /var/tmp/tarball +cvs tag <em class="replaceable"><code>openacs-5-1-2-final</code></em></span></pre> + </li></ol></div> + + </li><li class="listitem"> + <p> + <b>Make the tarball(s). </b> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>openacs-core. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Go to a new working space and export the tagged files.</p> + <pre class="screen"><span class="action">mkdir /var/tmp/tarball cd /var/tmp/tarball -cvs -d /cvsroot export -r <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> acs-core</span></span></pre></li><li class="listitem"><p>Generate the tarball.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/tarball -mv openacs-4 openacs-<span class="replaceable"><span class="replaceable">5.0.0a1</span></span> -tar cz -f <span class="replaceable"><span class="replaceable">openacs-5.0.0a1.tar.gz</span></span> openacs-<span class="replaceable"><span class="replaceable">5.0.0a1</span></span> -</span></span></pre></li></ol></div></li><li class="listitem"><p><b>dotlrn. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Go to a new working space and export the tagged +cvs -d /cvsroot export -r <em class="replaceable"><code>openacs-5-0-0a1</code></em> acs-core</span></pre> + </li><li class="listitem"> + <p>Generate the tarball.</p> + <pre class="screen"><span class="action">cd /var/tmp/tarball +mv openacs-4 openacs-<em class="replaceable"><code>5.0.0a1</code></em> +tar cz -f <em class="replaceable"><code>openacs-5.0.0a1.tar.gz</code></em> openacs-<em class="replaceable"><code>5.0.0a1</code></em> +</span></pre> + </li></ol></div> + </li><li class="listitem"> + <p> + <b>dotlrn. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Go to a new working space and export the tagged files. (was getting errors here trying to use -d, so gave up and just moved things from openacs-4 to - OpenACS at the end)</p><pre class="screen"><span class="action"><span class="action">mkdir /var/tmp/dotlrn-tarball + OpenACS at the end)</p> + <pre class="screen"><span class="action">mkdir /var/tmp/dotlrn-tarball cd /var/tmp/dotlrn-tarball -cvs -d /cvsroot export -r <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> acs-core +cvs -d /cvsroot export -r <em class="replaceable"><code>openacs-5-0-0a1</code></em> acs-core cd /var/tmp/dotlrn-tarball/openacs-4/packages -cvs -d /cvsroot export -r <span class="replaceable"><span class="replaceable">openacs-5-0-0a1</span></span> dotlrn-prereq -cvs -d /dotlrn-cvsroot export -r <span class="replaceable"><span class="replaceable">dotlrn-2-0-0a1</span></span> dotlrn-core -</span></span></pre></li><li class="listitem"><p>Copy the dotlrn install.xml file, which controls +cvs -d /cvsroot export -r <em class="replaceable"><code>openacs-5-0-0a1</code></em> dotlrn-prereq +cvs -d /dotlrn-cvsroot export -r <em class="replaceable"><code>dotlrn-2-0-0a1</code></em> dotlrn-core +</span></pre> + </li><li class="listitem"> + <p>Copy the dotlrn install.xml file, which controls which packages are installed on setup, to the root - location:</p><pre class="screen"><span class="action"><span class="action">cp /var/tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml \ + location:</p> + <pre class="screen"><span class="action">cp /var/tmp/dotlrn-tarball/openacs-4/packages/dotlrn/install.xml \ /var/tmp/dotlrn-tarball/openacs-4 -</span></span></pre></li><li class="listitem"><p>Generate the tarball</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp/dotlrn-tarball -mv openacs-4 dotlrn-<span class="replaceable"><span class="replaceable">2.0.0a1</span></span> -tar cz -f <span class="replaceable"><span class="replaceable">dotlrn-2.0.0a1.tar.gz</span></span> dotlrn-<span class="replaceable"><span class="replaceable">2.0.0a1</span></span> -</span></span></pre></li></ol></div></li></ul></div></li><li class="listitem"><p><b>Test the new tarball(s). </b>Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass.</p></li><li class="listitem"><p><b>Update Web site. </b>Update the different places on OpenACS.org where we track status.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones</p></li><li class="listitem"><p>Home page of openacs.org</p></li><li class="listitem"><p>Post a new news item</p></li></ul></div></li><li class="listitem"><p><b>Clean Up. </b>Clean up after yourself.</p><pre class="screen"><span class="action"><span class="action">cd /var/tmp -rm -rf tarball dotlrn-tarball dotlrn-packages openacs-<span class="replaceable"><span class="replaceable">5.0.0a1</span></span> -rm -rf /var/tmp/openacs-4</span></span></pre></li></ol></div><p> +</span></pre> + </li><li class="listitem"> + <p>Generate the tarball</p> + <pre class="screen"><span class="action">cd /var/tmp/dotlrn-tarball +mv openacs-4 dotlrn-<em class="replaceable"><code>2.0.0a1</code></em> +tar cz -f <em class="replaceable"><code>dotlrn-2.0.0a1.tar.gz</code></em> dotlrn-<em class="replaceable"><code>2.0.0a1</code></em> +</span></pre> + </li></ol></div> + </li></ul></div> + </li><li class="listitem"> + <p> + <b>Test the new tarball(s). </b> + Download the tarballs just created and install them and make sure everything looks okay and that automated tests pass. + </p> + </li><li class="listitem"> + <p> + <b>Update Web site. </b> + Update the different places on OpenACS.org where we track status. + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Release Status for the current version - something like http://openacs.org/projects/openacs/5.0/milestones</p> + </li><li class="listitem"> + <p>Home page of openacs.org</p> + </li><li class="listitem"> + <p>Post a new news item</p> + </li></ul></div> + </li><li class="listitem"> + <p> + <b>Clean Up. </b> + Clean up after yourself. + </p> + <pre class="screen"><span class="action">cd /var/tmp +rm -rf tarball dotlrn-tarball dotlrn-packages openacs-<em class="replaceable"><code>5.0.0a1</code></em> +rm -rf /var/tmp/openacs-4</span></pre> + </li></ol></div> + + <p> Here is a shell script that automates packaging the tarball (it's a bit out of date with the new steps - I've been doing everything manually or with little throwaway scripts as detailed above until the process is stabilized). - </p><pre class="programlisting">#!/bin/bash + </p> + <pre class="programlisting">#!/bin/bash + # if TAG=1 create the cvs tags otherwise assume they exist. TAG=1 @@ -139,4 +260,7 @@ # Clean up after ourselves... cd $BASE && rm -rf dotlrn-tarball tarball openacs-4 dotlrn-packages -</pre><div class="cvstag">($Id$)</div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="releasing-openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="update-repository.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 16. Releasing OpenACS </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> How to Update the OpenACS.org repository</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + + <p><span class="cvstag">($Id$)</span></p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="releasing-openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="update-repository.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 16. Releasing OpenACS </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> How to Update the OpenACS.org repository</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/releasing-openacs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-openacs.html,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/releasing-openacs.html 7 Aug 2017 23:47:52 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/releasing-openacs.html 8 Nov 2017 09:42:11 -0000 1.31 @@ -1,2 +1,10 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 16. Releasing OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"><link rel="previous" href="ext-auth-requirements.html" title="External Authentication Requirements"><link rel="next" href="releasing-openacs-core.html" title="OpenACS Core and .LRN"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="ext-auth-requirements.html">Prev</a> </td><th width="60%" align="center">Part IV. For OpenACS Platform Developers</th><td width="20%" align="right"> <a accesskey="n" href="releasing-openacs-core.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="releasing-openacs"></a>Chapter 16. Releasing OpenACS</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="releasing-openacs-core.html">OpenACS Core and .LRN</a></span></dt><dt><span class="section"><a href="update-repository.html">How to Update the OpenACS.org repository</a></span></dt><dt><span class="section"><a href="releasing-package.html">How to package and release an OpenACS Package</a></span></dt><dt><span class="section"><a href="update-translations.html">How to Update the translations</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext-auth-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-openacs-core.html">Next</a></td></tr><tr><td width="40%" align="left">External Authentication Requirements </td><td width="20%" align="center"><a accesskey="u" href="acs-plat-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Core and .LRN</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 16. Releasing OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-plat-dev.html" title="Part IV. For OpenACS Platform Developers"><link rel="previous" href="ext-auth-requirements.html" title="External Authentication Requirements"><link rel="next" href="releasing-openacs-core.html" title="OpenACS Core and .LRN"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="ext-auth-requirements.html">Prev</a> </td><th width="60%" align="center">Part IV. For OpenACS Platform Developers</th><td width="20%" align="right"> <a accesskey="n" href="releasing-openacs-core.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="releasing-openacs"></a>Chapter 16. Releasing OpenACS</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="section"><a href="releasing-openacs-core.html">OpenACS Core and .LRN</a></span></dt><dt><span class="section"><a href="update-repository.html">How to Update the OpenACS.org repository</a></span></dt><dt><span class="section"><a href="releasing-package.html">How to package and release an OpenACS Package</a></span></dt><dt><span class="section"><a href="update-translations.html">How to Update the translations</a></span></dt></dl></div> + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ext-auth-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-openacs-core.html">Next</a></td></tr><tr><td width="40%" align="left">External Authentication Requirements </td><td width="20%" align="center"><a accesskey="u" href="acs-plat-dev.html">Up</a></td><td width="40%" align="right"> OpenACS Core and .LRN</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/releasing-package.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-package.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/releasing-package.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/releasing-package.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -13,10 +13,10 @@ Package</h2></div></div></div><p>In this example, we are packaging and releasing <code class="computeroutput">myfirstpackage</code> as version 1.0.0, which is compatible with OpenACS 5.0.x.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Update the version number, release date, and <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161393" target="_top">package maturity</a> of your package in the <a class="ulink" href="/acs-admin/apm/" target="_top">APM</a>.</p></li><li class="listitem"><p>Make sure all changes are committed.</p></li><li class="listitem"> -<p>Tag the updated work.:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> -cvs tag <span class="replaceable"><span class="replaceable">myfirstpackages-1-0-0-final</span></span> -cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-compat</span></span> -</span></span></pre> +<p>Tag the updated work.:</p><pre class="screen"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/<em class="replaceable"><code>myfirstpackage</code></em> +cvs tag <em class="replaceable"><code>myfirstpackages-1-0-0-final</code></em> +cvs tag -F <em class="replaceable"><code>openacs-5-0-compat</code></em> +</span></pre> </li> </ol></div><p>Done. The package will be added to the <a class="ulink" href="http://openacs.org/repository" target="_top">repository</a> automatically. If the correct version does not show up within 24 Index: openacs-4/packages/acs-core-docs/www/releasing-package.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/releasing-package.html,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/releasing-package.html 7 Aug 2017 23:47:52 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/releasing-package.html 8 Nov 2017 09:42:12 -0000 1.17 @@ -1,5 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to package and release an OpenACS Package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="update-repository.html" title="How to Update the OpenACS.org repository"><link rel="next" href="update-translations.html" title="How to Update the translations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="update-repository.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="update-translations.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="releasing-package"></a>How to package and release an OpenACS Package</h2></div></div></div><p>In this example, we are packaging and releasing <code class="computeroutput">myfirstpackage</code> as version 1.0.0, which is compatible with OpenACS 5.0.x.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Update the version number, release date, and <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161393" target="_top">package maturity</a> of your package in the <a class="ulink" href="/acs-admin/apm/" target="_top">APM</a>.</p></li><li class="listitem"><p>Make sure all changes are committed.</p></li><li class="listitem"><p>Tag the updated work.:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> -cvs tag <span class="replaceable"><span class="replaceable">myfirstpackages-1-0-0-final</span></span> -cvs tag -F <span class="replaceable"><span class="replaceable">openacs-5-0-compat</span></span> -</span></span></pre></li></ol></div><p>Done. The package will be added to the <a class="ulink" href="http://openacs.org/repository" target="_top">repository</a> automatically. If the correct version does not show up within 24 hours, ask for help on the OpenACS.org development forum.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="update-repository.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="update-translations.html">Next</a></td></tr><tr><td width="40%" align="left">How to Update the OpenACS.org repository </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> How to Update the translations</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to package and release an OpenACS Package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="update-repository.html" title="How to Update the OpenACS.org repository"><link rel="next" href="update-translations.html" title="How to Update the translations"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="update-repository.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="update-translations.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="releasing-package"></a>How to package and release an OpenACS Package</h2></div></div></div> + + <p>In this example, we are packaging and releasing <code class="computeroutput">myfirstpackage</code> as version 1.0.0, which is compatible with OpenACS 5.0.x.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Update the version number, release date, and <a class="ulink" href="http://openacs.org/forums/message-view?message_id=161393" target="_top">package maturity</a> of your package in the <a class="ulink" href="/acs-admin/apm/" target="_top">APM</a>.</p> + </li><li class="listitem"> + <p>Make sure all changes are committed.</p> + </li><li class="listitem"> + <p>Tag the updated work.:</p> + <pre class="screen"><span class="action">cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/<em class="replaceable"><code>myfirstpackage</code></em> +cvs tag <em class="replaceable"><code>myfirstpackages-1-0-0-final</code></em> +cvs tag -F <em class="replaceable"><code>openacs-5-0-compat</code></em> +</span></pre> + </li></ol></div> + <p>Done. The package will be added to the <a class="ulink" href="http://openacs.org/repository" target="_top">repository</a> automatically. If the correct version does not show up within 24 hours, ask for help on the OpenACS.org development forum.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="update-repository.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="update-translations.html">Next</a></td></tr><tr><td width="40%" align="left">How to Update the OpenACS.org repository </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> How to Update the translations</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/remote-postgres.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/remote-postgres.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/remote-postgres.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -26,7 +26,7 @@ specific remote clients to access. Access can be controlled ... (add notes from forum post)</p></li><li class="listitem"> <p>Change the OpenACS service's configuration file to point to -the remote database. Edit <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl</code> +the remote database. Edit <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl</code> and change</p><pre class="programlisting"></pre><p>to</p><pre class="programlisting"></pre> </li> </ul></div> Index: openacs-4/packages/acs-core-docs/www/remote-postgres.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/remote-postgres.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/remote-postgres.html 7 Aug 2017 23:47:52 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/remote-postgres.html 8 Nov 2017 09:42:12 -0000 1.15 @@ -1,12 +1,29 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Running a PostgreSQL database on another server</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="database-management.html" title="Chapter 7. Database Management"><link rel="previous" href="database-management.html" title="Chapter 7. Database Management"><link rel="next" href="install-openacs-delete-tablespace.html" title="Deleting a tablespace"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="database-management.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Database Management</th><td width="20%" align="right"> <a accesskey="n" href="install-openacs-delete-tablespace.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="remote-postgres"></a>Running a PostgreSQL database on another server</h2></div></div></div><p>To run a database on a different machine than the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Running a PostgreSQL database on another server</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="database-management.html" title="Chapter 7. Database Management"><link rel="previous" href="database-management.html" title="Chapter 7. Database Management"><link rel="next" href="install-openacs-delete-tablespace.html" title="Deleting a tablespace"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="database-management.html">Prev</a> </td><th width="60%" align="center">Chapter 7. Database Management</th><td width="20%" align="right"> <a accesskey="n" href="install-openacs-delete-tablespace.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="remote-postgres"></a>Running a PostgreSQL database on another server</h2></div></div></div> + + + <p>To run a database on a different machine than the webserver requires changes to the database configuration file and access control file, and to the OpenACS service's - configuration file.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Edit the database configuration file, which in a + configuration file.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Edit the database configuration file, which in a Reference install is located at <code class="computeroutput">/usr/local/pgsql/data/postgresql.conf</code> - and change</p><pre class="programlisting">#tcpip_socket = false</pre><p>to</p><pre class="programlisting">tcpip_socket = true</pre></li><li class="listitem"><p>Change the access control file for the database to + and change</p> + <pre class="programlisting">#tcpip_socket = false</pre> +<p>to</p> +<pre class="programlisting">tcpip_socket = true</pre> + </li><li class="listitem"> + <p>Change the access control file for the database to permit specific remote clients to access. Access can be - controlled ... (add notes from forum post) </p></li><li class="listitem"><p>Change the OpenACS service's configuration file to + controlled ... (add notes from forum post) </p> + </li><li class="listitem"> + <p>Change the OpenACS service's configuration file to point to the remote database. Edit - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/config.tcl</code> - and change</p><pre class="programlisting"></pre><p>to </p><pre class="programlisting"></pre></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="database-management.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-openacs-delete-tablespace.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 7. Database Management </td><td width="20%" align="center"><a accesskey="u" href="database-management.html">Up</a></td><td width="40%" align="right"> Deleting a tablespace</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/config.tcl</code> + and change</p> + <pre class="programlisting"></pre> + <p>to </p> + <pre class="programlisting"></pre> + </li></ul></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="database-management.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="install-openacs-delete-tablespace.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 7. Database Management </td><td width="20%" align="center"><a accesskey="u" href="database-management.html">Up</a></td><td width="40%" align="right"> Deleting a tablespace</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/request-processor.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/request-processor.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/request-processor.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="db-api" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="request-processor" id="request-processor"></a>The Request Processor</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="request-processor" id="request-processor"></a>The Request Processor</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-overview" id="rp-overview"></a>Overview</h3></div></div></div><p>This document is a brief introduction to the OpenACS 5.9.0 Request Processor; more details can be found in the <a class="xref" href="rp-design" title="Request Processor Design">OpenACS 4 @@ -106,8 +103,8 @@ name of the package.</p></dd><dt><span class="term"><code class="computeroutput">[ad_conn path_info]</code></span></dt><dd><p>In a .vuh file, path_info is the trailing part of the URL not matched by the .vuh file.</p></dd> -</dl></div><div class="cvstag">($‌Id: rp.xml,v 1.12.6.3 2017/04/21 15:07:52 -gustafn Exp $)</div> +</dl></div><p><span class="cvstag">($‌Id: rp.xml,v 1.13 2017/08/07 23:47:54 +gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/request-processor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/request-processor.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/request-processor.html 7 Aug 2017 23:47:52 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/request-processor.html 8 Nov 2017 09:42:12 -0000 1.51 @@ -1,26 +1,44 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>The Request Processor</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="objects.html" title="OpenACS Data Models and the Object System"><link rel="next" href="db-api.html" title="The OpenACS Database Access API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="request-processor"></a>The Request Processor</h2></div></div></div><div class="authorblurb"><p>By Pete Su</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-overview"></a>Overview</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>The Request Processor</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="objects.html" title="OpenACS Data Models and the Object System"><link rel="next" href="db-api.html" title="The OpenACS Database Access API"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="request-processor"></a>The Request Processor</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Pete Su</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-overview"></a>Overview</h3></div></div></div> + +<p> This document is a brief introduction to the OpenACS 5.9.0 Request Processor; more details can be found in the <a class="xref" href="rp-design.html" title="Request Processor Design">OpenACS 4 Request Processor Design</a>. Here we cover the high level concepts behind the system, and implications and usage for the application developer. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-thenewway"></a>Request Processor</h3></div></div></div><p> +</p> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-thenewway"></a>Request Processor</h3></div></div></div> + +<p> The 5.9.0 Request Processor is a global filter and set of Tcl procs that respond to every incoming URL reaching the server. The following diagram summarizes the stages of the request processor assuming a URL request like <code class="computeroutput">http://someserver.com/notes/somepage.adp</code>. </p><div class="mediaobject" align="center"><img src="images/rp-flow.gif" align="middle"></div><p> -</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">Stage 1: Search Site Map</span></dt><dd><p> +</p> + + + +<div class="variablelist"><dl class="variablelist"><dt><span class="term">Stage 1: Search Site Map</span></dt><dd><p> The first thing the RP does is to map the given URL to the appropriate physical directory in the filesystem, from which to serve content. We do this by searching the site map data model (touched on in the <a class="xref" href="packages.html" title="OpenACS Packages">Packages</a>, and further discussed in <a class="xref" href="subsites.html" title="Writing OpenACS Application Pages">Writing OpenACS Application Pages</a>). This data model maps URLs to objects representing content, and these objects are typically package instances. -</p><p> +</p> + +<p> After looking up the appropriate object, the RP stores the URL, the ID of the object it found, and the package and package instance the object belongs to into the environment of the connection. This @@ -50,7 +68,9 @@ an abstract URL. It searches for files with predefined "magic" extensions, i.e. files that end with: <code class="computeroutput">.html</code>, <code class="computeroutput">.tcl</code> and <code class="computeroutput">.adp</code>. -</p><p> +</p> + +<p> If the RP can't find any matching files with the expected extensions, it will look for virtual-url-handler files, or <code class="computeroutput">.vuh</code> files. A <code class="computeroutput">.vuh</code> file will be executed as if it were a Tcl @@ -61,18 +81,31 @@ except that they integrate cleanly and correctly with the RP's URL mapping mechanisms. The details of how to use these files are described in <a class="xref" href="rp-design.html" title="Request Processor Design">OpenACS 4 Request Processor Design</a>. -</p><p> +</p> + +<p> Once the appropriate file is found, it is either served directly if it's static content, or sent to the template system or the standard Tcl interpreter if it's a dynamic page. -</p></dd></dl></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-basicapi"></a>Basic API</h3></div></div></div><p> +</p> + +</dd></dl></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-basicapi"></a>Basic API</h3></div></div></div> + +<p> Once the flow of control reaches a dynamic page, the Request Processor has populated the environment of the request with several pieces of useful information. The RP's environment is accessible through the <code class="computeroutput">ad_conn</code> interface, and the following calls should be useful to you when developing dynamic pages: -</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">[ad_conn user_id]</code> +</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">[ad_conn user_id]</code> + </span></dt><dd><p> The ID of the user associated with this request. By convention this is zero if there is no user. @@ -127,4 +160,10 @@ </span></dt><dd><p> In a .vuh file, path_info is the trailing part of the URL not matched by the .vuh file. -</p></dd></dl></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Data Models and the Object System </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The OpenACS Database Access API</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p></dd></dl></div> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="objects.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="db-api.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Data Models and the Object System </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> The OpenACS Database Access API</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/requirements-template.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/requirements-template.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/requirements-template.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,11 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="requirements-template" id="requirements-template"></a>System/Application Requirements -Template</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:youremail\@example.com" target="_top">You</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +Template</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:youremail\@example.com" target="_top">You</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="yourpackage-requirements-introduction" id="yourpackage-requirements-introduction"></a>Introduction</h3></div></div></div><p><span class="emphasis"><em>Briefly explain to the reader what this document is for, whether it records the requirements for a new @@ -127,8 +124,8 @@ <td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td> </tr> </tbody> -</table></div><div class="cvstag">($‌Id: requirements-template.xml,v 1.6.14.2 -2017/06/15 13:56:42 gustafn Exp $)</div> +</table></div><p><span class="cvstag">($‌Id: requirements-template.xml,v 1.7 +2017/08/07 23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/requirements-template.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/requirements-template.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/requirements-template.html 7 Aug 2017 23:47:52 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/requirements-template.html 8 Nov 2017 09:42:12 -0000 1.51 @@ -1,8 +1,18 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>System/Application Requirements Template</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="filename.html" title="Detailed Design Documentation Template"><link rel="next" href="i18n.html" title="Chapter 14. Internationalization"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="requirements-template"></a>System/Application Requirements Template</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:youremail@example.com" target="_top">You</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>System/Application Requirements Template</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="doc-standards.html" title="Chapter 13. Documentation Standards"><link rel="previous" href="filename.html" title="Detailed Design Documentation Template"><link rel="next" href="i18n.html" title="Chapter 14. Internationalization"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><th width="60%" align="center">Chapter 13. Documentation Standards</th><td width="20%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="requirements-template"></a>System/Application Requirements Template</h2></div></div></div> + + + + <span style="color: red"><authorblurb> + <p>By <a class="ulink" href="mailto:youremail@example.com" target="_top">You</a></p> + </authorblurb></span> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-introduction"></a>Introduction</h3></div></div></div> + + + + <p> <span class="emphasis"><em>Briefly explain to the reader what this document is for, whether it records the requirements for a new system, a client application, a toolkit subsystem, etc. Remember your audience: fellow programmers, @@ -11,61 +21,133 @@ everywhere, write clearly and precisely; for requirements documentation, write at a level that any intelligent layperson can understand.</em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div></div><p> + </p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-vision"></a>Vision Statement</h3></div></div></div> + + <p> + + <span class="emphasis"><em>Very broadly, describe how the system meets a need of a business, group, the OpenACS as a whole, etc. Make sure that technical and non-technical readers alike would understand what the system would do and why it's useful. Whenever applicable, you should explicitly state what the business value of the system is. </em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-system-app-overview"></a>System/Application Overview</h3></div></div></div> + + + + <p> <span class="emphasis"><em>Discuss the high-level breakdown of the components that make up the system. You can go by functional areas, by the main transactions the system allows, etc. </em></span> - </p><p> + </p> + + <p> <span class="emphasis"><em>You should also state the context and dependencies of the system here, e.g. if it's an application-level package for OpenACS 4, briefly describe how it uses kernel services, like permissions or subsites. </em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-cases"></a>Use-cases and User-scenarios</h3></div></div></div> + + + + <p> <span class="emphasis"><em>Determine the types or classes of users who would use the system, and what their experience would be like at a high-level. Sketch what their experience would be like and what actions they would take, and how the system would support them.</em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-competitive-analysis"></a>Optional: Competitive Analysis</h3></div></div></div> + + + + <p> <span class="emphasis"><em>Describe other systems or services that are comparable to what you're building. If applicable, say why your implementation will be superior, where it will match the competition, and where/why it will lack existing best-of-breed capabilities. This section is also in the Design doc, so write about it where you deem most appropriate.</em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-links"></a>Related Links</h3></div></div></div><p>Include all pertinent links to supporting and related material, - such as: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li><li class="listitem"><p> Design document</p></li><li class="listitem"><p> Developer's guide</p></li><li class="listitem"><p> User's guide</p></li><li class="listitem"><p> Other-cool-system-related-to-this-one document</p></li><li class="listitem"><p> Test plan </p></li><li class="listitem"><p> Competitive system(s)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div></div><p> + </p> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-links"></a>Related Links</h3></div></div></div> + + + <p>Include all pertinent links to supporting and related material, + such as: </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> System/Package "coversheet" - where all documentation for this software is linked off of</p></li><li class="listitem"><p> Design document</p></li><li class="listitem"><p> Developer's guide</p></li><li class="listitem"><p> User's guide</p></li><li class="listitem"><p> Other-cool-system-related-to-this-one document</p></li><li class="listitem"><p> Test plan </p></li><li class="listitem"><p> Competitive system(s)</p></li></ul></div> + + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-requirements"></a>Requirements</h3></div></div></div> + + + <p> <span class="emphasis"><em>The main course of the document, requirements. Break up the requirements sections (A, B, C, etc.) as needed. Within each section, create a list denominated with unique identifiers that reflect any functional hierarchy present, e.g. 20.5.13. - for the first number, leave generous gaps on the first writing of requirements (e.g. 1, 10, 20, 30, 40, etc.) because you'll want to leave room for any missing key requirements that may arise. </em></span> - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>10.0 A Common Solution</strong></span></p><p> + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + + <p><span class="strong"><strong>10.0 A Common Solution</strong></span></p> + + <p> Programmers and designers should only have to learn a single system that serves as a UI substrate for all the functionally specific modules in the toolkit. - </p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>10.0.1</strong></span></p><p> + </p> + + <div class="blockquote"><blockquote class="blockquote"> + <p><span class="strong"><strong>10.0.1</strong></span></p> + + <p> The system should not make any assumptions about how pages should look or function. - </p><p><span class="strong"><strong>10.0.5</strong></span></p><p> + </p> + + <p><span class="strong"><strong>10.0.5</strong></span></p> + + <p> Publishers should be able to change the default presentation of any module using a single methodology with minimal exposure to code. - </p></blockquote></div></li></ul></div><p> + </p> + </blockquote></div> + </li></ul></div> + + <p> For guidelines writing requirements, take a look at <a class="ulink" href="http://www.utm.mx/~caff/doc/OpenUPWeb/openup/guidances/guidelines/writing_good_requirements_48248536.html" target="_top"> quality standards</a> or <a class="ulink" href="https://ep.jhu.edu/about-us/news-and-media/writing-good-requirements-checklists" target="_top">requirements checklist</a>, along with a good example, such as <a class="xref" href="apm-requirements.html" title="Package Manager Requirements">Package Manager Requirements</a>. - </p><p> + </p> + + <p> Besides writing requirements in natural language, consider using the following techniques as needed: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Pseudocode - a quasi programming language, combining the + </p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> Pseudocode - a quasi programming language, combining the informality of natural language with the strict syntax and control structures of a programming language. </p></li><li class="listitem"><p> Finite State Machines - a hypothetical machine that can be in only one of a given number of states at any specific time. Useful to @@ -74,11 +156,35 @@ suited to handle combinations of inputs. </p></li><li class="listitem"><p> Flowcharts - easy to draw and understand, suited for event and decision driven systems. UML is the industry standard here.</p></li><li class="listitem"><p> Entity-Relationship diagrams - a necessary part of Design documents, sometimes a high-level ER diagram is useful for - requirements as well.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div></div><p> + requirements as well.</p></li></ul></div> + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-requirements-implementation"></a>Optional: Implementation Notes</h3></div></div></div> + + + + <p> <span class="emphasis"><em>Although in theory coding comes after design, which comes after requirements, we do not, and perhaps should not, always follow such a rigid process (a.k.a. the waterfall lifecyle). Often, there is a pre-existing system or prototype first, and thus you may want to write some thoughts on implementation, for aiding and guiding yourself or other programmers. </em></span> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-revision-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th class="revisionheader">Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td class="revisionbody">0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr><tr><td width="40%" align="left">Detailed Design Documentation Template </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Chapter 14. Internationalization</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="yourpackage-revision-history"></a>Revision History</h3></div></div></div> + + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th class="revisionheader">Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td class="revisionbody">0.3</td><td>Edited further, incorporated feedback from Michael Yoon</td><td>9/05/2000</td><td>Kai Wu</td></tr><tr><td>0.2</td><td>Edited</td><td>8/22/2000</td><td>Kai Wu</td></tr><tr><td>0.1</td><td>Created</td><td>8/21/2000</td><td>Josh Finkler, Audrey McLoghlin</td></tr></tbody></table></div> + + <p><span class="cvstag">($Id$)</span></p> + + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="filename.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="i18n.html">Next</a></td></tr><tr><td width="40%" align="left">Detailed Design Documentation Template </td><td width="20%" align="center"><a accesskey="u" href="doc-standards.html">Up</a></td><td width="40%" align="right"> Chapter 14. Internationalization</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/rp-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/rp-design.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/rp-design.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="tcl-doc" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="rp-design" id="rp-design"></a>Request Processor Design</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="rp-design" id="rp-design"></a>Request Processor Design</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. +Schloming</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-design-essentials" id="rp-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p><a class="xref" href="rp-requirements" title="Request Processor Requirements">OpenACS 4 Request Processor Index: openacs-4/packages/acs-core-docs/www/rp-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-design.html,v diff -u -r1.38 -r1.39 --- openacs-4/packages/acs-core-docs/www/rp-design.html 7 Aug 2017 23:47:52 -0000 1.38 +++ openacs-4/packages/acs-core-docs/www/rp-design.html 8 Nov 2017 09:42:12 -0000 1.39 @@ -1,36 +1,99 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Request Processor Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="rp-requirements.html" title="Request Processor Requirements"><link rel="next" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rp-design"></a>Request Processor Design</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="rp-requirements.html" title="Request Processor Requirements">OpenACS 4 Request Processor Requirements</a></p></li><li class="listitem"><p><a class="ulink" href="request-processor" target="_top">Request Processor Stages and API</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/request-processor-procs.tcl" target="_top"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Request Processor Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="rp-requirements.html" title="Request Processor Requirements"><link rel="next" href="tcl-doc.html" title="Documenting Tcl Files: Page Contracts and Libraries"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rp-design"></a>Request Processor Design</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-essentials"></a>Essentials</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p><a class="xref" href="rp-requirements.html" title="Request Processor Requirements">OpenACS 4 Request Processor Requirements</a></p> +</li><li class="listitem"> +<p><a class="ulink" href="request-processor" target="_top">Request Processor Stages and API</a></p> +</li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/request-processor-procs.tcl" target="_top"> /packages/acs-tcl/tcl/request-processor-procs.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/request-processor-init.tcl" target="_top"> /packages/acs-tcl/tcl/request-processor-init.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/site-nodes-procs.tcl" target="_top"> /packages/acs-tcl/tcl/site-nodes-procs.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/api-doc/procs-file-view?path=packages/acs-tcl/tcl/site-nodes-init.tcl" target="_top"> /packages/acs-tcl/tcl/site-nodes-init.tcl</a></p></li><li class="listitem"><p><a class="ulink" href="/doc/sql/display-sql?package_key=acs-kernel&url=site-nodes-create.sql" target="_top"> -/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-intro"></a>Introduction</h3></div></div></div><p>The request processor is the set of procs that responds to every HTTP +/packages/acs-kernel/sql/site-nodes-create.sql</a></p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-intro"></a>Introduction</h3></div></div></div> + + +<p>The request processor is the set of procs that responds to every HTTP request made to the OpenACS. The request processor must authenticate the connecting user, and make sure that he is authorized to perform the given request. If these steps succeed, then the request processor must locate the file that is associated with the specified URL, and serve the content it -provides to the browser.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-related-systems"></a>Related Systems</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="apm-design.html" title="Package Manager Design">Package Manager Design</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-terminology"></a>Terminology</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +provides to the browser.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-related-systems"></a>Related Systems</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="apm-design.html" title="Package Manager Design">Package Manager Design</a></p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-terminology"></a>Terminology</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <span class="strong"><strong>pageroot</strong></span> -- Any directory that contains scripts and/or static files intended to be served in response to HTTP requests. A typical -OpenACS installation is required to serve files from multiple pageroots.</p></li><li class="listitem"><p><span class="strong"><strong>global pageroot</strong></span> +OpenACS installation is required to serve files from multiple pageroots.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>global pageroot</strong></span> (<span class="strong"><strong>/var/lib/aolserver/<span class="emphasis"><em>servicename</em></span>/www</strong></span>) -- Files appearing under this pageroot will be served directly off the base url -http://www.<span class="emphasis"><em>servicename</em></span>.com/</p></li><li class="listitem"><p><span class="strong"><strong>package root</strong></span> +http://www.<span class="emphasis"><em>servicename</em></span>.com/</p> +</li><li class="listitem"> +<p><span class="strong"><strong>package root</strong></span> (<span class="strong"><strong>/var/lib/aolserver/<span class="emphasis"><em>servicename</em></span>/packages</strong></span>) -- Each subdirectory of the package root is a package. A typical OpenACS installation will have several -packages.</p></li><li class="listitem"><p><span class="strong"><strong>package pageroot</strong></span> +packages.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>package pageroot</strong></span> (<span class="strong"><strong>/var/lib/aolserver/<span class="emphasis"><em>servicename</em></span>/packages/<span class="emphasis"><em>package_key</em></span>/www</strong></span>) --- This is the pageroot for the <span class="emphasis"><em>package_key</em></span> package.</p></li><li class="listitem"><p><span class="strong"><strong>request environment</strong></span> (<span class="strong"><strong>ad_conn</strong></span>) -- This is +-- This is the pageroot for the <span class="emphasis"><em>package_key</em></span> package.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>request environment</strong></span> (<span class="strong"><strong>ad_conn</strong></span>) -- This is a global namespace containing variables associated with the current -request.</p></li><li class="listitem"><p><span class="strong"><strong>abstract URL</strong></span> -- A URL with no extension that doesn't -directly correspond to a file in the filesystem.</p></li><li class="listitem"><p><span class="strong"><strong>abstract file</strong></span> or <span class="strong"><strong>abstract path</strong></span> -- A URL +request.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>abstract URL</strong></span> -- A URL with no extension that doesn't +directly correspond to a file in the filesystem.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>abstract file</strong></span> or <span class="strong"><strong>abstract path</strong></span> -- A URL that has been translated into a file system path (probably by prepending the appropriate pageroot), but still doesn't have any extension and so does -not directly correspond to a file in the filesystem.</p></li><li class="listitem"><p><span class="strong"><strong>concrete file</strong></span> or <span class="strong"><strong>concrete path</strong></span> -- A file -or path that actually references something in the filesystem.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-system-overview"></a>System Overview</h3></div></div></div><p><span class="strong"><strong>Package Lookup</strong></span></p><p>One of the first things the request processor must do is to determine +not directly correspond to a file in the filesystem.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>concrete file</strong></span> or <span class="strong"><strong>concrete path</strong></span> -- A file +or path that actually references something in the filesystem.</p> +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-system-overview"></a>System Overview</h3></div></div></div> + + + +<p><span class="strong"><strong>Package Lookup</strong></span></p> + +<p>One of the first things the request processor must do is to determine which package instance a given request references, and based on this information, which pageroot to use when searching for a file to serve. During this process the request processor divides the URL into two pieces. The first @@ -43,12 +106,20 @@ able to figure out which <span class="strong"><strong>package_id</strong></span> is associated with a given package_url, and package mountings must be persistent across server restarts and users must be able to manipulate the mountings on a live site, -therefore this mapping is stored in the database.</p><p><span class="strong"><strong>Authentication and Authorization</strong></span></p><p>Once the request processor has located both the package_id and concrete +therefore this mapping is stored in the database.</p> + +<p><span class="strong"><strong>Authentication and Authorization</strong></span></p> + +<p>Once the request processor has located both the package_id and concrete file associated with the request, authentication is performed by the <a class="ulink" href="security-design.html" target="_top">session</a> security system. After authentication has been performed the user is authorized to have read access for the given package by the <a class="xref" href="permissions-design.html" title="Permissions Design">OpenACS 4 Permissions Design</a>. If authorization succeeds then the request is served, otherwise it is -aborted.</p><p><span class="strong"><strong>Concrete File Search</strong></span></p><p>To actually serve a file, the request processor generates an ordered list +aborted.</p> + +<p><span class="strong"><strong>Concrete File Search</strong></span></p> + +<p>To actually serve a file, the request processor generates an ordered list of abstract paths and searches each path for a concrete file. The first path searched is composed of the package pageroot with the extra portion of the URL appended. The second abstract path consists of the global pageroot with @@ -59,7 +130,11 @@ directory. Files take precedence over directory listings, so an index file in the global pageroot will be served instead of a directory listing in the package pageroot, even though the global pageroot is searched later. If a -file is found at any of the searched locations then it is served.</p><p><span class="strong"><strong>Virtual URL Handlers</strong></span></p><p>If no file is found during the concrete file search, then the request +file is found at any of the searched locations then it is served.</p> + +<p><span class="strong"><strong>Virtual URL Handlers</strong></span></p> + +<p>If no file is found during the concrete file search, then the request processor searches the filesystem for a <span class="strong"><strong>virtual url handler</strong></span> (<span class="strong"><strong>.vuh</strong></span>) file. This file contains normal Tcl code, and is in fact handled by the same extension handling procedure that handles .tcl @@ -74,29 +149,55 @@ special distinction is required between sitewide procs and package specific procs when using this facility. It is also much less prone to overlap and confusion than the use of registered procs, especially in an environment with -many packages installed.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-site-nodes"></a>Site Nodes</h3></div></div></div><p>The request processor manages the mappings from URL patterns to package +many packages installed.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-site-nodes"></a>Site Nodes</h3></div></div></div> + + +<p>The request processor manages the mappings from URL patterns to package instances with the site_nodes data model. Every row in the site_nodes table represents a fully qualified URL. A package can be mounted on any node in this data model. When the request processor performs a URL lookup, it determines which node matches the longest possible prefix of the request URI. In order to make this lookup operation as fast as possible, the rows in the site_nodes table are pulled out of the database at server startup, and stored -in memory.</p><p>The memory structure used to store the site_nodes mapping is a hash table +in memory.</p> + +<p>The memory structure used to store the site_nodes mapping is a hash table that maps from the fully qualified URL of the node, to the package_id and package_key of the package instance mounted on the node. A lookup is performed by starting with the full request URI and successively stripping off the rightmost path components until a match is reached. This way the time required to lookup a URL is proportional to the length of the URL, not to the -number of entries in the mapping.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-req-env"></a>Request Environment</h3></div></div></div><p>The request environment is managed by the procedure +number of entries in the mapping.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-design-req-env"></a>Request Environment</h3></div></div></div> + + + +<p>The request environment is managed by the procedure <span class="strong"><strong>ad_conn</strong></span>. Variables can be set and retrieved through use of the ad_conn procedure. The following variables are available for public use. If the ad_conn procedure doesn't recognize a variable being passed to it for a lookup, it tries to get a value using ns_conn. This guarantees that -ad_conn subsumes the functionality of ns_conn.</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="0"><colgroup><col class="c1"><col class="c2"></colgroup><tbody><tr><td colspan="2"><span class="strong"><strong>Request processor</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn urlv]</code> </td><td valign="top">A list containing each element of the URL</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn url]</code> </td><td valign="top">The URL associated with the request.</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn query]</code> </td><td valign="top">The portion of the URL from the ? on (i.e. GET +ad_conn subsumes the functionality of ns_conn.</p> + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="0"><colgroup><col class="c1"><col class="c2"></colgroup><tbody><tr><td colspan="2"><span class="strong"><strong>Request processor</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn urlv]</code> </td><td valign="top">A list containing each element of the URL</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn url]</code> </td><td valign="top">The URL associated with the request.</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn query]</code> </td><td valign="top">The portion of the URL from the ? on (i.e. GET variables) associated with the request.</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn file]</code> </td><td valign="top">The filepath including filename of the file being served</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn request]</code> </td><td valign="top">The number of requests since the server was last started</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn start_clicks]</code> </td><td valign="top">The system time when the RP starts handling the request</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>Session System Variables</strong></span>: set in sec_handler, check security with ad_validate_security_info</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn session_id]</code> </td><td valign="top">The unique session_id coming from the sequence <code class="computeroutput">sec_id_seq</code></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn user_id]</code> </td><td valign="top">User_id of a person if the person is logged in. Otherwise, it is blank</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn sec_validated]</code> </td><td valign="top">This becomes "secure" when the connection uses SSL</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>Database API</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn db,handles]</code> </td><td valign="top">What are the list of handles available to AOL?</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn db,n_handles_used]</code> </td><td valign="top">How many database handles are currently used?</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn db,last_used]</code> </td><td valign="top">Which database handle did we use last?</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn db,transaction_level,$db]</code> </td><td valign="top">Specifies what transaction level we are in</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn db,db_abort_p,$dbh]</code> </td><td valign="top">Whether the transaction is aborted</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>APM</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn xml_loaded_p]</code> </td><td valign="top">Checks whether the XML parser is loaded so that it only gets loaded once. Set in apm_load_xml_packages</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>Packages</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn package_id]</code> </td><td valign="top">The package_id of the package associated with the URL.</td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn package_url]</code> </td><td valign="top">The URL on which the package is mounted.</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>Miscellaneous</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn system_p]</code> </td><td valign="top">If true then the request has been made to one of the special directories specified in the config file (somewhere), and no authentication or -authorization has been performed.</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>Documentation</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn api_page_documentation_mode_p]</code> </td><td valign="top"> </td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr><tr><td width="40%" align="left">Request Processor Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Documenting Tcl Files: Page Contracts and Libraries</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +authorization has been performed.</td></tr><tr><td colspan="2"> </td></tr><tr><td colspan="2"><span class="strong"><strong>Documentation</strong></span></td></tr><tr><td valign="top"><code class="computeroutput">[ad_conn api_page_documentation_mode_p]</code> </td><td valign="top"> </td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tcl-doc.html">Next</a></td></tr><tr><td width="40%" align="left">Request Processor Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Documenting Tcl Files: Page Contracts and Libraries</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/rp-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/rp-requirements.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="rp-design" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="rp-requirements" id="rp-requirements"></a>Request Processor Requirements</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="rp-requirements" id="rp-requirements"></a>Request Processor Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. +Schloming</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="rp-requirements-intro" id="rp-requirements-intro"></a>Introduction</h3></div></div></div><p>The following is a requirements document for the OpenACS 4.0 request processor. The major enhancements in the 4.0 version Index: openacs-4/packages/acs-core-docs/www/rp-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/rp-requirements.html,v diff -u -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/rp-requirements.html 7 Aug 2017 23:47:52 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/rp-requirements.html 8 Nov 2017 09:42:12 -0000 1.35 @@ -1,26 +1,118 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Request Processor Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="security-notes.html" title="Security Notes"><link rel="next" href="rp-design.html" title="Request Processor Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rp-requirements"></a>Request Processor Requirements</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-intro"></a>Introduction</h3></div></div></div><p>The following is a requirements document for the OpenACS 4.0 request +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Request Processor Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="security-notes.html" title="Security Notes"><link rel="next" href="rp-design.html" title="Request Processor Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="rp-requirements"></a>Request Processor Requirements</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-intro"></a>Introduction</h3></div></div></div> + + + +<p>The following is a requirements document for the OpenACS 4.0 request processor. The major enhancements in the 4.0 version include a more sophisticated directory mapping system that allows package pageroots to be mounted at arbitrary urls, and tighter integration with the database to allow -for flexible user controlled url structures, and subsites.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-vision"></a>Vision Statement</h3></div></div></div><p>Most web servers are designed to serve pages from exactly one static +for flexible user controlled url structures, and subsites.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-vision"></a>Vision Statement</h3></div></div></div> + + + +<p>Most web servers are designed to serve pages from exactly one static pageroot. This restriction can become cumbersome when trying to build a web -toolkit full of reusable and reconfigurable components.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-system-overview"></a>System Overview</h3></div></div></div><p>The request processor's functionality can be split into two main -pieces.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Set up the environment in which a server side script expects to run. This -includes things like:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Initialize common variables associated with a request.</p></li><li class="listitem"><p>Authenticate the connecting party.</p></li><li class="listitem"><p>Check that the connecting party is authorized to proceed with the -request.</p></li><li class="listitem"><p>Invoke any filters associated with the request URI.</p></li></ul></div></li><li class="listitem"><p>Determine to which entity the request URI maps, and deliver the content +toolkit full of reusable and reconfigurable components.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-system-overview"></a>System Overview</h3></div></div></div> + + + +<p>The request processor's functionality can be split into two main +pieces.</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> +<p>Set up the environment in which a server side script expects to run. This +includes things like:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p>Initialize common variables associated with a request.</p> +</li><li class="listitem"> +<p>Authenticate the connecting party.</p> +</li><li class="listitem"> +<p>Check that the connecting party is authorized to proceed with the +request.</p> +</li><li class="listitem"> +<p>Invoke any filters associated with the request URI.</p> +</li></ul></div> + +</li><li class="listitem"> +<p>Determine to which entity the request URI maps, and deliver the content provided by this entity. If this entity is a proc, then it is invoked. If this entitty is a file then this step involves determining the file type, and the manner in which the file must be processed to produce content appropriate for the connecting party. Eventually this may also require determining the capabilities of the connecting browser and choosing the most appropriate form -for the delivered content.</p></li></ol></div><p>It is essential that any errors that occur during the above steps be -reported to developers in an easily decipherable manner.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-links"></a>Related Links</h3></div></div></div><p><a class="xref" href="rp-design.html" title="Request Processor Design">OpenACS 4 Request Processor Design</a></p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-req"></a>Requirements</h3></div></div></div><p><span class="strong"><strong>10.0 Multiple Pageroots</strong></span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>10.10</strong></span> Pageroots may be combined into one URL space.</p><p><span class="strong"><strong>10.20</strong></span> Pageroots may be mounted at more than one location in the URL -space.</p></blockquote></div><p><span class="strong"><strong>20.0 Application Context</strong></span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>20.10</strong></span> The request processor must be able to determine a primary context +for the delivered content.</p> +</li></ol></div> + +<p>It is essential that any errors that occur during the above steps be +reported to developers in an easily decipherable manner.</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-links"></a>Related Links</h3></div></div></div> + + + +<p><a class="xref" href="rp-design.html" title="Request Processor Design">OpenACS 4 Request Processor Design</a></p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="rp-requirements-req"></a>Requirements</h3></div></div></div> + + + +<p><span class="strong"><strong>10.0 Multiple Pageroots</strong></span></p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="strong"><strong>10.10</strong></span> Pageroots may be combined into one URL space.</p> + +<p><span class="strong"><strong>10.20</strong></span> Pageroots may be mounted at more than one location in the URL +space.</p> +</blockquote></div> + +<p><span class="strong"><strong>20.0 Application Context</strong></span></p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="strong"><strong>20.10</strong></span> The request processor must be able to determine a primary context or state associated with a pageroot based on it's location within the URL -space.</p></blockquote></div><p><span class="strong"><strong>30.0 Authentication</strong></span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>30.10</strong></span> The request processor must be able to verify that the connecting -browser actually represents the party it claims to represent.</p></blockquote></div><p><span class="strong"><strong>40.0 Authorization</strong></span></p><div class="blockquote"><blockquote class="blockquote"><p><span class="strong"><strong>40.10</strong></span> The request processor must be able to verify that the party the -connecting browser represents is allowed to make the request.</p></blockquote></div><p><span class="strong"><strong>50.0 Scalability</strong></span></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr><tr><td width="40%" align="left">Security Notes </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Request Processor Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +space.</p> +</blockquote></div> + +<p><span class="strong"><strong>30.0 Authentication</strong></span></p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="strong"><strong>30.10</strong></span> The request processor must be able to verify that the connecting +browser actually represents the party it claims to represent.</p> +</blockquote></div> + +<p><span class="strong"><strong>40.0 Authorization</strong></span></p> + +<div class="blockquote"><blockquote class="blockquote"> +<p><span class="strong"><strong>40.10</strong></span> The request processor must be able to verify that the party the +connecting browser represents is allowed to make the request.</p> +</blockquote></div> + +<p><span class="strong"><strong>50.0 Scalability</strong></span></p> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-notes.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-design.html">Next</a></td></tr><tr><td width="40%" align="left">Security Notes </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Request Processor Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/security-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/security-design.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/security-design.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="security-notes" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="security-design" id="security-design"></a>Security Design</h2></div></div></div><div class="authorblurb"> -<p>By Richard Li and Archit Shah</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="security-design" id="security-design"></a>Security Design</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Richard Li and Archit +Shah</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="security-design-essentials" id="security-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"><li class="listitem"><p><a class="xref" href="security-requirements" title="Security Requirements">OpenACS 4 Security Requirements</a></p></li></ul></div> </div><div class="sect2"> Index: openacs-4/packages/acs-core-docs/www/security-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-design.html,v diff -u -r1.36 -r1.37 --- openacs-4/packages/acs-core-docs/www/security-design.html 7 Aug 2017 23:47:52 -0000 1.36 +++ openacs-4/packages/acs-core-docs/www/security-design.html 8 Nov 2017 09:42:12 -0000 1.37 @@ -1,51 +1,144 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="security-requirements.html" title="Security Requirements"><link rel="next" href="security-notes.html" title="Security Notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-design"></a>Security Design</h2></div></div></div><div class="authorblurb"><p>By Richard Li and Archit Shah</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="security-requirements.html" title="Security Requirements">OpenACS 4 Security Requirements</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-intro"></a>Introduction</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Design</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="security-requirements.html" title="Security Requirements"><link rel="next" href="security-notes.html" title="Security Notes"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-design"></a>Security Design</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By Richard Li and Archit Shah</p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-essentials"></a>Essentials</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="security-requirements.html" title="Security Requirements">OpenACS 4 Security Requirements</a></p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-intro"></a>Introduction</h3></div></div></div> + + +<p> This document explains security model design for OpenACS 4. The security system with the OpenACS core must authenticate users in both secure and insecure environments. In addition, this subsystem provides sessions on top of the stateless HTTP protocol. This system also provides session level properties as a generic service to the rest of the OpenACS. -</p><p>The atoms used in the implementation:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Cookies: <a class="ulink" href="http://web.mit.edu/rfc/rfc2109.txt" target="_top">RFC 2109, HTTP -State Management Mechanism</a> </p><p>Cookies provide client side state. They are used to identify the +</p> + +<p>The atoms used in the implementation:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Cookies: <a class="ulink" href="http://web.mit.edu/rfc/rfc2109.txt" target="_top">RFC 2109, HTTP +State Management Mechanism</a> </p> + +<p>Cookies provide client side state. They are used to identify the user. Expiration of cookies is used to demark the end of a session. -</p></li><li class="listitem"><p>SHA: <a class="ulink" href="http://csrc.nist.gov/fips/fip180-1.txt" target="_top">SHA-1</a> </p><p>This secure hash algorithm enables us to digitally sign cookies +</p></li><li class="listitem"><p>SHA: <a class="ulink" href="http://csrc.nist.gov/fips/fip180-1.txt" target="_top">SHA-1</a> </p> + +<p>This secure hash algorithm enables us to digitally sign cookies which guarantee that they have not been tampered with. It is also used to hash passwords. -</p></li><li class="listitem"><p>SSL with server authentication: <a class="ulink" href="http://home.netscape.com/eng/ssl3/ssl-toc.html" target="_top">SSL v3</a> </p><p>SSL provides the client with a guarantee that the server is +</p></li><li class="listitem"><p>SSL with server authentication: <a class="ulink" href="http://home.netscape.com/eng/ssl3/ssl-toc.html" target="_top">SSL v3</a> </p> + +<p>SSL provides the client with a guarantee that the server is actually the server it is advertised as being. It also provides a secure transport. -</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-design"></a>Design</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="sessions"></a>Sessions</h4></div></div></div><p> +</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-design"></a>Design</h3></div></div></div> + + + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="sessions"></a>Sessions</h4></div></div></div> + + +<p> A session is defined as a series of clicks in which no two clicks are separated by more than some constant. This constant is the parameter SessionTimeout. Using the expiration time on the signatures of the signed cookies, we can verify when the cookie was issued and determine if two requests are part of the same session. It is important to note that the expiration time set in the cookie protocol is not trusted. Only the time inserted by the signed cookie mechanism is trusted. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="authentication"></a>Authentication</h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="authentication"></a>Authentication</h4></div></div></div> + + +<p> Two levels of access can be granted: insecure and secure. This grant lasts for the remainder of the particular session. Secure authentication tokens are only issued over secured connections. -</p><p>One consequence of this security design is that secure tokens are not +</p> + +<p>One consequence of this security design is that secure tokens are not automatically issued to users who authenticate themselves over insecure connections. This means that users will need to reauthenticate themselves -over SSL when performing some action that requires secure authentication.</p><p>Although this makes the site less user friendly, this design significantly +over SSL when performing some action that requires secure authentication.</p> + +<p>Although this makes the site less user friendly, this design significantly increases the security of the system because this insures that the authentication tokens presented to a secure section of the web site were not sniffed. The system is not entirely secure, since the actual authentication password can be sniffed from the system, after which the sniffer can apply for a secure authentication token. However, the basic architecture here lays the foundation for a secure system and can be easily adapted to a more secure -authentication system by forcing all logins to occur over HTTPS.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="authentication-details"></a>Details</h4></div></div></div><p>The authentication system issues up to four signed cookies (see below), -with each cookie serving a different purpose. These cookies are:</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>name</strong></span></td><td><span class="strong"><strong>value</strong></span></td><td><span class="strong"><strong>max-age</strong></span></td><td><span class="strong"><strong>secure?</strong></span></td></tr><tr><td>ad_session_id</td><td>session_id,user_id</td><td>SessionTimeout</td><td>no</td></tr><tr><td>ad_user_login</td><td>user_id</td><td>Infinity</td><td>no</td></tr><tr><td>ad_user_login_secure</td><td>user_id,random</td><td>Infinity</td><td>yes</td></tr><tr><td>ad_secure_token</td><td>session_id,user_id,random</td><td>SessionLifetime</td><td>yes</td></tr></tbody></table></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>ad_session_id</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>reissued on any hit separated by more than SessionRenew seconds from the -previous hit that received a cookie</p></li><li class="listitem"><p>is valid only for SessionTimeout seconds</p></li><li class="listitem"><p>is the canonical source for the session ID in ad_conn</p></li></ul></div></li><li class="listitem"><p>ad_user_login</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>is used for permanent logins</p></li></ul></div></li><li class="listitem"><p>ad_user_login_secure</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>is used for permanent secure logins</p></li><li class="listitem"><p>contains random garbage (ns_time) to prevent attack against the secure -hash</p></li></ul></div></li><li class="listitem"><p>ad_secure_token -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>is a session-level cookie from the browser's standpoint</p></li><li class="listitem"><p>its signature expires in SessionLifetime seconds</p></li><li class="listitem"><p>contains random garbage (ns_time) to prevent attack against the secure -hash</p></li><li class="listitem"><p>user_id is extraneous</p></li></ul></div></li></ul></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="authentication-process"></a>Authentication Process</h4></div></div></div><p>The Tcl function (<code class="computeroutput">sec_handler</code>) is called by the request +authentication system by forcing all logins to occur over HTTPS.</p> + + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="authentication-details"></a>Details</h4></div></div></div> + + +<p>The authentication system issues up to four signed cookies (see below), +with each cookie serving a different purpose. These cookies are:</p> + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>name</strong></span></td><td><span class="strong"><strong>value</strong></span></td><td><span class="strong"><strong>max-age</strong></span></td><td><span class="strong"><strong>secure?</strong></span></td></tr><tr><td>ad_session_id</td><td>session_id,user_id</td><td>SessionTimeout</td><td>no</td></tr><tr><td>ad_user_login</td><td>user_id</td><td>Infinity</td><td>no</td></tr><tr><td>ad_user_login_secure</td><td>user_id,random</td><td>Infinity</td><td>yes</td></tr><tr><td>ad_secure_token</td><td>session_id,user_id,random</td><td>SessionLifetime</td><td>yes</td></tr></tbody></table></div> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>ad_session_id</p> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>reissued on any hit separated by more than SessionRenew seconds from the +previous hit that received a cookie</p></li><li class="listitem"><p>is valid only for SessionTimeout seconds</p></li><li class="listitem"><p>is the canonical source for the session ID in ad_conn</p></li></ul></div> + + +</li><li class="listitem"><p>ad_user_login</p> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>is used for permanent logins</p></li></ul></div> + + +</li><li class="listitem"><p>ad_user_login_secure</p> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>is used for permanent secure logins</p></li><li class="listitem"><p>contains random garbage (ns_time) to prevent attack against the secure +hash</p></li></ul></div> + + +</li><li class="listitem"><p>ad_secure_token +</p> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>is a session-level cookie from the browser's standpoint</p></li><li class="listitem"><p>its signature expires in SessionLifetime seconds</p></li><li class="listitem"><p>contains random garbage (ns_time) to prevent attack against the secure +hash</p></li><li class="listitem"><p>user_id is extraneous</p></li></ul></div> +</li></ul></div> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="authentication-process"></a>Authentication Process</h4></div></div></div> + + +<p>The Tcl function (<code class="computeroutput">sec_handler</code>) is called by the request processor to authenticate the user. It first checks the <code class="computeroutput">ad_session_id</code> cookie. If there is no valid session in progress, a new session is created with <code class="computeroutput">sec_setup_session</code>. If the user @@ -55,11 +148,20 @@ determined by whether or not the request is on a secure connection. If neither cookie is present, then a session is created without any authentication. If the <code class="computeroutput">ad_session_id</code> cookie is valid, the -user_id and session_id are pulled from it and put into ad_conn.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="secure-connections"></a>Authenticating Secure Connections</h4></div></div></div><p>Secure connections are authenticated slightly differently. The function +user_id and session_id are pulled from it and put into ad_conn.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="secure-connections"></a>Authenticating Secure Connections</h4></div></div></div> + + +<p>Secure connections are authenticated slightly differently. The function <code class="computeroutput">ad_secure_conn_p</code> is used to determine whether or not the URL being accessed is requires a secure login. The function simply checks if the location begins with "https". (This is safe because the location is -set during the server initialization.)</p><p>If secure authentication is required, the <code class="computeroutput">ad_secure_token</code> +set during the server initialization.)</p> + +<p>If secure authentication is required, the <code class="computeroutput">ad_secure_token</code> cookie is checked to make sure its data matches the data stored in <code class="computeroutput">ad_session_id</code>. This is true for all pages except those that are part of the login process. On these pages, the user can not yet have received @@ -70,21 +172,42 @@ browser when the browser exits. Since an attacker could conceivably store the secure cookie in a replay attack (since expiration date is not validated), the data in the secure cookie is never used to set any data in ad_conn; -user_id and session_id is set from the ad_session_id cookie.</p><p>It is important to note that the integrity of secure authentication rests +user_id and session_id is set from the ad_session_id cookie.</p> + +<p>It is important to note that the integrity of secure authentication rests on the two Tcl function <code class="computeroutput">ad_secure_conn_p</code> and <code class="computeroutput">ad_login_page</code>. If <code class="computeroutput">ad_secure_conn_p</code> is false, secure authentication is not required. If <code class="computeroutput">ad_login_page</code> is false, -secure authentication is not required.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="login-process"></a>Login Process</h4></div></div></div><p>The Tcl function <code class="computeroutput">ad_user_login</code> does two things. First it +secure authentication is not required.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="login-process"></a>Login Process</h4></div></div></div> + + +<p>The Tcl function <code class="computeroutput">ad_user_login</code> does two things. First it performs the appropriate manipulation of the permanent login cookies, and then it updates the current session to reflect the new user_id. The -manipulation of the permanent login cookies is based on 3 factors:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>previous login: other user, same user</p></li><li class="listitem"><p>permanent: was a permanent login requested?</p></li><li class="listitem"><p>secure: is this a secure connection?</p></li></ul></div><p> +manipulation of the permanent login cookies is based on 3 factors:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>previous login: other user, same user</p></li><li class="listitem"><p>permanent: was a permanent login requested?</p></li><li class="listitem"><p>secure: is this a secure connection?</p></li></ul></div> + +<p> Both the secure and insecure permanent login cookie can have one of three actions taken on it: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>set: cookie with no expiration is set</p></li><li class="listitem"><p>delete: set to "" with max age of 0, so it is expired -immediately</p></li><li class="listitem"><p>nothing: if the cookie is present, it remains</p></li></ul></div><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>set: cookie with no expiration is set</p></li><li class="listitem"><p>delete: set to "" with max age of 0, so it is expired +immediately</p></li><li class="listitem"><p>nothing: if the cookie is present, it remains</p></li></ul></div> + +<p> The current state of the permanent login cookies is not taken into account when determining the appropriate action. -</p><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>previous login state</strong></span></td><td><span class="strong"><strong>permanent login requested</strong></span></td><td><span class="strong"><strong>secure connection</strong></span></td><td><span class="strong"><strong>action on insecure</strong></span></td><td><span class="strong"><strong>action on secure</strong></span></td></tr><tr><td>other</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>same</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>other</td><td>y</td><td>n</td><td>set</td><td>delete</td></tr><tr><td>same</td><td>y</td><td>n</td><td>set</td><td>nothing</td></tr><tr><td>same</td><td>n</td><td>y</td><td>nothing</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>y</td><td>delete</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr><tr><td>same</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr></tbody></table></div><p><code class="computeroutput">ad_user_login</code> +</p> +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>previous login state</strong></span></td><td><span class="strong"><strong>permanent login requested</strong></span></td><td><span class="strong"><strong>secure connection</strong></span></td><td><span class="strong"><strong>action on insecure</strong></span></td><td><span class="strong"><strong>action on secure</strong></span></td></tr><tr><td>other</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>same</td><td>y</td><td>y</td><td>set</td><td>set</td></tr><tr><td>other</td><td>y</td><td>n</td><td>set</td><td>delete</td></tr><tr><td>same</td><td>y</td><td>n</td><td>set</td><td>nothing</td></tr><tr><td>same</td><td>n</td><td>y</td><td>nothing</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>y</td><td>delete</td><td>delete</td></tr><tr><td>other</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr><tr><td>same</td><td>n</td><td>n</td><td>delete</td><td>delete</td></tr></tbody></table></div> + +<p><code class="computeroutput">ad_user_login</code> calls<code class="computeroutput">sec_setup_session</code> which actually calls <code class="computeroutput">sec_generate_session_id_cookie</code> to generate the new cookie with refer to the appropriate user_id. If the connection is secure @@ -96,30 +219,57 @@ <code class="computeroutput">sec_setup_session</code> call <code class="computeroutput">sec_generate_session_id_cookie</code>. -</p><p><code class="computeroutput">ad_user_logout</code> logs the user out by deleting all 4 cookies -that are used by the authentication system.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-creation"></a>Session Creation</h4></div></div></div><p>The creation and setup of sessions is handled in +</p> + +<p><code class="computeroutput">ad_user_logout</code> logs the user out by deleting all 4 cookies +that are used by the authentication system.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-creation"></a>Session Creation</h4></div></div></div> + + +<p>The creation and setup of sessions is handled in <code class="computeroutput">sec_setup_session</code>, which is called either to create a new session from <code class="computeroutput">sec_handler</code> or from <code class="computeroutput">ad_user_login</code> when there is a change in authorization level. The session management code must do two things: insure that session-level data does not float between users, and update the users table which has columns for <code class="computeroutput">n_sessions</code>, <code class="computeroutput">last_visit</code>, and -<code class="computeroutput">second_to_last_visit</code>.</p><p>If there is no session already setup on this hit, a new session is +<code class="computeroutput">second_to_last_visit</code>.</p> + +<p>If there is no session already setup on this hit, a new session is created. This happens when <code class="computeroutput">sec_setup_session</code> is called from <code class="computeroutput">sec_handler</code>. If the login is from a user to another user, a new session is created, otherwise, the current session is continued, simply with a higher authorization state. This allows for data -associated with a session to be carried over when a user logs in.</p><p>The users table is updated by +associated with a session to be carried over when a user logs in.</p> + +<p>The users table is updated by <code class="computeroutput">sec_update_user_session_info</code> which is called when an existing session is assigned a non-zero user_id, or when a session is -created with a non-zero user_id.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="passwords"></a>Passwords</h4></div></div></div><p><code class="computeroutput">ad_user_login</code> assumes a password check has already been +created with a non-zero user_id.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="passwords"></a>Passwords</h4></div></div></div> + + +<p><code class="computeroutput">ad_user_login</code> assumes a password check has already been performed (this will change in the future). The actual check is done by <code class="computeroutput">ad_check_password</code>. The database stores a salt and a hash of the password concatenated with the salt. Updating the password (<code class="computeroutput">ad_change_password</code>) simply requires getting a new salt (ns_time) concatenating and rehashing. Both the salt and the hashed password -field are updated.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="performance-enhancements"></a>Performance Enhancements</h4></div></div></div><p>A session is labeled by a session_id sequence. Creating a session merely +field are updated.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="performance-enhancements"></a>Performance Enhancements</h4></div></div></div> + + +<p>A session is labeled by a session_id sequence. Creating a session merely requires incrementing the session_id sequence. We do two things to improve the performance of this process. First, sequence values are precomputed and cached in the Oracle SGA. In addition, sequence values are incremented by 100 with each @@ -135,14 +285,23 @@ db and <code class="computeroutput">tcl_max_value</code> is incremented by 100. This is done on a per-thread basis so that no locking is required. -</p><p>In addition, two procedures are dynamically generated at startup in +</p> + +<p>In addition, two procedures are dynamically generated at startup in <code class="computeroutput">security-init.tcl</code>. These two procedures use <code class="computeroutput">ad_parameter</code> to obtain the constant value of a given parameter; these values are used to dynamically generate a procedure that returns a constant. This approach avoids (relatively) expensive calls to <code class="computeroutput">ad_parameter</code> in <code class="computeroutput">sec_handler</code>. The impact of this approach is that these parameters cannot be dynamically changed at runtime -and require a server restart.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-properties"></a>Session Properties</h4></div></div></div><p> +and require a server restart.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-properties"></a>Session Properties</h4></div></div></div> + + +<p> Session properties are stored in a single table that maps session IDs to named session properties and values. This table is periodically purged. For maximum performance, the table is created with nologging turned on and new @@ -151,37 +310,62 @@ sessions whose first hit was more than SessionLifetime seconds (1 week by default) ago. Session properties are removed through that same process with cascading delete. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="secure-session-properties"></a>Secure Session Properties</h4></div></div></div><p>Session properties can be set as secure. In this case, +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="secure-session-properties"></a>Secure Session Properties</h4></div></div></div> + + +<p>Session properties can be set as secure. In this case, <code class="computeroutput">ad_set_client_property</code> will fail if the connection is not secure. <code class="computeroutput">ad_get_client_property</code> will behave as if the property -had not been set if the property was not set securely.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="digital-signatures"></a>Digital Signatures & Signed Cookies</h4></div></div></div><p> +had not been set if the property was not set securely.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="digital-signatures"></a>Digital Signatures & Signed Cookies</h4></div></div></div> + + +<p> Signed cookies are implemented using the generic secure digital signature mechanism. This mechanism guarantees that the user can not tamper with (or construct a value of his choice) without detection. In addition, it provides the optional facility of timing out the signature so it is valid for only a certain period of time. This works by simply including an expiration time as part of the value that is signed. -</p><p>The signature produced by <code class="computeroutput">ad_sign</code> is the Tcl list of +</p> + +<p>The signature produced by <code class="computeroutput">ad_sign</code> is the Tcl list of <code class="computeroutput">token_id,expire_time,hash</code>, where hash = SHA1(value,token_id,expire_time,secret_token). The secret_token is a forty character randomly generated string that is never sent to any user agent. The -scheme consists of one table:</p><pre class="programlisting"> +scheme consists of one table:</p> + + +<pre class="programlisting"> + create table secret_tokens ( token_id integer constraint secret_tokens_token_id_pk primary key, token char(40), token_timestamp sysdate ); -</pre><p><code class="computeroutput">ad_verify_signature</code> takes a value and a signature and +</pre> + + +<p><code class="computeroutput">ad_verify_signature</code> takes a value and a signature and verifies that the signature was generated using that value. It works simply by taking the token_id and expire_time from the signature, and regenerating the hash using the supplied value and the secret_token corresponding to the token_id. This regenerated hash is compared to the hash extracted from the supplied signature. The expire_time is also verified to be greater than the current time. An expire_time of 0 is also allowed, as it indicates no time -out on the signature.</p><p>Signed cookies include in their RFC2109 VALUE field a Tcl list of the +out on the signature.</p> + +<p>Signed cookies include in their RFC2109 VALUE field a Tcl list of the value and the signature. In addition to the expiration of the digital signature, RFC 2109 specifies an optional max age that is returned to the client. For most cookies, this max age matches the expiration date of the @@ -190,11 +374,18 @@ exits." Because we can not trust the client to do this, we must specify a timeout for the signature. The SessionLifetime parameter is used for this purpose, as it represents the maximum possible lifetime of a single -session.</p><p>RFC 2109 specifies this optional "secure" parameter which +session.</p> + +<p>RFC 2109 specifies this optional "secure" parameter which mandates that the user-agent use "secure means" to contact the server when transmitting the cookie. If a secure cookie is returned to the client over https, then the cookie will never be transmitted over insecure -means.</p><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="signature-performance"></a>Performance</h5></div></div></div><p>Performance is a key goal of this implementation of signed cookies. To +means.</p> + +<div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="signature-performance"></a>Performance</h5></div></div></div> + + +<p>Performance is a key goal of this implementation of signed cookies. To maximize performance, we will use the following architecture. At the lowest level, we will use the <code class="computeroutput">secret_tokens</code> table as the canonical set of secret tokens. This table is necessary for multiple servers to maintain @@ -203,94 +394,219 @@ <code class="computeroutput">secret_tokens</code>. When a new signed cookie is requested, a random token_id is returned out of the entire set of cached token_ids. In addition, a thread-persistent cache called tcl_secret_tokens is maintained on a -per-thread basis.</p><p>Thus, the L2 ns_cache functions as a server-wide LRU cache that has a -minimum of 100 tokens in it. The cache has a dual purpose:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>LRU cache</strong></span> Note that cache misses will only occur in the +per-thread basis.</p> + +<p>Thus, the L2 ns_cache functions as a server-wide LRU cache that has a +minimum of 100 tokens in it. The cache has a dual purpose:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>LRU cache</strong></span> Note that cache misses will only occur in the multiple server case, where a user agent may have a signature guaranteed by a secret token issued by another server in the cluster.</p></li><li class="listitem"><p><span class="strong"><strong>signature cache</strong></span> Since the cache always maintains a minimum of 100 (set by a parameter) tokens populated at startup, it can be -used to provide a random token for signature purposes.</p></li></ul></div><p> +used to provide a random token for signature purposes.</p></li></ul></div> + +<p> The per-thread cache functions as an L1 cache that indiscriminately caches all secret tokens. Note that this is <span class="strong"><strong>not</strong></span> an LRU cache because there is no cache eviction policy per se -- the cache is cleared when the thread is destroyed by AOLserver. -</p></div><div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="signature-security"></a>Security</h5></div></div></div><p>Storing information on a client always presents an additional security -risk.</p><p>Since we are only validating the information and not trying to protect it +</p> + +</div> + +<div class="sect4"><div class="titlepage"><div><div><h5 class="title"><a name="signature-security"></a>Security</h5></div></div></div> + + +<p>Storing information on a client always presents an additional security +risk.</p> + +<p>Since we are only validating the information and not trying to protect it as a secret, we don't use salt. Cryptographic salt is useful if you are -trying to protect information from being read (e.g., hashing passwords).</p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="external-ssl"></a>External SSL</h4></div></div></div><p> +trying to protect information from being read (e.g., hashing passwords).</p> + +</div> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="external-ssl"></a>External SSL</h4></div></div></div> + + +<p> External SSL mechanisms (firewall, dedicated hardware, etc.) can be used by creating two pools of AOLservers. In one pool the servers should be configured with the location parameter of nssock module set to "https://yourservername". The servers in the other pool are configured as normal. The external SSL agent should direct SSL queries to the pool of secure servers, and it should direct non-SSL queries to the insecure servers. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="PRNG"></a>PRNG</h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="PRNG"></a>PRNG</h4></div></div></div> + + +<p> The pseudorandom number generator depends primarily on ns_rand, but is also seeded with ns_time and the number of page requests served since the server was started. The PRNG takes the SHA1(seed,ns_rand,ns_time,requests,clicks), and saves the first 40 bits as the seed for the next call to the PRNG in a thread-persistent global variable. The remaining 120 bits are rehashed to produce 160 bits of output. -</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-api"></a>API</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="login-password-api"></a>Login/Password</h4></div></div></div><p> +</p> + +</div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-api"></a>API</h3></div></div></div> + + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="login-password-api"></a>Login/Password</h4></div></div></div> + + +<p> <span class="strong"><strong>ad_user_login <span class="emphasis"><em>user_id</em></span></strong></span> Logs the user in as user <span class="emphasis"><em>user_id</em></span>. Optional forever flag determines whether or not permanent cookies are issued. -</p><p><span class="strong"><strong>ad_user_logout</strong></span> Logs the user out.</p><p><span class="strong"><strong>ad_check_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>password</em></span></strong></span> -returns 0 or 1.</p><p><span class="strong"><strong>ad_change_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>new -password</em></span></strong></span></p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="signature-api"></a>Digital Signatures and Signed Cookies</h4></div></div></div><p> +</p> + +<p><span class="strong"><strong>ad_user_logout</strong></span> Logs the user out.</p> +<p><span class="strong"><strong>ad_check_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>password</em></span></strong></span> +returns 0 or 1.</p> + +<p><span class="strong"><strong>ad_change_password <span class="emphasis"><em>user_id</em></span> <span class="emphasis"><em>new +password</em></span></strong></span></p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="signature-api"></a>Digital Signatures and Signed Cookies</h4></div></div></div> + + +<p> <span class="strong"><strong>ad_sign <span class="emphasis"><em>value</em></span></strong></span> Returns the digital signature of this value. Optional parameters allow for the specification of the <span class="emphasis"><em>secret</em></span> used, the <span class="emphasis"><em>token_id</em></span> used and the <span class="emphasis"><em>max_age</em></span> for the signature. <span class="strong"><strong>ad_verify_signature <span class="emphasis"><em>value</em></span> <span class="emphasis"><em>signature</em></span></strong></span>Returns 1 or 0 indicating whether or not the signature matches the value specified. The <span class="emphasis"><em>secret</em></span> parameter allows for specification of a different secret -token to be used. </p><p> +token to be used. </p> + +<p> <span class="strong"><strong>ad_set_signed_cookie <span class="emphasis"><em>name</em></span> <span class="emphasis"><em>data</em></span></strong></span> Sets a -signed cookie <span class="emphasis"><em>name</em></span> with value <span class="emphasis"><em>data</em></span>. </p><p><span class="strong"><strong>ad_get_signed_cookie <span class="emphasis"><em>name</em></span></strong></span> Gets the signed cookie +signed cookie <span class="emphasis"><em>name</em></span> with value <span class="emphasis"><em>data</em></span>. </p> + +<p><span class="strong"><strong>ad_get_signed_cookie <span class="emphasis"><em>name</em></span></strong></span> Gets the signed cookie <span class="emphasis"><em>name</em></span>. It raises an error if the cookie has been tampered with, or if -its expiration time has passed.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-property-api"></a>Session Properties</h4></div></div></div><p><span class="strong"><strong>ad_set_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span> +its expiration time has passed.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-property-api"></a>Session Properties</h4></div></div></div> + + +<p><span class="strong"><strong>ad_set_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span> <span class="emphasis"><em>data</em></span></strong></span> Sets a session property with <span class="emphasis"><em>name</em></span> to value <span class="emphasis"><em>data</em></span> for the module <span class="emphasis"><em>module</em></span>. The optional secure flag specifies the property should only be set if the client is authorized for secure access (<code class="computeroutput">ad_secure_conn_p</code> is true). There is also an optional -<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p><p><span class="strong"><strong>ad_get_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span> +<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p> + +<p><span class="strong"><strong>ad_get_client_property <span class="emphasis"><em>module</em></span> <span class="emphasis"><em>name</em></span> <span class="emphasis"><em>data</em></span></strong></span> Gets a session property with <span class="emphasis"><em>name</em></span> to for the module <span class="emphasis"><em>module</em></span>. The optional secure flag specifies the property should only be retrieved if the client is authorized for secure access (<code class="computeroutput">ad_secure_conn_p</code> is true). There is also an optional -<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="parameters"></a>Parameters</h4></div></div></div><p> +<span class="emphasis"><em>session_id</em></span> flag to access data from sessions other than the current one.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="parameters"></a>Parameters</h4></div></div></div> + + +<p> <span class="strong"><strong>SessionTimeout</strong></span> the maximum time in seconds (default 1200) -between requests that are part of the same session </p><p><span class="strong"><strong>SessionRenew</strong></span> the time in seconds (default 300) between +between requests that are part of the same session </p> + +<p><span class="strong"><strong>SessionRenew</strong></span> the time in seconds (default 300) between reissue of the session cookie. The minimum time that can pass after a session cookie is issued and before it is rejected is (SessionTimeout - SessionRenew). This parameter is used so that only one session_id cookie is set on a single page even if there are multiple images that are being -downloaded.</p><p><span class="strong"><strong>SessionLifetime</strong></span> the maximum possible lifetime of a -session in seconds (default 604800 = 7 days)</p><p><span class="strong"><strong>NumberOfCachedSecretTokens</strong></span> the number of secret tokens to -cache. (default 100)</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-future"></a>Future Improvements</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="PRNG-impl"></a>PRNG implementation</h4></div></div></div><p> +downloaded.</p> + +<p><span class="strong"><strong>SessionLifetime</strong></span> the maximum possible lifetime of a +session in seconds (default 604800 = 7 days)</p> + +<p><span class="strong"><strong>NumberOfCachedSecretTokens</strong></span> the number of secret tokens to +cache. (default 100)</p> + +</div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-future"></a>Future Improvements</h3></div></div></div> + + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="PRNG-impl"></a>PRNG implementation</h4></div></div></div> + + +<p> The pseudorandom number generator used in the OpenACS is cryptographically weak, and depends primarily on the randomness of the <code class="computeroutput">ns_rand</code> function for its randomness. The implementation of the PRNG could be substantially improved. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="ad_user_login"></a><code class="computeroutput">ad_user_login</code></h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="ad_user_login"></a><code class="computeroutput">ad_user_login</code></h4></div></div></div> + + + +<p> Add a password argument. It is non-optimal to make the default behavior to assume that the password was provided. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="secret-tokens"></a>Secret Tokens</h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="secret-tokens"></a>Secret Tokens</h4></div></div></div> + + + +<p> The secret tokens pool is currently static. Ideally, this pool should be changed on a random but regular basis, and the number of secret_tokens increased as the number of users come to the web site. -</p><p>Since the security of the entire system depends on the secret tokens pool, +</p> + +<p>Since the security of the entire system depends on the secret tokens pool, access to the secret tokens table should be restricted and accessible via a strict PL/SQL API. This can be done by revoking standard SQL permissions on the table for the AOLserver user and giving those permissions to a PL/SQL -package.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="robots"></a>Robots</h4></div></div></div><p> +package.</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="robots"></a>Robots</h4></div></div></div> + + +<p> Deferring session to creation until the second hit from a browser seems to be a good way of preventing a lot of overhead processing for robots. If we do this, send cookie on first hit to test if cookies are accepted, then actually allocate on second hit. To preserve a record of the first hit of the session, just include any info about that first hit in the probe cookie sent. Look at how usca_p (user session cookie attempted) is used in OpenACS 3.x ecommerce. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="client-property-future"></a>Client properties</h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="client-property-future"></a>Client properties</h4></div></div></div> + + +<p> Currently there are only session properties. Because sessions have a maximum life, properties have a maximum life. It would be nice to expand the interface to allow for more persistent properties. In the past, there was a @@ -303,7 +619,14 @@ can be shared between concurrent sessions). The applications should have control over the deletion patterns, but should not be able to ignore the amount of data stored. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-information"></a>Session information</h4></div></div></div><p> +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="session-information"></a>Session information</h4></div></div></div> + + +<p> It would be nice to keep some info about sessions: first hit, last hit, and URLs visited come to mind. Both logging and API for accessing this info would be nice. WimpyPoint is an application that already wants to use this @@ -312,15 +635,24 @@ analyzers (leaving it in server memory for applications to access). Putting it into the database at all is probably too big a hammer. Certainly putting it into the database on every hit is too big a hammer. -</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="cookieless-sessions"></a>Cookieless Sessions</h4></div></div></div><p>Two trends drive the requirement for removing cookie dependence. WAP +</p> + +</div> + +<div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="cookieless-sessions"></a>Cookieless Sessions</h4></div></div></div> + + +<p>Two trends drive the requirement for removing cookie dependence. WAP browsers that do not have cookies, and publc perceptions of cookies as an invasion of privacy. The rely on the cookies mechanism in HTTP to distinguish one request from the next, and we trust it to force requests from the same client to carry the same cookie headers. The same thing can be accomplished by personalizing the URLs sent back to each browser. If we can store an identifier in the URL and get it back on the next hit, the sessions system would continue -to work.</p><p>Problems that arise: +to work.</p> +<p>Problems that arise: + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>URL sharing could be dangerous. If I happen to be browsing Amazon while logged in and I email a friend, he could conceivably receive it and follow it before my session has expired, gaining all of the privileges I @@ -331,13 +663,24 @@ Both of these problems can be mitigated by doing detection of cookie support (see the section on robot detection). To help deal with the first problem, One could also make the restriction that secure sessions are only allowed over -cookied HTTP.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-vulnerability"></a>Vulnerability Analysis</h3></div></div></div><p> +cookied HTTP.</p> + +</div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-design-vulnerability"></a>Vulnerability Analysis</h3></div></div></div> + + +<p> This section is not meant to be a comprehensive analysis of the vulnerabilities of the security system. Listed below are possible attack points for the system; these vulnerabilities are currently theoretical in nature. The major cryptographic vulnerability of the system stems from the pseudorandom nature of the random number generators used in the system. -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>Cryptographically weak PRNG</strong></span> see +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>Cryptographically weak PRNG</strong></span> see above.</p></li><li class="listitem"><p><span class="strong"><strong>Dependence on <code class="computeroutput">sample</code> SQL command</strong></span> The list of random token that are placed in the secret tokens cache is randomly chosen by the Oracle @@ -348,4 +691,8 @@ chosen from the cache to be used is chosen by a call to <code class="computeroutput">ns_rand</code>.</p></li><li class="listitem"><p><span class="strong"><strong><code class="computeroutput">ad_secure_conn_p</code></strong></span> As discussed above, the security of the secure sessions authentication system is -dependent upon this function.</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr><tr><td width="40%" align="left">Security Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Security Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +dependent upon this function.</p></li></ul></div> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-notes.html">Next</a></td></tr><tr><td width="40%" align="left">Security Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Security Notes</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/security-notes.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/security-notes.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/security-notes.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="rp-requirements" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="security-notes" id="security-notes"></a>Security Notes</h2></div></div></div><div class="authorblurb"> -<p>By Richard Li</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>The security system was designed for security. Thus, decisions +<a name="security-notes" id="security-notes"></a>Security Notes</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Richard Li</span></p><span style="color: red"></authorblurb></span><p>The security system was designed for security. Thus, decisions requiring trade-offs between ease-of-use and security tend to result in a system that may not be as easy to use but is more secure.</p><div class="sect2"> @@ -68,8 +65,8 @@ </pre><p>The set of string match expressions in the procedure above should be extended appropriately for other registration pages. This procedure does not use <code class="computeroutput">ad_parameter</code> or regular expressions for -performance reasons, as it is called by the request processor.</p><div class="cvstag">($‌Id: security-notes.xml,v 1.7 2014/10/27 -16:39:32 victorg Exp $)</div> +performance reasons, as it is called by the request processor.</p><p><span class="cvstag">($‌Id: security-notes.xml,v 1.7 2014/10/27 +16:39:32 victorg Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/security-notes.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-notes.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/security-notes.html 7 Aug 2017 23:47:52 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/security-notes.html 8 Nov 2017 09:42:12 -0000 1.50 @@ -1,29 +1,48 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Notes</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="security-design.html" title="Security Design"><link rel="next" href="rp-requirements.html" title="Request Processor Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-notes"></a>Security Notes</h2></div></div></div><div class="authorblurb"><p>By Richard Li</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Notes</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="security-design.html" title="Security Design"><link rel="next" href="rp-requirements.html" title="Request Processor Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-notes"></a>Security Notes</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Richard Li</p> +</authorblurb></span> + +<p> The security system was designed for security. Thus, decisions requiring trade-offs between ease-of-use and security tend to result in a system that may not be as easy to use but is more secure. -</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-notes-https-sessions"></a>HTTPS and the sessions system</h3></div></div></div><p> +</p> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-notes-https-sessions"></a>HTTPS and the sessions system</h3></div></div></div> + +<p> + If a user switches to HTTPS after logging into the system via HTTP, the user must obtain a secure token. To insure security, the <span class="emphasis"><em>only way</em></span> to obtain a secure token in the security system is to authenticate yourself via password over an HTTPS connection. Thus, users may need to log on again to a system when switching from HTTP to HTTPS. Note that logging on to a system via HTTPS gives the user both insecure and secure authentication tokens, so switching from HTTPS to HTTP does not require reauthentication. -</p><p>This method of authentication is important in order to establish, in as +</p> + +<p>This method of authentication is important in order to establish, in as strong a manner as possible, the identity of the owner of the secure token. In order for the security system to offer stronger guarantees of someone who issues a secure token, the method of authentication must be as strong as the -method of transmission.</p><p>If a developer truly does not want such a level of protection, this system +method of transmission.</p> + +<p>If a developer truly does not want such a level of protection, this system can be disabled via source code modification only. This can be accomplished by commenting out the following lines in the <code class="computeroutput">sec_handler</code> -procedure defined in <code class="computeroutput">security-procs.tcl</code>:</p><pre class="programlisting"> +procedure defined in <code class="computeroutput">security-procs.tcl</code>:</p> + + +<pre class="programlisting"> + if { [ad_secure_conn_p] && ![ad_login_page] } { set s_token_cookie [ns_urldecode [ad_get_cookie "ad_secure_token"]] @@ -33,10 +52,17 @@ } } -</pre><p>The source code must also be edited if the user login pages have been +</pre> + + +<p>The source code must also be edited if the user login pages have been moved out of an OpenACS system. This information is contained by the -<code class="computeroutput">ad_login_page</code> procedure in <code class="computeroutput">security-procs.tcl</code>:</p><pre class="programlisting"> +<code class="computeroutput">ad_login_page</code> procedure in <code class="computeroutput">security-procs.tcl</code>:</p> + + +<pre class="programlisting"> + ad_proc -private ad_login_page {} { Returns 1 if the page is used for logging in, 0 otherwise. @@ -51,8 +77,16 @@ return 0 } -</pre><p> +</pre> + +<p> The set of string match expressions in the procedure above should be extended appropriately for other registration pages. This procedure does not use <code class="computeroutput">ad_parameter</code> or regular expressions for performance reasons, as -it is called by the request processor. </p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Security Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Request Processor Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +it is called by the request processor. </p> + + + +<p><span class="cvstag">($Id$)</span></p> +</div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="security-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="rp-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Security Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Request Processor Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/security-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/security-requirements.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/security-requirements.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,10 +10,7 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="security-requirements" id="security-requirements"></a>Security -Requirements</h2></div></div></div><div class="authorblurb"> -<p>By Richard Li</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Richard Li</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="security-requirements-intro" id="security-requirements-intro"></a>Introduction</h3></div></div></div><p>This document lists the requirements for the security system for the OpenACS.</p> Index: openacs-4/packages/acs-core-docs/www/security-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/security-requirements.html,v diff -u -r1.36 -r1.37 --- openacs-4/packages/acs-core-docs/www/security-requirements.html 7 Aug 2017 23:47:52 -0000 1.36 +++ openacs-4/packages/acs-core-docs/www/security-requirements.html 8 Nov 2017 09:42:12 -0000 1.37 @@ -1,38 +1,77 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"><link rel="next" href="security-design.html" title="Security Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-requirements"></a>Security Requirements</h2></div></div></div><div class="authorblurb"><p>By Richard Li</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-intro"></a>Introduction</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Security Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="i18n-requirements.html" title="OpenACS Internationalization Requirements"><link rel="next" href="security-design.html" title="Security Design"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="security-requirements"></a>Security Requirements</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By Richard Li</p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-intro"></a>Introduction</h3></div></div></div> + + +<p> This document lists the requirements for the security system for the OpenACS. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-vision"></a>Vision Statement</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-vision"></a>Vision Statement</h3></div></div></div> + + +<p> Virtually all web sites support personalized content based on user identity. The level of personalization may be as simple as displaying the name of the user on certain pages or can be as sophisticated as dynamically recommending sections of site that the user may be interested in based on prior browsing history. In any case, the user's identity must be validated and made available to the rest of the system. In addition, sites such as ecommerce vendors require that the user identity be securely validated. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-system-overview"></a>Security System Overview</h3></div></div></div><p> +</p> +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="security-requirements-system-overview"></a>Security System Overview</h3></div></div></div> + + +<p> The security system consists of a number of subsystems. -</p><p><span class="strong"><strong>Signed Cookies</strong></span></p><p> +</p> + +<p><span class="strong"><strong>Signed Cookies</strong></span></p> + +<p> Cookies play a key role in storing user information. However, since they are stored in plaintext on a user's system, the validity of cookies is an important issue in trusting cookie information. Thus, we want to be able to validate a cookie, but we also want to validate the cookie without a database hit. -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>10.0 Guaranteed Tamper Detection</strong></span> Any tampering of cookie +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>10.0 Guaranteed Tamper Detection</strong></span> Any tampering of cookie data should be easily detectable by the web server.</p></li><li class="listitem"><p><span class="strong"><strong>10.1 Performance and Scalability</strong></span> Validation and verification of the cookie should be easily scalable and should not require a -database query on every hit.</p></li></ul></div><p><span class="strong"><strong>Session Properties</strong></span></p><p> +database query on every hit.</p></li></ul></div> + +<p><span class="strong"><strong>Session Properties</strong></span></p> + +<p> Applications should be able to store session-level properties in a database table. -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>11.0 Storage API</strong></span> Session-level data should be accessible +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>11.0 Storage API</strong></span> Session-level data should be accessible via an API.</p></li><li class="listitem"><p><span class="strong"><strong>11.1 Purge Mechanism</strong></span> An efficient pruning mechanism should be used to prevent old session level properties from filling up the -table.</p></li></ul></div><p><span class="strong"><strong>Login</strong></span></p><p> +table.</p></li></ul></div> + +<p><span class="strong"><strong>Login</strong></span></p> + +<p> The security system should support the concept of persistent user logins. This persistence takes several forms. -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>12.0 Permanent Login</strong></span> Users should be able to maintain a +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>12.0 Permanent Login</strong></span> Users should be able to maintain a permanent user login so that they never need to type their password.</p></li><li class="listitem"><p><span class="strong"><strong>12.1 Session Login</strong></span> The security system should support the concept of a session, with authentication tokens that become invalid after a certain period of time.</p></li><li class="listitem"><p><span class="strong"><strong>12.2 Session Definition</strong></span> A session is a sequence of @@ -42,6 +81,15 @@ user request (including cookies), and in the database. A single user should be able to log in to the system even if the user is sent to a different AOLserver for each step of the login process (e.g., by a load balancer).</p></li><li class="listitem"><p><span class="strong"><strong>12.4 Secure</strong></span> The security system should not store -passwords in clear text in the database.</p></li></ul></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>13.0 SSL Hardware</strong></span> The system must work when the SSL +passwords in clear text in the database.</p></li></ul></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>13.0 SSL Hardware</strong></span> The system must work when the SSL processing occurs outside of the web server (in specialized hardware, in a -firewall, etc.).</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Internationalization Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Security Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +firewall, etc.).</p></li></ul></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="i18n-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="security-design.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Internationalization Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Security Design</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/snapshot-backup.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/snapshot-backup.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/snapshot-backup.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/snapshot-backup.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -35,9 +35,9 @@ </li><li class="listitem"> <p>Setup the export directory; this is the directory where backups will be stored. We recommend the directory <code class="filename">/ora8/m02/oracle-exports</code>.</p><pre class="programlisting"> -[root ~]# <strong class="userinput"><code>mkdir <span class="replaceable"><span class="replaceable">/ora8/m02/</span></span>oracle-exports</code></strong> -[root ~]# <strong class="userinput"><code>chown oracle:dba <span class="replaceable"><span class="replaceable">/ora8/m02/</span></span>oracle-exports</code></strong> -[root ~]# <strong class="userinput"><code>chmod 770 <span class="replaceable"><span class="replaceable">/ora8/m02/</span></span>oracle-exports</code></strong> +[root ~]# <strong class="userinput"><code>mkdir <em class="replaceable"><code>/ora8/m02/</code></em>oracle-exports</code></strong> +[root ~]# <strong class="userinput"><code>chown oracle:dba <em class="replaceable"><code>/ora8/m02/</code></em>oracle-exports</code></strong> +[root ~]# <strong class="userinput"><code>chmod 770 <em class="replaceable"><code>/ora8/m02/</code></em>oracle-exports</code></strong> </pre> </li><li class="listitem"> <p>Now edit <code class="filename">/usr/sbin/export-oracle</code> @@ -88,26 +88,26 @@ </ul></div> </li><li class="listitem"> <p> -<a name="postgres-snapshot-backup" id="postgres-snapshot-backup"></a><strong>PostgreSQL. </strong>Create -a backup file and verify that it was created and has a reasonable -size (several megabytes).</p><pre class="screen"> +<a name="postgres-snapshot-backup" id="postgres-snapshot-backup"></a><strong>PostgreSQL. </strong> Create a backup file and +verify that it was created and has a reasonable size (several +megabytes).</p><pre class="screen"> [root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>pg_dump -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>pg_dump -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>ls -al /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp </code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>ls -al /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp </code></strong> -rw-rw-r-x 1 $OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME 4005995 Feb 21 18:28 /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> [root root]# -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -pg_dump -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable"><span class="replaceable">openacs-dev</span></span> -ls -al /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp -exit</span></span> +<span class="action">su - $OPENACS_SERVICE_NAME +pg_dump -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp <em class="replaceable"><code>openacs-dev</code></em> +ls -al /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp +exit</span> </pre> </li> </ul></div> </li><li class="listitem"> <a name="backup-file-system" id="backup-file-system"></a><p> -<strong>Back up the file system. </strong>Back up +<strong>Back up the file system. </strong> Back up all of the files in the service, including the database backup file but excluding the auto-generated <code class="filename">supervise</code> directory, which is unnecessary and has complicated permissions.</p><p>In the tar command,</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> @@ -123,28 +123,28 @@ backed up by the service owner. These files are autogenerated and we don't break anything by omitting them.</p></li><li class="listitem"><p>The <code class="computeroutput">--file</code> clause specifies the name of the output file to be generated; we manually add the -correct extensions.</p></li><li class="listitem"><p>The last clause, <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/</code>, +correct extensions.</p></li><li class="listitem"><p>The last clause, <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/</code>, specifies the starting point for backup. Tar defaults to recursive backup.</p></li> </ul></div><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>tar -cpsz --exclude /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/supervise \ - --file /var/tmp/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-backup.tar.gz /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>tar -cpsz --exclude /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/supervise \ + --file /var/tmp/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-backup.tar.gz /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/</code></strong> tar: Removing leading `/' from member names [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ </pre> </li><li class="listitem"> <p> <strong>Suffer a catastrophic failure on your production -system. </strong>(We'll simulate this step)</p><pre class="screen"> +system. </strong> (We'll simulate this step)</p><pre class="screen"> [root root]# <strong class="userinput"><code>svc -d /service/$OPENACS_SERVICE_NAME</code></strong> [root root]# <strong class="userinput"><code>mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost</code></strong> [root root]#<strong class="userinput"><code> rm /service/$OPENACS_SERVICE_NAME</code></strong> rm: remove symbolic link `/service/$OPENACS_SERVICE_NAME'? y [root root]# <strong class="userinput"><code>ps -auxw | grep $OPENACS_SERVICE_NAME</code></strong> root 1496 0.0 0.0 1312 252 ? S 16:58 0:00 supervise $OPENACS_SERVICE_NAME -[root root]#<strong class="userinput"><code> kill<span class="replaceable"><span class="replaceable"> 1496</span></span> +[root root]#<strong class="userinput"><code> kill<em class="replaceable"><code> 1496</code></em> </code></strong> [root root]# <strong class="userinput"><code>ps -auxw | grep $OPENACS_SERVICE_NAME</code></strong> [root root]# <strong class="userinput"><code>su - postgres</code></strong> @@ -164,15 +164,15 @@ this with standard backup processes or by keeping copies of the install material (OS CDs, OpenACS tarball and supporting software) and repeating the install guide. Recreate the service user -(<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>).</p></li><li class="listitem"> +(<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>).</p></li><li class="listitem"> <p>Restore the OpenACS files and database backup file.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> [$OPENACS_SERVICE_NAME aolserver]$<strong class="userinput"><code> tar xzf /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME.web</span></span><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <em class="replaceable"><code>$OPENACS_SERVICE_NAME.web</code></em><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre> </li><li class="listitem"> @@ -181,15 +181,15 @@ <p><strong>Oracle. </strong></p><div class="orderedlist"><ol class="orderedlist" type="i"> <li class="listitem"><p>Set up a clean Oracle database user and tablespace with the same names as the ones exported from (<a class="link" href="openacs" title="Prepare Oracle for OpenACS">more information</a>).</p></li><li class="listitem"> -<p>Invoke the import command</p><pre class="screen"><span class="action"><span class="action">imp <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> FILE=/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/nighty_backup.dmp FULL=Y</span></span></pre> +<p>Invoke the import command</p><pre class="screen"><span class="action">imp <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> FILE=/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/nighty_backup.dmp FULL=Y</span></pre> </li> </ol></div> </li><li class="listitem"> <p> -<a name="restore-postgres" id="restore-postgres"></a><strong>Postgres. </strong>If -the database user does not already exist, create it.</p><pre class="screen"> +<a name="restore-postgres" id="restore-postgres"></a><strong>Postgres. </strong> If the database user does +not already exist, create it.</p><pre class="screen"> [root root]# <strong class="userinput"><code>su - postgres</code></strong> -[postgres ~]$ <strong class="userinput"><code>createuser <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[postgres ~]$ <strong class="userinput"><code>createuser <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> Shall the new user be allowed to create databases? (y/n) <strong class="userinput"><code>y</code></strong> Shall the new user be allowed to create more new users? (y/n) <strong class="userinput"><code>y</code></strong> @@ -202,14 +202,14 @@ database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>createdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>createdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> CREATE DATABASE -[$OPENACS_SERVICE_NAME ~]$<strong class="userinput"><code> psql -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME ~]$<strong class="userinput"><code> psql -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-kernel/sql/postgresql/postgresql.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong><span class="emphasis"><em>(many lines omitted)</em></span> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> < /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/<span class="replaceable"><span class="replaceable">database-backup.dmp</span></span> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> < /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/<em class="replaceable"><code>database-backup.dmp</code></em> </code></strong><span class="emphasis"><em>(many lines omitted)</em></span> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>exit</code></strong> [postgres ~]$ <strong class="userinput"><code>exit</code></strong> @@ -219,10 +219,10 @@ </ul></div> </li><li class="listitem"> <p>Activate the service</p><pre class="screen"> -[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [root root]# <strong class="userinput"><code>sleep 10</code></strong> -[root root]# <strong class="userinput"><code>svgroup web /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>svgroup web /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre> </li> Index: openacs-4/packages/acs-core-docs/www/snapshot-backup.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/snapshot-backup.html,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/snapshot-backup.html 7 Aug 2017 23:47:52 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/snapshot-backup.html 8 Nov 2017 09:42:12 -0000 1.15 @@ -1,24 +1,44 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Manual backup and recovery</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="install-next-backups.html" title="Backup Strategy"><link rel="next" href="automated-backup.html" title="Automated Backup"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-next-backups.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="automated-backup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="snapshot-backup"></a>Manual backup and recovery</h2></div></div></div><p>This section describes how to make a one-time backup and +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Manual backup and recovery</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="backup-recovery.html" title="Chapter 8. Backup and Recovery"><link rel="previous" href="install-next-backups.html" title="Backup Strategy"><link rel="next" href="automated-backup.html" title="Automated Backup"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="install-next-backups.html">Prev</a> </td><th width="60%" align="center">Chapter 8. Backup and Recovery</th><td width="20%" align="right"> <a accesskey="n" href="automated-backup.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="snapshot-backup"></a>Manual backup and recovery</h2></div></div></div> + + + <p>This section describes how to make a one-time backup and restore of the files and database. This is useful for rolling back to known-good versions of a service, such as at initial installation and just before an upgrade. First, you back up the database to a file within the file tree. Then, you back up the file tree. All of the information needed to rebuild the site, including the AOLserver config files, is then in tree for regular - file system backup.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Back up the database to a file. </b></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a name="oracle-snapshot-backup"></a><b>Oracle. </b></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> + file system backup.</p> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Back up the database to a file. </b> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><a name="oracle-snapshot-backup"></a> + <b>Oracle. </b> + + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p> Download the backup script. Save the file <a class="ulink" href="files/export-oracle.txt" target="_top">export-oracle.txt</a> as <code class="filename">/var/tmp/export-oracle.txt</code> </p></li><li class="listitem"><p> Login as root. The following commands will install the export script: - </p><pre class="programlisting">[joeuser ~]$ <strong class="userinput"><code>su -</code></strong> + </p> + <pre class="programlisting">[joeuser ~]$ <strong class="userinput"><code>su -</code></strong> [root ~]# <strong class="userinput"><code>cp /var/tmp/export-oracle.txt /usr/sbin/export-oracle</code></strong> -[root ~]# <strong class="userinput"><code>chmod 700 /usr/sbin/export-oracle</code></strong></pre></li><li class="listitem"><p> +[root ~]# <strong class="userinput"><code>chmod 700 /usr/sbin/export-oracle</code></strong></pre> + </li><li class="listitem"><p> Setup the export directory; this is the directory where backups will be stored. We recommend the directory - <code class="filename">/ora8/m02/oracle-exports</code>.</p><pre class="programlisting">[root ~]# <strong class="userinput"><code>mkdir <span class="replaceable"><span class="replaceable">/ora8/m02/</span></span>oracle-exports</code></strong> -[root ~]# <strong class="userinput"><code>chown oracle:dba <span class="replaceable"><span class="replaceable">/ora8/m02/</span></span>oracle-exports</code></strong> -[root ~]# <strong class="userinput"><code>chmod 770 <span class="replaceable"><span class="replaceable">/ora8/m02/</span></span>oracle-exports</code></strong></pre></li><li class="listitem"><p> + <code class="filename">/ora8/m02/oracle-exports</code>.</p> + + <pre class="programlisting">[root ~]# <strong class="userinput"><code>mkdir <em class="replaceable"><code>/ora8/m02/</code></em>oracle-exports</code></strong> +[root ~]# <strong class="userinput"><code>chown oracle:dba <em class="replaceable"><code>/ora8/m02/</code></em>oracle-exports</code></strong> +[root ~]# <strong class="userinput"><code>chmod 770 <em class="replaceable"><code>/ora8/m02/</code></em>oracle-exports</code></strong></pre> + </li><li class="listitem"><p> Now edit <code class="filename">/usr/sbin/export-oracle</code> and change the <code class="computeroutput">SERVICE_NAME</code> and @@ -27,9 +47,12 @@ <code class="filename">/ora8/m02/oracle-exports</code>, you also need to change the <code class="computeroutput">exportdir</code> setting. - </p><p> + </p> + <p> Test the export procedure by running the command: - </p><pre class="programlisting">[root ~]# <strong class="userinput"><code>/usr/sbin/export-oracle</code></strong> + </p> + + <pre class="programlisting">[root ~]# <strong class="userinput"><code>/usr/sbin/export-oracle</code></strong> mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory Export: Release 8.1.6.1.0 - Production on Sun Jun 11 18:07:45 2000 @@ -64,38 +87,74 @@ . exporting dimensions . exporting post-schema procedural objects and actions . exporting statistics -Export terminated successfully without warnings.</pre></li></ul></div></li><li class="listitem"><p><a name="postgres-snapshot-backup"></a><b>PostgreSQL. </b>Create a backup file and verify that it was created and has a reasonable size (several megabytes).</p><pre class="screen">[root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>pg_dump -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>ls -al /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp </code></strong> +Export terminated successfully without warnings.</pre> + </li></ul></div> + </li><li class="listitem"> + <p><a name="postgres-snapshot-backup"></a> + <b>PostgreSQL. </b> + Create a backup file and verify that it was created and has a reasonable size (several megabytes). + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - $OPENACS_SERVICE_NAME</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>pg_dump -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>ls -al /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp </code></strong> -rw-rw-r-x 1 $OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME 4005995 Feb 21 18:28 /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> [root root]# -<span class="action"><span class="action">su - $OPENACS_SERVICE_NAME -pg_dump -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp <span class="replaceable"><span class="replaceable">openacs-dev</span></span> -ls -al /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/before_upgrade_to_4.6.dmp -exit</span></span></pre></li></ul></div></li><li class="listitem"><a name="backup-file-system"></a><p><b>Back up the file system. </b>Back up all of the files in the service, including the +<span class="action">su - $OPENACS_SERVICE_NAME +pg_dump -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp <em class="replaceable"><code>openacs-dev</code></em> +ls -al /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/before_upgrade_to_4.6.dmp +exit</span></pre> + </li></ul></div> + </li><li class="listitem"><a name="backup-file-system"></a> + <p> + <b>Back up the file system. </b> + Back up all of the files in the service, including the database backup file but excluding the auto-generated <code class="filename">supervise</code> directory, which is - unnecessary and has complicated permissions. </p><p>In the tar command,</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">c</code> create a - new tar archive</p></li><li class="listitem"><p><code class="computeroutput">p</code> preserves permissions.</p></li><li class="listitem"><p><code class="computeroutput">s</code> preserves file sort order</p></li><li class="listitem"><p><code class="computeroutput">z</code> compresses the output with gzip.</p></li><li class="listitem"><p>The <code class="computeroutput">--exclude</code> clauses skips some daemontools files that + unnecessary and has complicated permissions. + </p> + <p>In the tar command,</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><code class="computeroutput">c</code> create a + new tar archive</p> + </li><li class="listitem"> + <p><code class="computeroutput">p</code> preserves permissions.</p> + </li><li class="listitem"> + <p><code class="computeroutput">s</code> preserves file sort order</p> + </li><li class="listitem"> + <p><code class="computeroutput">z</code> compresses the output with gzip.</p> + </li><li class="listitem"> + <p>The <code class="computeroutput">--exclude</code> clauses skips some daemontools files that are owned by root and thus cannot be backed up by the service owner. These files are autogenerated and we don't - break anything by omitting them.</p></li><li class="listitem"><p>The <code class="computeroutput">--file</code> clause + break anything by omitting them.</p> + </li><li class="listitem"> + <p>The <code class="computeroutput">--file</code> clause specifies the name of the output file to be generated; we - manually add the correct extensions.</p></li><li class="listitem"><p>The last clause, - <code class="filename">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/</code>, + manually add the correct extensions.</p> + </li><li class="listitem"> + <p>The last clause, + <code class="filename">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/</code>, specifies the starting point for backup. Tar defaults to - recursive backup.</p></li></ul></div><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>tar -cpsz --exclude /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools/supervise \ - --file /var/tmp/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-backup.tar.gz /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/</code></strong> + recursive backup.</p> + </li></ul></div> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>tar -cpsz --exclude /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools/supervise \ + --file /var/tmp/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-backup.tar.gz /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/</code></strong> tar: Removing leading `/' from member names -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre></li><li class="listitem"><p><b>Suffer a catastrophic failure on your production system. </b>(We'll simulate this step)</p><pre class="screen">[root root]# <strong class="userinput"><code>svc -d /service/$OPENACS_SERVICE_NAME</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre> + </li><li class="listitem"> + <p> + <b>Suffer a catastrophic failure on your production system. </b> + (We'll simulate this step) + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>svc -d /service/$OPENACS_SERVICE_NAME</code></strong> [root root]# <strong class="userinput"><code>mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost</code></strong> [root root]#<strong class="userinput"><code> rm /service/$OPENACS_SERVICE_NAME</code></strong> rm: remove symbolic link `/service/$OPENACS_SERVICE_NAME'? y [root root]# <strong class="userinput"><code>ps -auxw | grep $OPENACS_SERVICE_NAME</code></strong> root 1496 0.0 0.0 1312 252 ? S 16:58 0:00 supervise $OPENACS_SERVICE_NAME -[root root]#<strong class="userinput"><code> kill<span class="replaceable"><span class="replaceable"> 1496</span></span></code></strong> +[root root]#<strong class="userinput"><code> kill<em class="replaceable"><code> 1496</code></em></code></strong> [root root]# <strong class="userinput"><code>ps -auxw | grep $OPENACS_SERVICE_NAME</code></strong> [root root]# <strong class="userinput"><code>su - postgres</code></strong> [postgres pgsql]$ <strong class="userinput"><code>dropdb $OPENACS_SERVICE_NAME</code></strong> @@ -104,30 +163,69 @@ DROP USER [postgres pgsql]$ <strong class="userinput"><code>exit</code></strong> logout -[root root]#</pre></li><li class="listitem"><p><a name="recovery"></a><b>Recovery. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Restore the operating system and required software. +[root root]#</pre> + </li><li class="listitem"> + <p><a name="recovery"></a> + <b>Recovery. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Restore the operating system and required software. You can do this with standard backup processes or by keeping copies of the install material (OS CDs, OpenACS tarball and supporting software) and repeating the install - guide. Recreate the service user (<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>).</p></li><li class="listitem"><p>Restore the OpenACS files and database backup file.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + guide. Recreate the service user (<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>).</p> + </li><li class="listitem"> + <p>Restore the OpenACS files and database backup file.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> [$OPENACS_SERVICE_NAME aolserver]$<strong class="userinput"><code> tar xzf /var/tmp/$OPENACS_SERVICE_NAME-backup.tar.gz</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME.web</span></span> <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li><li class="listitem"><p>Restore the database</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Oracle. </b></p><div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"><p>Set up a clean Oracle database user and - tablespace with the same names as the ones exported from (<a class="link" href="openacs.html#install-openacs-prepare-oracle" title="Prepare Oracle for OpenACS">more information</a>).</p></li><li class="listitem"><p>Invoke the import command</p><pre class="screen"><span class="action"><span class="action">imp <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> FILE=/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/nighty_backup.dmp FULL=Y</span></span></pre></li></ol></div></li><li class="listitem"><p><a name="restore-postgres"></a><b>Postgres. </b>If the database user does not already exist, create it.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - postgres</code></strong> -[postgres ~]$ <strong class="userinput"><code>createuser <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chmod -R 775 <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>chown -R <em class="replaceable"><code>$OPENACS_SERVICE_NAME.web</code></em> <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li><li class="listitem"> + <p>Restore the database</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Oracle. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="i"><li class="listitem"> + <p>Set up a clean Oracle database user and + tablespace with the same names as the ones exported from (<a class="link" href="openacs.html#install-openacs-prepare-oracle" title="Prepare Oracle for OpenACS">more information</a>).</p> + </li><li class="listitem"> + <p>Invoke the import command</p> + <pre class="screen"><span class="action">imp <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> FILE=/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/nighty_backup.dmp FULL=Y</span></pre> + </li></ol></div> + </li><li class="listitem"> + <p><a name="restore-postgres"></a> + <b>Postgres. </b> + If the database user does not already exist, create it. +</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - postgres</code></strong> +[postgres ~]$ <strong class="userinput"><code>createuser <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> Shall the new user be allowed to create databases? (y/n) <strong class="userinput"><code>y</code></strong> Shall the new user be allowed to create more new users? (y/n) <strong class="userinput"><code>y</code></strong> CREATE USER [postgres ~]$ <strong class="userinput"><code>exit</code></strong> -</pre><p>Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects. Next, restore the database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>createdb <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +</pre> + <p>Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects. Next, restore the database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored.</p> + +<pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>createdb <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> CREATE DATABASE -[$OPENACS_SERVICE_NAME ~]$<strong class="userinput"><code> psql -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-kernel/sql/postgresql/postgresql.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +[$OPENACS_SERVICE_NAME ~]$<strong class="userinput"><code> psql -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-kernel/sql/postgresql/postgresql.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> <span class="emphasis"><em>(many lines omitted)</em></span> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> < /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/database-backup/<span class="replaceable"><span class="replaceable">database-backup.dmp</span></span></code></strong> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> < /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/database-backup/<em class="replaceable"><code>database-backup.dmp</code></em></code></strong> <span class="emphasis"><em>(many lines omitted)</em></span> [$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>exit</code></strong> [postgres ~]$ <strong class="userinput"><code>exit</code></strong> -logout</pre></li></ul></div></li><li class="listitem"><p>Activate the service</p><pre class="screen">[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/etc/daemontools /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +logout</pre> + </li></ul></div> + </li><li class="listitem"> + <p>Activate the service</p> + <pre class="screen">[root root]# <strong class="userinput"><code>ln -s /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/etc/daemontools /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [root root]# <strong class="userinput"><code>sleep 10</code></strong> -[root root]# <strong class="userinput"><code>svgroup web /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li></ol></div></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-next-backups.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="automated-backup.html">Next</a></td></tr><tr><td width="40%" align="left">Backup Strategy </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Automated Backup</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +[root root]# <strong class="userinput"><code>svgroup web /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li></ol></div> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="install-next-backups.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="automated-backup.html">Next</a></td></tr><tr><td width="40%" align="left">Backup Strategy </td><td width="20%" align="center"><a accesskey="u" href="backup-recovery.html">Up</a></td><td width="40%" align="right"> Automated Backup</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/style-guide.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/style-guide.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/style-guide.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/style-guide.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -99,8 +99,8 @@ </tr></thead><tbody><tr> <td>0.1</td><td>Creation</td><td>12/2003</td><td>Jeff Davis</td> </tr></tbody> -</table></div><div class="cvstag">($‌Id: style-guide.xml,v 1.3.14.3 2017/04/22 -17:18:48 gustafn Exp $)</div> +</table></div><p><span class="cvstag">($‌Id: style-guide.xml,v 1.4 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/style-guide.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/style-guide.html,v diff -u -r1.29 -r1.30 --- openacs-4/packages/acs-core-docs/www/style-guide.html 7 Aug 2017 23:47:52 -0000 1.29 +++ openacs-4/packages/acs-core-docs/www/style-guide.html 8 Nov 2017 09:42:12 -0000 1.30 @@ -1,10 +1,18 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Style Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="next" href="cvs-guidelines.html" title="CVS Guidelines"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="cvs-guidelines.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="style-guide"></a>OpenACS Style Guide</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Style Guide</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="next" href="cvs-guidelines.html" title="CVS Guidelines"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="cvs-guidelines.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="style-guide"></a>OpenACS Style Guide</h2></div></div></div> + + + <p> By Jeff Davis - </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-guide-motivation"></a>Motivation</h3></div></div></div><p> + </p> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-guide-motivation"></a>Motivation</h3></div></div></div> + + <p> Why have coding standards for OpenACS? And if the code works why change it to adhere to some arbitrary rules? - </p><p> + </p> + <p> Well, first lets consider the OpenACS code base (all this as of December 2003 and including dotLRN). There are about 390,000 lines of Tcl code, about 460,000 lines of sql (in datamodel @@ -14,22 +22,34 @@ there are about 160 packages, 800 tables, 2,000 stored procedures, about 2,000 functional pages, and about 3,200 Tcl procedures. - </p><p> + </p> + <p> When confronted by this much complexity it's important to be able to make sense of it without having to wade through it all. Things should be coherent, things should be named predictably and behave like you would expect, and your guess about what something is called or where it is should be right more often than not because the code follows the rules. - </p><p> + </p> + <p> Unfortunately, like any large software project written over a long period by a lot of different people, OpenACS sometimes lacks this basic guessability and in the interest of bringing it into line we have advanced these guidelines. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-commandments"></a>Commandments</h3></div></div></div><p> + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-commandments"></a>Commandments</h3></div></div></div> + + + <p> Here is a short list of the basic rules code contributed to OpenACS should follow... - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Follow the file naming and the package structure rules. </b> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Follow the file naming and the package structure rules. </b> + Some of the file naming rules are requirements for things to function correctly (for example data model creation scripts and Tcl library files must be named properly to be @@ -38,25 +58,50 @@ if ignored won't break anything, but if you follow the rules people will be able to understand your package much more easily. - </p></li><li class="listitem"><p><b>Be literate in your programming. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Be literate in your programming. </b> + Use ad_proc, ad_library, and ad_page_contract to provide documentation for your code, use comments on your datamodel, explain what things mean and how they should work. - </p></li><li class="listitem"><p><b>Test. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Test. </b> + Write test cases for your API and data model; test negative cases as well as positive; document your tests. Provide tests for bugs which are not yet fixed. Test, Test, Test. - </p></li><li class="listitem"><p><b>Use namespaces. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Use namespaces. </b> + For new packages choose a namespace and place all procedures in it and in oracle create packages. - </p></li><li class="listitem"><p><b>Follow the constraint naming and the PL/SQL and PL/pgSQL rules. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Follow the constraint naming and the PL/SQL and PL/pgSQL rules. </b> + Naming constraints is important for upgradability and for consistency. Also, named constraints can be immensely helpful in developing good error handling. Following the PL/SQL and PL/pgSQL rules ensure that the procedures created can be handled similarly across both Oracle and PostgreSQL databases. - </p></li><li class="listitem"><p><b>Follow the code formatting guidelines. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Follow the code formatting guidelines. </b> + The code base is very large and if things are formatted consistently it is easier to read. Also, if it conforms to the standard it won't be reformatted (which can mask @@ -65,29 +110,65 @@ easier to read and manage and does not force other programmers to decipher what tab settings you had in place in your editor. - </p></li><li class="listitem"><p><b>Use the standard APIs. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Use the standard APIs. </b> + Don't reinvent the wheel. Prefer extending an existing core API to creating your own. If something in the core does not meet your particular needs it probably won't meet others as well and fleshing out the core API's makes the toolkit more useful for everyone and more easily extended. - </p></li><li class="listitem"><p><b>Make sure your datamodel create/drop scripts work. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Make sure your datamodel create/drop scripts work. </b> + Break the table creation out from the package/stored procedure creation and use <code class="computeroutput">create or replace</code> where possible so that scripts can be sourced more than once. Make sure your drop script works if data has been inserted (and permissioned and notifications have been attached etc). - </p></li><li class="listitem"><p><b>Practice CVS/Bug Tracker Hygiene. </b> + + </p> + </li><li class="listitem"> + <p> + <b>Practice CVS/Bug Tracker Hygiene. </b> + Commit your work. commit with sensible messages and include patch and bug numbers in your commit messages. - </p><p> + + </p> + <p> Create bug tracker tickets for things you are going to work on yourself (just in case you don't get to it and to act as a pointer for others who might encounter the same problem). - </p></li><li class="listitem"><p><b>Solicit code reviews. </b> + </p> + </li><li class="listitem"> + <p> + <b>Solicit code reviews. </b> + Ask others to look over your code and provide feedback and do the same for others. - </p></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-guide-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.1</td><td>Creation</td><td>12/2003</td><td>Jeff Davis</td></tr></tbody></table></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-guidelines.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 12. Engineering Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> + + </p> + </li></ol></div> + </div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="style-guide-rev-history"></a>Revision History</h3></div></div></div> + + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><thead><tr><th>Document Revision #</th><th>Action Taken, Notes</th><th>When?</th><th>By Whom?</th></tr></thead><tbody><tr><td>0.1</td><td>Creation</td><td>12/2003</td><td>Jeff Davis</td></tr></tbody></table> + </div> + <p><span class="cvstag">($Id$)</span></p> + </div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="cvs-guidelines.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 12. Engineering Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> CVS Guidelines </td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/subsites-design.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/subsites-design.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/subsites-design.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="apm-requirements" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="subsites-design" id="subsites-design"></a>Subsites Design Document</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p><span class="emphasis"><em>*Note* This document has not gone +<a name="subsites-design" id="subsites-design"></a>Subsites Design Document</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. +Schloming</a> +</span></p><span style="color: red"></authorblurb></span><p><span class="emphasis"><em>*Note* This document has not gone through the any of the required QA process yet. It is being tagged as stable due to high demand.</em></span></p><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> Index: openacs-4/packages/acs-core-docs/www/subsites-design.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-design.html,v diff -u -r1.36 -r1.37 --- openacs-4/packages/acs-core-docs/www/subsites-design.html 7 Aug 2017 23:47:52 -0000 1.36 +++ openacs-4/packages/acs-core-docs/www/subsites-design.html 8 Nov 2017 09:42:12 -0000 1.37 @@ -1,50 +1,125 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Subsites Design Document</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="subsites-requirements.html" title="Subsites Requirements"><link rel="next" href="apm-requirements.html" title="Package Manager Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites-design"></a>Subsites Design Document</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p><span class="emphasis"><em>*Note* This document has not gone through the any of the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Subsites Design Document</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="subsites-requirements.html" title="Subsites Requirements"><link rel="next" href="apm-requirements.html" title="Package Manager Requirements"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites-design"></a>Subsites Design Document</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> </p> +</authorblurb></span> + +<p><span class="emphasis"><em>*Note* This document has not gone through the any of the required QA process yet. It is being tagged as stable due to high -demand.</em></span></p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-essentials"></a>Essentials</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="subsites-requirements.html" title="Subsites Requirements">OpenACS 4 Subsites Requirements</a></p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-intro"></a>Introduction</h3></div></div></div><p>An OpenACS 4 subsite is a managed suite of applications that work together for +demand.</em></span></p> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-essentials"></a>Essentials</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p><a class="xref" href="subsites-requirements.html" title="Subsites Requirements">OpenACS 4 Subsites Requirements</a></p> +</li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-intro"></a>Introduction</h3></div></div></div> + + + + +<p>An OpenACS 4 subsite is a managed suite of applications that work together for a particular user community. This definition covers a very broad range of requirements: from a Geocities style homepage where a user can install whatever available application he wants (e.g. a single user could have their own news and forums), to a highly structured project subsite with multiple interdependent applications. Thus, flexibility in application deployment is -the overarching philosophy of subsites.</p><p>Meeting such broad requirements of flexibility demands architecture-level +the overarching philosophy of subsites.</p> + +<p>Meeting such broad requirements of flexibility demands architecture-level support, i.e. very low level support from the core OpenACS 4 data model. For example, the subsites concept demands that any package can have multiple instances installed at different URLs - entailing support from the APM and the Request Processor. Since the design and implementation directly associated with subsites is actually minimal, a discussion of subsites design is, in fact, a discussion of how core OpenACS 4 components implicitly support -subsites as a whole.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-hist-considerations"></a>Historical Considerations</h3></div></div></div><p>The subsites problem actually has several quite diverse origins. It was +subsites as a whole.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-hist-considerations"></a>Historical Considerations</h3></div></div></div> + + + + +<p>The subsites problem actually has several quite diverse origins. It was originally recognized as a toolkit feature in the form of "scoping". The basic concept behind scoping was to allow one scoped OpenACS installation to behave as multiple unscoped OpenACS installations so that one OpenACS install could serve multiple communities. Each piece of application data was tagged with a "scope" consisting of the (user_id, group_id, scope) triple. In practice the highly denormalized data models that this method uses produced large amounts of very redundant code and in general made -it an extremely cumbersome process to "scopify" a module.</p><p>Before the advent of scoping there were several cases of client projects +it an extremely cumbersome process to "scopify" a module.</p> + +<p>Before the advent of scoping there were several cases of client projects implementing their own version of scoping in special cases. One example being the wineaccess multi-retailer ecommerce. (Remember the other examples and get -details. Archnet?, iluvcamp?)</p><p>The requirements of all these different projects vary greatly, but the one +details. Archnet?, iluvcamp?)</p> + +<p>The requirements of all these different projects vary greatly, but the one consistent theme among all of them is the concept that various areas of the web site have their own private version of a module. Because this theme is so dominant, this is the primary problem that the OpenACS4 implementation of -subsites addresses.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-competitors"></a>Competitive Analysis</h3></div></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div><p>The current implementation of package instances and subsites allows +subsites addresses.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-competitors"></a>Competitive Analysis</h3></div></div></div> + + + + +<p>...</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-design-tradeoffs"></a>Design Tradeoffs</h3></div></div></div> + + + + +<p>The current implementation of package instances and subsites allows extremely flexible URL configurations. This has the benefit of allowing multiple instances of the same package to be installed in one subsite, but can potentially complicate the process of integrating packages with each other since it is likely people will want packages that live at non standard URLs to operate together. This requirement would cause some packages to have more configuration options than normal since hard-coding the URLs would not -be feasible anymore.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-api"></a>API</h3></div></div></div><p>This section will cover all the APIs relevant to subsites, and so will -consist of portions of the APIs of several systems.</p><p><span class="strong"><strong>Packages</strong></span></p><p>The following package is provided for instantiation of packages. The +be feasible anymore.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-api"></a>API</h3></div></div></div> + + + + +<p>This section will cover all the APIs relevant to subsites, and so will +consist of portions of the APIs of several systems.</p> + +<p><span class="strong"><strong>Packages</strong></span></p> + +<p>The following package is provided for instantiation of packages. The apm_package.new function can be used to create a package of any type known to the system. The apm_package_types table can be queried for a list of -installed packages. (See APM docs for more detail XXX: insert link here)</p><pre class="programlisting"> +installed packages. (See APM docs for more detail XXX: insert link here)</p> + + +<pre class="programlisting"> + <code class="computeroutput">create or replace package apm_package as @@ -100,16 +175,25 @@ show errors </code> -</pre><p><span class="strong"><strong>Site Nodes</strong></span></p><p>This data model keeps track of what packages are being served from what +</pre> + + +<p><span class="strong"><strong>Site Nodes</strong></span></p> + +<p>This data model keeps track of what packages are being served from what URLs. You can think of this as a kind of rp_register_directory_map on drugs. This table represents a fully hierarchical site map. The directory_p column indicates whether or not the node is a leaf node. The pattern_p column indicates whether an exact match between the request URL and the URL of the node is required. If pattern_p is true then a match between a request URL and a site node occurs if any valid prefix of the request URL matches the site node URL. The object_id column contains the object mounted on the URL -represented by the node. In most cases this will be a package instance.</p><pre class="programlisting"> +represented by the node. In most cases this will be a package instance.</p> + + +<pre class="programlisting"> + <code class="computeroutput">create table site_nodes ( node_id constraint site_nodes_node_id_fk references acs_objects (object_id) @@ -136,8 +220,15 @@ ); </code> -</pre><p>The following package is provided for creating nodes.</p><pre class="programlisting"> +</pre> + +<p>The following package is provided for creating nodes.</p> + + + +<pre class="programlisting"> + <code class="computeroutput">create or replace package site_node as @@ -181,26 +272,76 @@ show errors </code> -</pre><p><span class="strong"><strong>Request Processor</strong></span></p><p>Once the above APIs are used to create packages and mount them on a +</pre> + + +<p><span class="strong"><strong>Request Processor</strong></span></p> + +<p>Once the above APIs are used to create packages and mount them on a specific site node, the following request processor APIs can be used to allow -the package to serve content appropriate to the package instance.</p><pre class="programlisting"> +the package to serve content appropriate to the package instance.</p> + + +<pre class="programlisting"> + <code class="computeroutput">[ad_conn node_id] [ad_conn package_id] [ad_conn package_url] [ad_conn subsite_id] [ad_conn subsite_url] </code> -</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-data-model"></a>Data Model Discussion</h3></div></div></div><p>The subsites implementation doesn't really have it's own data +</pre> + + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-data-model"></a>Data Model Discussion</h3></div></div></div> + + + + +<p>The subsites implementation doesn't really have it's own data model, although it depends heavily on the site-nodes data model, and the APM -data model.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-ui"></a>User Interface</h3></div></div></div><p>The primary elements of the subsite user interface consist of the subsite +data model.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-ui"></a>User Interface</h3></div></div></div> + + + + +<p>The primary elements of the subsite user interface consist of the subsite admin pages. These pages are divided up into two areas: Group administration, and the site map. The group administration pages allow a subsite administrator to create and modify groups. The site map pages allow a subsite administrator to install, remove, configure, and control access to packages. The site map interface is the primary point of entry for most of the things a -subsite administrator would want to do.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-config"></a>Configuration/Parameters</h3></div></div></div><p>...</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div><p>The current subsites implementation addresses the most basic functionality +subsite administrator would want to do.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-config"></a>Configuration/Parameters</h3></div></div></div> + + + + +<p>...</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-future"></a>Future Improvements/Areas of Likely Change</h3></div></div></div> + + + + +<p>The current subsites implementation addresses the most basic functionality required for subsites. It is likely that as developers begin to use the subsites system for more sophisticated projects, it will become necessary to develop tools to help build tightly integrated packages. The general area @@ -211,4 +352,19 @@ a particular configuration of site nodes/packages. As we build more fundamental applications that can be applied in more general areas, this feature will become more and more in demand since more problems will be -solvable by configuration instead of coding.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-authors"></a>Authors</h3></div></div></div><p><a class="ulink" href="mailto:rhs@mit.edu" target="_top">rhs@mit.edu</a></p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Subsites Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Package Manager Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +solvable by configuration instead of coding.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-design-authors"></a>Authors</h3></div></div></div> + + + + +<p><a class="ulink" href="mailto:rhs@mit.edu" target="_top">rhs@mit.edu</a></p> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="subsites-requirements.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="apm-requirements.html">Next</a></td></tr><tr><td width="40%" align="left">Subsites Requirements </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Package Manager Requirements</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,10 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="subsites-requirements" id="subsites-requirements"></a>Subsites -Requirements</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and Dennis Gregorovic</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +Requirements</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and +Dennis Gregorovic</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="subsites-requirements-intro" id="subsites-requirements-intro"></a>Introduction</h3></div></div></div><p>The following is a requirements document for OpenACS 4 Subsites, part of the OpenACS 4 Kernel. The Subsites system allows one Index: openacs-4/packages/acs-core-docs/www/subsites-requirements.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites-requirements.html,v diff -u -r1.35 -r1.36 --- openacs-4/packages/acs-core-docs/www/subsites-requirements.html 7 Aug 2017 23:47:52 -0000 1.35 +++ openacs-4/packages/acs-core-docs/www/subsites-requirements.html 8 Nov 2017 09:42:12 -0000 1.36 @@ -1,57 +1,194 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Subsites Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="groups-design.html" title="Groups Design"><link rel="next" href="subsites-design.html" title="Subsites Design Document"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites-requirements"></a>Subsites Requirements</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and Dennis Gregorovic</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-intro"></a>Introduction</h3></div></div></div><p>The following is a requirements document for OpenACS 4 Subsites, part of the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Subsites Requirements</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="groups-design.html" title="Groups Design"><link rel="next" href="subsites-design.html" title="Subsites Design Document"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites-requirements"></a>Subsites Requirements</h2></div></div></div> + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="http://planitia.org" target="_top">Rafael H. Schloming</a> and Dennis Gregorovic</p> +</authorblurb></span> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-intro"></a>Introduction</h3></div></div></div> + + + + +<p>The following is a requirements document for OpenACS 4 Subsites, part of the OpenACS 4 Kernel. The Subsites system allows one OpenACS server instance to serve multiple user communities, by enabling the suite of available OpenACS -applications to be customized for defined user communities.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-vision"></a>Vision Statement</h3></div></div></div><p>Many online communities are also collections of discrete subcommunities, +applications to be customized for defined user communities.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-vision"></a>Vision Statement</h3></div></div></div> + + + + +<p>Many online communities are also collections of discrete subcommunities, reflecting real-world relationships. For example, a corporate intranet/extranet website serves both units within the company (e.g., offices, departments, teams, projects) and external parties (e.g., customers, partners, vendors). Subsites enable a single OpenACS instance to provide each subcommunity with its own "virtual website," by assembling OpenACS packages that together deliver a feature set tailored to the needs of the -subcommunity.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-system-overview"></a>System Overview</h3></div></div></div><p>The OpenACS subsite system allows a single OpenACS installation to serve multiple +subcommunity.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-system-overview"></a>System Overview</h3></div></div></div> + + + + +<p>The OpenACS subsite system allows a single OpenACS installation to serve multiple communities. At an implementation level this is primarily accomplished by having an application "scope" its content to a particular package instance. The <a class="link" href="rp-design.html" title="Request Processor Design">request processor</a> then figures out which package_id a particular URL references and then provides this information through the <code class="computeroutput">ad_conn</code> api (<code class="computeroutput">[ad_conn -package_id]</code>, <code class="computeroutput">[ad_conn package_url]</code>).</p><p>The other piece of the subsite system is a subsite package that provides +package_id]</code>, <code class="computeroutput">[ad_conn package_url]</code>).</p> + + + +<p>The other piece of the subsite system is a subsite package that provides subsite admins a "control panel" for administering their subsite. This is the same package used to provide all the community core functionality available at the "main" site which is in fact simply another -subsite.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div></div><p>The Subsites functionality is intended for use by two different classes of -users:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Package programmers (referred to as 'the programmer') must +subsite.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-use-cases"></a>Use-cases and User-scenarios</h3></div></div></div> + + + + +<p>The Subsites functionality is intended for use by two different classes of +users:</p> + +<div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Package programmers (referred to as 'the programmer') must develop subcommunity-aware applications.</p></li><li class="listitem"><p>Site administrators (referred to as 'the administrator') use subsites to provide tailored "virtual websites" to different -subcommunities.</p></li></ol></div><p>Joe Programmer is working on the forum package and wants to make it +subcommunities.</p></li></ol></div> + +<p>Joe Programmer is working on the forum package and wants to make it subsite-aware. Using [ad_conn package_id], Joe adds code that only displays forum messages associated with the current package instance. Joe is happy to realize that parameter::get is already smart enough to return configuration parameters for the current package instance, and so he has to do no extra -work to tailor configuration parameters to the current subsite.</p><p>Jane Admin maintains www.company.com. She learns of Joe's work and +work to tailor configuration parameters to the current subsite.</p> + +<p>Jane Admin maintains www.company.com. She learns of Joe's work and would like to set up individual forums for the Boston and Austin offices of her company. The first thing she does is use the APM to install the new -forum package.</p><p>Next, Jane uses the Subsite UI to create subsites for the Boston and +forum package.</p> + +<p>Next, Jane uses the Subsite UI to create subsites for the Boston and Austin offices. Then Jane uses the Subsite UI to create forums for each -office.</p><p>Now, the Boston office employees have their own forum at +office.</p> + +<p>Now, the Boston office employees have their own forum at http://www.company.com/offices/boston/forum, and similarly for the Austin office. At this point, the Boston and Austin office admins can customize the configurations for each of their forums, or they can just use the -defaults.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-links"></a>Related Links</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="subsites-design.html" title="Subsites Design Document">OpenACS 4 Subsites Design Document</a></p></li><li class="listitem"><p>Test plan (Not available yet)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-api"></a>Requirements: Programmer's API</h3></div></div></div><p>A subsite API is required for programmers to ensure their packages are -subsite-aware. The following functions should be sufficient for this:</p><p><span class="strong"><strong>10.10.0 Package creation</strong></span></p><p>The system must provide an API call to create a package, and it must be -possible for the context (to which the package belongs) to be specified.</p><p><span class="strong"><strong>10.20.0 Package deletion</strong></span></p><p>The system must provide an API call to delete a package and all related -objects in the subsite's context.</p><p><span class="strong"><strong>10.30.0 Object's package information</strong></span></p><p>Given an object ID, the system must provide an API call to determine the -package (ID) to which the object belongs.</p><p><span class="strong"><strong>10.40.0 URL from package</strong></span></p><p>Given a package (ID), the system must provide an API call to return the -canonical URL for that package.</p><p><span class="strong"><strong>10.50.0 Main subsite's package_id</strong></span></p><p>The system must provide an API call to return a package ID corresponding -to the main subsite's package ID (the degenerate subsite).</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-ui"></a>Requirements: The User Interface</h3></div></div></div><p><span class="strong"><strong>The Programmer's User Interface</strong></span></p><p>There is no programmer's UI, other than the API described above.</p><p><span class="strong"><strong>The Administrator's User Interface</strong></span></p><p>The UI for administrators is a set of HTML pages that are used to drive +defaults.</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-links"></a>Related Links</h3></div></div></div> + + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><a class="xref" href="subsites-design.html" title="Subsites Design Document">OpenACS 4 Subsites Design Document</a></p></li><li class="listitem"><p>Test plan (Not available yet)</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-api"></a>Requirements: Programmer's API</h3></div></div></div> + + + + +<p>A subsite API is required for programmers to ensure their packages are +subsite-aware. The following functions should be sufficient for this:</p> + +<p><span class="strong"><strong>10.10.0 Package creation</strong></span></p> + +<p>The system must provide an API call to create a package, and it must be +possible for the context (to which the package belongs) to be specified.</p> + +<p><span class="strong"><strong>10.20.0 Package deletion</strong></span></p> + +<p>The system must provide an API call to delete a package and all related +objects in the subsite's context.</p> + +<p><span class="strong"><strong>10.30.0 Object's package information</strong></span></p> + +<p>Given an object ID, the system must provide an API call to determine the +package (ID) to which the object belongs.</p> + +<p><span class="strong"><strong>10.40.0 URL from package</strong></span></p> + +<p>Given a package (ID), the system must provide an API call to return the +canonical URL for that package.</p> + +<p><span class="strong"><strong>10.50.0 Main subsite's package_id</strong></span></p> + +<p>The system must provide an API call to return a package ID corresponding +to the main subsite's package ID (the degenerate subsite).</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-ui"></a>Requirements: The User Interface</h3></div></div></div> + + + + +<p><span class="strong"><strong>The Programmer's User Interface</strong></span></p> + +<p>There is no programmer's UI, other than the API described above.</p> + +<p><span class="strong"><strong>The Administrator's User Interface</strong></span></p> + +<p>The UI for administrators is a set of HTML pages that are used to drive the underlying API for package instance management (i.e. adding, removing, or altering packages). It is restricted to administrators of the current subsite such that administrators can only manage their own subsites. Of course, -Site-Wide Administrators can manage all subsites.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>20.10.0 Package creation</strong></span></p><p><span class="strong"><strong>20.10.1</strong></span> The administrator should be able to create a -package and make it available at a URL underneath the subsite.</p></li><li class="listitem"><p><span class="strong"><strong>20.20.0 Package deactivation</strong></span></p><p><span class="strong"><strong>20.20.1</strong></span> The administrator should be able to deactivate -any package, causing it to be inaccessible to users.</p><p><span class="strong"><strong>20.20.5</strong></span> Deactivating a package makes the package no +Site-Wide Administrators can manage all subsites.</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> +<p><span class="strong"><strong>20.10.0 Package creation</strong></span></p> + +<p><span class="strong"><strong>20.10.1</strong></span> The administrator should be able to create a +package and make it available at a URL underneath the subsite.</p> +</li><li class="listitem"> +<p><span class="strong"><strong>20.20.0 Package deactivation</strong></span></p> + +<p><span class="strong"><strong>20.20.1</strong></span> The administrator should be able to deactivate +any package, causing it to be inaccessible to users.</p> + +<p><span class="strong"><strong>20.20.5</strong></span> Deactivating a package makes the package no longer accessible, but it does not remove data created within the context of -that package.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-rev-history"></a>Revision History</h3></div></div></div><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/18/2000</td><td>Dennis Gregorovic</td></tr><tr><td>0.2</td><td>Edited, reviewed</td><td>08/29/2000</td><td>Kai Wu</td></tr></tbody></table></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr><tr><td width="40%" align="left">Groups Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Subsites Design Document</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +that package.</p> +</li></ul></div> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-requirements-rev-history"></a>Revision History</h3></div></div></div> + + + + + +<div class="informaltable"> +<table class="informaltable" cellspacing="0" border="1"><colgroup><col><col><col><col></colgroup><tbody><tr><td><span class="strong"><strong>Document Revision #</strong></span></td><td><span class="strong"><strong>Action Taken, Notes</strong></span></td><td><span class="strong"><strong>When?</strong></span></td><td><span class="strong"><strong>By Whom?</strong></span></td></tr><tr><td>0.1</td><td>Creation</td><td>08/18/2000</td><td>Dennis Gregorovic</td></tr><tr><td>0.2</td><td>Edited, reviewed</td><td>08/29/2000</td><td>Kai Wu</td></tr></tbody></table></div> + + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="groups-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="subsites-design.html">Next</a></td></tr><tr><td width="40%" align="left">Groups Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Subsites Design Document</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/subsites.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/subsites.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/subsites.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,10 +9,8 @@ rightLink="parties" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="subsites" id="subsites"></a>Writing OpenACS Application Pages</h2></div></div></div><div class="authorblurb"> -<p>By Rafael H. Schloming and Pete Su</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="subsites" id="subsites"></a>Writing OpenACS Application Pages</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Rafael H. Schloming and Pete +Su</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="subsites-overview" id="subsites-overview"></a>Overview</h3></div></div></div><p>In this document, we'll examine the user interface pages of the Notes application in more detail, covering two separate aspects @@ -242,8 +240,8 @@ that appears to provide each user in a system with their own private notes database.</p><p>We also saw how to use the templating system's forms API in a simple way, to create forms based pages with minimal duplication -of code.</p><div class="cvstag">($‌Id: subsites.xml,v 1.9.2.1 2016/06/23 -08:32:46 gustafn Exp $)</div> +of code.</p><p><span class="cvstag">($‌Id: subsites.xml,v 1.10 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/subsites.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/subsites.html,v diff -u -r1.49 -r1.50 --- openacs-4/packages/acs-core-docs/www/subsites.html 7 Aug 2017 23:47:52 -0000 1.49 +++ openacs-4/packages/acs-core-docs/www/subsites.html 8 Nov 2017 09:42:12 -0000 1.50 @@ -1,8 +1,19 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Writing OpenACS Application Pages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="permissions.html" title="Groups, Context, Permissions"><link rel="next" href="parties.html" title="Parties in OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites"></a>Writing OpenACS Application Pages</h2></div></div></div><div class="authorblurb"><p>By Rafael H. Schloming and Pete Su</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-overview"></a>Overview</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Writing OpenACS Application Pages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="permissions.html" title="Groups, Context, Permissions"><link rel="next" href="parties.html" title="Parties in OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="subsites"></a>Writing OpenACS Application Pages</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Rafael H. Schloming and Pete Su</p> +</authorblurb></span> + + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-overview"></a>Overview</h3></div></div></div> + + + +<p> In this document, we'll examine the user interface pages of the Notes application in more detail, covering two separate aspects of page development in OpenACS. First, we'll talk about the code needed to make @@ -11,7 +22,15 @@ form-based user interfaces in OpenACS. While these seem like unrelated topics, they both come up in the example page that we are going to look at, so it makes sense to address them at the same time. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-instances"></a>Application Instances and Subsites</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-instances"></a>Application Instances and Subsites</h3></div></div></div> + + + +<p> As you will recall from the <a class="link" href="packages.html" title="OpenACS Packages">packages</a> tutorial, the Request Processor (RP) and Package Manager (APM) allow site administrators to define an arbitrary mapping from URLs in the site to @@ -23,7 +42,9 @@ translated into a physical file to serve using the site map. We'll repeat this description here, assuming that you have mounted an instance of Notes at the URL <code class="computeroutput">/notes</code> as we did in the <a class="link" href="packages.html#packages-looks" title="What a Package Looks Like">packages-example</a>: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> AOLserver receives your request for the URL <code class="computeroutput">/notes/somepage</code>. </p></li><li class="listitem"><p> This URL is passed to the request processor. @@ -41,14 +62,18 @@ <code class="computeroutput">ROOT/packages/notes/www/</code>. Therefore, the page that is finally served is <code class="computeroutput">ROOT/packages/notes/www/hello.html</code>, which is what we wanted. -</p></li></ul></div><p> +</p></li></ul></div> + +<p> What is missing from this description is a critical fact for application developers: In addition to working out what file to serve, the RP also stores information about which package instance the file belongs to into the AOLserver connection environment. The following <code class="computeroutput">ad_conn</code> interfaces can be used to extract this information: -</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">[ad_conn package_url]</code></span></dt><dd><p> +</p> + +<div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">[ad_conn package_url]</code></span></dt><dd><p> If the URL refers to a package instance, this is the URL to the root of the tree where the package is mounted. </p></dd><dt><span class="term"><code class="computeroutput">[ad_conn package_id]</code></span></dt><dd><p> @@ -64,7 +89,9 @@ </span></dt><dd><p> If we found the URL in the site map, this is the tail of the URL following the part that matched a site map entry. -</p></dd></dl></div><p> +</p></dd></dl></div> + +<p> In the Notes example, we are particularly interested in the <code class="computeroutput">package_id</code> field. If you study the data model and code, you'll see why. As we said before in the <a class="link" href="objects.html" title="OpenACS Data Models and the Object System">data modeling</a> tutorial, the Notes application points the @@ -75,13 +102,18 @@ owner of the package to easily define access control policies for all the notes in a particular instance just my setting permissions on the package instance itself. -</p><p> +</p> + +<p> The code for adding and editing notes, in <code class="computeroutput">notes/www/add-edit.tcl</code>, shows how this works. At the top of the page, we extract the <code class="computeroutput">package_id</code> and use it to do permission checks: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + set package_id [ad_conn package_id] if {[info exists note_id]} { @@ -94,15 +126,24 @@ set context_bar [ad_context_bar "New Note"] } -</pre><p> +</pre> + + +<p> This code figures out whether we are editing an existing note or creating a new one. It then ensures that we have the right privileges for each action. -</p><p> +</p> + +<p> Later, when we actually create a note, the SQL that we run ensures that the <code class="computeroutput">context_id</code> is set the right way: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + db_dml new_note { declare id integer; @@ -118,34 +159,58 @@ end; } -</pre><p> +</pre> + + +<p> The rest of this page makes calls to the form builder part of the template system. This API allows you to write forms-based pages without generating a lot of duplicated HTML in your pages. It also encapsulates most of the common logic that we use in dealing with forms, which we'll discuss next. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-using-forms"></a>Using Forms</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-using-forms"></a>Using Forms</h3></div></div></div> + + + +<p> The forms API is pretty simple: You use calls in the <code class="computeroutput">template::form</code> namespace in your Tcl script to create form elements. The final template page then picks this stuff up and lays the form out for the user. The form is set up to route submit buttons and whatnot back to the same Tcl script that set up the form, so your Tcl script will also contain the logic needed to process these requests. -</p><p> +</p> + +<p> So, given this outline, here is a breakdown of how the forms code works in the <code class="computeroutput">add-edit.tcl</code> page. First, we create a form object called <code class="computeroutput">new_note</code>: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + template::form create new_note -</pre><p> +</pre> + + +<p> All the forms related code in this page will refer back to this object. In addition, the <code class="computeroutput">adp</code> part of this page does nothing but display the form object: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + <master> @context_bar@ @@ -156,11 +221,18 @@ <formtemplate id="new_note"></formtemplate> </center> -</pre><p> +</pre> + + +<p> The next thing that the Tcl page does is populate the form with form elements. This code comes first: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + if {[template::form is_request new_note] && [info exists note_id]} { template::element create new_note note_id \ @@ -175,37 +247,52 @@ } } -</pre><p> +</pre> + + +<p> The <code class="computeroutput">if_request</code> call returns true if we are asking the page to render the form for the first time. That is, we are rendering the form to ask the user for input. The <code class="computeroutput">tcl</code> part of a form page can be called in 3 different states: the initial request, the initial submission, and the validated submission. These states reflect the typical logic of a forms based page in OpenACS: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> First render the input form. </p></li><li class="listitem"><p> Next, control passes to a validation page that checks and confirms the inputs. </p></li><li class="listitem"><p> Finally, control passes to the page that performs the update in the database. -</p></li></ul></div><p> +</p></li></ul></div> + +<p> The rest of the <code class="computeroutput">if</code> condition figures out if we are creating a new note or editing an existing note. If <code class="computeroutput">note_id</code> is passed to us from the calling page, we assume that we are editing an existing note. In this case, we do a database query to grab the data for the note so we can populate the form with it. -</p><p> +</p> + +<p> The next two calls create form elements where the user can insert or edit the title and body of the Note. The interface to <code class="computeroutput">template::element</code> is pretty straightforward. -</p><p> +</p> + +<p> Finally, the code at the bottom of the page performs the actual database updates when the form is submitted and validated: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + if {[template::form is_valid new_note]} { set user_id [ad_conn user_id] set peeraddr [ad_conn peeraddr] @@ -237,13 +324,24 @@ ad_returnredirect "." } -</pre><p> +</pre> + + +<p> In this simple example, we don't do any custom validation. The nice thing about using this API is that the forms library handles all of the HTML rendering, input validation and database transaction logic on your behalf. This means that you can write pages without duplicating all of that code in every set of pages that uses forms. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-how-it-all-fits"></a>How it All Fits</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-how-it-all-fits"></a>How it All Fits</h3></div></div></div> + + + +<p> To watch all of this work, use the installer to update the Notes package with the new code that you grabbed out of CVS or the package repository, mount an instance of Notes somewhere in your server and @@ -253,25 +351,45 @@ home page, and set up the permissions so that the instance is only visible to that user. The end result is a site where users can come and write notes to themselves. -</p><p> +</p> + +<p> This is a good example of the leverage available in the OpenACS 5.9.0 system. The code that we have written for Notes is not at all more complex than a similar application without access control or site map awareness. By adding a small amount of code, we have taken a small, simple, and special purpose application to something that has the potential to be a very useful, general-purpose tool, complete with multi-user features, access control, and centralized administration. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-summary"></a>Summary</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="subsites-summary"></a>Summary</h3></div></div></div> + + + +<p> In OpenACS 5.9.0, application pages and scripts can be aware of the package instance, or subsite in which they are executing. This is a powerful general purpose mechanism that can be used to structure web services in very flexible ways. -</p><p> +</p> + +<p> We saw how to use this mechanism in the Notes application and how it makes it possible to easily turn Notes into an application that appears to provide each user in a system with their own private notes database. -</p><p> +</p> + +<p> We also saw how to use the templating system's forms API in a simple way, to create forms based pages with minimal duplication of code. -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr><tr><td width="40%" align="left">Groups, Context, Permissions </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Parties in OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> + +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="permissions.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="parties.html">Next</a></td></tr><tr><td width="40%" align="left">Groups, Context, Permissions </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Parties in OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tcl-doc.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tcl-doc.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,10 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tcl-doc" id="tcl-doc"></a>Documenting Tcl Files: Page Contracts and -Libraries</h2></div></div></div><div class="authorblurb"> -<p>By <a class="ulink" href="mailto:jsalz\@mit.edu" target="_top">Jon Salz</a> on 3 July 2000</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"><li class="listitem"><p>Tcl procedures: +Libraries</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By <a class="ulink" href="mailto:jsalz\@mit.edu" target="_top">Jon Salz</a> on 3 July +2000</span></p><span style="color: red"></authorblurb></span><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"><li class="listitem"><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="tcl-doc-bigpicture" id="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div></div><p>In versions of the OpenACS prior to 3.4, <a class="ulink" href="/doc/standards" target="_top">the standard place</a> to document @@ -222,8 +220,8 @@ page's CVS identification string. Just use <code class="computeroutput">$‌Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $</code> when creating the file, and CVS will substitute an appropriate string when you check the file in.</p></li> -</ul></div><div class="cvstag">($‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 -torbenb Exp $)</div> +</ul></div><p><span class="cvstag">($‌Id: tcl-doc.xml,v 1.7 2006/07/17 05:38:38 +torbenb Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/tcl-doc.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tcl-doc.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/tcl-doc.html 7 Aug 2017 23:47:52 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/tcl-doc.html 8 Nov 2017 09:42:12 -0000 1.51 @@ -1,10 +1,26 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Documenting Tcl Files: Page Contracts and Libraries</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="rp-design.html" title="Request Processor Design"><link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div></div><div class="authorblurb"><p>By <a class="ulink" href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> on 3 July 2000 </p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div></div><p>In versions of the OpenACS prior to 3.4, <a class="ulink" href="/doc/standards" target="_top">the standard +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Documenting Tcl Files: Page Contracts and Libraries</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="kernel-doc.html" title="Chapter 15. Kernel Documentation"><link rel="previous" href="rp-design.html" title="Request Processor Design"><link rel="next" href="bootstrap-acs.html" title="Bootstrapping OpenACS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><th width="60%" align="center">Chapter 15. Kernel Documentation</th><td width="20%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tcl-doc"></a>Documenting Tcl Files: Page Contracts and Libraries</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By <a class="ulink" href="mailto:jsalz@mit.edu" target="_top">Jon Salz</a> on 3 July 2000 </p> +</authorblurb></span> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Tcl procedures: /packages/acs-kernel/tcl-documentation-procs.tcl</p></li></ul></div> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-bigpicture"></a>The Big Picture</h3></div></div></div> + + + +<p>In versions of the OpenACS prior to 3.4, <a class="ulink" href="/doc/standards" target="_top">the standard place</a> to document Tcl files (both Tcl pages and Tcl library files) was in -a comment at the top of the file:</p><pre class="programlisting"> +a comment at the top of the file:</p> + + + +<pre class="programlisting"> # # <span class="emphasis"><em>path from server home</em></span>/<span class="emphasis"><em>filename</em></span> # @@ -14,30 +30,47 @@ # # <a class="ulink" href="http://www.loria.fr/~molli/cvs/doc/cvs_12.html#SEC93" target="_top">$Id$</a> # -</pre><p> +</pre> + +<p> In addition, the inputs expected by a Tcl page (i.e., form variables) would be enumerated in a call to <code class="computeroutput">ad_page_variables</code>, in effect, documenting the page's argument list. -</p><p>The problem with these practices is that the documentation is only +</p> + +<p>The problem with these practices is that the documentation is only accessible by reading the source file itself. For this reason, ACS 3.4 introduces a new API for documenting Tcl files and, on top of that, a -web-based user interface for browsing the documentation:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong><code class="computeroutput"><a class="link" href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></code></strong></span>: Every Tcl page +web-based user interface for browsing the documentation:</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong><code class="computeroutput"><a class="link" href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a></code></strong></span>: Every Tcl page has a <span class="strong"><strong>contract</strong></span> that explicitly defines what inputs the page expects (with more precision than <code class="computeroutput">ad_page_variables</code>) and incorporates metadata about the page (what used to live in the top-of-page comment). Like <code class="computeroutput">ad_page_variables</code>, <code class="computeroutput">ad_page_contract</code> also sets the specified variables in the context of the Tcl page.</p></li><li class="listitem"><p><span class="strong"><strong><code class="computeroutput"><a class="link" href="tcl-doc.html#tcl-doc-ad-library" title="ad_library">ad_library</a></code></strong></span>: To be called at the top of every library file (i.e., all files in the <code class="computeroutput">/tcl/</code> directory under the server root and -<code class="computeroutput">*-procs.tcl</code> files under <code class="computeroutput">/packages/</code>).</p></li></ul></div><p> +<code class="computeroutput">*-procs.tcl</code> files under <code class="computeroutput">/packages/</code>).</p></li></ul></div> + +<p> This has the following benefits: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Facilitates automatic generation of human-readable documentation.</p></li><li class="listitem"><p>Promotes security, by introducing a standard and automated way to check +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Facilitates automatic generation of human-readable documentation.</p></li><li class="listitem"><p>Promotes security, by introducing a standard and automated way to check inputs to scripts for correctness.</p></li><li class="listitem"><p>Allows graphical designers to determine easily how to customize sites' UIs, e.g., what properties are available in templates.</p></li><li class="listitem"><p>Allows the request processor to be intelligent: a script can specify in its contract which type of abstract document it returns, and the request processor can transform it automatically into something useful to a particular user agent. (Don't worry about this for -now - it's not complete for ACS 3.4.)</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div></div><p> +now - it's not complete for ACS 3.4.)</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-ad-page-contract"></a>ad_page_contract</h3></div></div></div> + + +<p> Currently <code class="computeroutput">ad_page_contract</code> serves mostly as a replacement for <code class="computeroutput">ad_page_variables</code>. Eventually, it will be integrated closely with the documents API so that each script's contract will document @@ -46,8 +79,14 @@ decsribe it here yet; for now, you can just consider <code class="computeroutput">ad_page_contract</code> a newer, better, documented <code class="computeroutput">ad_page_variables</code>.) -</p><p>Let's look at an example usage of <code class="computeroutput">ad_page_contract</code>:</p><pre class="programlisting"> +</p> +<p>Let's look at an example usage of <code class="computeroutput">ad_page_contract</code>:</p> + + + +<pre class="programlisting"> + # /packages/acs-kernel/api-doc/www/package-view.tcl ad_page_contract { version_id:integer @@ -69,9 +108,13 @@ @cvs-id $Id$ } -</pre><p> +</pre> + +<p> Note that: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>By convention, <code class="computeroutput">ad_page_contract</code> should be preceded +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><span class="strong"><strong>By convention, <code class="computeroutput">ad_page_contract</code> should be preceded by a comment line containing the file's path</strong></span>. The comment is on line 1, and the contract starts on line 2. </p></li><li class="listitem"><p><span class="strong"><strong><code class="computeroutput">ad_page_contract</code></strong></span>'s first argument is @@ -85,7 +128,10 @@ </p></li><li class="listitem"><p><span class="strong"><strong>Arguments can have flags</strong></span>, specified by following the name of the query argument with a colon and one or more of the following -strings (separated by commas): </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="strong"><strong><code class="computeroutput">optional</code></strong></span>: the query argument doesn't +strings (separated by commas): </p> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><span class="strong"><strong><code class="computeroutput">optional</code></strong></span>: the query argument doesn't need to be provided; if it's not, the variable for that argument simply won't be set. For instance, if I call the script above without a <code class="computeroutput">public_p</code> in the query, then in the page body <code class="computeroutput">[info exists @@ -107,50 +153,96 @@ list of all those values (or an empty list if it's unspecified). This is analogous to the <code class="computeroutput">-multiple-list</code> flag to <code class="computeroutput">ad_page_variables</code>, and is useful for handling form input -generated by <code class="computeroutput"><SELECT MULTIPLE></code> tags and checkboxes. </p><p>For instance, if <code class="computeroutput">dest_user_id:multiple</code> is specified in the -contract, and the query string is</p><pre class="programlisting"> +generated by <code class="computeroutput"><SELECT MULTIPLE></code> tags and checkboxes. </p> +<p>For instance, if <code class="computeroutput">dest_user_id:multiple</code> is specified in the +contract, and the query string is</p> + + + +<pre class="programlisting"> + ?dest_user_id=913&dest_user_id=891&dest_user_id=9 -</pre><p> +</pre> + +<p> then <code class="computeroutput">$dest_user_id</code> is set to <code class="computeroutput">[list 913 891 9]</code>. </p></li><li class="listitem"><p><span class="strong"><strong><code class="computeroutput">array</code></strong></span>: the argument may be specified arbitrarily many times in the query string, with parameter names with suffixes like <code class="computeroutput">_1</code>, <code class="computeroutput">_2</code>, <code class="computeroutput">_3</code>, etc. The variable is set to a list of all those values (or an empty list if none are -specified). </p><p>For instance, if <code class="computeroutput">dest_user_id:array</code> is specified in the -contract, and the query string is</p><pre class="programlisting"> +specified). </p> +<p>For instance, if <code class="computeroutput">dest_user_id:array</code> is specified in the +contract, and the query string is</p> + + + +<pre class="programlisting"> + ?dest_user_id_0=913&dest_user_id_1=891&dest_user_id_2=9 -</pre><p> -then <code class="computeroutput">$dest_user_id</code> is set to <code class="computeroutput">[list 913 891 9]</code>.</p></li></ul></div></li><li class="listitem"><p><span class="strong"><strong>You can provide structured, HTML-formatted documentation for your +</pre> + +<p> +then <code class="computeroutput">$dest_user_id</code> is set to <code class="computeroutput">[list 913 891 9]</code>.</p></li></ul></div> + + + +</li><li class="listitem"><p><span class="strong"><strong>You can provide structured, HTML-formatted documentation for your contract</strong></span>. Note that format is derived heavily from Javadoc: a general description of the script's functionality, followed optionally by a series of named attributes tagged by at symbols (<code class="computeroutput">@</code>). You are encouraged to provide: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>A description of the functionality of the page. If the description +</p> + + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>A description of the functionality of the page. If the description contains more than one sentence, the first sentence should be a brief summary. </p></li><li class="listitem"><p>A <span class="strong"><strong><code class="computeroutput">@param</code></strong></span> tag for each allowable query -argument. The format is </p><pre class="programlisting"> +argument. The format is </p> + + +<pre class="programlisting"> + @param <span class="emphasis"><em>parameter-name</em></span> <span class="emphasis"><em>description...</em></span> -</pre></li><li class="listitem"><p>An <span class="strong"><strong><code class="computeroutput">@author</code></strong></span> tag for each author. Specify the +</pre> + + + + +</li><li class="listitem"><p>An <span class="strong"><strong><code class="computeroutput">@author</code></strong></span> tag for each author. Specify the author's name, followed his or her email address in parentheses.</p></li><li class="listitem"><p>A <span class="strong"><strong><code class="computeroutput">@creation-date</code></strong></span> tag indicating when the script was first created.</p></li><li class="listitem"><p>A <span class="strong"><strong><code class="computeroutput">@cvs-id</code></strong></span> tag containing the page's CVS identification string. Just use <code class="computeroutput">$Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $</code> when creating the file, and CVS will -substitute an appropriate string when you check the file in.</p></li></ul></div><p> - These <code class="computeroutput">@</code> tags are optional, but highly recommended!</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-ad-library"></a>ad_library</h3></div></div></div><p> +substitute an appropriate string when you check the file in.</p></li></ul></div> + + + +<p> + These <code class="computeroutput">@</code> tags are optional, but highly recommended!</p></li></ul></div> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tcl-doc-ad-library"></a>ad_library</h3></div></div></div> + + +<p> <code class="computeroutput">ad_library</code> provides a replacement for the informal documentation (described above) found at the beginning of every Tcl page. Instead of: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + # /packages/acs-kernel/00-proc-procs.tcl # # Routines for defining procedures and libraries of procedures (-procs.tcl files). @@ -159,10 +251,16 @@ # # $Id$ -</pre><p> +</pre> + + +<p> you'll now write: -</p><pre class="programlisting"> +</p> + +<pre class="programlisting"> + # /packages/acs-kernel/00-proc-procs.tcl ad_library { @@ -175,14 +273,23 @@ } -</pre><p> +</pre> + +<p> Note that format is derived heavily from Javadoc: a general description of the script's functionality, followed optionally by a series of named attributes tagged by at symbols (<code class="computeroutput">@</code>). HTML formatting is allowed. You are encouraged to provide: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>An <span class="strong"><strong><code class="computeroutput">@author</code></strong></span> tag for each author. Specify the +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>An <span class="strong"><strong><code class="computeroutput">@author</code></strong></span> tag for each author. Specify the author's name, followed his or her email address in parentheses.</p></li><li class="listitem"><p>A <span class="strong"><strong><code class="computeroutput">@creation-date</code></strong></span> tag indicating when the script was first created.</p></li><li class="listitem"><p>A <span class="strong"><strong><code class="computeroutput">@cvs-id</code></strong></span> tag containing the page's CVS identification string. Just use <code class="computeroutput">$Id: tcl-documentation.html,v 1.2 2000/09/19 07:22:35 ron Exp $</code> when creating the file, and CVS will -substitute an appropriate string when you check the file in.</p></li></ul></div><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr><tr><td width="40%" align="left">Request Processor Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Bootstrapping OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +substitute an appropriate string when you check the file in.</p></li></ul></div> + + +<p><span class="cvstag">($Id$)</span></p> +</div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="rp-design.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="bootstrap-acs.html">Next</a></td></tr><tr><td width="40%" align="left">Request Processor Design </td><td width="20%" align="center"><a accesskey="u" href="kernel-doc.html">Up</a></td><td width="40%" align="right"> Bootstrapping OpenACS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/templates.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/templates.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="permissions" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="templates" id="templates"></a>Using Templates in OpenACS</h2></div></div></div><div class="authorblurb"> -<p>By Pete Su</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="templates" id="templates"></a>Using Templates in OpenACS</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">By Pete Su</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="templates-overview" id="templates-overview"></a>Overview</h3></div></div></div><p>The OpenACS Template System (ATS) is designed to allow developers to cleanly separate <span class="emphasis"><em>application logic</em></span> from <span class="emphasis"><em>display logic</em></span>. The intent is to have all @@ -153,8 +150,8 @@ sources.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="templates-documentation" id="templates-documentation"></a>Documentation</h3></div></div></div><p><a class="ulink" href="/doc/acs-templating/" target="_top">Templating system documentation</a></p><div class="cvstag">($‌Id: templates.xml,v 1.12.2.1 2016/06/23 -08:32:46 gustafn Exp $)</div> +<a name="templates-documentation" id="templates-documentation"></a>Documentation</h3></div></div></div><p><a class="ulink" href="/doc/acs-templating/" target="_top">Templating system documentation</a></p><p><span class="cvstag">($‌Id: templates.xml,v 1.13 2017/08/07 +23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/templates.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/templates.html 7 Aug 2017 23:47:52 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/templates.html 8 Nov 2017 09:42:12 -0000 1.51 @@ -1,8 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using Templates in OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="db-api.html" title="The OpenACS Database Access API"><link rel="next" href="permissions.html" title="Groups, Context, Permissions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="templates"></a>Using Templates in OpenACS</h2></div></div></div><div class="authorblurb"><p>By Pete Su</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-overview"></a>Overview</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using Templates in OpenACS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="dev-guide.html" title="Chapter 11. Development Reference"><link rel="previous" href="db-api.html" title="The OpenACS Database Access API"><link rel="next" href="permissions.html" title="Groups, Context, Permissions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><th width="60%" align="center">Chapter 11. Development Reference</th><td width="20%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="templates"></a>Using Templates in OpenACS</h2></div></div></div> + + + +<span style="color: red"><authorblurb> +<p>By Pete Su</p> +</authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-overview"></a>Overview</h3></div></div></div> + + + +<p> The OpenACS Template System (ATS) is designed to allow developers to cleanly separate <span class="emphasis"><em>application logic</em></span> from <span class="emphasis"><em>display logic</em></span>. The intent is to have all of the logic related to @@ -11,7 +20,9 @@ application in another place. This gives developer's quicker customization and easier upgrades, and also allows developers and graphic designers to work more independently. -</p><p> +</p> + +<p> In ATS, you write two files for every user-visible page in the system. One is a plain <code class="computeroutput">.tcl</code> file and the other is a special <code class="computeroutput">.adp</code> file. The <code class="computeroutput">.tcl</code> file runs a @@ -21,15 +32,26 @@ them available to the <code class="computeroutput">.adp</code> file, or the display part of the template, which is written in a combination of HTML, special template related tags, and data source substitutions. -</p><p> +</p> + +<p> In the overall context of our example OpenACS Notes application, this document will show you how to set up a simple templated page that displays a form to the user for entering new notes into the system. In later sections of the DG, we'll discuss how to develop the pages that actually add notes to the database, how to provide a separate instance of the Notes application to every user and how to design appropriate access control policies for the system. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-entering-notes"></a>Entering Notes</h3></div></div></div><p> +</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-entering-notes"></a>Entering Notes</h3></div></div></div> + + + +<p> In order for the Notes application to be useful, we have to allow users to enter data into the database. Typically, this takes two pages: one that displays a form for data entry, and another page that @@ -38,14 +60,20 @@ build the first of these pages. This isn't a very interesting use of the system since we won't be displaying much data, but we'll cover more on that end later. -</p><p> +</p> + +<p> The <code class="computeroutput">.tcl</code> file for the form entry template is pretty simple. Here, the only thing we need from the database is a new ID for the note object to be inserted. Open up a file called <code class="computeroutput">note-add.tcl</code> in the <code class="computeroutput">ROOT/packages/notes/www</code> directory, and put the following code in it: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + ad_page_contract { Form to add a note in OpenACS Notes. @@ -76,9 +104,14 @@ ad_return_template "note-add" -</pre><p> +</pre> + + +<p> Some things to note about this code: -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +</p> + +<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> The procedure <a class="link" href="tcl-doc.html#tcl-doc-ad-page-contract" title="ad_page_contract">ad_page_contract</a> is always the first thing a <code class="computeroutput">.tcl</code> file calls, if it's under the www/ directory (i.e. not a Tcl library file). It does validation @@ -103,14 +136,20 @@ properties that have been processed. By default, the template system will look for a file by the same name as the <code class="computeroutput">.tcl</code> file that just ran, but with an <code class="computeroutput">.adp</code> extension. -</p></li></ul></div><p> +</p></li></ul></div> + +<p> Next we write the corresponding <code class="computeroutput">.adp</code> page. This page outputs HTML for the form, and also contains placeholders whose values are substituted in from the properties set up by the <code class="computeroutput">.tcl</code> file. Create a file called <code class="computeroutput">note-add.adp</code> in your editor, and insert this text: -</p><pre class="programlisting"> +</p> + + +<pre class="programlisting"> + <master src="master"> <property name="title">@page_title;literal@</property> <property name="context_bar">@context_bar;literal@</property> @@ -129,19 +168,33 @@ </p> </form> -</pre><p> +</pre> + + +<p> The main point to note here is: when you want to substitute a value into a page, you put the name of the data source between two "@" characters. Another point to note is the use of a master template: Master templates allow you do centralize display code that is used throughout an application in a single file. In this case, we intend to have a master template that does the standard page headers and footers for us -</p><p> +</p> + +<p> After putting all these files into <code class="computeroutput">ROOT/packages/notes/www</code>, you should be able to go to <code class="computeroutput">/notes/</code> URL for your server and see the input form. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-summary"></a>Summary</h3></div></div></div><p> +</p> + + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-summary"></a>Summary</h3></div></div></div> + + + +<p> Templates separate application logic from display logic by requiring the developer to write pages in two stages, one file for database queries and application logic, and another for display. In OpenACS, the @@ -152,6 +205,17 @@ inserting properties into the text of the page. Later on we'll get into templates more deeply, and show how to use database queries as data sources. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-documentation"></a>Documentation</h3></div></div></div><p> +</p> + +</div> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="templates-documentation"></a>Documentation</h3></div></div></div> + +<p> <a class="ulink" href="/doc/acs-templating/" target="_top">Templating system documentation</a> -</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr><tr><td width="40%" align="left">The OpenACS Database Access API </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Groups, Context, Permissions</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</p> +<p><span class="cvstag">($Id$)</span></p> + +</div> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="db-api.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="permissions.html">Next</a></td></tr><tr><td width="40%" align="left">The OpenACS Database Access API </td><td width="20%" align="center"><a accesskey="u" href="dev-guide.html">Up</a></td><td width="40%" align="right"> Groups, Context, Permissions</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -19,7 +19,7 @@ <p>Dedicated admin pages. If you want admins to have access to data that users aren't interested in or aren't allowed to see you will need dedicated admin pages. The conventional place to put -those dedicated admin pages is in the <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin</code> +those dedicated admin pages is in the <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin</code> directory.</p><pre class="screen"> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>mkdir admin</code></strong> </pre><pre class="screen"> @@ -71,7 +71,7 @@ a nasty "You don't have permission to access this page" message.</p><p>In order to display the link to the admin page only to users that have admin privileges add the following code near the top of -<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.tcl</code>:</p><pre class="programlisting"> +<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.tcl</code>:</p><pre class="programlisting"> set package_id [ad_conn package_id] @@ -82,7 +82,7 @@ set admin_url "admin" set admin_title Administration } -</pre><p>In <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.adp</code> +</pre><p>In <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.adp</code> put:</p><pre class="programlisting"> <if \@admin_p\@ ne nil> <a href="\@admin_url\@">\@admin_title\@</a> Index: openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html 7 Aug 2017 23:47:52 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/tutorial-admin-pages.html 8 Nov 2017 09:42:12 -0000 1.16 @@ -1,7 +1,10 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Admin Pages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-comments.html" title="Adding Comments"><link rel="next" href="tutorial-categories.html" title="Categories"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-comments.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-categories.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-admin-pages"></a>Admin Pages</h2></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Admin Pages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-comments.html" title="Adding Comments"><link rel="next" href="tutorial-categories.html" title="Categories"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-comments.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-categories.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-admin-pages"></a>Admin Pages</h2></div></div></div> + + <p> There are at least two flavors of admin user interface: - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Admins use same pages as all other users, except + </p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Admins use same pages as all other users, except that they are offered admin links and buttons where appropriate. For example, if admins have privilege to bulk-delete items you could provide checkboxes next to every item seen on a list and the @@ -10,24 +13,31 @@ access to data that users aren't interested in or aren't allowed to see you will need dedicated admin pages. The conventional place to put those dedicated admin pages is in the - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin</code> + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin</code> directory. - </p><pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>mkdir admin</code></strong></pre><pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cd admin</code></strong></pre><p> + </p> +<pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>mkdir admin</code></strong></pre> +<pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cd admin</code></strong></pre> + <p> Even if your application doesn't need any admin pages of its own you will usually need at least one simple page with a bunch of links to existing administration UI such as Category Management or standard Parameters UI. Adding the link to Category Management is described in the section on categories. The listing below adds a link to the Parameters UI of our package. - </p><pre class="screen">[$OPENACS_SERVICE_NAME admin]$ <strong class="userinput"><code>vi index.adp</code></strong></pre><pre class="programlisting"> + </p> +<pre class="screen">[$OPENACS_SERVICE_NAME admin]$ <strong class="userinput"><code>vi index.adp</code></strong></pre> +<pre class="programlisting"> <master> <property name="title">@title;noquote@</property> <property name="context">@context;noquote@</property> <ul class="action-links"> <li><a href="@parameters_url@" title="Set parameters" class="action_link">Set parameters</a></li> </ul> -</pre><pre class="screen">[$OPENACS_SERVICE_NAME admin]$ <strong class="userinput"><code>vi index.tcl</code></strong></pre><pre class="programlisting"> +</pre> +<pre class="screen">[$OPENACS_SERVICE_NAME admin]$ <strong class="userinput"><code>vi index.tcl</code></strong></pre> +<pre class="programlisting"> ad_page_contract {} { } -properties { context_bar @@ -47,7 +57,9 @@ package_id { return_url [ad_return_url] } }] -</pre><p> +</pre> + +<p> Now that you have the first admin page it would be nice to have a link to it somewhere in the system so that admins don't have to type in the <code class="computeroutput">/admin</code> every time they need to reach it. You @@ -56,11 +68,13 @@ people who are not admins. Besides, some people consider it impolite to first offer a link and then display a nasty "You don't have permission to access this page" message. -</p><p> +</p> +<p> In order to display the link to the admin page only to users that have admin privileges add the following code near the top of -<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.tcl</code>: -</p><pre class="programlisting"> +<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.tcl</code>: +</p> +<pre class="programlisting"> set package_id [ad_conn package_id] @@ -71,11 +85,17 @@ set admin_url "admin" set admin_title Administration } -</pre><p> +</pre> +<p> In -<code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.adp</code> put: -</p><pre class="programlisting"> +<code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.adp</code> put: +</p> +<pre class="programlisting"> <if @admin_p@ ne nil> <a href="@admin_url@">@admin_title@</a> </if> -</pre></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-comments.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-categories.html">Next</a></td></tr><tr><td width="40%" align="left">Adding Comments </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Categories</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + + </li></ul></div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-comments.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-categories.html">Next</a></td></tr><tr><td width="40%" align="left">Adding Comments </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Categories</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -30,11 +30,9 @@ scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics">Future Topics</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>This tutorial covers topics which are not essential to creating +</div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><p>This tutorial covers topics which are not essential to creating a minimal working package. Each section can be used independently of all of the others; all sections assume that you've completed the basic tutorial.</p> Index: openacs-4/packages/acs-core-docs/www/tutorial-advanced.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-advanced.html,v diff -u -r1.36 -r1.37 --- openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 7 Aug 2017 23:47:52 -0000 1.36 +++ openacs-4/packages/acs-core-docs/www/tutorial-advanced.html 8 Nov 2017 09:42:12 -0000 1.37 @@ -1,8 +1,53 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 10. Advanced Topics</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="tutorial-debug.html" title="Debugging and Automated Testing"><link rel="next" href="tutorial-specs.html" title="Write the Requirements and Design Specs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-specs.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="tutorial-advanced"></a>Chapter 10. Advanced Topics</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-specs.html">Write the Requirements and Design Specs</a></span></dt><dt><span class="sect1"><a href="tutorial-cvs.html">Add the new package to CVS</a></span></dt><dt><span class="sect1"><a href="tutorial-etp-templates.html">OpenACS Edit This Page Templates</a></span></dt><dt><span class="sect1"><a href="tutorial-comments.html">Adding Comments</a></span></dt><dt><span class="sect1"><a href="tutorial-admin-pages.html">Admin Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-categories.html">Categories</a></span></dt><dt><span class="sect1"><a href="profile-code.html">Profile your code</a></span></dt><dt><span class="sect1"><a href="tutorial-distribute.html">Prepare the package for distribution.</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrades.html">Distributing upgrades of your package</a></span></dt><dt><span class="sect1"><a href="tutorial-notifications.html">Notifications</a></span></dt><dt><span class="sect1"><a href="tutorial-hierarchical.html">Hierarchical data</a></span></dt><dt><span class="sect1"><a href="tutorial-vuh.html">Using .vuh files for pretty urls</a></span></dt><dt><span class="sect1"><a href="tutorial-css-layout.html">Laying out a page with CSS instead of tables</a></span></dt><dt><span class="sect1"><a href="tutorial-html-email.html">Sending HTML email from your application</a></span></dt><dt><span class="sect1"><a href="tutorial-caching.html">Basic Caching</a></span></dt><dt><span class="sect1"><a href="tutorial-schedule-procs.html">Scheduled Procedures</a></span></dt><dt><span class="sect1"><a href="tutorial-wysiwyg-editor.html">Enabling WYSIWYG</a></span></dt><dt><span class="sect1"><a href="tutorial-parameters.html">Adding in parameters for your package</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrade-scripts.html">Writing upgrade scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database.html">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics.html">Future Topics</a></span></dt></dl></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>This tutorial covers topics which are not essential to +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 10. Advanced Topics</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="tutorial-debug.html" title="Debugging and Automated Testing"><link rel="next" href="tutorial-specs.html" title="Write the Requirements and Design Specs"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-specs.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="tutorial-advanced"></a>Chapter 10. Advanced Topics</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-specs.html">Write the Requirements and Design Specs</a></span></dt><dt><span class="sect1"><a href="tutorial-cvs.html">Add the new package to CVS</a></span></dt><dt><span class="sect1"><a href="tutorial-etp-templates.html">OpenACS Edit This Page Templates</a></span></dt><dt><span class="sect1"><a href="tutorial-comments.html">Adding Comments</a></span></dt><dt><span class="sect1"><a href="tutorial-admin-pages.html">Admin Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-categories.html">Categories</a></span></dt><dt><span class="sect1"><a href="profile-code.html">Profile your code</a></span></dt><dt><span class="sect1"><a href="tutorial-distribute.html">Prepare the package for distribution.</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrades.html">Distributing upgrades of your package</a></span></dt><dt><span class="sect1"><a href="tutorial-notifications.html">Notifications</a></span></dt><dt><span class="sect1"><a href="tutorial-hierarchical.html">Hierarchical data</a></span></dt><dt><span class="sect1"><a href="tutorial-vuh.html">Using .vuh files for pretty urls</a></span></dt><dt><span class="sect1"><a href="tutorial-css-layout.html">Laying out a page with CSS instead of tables</a></span></dt><dt><span class="sect1"><a href="tutorial-html-email.html">Sending HTML email from your application</a></span></dt><dt><span class="sect1"><a href="tutorial-caching.html">Basic Caching</a></span></dt><dt><span class="sect1"><a href="tutorial-schedule-procs.html">Scheduled Procedures</a></span></dt><dt><span class="sect1"><a href="tutorial-wysiwyg-editor.html">Enabling WYSIWYG</a></span></dt><dt><span class="sect1"><a href="tutorial-parameters.html">Adding in parameters for your package</a></span></dt><dt><span class="sect1"><a href="tutorial-upgrade-scripts.html">Writing upgrade scripts</a></span></dt><dt><span class="sect1"><a href="tutorial-second-database.html">Connect to a second database</a></span></dt><dt><span class="sect1"><a href="tutorial-future-topics.html">Future Topics</a></span></dt></dl></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + <p>This tutorial covers topics which are not essential to creating a minimal working package. Each section can be used independently of all of the others; all sections assume that - you've completed the basic tutorial.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-specs.html">Next</a></td></tr><tr><td width="40%" align="left">Debugging and Automated Testing </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Write the Requirements and Design Specs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + you've completed the basic tutorial.</p> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-debug.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-specs.html">Next</a></td></tr><tr><td width="40%" align="left">Debugging and Automated Testing </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Write the Requirements and Design Specs</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-caching.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-caching.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-caching.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-caching.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,10 +9,7 @@ rightLink="tutorial-schedule-procs" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-caching" id="tutorial-caching"></a>Basic Caching</h2></div></div></div><div class="authorblurb"> -<p>Based on <a class="ulink" href="http://openacs.org/forums/message-view?message_id=157448" target="_top">a post by Dave Bauer</a>.</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Caching using the database API is described in the database API +<a name="tutorial-caching" id="tutorial-caching"></a>Basic Caching</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">Based on <a class="ulink" href="http://openacs.org/forums/message-view?message_id=157448" target="_top">a post by Dave Bauer</a>.</span></p><span style="color: red"></authorblurb></span><p>Caching using the database API is described in the database API tutorial.</p><p>Caching using util_memoize</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Implement your proc as <code class="computeroutput">my_proc_not_cached</code> </p></li><li class="listitem"> Index: openacs-4/packages/acs-core-docs/www/tutorial-caching.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-caching.html,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-caching.html 7 Aug 2017 23:47:52 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-caching.html 8 Nov 2017 09:42:12 -0000 1.13 @@ -1,11 +1,33 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Basic Caching</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-html-email.html" title="Sending HTML email from your application"><link rel="next" href="tutorial-schedule-procs.html" title="Scheduled Procedures"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-html-email.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-schedule-procs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-caching"></a>Basic Caching</h2></div></div></div><div class="authorblurb"><p>Based on <a class="ulink" href="http://openacs.org/forums/message-view?message_id=157448" target="_top">a post by Dave Bauer</a>.</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Caching using the database API is described in the database API tutorial.</p><p>Caching using util_memoize</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Implement your proc as <code class="computeroutput">my_proc_not_cached</code></p></li><li class="listitem"><p>Create a version of your proc called <code class="computeroutput">my_proc</code> which wraps the non-cached version in the caching mechanism. In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on. The wrapper also uses the list command, to ensure that the arguments get passed correctly and to prevent commands passed in as arguments from being executed.</p><pre class="programlisting">ad_proc my_proc {-foo} { +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Basic Caching</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-html-email.html" title="Sending HTML email from your application"><link rel="next" href="tutorial-schedule-procs.html" title="Scheduled Procedures"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-html-email.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-schedule-procs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-caching"></a>Basic Caching</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>Based on <a class="ulink" href="http://openacs.org/forums/message-view?message_id=157448" target="_top">a post by Dave Bauer</a>.</p> + </authorblurb></span> + <p>Caching using the database API is described in the database API tutorial.</p> + <p>Caching using util_memoize</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Implement your proc as <code class="computeroutput">my_proc_not_cached</code></p> + </li><li class="listitem"> + <p>Create a version of your proc called <code class="computeroutput">my_proc</code> which wraps the non-cached version in the caching mechanism. In this example, my_proc_not_cached takes one argument, -foo, so the wrapper passes that on. The wrapper also uses the list command, to ensure that the arguments get passed correctly and to prevent commands passed in as arguments from being executed.</p> + <pre class="programlisting">ad_proc my_proc {-foo} { Get a cached version of my_proc. } { return [util_memoize [list my_proc_not_cached -foo $foo]] -}</pre></li><li class="listitem"><p>In your code, always call my_proc. There will be a separate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached separately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.</p></li><li class="listitem"><p> - The cached material will of course become obsolete over time. There are two ways to handle this.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Timed Expiration: pass in max_age to util_memoize. If the content is older than max_age, it will be re-generated.</p></li><li class="listitem"><p> - Direct Flushing. In any proc which invalidates the cached content, call util_memoize_flush my_proc_not_cached args.</p></li></ul></div></li><li class="listitem"><p>If you are correctly flushing the cached value, then it will need to be reloaded. You may wish to pre-load it, so that the loading delay does not impact users. If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it. Or, you can call (and discard) it immediately after flushing it.</p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-html-email.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-schedule-procs.html">Next</a></td></tr><tr><td width="40%" align="left">Sending HTML email from your application </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Scheduled Procedures</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +}</pre> + </li><li class="listitem"> + <p>In your code, always call my_proc. There will be a separate cache item for each unique call to my_proc_not_cached so that calls with different arguments are cached separately. You can flush the cache for each cache key by calling util_memoize_flush my_proc_not_cached args.</p> + </li><li class="listitem"> + <p> + The cached material will of course become obsolete over time. There are two ways to handle this.</p> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Timed Expiration: pass in max_age to util_memoize. If the content is older than max_age, it will be re-generated.</p> + </li><li class="listitem"> + <p> + Direct Flushing. In any proc which invalidates the cached content, call util_memoize_flush my_proc_not_cached args.</p> + </li></ul></div> + </li><li class="listitem"> + <p>If you are correctly flushing the cached value, then it will need to be reloaded. You may wish to pre-load it, so that the loading delay does not impact users. If you have a sequence of pages, you could call the cached proc in advance, to increase the chances that it's loaded and current when the user reaches it. Or, you can call (and discard) it immediately after flushing it.</p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-html-email.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-schedule-procs.html">Next</a></td></tr><tr><td width="40%" align="left">Sending HTML email from your application </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Scheduled Procedures</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-categories.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-categories.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="profile-code" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-categories" id="tutorial-categories"></a>Categories</h2></div></div></div><div class="authorblurb"> -<p>extended by <a class="ulink" href="mailto:nima.mazloumi\@gmx.de" target="_top">Nima Mazloumi</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>You can associate any ACS Object with one or more categories. In +<a name="tutorial-categories" id="tutorial-categories"></a>Categories</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">extended by <a class="ulink" href="mailto:nima.mazloumi\@gmx.de" target="_top">Nima +Mazloumi</a> +</span></p><span style="color: red"></authorblurb></span><p>You can associate any ACS Object with one or more categories. In this tutorial we'll show how to equip your application with user interface to take advantage of the Categories service.</p><p>We'll start by installing the Categories service. Go to <code class="computeroutput">/acs/admin</code> and install it. This @@ -33,11 +31,11 @@ advantage of the Categories service there needs to be a way for administrators of your application to choose which category trees are applicable for the application.</p><p>The way to achieve this is is to provide a link to the Category -Management pages. Add the following snippet to your <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.tcl</code> +Management pages. Add the following snippet to your <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.tcl</code> file:</p><pre class="programlisting"> set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }] -</pre><p>and the following snippet to your <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.adp</code> +</pre><p>and the following snippet to your <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.adp</code> file:</p><pre class="programlisting"> <a href="\@category_map_url\@">#categories.Site_wide_Categories#</a> Index: openacs-4/packages/acs-core-docs/www/tutorial-categories.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-categories.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/tutorial-categories.html 7 Aug 2017 23:47:52 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/tutorial-categories.html 8 Nov 2017 09:42:12 -0000 1.16 @@ -1,22 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Categories</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-admin-pages.html" title="Admin Pages"><link rel="next" href="profile-code.html" title="Profile your code"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-admin-pages.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="profile-code.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-categories"></a>Categories</h2></div></div></div><div class="authorblurb"><p>extended by <a class="ulink" href="mailto:nima.mazloumi@gmx.de" target="_top">Nima Mazloumi</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>You can associate any ACS Object with one or more categories. +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Categories</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-admin-pages.html" title="Admin Pages"><link rel="next" href="profile-code.html" title="Profile your code"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-admin-pages.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="profile-code.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-categories"></a>Categories</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>extended by <a class="ulink" href="mailto:nima.mazloumi@gmx.de" target="_top">Nima Mazloumi</a></p> + </authorblurb></span> + <p>You can associate any ACS Object with one or more categories. In this tutorial we'll show how to equip your application with user interface to take advantage of the Categories service. - </p><p> + </p> + <p> We'll start by installing the Categories service. Go to <code class="computeroutput">/acs/admin</code> and install it. This step won't be necessary for the users of your applications because you'll create a dependency with the Package Manager which will take care that the Categories service always gets installed when your application gets installed. - </p><p> + </p> + <p> Now that we have installed the Categories service we can proceed to modifying our application so that it can take advantage of it. We'll do it in three steps: - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> The Categories service provides a mechanism to associate one or more <span class="emphasis"><em>category trees</em></span> that are relevant to your application. One example of such tree is a tree of @@ -26,20 +31,25 @@ can take advantage of the Categories service there needs to be a way for administrators of your application to choose which category trees are applicable for the application. - </p><p> + </p> + <p> The way to achieve this is is to provide a link to the Category Management pages. Add the following snippet to your - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.tcl</code> + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.tcl</code> file: - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> set category_map_url [export_vars -base "[site_node::get_package_url -package_key categories]cadmin/one-object" { { object_id $package_id } }] - </pre><p> + </pre> + <p> and the following snippet to your - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/admin/index.adp</code> + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/admin/index.adp</code> file: - </p><pre class="programlisting"> + </p> + <pre class="programlisting"> <a href="@category_map_url@">#categories.Site_wide_Categories#</a> - </pre><p>The link created by the above code (<code class="computeroutput">category_map_url</code>) + </pre> + <p>The link created by the above code (<code class="computeroutput">category_map_url</code>) will take the admin to the generic admin UI where he can pick category trees that make sense for this application. The same UI also includes facilities to build and edit @@ -61,7 +71,8 @@ form builder to <code class="computeroutput">note-edit.tcl</code>. To achieve this we'll need to use the <code class="computeroutput">-extend</code> switch to the <code class="computeroutput">ad_form</code> command. Here's the "meat" of the - <code class="computeroutput">note-edit.tcl</code> page:</p><pre class="programlisting"> + <code class="computeroutput">note-edit.tcl</code> page:</p> + <pre class="programlisting"> # extend the form to support categories set package_id [ad_conn package_id] @@ -81,15 +92,18 @@ ad_returnredirect "." ad_script_abort } - </pre><p>While the <code class="computeroutput">category::ad_form::add_widgets</code> proc is taking + </pre> + <p>While the <code class="computeroutput">category::ad_form::add_widgets</code> proc is taking care to extend your form with associated categories you need to ensure that your items are mapped to the corresponding category object yourself. Also since the categories package knows nothing from your objects you have to keep the <code class="computeroutput">acs_named_objects</code> table updated with any changes taking place. We use the items title so that they are listed in the categories browser by title.</p><p>Make sure that you also delete these entries if your item is delete. Add this to - your corresponding delete page:</p><pre class="programlisting"> + your corresponding delete page:</p> + <pre class="programlisting"> db_dml delete_named_object "delete from acs_named_objects where object_id = :item_id" - </pre><p><code class="computeroutput">note-edit.tcl</code> requires a + </pre> + <p><code class="computeroutput">note-edit.tcl</code> requires a <code class="computeroutput">note_id</code> to determine which record should be deleted. It also looks for a confirmation variable, which should initially be absert. If it is absent, we create a form to @@ -101,7 +115,11 @@ <code class="computeroutput">note_id</code> and <code class="computeroutput">confirm_p</code>. If confirm_p is present, we delete the record, set redirection back to the index, and abort -script execution.</p><p>The database commands:</p><pre class="screen">[$OPENACS_SERVICE_NAME@yourserver www]$ <strong class="userinput"><code>emacs note-delete.xql</code></strong></pre><pre class="programlisting"><?xml version="1.0"?> +script execution.</p> + + <p>The database commands:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME@yourserver www]$ <strong class="userinput"><code>emacs note-delete.xql</code></strong></pre> + <pre class="programlisting"><?xml version="1.0"?> <queryset> <fullquery name="do_delete"> <querytext> @@ -113,29 +131,41 @@ select samplenote__name(:note_id) </querytext> </fullquery> -</queryset></pre><p>And the adp page:</p><pre class="screen">[$OPENACS_SERVICE_NAME@yourserver www]$ <strong class="userinput"><code>emacs note-delete.adp</code></strong></pre><pre class="programlisting"> +</queryset></pre> + <p>And the adp page:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME@yourserver www]$ <strong class="userinput"><code>emacs note-delete.adp</code></strong></pre> + <pre class="programlisting"> <master> <property name="title">@title@</property> <property name="context">{@title@}</property> <h2>@title@</h2> <formtemplate id="note-del-confirm"></formtemplate> -</form></pre><p>The ADP is very simple. The +</form></pre> + <p>The ADP is very simple. The <code class="computeroutput">formtemplate</code> tag outputs the HTML form generated by the ad_form command with the matching name. Test it by adding the new files in the APM and then deleting a few - samplenotes.</p></li><li class="listitem"><p>We will now make categories optional on package instance level and + samplenotes.</p> + </li><li class="listitem"><p>We will now make categories optional on package instance level and also add a configuration page to allow the package admin to enable/disable categories for his package. - </p><p>Go to the APM and create a number parameter with the name "<code class="computeroutput">EnableCategoriesP</code>" - and the default value "<code class="computeroutput">0</code>".</p><p>Add the following lines to your <code class="computeroutput">index.tcl</code>:</p><pre class="programlisting"> + </p> + <p>Go to the APM and create a number parameter with the name "<code class="computeroutput">EnableCategoriesP</code>" + and the default value "<code class="computeroutput">0</code>".</p> + <p>Add the following lines to your <code class="computeroutput">index.tcl</code>:</p> + <pre class="programlisting"> set return_url [ns_conn url] set use_categories_p [parameter::get -parameter "EnableCategoriesP"] - </pre><p>Change your to this:</p><pre class="programlisting"> + </pre> + <p>Change your to this:</p> + <pre class="programlisting"> <a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a> <if @use_categories_p@> <a href="@category_map_url@">#categories.Site_wide_Categories#</a> </if> - </pre><p>Now create a configure page</p><pre class="programlisting"> + </pre> + <p>Now create a configure page</p> + <pre class="programlisting"> ad_page_contract { This page allows an admin to change the categories usage mode. } { @@ -160,41 +190,51 @@ ns_returnredirect $return_url } } - </pre><p>and add this to its corresponding ADP page</p><pre class="programlisting"> + </pre> + <p>and add this to its corresponding ADP page</p> + <pre class="programlisting"> <master> <property name="title">@title@</property> <property name="context">@context@</property> <formtemplate id="categories_mode"></formtemplate> - </pre><p>Reference this page from your admin page</p><pre class="programlisting"> + </pre> + <p>Reference this page from your admin page</p> + <pre class="programlisting"> #TCL: set return_url [ad_conn url] #ADP: <a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a> - </pre><p>Change the <code class="computeroutput">note-edit.tcl</code>:</p><pre class="programlisting"> + </pre> + <p>Change the <code class="computeroutput">note-edit.tcl</code>:</p> + <pre class="programlisting"> # Use Categories? set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] if { $use_categories_p == 1 } { # YOUR NEW FORM DEFINITION } else { # YOUR OLD FORM DEFINITION } - </pre></li><li class="listitem"><p>You can filter your notes using categories. The below example does not support multiple + </pre> + </li><li class="listitem"><p>You can filter your notes using categories. The below example does not support multiple filters and displays a category in a flat format.</p><p>The first step is to define the optional parameter <code class="computeroutput">category_id</code> for - <code class="computeroutput">index.tcl</code>:</p><pre class="programlisting"> + <code class="computeroutput">index.tcl</code>:</p> + <pre class="programlisting"> ad_page_contract { YOUR TEXT } { YOURPARAMS {category_id:integer,optional {}} } - </pre><p>Now you have to check whether categories are enabled or not. If this is the case and a + </pre> + <p>Now you have to check whether categories are enabled or not. If this is the case and a category id is passed you need to extend your sql select query to support filtering. One way would be to extend the <code class="computeroutput">mfp::note::get</code> proc to support two more swiches <code class="computeroutput">-where_clause</code> and - <code class="computeroutput">-from_clause</code>.</p><pre class="programlisting"> + <code class="computeroutput">-from_clause</code>.</p> + <pre class="programlisting"> set use_categories_p [parameter::get -parameter "EnableCategoriesP" -default 0] if { $use_categories_p == 1 && $category_id ne "" } { @@ -217,8 +257,10 @@ } else { # OLD STUFF } - </pre><p>Also you need to make sure that the user can see the corresponding categories. Add the following - snippet to the end of your index page:</p><pre class="programlisting"> + </pre> + <p>Also you need to make sure that the user can see the corresponding categories. Add the following + snippet to the end of your index page:</p> + <pre class="programlisting"> # Site-Wide Categories if { $use_categories_p == 1} { set package_url [ad_conn package_url] @@ -250,7 +292,9 @@ set tree_name [category_tree::get_name $tree_id] } } - </pre><p>and to the corresponding index ADP page:</p><pre class="programlisting"> + </pre> + <p>and to the corresponding index ADP page:</p> + <pre class="programlisting"> <if @use_categories_p@> <multiple name="categories"> <h2>@categories.tree_name@ @@ -259,12 +303,17 @@ </group> </multiple> <a href="@package_url@view?@YOURPARAMS@">All Items</if> - </pre><p>Finally you need a an <code class="computeroutput">index.vuh</code> in your - www folder to rewrite the URLs correctly, <a class="xref" href="tutorial-vuh.html" title="Using .vuh files for pretty urls">the section called “Using .vuh files for pretty urls”</a>:</p><pre class="programlisting"> + </pre> + <p>Finally you need a an <code class="computeroutput">index.vuh</code> in your + www folder to rewrite the URLs correctly, <a class="xref" href="tutorial-vuh.html" title="Using .vuh files for pretty urls">the section called “Using .vuh files for pretty urls”</a>:</p> + <pre class="programlisting"> set url /[ad_conn extra_url] if {[regexp {^/+cat/+([^/]+)/*} $url ignore_whole category_id]} { rp_form_put category_id $category_id } rp_internal_redirect "/packages/YOURPACKAGE/www/index" - </pre><p>Now when ever the user select a category only notes that belong to this category are displayed.</p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-admin-pages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="profile-code.html">Next</a></td></tr><tr><td width="40%" align="left">Admin Pages </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Profile your code</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + <p>Now when ever the user select a category only notes that belong to this category are displayed.</p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-admin-pages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="profile-code.html">Next</a></td></tr><tr><td width="40%" align="left">Admin Pages </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Profile your code</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-comments.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-comments.html,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/tutorial-comments.html 7 Aug 2017 23:47:52 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/tutorial-comments.html 8 Nov 2017 09:42:12 -0000 1.17 @@ -1,23 +1,34 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adding Comments</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-etp-templates.html" title="OpenACS Edit This Page Templates"><link rel="next" href="tutorial-admin-pages.html" title="Admin Pages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-etp-templates.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-admin-pages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-comments"></a>Adding Comments</h2></div></div></div><p>You can track comments for any ACS Object. Here we'll track +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adding Comments</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-etp-templates.html" title="OpenACS Edit This Page Templates"><link rel="next" href="tutorial-admin-pages.html" title="Admin Pages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-etp-templates.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-admin-pages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-comments"></a>Adding Comments</h2></div></div></div> + + <p>You can track comments for any ACS Object. Here we'll track comments for notes. On the note-edit.tcl/adp pair, which is used to display individual notes, we want to put a link to add comments at the bottom of the screen. If there are any comments, we want to - show them.</p><p>First, we need to generate a url for adding comments. In note-edit.tcl:</p><pre class="programlisting"> + show them.</p> + <p>First, we need to generate a url for adding comments. In note-edit.tcl:</p> + <pre class="programlisting"> set comment_add_url [export_vars -base [general_comments_package_url]comment-add { { object_id $note_id } { object_name $title } { return_url "[ad_conn url]?[ad_conn query]"} }] - </pre><p>This calls a global, public Tcl function that the + </pre> + <p>This calls a global, public Tcl function that the general_comments package registered, to get its url. You then embed in that url the id of the note and its title, and set the return_url to the current url so that the user can return after - adding a comment.</p><p>We need to create html that shows any existing comments. - We do this with another general_comments function:</p><pre class="programlisting">set comments_html [general_comments_get_comments - -print_content_p 1 $note_id]</pre><p>First, we pass in an optional parameter that that says to actually + adding a comment.</p> + <p>We need to create html that shows any existing comments. + We do this with another general_comments function:</p> + <pre class="programlisting">set comments_html [general_comments_get_comments + -print_content_p 1 $note_id]</pre> + <p>First, we pass in an optional parameter that that says to actually show the contents of the comments, instead of just the fact that there are comments. Then you pass the note id, which is also the - acs_object id.</p><p>We put our two new variables in the note-edit.adp - page.</p><pre class="programlisting"><a href="@comment_add_url@">Add a comment</a> - @comments_html@</pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-etp-templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-admin-pages.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Edit This Page Templates </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Admin Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + acs_object id.</p> + <p>We put our two new variables in the note-edit.adp + page.</p> + <pre class="programlisting"><a href="@comment_add_url@">Add a comment</a> + @comments_html@</pre> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-etp-templates.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-admin-pages.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Edit This Page Templates </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Admin Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -12,7 +12,7 @@ <a name="tutorial-css-layout" id="tutorial-css-layout"></a>Laying out a page with CSS instead of tables</h2></div></div></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592101677160" id="idp140592101677160"></a>.LRN home page with table-based +<a name="idp140623161993752" id="idp140623161993752"></a>.LRN home page with table-based layout</h3></div></div></div><div class="mediaobject" align="center"><img src="images/dotlrn-style-1.png" align="middle"></div><p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-1" target="_top">full source</a>)</p><pre class="programlisting"> <table border="0" width="100%"> <tr> @@ -40,7 +40,7 @@ </pre> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592101682168" id="idp140592101682168"></a>.LRN Home with CSS-based layout</h3></div></div></div><div class="mediaobject" align="center"><img src="images/dotlrn-style-3.png" align="middle"></div><p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-2" target="_top">full source</a>)</p><pre class="programlisting"> +<a name="idp140623163102936" id="idp140623163102936"></a>.LRN Home with CSS-based layout</h3></div></div></div><div class="mediaobject" align="center"><img src="images/dotlrn-style-3.png" align="middle"></div><p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-2" target="_top">full source</a>)</p><pre class="programlisting"> <div class="left"> <div class="portlet-wrap-shadow"> <div class="portlet-wrap-bl"> Index: openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html,v diff -u -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html 7 Aug 2017 23:47:52 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/tutorial-css-layout.html 8 Nov 2017 09:42:12 -0000 1.14 @@ -1,5 +1,11 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Laying out a page with CSS instead of tables</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-vuh.html" title="Using .vuh files for pretty urls"><link rel="next" href="tutorial-html-email.html" title="Sending HTML email from your application"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-vuh.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-html-email.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-css-layout"></a>Laying out a page with CSS instead of tables</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592101677160"></a>.LRN home page with table-based layout</h3></div></div></div><div class="mediaobject" align="center"><img src="images/dotlrn-style-1.png" align="middle"></div><p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-1.html" target="_top">full source</a>)</p><pre class="programlisting"><table border="0" width="100%"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Laying out a page with CSS instead of tables</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-vuh.html" title="Using .vuh files for pretty urls"><link rel="next" href="tutorial-html-email.html" title="Sending HTML email from your application"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-vuh.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-html-email.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-css-layout"></a>Laying out a page with CSS instead of tables</h2></div></div></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623161993752"></a>.LRN home page with table-based layout</h3></div></div></div> + + <div class="mediaobject" align="center"><img src="images/dotlrn-style-1.png" align="middle"></div> + <p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-1.html" target="_top">full source</a>)</p> + <pre class="programlisting"><table border="0" width="100%"> <tr> <td valign="top" width="50%"> <table class="element" border="0" cellpadding="0" cellspacing="0" width="100%"> @@ -21,12 +27,22 @@ <table border="0" bgcolor="white" cellpadding="0" cellspacing="0" width="100%"> <tr> <td class=element-text> - MBA 101</pre></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592101682168"></a>.LRN Home with CSS-based layout</h3></div></div></div><div class="mediaobject" align="center"><img src="images/dotlrn-style-3.png" align="middle"></div><p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-2.html" target="_top">full source</a>)</p><pre class="programlisting"><div class="left"> + MBA 101</pre> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623163102936"></a>.LRN Home with CSS-based layout</h3></div></div></div> + + <div class="mediaobject" align="center"><img src="images/dotlrn-style-3.png" align="middle"></div> + <p>A sample of the HTML code (<a class="ulink" href="files/dotlrn-style-2.html" target="_top">full source</a>)</p> + <pre class="programlisting"><div class="left"> <div class="portlet-wrap-shadow"> <div class="portlet-wrap-bl"> <div class="portlet-wrap-tr"> <div class="portlet"> <h2>Groups</h2> <ul> <li> - <a href="#">Class MBA 101</a></pre><p>If the CSS is removed from the file, it looks somewhat different:</p><div class="mediaobject" align="center"><img src="images/dotlrn-style-2.png" align="middle"></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-vuh.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-html-email.html">Next</a></td></tr><tr><td width="40%" align="left">Using .vuh files for pretty urls </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Sending HTML email from your application</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + <a href="#">Class MBA 101</a></pre> + <p>If the CSS is removed from the file, it looks somewhat different:</p> + <div class="mediaobject" align="center"><img src="images/dotlrn-style-2.png" align="middle"></div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-vuh.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-html-email.html">Next</a></td></tr><tr><td width="40%" align="left">Using .vuh files for pretty urls </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Sending HTML email from your application</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -18,13 +18,13 @@ [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cd ..</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cd ..</code></strong> [$OPENACS_SERVICE_NAME packages]$ <strong class="userinput"><code>cvs add myfirstpackage/</code></strong> -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage added to the repository [$OPENACS_SERVICE_NAME packages]$ <strong class="userinput"><code>cd myfirstpackage/</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cvs add www</code></strong> -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www added to the repository [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cd www</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cvs add doc</code></strong> -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc added to the repository [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cd doc</code></strong> [$OPENACS_SERVICE_NAME doc]$ <strong class="userinput"><code>cvs add *</code></strong> cvs add: cannot add special file `CVS'; skipping @@ -49,7 +49,7 @@ cvs add: scheduling file `user-guide.html' for addition cvs add: scheduling file `user-interface.dia' for addition cvs add: scheduling file `user-interface.png' for addition -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc/xml added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc/xml added to the repository cvs add: use 'cvs commit' to add these files permanently [$OPENACS_SERVICE_NAME doc]$ <strong class="userinput"><code>cd xml</code></strong> [$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cvs add Makefile index.xml</code></strong> @@ -62,16 +62,16 @@ cvs commit: Examining www cvs commit: Examining www/doc cvs commit: Examining www/doc/xml -RCS file: /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc/admin-guide.html,v +RCS file: /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc/admin-guide.html,v done Checking in www/doc/admin-guide.html; -/cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc/admin-guide.html,v <-- admin-guide.html +/cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc/admin-guide.html,v <-- admin-guide.html initial revision: 1.1 done <span class="emphasis"><em>(many lines omitted)</em></span> [$OPENACS_SERVICE_NAME myfirstpackage]$ </pre><div class="figure"> -<a name="idp140592099723480" id="idp140592099723480"></a><p class="title"><strong>Figure 10.1. Upgrading a local CVS +<a name="idp140623162867368" id="idp140623162867368"></a><p class="title"><strong>Figure 10.1. Upgrading a local CVS repository</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/development-with-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div></div> </div><br class="figure-break"> </div> Index: openacs-4/packages/acs-core-docs/www/tutorial-cvs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-cvs.html,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 7 Aug 2017 23:47:52 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/tutorial-cvs.html 8 Nov 2017 09:42:12 -0000 1.28 @@ -1,20 +1,23 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Add the new package to CVS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-specs.html" title="Write the Requirements and Design Specs"><link rel="next" href="tutorial-etp-templates.html" title="OpenACS Edit This Page Templates"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-specs.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-etp-templates.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-cvs"></a>Add the new package to CVS</h2></div></div></div><p>Before you do any more work, make sure that your work is +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Add the new package to CVS</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-specs.html" title="Write the Requirements and Design Specs"><link rel="next" href="tutorial-etp-templates.html" title="OpenACS Edit This Page Templates"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-specs.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-etp-templates.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-cvs"></a>Add the new package to CVS</h2></div></div></div> + + <p>Before you do any more work, make sure that your work is protected by putting it all into cvs. The <code class="computeroutput">cvs add</code> command is not recursive, so you'll have to traverse the directory tree manually and add as you go. (<a class="ulink" href="http://www.piskorski.com/docs/cvs-conventions.html" target="_top">More on - CVS</a>)</p><pre class="screen">[$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cd ..</code></strong> + CVS</a>)</p> + <pre class="screen">[$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cd ..</code></strong> [$OPENACS_SERVICE_NAME doc]$ <strong class="userinput"><code>cd ..</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cd ..</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cd ..</code></strong> [$OPENACS_SERVICE_NAME packages]$ <strong class="userinput"><code>cvs add myfirstpackage/</code></strong> -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage added to the repository [$OPENACS_SERVICE_NAME packages]$ <strong class="userinput"><code>cd myfirstpackage/</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cvs add www</code></strong> -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www added to the repository [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cd www</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cvs add doc</code></strong> -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc added to the repository [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>cd doc</code></strong> [$OPENACS_SERVICE_NAME doc]$ <strong class="userinput"><code>cvs add *</code></strong> cvs add: cannot add special file `CVS'; skipping @@ -39,7 +42,7 @@ cvs add: scheduling file `user-guide.html' for addition cvs add: scheduling file `user-interface.dia' for addition cvs add: scheduling file `user-interface.png' for addition -Directory /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc/xml added to the repository +Directory /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc/xml added to the repository cvs add: use 'cvs commit' to add these files permanently [$OPENACS_SERVICE_NAME doc]$ <strong class="userinput"><code>cd xml</code></strong> [$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cvs add Makefile index.xml</code></strong> @@ -52,11 +55,16 @@ cvs commit: Examining www cvs commit: Examining www/doc cvs commit: Examining www/doc/xml -RCS file: /cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc/admin-guide.html,v +RCS file: /cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc/admin-guide.html,v done Checking in www/doc/admin-guide.html; -/cvsroot/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www/doc/admin-guide.html,v <-- admin-guide.html +/cvsroot/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www/doc/admin-guide.html,v <-- admin-guide.html initial revision: 1.1 done <span class="emphasis"><em>(many lines omitted)</em></span> -[$OPENACS_SERVICE_NAME myfirstpackage]$</pre><div class="figure"><a name="idp140592099723480"></a><p class="title"><b>Figure 10.1. Upgrading a local CVS repository</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/development-with-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div></div></div><br class="figure-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-specs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-etp-templates.html">Next</a></td></tr><tr><td width="40%" align="left">Write the Requirements and Design Specs </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> OpenACS Edit This Page Templates</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +[$OPENACS_SERVICE_NAME myfirstpackage]$</pre> + <div class="figure"><a name="idp140623162867368"></a><p class="title"><b>Figure 10.1. Upgrading a local CVS repository</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/development-with-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div> + </div></div><br class="figure-break"> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-specs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-etp-templates.html">Next</a></td></tr><tr><td width="40%" align="left">Write the Requirements and Design Specs </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> OpenACS Edit This Page Templates</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-database.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-database.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-database.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,21 +9,19 @@ rightLink="tutorial-pages" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-database" id="tutorial-database"></a>Setting Up Database Objects</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="tutorial-database" id="tutorial-database"></a>Setting Up Database Objects</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592104860472" id="idp140592104860472"></a>Code the data model</h3></div></div></div><p>We create all database objects with scripts in the <code class="computeroutput">myfirstpackage/sql/</code> directory. All database +<a name="idp140623172585384" id="idp140623172585384"></a>Code the data model</h3></div></div></div><p>We create all database objects with scripts in the <code class="computeroutput">myfirstpackage/sql/</code> directory. All database scripts are database-specific and are thus in either the <code class="computeroutput">myfirstpackage/sql/oracle</code> or <code class="computeroutput">myfirstpackage/sql/postgresql</code> directory. Packages can support Oracle, PostgreSQL, or both. In this tutorial, we will be working with PostgreSQL</p><p>The first file will be <code class="computeroutput">myfirstpackage-create.sql</code>. The package manager requires a file with the name <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">packagekey</span></span>-create.sql</code>, which it -will run automatically when the package in installed. This file +<em class="replaceable"><code>packagekey</code></em>-create.sql</code>, which +it will run automatically when the package in installed. This file should create all tables and views.</p><p>Our package is going to store all of its information in one table. It takes more than just a <code class="computeroutput">CREATE TABLE</code> command, however, because we want to integrate our table with the OpenACS system. By making each @@ -42,16 +40,16 @@ simplify our database creation. (<a class="ulink" href="objects" target="_top">More information about ACS Objects</a>. <a class="ulink" href="/doc/acs-content-repository" target="_top">More information about the Content Repository</a>.)</p><div class="figure"> -<a name="idp140592094116616" id="idp140592094116616"></a><p class="title"><strong>Figure 9.2. Tutorial Data +<a name="idp140623163033192" id="idp140623163033192"></a><p class="title"><strong>Figure 9.2. Tutorial Data Model</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/tutorial-data-model.png" align="middle" alt="Tutorial Data Model"></div></div> </div><br class="figure-break"><p>The top of each sql file has some standard comments, including doc tags such as <code class="computeroutput">\@author</code> which will be picked up by the API browser. The string <code class="computeroutput">$‌Id:$</code> will automatically be expanded when the file is checked in to cvs.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/sql/postgresql</code></strong> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/sql/postgresql</code></strong> [$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>emacs myfirstpackage-create.sql</code></strong> </pre><p>Paste the text below into the file, save, and close.</p><div class="figure"> -<a name="idp140592098943512" id="idp140592098943512"></a><p class="title"><strong>Figure 9.3. The +<a name="idp140623161557048" id="idp140623161557048"></a><p class="title"><strong>Figure 9.3. The Database Creation Script</strong></p><div class="figure-contents"><pre class="programlisting"> -- creation script -- @@ -81,7 +79,7 @@ uninstalled.</p><pre class="screen"> [$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>emacs myfirstpackage-drop.sql</code></strong> </pre><div class="figure"> -<a name="idp140592099179128" id="idp140592099179128"></a><p class="title"><strong>Figure 9.4. Database Deletion +<a name="idp140623165914152" id="idp140623165914152"></a><p class="title"><strong>Figure 9.4. Database Deletion Script</strong></p><div class="figure-contents"><pre class="programlisting"> -- drop script -- Index: openacs-4/packages/acs-core-docs/www/tutorial-database.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-database.html,v diff -u -r1.45 -r1.46 --- openacs-4/packages/acs-core-docs/www/tutorial-database.html 7 Aug 2017 23:47:52 -0000 1.45 +++ openacs-4/packages/acs-core-docs/www/tutorial-database.html 8 Nov 2017 09:42:12 -0000 1.46 @@ -1,19 +1,28 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Setting Up Database Objects</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial-newpackage.html" title="Creating an Application Package"><link rel="next" href="tutorial-pages.html" title="Creating Web Pages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-database"></a>Setting Up Database Objects</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592104860472"></a>Code the data model</h3></div></div></div><p>We create all database objects with scripts in the +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Setting Up Database Objects</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial-newpackage.html" title="Creating an Application Package"><link rel="next" href="tutorial-pages.html" title="Creating Web Pages"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-database"></a>Setting Up Database Objects</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623172585384"></a>Code the data model</h3></div></div></div> + + <p>We create all database objects with scripts in the <code class="computeroutput">myfirstpackage/sql/</code> directory. All database scripts are database-specific and are thus in either the <code class="computeroutput">myfirstpackage/sql/oracle</code> or <code class="computeroutput">myfirstpackage/sql/postgresql</code> directory. Packages can support Oracle, PostgreSQL, or both. In this - tutorial, we will be working with PostgreSQL</p><p>The first file will be + tutorial, we will be working with PostgreSQL</p> + <p>The first file will be <code class="computeroutput">myfirstpackage-create.sql</code>. The package manager requires a file with the name - <code class="computeroutput"><span class="replaceable"><span class="replaceable">packagekey</span></span>-create.sql</code>, + <code class="computeroutput"><em class="replaceable"><code>packagekey</code></em>-create.sql</code>, which it will run automatically when the package in installed. - This file should create all tables and views.</p><p>Our package is going to store all of its information in + This file should create all tables and views.</p> + + <p>Our package is going to store all of its information in one table. It takes more than just a <code class="computeroutput">CREATE TABLE</code> command, however, because we want to integrate our table with the OpenACS system. By making each @@ -22,7 +31,9 @@ objects, such as <code class="computeroutput">general-comments</code> and <code class="computeroutput">notification</code>. The cost is that our table creation code must include several functions, - stored procedures, and is complicated (even for simple tables).</p><p>There are many kinds of OpenACS objects in the system. (You + stored procedures, and is complicated (even for simple tables).</p> + + <p>There are many kinds of OpenACS objects in the system. (You can see them with the psql code: <code class="computeroutput"> select object_type from acs_object_types;</code>.) One such object is the content_item, which is part of the content repository system. @@ -32,13 +43,23 @@ repository functions to simplify our database creation. (<a class="ulink" href="objects.html" target="_top">More information about ACS Objects</a>. <a class="ulink" href="/doc/acs-content-repository" target="_top">More information about the Content Repository</a>.) -</p><div class="figure"><a name="idp140592094116616"></a><p class="title"><b>Figure 9.2. Tutorial Data Model</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/tutorial-data-model.png" align="middle" alt="Tutorial Data Model"></div></div></div><br class="figure-break"><p>The top of each sql file has some +</p> + <div class="figure"><a name="idp140623163033192"></a><p class="title"><b>Figure 9.2. Tutorial Data Model</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/tutorial-data-model.png" align="middle" alt="Tutorial Data Model"></div> +</div></div><br class="figure-break"> + <p>The top of each sql file has some standard comments, including doc tags such as <code class="computeroutput">@author</code> which will be picked up by the API browser. The string <code class="computeroutput">$Id$</code> will automatically be - expanded when the file is checked in to cvs.</p><pre class="screen">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/sql/postgresql</code></strong> -[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>emacs myfirstpackage-create.sql</code></strong></pre><p>Paste the text below into the file, save, and close.</p><div class="figure"><a name="idp140592098943512"></a><p class="title"><b>Figure 9.3. The Database Creation Script</b></p><div class="figure-contents"><pre class="programlisting">-- creation script + expanded when the file is checked in to cvs.</p> +<pre class="screen">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/sql/postgresql</code></strong> +[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>emacs myfirstpackage-create.sql</code></strong></pre> + <p>Paste the text below into the file, save, and close.</p> + <div class="figure"><a name="idp140623161557048"></a><p class="title"><b>Figure 9.3. The Database Creation Script</b></p><div class="figure-contents"> + + <pre class="programlisting">-- creation script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ @@ -56,13 +77,20 @@ -- necessary to work around limitation of content repository: select content_folder__register_content_type(-100,'mfp_note','t'); -</pre></div></div><br class="figure-break"><p>The creation script calls a function in PL/pgSQL (PL/pgSQL is a procedural language extension to sql), +</pre> + </div></div><br class="figure-break"> + <p>The creation script calls a function in PL/pgSQL (PL/pgSQL is a procedural language extension to sql), <code class="computeroutput"><a class="ulink" href="/api-doc/plsql-subprogram-one?type=FUNCTION&name=content%5ftype%5f%5fcreate%5ftype" target="_top">content_type__create_type</a></code>, which in turn creates the necessary database changes to support our data object. Notice the use of "mfp." This is derived from "My First Package" and ensures that our object is unlikely to conflict - with objects from other packages.</p><p>Create a database file to drop everything if the package is uninstalled.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>emacs myfirstpackage-drop.sql</code></strong></pre><div class="figure"><a name="idp140592099179128"></a><p class="title"><b>Figure 9.4. Database Deletion Script</b></p><div class="figure-contents"><pre class="programlisting">-- drop script + with objects from other packages.</p> + <p>Create a database file to drop everything if the package is uninstalled.</p> + <pre class="screen"> +[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>emacs myfirstpackage-drop.sql</code></strong></pre> + <div class="figure"><a name="idp140623165914152"></a><p class="title"><b>Figure 9.4. Database Deletion Script</b></p><div class="figure-contents"> + + <pre class="programlisting">-- drop script -- -- @author joel@aufrecht.org -- @cvs-id &Id:$ @@ -74,19 +102,30 @@ 't', 't' ); -</pre></div></div><br class="figure-break"><p>(like the creation script the drop script calls a PL/pgSQL function: <code class="computeroutput"><a class="ulink" href="/api-doc/plsql-subprogram-one?type=FUNCTION&name=content%5ftype%5f%5fdrop%5ftype" target="_top">content_type__drop_type</a></code></p><p>Run the create script manually to add your tables and functions.</p><pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>psql service0 -f myfirstpackage-create.sql</code></strong> +</pre> + </div></div><br class="figure-break"> + <p>(like the creation script the drop script calls a PL/pgSQL function: <code class="computeroutput"><a class="ulink" href="/api-doc/plsql-subprogram-one?type=FUNCTION&name=content%5ftype%5f%5fdrop%5ftype" target="_top">content_type__drop_type</a></code></p> + <p>Run the create script manually to add your tables and functions.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>psql service0 -f myfirstpackage-create.sql</code></strong> psql:myfirstpackage-create.sql:15: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'mfp_notes_pkey' for table 'mfp_notes' psql:myfirstpackage-create.sql:15: NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s) content_type__create_type --------------------------- 0 (1 row) -[$OPENACS_SERVICE_NAME postgresql]$</pre><p>If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.</p><p>Once you get the same output as shown above, test the drop script:</p><pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>psql service0 -f myfirstpackage-drop.sql</code></strong> +[$OPENACS_SERVICE_NAME postgresql]$</pre> + <p>If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored.</p> + <p>Once you get the same output as shown above, test the drop script:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>psql service0 -f myfirstpackage-drop.sql</code></strong> content_type__drop_type ------------------------- 0 (1 row) -[$OPENACS_SERVICE_NAME postgresql]$</pre><p>Once both scripts are working without errors, <span class="emphasis"><em>run the create script one last time</em></span> and proceed.</p><pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>psql service0 -f myfirstpackage-create.sql</code></strong></pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr><tr><td width="40%" align="left">Creating an Application Package </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Creating Web Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +[$OPENACS_SERVICE_NAME postgresql]$</pre> + <p>Once both scripts are working without errors, <span class="emphasis"><em>run the create script one last time</em></span> and proceed.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$ <strong class="userinput"><code>psql service0 -f myfirstpackage-create.sql</code></strong></pre> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-newpackage.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-pages.html">Next</a></td></tr><tr><td width="40%" align="left">Creating an Application Package </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Creating Web Pages</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-debug.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-debug.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,30 +9,28 @@ rightLink="tutorial-advanced" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-debug" id="tutorial-debug"></a>Debugging and Automated Testing</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="tutorial-debug" id="tutorial-debug"></a>Debugging and Automated Testing</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592107822152" id="idp140592107822152"></a>Debugging</h3></div></div></div><p> -<strong>Developer Support. </strong>The Developer +<a name="idp140623170297736" id="idp140623170297736"></a>Debugging</h3></div></div></div><p> +<strong>Developer Support. </strong> The Developer Support package adds several goodies: debug information for every page; the ability to log comments to the page instead of the error log, and fast user switching so that you can test pages as anonymous and as dummy users without logging in and out.</p><p> -<strong>PostgreSQL. </strong>You can work directly +<strong>PostgreSQL. </strong> You can work directly with the database to do debugging steps like looking directly at tables and testing stored procedures. Start emacs. Type <strong class="userinput"><code>M-x sql-postgres</code></strong>. -Press enter for server name and use <strong class="userinput"><code><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> +Press enter for server name and use <strong class="userinput"><code><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> for database name. You can use C-(up arrow) and C-(down arrow) for command history.</p><p>Hint: "Parse error near *" usually means that an xql file wasn't recognized, because the Tcl file is choking on the *SQL* placeholder that it falls back on.</p><p><strong>Watching the server log. </strong></p><p>To set up real-time monitoring of the AOLserver error log, <span class="bold"><strong>type</strong></span> </p><pre class="screen"> -less /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/openacs-dev-error.log +less /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/openacs-dev-error.log </pre><div class="literallayout"><p> F to show new log entries in real time (like tail -f)<br> @@ -45,7 +43,7 @@ </p></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592107831512" id="idp140592107831512"></a>Manual testing</h3></div></div></div><p>Make a list of basic tests to make sure it works</p><div class="segmentedlist"><table border="0"> +<a name="idp140623166255592" id="idp140623166255592"></a>Manual testing</h3></div></div></div><p>Make a list of basic tests to make sure it works</p><div class="segmentedlist"><table border="0"> <thead><tr class="segtitle"> <th>Test Num</th><th>Action</th><th>Expected Result</th> </tr></thead><tbody> @@ -73,19 +71,17 @@ to delete your own note. Edit your own note. Search for a note.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592102696792" id="idp140592102696792"></a>Write automated tests</h3></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:simon\@collaboraid.net" target="_top">Simon Carstensen</a> and Joel Aufrecht</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p> -<a class="indexterm" name="idp140592102521720" id="idp140592102521720"></a> It seems to me that a lot of people have +<a name="idp140623164614664" id="idp140623164614664"></a>Write automated tests</h3></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:simon\@collaboraid.net" target="_top">Simon Carstensen</a> +and Joel Aufrecht</span></p><span style="color: red"></authorblurb></span><p> +<a class="indexterm" name="idp140623162159976" id="idp140623162159976"></a> 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.</p><p>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:</p><pre class="screen"> -[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/tcl/test</code></strong> -[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/tcl/test</code></strong> +[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/tcl/test</code></strong> +[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/tcl/test</code></strong> [$OPENACS_SERVICE_NAME test]$ <strong class="userinput"><code>emacs myfirstpackages-procs.tcl</code></strong> </pre><p>Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file:</p><pre class="screen"> @@ -148,7 +144,7 @@ myfirstpackage. You should see your test case. Run it and examine the results.</p><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592102416504" id="idp140592102416504"></a>TCLWebtest tests</h4></div></div></div><p>API testing can only test part of our package - it doesn't +<a name="idp140623166048792" id="idp140623166048792"></a>TCLWebtest tests</h4></div></div></div><p>API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs. For this, we can use TCLwebtest. TCLwebtest must be <a class="link" href="install-tclwebtest" title="Install tclwebtest.">installed</a> for this test to work. This provides a <a class="ulink" href="http://tclwebtest.sourceforge.net/doc/api_public.html" target="_top">library of functions</a> that make it easy to call a page @@ -158,7 +154,7 @@ integrating them.</p> </div><div class="sect3"> <div class="titlepage"><div><div><h4 class="title"> -<a name="idp140592102047384" id="idp140592102047384"></a>Example</h4></div></div></div><p>Now we can add the rest of the API tests, including a test with +<a name="idp140623160629800" id="idp140623160629800"></a>Example</h4></div></div></div><p>Now we can add the rest of the API tests, including a test with deliberately bad data. The complete test looks like:</p><pre class="programlisting"> ad_library { Test cases for my first package. Index: openacs-4/packages/acs-core-docs/www/tutorial-debug.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-debug.html,v diff -u -r1.44 -r1.45 --- openacs-4/packages/acs-core-docs/www/tutorial-debug.html 7 Aug 2017 23:47:52 -0000 1.44 +++ openacs-4/packages/acs-core-docs/www/tutorial-debug.html 8 Nov 2017 09:42:12 -0000 1.45 @@ -1,61 +1,122 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Debugging and Automated Testing</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial-pages.html" title="Creating Web Pages"><link rel="next" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-debug"></a>Debugging and Automated Testing</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592107822152"></a>Debugging</h3></div></div></div><p><b>Developer Support. </b>The Developer Support package adds several goodies: debug +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Debugging and Automated Testing</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial-pages.html" title="Creating Web Pages"><link rel="next" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-debug"></a>Debugging and Automated Testing</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623170297736"></a>Debugging</h3></div></div></div> + <p> + <b>Developer Support. </b> + The Developer Support package adds several goodies: debug information for every page; the ability to log comments to the page instead of the error log, and fast user switching so that you can test pages as anonymous and as dummy users without logging - in and out.</p><p><b>PostgreSQL. </b>You can work directly with the database to do debugging + in and out. + </p> + <p> + <b>PostgreSQL. </b> + You can work directly with the database to do debugging steps like looking directly at tables and testing stored procedures. Start emacs. Type <strong class="userinput"><code>M-x sql-postgres</code></strong>. Press enter for - server name and use <strong class="userinput"><code><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> for + server name and use <strong class="userinput"><code><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> for database name. You can use C-(up arrow) and C-(down arrow) for command history. -</p><p>Hint: "Parse error near *" usually means that an xql file + + </p> + <p>Hint: "Parse error near *" usually means that an xql file wasn't recognized, because the Tcl file is choking on the *SQL* - placeholder that it falls back on.</p><p><b>Watching the server log. </b></p><p>To set up real-time monitoring of the AOLserver error - log, <span class="bold"><strong>type</strong></span> </p><pre class="screen">less /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/log/openacs-dev-error.log</pre><p> + placeholder that it falls back on.</p> + <p> + <b>Watching the server log. </b> + + </p> + <p>To set up real-time monitoring of the AOLserver error + log, <span class="bold"><strong>type</strong></span> </p><pre class="screen">less /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/log/openacs-dev-error.log</pre><p> </p><div class="literallayout"><p>F to show new log entries in real time (like tail -f)<br> C-c to stop and F to start it up again. <br> G goes to the end.<br> ? searches backward <br> / searches forward. <br> </p></div><p> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592107831512"></a>Manual testing</h3></div></div></div><p>Make a list of basic tests to make sure it works</p><div class="segmentedlist"><table border="0"><thead><tr class="segtitle"><th>Test Num</th><th>Action</th><th>Expected Result</th></tr></thead><tbody><tr class="seglistitem"><td class="seg">001</td><td class="seg">Browse to the index page while not logged in and - while one or more notes exist.</td><td class="seg">No edit or delete or add links should appear.</td></tr><tr class="seglistitem"><td class="seg">002</td><td class="seg">Browse to the index page while logged in. An Edit + </p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623166255592"></a>Manual testing</h3></div></div></div> + + <p>Make a list of basic tests to make sure it works</p> + <div class="segmentedlist"><table border="0"><thead><tr class="segtitle"><th>Test Num</th><th>Action</th><th>Expected Result</th></tr></thead><tbody><tr class="seglistitem"> + <td class="seg">001</td> + <td class="seg">Browse to the index page while not logged in and + while one or more notes exist.</td> + <td class="seg">No edit or delete or add links should appear.</td> + </tr><tr class="seglistitem"> + <td class="seg">002</td> + <td class="seg">Browse to the index page while logged in. An Edit link should appear. Click on it. Fill out the form and - click Submit.</td><td class="seg">The text added in the form should be visible on the - index page.</td></tr><tr class="seglistitem"><td class="seg">API-001</td><td class="seg">Invoke mfp::note::create with a specific word as the title.</td><td class="seg">Proc should return an object id.</td></tr><tr class="seglistitem"><td class="seg">API-002</td><td class="seg">Given an object id from API-001, invoke mfp::note::get.</td><td class="seg">Proc should return the specific word in the title.</td></tr><tr class="seglistitem"><td class="seg">API-003</td><td class="seg">Given the object id from API-001, invoke mfp::note::delete.</td><td class="seg">Proc should return 0 for success.</td></tr></tbody></table></div><p>Other things to test: try to delete someone else's + click Submit.</td> + <td class="seg">The text added in the form should be visible on the + index page.</td> + </tr><tr class="seglistitem"> + <td class="seg">API-001</td> + <td class="seg">Invoke mfp::note::create with a specific word as the title.</td> + <td class="seg">Proc should return an object id.</td> + </tr><tr class="seglistitem"> + <td class="seg">API-002</td> + <td class="seg">Given an object id from API-001, invoke mfp::note::get.</td> + <td class="seg">Proc should return the specific word in the title.</td> + </tr><tr class="seglistitem"> + <td class="seg">API-003</td> + <td class="seg">Given the object id from API-001, invoke mfp::note::delete.</td> + <td class="seg">Proc should return 0 for success.</td> + </tr></tbody></table></div> + <p>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.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592102696792"></a>Write automated tests</h3></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:simon@collaboraid.net" target="_top">Simon Carstensen</a> and Joel Aufrecht</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p><a class="indexterm" name="idp140592102521720"></a> - 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.</p><p>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:</p><pre class="screen">[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/tcl/test</code></strong> -[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/tcl/test</code></strong> -[$OPENACS_SERVICE_NAME test]$ <strong class="userinput"><code>emacs myfirstpackages-procs.tcl</code></strong></pre><p>Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file:</p><pre class="screen">ad_library { + Search for a note.</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623164614664"></a>Write automated tests</h3></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:simon@collaboraid.net" target="_top">Simon Carstensen</a> and Joel Aufrecht</p> + </authorblurb></span> + + <p><a class="indexterm" name="idp140623162159976"></a> + 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.</p> + <p>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:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/tcl/test</code></strong> +[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/tcl/test</code></strong> +[$OPENACS_SERVICE_NAME test]$ <strong class="userinput"><code>emacs myfirstpackages-procs.tcl</code></strong></pre> + <p>Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file:</p> + <pre class="screen">ad_library { ... } -</pre><p>To create a test case you call +</pre> + <p>To create a test case you call <code class="computeroutput"><a class="ulink" href="/api-doc/proc-view?proc=aa%5fregister%5fcase" target="_top">aa_register_case</a> test_case_name.</code>. Once you've created the test case you start writing the needed logic. We'll use the tutorial package, "myfirstpackage," as an example. Let's say you just wrote an <a class="ulink" href="/api-doc" target="_top">API</a> for adding and deleting notes in the notes packages and wanted to test that. You'd probably want to write a test that first creates a note, then verifies that it was inserted, then perhaps deletes it again, and finally verifies that it is -gone.</p><p> +gone.</p> + +<p> Naturally this means you'll be adding a lot of bogus data to the database, which you're not really interested in having there. To avoid this I usually do two things. I always put all my test code inside a call to aa_run_with_teardown which basically means that all the inserts, deletes, and updates will be rolled back once the test has been executed. A very useful feature. Instead of inserting bogus data -like: <code class="computeroutput">set name "Simon"</code>, I tend to generate a random script in order avoid inserting a value that's already in the database:</p><pre class="screen">set name [ad_generate_random_string] -</pre><p>Here's how the test case looks so far:</p><pre class="screen">aa_register_case mfp_basic_test { +like: <code class="computeroutput">set name "Simon"</code>, I tend to generate a random script in order avoid inserting a value that's already in the database:</p> +<pre class="screen">set name [ad_generate_random_string] +</pre> +<p>Here's how the test case looks so far:</p> + +<pre class="screen">aa_register_case mfp_basic_test { My test } { aa_run_with_teardown \ @@ -64,11 +125,23 @@ } } -</pre><p>Now let's look at the actual test code. That's the code that -goes inside <code class="computeroutput">-test_code {}</code>. We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title."</p><pre class="programlisting"> +</pre> +<p>Now let's look at the actual test code. That's the code that +goes inside <code class="computeroutput">-test_code {}</code>. We want to implement test case API-001, "Given an object id from API-001, invoke mfp::note::get. Proc should return the specific word in the title."</p> + <pre class="programlisting"> set name [ad_generate_random_string] set new_id [mfp::note::add -title $name] - aa_true "Note add succeeded" ([info exists new_id] && $new_id ne "")</pre><p>To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.) To make this file take effect, go to the <a class="ulink" href="/acs-admin/apm" target="_top">APM</a> and choose "Reload changed" for "MyFirstPackage". Since we'll be changing it frequently, select "watch this file" on the next page. This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing. We can also add some aa_register_case flags to make it easier to run the test. The <code class="computeroutput">-procs</code> flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all. The <code class="computeroutput">-cats</code> flag, setting categories, makes it easier to control which tests to run. The <code class="computeroutput">smoke</code> test setting means that this is a basic test case that can and should be run any time you are doing any test. (<a class="ulink" href="http://www.nedbatchelder.com/blog/20030408T062805.html" target="_top">a definition of "smoke test"</a>)</p><p>Once the file is loaded, go to <a class="ulink" href="/test" target="_top">ACS Automated Testing</a> and click on myfirstpackage. You should see your test case. Run it and examine the results.</p><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592102416504"></a>TCLWebtest tests</h4></div></div></div><p>API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs. For this, we can use TCLwebtest. TCLwebtest must be <a class="link" href="install-tclwebtest.html" title="Install tclwebtest.">installed</a> for this test to work. This provides a <a class="ulink" href="http://tclwebtest.sourceforge.net/doc/api_public.html" target="_top">library of functions</a> that make it easy to call a page through HTTP, examine the results, and drive forms. TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140592102047384"></a>Example</h4></div></div></div><p>Now we can add the rest of the API tests, including a test with deliberately bad data. The complete test looks like:</p><pre class="programlisting">ad_library { + aa_true "Note add succeeded" ([info exists new_id] && $new_id ne "")</pre> + <p>To test our simple case, we must load the test file into the system (just as with the /tcl file in the basic tutorial, since the file didn't exist when the system started, the system doesn't know about it.) To make this file take effect, go to the <a class="ulink" href="/acs-admin/apm" target="_top">APM</a> and choose "Reload changed" for "MyFirstPackage". Since we'll be changing it frequently, select "watch this file" on the next page. This will cause the system to check this file every time any page is requested, which is bad for production systems but convenient for developing. We can also add some aa_register_case flags to make it easier to run the test. The <code class="computeroutput">-procs</code> flag, which indicates which procs are tested by this test case, makes it easier to find procs in your package that aren't tested at all. The <code class="computeroutput">-cats</code> flag, setting categories, makes it easier to control which tests to run. The <code class="computeroutput">smoke</code> test setting means that this is a basic test case that can and should be run any time you are doing any test. (<a class="ulink" href="http://www.nedbatchelder.com/blog/20030408T062805.html" target="_top">a definition of "smoke test"</a>)</p> + <p>Once the file is loaded, go to <a class="ulink" href="/test" target="_top">ACS Automated Testing</a> and click on myfirstpackage. You should see your test case. Run it and examine the results.</p> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623166048792"></a>TCLWebtest tests</h4></div></div></div> + + <p>API testing can only test part of our package - it doesn't test the code in our adp/tcl pairs. For this, we can use TCLwebtest. TCLwebtest must be <a class="link" href="install-tclwebtest.html" title="Install tclwebtest.">installed</a> for this test to work. This provides a <a class="ulink" href="http://tclwebtest.sourceforge.net/doc/api_public.html" target="_top">library of functions</a> that make it easy to call a page through HTTP, examine the results, and drive forms. TCLwebtest's functions overlap slightly with acs-automated-testing; see the example provided for one approach on integrating them.</p> + </div> + <div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="idp140623160629800"></a>Example</h4></div></div></div> + + <p>Now we can add the rest of the API tests, including a test with deliberately bad data. The complete test looks like:</p> + <pre class="programlisting">ad_library { Test cases for my first package. } @@ -220,4 +293,8 @@ # tcl-indent-level: 4 # indent-tabs-mode: nil # End: -</pre><p>See also <a class="xref" href="automated-testing-best-practices.html" title="Automated Testing">the section called “Automated Testing”</a>.</p></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr><tr><td width="40%" align="left">Creating Web Pages </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Chapter 10. Advanced Topics</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + <p>See also <a class="xref" href="automated-testing-best-practices.html" title="Automated Testing">the section called “Automated Testing”</a>.</p> + </div> + </div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-pages.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-advanced.html">Next</a></td></tr><tr><td width="40%" align="left">Creating Web Pages </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Chapter 10. Advanced Topics</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,10 +10,10 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tutorial-distribute" id="tutorial-distribute"></a>Prepare the package for -distribution.</h2></div></div></div><p>Browse to the package manager. Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">tutorialapp</span></span></code>.</p><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Generate a distribution file for -this package from the filesystem</span></span></code>.</p><p>Click on the file size (<code class="computeroutput"><span class="guilabel"><span class="guilabel">37.1KB</span></span></code>) after the label -<code class="computeroutput"><span class="guilabel"><span class="guilabel">Distribution File:</span></span></code> and save the -file to /var/tmp.</p><p><a class="indexterm" name="idp140592104250328" id="idp140592104250328"></a></p><p><a class="ulink" href="http://openacs.org/forums/message-view?message_id=192919" target="_top">Package development guidelines</a></p> +distribution.</h2></div></div></div><p>Browse to the package manager. Click on <code class="computeroutput"><span class="guilabel">tutorialapp</span></code>.</p><p>Click on <code class="computeroutput"><span class="guilabel">Generate a distribution file for this package from the +filesystem</span></code>.</p><p>Click on the file size (<code class="computeroutput"><span class="guilabel">37.1KB</span></code>) after +the label <code class="computeroutput"><span class="guilabel">Distribution File:</span></code> and save the file to +/var/tmp.</p><p><a class="indexterm" name="idp140623164525208" id="idp140623164525208"></a></p><p><a class="ulink" href="http://openacs.org/forums/message-view?message_id=192919" target="_top">Package development guidelines</a></p> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="profile-code" leftLabel="Prev" leftTitle="Profile your code" Index: openacs-4/packages/acs-core-docs/www/tutorial-distribute.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-distribute.html,v diff -u -r1.27 -r1.28 --- openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 7 Aug 2017 23:47:52 -0000 1.27 +++ openacs-4/packages/acs-core-docs/www/tutorial-distribute.html 8 Nov 2017 09:42:12 -0000 1.28 @@ -1,11 +1,20 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Prepare the package for distribution.</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="profile-code.html" title="Profile your code"><link rel="next" href="tutorial-upgrades.html" title="Distributing upgrades of your package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="profile-code.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-upgrades.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-distribute"></a>Prepare the package for distribution.</h2></div></div></div><p>Browse to the package manager. Click on - <code class="computeroutput"><span class="guilabel"><span class="guilabel">tutorialapp</span></span></code>.</p><p>Click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">Generate a distribution file +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Prepare the package for distribution.</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="profile-code.html" title="Profile your code"><link rel="next" href="tutorial-upgrades.html" title="Distributing upgrades of your package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="profile-code.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-upgrades.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-distribute"></a>Prepare the package for distribution.</h2></div></div></div> + + <p>Browse to the package manager. Click on + <code class="computeroutput"><span class="guilabel">tutorialapp</span></code>.</p> + <p>Click on <code class="computeroutput"><span class="guilabel">Generate a distribution file for this package from the - filesystem</span></span></code>. - </p><p>Click on the file size - (<code class="computeroutput"><span class="guilabel"><span class="guilabel">37.1KB</span></span></code>) - after the label <code class="computeroutput"><span class="guilabel"><span class="guilabel">Distribution - File:</span></span></code> and save the file to - /var/tmp.</p><p><a class="indexterm" name="idp140592104250328"></a> -</p><p><a class="ulink" href="http://openacs.org/forums/message-view?message_id=192919" target="_top">Package development guidelines</a></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile-code.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-upgrades.html">Next</a></td></tr><tr><td width="40%" align="left">Profile your code </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Distributing upgrades of your package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + filesystem</span></code>. + </p> + <p>Click on the file size + (<code class="computeroutput"><span class="guilabel">37.1KB</span></code>) + after the label <code class="computeroutput"><span class="guilabel">Distribution + File:</span></code> and save the file to + /var/tmp.</p> + <p><a class="indexterm" name="idp140623164525208"></a> +</p> + + <p><a class="ulink" href="http://openacs.org/forums/message-view?message_id=192919" target="_top">Package development guidelines</a></p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="profile-code.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-upgrades.html">Next</a></td></tr><tr><td width="40%" align="left">Profile your code </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Distributing upgrades of your package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,11 +9,9 @@ rightLink="tutorial-comments" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-etp-templates"></a>OpenACS Edit This Page Templates</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:ncarroll\@ee.usyd.edu.au" target="_top">Nick Carroll</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="tutorial-etp-templates"></a>OpenACS Edit This Page Templates</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:ncarroll\@ee.usyd.edu.au" target="_top">Nick +Carroll</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="goals"></a>Goals</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>Learn about the OpenACS templating system.</p></li><li class="listitem"><p>Learn about subsites and site-map administration.</p></li> @@ -86,7 +84,7 @@ </li><li class="listitem"> <p>The template should provide us with the following ETP layout:</p><div class="table"> -<a name="idp140592099042408"></a><p class="title"><strong>Table 10.1. table +<a name="idp140623170145000"></a><p class="title"><strong>Table 10.1. table showing ETP layout</strong></p><div class="table-contents"><table class="table" summary="table showing ETP layout" cellspacing="0" border="1" width="250"> <colgroup> <col align="left" class="c1"><col width="2" align="left" class="c2"> @@ -133,8 +131,8 @@ <a name="end"></a>Who Wrote This and When</h3></div></div></div><p>This problem set was originally written by Nick Carroll in August 2004 for the <a class="ulink" href="http://www.usyd.edu.au" target="_top">University of Sydney</a> Course EBUS5002.</p><p>This material is copyright 2004 by Nick Carroll. It may be copied, reused, and modified, provided credit is given to the -original author.</p><div class="cvstag">($‌Id: tutorial-advanced.xml,v 1.52.2.7 -2017/06/17 10:15:41 gustafn Exp $)</div> +original author.</p><p><span class="cvstag">($‌Id: tutorial-advanced.xml,v 1.53 +2017/08/07 23:47:54 gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html 7 Aug 2017 23:47:52 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial-etp-templates.html 8 Nov 2017 09:42:12 -0000 1.11 @@ -1,17 +1,129 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Edit This Page Templates</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-cvs.html" title="Add the new package to CVS"><link rel="next" href="tutorial-comments.html" title="Adding Comments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-cvs.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-comments.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-etp-templates"></a>OpenACS Edit This Page Templates</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:ncarroll@ee.usyd.edu.au" target="_top">Nick Carroll</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="goals"></a>Goals</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Learn about the OpenACS templating system.</p></li><li class="listitem"><p>Learn about subsites and site-map administration.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="introduction"></a>Introduction</h3></div></div></div><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Edit This Page Templates</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-cvs.html" title="Add the new package to CVS"><link rel="next" href="tutorial-comments.html" title="Adding Comments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-cvs.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-comments.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-etp-templates"></a>OpenACS Edit This Page Templates</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:ncarroll@ee.usyd.edu.au" target="_top">Nick Carroll</a></p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="goals"></a>Goals</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Learn about the OpenACS templating system.</p> + </li><li class="listitem"> + <p>Learn about subsites and site-map administration.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="introduction"></a>Introduction</h3></div></div></div> + + <p> The OpenACS templating system allows you to give your site a consistent look and feel. It also promotes code maintainability in the presentation layer, by allowing presentation components to be reused across multiple pages. If you need to change the layout for some reason, then you only need to make that change in one location, instead of across many files. - </p><p> + </p> + <p> In this problem set you will familiarise yourself with the templating system in openacs. This will be achieved through customising an existing edit-this-page application template. - </p><p> + </p> + <p> Before proceeding, it is strongly advised to read the templating documentation on your OpenACS installation (http://localhost:8000/doc/acs-templating). The documentation lists the special tags available for ADP files. - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise1"></a>Exercise 1: Create a Subsite</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Create a subsite called pset3.</p></li><li class="listitem"><p>A subsite is simply a directory or subdirectory mounted at the end of your domain name. This can be done in one of two places:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>http://localhost:8000/admin/site-map</p></li><li class="listitem"><p>or the subsite admin form on the main site, which is available when you login to your OpenACS installation.</p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise2"></a>Exercise 2: Checkout and Install edit-this-page (ETP)</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Checkout ETP from CVS:</p><pre class="screen">cd ~/openacs/packages + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise1"></a>Exercise 1: Create a Subsite</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Create a subsite called pset3.</p> + </li><li class="listitem"> + <p>A subsite is simply a directory or subdirectory mounted at the end of your domain name. This can be done in one of two places:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p>http://localhost:8000/admin/site-map</p> + </li><li class="listitem"> + <p>or the subsite admin form on the main site, which is available when you login to your OpenACS installation.</p> + </li></ul></div> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise2"></a>Exercise 2: Checkout and Install edit-this-page (ETP)</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Checkout ETP from CVS:</p> + <pre class="screen">cd ~/openacs/packages cvs -d:pserver:anonymous@openacs.org:/cvsroot login - cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page</pre></li><li class="listitem"><p>Go to the package manager at http://yoursite/acs-admin/apm. And install the new package: edit-this-page.</p></li><li class="listitem"><p>Or use the "Add Application" form available on the Main site.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise3"></a>Change ETP Application</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Work out how to change the ETP application.</p></li><li class="listitem"><p>Investigate each of the available ETP templates:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Default</p></li><li class="listitem"><p>News</p></li><li class="listitem"><p>FAQ</p></li></ul></div></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise4"></a>Exercise 4: Create a New ETP Template</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Browse the files for each of the above ETP templates at:</p><pre class="screen">cd ~/openacs/packages/edit-this-page/templates</pre></li><li class="listitem"><p>Use the article template as the basis of our new col2 template.</p><pre class="screen">cp article-content.adp col2-content.adp + cvs -d:pserver:anonymous@openacs.org:/cvsroot co edit-this-page</pre> + </li><li class="listitem"> + <p>Go to the package manager at http://yoursite/acs-admin/apm. And install the new package: edit-this-page.</p> + </li><li class="listitem"> + <p>Or use the "Add Application" form available on the Main site.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise3"></a>Change ETP Application</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Work out how to change the ETP application.</p> + </li><li class="listitem"> + <p>Investigate each of the available ETP templates:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Default</p></li><li class="listitem"><p>News</p></li><li class="listitem"><p>FAQ</p></li></ul></div> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise4"></a>Exercise 4: Create a New ETP Template</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Browse the files for each of the above ETP templates at:</p> + <pre class="screen">cd ~/openacs/packages/edit-this-page/templates</pre> + </li><li class="listitem"> + <p>Use the article template as the basis of our new col2 template.</p> + <pre class="screen">cp article-content.adp col2-content.adp cp article-content.tcl col2-content.tcl cp article-index.adp col2-index.adp - cp article-index.tcl col2-index.tcl</pre></li><li class="listitem"><p>The template should provide us with the following ETP layout:</p><div class="table"><a name="idp140592099042408"></a><p class="title"><b>Table 10.1. table showing ETP layout</b></p><div class="table-contents"><table class="table" summary="table showing ETP layout" cellspacing="0" border="1" width="250"><colgroup><col align="left" class="c1"><col width="2" align="left" class="c2"></colgroup><tbody><tr><td colspan="2" align="center">Header</td></tr><tr height="200"><td align="left">Sidebar</td><td align="left">Main Content Pane</td></tr></tbody></table></div></div><br class="table-break"></li><li class="listitem"><p>The "Main Content" pane should contain the editable content that ETP provides.</p></li><li class="listitem"><p>The "Header" should display the title of the page that you set in ETP.</p></li><li class="listitem"><p>The "Sidebar" should display the extlinks that you add as a content item in ETP.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise5"></a>Exercise 5: Register the col2 Template with ETP</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.</p><pre class="screen">cd ~/openacs/packages/edit-this-page/tcl - emacs etp-custom-init.tcl</pre></li><li class="listitem"><p>Use the function etp::define_application to register your template with ETP</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Uncomment the "asc" definition</p></li><li class="listitem"><p>Set allow_extlinks to true, the rest should be false.</p></li></ul></div></li><li class="listitem"><p>Restart your server for the changes to take effect.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise6"></a>Exercise 6: Configure ETP to use the col2 Template</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Configure your ETP instance at /lab4/index to use the col2 template.</p></li><li class="listitem"><p>Create external links to link to other mounted ETP instances.</p></li><li class="listitem"><p>Check that your external links show up in the sidebar when you view your ETP application using the col2 template.</p></li></ul></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="end"></a>Who Wrote This and When</h3></div></div></div><p>This problem set was originally written by Nick Carroll in August 2004 for the <a class="ulink" href="http://www.usyd.edu.au" target="_top">University of Sydney</a> Course EBUS5002.</p><p>This material is copyright 2004 by Nick Carroll. It may be copied, reused, and modified, provided credit is given to the original author.</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-comments.html">Next</a></td></tr><tr><td width="40%" align="left">Add the new package to CVS </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Adding Comments</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + cp article-index.tcl col2-index.tcl</pre> + </li><li class="listitem"> + <p>The template should provide us with the following ETP layout:</p> + <div class="table"><a name="idp140623170145000"></a><p class="title"><b>Table 10.1. table showing ETP layout</b></p><div class="table-contents"> + + + + <table class="table" summary="table showing ETP layout" cellspacing="0" border="1" width="250"><colgroup><col align="left" class="c1"><col width="2" align="left" class="c2"></colgroup><tbody><tr><td colspan="2" align="center">Header</td></tr><tr height="200"><td align="left">Sidebar</td><td align="left">Main Content Pane</td></tr></tbody></table> + </div></div><br class="table-break"> + </li><li class="listitem"> + <p>The "Main Content" pane should contain the editable content that ETP provides.</p> + </li><li class="listitem"> + <p>The "Header" should display the title of the page that you set in ETP.</p> + </li><li class="listitem"> + <p>The "Sidebar" should display the extlinks that you add as a content item in ETP.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise5"></a>Exercise 5: Register the col2 Template with ETP</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Need to register your template with ETP so that it appears in the drop-down menu that you would have seen in Exercise 3.</p> + <pre class="screen">cd ~/openacs/packages/edit-this-page/tcl + emacs etp-custom-init.tcl</pre> + </li><li class="listitem"> + <p>Use the function etp::define_application to register your template with ETP</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>Uncomment the "asc" definition</p></li><li class="listitem"><p>Set allow_extlinks to true, the rest should be false.</p></li></ul></div> + </li><li class="listitem"> + <p>Restart your server for the changes to take effect.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="exercise6"></a>Exercise 6: Configure ETP to use the col2 Template</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Configure your ETP instance at /lab4/index to use the col2 template.</p> + </li><li class="listitem"> + <p>Create external links to link to other mounted ETP instances.</p> + </li><li class="listitem"> + <p>Check that your external links show up in the sidebar when you view your ETP application using the col2 template.</p> + </li></ul></div> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="end"></a>Who Wrote This and When</h3></div></div></div> + + <p>This problem set was originally written by Nick Carroll in August 2004 for the <a class="ulink" href="http://www.usyd.edu.au" target="_top">University of Sydney</a> Course EBUS5002.</p> + <p>This material is copyright 2004 by Nick Carroll. It may be copied, reused, and modified, provided credit is given to the original author.</p> + <p><span class="cvstag">($Id$)</span></p> + </div> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-cvs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-comments.html">Next</a></td></tr><tr><td width="40%" align="left">Add the new package to CVS </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Adding Comments</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html 7 Aug 2017 23:47:52 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/tutorial-future-topics.html 8 Nov 2017 09:42:12 -0000 1.19 @@ -1,7 +1,12 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Future Topics</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-second-database.html" title="Connect to a second database"><link rel="next" href="dev-guide.html" title="Chapter 11. Development Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-second-database.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-future-topics"></a>Future Topics</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>How to enforce security so that users can't - change other users records</p></li><li class="listitem"><p>How to use the content management tables so that +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Future Topics</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-second-database.html" title="Connect to a second database"><link rel="next" href="dev-guide.html" title="Chapter 11. Development Reference"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-second-database.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-future-topics"></a>Future Topics</h2></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>How to enforce security so that users can't + change other users records</p> + </li><li class="listitem"><p>How to use the content management tables so that ... what?</p></li><li class="listitem"><p>How to change the default stylesheets for Form Builder HTML forms.</p></li><li class="listitem"><p>How to make your package searchable with OpenFTS/Oracle</p></li><li class="listitem"><p>How to prepare pagelets for inclusion in other pages</p></li><li class="listitem"><p>How and when to put procedures in a Tcl procedure library</p></li><li class="listitem"><p>More on ad_form - data validation, other stuff. (plan to draw from Jon Griffin's doc)</p></li><li class="listitem"><p>partialquery in xql</p></li><li class="listitem"><p>How to use the html/text entry widget to get the - "does this look right" confirm page </p></li><li class="listitem"><p>APM package dependencies</p></li></ul></div><p>See also the <a class="ulink" href="http://openacs.org/faq/one-faq?faq_id=43841" target="_top">OpenACS Programming FAQ</a></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-second-database.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr><tr><td width="40%" align="left">Connect to a second database </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Chapter 11. Development Reference</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + "does this look right" confirm page </p></li><li class="listitem"><p>APM package dependencies</p></li></ul></div> + <p>See also the <a class="ulink" href="http://openacs.org/faq/one-faq?faq_id=43841" target="_top">OpenACS Programming FAQ</a></p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-second-database.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="dev-guide.html">Next</a></td></tr><tr><td width="40%" align="left">Connect to a second database </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Chapter 11. Development Reference</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,11 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tutorial-hierarchical" id="tutorial-hierarchical"></a>Hierarchical -data</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="http://rubick.com:8002" target="_top">Jade Rubick</a> with help from many people in the OpenACS -community</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>One of the nice things about using the OpenACS object system is +data</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="http://rubick.com:8002" target="_top">Jade Rubick</a> with help +from many people in the OpenACS community</span></p><span style="color: red"></authorblurb></span><p>One of the nice things about using the OpenACS object system is that it has a built-in facility for tracking hierarchical data in an efficient way. The algorithm behind this is called <code class="computeroutput">tree_sortkey.</code> </p><p>Any time your tables are subclasses of the acs_objects table, Index: openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html 7 Aug 2017 23:47:52 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-hierarchical.html 8 Nov 2017 09:42:12 -0000 1.13 @@ -1,12 +1,17 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Hierarchical data</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-notifications.html" title="Notifications"><link rel="next" href="tutorial-vuh.html" title="Using .vuh files for pretty urls"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-notifications.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-vuh.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-hierarchical"></a>Hierarchical data</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="http://rubick.com:8002" target="_top">Jade Rubick</a> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Hierarchical data</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-notifications.html" title="Notifications"><link rel="next" href="tutorial-vuh.html" title="Using .vuh files for pretty urls"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-notifications.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-vuh.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-hierarchical"></a>Hierarchical data</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="http://rubick.com:8002" target="_top">Jade Rubick</a> with help from many people in the OpenACS community</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>One of the nice things about using the OpenACS object system + </authorblurb></span> + + <p>One of the nice things about using the OpenACS object system is that it has a built-in facility for tracking hierarchical data in an efficient way. The algorithm behind this is called - <code class="computeroutput">tree_sortkey.</code></p><p>Any time your tables are subclasses of the acs_objects + <code class="computeroutput">tree_sortkey.</code></p> + + <p>Any time your tables are subclasses of the acs_objects table, then you automatically get the ability to structure them hierarchically. The way you do this is currently via the <code class="computeroutput">context_id</code> column of @@ -15,7 +20,9 @@ the use of <code class="computeroutput">context_id</code> has been ambiguous in the past). So when you want to build your hierarchy, simply set the context_id values. Then, when you want to make - hierarchical queries, you can do them as follows:</p><pre class="programlisting"> + hierarchical queries, you can do them as follows:</p> + + <pre class="programlisting"> db_multirow categories blog_categories " SELECT c.*, @@ -28,10 +35,16 @@ c.category_id = o.object_id ORDER BY o.tree_sortkey" - </pre><p>Note the use of the + </pre> + + <p>Note the use of the <code class="computeroutput">tree_level()</code> function, which - gives you the level, starting from 1, 2, 3... </p><p>Here's an example, pulling all of the children for a given - parent:</p><pre class="programlisting"> + gives you the level, starting from 1, 2, 3... </p> + + <p>Here's an example, pulling all of the children for a given + parent:</p> + + <pre class="programlisting"> SELECT children.*, tree_level(children.tree_sortkey) - @@ -43,14 +56,20 @@ children.tree_sortkey between parent.tree_sortkey and tree_right(parent.tree_sortkey) and parent.tree_sortkey <> children.tree_sortkey and parent.key = :the_parent_key; - </pre><p>The reason we subtract the parent's tree_level from the + </pre> + + <p>The reason we subtract the parent's tree_level from the child's tree_level is that the tree_levels are global, so if you want the parent's tree_level to start with 0, you'll want the subtraction in there. This is a reason you'll commonly see magic numbers in tree_sortkey SQL queries, like <code class="computeroutput">tree_level(children.tree_sortkey) - 4</code>. That is basically an incorrect way to do it, - and subtracting the parent's tree_level is the preferred method.</p><p>This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:</p><pre class="programlisting"> + and subtracting the parent's tree_level is the preferred method.</p> + + <p>This example does not include the parent. To return the entire subtree including the parent, leave out the non-equals clause:</p> + + <pre class="programlisting"> SELECT subtree.*, tree_level(subtree.tree_sortkey) - @@ -59,10 +78,14 @@ WHERE subtree.tree_sortkey between parent.tree_sortkey and tree_right(parent.tree_sortkey) and parent.key = :the_parent_key; - </pre><p>If you are using the Content Repository, you get a similar + </pre> + + <p>If you are using the Content Repository, you get a similar facility, but the <code class="computeroutput">parent_id</code> column is already there. Note you can do joins with - <code class="computeroutput">tree_sortkey</code>:</p><pre class="programlisting"> + <code class="computeroutput">tree_sortkey</code>:</p> + + <pre class="programlisting"> SELECT p.item_id, repeat(:indent_pattern, (tree_level(p.tree_sortkey) - 5)* :indent_factor) as indent, @@ -71,10 +94,14 @@ FROM pm_projectsx p, cr_items i WHERE p.project_id = i.live_revision ORDER BY i.tree_sortkey - </pre><p>This rather long thread explains <a class="ulink" href="http://openacs.org/forums/message-view?message_id=16799" target="_top">How + </pre> + + <p>This rather long thread explains <a class="ulink" href="http://openacs.org/forums/message-view?message_id=16799" target="_top">How tree_sortkeys work</a> and this paper <a class="ulink" href="http://www.yafla.com/papers/sqlhierarchies/sqlhierarchies2.htm" target="_top">describes the technique for tree_sortkeys</a>, although the <a class="ulink" href="http://openacs.org/forums/message-view?message_id=112943" target="_top">OpenACS implementation has a few differences in the implementation</a>, to make it work for many languages and the LIKE construct in Postgres. - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-notifications.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-vuh.html">Next</a></td></tr><tr><td width="40%" align="left">Notifications </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Using .vuh files for pretty urls</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-notifications.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-vuh.html">Next</a></td></tr><tr><td width="40%" align="left">Notifications </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Using .vuh files for pretty urls</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-html-email.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-html-email.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-html-email.adp 7 Aug 2017 23:47:52 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-html-email.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,11 +10,8 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tutorial-html-email" id="tutorial-html-email"></a>Sending HTML email from your -application</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Sending email is fairly simple using the acs-mail-lite package. +application</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><p>Sending email is fairly simple using the acs-mail-lite package. Sending HTML email is only slightly more complicated.</p><pre class="programlisting"> set subject "my subject" Index: openacs-4/packages/acs-core-docs/www/tutorial-html-email.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-html-email.html,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/tutorial-html-email.html 7 Aug 2017 23:47:52 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/tutorial-html-email.html 8 Nov 2017 09:42:12 -0000 1.13 @@ -1,9 +1,14 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Sending HTML email from your application</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-css-layout.html" title="Laying out a page with CSS instead of tables"><link rel="next" href="tutorial-caching.html" title="Basic Caching"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-css-layout.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-caching.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-html-email"></a>Sending HTML email from your application</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Sending email is fairly simple using the acs-mail-lite - package. Sending HTML email is only slightly more complicated.</p><pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Sending HTML email from your application</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-css-layout.html" title="Laying out a page with CSS instead of tables"><link rel="next" href="tutorial-caching.html" title="Basic Caching"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-css-layout.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-caching.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-html-email"></a>Sending HTML email from your application</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + + <p>Sending email is fairly simple using the acs-mail-lite + package. Sending HTML email is only slightly more complicated.</p> + + <pre class="programlisting"> set subject "my subject" set message "<b>Bold</b> not bold" @@ -34,4 +39,5 @@ -subject $subject \ -body $message \ -extraheaders $extra_headers - </pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-css-layout.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-caching.html">Next</a></td></tr><tr><td width="40%" align="left">Laying out a page with CSS instead of tables </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Basic Caching</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-css-layout.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-caching.html">Next</a></td></tr><tr><td width="40%" align="left">Laying out a page with CSS instead of tables </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Basic Caching</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,16 +9,14 @@ rightLink="tutorial-database" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-newpackage" id="tutorial-newpackage"></a>Creating an Application Package</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="tutorial-newpackage" id="tutorial-newpackage"></a>Creating an Application Package</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="tutorial-picture" id="tutorial-picture"></a>The intended page map</h3></div></div></div><div class="mediaobject"><img src="images/openacs-best-practice.png"></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592102395400" id="idp140592102395400"></a>Overview</h3></div></div></div><p>To start developing new code in OpenACS, we build a new package. +<a name="idp140623176147848" id="idp140623176147848"></a>Overview</h3></div></div></div><p>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 <span class="strong"><strong>application</strong></span>; @@ -36,41 +34,41 @@ displaying a list of text notes.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592102408120" id="idp140592102408120"></a>Before you begin</h3></div></div></div><p>You will need:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +<a name="idp140623176152424" id="idp140623176152424"></a>Before you begin</h3></div></div></div><p>You will need:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>A computer with a working installation of OpenACS. If you don't have this, see <a class="xref" href="install-overview" title="Chapter 2. Installation Overview">Chapter 2, <em>Installation Overview</em> </a>.</p></li><li class="listitem"><p>Example files, which are included in the standard OpenACS 5.9.0 distribution.</p></li> </ul></div><div class="figure"> -<a name="idp140592100698680" id="idp140592100698680"></a><p class="title"><strong>Figure 9.1. Assumptions in this +<a name="idp140623174045016" id="idp140623174045016"></a><p class="title"><strong>Figure 9.1. Assumptions in this section</strong></p><div class="figure-contents"><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"> <colgroup> <col><col> </colgroup><tbody> <tr> -<td>Fully qualified domain name of your server</td><td><span class="replaceable"><span class="replaceable">yourserver.test</span></span></td> +<td>Fully qualified domain name of your server</td><td><em class="replaceable"><code>yourserver.test</code></em></td> </tr><tr> -<td>URL of your server</td><td><span class="replaceable"><span class="replaceable">http://yourserver.test:8000</span></span></td> +<td>URL of your server</td><td><em class="replaceable"><code>http://yourserver.test:8000</code></em></td> </tr><tr> -<td>Name of development account</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td> +<td>Name of development account</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> -<td>New Package key</td><td><span class="replaceable"><span class="replaceable">myfirstpackage</span></span></td> +<td>New Package key</td><td><em class="replaceable"><code>myfirstpackage</code></em></td> </tr> </tbody> </table></div></div> </div><br class="figure-break"> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592100706104" id="idp140592100706104"></a>Use the APM to initialize a new +<a name="idp140623174833816" id="idp140623174833816"></a>Use the APM to initialize a new package</h3></div></div></div><p>We use the <a class="ulink" href="packages" target="_top">ACS Package Manager</a> (APM) to add, remove, and upgrade packages. It handles package meta-data, such as lists of files that belong in the package. Each package is uniquely identified by a package key. To start developing a new package, use the APM to -create an empty package with our new package key, <span class="replaceable"><span class="replaceable">myfirstpackage</span></span>. This will create the -initial directories, meta-information files, and database entries -for a new package. (<a class="ulink" href="apm-requirements" target="_top">More info on APM</a>)</p><div class="orderedlist"><ol class="orderedlist" type="1"> -<li class="listitem"><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver:8000</span></span><a class="ulink" href="/acs-admin/apm" target="_top">/acs-admin/apm</a> +create an empty package with our new package key, <em class="replaceable"><code>myfirstpackage</code></em>. This will create +the initial directories, meta-information files, and database +entries for a new package. (<a class="ulink" href="apm-requirements" target="_top">More info on APM</a>)</p><div class="orderedlist"><ol class="orderedlist" type="1"> +<li class="listitem"><p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver:8000</code></em><a class="ulink" href="/acs-admin/apm" target="_top">/acs-admin/apm</a> </code>.</p></li><li class="listitem"> <p>Click <code class="computeroutput">Create a New Package</code>.</p><p>Fill in the fields listed below. <span class="strong"><strong>Ignore the rest (and leave the check boxes @@ -92,17 +90,16 @@ </p></li><li class="listitem"><p> <code class="computeroutput">Summary</code>: <strong class="userinput"><code>This is my first package.</code></strong> </p></li> -</ul></div><p>At the bottom, click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Create -Package</span></span></code>.</p> +</ul></div><p>At the bottom, click <code class="computeroutput"><span class="guibutton">Create Package</span></code>.</p> </li> -</ol></div><p>This creates a package rooted at <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> +</ol></div><p>This creates a package rooted at <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/<em class="replaceable"><code>myfirstpackage</code></em> </code>. This is the "home directory" of our new package, and all files in the package will be within this directory. <a class="ulink" href="packages" target="_top">More on the structure of packages</a>).</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592100726520" id="idp140592100726520"></a>Add an Application Instance to the +<a name="idp140623175709240" id="idp140623175709240"></a>Add an Application Instance to the Server</h3></div></div></div><p>In order to see your work in progress, you must create a map between the URL space of incoming requests and the package application instance. You do this by adding the application in the @@ -113,19 +110,19 @@ and tables. This requires that a package be developed <span class="emphasis"><em>package-aware</em></span>. You'll see how to do that in this tutorial.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Browse to <code class="computeroutput"> -<span class="replaceable"><span class="replaceable">http://yourserver.test:8000</span></span><a class="ulink" href="/admin/applications/application-add" target="_top">/admin/applications/application-add/</a> +<em class="replaceable"><code>http://yourserver.test:8000</code></em><a class="ulink" href="/admin/applications/application-add" target="_top">/admin/applications/application-add/</a> </code>.</p></li><li class="listitem"><p>Choose "My First Package" from the list and click OK (the other fields are optional).</p></li> </ol></div><p>By mounting the package, we've caused all requests to <code class="computeroutput">http://yourserver.test:8000/myfirstpackage</code> to be satisfied from the files at <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www</code>.</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592100734328" id="idp140592100734328"></a>Quick start</h3></div></div></div><p>The remainder of the tutorial walks you through each file one at +<a name="idp140623171946968" id="idp140623171946968"></a>Quick start</h3></div></div></div><p>The remainder of the tutorial walks you through each file one at a time as you create the package. You can skip all this, and get a working package, by doing the following:</p><pre class="screen"> -cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/tutorial -psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f myfirstpackage-create.sql +cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/tutorial +psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f myfirstpackage-create.sql cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/ mkdir ../../../../myfirstpackage/lib cp note-list.* ../../../../myfirstpackage/lib/ Index: openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html,v diff -u -r1.44 -r1.45 --- openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 7 Aug 2017 23:47:53 -0000 1.44 +++ openacs-4/packages/acs-core-docs/www/tutorial-newpackage.html 8 Nov 2017 09:42:12 -0000 1.45 @@ -1,42 +1,80 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Creating an Application Package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="next" href="tutorial-database.html" title="Setting Up Database Objects"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-database.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-newpackage"></a>Creating an Application Package</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tutorial-picture"></a>The intended page map</h3></div></div></div><div class="mediaobject"><img src="images/openacs-best-practice.png"></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592102395400"></a>Overview</h3></div></div></div><p>To start developing new code in OpenACS, we build a new package. A package +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Creating an Application Package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="next" href="tutorial-database.html" title="Setting Up Database Objects"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-database.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-newpackage"></a>Creating an Application Package</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="tutorial-picture"></a>The intended page map</h3></div></div></div> + + <div class="mediaobject"><img src="images/openacs-best-practice.png"></div> +</div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623176147848"></a>Overview</h3></div></div></div> + + <p>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 <span class="strong"><strong>application</strong></span>; a package which provides functions to other packages and has no direct interface, a <span class="strong"><strong>service</strong></span>. A package can be installed, upgraded, and removed. It communicates with other packages through an API. This chapter walks you through the minimum steps to create a useful package, including writing documentation, setting up database tables and procedures, writing web pages, debugging, and automatic regression testing. - </p><p> + </p> + + <p> This tutorial uses the content repository package. This radically simplifies the database work, but forces us to work around the content repository's limitations, including an incomplete Tcl API. So the tutorial is messier than we'd like right now. Code that is temporary hackage is clearly marked. - </p><p>In this tutorial, we will make an application package for + </p> + + <p>In this tutorial, we will make an application package for displaying a list of text notes. -</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592102408120"></a>Before you begin</h3></div></div></div><p>You will need:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A computer with a working installation of +</p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623176152424"></a>Before you begin</h3></div></div></div> + <p>You will need:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A computer with a working installation of OpenACS. If you don't have this, see <a class="xref" href="install-overview.html" title="Chapter 2. Installation Overview">Chapter 2, <i>Installation Overview</i></a>. </p></li><li class="listitem"><p>Example files, which are included in the standard OpenACS 5.9.0 distribution. - </p></li></ul></div><div class="figure"><a name="idp140592100698680"></a><p class="title"><b>Figure 9.1. Assumptions in this section</b></p><div class="figure-contents"><div class="informaltable"><table class="informaltable" cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><span class="replaceable"><span class="replaceable">yourserver.test</span></span></td></tr><tr><td>URL of your server</td><td><span class="replaceable"><span class="replaceable">http://yourserver.test:8000</span></span></td></tr><tr><td>Name of development account</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>New Package key</td><td><span class="replaceable"><span class="replaceable">myfirstpackage</span></span></td></tr></tbody></table></div></div></div><br class="figure-break"></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592100706104"></a>Use the APM to initialize a new package</h3></div></div></div><p>We use the <a class="ulink" href="packages.html" target="_top">ACS Package Manager</a> (APM) to add, remove, and + </p></li></ul></div> + <div class="figure"><a name="idp140623174045016"></a><p class="title"><b>Figure 9.1. Assumptions in this section</b></p><div class="figure-contents"> + + <div class="informaltable"> + <table class="informaltable" cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>Fully qualified domain name of your server</td><td><em class="replaceable"><code>yourserver.test</code></em></td></tr><tr><td>URL of your server</td><td><em class="replaceable"><code>http://yourserver.test:8000</code></em></td></tr><tr><td>Name of development account</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>New Package key</td><td><em class="replaceable"><code>myfirstpackage</code></em></td></tr></tbody></table> + </div> + </div></div><br class="figure-break"> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623174833816"></a>Use the APM to initialize a new package</h3></div></div></div> + + <p>We use the <a class="ulink" href="packages.html" target="_top">ACS Package Manager</a> (APM) to add, remove, and upgrade packages. It handles package meta-data, such as lists of files that belong in the package. Each package is uniquely identified by a package key. To start developing a new package, use the APM to create an empty package with our new - package key, <span class="replaceable"><span class="replaceable">myfirstpackage</span></span>. This will create + package key, <em class="replaceable"><code>myfirstpackage</code></em>. This will create the initial directories, meta-information files, and database entries for a new package. (<a class="ulink" href="apm-requirements.html" target="_top">More info on APM</a>) -</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Browse to - <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver:8000</span></span><a class="ulink" href="/acs-admin/apm" target="_top">/acs-admin/apm</a></code>. -</p></li><li class="listitem"><p>Click <code class="computeroutput">Create a New Package</code>.</p><p>Fill in the fields listed below. <span class="strong"><strong>Ignore the rest (and leave the check boxes alone).</strong></span> +</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Browse to + <code class="computeroutput">http://<em class="replaceable"><code>yourserver:8000</code></em><a class="ulink" href="/acs-admin/apm" target="_top">/acs-admin/apm</a></code>. +</p> + </li><li class="listitem"> + <p>Click <code class="computeroutput">Create a New Package</code>.</p> + <p>Fill in the fields listed below. <span class="strong"><strong>Ignore the rest (and leave the check boxes alone).</strong></span> (Some will change automatically. Don't mess with those.) -</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> +</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> <code class="computeroutput">Package Key</code>: - <strong class="userinput"><code>myfirstpackage</code></strong></p></li><li class="listitem"><p> + <strong class="userinput"><code>myfirstpackage</code></strong></p> + </li><li class="listitem"><p> <code class="computeroutput">Package Name</code>: <strong class="userinput"><code>My First Package</code></strong> </p></li><li class="listitem"><p> @@ -49,28 +87,49 @@ <strong class="userinput"><code>0.1d</code></strong> </p></li><li class="listitem"><p><code class="computeroutput">Summary</code>: <strong class="userinput"><code>This is my first package.</code></strong> - </p></li></ul></div><p>At the bottom, click - <code class="computeroutput"><span class="guibutton"><span class="guibutton">Create Package</span></span></code>. - </p></li></ol></div><p>This creates a package rooted at - <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span></code>. + </p></li></ul></div> + <p>At the bottom, click + <code class="computeroutput"><span class="guibutton">Create Package</span></code>. + </p> + </li></ol></div> + <p>This creates a package rooted at + <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/<em class="replaceable"><code>myfirstpackage</code></em></code>. This is the "home directory" of our new package, and all files in the package will be within this directory. <a class="ulink" href="packages.html" target="_top">More on the structure of - packages</a>). </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592100726520"></a>Add an Application Instance to the Server</h3></div></div></div><p>In order to see your work in progress, you must create a + packages</a>). </p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623175709240"></a>Add an Application Instance to the Server</h3></div></div></div> + + <p>In order to see your work in progress, you must create a map between the URL space of incoming requests and the package application instance. You do this by adding the application in the main site administration). This creates a link between the incoming URL requests and an - <span class="emphasis"><em>instance</em></span> of the application. (<a class="ulink" href="rp-design.html" target="_top">More on applications and nodes</a>)</p><p>You can have instances of a package on one site, each with a + <span class="emphasis"><em>instance</em></span> of the application. (<a class="ulink" href="rp-design.html" target="_top">More on applications and nodes</a>)</p> + <p>You can have instances of a package on one site, each with a different URL and different permissions, all sharing the same code and tables. This requires that a package be developed <span class="emphasis"><em>package-aware</em></span>. You'll see how to do that - in this tutorial.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Browse to -<code class="computeroutput"><span class="replaceable"><span class="replaceable">http://yourserver.test:8000</span></span><a class="ulink" href="/admin/applications/application-add" target="_top">/admin/applications/application-add/</a></code>.</p></li><li class="listitem"><p>Choose "My First Package" from the list and click OK (the other fields are optional).</p></li></ol></div><p>By mounting the package, we've caused all requests to + in this tutorial.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Browse to +<code class="computeroutput"><em class="replaceable"><code>http://yourserver.test:8000</code></em><a class="ulink" href="/admin/applications/application-add" target="_top">/admin/applications/application-add/</a></code>.</p> + </li><li class="listitem"> + <p>Choose "My First Package" from the list and click OK (the other fields are optional).</p> + </li></ol></div> + <p>By mounting the package, we've caused all requests to <code class="computeroutput">http://yourserver.test:8000/myfirstpackage</code> - to be satisfied from the files at <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www</code>.</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592100734328"></a>Quick start</h3></div></div></div><p>The remainder of the tutorial walks you through each file one at a time as you create the package. You can skip all this, and get a working package, by doing the following:</p><pre class="screen">cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/tutorial -psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f myfirstpackage-create.sql + to be satisfied from the files at <code class="computeroutput">/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www</code>.</p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623171946968"></a>Quick start</h3></div></div></div> + + <p>The remainder of the tutorial walks you through each file one at a time as you create the package. You can skip all this, and get a working package, by doing the following:</p> + <pre class="screen">cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/tutorial +psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f myfirstpackage-create.sql cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/ mkdir ../../../../myfirstpackage/lib cp note-list.* ../../../../myfirstpackage/lib/ cp myfirstpackage-*sql ../../../../myfirstpackage/sql/postgresql/ cp myfirstpackage-procs.tcl ../../../../myfirstpackage/tcl/test/ -cp note-procs.tcl ../../../../myfirstpackage/tcl/</pre><p>After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-database.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 9. Development Tutorial </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Setting Up Database Objects</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +cp note-procs.tcl ../../../../myfirstpackage/tcl/</pre> +<p>After restarting the server, the tutorial application will be installed and working at the url you selected in the previous step.</p> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-database.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 9. Development Tutorial </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Setting Up Database Objects</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,12 +9,9 @@ rightLink="tutorial-hierarchical" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-notifications" id="tutorial-notifications"></a>Notifications</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:dave\@student.usyd.edu.au" target="_top">David Bell</a> and <a class="ulink" href="mailto:simon\@collaboraid.net" target="_top">Simon -Carstensen</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>The notifications package allows you to send notifications +<a name="tutorial-notifications" id="tutorial-notifications"></a>Notifications</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:dave\@student.usyd.edu.au" target="_top">David Bell</a> and +<a class="ulink" href="mailto:simon\@collaboraid.net" target="_top">Simon Carstensen</a> +</span></p><span style="color: red"></authorblurb></span><p>The notifications package allows you to send notifications through any defined communications medium (e.g. email, sms) upon some event occurring within the system.</p><p>This tutorial steps through the process of integrating the notifications package with your package.</p><p>First step is to create the notification types. To do this a Index: openacs-4/packages/acs-core-docs/www/tutorial-notifications.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-notifications.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 7 Aug 2017 23:47:53 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/tutorial-notifications.html 8 Nov 2017 09:42:12 -0000 1.19 @@ -1,16 +1,24 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Notifications</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-upgrades.html" title="Distributing upgrades of your package"><link rel="next" href="tutorial-hierarchical.html" title="Hierarchical data"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-upgrades.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-hierarchical.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-notifications"></a>Notifications</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:dave@student.usyd.edu.au" target="_top">David Bell</a> and <a class="ulink" href="mailto:simon@collaboraid.net" target="_top">Simon Carstensen</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>The notifications package allows you to send notifications through any +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Notifications</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-upgrades.html" title="Distributing upgrades of your package"><link rel="next" href="tutorial-hierarchical.html" title="Hierarchical data"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-upgrades.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-hierarchical.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-notifications"></a>Notifications</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:dave@student.usyd.edu.au" target="_top">David Bell</a> and <a class="ulink" href="mailto:simon@collaboraid.net" target="_top">Simon Carstensen</a></p> + </authorblurb></span> + + <p>The notifications package allows you to send notifications through any defined communications medium (e.g. email, sms) upon some event occurring within - the system.</p><p>This tutorial steps through the process of integrating the notifications - package with your package.</p><p>First step is to create the notification types. To do this a script similar + the system.</p> + <p>This tutorial steps through the process of integrating the notifications + package with your package.</p> + + <p>First step is to create the notification types. To do this a script similar to the one below needs to be loaded into Postgresql. I create this script in a package-name/sql/postgresql/package-name-notifications-init.sql file. I then load this file from my create sql file. The following code snippet is taken from Weblogger. It creates a lars_blogger_notif notification type (which was created - above).</p><pre class="programlisting"> + above).</p> + + <pre class="programlisting"> create function inline_0() returns integer as $$ declare impl_id integer; @@ -73,8 +81,11 @@ select inline_0(); drop function inline_0(); - </pre><p>You also need a drop script. This is untested for - comptability with the above script.</p><pre class="programlisting"> + </pre> + + <p>You also need a drop script. This is untested for + comptability with the above script.</p> + <pre class="programlisting"> -- @author gwong@orchardlabs.com,ben@openforce.biz -- @creation-date 2002-05-16 -- @@ -163,17 +174,23 @@ select inline_0(); drop function inline_0(); - </pre><p>The next step is to setup our notification creation. A new notification must + </pre> + + <p>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</p><pre class="programlisting"> + notification::new procedure</p> + + <pre class="programlisting"> notification::new \ -type_id [notification::type::get_type_id \ -short_name lars_blogger_notif] \ -object_id $blog(package_id) \ -response_id $blog(entry_id) \ -notif_subject $blog(title) \ -notif_text $new_content - </pre><p>This code is placed in the Tcl procedure that creates blog + </pre> + + <p>This code is placed in the Tcl procedure that creates blog entries, right after the entry gets created in the code. The <code class="computeroutput">$blog(package_id)</code> is the OpenACS object_id of the Weblogger instance to which the entry has been @@ -183,24 +200,34 @@ 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.</p><p>The final step is to setup the notification subscription process. In this + you can look at it for an example.</p> + + <p>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.</p><p>Such a link can be created using the <code class="computeroutput">notification::display::request_widget</code> - proc:</p><pre class="programlisting"> + entries. The notifications/requests-new page is very handy in this situation.</p> + + <p>Such a link can be created using the <code class="computeroutput">notification::display::request_widget</code> + proc:</p> + <pre class="programlisting"> set notification_chunk [notification::display::request_widget \ -type lars_blogger_notif \ -object_id $package_id \ -pretty_name [lars_blog_name] \ -url [lars_blog_public_package_url] \ ] - </pre><p>which will return something like + </pre> + <p>which will return something like + </p><pre class="programlisting"> You may <a href="/notifications/request-new?...">request notification</a> for Weblogger.</pre><p> which can be readily put on the blog index page. The <code class="computeroutput">pretty_name</code> parameter is what appears at the end of the text returned (i.e. "... request notification</a> for pretty_name"), The <code class="computeroutput">url</code> parameter should be set to the address we want the user - to be redirected to after they have finished the subscription process.</p><p>This should be all you need to implement a notification system. For more examples - look at the forums package.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-upgrades.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-hierarchical.html">Next</a></td></tr><tr><td width="40%" align="left">Distributing upgrades of your package </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Hierarchical data</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + to be redirected to after they have finished the subscription process.</p> + + <p>This should be all you need to implement a notification system. For more examples + look at the forums package.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-upgrades.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-hierarchical.html">Next</a></td></tr><tr><td width="40%" align="left">Distributing upgrades of your package </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Hierarchical data</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-pages.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-pages.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,29 +9,27 @@ rightLink="tutorial-debug" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-pages" id="tutorial-pages"></a>Creating Web Pages</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +<a name="tutorial-pages" id="tutorial-pages"></a>Creating Web Pages</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592102536376" id="idp140592102536376"></a>Install some API</h3></div></div></div><p>As a workaround for missing content-repository functionality, -copy a provided file into the directory for Tcl files:</p><pre class="screen"><span class="action"><span class="action">cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/tcl/</span></span></pre><p>To make this file take effect, go to the <a class="ulink" href="/acs-admin/apm" target="_top">APM</a> and choose "Reload +<a name="idp140623165919032" id="idp140623165919032"></a>Install some API</h3></div></div></div><p>As a workaround for missing content-repository functionality, +copy a provided file into the directory for Tcl files:</p><pre class="screen"><span class="action">cp /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/tcl/</span></pre><p>To make this file take effect, go to the <a class="ulink" href="/acs-admin/apm" target="_top">APM</a> and choose "Reload changed" for "MyFirstPackage".</p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592102540216" id="idp140592102540216"></a>Page Map</h3></div></div></div><p>Our package will have two visible pages. The first shows a list +<a name="idp140623162540728" id="idp140623162540728"></a>Page Map</h3></div></div></div><p>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 separate file and include it on the index page.</p><div class="figure"> -<a name="idp140592102541576" id="idp140592102541576"></a><p class="title"><strong>Figure 9.5. Page +<a name="idp140623165411624" id="idp140623165411624"></a><p class="title"><strong>Figure 9.5. Page Map</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/tutorial-page-map.png" align="middle" alt="Page Map"></div></div> </div><br class="figure-break"> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592107977784" id="idp140592107977784"></a>Build the "Index" page</h3></div></div></div><p>Each user-visible page in your package has, typically, three +<a name="idp140623162336104" id="idp140623162336104"></a>Build the "Index" page</h3></div></div></div><p>Each user-visible page in your package has, typically, three parts. The <code class="computeroutput">tcl</code> file holds the procedural logic for the page, including Tcl and database-independent SQL code, and does things like check @@ -41,14 +39,14 @@ database-specific SQL. The default page in any directory is <code class="computeroutput">index</code>, so we'll build that first, starting with the Tcl file:</p><pre class="screen"> -[$OPENACS_SERVICE_NAME postgresql]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackages/www</code></strong> +[$OPENACS_SERVICE_NAME postgresql]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackages/www</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs index.tcl</code></strong> </pre><p>Paste this into the file.</p><pre class="programlisting"> ad_page_contract { This is the main page for the package. It displays all of the Notes and provides links to edit them and to create new Notes. \@author Your Name (you\@example.com) - \@cvs-id $‌Id: index.tcl,v 1.2.22.1 2015/09/10 08:21:20 gustafn Exp $ + \@cvs-id $‌Id: index.tcl,v 1.3 2017/08/07 23:47:54 gustafn Exp $ } set page_title [ad_conn instance_name] @@ -66,8 +64,8 @@ </pre><p>The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/lib</code></strong> -[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/lib</code></strong> +[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/lib</code></strong> +[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/lib</code></strong> [$OPENACS_SERVICE_NAME lib]$ <strong class="userinput"><code>emacs note-list.tcl</code></strong> </pre><pre class="programlisting"> template::list::create \ @@ -121,14 +119,14 @@ your installation.</p><p>Create the add/edit page. If note_id is passed in, it display that note, and can change to edit mode if appropriate. Otherwise, it presents a form for adding notes.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME lib]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www</code></strong> +[$OPENACS_SERVICE_NAME lib]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-edit.tcl</code></strong> </pre><pre class="programlisting"> ad_page_contract { This is the view-edit page for notes. \@author Your Name (you\@example.com) - \@cvs-id $‌Id: note-edit.tcl,v 1.3.2.1 2015/09/10 08:21:20 gustafn Exp $ + \@cvs-id $‌Id: note-edit.tcl,v 1.4 2017/08/07 23:47:54 gustafn Exp $ \@param item_id If present, assume we are editing that note. Otherwise, we are creating a new note. } { @@ -187,7 +185,7 @@ This deletes a note \@author Your Name (you\@example.com) - \@cvs-id $‌Id: note-delete.tcl,v 1.3.2.1 2015/09/10 08:21:20 gustafn Exp $ + \@cvs-id $‌Id: note-delete.tcl,v 1.4 2017/08/07 23:47:54 gustafn Exp $ \@param item_id The item_id of the note to delete } { Index: openacs-4/packages/acs-core-docs/www/tutorial-pages.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-pages.html,v diff -u -r1.45 -r1.46 --- openacs-4/packages/acs-core-docs/www/tutorial-pages.html 7 Aug 2017 23:47:53 -0000 1.45 +++ openacs-4/packages/acs-core-docs/www/tutorial-pages.html 8 Nov 2017 09:42:12 -0000 1.46 @@ -1,9 +1,29 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Creating Web Pages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial-database.html" title="Setting Up Database Objects"><link rel="next" href="tutorial-debug.html" title="Debugging and Automated Testing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-database.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-debug.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-pages"></a>Creating Web Pages</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592102536376"></a>Install some API</h3></div></div></div><p>As a workaround for missing content-repository functionality, copy a provided file into the directory for Tcl files:</p><pre class="screen"> - <span class="action"><span class="action">cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/tcl/</span></span></pre><p>To make this file take effect, go to the <a class="ulink" href="/acs-admin/apm" target="_top">APM</a> and choose "Reload changed" for "MyFirstPackage".</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592102540216"></a>Page Map</h3></div></div></div><p>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 separate file and include it on the index page.</p><div class="figure"><a name="idp140592102541576"></a><p class="title"><b>Figure 9.5. Page Map</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/tutorial-page-map.png" align="middle" alt="Page Map"></div></div></div><br class="figure-break"></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592107977784"></a>Build the "Index" page</h3></div></div></div><p>Each user-visible page in your package has, typically, +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Creating Web Pages</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial.html" title="Chapter 9. Development Tutorial"><link rel="previous" href="tutorial-database.html" title="Setting Up Database Objects"><link rel="next" href="tutorial-debug.html" title="Debugging and Automated Testing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-database.html">Prev</a> </td><th width="60%" align="center">Chapter 9. Development Tutorial</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-debug.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-pages"></a>Creating Web Pages</h2></div></div></div> + + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623165919032"></a>Install some API</h3></div></div></div> + + <p>As a workaround for missing content-repository functionality, copy a provided file into the directory for Tcl files:</p> + <pre class="screen"> + <span class="action">cp /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/tutorial/note-procs.tcl /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/tcl/</span></pre> + <p>To make this file take effect, go to the <a class="ulink" href="/acs-admin/apm" target="_top">APM</a> and choose "Reload changed" for "MyFirstPackage".</p> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623162540728"></a>Page Map</h3></div></div></div> + + <p>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 separate file and include it on the index page.</p> + <div class="figure"><a name="idp140623165411624"></a><p class="title"><b>Figure 9.5. Page Map</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/tutorial-page-map.png" align="middle" alt="Page Map"></div> + </div></div><br class="figure-break"> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623162336104"></a>Build the "Index" page</h3></div></div></div> + + <p>Each user-visible page in your package has, typically, three parts. The <code class="computeroutput">tcl</code> file holds the procedural logic for the page, including Tcl and database-independent SQL code, and does things like @@ -13,8 +33,11 @@ and <code class="computeroutput">-oracle.xql</code> files contains database-specific SQL. The default page in any directory is <code class="computeroutput">index</code>, so we'll build that - first, starting with the Tcl file:</p><pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackages/www</code></strong> -[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs index.tcl</code></strong></pre><p>Paste this into the file.</p><pre class="programlisting">ad_page_contract { + first, starting with the Tcl file:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME postgresql]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackages/www</code></strong> +[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs index.tcl</code></strong></pre> + <p>Paste this into the file.</p> + <pre class="programlisting">ad_page_contract { This is the main page for the package. It displays all of the Notes and provides links to edit them and to create new Notes. @author Your Name (you@example.com) @@ -28,12 +51,17 @@ # tcl-indent-level: 4 # indent-tabs-mode: nil # End: -</pre><p>Now <code class="computeroutput">index.adp</code>:</p><pre class="programlisting"><master> +</pre> + <p>Now <code class="computeroutput">index.adp</code>:</p> + <pre class="programlisting"><master> <property name="doc(title)">@page_title;literal@</property> <property name="context">@context;literal@</property> -<include src="/packages/myfirstpackage/lib/note-list"></pre><p>The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.</p><pre class="screen">[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/lib</code></strong> -[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/lib</code></strong> -[$OPENACS_SERVICE_NAME lib]$ <strong class="userinput"><code>emacs note-list.tcl</code></strong></pre><pre class="programlisting">template::list::create \ +<include src="/packages/myfirstpackage/lib/note-list"></pre> + <p>The index page includes the list page, which we put in /lib instead of /www to designate that it's available for reuse by other packages.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> mkdir /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/lib</code></strong> +[$OPENACS_SERVICE_NAME www]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/lib</code></strong> +[$OPENACS_SERVICE_NAME lib]$ <strong class="userinput"><code>emacs note-list.tcl</code></strong></pre> + <pre class="programlisting">template::list::create \ -name notes \ -multirow notes \ -actions { "Add a Note" note-edit} \ @@ -76,9 +104,15 @@ # tcl-indent-level: 4 # indent-tabs-mode: nil # End: -</pre><pre class="screen">[$OPENACS_SERVICE_NAME lib]$ <strong class="userinput"><code>emacs note-list.adp</code></strong></pre><pre class="programlisting"><listtemplate name="notes"></listtemplate></pre><p>You can test your work by viewing the page /myfirstpackage on your installation.</p><p>Create the add/edit page. If note_id is passed in, - it display that note, and can change to edit mode if appropriate. Otherwise, it presents a form for adding notes.</p><pre class="screen">[$OPENACS_SERVICE_NAME lib]$<strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www</code></strong> -[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-edit.tcl</code></strong></pre><pre class="programlisting">ad_page_contract { +</pre> +<pre class="screen">[$OPENACS_SERVICE_NAME lib]$ <strong class="userinput"><code>emacs note-list.adp</code></strong></pre> +<pre class="programlisting"><listtemplate name="notes"></listtemplate></pre> +<p>You can test your work by viewing the page /myfirstpackage on your installation.</p> + <p>Create the add/edit page. If note_id is passed in, + it display that note, and can change to edit mode if appropriate. Otherwise, it presents a form for adding notes.</p> + <pre class="screen">[$OPENACS_SERVICE_NAME lib]$<strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www</code></strong> +[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-edit.tcl</code></strong></pre> + <pre class="programlisting">ad_page_contract { This is the view-edit page for notes. @author Your Name (you@example.com) @@ -124,13 +158,18 @@ # tcl-indent-level: 4 # indent-tabs-mode: nil # End: -</pre><pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-edit.adp</code></strong></pre><pre class="programlisting"><master> +</pre> +<pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-edit.adp</code></strong></pre> + <pre class="programlisting"><master> <property name="doc(title)">@page_title;literal@</property> <property name="context">@context;literal@</property> <property name="focus">note.title</property> -<formtemplate id="note"></formtemplate></pre><p>And the delete page. Since it has no UI, there is only a - Tcl page, and no adp page.</p><pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-delete.tcl</code></strong></pre><pre class="programlisting">ad_page_contract { +<formtemplate id="note"></formtemplate></pre> + <p>And the delete page. Since it has no UI, there is only a + Tcl page, and no adp page.</p> +<pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note-delete.tcl</code></strong></pre> + <pre class="programlisting">ad_page_contract { This deletes a note @author Your Name (you@example.com) @@ -154,4 +193,6 @@ # tcl-indent-level: 4 # indent-tabs-mode: nil # End: -</pre></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-database.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-debug.html">Next</a></td></tr><tr><td width="40%" align="left">Setting Up Database Objects </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Debugging and Automated Testing</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-database.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-debug.html">Next</a></td></tr><tr><td width="40%" align="left">Setting Up Database Objects </td><td width="20%" align="center"><a accesskey="u" href="tutorial.html">Up</a></td><td width="40%" align="right"> Debugging and Automated Testing</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-parameters.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-parameters.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial-parameters.html 7 Aug 2017 23:47:53 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial-parameters.html 8 Nov 2017 09:42:12 -0000 1.11 @@ -1,8 +1,20 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adding in parameters for your package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-wysiwyg-editor.html" title="Enabling WYSIWYG"><link rel="next" href="tutorial-upgrade-scripts.html" title="Writing upgrade scripts"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-wysiwyg-editor.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-upgrade-scripts.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-parameters"></a>Adding in parameters for your package</h2></div></div></div><p>Each instance of a package can have paramaters associated +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Adding in parameters for your package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-wysiwyg-editor.html" title="Enabling WYSIWYG"><link rel="next" href="tutorial-upgrade-scripts.html" title="Writing upgrade scripts"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-wysiwyg-editor.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-upgrade-scripts.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-parameters"></a>Adding in parameters for your package</h2></div></div></div> + + <p>Each instance of a package can have paramaters associated with it. These are like preferences, and they can be set by the administrator for each application to change the behavior of your - application. </p><p>To add parameters for your package, go to the Automatic - Package Manager (/acs-admin/apm)</p><p>Click on your package</p><p>Under the Manage section, click on Parameters</p><p>It's fairly self-explanatory at this point. Create the + application. </p> + + <p>To add parameters for your package, go to the Automatic + Package Manager (/acs-admin/apm)</p> + + <p>Click on your package</p> + + <p>Under the Manage section, click on Parameters</p> + + <p>It's fairly self-explanatory at this point. Create the parameters you want, and then access them in your code using the - parameter::get procedure.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-wysiwyg-editor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-upgrade-scripts.html">Next</a></td></tr><tr><td width="40%" align="left">Enabling WYSIWYG </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Writing upgrade scripts</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + parameter::get procedure.</p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-wysiwyg-editor.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-upgrade-scripts.html">Next</a></td></tr><tr><td width="40%" align="left">Enabling WYSIWYG </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Writing upgrade scripts</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,7 +9,7 @@ rightLink="tutorial-wysiwyg-editor" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-schedule-procs" id="tutorial-schedule-procs"></a>Scheduled Procedures</h2></div></div></div><p>Put this proc in a file <code class="computeroutput">/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>/tcl/scheduled-init.tcl</code>. +<a name="tutorial-schedule-procs" id="tutorial-schedule-procs"></a>Scheduled Procedures</h2></div></div></div><p>Put this proc in a file <code class="computeroutput">/packages/<em class="replaceable"><code>myfirstpackage</code></em>/tcl/scheduled-init.tcl</code>. Files in /tcl with the -init.tcl ending are sourced on server startup. This one executes my_proc every 60 seconds:</p><pre class="programlisting"> ad_schedule_proc 60 myfirstpackage::my_proc Index: openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html 7 Aug 2017 23:47:53 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/tutorial-schedule-procs.html 8 Nov 2017 09:42:12 -0000 1.12 @@ -1,7 +1,14 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Scheduled Procedures</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-caching.html" title="Basic Caching"><link rel="next" href="tutorial-wysiwyg-editor.html" title="Enabling WYSIWYG"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-caching.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-wysiwyg-editor.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-schedule-procs"></a>Scheduled Procedures</h2></div></div></div><p>Put this proc in a file <code class="computeroutput">/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span>/tcl/scheduled-init.tcl</code>. Files in /tcl with the -init.tcl ending are sourced on server startup. This one executes my_proc every 60 seconds:</p><pre class="programlisting">ad_schedule_proc 60 myfirstpackage::my_proc -</pre><p>This executes once a day, at midnight:</p><pre class="programlisting">ad_schedule_proc \ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Scheduled Procedures</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-caching.html" title="Basic Caching"><link rel="next" href="tutorial-wysiwyg-editor.html" title="Enabling WYSIWYG"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-caching.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-wysiwyg-editor.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-schedule-procs"></a>Scheduled Procedures</h2></div></div></div> + + <p>Put this proc in a file <code class="computeroutput">/packages/<em class="replaceable"><code>myfirstpackage</code></em>/tcl/scheduled-init.tcl</code>. Files in /tcl with the -init.tcl ending are sourced on server startup. This one executes my_proc every 60 seconds:</p> + <pre class="programlisting">ad_schedule_proc 60 myfirstpackage::my_proc +</pre> +<p>This executes once a day, at midnight:</p> + <pre class="programlisting">ad_schedule_proc \ -schedule_proc ns_schedule_daily \ [list 0 0] \ myfirstpackage::my_proc -</pre><p>See <a class="ulink" href="/api-doc/proc-view?proc=ad%5fschedule%5fproc" target="_top">ad_schedule_proc</a> for more information.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-caching.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-wysiwyg-editor.html">Next</a></td></tr><tr><td width="40%" align="left">Basic Caching </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Enabling WYSIWYG</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + <p>See <a class="ulink" href="/api-doc/proc-view?proc=ad%5fschedule%5fproc" target="_top">ad_schedule_proc</a> for more information.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-caching.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-wysiwyg-editor.html">Next</a></td></tr><tr><td width="40%" align="left">Basic Caching </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Enabling WYSIWYG</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-second-database.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-second-database.html,v diff -u -r1.11 -r1.12 --- openacs-4/packages/acs-core-docs/www/tutorial-second-database.html 7 Aug 2017 23:47:53 -0000 1.11 +++ openacs-4/packages/acs-core-docs/www/tutorial-second-database.html 8 Nov 2017 09:42:12 -0000 1.12 @@ -1,10 +1,15 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Connect to a second database</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-upgrade-scripts.html" title="Writing upgrade scripts"><link rel="next" href="tutorial-future-topics.html" title="Future Topics"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-upgrade-scripts.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-future-topics.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-second-database"></a>Connect to a second database</h2></div></div></div><p>It is possible to use the OpenACS Tcl database API with +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Connect to a second database</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-upgrade-scripts.html" title="Writing upgrade scripts"><link rel="next" href="tutorial-future-topics.html" title="Future Topics"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-upgrade-scripts.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-future-topics.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-second-database"></a>Connect to a second database</h2></div></div></div> + + <p>It is possible to use the OpenACS Tcl database API with other databases. In this example, the OpenACS site uses a PostGre database, and accesses another PostGre database called - legacy.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Modify config.tcl to accommodate the legacy database, and to + legacy.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Modify config.tcl to accommodate the legacy database, and to ensure that the legacy database is not used for standard - OpenACS queries:</p><pre class="programlisting">ns_section ns/db/pools + OpenACS queries:</p> + <pre class="programlisting">ns_section ns/db/pools ns_param pool1 "Pool 1" ns_param pool2 "Pool 2" ns_param pool3 "Pool 3" @@ -56,14 +61,20 @@ ns_section ns/server/${server}/acs/database ns_param database_names [list main legacy] ns_param pools_main [list pool1 pool2 pool3] -ns_param pools_legacy [list legacy]</pre></li><li class="listitem"><p>To use the legacy database, use the +ns_param pools_legacy [list legacy]</pre> + </li><li class="listitem"> + <p>To use the legacy database, use the <code class="code">-dbn</code> flag for any of the <code class="code">db_</code> API calls. For example, suppose there is a table called "foo" in the legacy system, with a field "bar". List "bar" for all records with - this Tcl file:</p><pre class="programlisting">db_foreach -dbn legacy get_bar_query { + this Tcl file:</p> + <pre class="programlisting">db_foreach -dbn legacy get_bar_query { select bar from foo limit 10 } { ns_write "<br/>$bar" -}</pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-upgrade-scripts.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-future-topics.html">Next</a></td></tr><tr><td width="40%" align="left">Writing upgrade scripts </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Future Topics</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +}</pre> + + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-upgrade-scripts.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-future-topics.html">Next</a></td></tr><tr><td width="40%" align="left">Writing upgrade scripts </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Future Topics</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-specs.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-specs.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -21,12 +21,12 @@ supporting files, like page maps or schema diagrams, in the <code class="computeroutput">www/doc/xml</code> directory, and store png or jpg versions of supporting files in the <code class="computeroutput">www/doc</code> directory.</p><p>For this tutorial, you should instead install the pre-written -documentation files for the tutorial app. Log in as <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>, create the +documentation files for the tutorial app. Log in as <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>, create the standard directories, and copy the prepared documentation:</p><pre class="screen"> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>mkdir -p www/doc/xml</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cd www/doc/xml</code></strong> -[$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/myfirstpackage/* .</code></strong> +[$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cp /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/myfirstpackage/* .</code></strong> [$OPENACS_SERVICE_NAME xml]$ </pre><p>OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the @@ -60,7 +60,7 @@ Writing index.html for book [$OPENACS_SERVICE_NAME xml]$ </pre><p>Verify that the documentation was generated and reflects your -changes by browsing to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yoursite</span></span>:8000/myfirstpackage/doc</code> +changes by browsing to <code class="computeroutput">http://<em class="replaceable"><code>yoursite</code></em>:8000/myfirstpackage/doc</code> </p> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/tutorial-specs.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-specs.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/tutorial-specs.html 7 Aug 2017 23:47:53 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/tutorial-specs.html 8 Nov 2017 09:42:12 -0000 1.16 @@ -1,39 +1,49 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Write the Requirements and Design Specs</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="next" href="tutorial-cvs.html" title="Add the new package to CVS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-specs"></a>Write the Requirements and Design Specs</h2></div></div></div><p>Before you get started you should make yourself familiar with +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Write the Requirements and Design Specs</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="next" href="tutorial-cvs.html" title="Add the new package to CVS"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-cvs.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-specs"></a>Write the Requirements and Design Specs</h2></div></div></div> + + <p>Before you get started you should make yourself familiar with the tags that are used to write your documentation. For tips on - editing SGML files in emacs, see <a class="xref" href="docbook-primer.html" title="OpenACS Documentation Guide">the section called “OpenACS Documentation Guide”</a>.</p><p>It's time to document. For the tutorial we'll use + editing SGML files in emacs, see <a class="xref" href="docbook-primer.html" title="OpenACS Documentation Guide">the section called “OpenACS Documentation Guide”</a>.</p> + <p>It's time to document. For the tutorial we'll use pre-written documentation. When creating a package from scratch, start by copying the documentation template from <code class="computeroutput">/var/lib/aolserver/openacs-dev/packages/acs-core-docs/xml/docs/xml/package-documentation-template.xml</code> to - <code class="computeroutput">myfirstpackage/www/docs/xml/index.xml</code>.</p><p>You then edit that file with emacs to write the + <code class="computeroutput">myfirstpackage/www/docs/xml/index.xml</code>.</p> + <p>You then edit that file with emacs to write the requirements and design sections, generate the html, and start coding. Store any supporting files, like page maps or schema diagrams, in the <code class="computeroutput">www/doc/xml</code> directory, and store png or jpg versions of supporting files in the - <code class="computeroutput">www/doc</code> directory.</p><p>For this tutorial, you should instead install the + <code class="computeroutput">www/doc</code> directory.</p> + <p>For this tutorial, you should instead install the pre-written documentation files for the tutorial app. Log in - as <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>, create the standard - directories, and copy the prepared documentation:</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/</code></strong> + as <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>, create the standard + directories, and copy the prepared documentation:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>mkdir -p www/doc/xml</code></strong> [$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cd www/doc/xml</code></strong> -[$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cp /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-core-docs/www/files/myfirstpackage/* .</code></strong> -[$OPENACS_SERVICE_NAME xml]$</pre><p> OpenACS uses DocBook for documentation. DocBook is +[$OPENACS_SERVICE_NAME xml]$ <strong class="userinput"><code>cp /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-core-docs/www/files/myfirstpackage/* .</code></strong> +[$OPENACS_SERVICE_NAME xml]$</pre> + <p> OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the tags you use indicate meaning, not intended appearance. The style sheet will determine appearance. You will edit the text in an xml file, and then process the file - into html for reading.</p><p>Open the file <code class="computeroutput">index.xml</code> + into html for reading.</p> + <p>Open the file <code class="computeroutput">index.xml</code> in emacs. Examine the file. Find the version history (look for the tag <code class="computeroutput"><revhistory></code>). Add a new record to the document version history. Look for the <code class="computeroutput"><authorgroup></code> tag and - add yourself as a second author. Save and exit.</p><p>Process the xml file to create html documentation. The + add yourself as a second author. Save and exit.</p> + <p>Process the xml file to create html documentation. The html documentation, including supporting files such as pictures, is stored in the <code class="computeroutput">www/docs/</code> directory. A Makefile is provided to generate html from the xml, and copy all of the supporting files. If Docbook is set up correctly, all you need - to do is:</p><pre class="screen">[$OPENACS_SERVICE_NAME xml]$<strong class="userinput"><code> make</code></strong> + to do is:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME xml]$<strong class="userinput"><code> make</code></strong> cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml Writing requirements-introduction.html for chapter(requirements-introduction) Writing requirements-overview.html for chapter(requirements-overview) @@ -49,5 +59,7 @@ Writing admin-guide.html for chapter(admin-guide) Writing bi01.html for bibliography Writing index.html for book -[$OPENACS_SERVICE_NAME xml]$</pre><p>Verify that the documentation was generated and reflects - your changes by browsing to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yoursite</span></span>:8000/myfirstpackage/doc</code></p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 10. Advanced Topics </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Add the new package to CVS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +[$OPENACS_SERVICE_NAME xml]$</pre> + <p>Verify that the documentation was generated and reflects + your changes by browsing to <code class="computeroutput">http://<em class="replaceable"><code>yoursite</code></em>:8000/myfirstpackage/doc</code></p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-advanced.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-cvs.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 10. Advanced Topics </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Add the new package to CVS</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,11 +9,8 @@ rightLink="tutorial-second-database" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="tutorial-upgrade-scripts" id="tutorial-upgrade-scripts"></a>Writing upgrade scripts</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>If your package changes its data model, you have to write an +<a name="tutorial-upgrade-scripts" id="tutorial-upgrade-scripts"></a>Writing upgrade scripts</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:jade\@rubick.com" target="_top">Jade Rubick</a> +</span></p><span style="color: red"></authorblurb></span><p>If your package changes its data model, you have to write an upgrade script. This is very easy in OpenACS.</p><p>First, you want to make sure you change the original .sql file so that new installation will have the new data model.</p><p>Next, check what version your package is currently at. For example, it may be at version 1.0b1. Create a file in Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html 7 Aug 2017 23:47:53 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial-upgrade-scripts.html 8 Nov 2017 09:42:12 -0000 1.11 @@ -1,18 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Writing upgrade scripts</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-parameters.html" title="Adding in parameters for your package"><link rel="next" href="tutorial-second-database.html" title="Connect to a second database"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-parameters.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-second-database.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-upgrade-scripts"></a>Writing upgrade scripts</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>If your package changes its data model, you have to write an - upgrade script. This is very easy in OpenACS. </p><p>First, you want to make sure you change the original .sql - file so that new installation will have the new data model.</p><p>Next, check what version your package is currently at. For +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Writing upgrade scripts</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-parameters.html" title="Adding in parameters for your package"><link rel="next" href="tutorial-second-database.html" title="Connect to a second database"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-parameters.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-second-database.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-upgrade-scripts"></a>Writing upgrade scripts</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:jade@rubick.com" target="_top">Jade Rubick</a></p> + </authorblurb></span> + <p>If your package changes its data model, you have to write an + upgrade script. This is very easy in OpenACS. </p> + + <p>First, you want to make sure you change the original .sql + file so that new installation will have the new data model.</p> + + <p>Next, check what version your package is currently at. For example, it may be at version 1.0b1. Create a file in sql/postgres/upgrade called packagename-1.0b1-1.0b2.sql and put the SQL code that will update the data model. For example, if you add in a column, you would have an alter table add column statement in this file. Test this out very well, because data model changes are more serious and fundamental changes than the - program .tcl files. </p><p>Now use the APM to create a new package version + program .tcl files. </p> + + <p>Now use the APM to create a new package version 1.0b2. Commit all your changes, tag the release (<a class="xref" href="tutorial-upgrades.html" title="Distributing upgrades of your package">the section called “Distributing upgrades of your package”</a>), and both new installations and upgrades - will be taken care of.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-parameters.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-second-database.html">Next</a></td></tr><tr><td width="40%" align="left">Adding in parameters for your package </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Connect to a second database</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + will be taken care of.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-parameters.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-second-database.html">Next</a></td></tr><tr><td width="40%" align="left">Adding in parameters for your package </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Connect to a second database</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-upgrades.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,10 +10,7 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tutorial-upgrades" id="tutorial-upgrades"></a>Distributing upgrades of your -package</h2></div></div></div><div class="authorblurb"> -<p>by Jade Rubick</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>The OpenACS Package Repository builds a list of packages that +package</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by Jade Rubick</span></p><span style="color: red"></authorblurb></span><p>The OpenACS Package Repository builds a list of packages that can be installed on OpenACS installations, and can be used by administrators to update their packages. If you are a package developer, there are a couple of steps you need to take in order to Index: openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html 7 Aug 2017 23:47:53 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial-upgrades.html 8 Nov 2017 09:42:12 -0000 1.11 @@ -1,17 +1,27 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Distributing upgrades of your package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-distribute.html" title="Prepare the package for distribution."><link rel="next" href="tutorial-notifications.html" title="Notifications"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-distribute.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-notifications.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-upgrades"></a>Distributing upgrades of your package</h2></div></div></div><div class="authorblurb"><p>by Jade Rubick</p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>The OpenACS Package Repository builds a list of packages +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Distributing upgrades of your package</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-distribute.html" title="Prepare the package for distribution."><link rel="next" href="tutorial-notifications.html" title="Notifications"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-distribute.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-notifications.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-upgrades"></a>Distributing upgrades of your package</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by Jade Rubick</p> + </authorblurb></span> + <p>The OpenACS Package Repository builds a list of packages that can be installed on OpenACS installations, and can be used by administrators to update their packages. If you are a package developer, there are a couple of steps you need to take in order - to release a new version of your package. </p><p>For the sake of this example, let's assume you are the + to release a new version of your package. </p> + + <p>For the sake of this example, let's assume you are the package owner of the <code class="computeroutput">notes</code> package. It is currently at version 1.5, and you are planning on - releasing version 1.6. It is also located in OpenACS's CVS.</p><p>To release your package:</p><pre class="screen">cd /path/to/notes + releasing version 1.6. It is also located in OpenACS's CVS.</p> + + <p>To release your package:</p> + <pre class="screen">cd /path/to/notes cvs commit -m "Update package to version 1.6." cvs tag notes-1-6-final cvs tag -F openacs-5-1-compat -</pre><p>Of course, make sure you write upgrade scripts - (<a class="xref" href="tutorial-upgrade-scripts.html" title="Writing upgrade scripts">the section called “Writing upgrade scripts”</a>)</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-distribute.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-notifications.html">Next</a></td></tr><tr><td width="40%" align="left">Prepare the package for distribution. </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Notifications</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + + <p>Of course, make sure you write upgrade scripts + (<a class="xref" href="tutorial-upgrade-scripts.html" title="Writing upgrade scripts">the section called “Writing upgrade scripts”</a>)</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-distribute.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-notifications.html">Next</a></td></tr><tr><td width="40%" align="left">Prepare the package for distribution. </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Notifications</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -15,7 +15,7 @@ <code class="computeroutput">note/495</code>. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh:</p><pre class="screen"> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www</code></strong> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note.vuh</code></strong> </pre><p>Paste this into the file:</p><pre class="programlisting"> # Transform requests of type: a/b Index: openacs-4/packages/acs-core-docs/www/tutorial-vuh.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-vuh.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 7 Aug 2017 23:47:53 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/tutorial-vuh.html 8 Nov 2017 09:42:12 -0000 1.20 @@ -1,7 +1,12 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using .vuh files for pretty urls</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-hierarchical.html" title="Hierarchical data"><link rel="next" href="tutorial-css-layout.html" title="Laying out a page with CSS instead of tables"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-hierarchical.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-css-layout.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-vuh"></a>Using .vuh files for pretty urls</h2></div></div></div><p>.Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of <code class="computeroutput">note-edit?item_id=495</code>, we can use <code class="computeroutput">note/495</code>. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh:</p><pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/myfirstpackage/www</code></strong> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Using .vuh files for pretty urls</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-hierarchical.html" title="Hierarchical data"><link rel="next" href="tutorial-css-layout.html" title="Laying out a page with CSS instead of tables"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-hierarchical.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-css-layout.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-vuh"></a>Using .vuh files for pretty urls</h2></div></div></div> + + <p>.Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of <code class="computeroutput">note-edit?item_id=495</code>, we can use <code class="computeroutput">note/495</code>. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/myfirstpackage/www</code></strong> [$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs note.vuh</code></strong> -</pre><p>Paste this into the file:</p><pre class="programlisting"># Transform requests of type: a/b +</pre> + <p>Paste this into the file:</p> + <pre class="programlisting"># Transform requests of type: a/b # into this internal request: A?c=b # for example, note/495 > note-edit?item_id=496 # a: base name of this .vuh file @@ -24,7 +29,12 @@ # tcl-indent-level: 4 # indent-tabs-mode: nil # End: -</pre><p>We parse the incoming request and treat everything after the final / as the item id. Note that this simple redirection will lose any additional query parameters passed in. Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id.</p><p>We use <code class="computeroutput">rp_form_put</code> to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh).</p><p>Next, modify note-list so that its link is of the new form.:</p><pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs ../lib/note-edit.tcl</code></strong></pre><pre class="programlisting"> +</pre> + <p>We parse the incoming request and treat everything after the final / as the item id. Note that this simple redirection will lose any additional query parameters passed in. Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id.</p> + <p>We use <code class="computeroutput">rp_form_put</code> to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh).</p> + <p>Next, modify note-list so that its link is of the new form.:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME www]$ <strong class="userinput"><code>emacs ../lib/note-edit.tcl</code></strong></pre> + <pre class="programlisting"> db_multirow \ -extend { edit_url @@ -39,8 +49,12 @@ <span class="strong"><strong>set edit_url [export_vars -base "note/$item_id"]</strong></span> set delete_url [export_vars -base "note-delete" {item_id}] } -</pre><p>You may also need to change some of the links in your +</pre> + + <p>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.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-hierarchical.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-css-layout.html">Next</a></td></tr><tr><td width="40%" align="left">Hierarchical data </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Laying out a page with CSS instead of tables</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + being served from.</p> + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-hierarchical.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-css-layout.html">Next</a></td></tr><tr><td width="40%" align="left">Hierarchical data </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Laying out a page with CSS instead of tables</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,11 +10,9 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="tutorial-wysiwyg-editor" id="tutorial-wysiwyg-editor"></a>Enabling -WYSIWYG</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:nima.mazloumi\@gmx.de" target="_top">Nima Mazloumi</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Most of the forms in OpenACS are created using the form builder, +WYSIWYG</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:nima.mazloumi\@gmx.de" target="_top">Nima +Mazloumi</a> +</span></p><span style="color: red"></authorblurb></span><p>Most of the forms in OpenACS are created using the form builder, see <a class="xref" href="form-builder" title="Using Form Builder: building html forms dynamically">the section called “Using Form Builder: building html forms dynamically”</a>. For detailed information on the API Index: openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html 7 Aug 2017 23:47:53 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/tutorial-wysiwyg-editor.html 8 Nov 2017 09:42:12 -0000 1.11 @@ -1,14 +1,22 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Enabling WYSIWYG</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-schedule-procs.html" title="Scheduled Procedures"><link rel="next" href="tutorial-parameters.html" title="Adding in parameters for your package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-schedule-procs.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-parameters.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-wysiwyg-editor"></a>Enabling WYSIWYG</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:nima.mazloumi@gmx.de" target="_top">Nima Mazloumi</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Most of the forms in OpenACS are created using the form builder, see <a class="xref" href="form-builder.html" title="Using Form Builder: building html forms dynamically">the section called “Using Form Builder: building html forms dynamically”</a>. For detailed information on the - API take a look <a class="ulink" href="/api-doc/proc-view?proc=ad_form" target="_top">here</a>.</p><p>The following section shows how you can modify your form to allow WYSIWYG functionalities.</p><p>Convert your page to use <code class="code">ad_form</code> (some changes but worth it)</p><p>Here an examples. From:</p><pre class="programlisting"> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Enabling WYSIWYG</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="tutorial-advanced.html" title="Chapter 10. Advanced Topics"><link rel="previous" href="tutorial-schedule-procs.html" title="Scheduled Procedures"><link rel="next" href="tutorial-parameters.html" title="Adding in parameters for your package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="tutorial-schedule-procs.html">Prev</a> </td><th width="60%" align="center">Chapter 10. Advanced Topics</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-parameters.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="tutorial-wysiwyg-editor"></a>Enabling WYSIWYG</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:nima.mazloumi@gmx.de" target="_top">Nima Mazloumi</a></p> + </authorblurb></span> + <p>Most of the forms in OpenACS are created using the form builder, see <a class="xref" href="form-builder.html" title="Using Form Builder: building html forms dynamically">the section called “Using Form Builder: building html forms dynamically”</a>. For detailed information on the + API take a look <a class="ulink" href="/api-doc/proc-view?proc=ad_form" target="_top">here</a>.</p> + <p>The following section shows how you can modify your form to allow WYSIWYG functionalities.</p> + <p>Convert your page to use <code class="code">ad_form</code> (some changes but worth it)</p> + <p>Here an examples. From:</p> + <pre class="programlisting"> template::form create my_form template::element create my_form my_form_id -label "The ID" -datatype integer -widget hidden template::element create my_form my_input_field_1 -html { size 30 } -label "Label 1" -datatype text -optional template::element create my_form my_input_field_2 -label "Label 2" -datatype text -help_text "Some Help" -after_html {<a name="#">Anchor</a>} - </pre><p>To:</p><pre class="programlisting"> + </pre> + <p>To:</p> + <pre class="programlisting"> ad_form -name my_form -form { my_form_id:key(acs_object_id_seq) {my_input_field_1:text,optional @@ -20,43 +28,68 @@ {after_html {<a name="#">Anchor</a>}}} } ... - </pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.</p></div><p>Convert your textarea widget to a richtext widget and enable htmlarea.</p><p>The <code class="code">htmlarea_p</code>-flag can be used to prevent - WYSIWYG functionality. Defaults to true if left away.</p><p>From:</p><pre class="programlisting"> + </pre> + <div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3> + <p>You must not give your your form the same name that your page has. Otherwise HTMLArea won't load.</p> + </div> + <p>Convert your textarea widget to a richtext widget and enable htmlarea.</p> + <p>The <code class="code">htmlarea_p</code>-flag can be used to prevent + WYSIWYG functionality. Defaults to true if left away.</p> + <p>From:</p> + <pre class="programlisting"> {my_input_field_2:text - </pre><p>To:</p><pre class="programlisting"> + </pre> + <p>To:</p> + <pre class="programlisting"> {my_input_field_2:richtext(richtext) {htmlarea_p "t"} - </pre><p>The richtext widget presents a list with two elements: text and content type. + </pre> + <p>The richtext widget presents a list with two elements: text and content type. To learn more on existing content types search in Google for "MIME-TYPES" or - take a look at the <code class="code">cr_mime_types</code> table.</p><p>Make sure that both values are passed as a list to your + take a look at the <code class="code">cr_mime_types</code> table.</p> + <p>Make sure that both values are passed as a list to your <code class="code">ad_form</code> or you will have problems - displaying the content or handling the data manipulation correctly.</p><p>Depending on the data model of your package you either support a content format + displaying the content or handling the data manipulation correctly.</p> + <p>Depending on the data model of your package you either support a content format or don't. If you don't you can assume <code class="code">"text/html"</code> or - <code class="code">"text/richtext"</code> or <code class="code">"text/enhanced"</code>.</p><p>The relevant parts in your <code class="code">ad_form</code> definition are the + <code class="code">"text/richtext"</code> or <code class="code">"text/enhanced"</code>.</p> + <p>The relevant parts in your <code class="code">ad_form</code> definition are the switches <code class="code">-new_data</code>, <code class="code">-edit_data</code>, - <code class="code">-on_request</code> and <code class="code">-on_submit</code>.</p><p>To allow your data to display correctly you need to add an <code class="code">-on_request</code> block. - If you have the format stored in the database pass this as well else use <code class="code">"text/html"</code>:</p><pre class="programlisting"> + <code class="code">-on_request</code> and <code class="code">-on_submit</code>.</p> + <p>To allow your data to display correctly you need to add an <code class="code">-on_request</code> block. + If you have the format stored in the database pass this as well else use <code class="code">"text/html"</code>:</p> + <pre class="programlisting"> set my_input_field_2 [template::util::richtext::create $my_input_field_2 "text/html"] - </pre><p>Now make sure that your SQL queries that do the data manipulation retrieve the correct value. + </pre> + <p>Now make sure that your SQL queries that do the data manipulation retrieve the correct value. If you simply use <code class="code">my_input_field_2</code> you will store a list. - Thus you need to add an <code class="code">-on_submit</code> block:</p><pre class="programlisting"> + Thus you need to add an <code class="code">-on_submit</code> block:</p> + <pre class="programlisting"> set my_input_field_2 [ template::util::richtext::get_property contents $my_input_field_2] set format [ template::util::richtext::get_property format $my_input_field_2] #This is optional - </pre><p>Now the correct values for <code class="code">my_input_field_2</code> and + </pre> + <p>Now the correct values for <code class="code">my_input_field_2</code> and <code class="code">format</code> are passed to the <code class="code">-new_data</code> and - <code class="code">-edit_data</code> blocks which don't need to get touched.</p><p>To make HTMLArea optional per package instance define a string parameter + <code class="code">-edit_data</code> blocks which don't need to get touched.</p> + <p>To make HTMLArea optional per package instance define a string parameter <code class="code">UseWysiwygP</code> which defaults <code class="code">0</code> for your - package using the APM.</p><p>In your edit page make the following changes</p><pre class="programlisting"> + package using the APM.</p> + <p>In your edit page make the following changes</p> + <pre class="programlisting"> # Is WYSIWYG enabled? set use_wysiwyg_p [parameter::get -parameter "UseWysiwygP" -default "f"] ... {htmlarea_p $use_wysiwyg_p} - </pre><p>The <code class="code">-on_request</code> switch should set this value for your form.</p><pre class="programlisting"> + </pre> + <p>The <code class="code">-on_request</code> switch should set this value for your form.</p> + <pre class="programlisting"> set htmlarea_p $use_wysiwyg_p - </pre><p>All you need now is a configuration page where the user can change this setting. Create a - <code class="code">configure.tcl</code> file:</p><pre class="programlisting"> + </pre> + <p>All you need now is a configuration page where the user can change this setting. Create a + <code class="code">configure.tcl</code> file:</p> + <pre class="programlisting"> ad_page_contract { This page allows a faq admin to change the UseWysiwygP setting @@ -84,16 +117,22 @@ ns_returnredirect $return_url } } -</pre><p>In the corresponding ADP file write</p><pre class="programlisting"> +</pre> + <p>In the corresponding ADP file write</p> + <pre class="programlisting"> <master> <property name="title">@title@</property> <property name="context">@context@</property> <formtemplate id="categories_mode"></formtemplate> - </pre><p>And finally reference this page from your admin page</p><pre class="programlisting"> + </pre> + <p>And finally reference this page from your admin page</p> + <pre class="programlisting"> #TCL: set return_url [ad_conn url] #ADP: <a href=configure?<%=[export_vars -url {return_url}]%>>Configure</a> - </pre></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-schedule-procs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-parameters.html">Next</a></td></tr><tr><td width="40%" align="left">Scheduled Procedures </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Adding in parameters for your package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </pre> + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="tutorial-schedule-procs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-parameters.html">Next</a></td></tr><tr><td width="40%" align="left">Scheduled Procedures </td><td width="20%" align="center"><a accesskey="u" href="tutorial-advanced.html">Up</a></td><td width="40%" align="right"> Adding in parameters for your package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/tutorial.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/tutorial.html,v diff -u -r1.26 -r1.27 --- openacs-4/packages/acs-core-docs/www/tutorial.html 7 Aug 2017 23:47:53 -0000 1.26 +++ openacs-4/packages/acs-core-docs/www/tutorial.html 8 Nov 2017 09:42:12 -0000 1.27 @@ -1,2 +1,8 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 9. Development Tutorial</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="next" href="tutorial-newpackage.html" title="Creating an Application Package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="tutorial"></a>Chapter 9. Development Tutorial</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-newpackage.html">Creating an Application Package</a></span></dt><dt><span class="sect1"><a href="tutorial-database.html">Setting Up Database Objects</a></span></dt><dt><span class="sect1"><a href="tutorial-pages.html">Creating Web Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-debug.html">Debugging and Automated Testing</a></span></dt></dl></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr><tr><td width="40%" align="left">Part III. For OpenACS Package Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Creating an Application Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 9. Development Tutorial</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="previous" href="acs-package-dev.html" title="Part III. For OpenACS Package Developers"><link rel="next" href="tutorial-newpackage.html" title="Creating an Application Package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><th width="60%" align="center">Part III. For OpenACS Package Developers</th><td width="20%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="tutorial"></a>Chapter 9. Development Tutorial</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="tutorial-newpackage.html">Creating an Application Package</a></span></dt><dt><span class="sect1"><a href="tutorial-database.html">Setting Up Database Objects</a></span></dt><dt><span class="sect1"><a href="tutorial-pages.html">Creating Web Pages</a></span></dt><dt><span class="sect1"><a href="tutorial-debug.html">Debugging and Automated Testing</a></span></dt></dl></div> + + + + + + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="acs-package-dev.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="tutorial-newpackage.html">Next</a></td></tr><tr><td width="40%" align="left">Part III. For OpenACS Package Developers </td><td width="20%" align="center"><a accesskey="u" href="acs-package-dev.html">Up</a></td><td width="40%" align="right"> Creating an Application Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/unix-installation.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/unix-installation.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/unix-installation.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/unix-installation.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -10,11 +10,9 @@ <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="unix-installation" id="unix-installation"></a>Install a Unix-like system and -supporting software</h2></div></div></div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><div class="sect2"> +supporting software</h2></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> <a name="unix-install" id="unix-install"></a>a Unix-like system</h3></div></div></div><p>Most of the documentation in this section is kept as a @@ -38,8 +36,8 @@ must first do <a class="xref" href="install-steps" title="Setting a global shell variable for cut and paste">Setting a global shell variable for cut and paste</a>.</p><p>To install a machine to the specifications of the Reference Platform, do the <a class="link" href="install-redhat" title="Appendix A. Install Red Hat 8/9">walkthrough -of the Red Hat 8.0 Install for OpenACS</a>.</p><div class="cvstag">($‌Id: os.xml,v 1.15.14.2 2017/04/22 17:18:48 -gustafn Exp $)</div> +of the Red Hat 8.0 Install for OpenACS</a>.</p><p><span class="cvstag">($‌Id: os.xml,v 1.16 2017/08/07 23:47:55 +gustafn Exp $)</span></p> </div> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/unix-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/unix-installation.html,v diff -u -r1.34 -r1.35 --- openacs-4/packages/acs-core-docs/www/unix-installation.html 7 Aug 2017 23:47:53 -0000 1.34 +++ openacs-4/packages/acs-core-docs/www/unix-installation.html 8 Nov 2017 09:42:12 -0000 1.35 @@ -1,11 +1,33 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install a Unix-like system and supporting software</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="next" href="oracle.html" title="Install Oracle 8.1.7"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="complete-install.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="unix-installation"></a>Install a Unix-like system and supporting software</h2></div></div></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="unix-install"></a>a Unix-like system</h3></div></div></div><p>Most of the documentation in this section is kept as a +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Install a Unix-like system and supporting software</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="next" href="oracle.html" title="Install Oracle 8.1.7"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="complete-install.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="unix-installation"></a>Install a Unix-like system and supporting software</h2></div></div></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="unix-install"></a>a Unix-like system</h3></div></div></div> + + <p>Most of the documentation in this section is kept as a reference. More up-to-date documentation is in the <a class="ulink" href="http://openacs.org/xowiki/openacs-system-install" target="_top">install sections in the Wiki</a>. - </p><p>You will need a computer running a unix-like system with the following software installed:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>tdom</p></li><li class="listitem"><p>tcl --if you plan to use the OpenACS installation script</p></li><li class="listitem"><p>gmake and the compile and build environment.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">BSD Note</h3><p>BSD users: in most places in these instructions, gmake will work better than make. (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=136910" target="_top">more - information on FreeBSD installation</a>). Also, fetch is a native replacement for wget.</p></div></li></ul></div><p>Note: Instructions for installing tDOM and threaded Tcl are included with the AOLserver4 installation instructions, - if these are not yet installed.</p><p>The following programs may be useful or required for some configurations. They are included in most distributions:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>emacs</p></li><li class="listitem"><p>cvs (and <a class="link" href="install-cvs.html" title="Initialize CVS (OPTIONAL)">initialize</a> it)</p></li><li class="listitem"><p>ImageMagick (used by some packages for server side image manipulation)</p></li><li class="listitem"><p>Aspell (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=130549" target="_top">more information on spell-checking</a>)</p></li><li class="listitem"><p>DocBook and supporting software (and <a class="link" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)">install</a> emacs keybindings for DocBook SGML)</p></li><li class="listitem"><p>daemontools (<a class="link" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install from source</a>)</p></li><li class="listitem"><p>a Mail Transport Agent, such as exim or sendmail (or <a class="link" href="install-qmail.html" title="Install qmail (OPTIONAL)">install qmail from source</a>)</p></li></ul></div><p>In order to cut and paste the example code into your shell, you must first do <a class="xref" href="install-steps.html#cut-and-paste-name-var" title="Setting a global shell variable for cut and paste">Setting a global shell variable for cut and paste</a>.</p><p>To install a machine to the specifications of the Reference Platform, do the - <a class="link" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9">walkthrough of the Red Hat 8.0 Install for OpenACS</a>.</p><div class="cvstag">($Id$)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="complete-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 3. Complete Installation </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install Oracle 8.1.7</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + <p>You will need a computer running a unix-like system with the following software installed:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>tdom</p></li><li class="listitem"><p>tcl --if you plan to use the OpenACS installation script</p></li><li class="listitem"><p>gmake and the compile and build environment.</p> + <div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">BSD Note</h3> + + <p>BSD users: in most places in these instructions, gmake will work better than make. (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=136910" target="_top">more + information on FreeBSD installation</a>). Also, fetch is a native replacement for wget.</p> + </div> + </li></ul></div> + <p>Note: Instructions for installing tDOM and threaded Tcl are included with the AOLserver4 installation instructions, + if these are not yet installed.</p> + <p>The following programs may be useful or required for some configurations. They are included in most distributions:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>emacs</p></li><li class="listitem"><p>cvs (and <a class="link" href="install-cvs.html" title="Initialize CVS (OPTIONAL)">initialize</a> it)</p></li><li class="listitem"><p>ImageMagick (used by some packages for server side image manipulation)</p></li><li class="listitem"><p>Aspell (<a class="ulink" href="http://openacs.org/forums/message-view?message_id=130549" target="_top">more information on spell-checking</a>)</p></li><li class="listitem"><p>DocBook and supporting software (and <a class="link" href="psgml-for-emacs.html" title="Add PSGML commands to emacs init file (OPTIONAL)">install</a> emacs keybindings for DocBook SGML)</p></li><li class="listitem"><p>daemontools (<a class="link" href="install-daemontools.html" title="Install Daemontools (OPTIONAL)">install from source</a>)</p></li><li class="listitem"> + <p>a Mail Transport Agent, such as exim or sendmail (or <a class="link" href="install-qmail.html" title="Install qmail (OPTIONAL)">install qmail from source</a>)</p> + </li></ul></div> + <p>In order to cut and paste the example code into your shell, you must first do <a class="xref" href="install-steps.html#cut-and-paste-name-var" title="Setting a global shell variable for cut and paste">Setting a global shell variable for cut and paste</a>.</p> + + <p>To install a machine to the specifications of the Reference Platform, do the + <a class="link" href="install-redhat.html" title="Appendix A. Install Red Hat 8/9">walkthrough of the Red Hat 8.0 Install for OpenACS</a>.</p> + <p><span class="cvstag">($Id$)</span></p> + </div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="complete-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="oracle.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 3. Complete Installation </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> Install Oracle 8.1.7</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/update-repository.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-repository.html,v diff -u -r1.19 -r1.20 --- openacs-4/packages/acs-core-docs/www/update-repository.html 7 Aug 2017 23:47:53 -0000 1.19 +++ openacs-4/packages/acs-core-docs/www/update-repository.html 8 Nov 2017 09:42:12 -0000 1.20 @@ -1,20 +1,39 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to Update the OpenACS.org repository</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="releasing-openacs-core.html" title="OpenACS Core and .LRN"><link rel="next" href="releasing-package.html" title="How to package and release an OpenACS Package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="releasing-openacs-core.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="releasing-package.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="update-repository"></a>How to Update the OpenACS.org repository</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to Update the OpenACS.org repository</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="releasing-openacs-core.html" title="OpenACS Core and .LRN"><link rel="next" href="releasing-package.html" title="How to package and release an OpenACS Package"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="releasing-openacs-core.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="releasing-package.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="update-repository"></a>How to Update the OpenACS.org repository</h2></div></div></div> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> Setup a local OpenACS server running 5.0 or better. - </p></li><li class="listitem"><p> - Edit <code class="computeroutput">packages/acs-admin/www/apm/build-repository.tcl</code> and adjust the Configuration Settings. </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> + Edit <code class="computeroutput">packages/acs-admin/www/apm/build-repository.tcl</code> and adjust the Configuration Settings. </p> + </li><li class="listitem"> + <p> Request /acs-admin/apm/build-repository on your new server. - </p></li><li class="listitem"><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p> + </p> + </li><li class="listitem"> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p> The page will find all branches in the cvs repository labeled oacs-x-y, and build a repository channel for each of those branches where x>=5 (so not for 4.6 and earlier). It will also build a channel for HEAD, which will be named after what you set in 'head_channel' above. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> For each channel, it'll do an anonymous checkout of packges and contrib/packages, then build .apm files for each package in the checkout. - </p></li><li class="listitem"><p> + </p> + </li><li class="listitem"> + <p> The files will be stored on the server's hard drive in the directory specified by the 'repository_dir' variable in the page script, by default "$::acs::rootdir/www/repository/". - </p></li></ol></div></li><li class="listitem"><p> + </p> + </li></ol></div> + </li><li class="listitem"> + <p> If you're on openacs.org, everything should now be fine. Otherwise, you need to move the entire directory tree to openacs.org:/web/openacs/www/repository, replacing what was already there. - </p><p>This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script. Since the page circumvents security checks for ease of use, the entire site is limited to local requests. The script is called daily with a cron job.</p><pre class="programlisting">#!/bin/sh + </p> + <p>This is automated on OpenACS.org by having a dedicated site just for building the repository, invoked with this shell script. Since the page circumvents security checks for ease of use, the entire site is limited to local requests. The script is called daily with a cron job.</p> + <pre class="programlisting">#!/bin/sh #set -x STATUS=`wget --output-document - http://127.0.0.1:8002/build-repository.tcl | grep DONE | wc -l` @@ -24,4 +43,7 @@ rm -rf /web/openacs.org/www/repository.old mv /web/openacs.org/www/repository /web/openacs.org/www/repository.old cp -r /web/repository/www/repository /web/openacs.org/www/repository -fi</pre></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="releasing-openacs-core.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-package.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Core and .LRN </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> How to package and release an OpenACS Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +fi</pre> + + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="releasing-openacs-core.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="releasing-package.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Core and .LRN </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> How to package and release an OpenACS Package</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/update-translations.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-translations.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/update-translations.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/update-translations.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -24,7 +24,7 @@ 'windows-1256', 't', 'f'); </pre><p>Put this command into the following four files. For the upgrade files, the correct file name will depend on the exact version.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> -<li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/postgresql/ad-locales.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/postgresql/upgrade/upgrade-<span class="replaceable"><span class="replaceable">current-version</span></span>.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/oracle/ad-locales.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/oracle/upgrade/upgrade-<span class="replaceable"><span class="replaceable">current-version</span></span>.sql</code></p></li> +<li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/postgresql/ad-locales.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/postgresql/upgrade/upgrade-<em class="replaceable"><code>current-version</code></em>.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/oracle/ad-locales.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/oracle/upgrade/upgrade-<em class="replaceable"><code>current-version</code></em>.sql</code></p></li> </ul></div> </li><li class="listitem"><p>Make a backup of the production database. Restore it as a new database. For example, if upgrading from OpenACS 5.1.1, and the Index: openacs-4/packages/acs-core-docs/www/update-translations.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/update-translations.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/update-translations.html 7 Aug 2017 23:47:53 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/update-translations.html 8 Nov 2017 09:42:12 -0000 1.19 @@ -1,19 +1,57 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to Update the translations</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="releasing-package.html" title="How to package and release an OpenACS Package"><link rel="next" href="ix01.html" title="Index"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="releasing-package.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="ix01.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="update-translations"></a>How to Update the translations</h2></div></div></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Identify any new locales that have been created. +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>How to Update the translations</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="releasing-openacs.html" title="Chapter 16. Releasing OpenACS"><link rel="previous" href="releasing-package.html" title="How to package and release an OpenACS Package"><link rel="next" href="ix01.html" title="Index"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="releasing-package.html">Prev</a> </td><th width="60%" align="center">Chapter 16. Releasing OpenACS</th><td width="20%" align="right"> <a accesskey="n" href="ix01.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="update-translations"></a>How to Update the translations</h2></div></div></div> + + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Identify any new locales that have been created. For each new locale, check the parameters, especially that the locale is in the format <span class="emphasis"><em>[two-letter code for language, lower-case]_[TWO-LETTER CODE FOR COUNTRY, UPPER-CASE]</em></span>, and create a sql command. A - example sql command for creating a locale is:</p><pre class="programlisting">insert into ad_locales + example sql command for creating a locale is:</p> + <pre class="programlisting">insert into ad_locales (locale, label, language, country, nls_language, nls_territory, nls_charset, mime_charset, default_p, enabled_p) values ('fa_IR', 'Farsi (IR)', 'fa', 'IR', 'FARSI', 'IRAN', 'AL24UTFFSS', - 'windows-1256', 't', 'f');</pre><p>Put this command into the following four files. For the + 'windows-1256', 't', 'f');</pre> + <p>Put this command into the following four files. For the upgrade files, the correct file name will depend on the - exact version.</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/postgresql/ad-locales.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/postgresql/upgrade/upgrade-<span class="replaceable"><span class="replaceable">current-version</span></span>.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/oracle/ad-locales.sql</code></p></li><li class="listitem"><p><code class="computeroutput">/packages/acs-lang/sql/oracle/upgrade/upgrade-<span class="replaceable"><span class="replaceable">current-version</span></span>.sql</code></p></li></ul></div></li><li class="listitem"><p>Make a backup of the production database. Restore it as a new database. For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.</p></li><li class="listitem"><p>Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1. Copy over any local settings - usually, <code class="computeroutput">/etc/config.tcl</code> and <code class="computeroutput">/etc/daemontools/run</code> and modify appropriately. Also, copy over several translation-server-only files: + exact version.</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p><code class="computeroutput">/packages/acs-lang/sql/postgresql/ad-locales.sql</code></p> + </li><li class="listitem"> + <p><code class="computeroutput">/packages/acs-lang/sql/postgresql/upgrade/upgrade-<em class="replaceable"><code>current-version</code></em>.sql</code></p> + </li><li class="listitem"> + <p><code class="computeroutput">/packages/acs-lang/sql/oracle/ad-locales.sql</code></p> + </li><li class="listitem"> + <p><code class="computeroutput">/packages/acs-lang/sql/oracle/upgrade/upgrade-<em class="replaceable"><code>current-version</code></em>.sql</code></p> + </li></ul></div> + </li><li class="listitem"> + <p>Make a backup of the production database. Restore it as a new database. For example, if upgrading from OpenACS 5.1.1, and the site name/database name is translate-511, create translate-512b1.</p> + </li><li class="listitem"> + <p>Check out the latest code on the release branch (e.g., oacs-5-1) as a new site, using the new site name (e.g., /var/lib/aolserver/translate-512b1. Copy over any local settings - usually, <code class="computeroutput">/etc/config.tcl</code> and <code class="computeroutput">/etc/daemontools/run</code> and modify appropriately. Also, copy over several translation-server-only files: </p><pre class="programlisting">...TBD </pre><p> - </p></li><li class="listitem"><p>Shut down the production site and put up a notice (no procedure on how to do this yet.)</p></li><li class="listitem"><p>Start the new site, and upgrade it.</p></li><li class="listitem"><p>Go to <a class="ulink" href="/acs-lang/admin" target="_top">ACS Lang admin page</a> and click "Import All Messages"</p></li><li class="listitem"><p>Resolve conflicts, if any, on the provided page. - </p></li><li class="listitem"><p>Back on the admin page, click the export link. If there are conflicts, the messages will be exported anyway and any errors will be shown in the web interface.</p></li><li class="listitem"><p>Commit the message catalogs to cvs.</p></li><li class="listitem"><p>From the packages dir, run the acs-lang/bin/check-catalog.sh script. (This checks for keys no longer in use and some other things. Until it is rolled into the UI, do it manually and check the results and take whatever steps you can intuit you should do.) - </p></li><li class="listitem"><p>CVS commit the catalog files. Done</p></li><li class="listitem"><p>If everything went well, reconfigure the new site to take over the role of the old site (<code class="computeroutput">/etc/config.tcl</code> and <code class="computeroutput">/etc/daemontools/run</code>). Otherwise, bring the old site back up while investigating problems, and then repeat. - </p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="releasing-package.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ix01.html">Next</a></td></tr><tr><td width="40%" align="left">How to package and release an OpenACS Package </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> Index</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li><li class="listitem"> + <p>Shut down the production site and put up a notice (no procedure on how to do this yet.)</p> + </li><li class="listitem"> + <p>Start the new site, and upgrade it.</p> + </li><li class="listitem"> + <p>Go to <a class="ulink" href="/acs-lang/admin" target="_top">ACS Lang admin page</a> and click "Import All Messages"</p> + </li><li class="listitem"> + <p>Resolve conflicts, if any, on the provided page. + </p> + </li><li class="listitem"> + <p>Back on the admin page, click the export link. If there are conflicts, the messages will be exported anyway and any errors will be shown in the web interface.</p> + </li><li class="listitem"> + <p>Commit the message catalogs to cvs.</p> + </li><li class="listitem"> + <p>From the packages dir, run the acs-lang/bin/check-catalog.sh script. (This checks for keys no longer in use and some other things. Until it is rolled into the UI, do it manually and check the results and take whatever steps you can intuit you should do.) + </p> + </li><li class="listitem"> + <p>CVS commit the catalog files. Done</p> + </li><li class="listitem"> + <p>If everything went well, reconfigure the new site to take over the role of the old site (<code class="computeroutput">/etc/config.tcl</code> and <code class="computeroutput">/etc/daemontools/run</code>). Otherwise, bring the old site back up while investigating problems, and then repeat. + </p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="releasing-package.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="ix01.html">Next</a></td></tr><tr><td width="40%" align="left">How to package and release an OpenACS Package </td><td width="20%" align="center"><a accesskey="u" href="releasing-openacs.html">Up</a></td><td width="40%" align="right"> Index</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -9,7 +9,7 @@ rightLink="upgrade-4.6.3-to-5" rightLabel="Next"> <div class="sect1"> <div class="titlepage"><div><div><h2 class="title" style="clear: both"> -<a name="upgrade-4.5-to-4.6" id="upgrade-4.5-to-4.6"></a>Upgrading 4.5 or higher to 4.6.3</h2></div></div></div><a class="indexterm" name="idp140592104583224" id="idp140592104583224"></a><p>The required platform for OpenACS 4.6 is the same as 4.5, with +<a name="upgrade-4.5-to-4.6" id="upgrade-4.5-to-4.6"></a>Upgrading 4.5 or higher to 4.6.3</h2></div></div></div><a class="indexterm" name="idp140623160154424" id="idp140623160154424"></a><p>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.</p><p>If upgrading from 4.4, you need to manually run @@ -21,17 +21,16 @@ </p></li> </ul></div><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p> -<strong>Make a Backup. </strong>Back up the database -and file system (see <a class="xref" href="snapshot-backup" title="Manual backup and recovery">the section called -“Manual backup and +<strong>Make a Backup. </strong> Back up the +database and file system (see <a class="xref" href="snapshot-backup" title="Manual backup and recovery">the +section called “Manual backup and recovery”</a>).</p></li><li class="listitem"><p> -<strong>OPTIONAL: Upgrade -OpenFTS. </strong><a class="xref" href="upgrade-supporting" title="Upgrading OpenFTS from 0.2 to 0.3.2">the section called +<strong>OPTIONAL: Upgrade OpenFTS. </strong><a class="xref" href="upgrade-supporting" title="Upgrading OpenFTS from 0.2 to 0.3.2">the section called “Upgrading OpenFTS from 0.2 to 0.3.2”</a> </p></li><li class="listitem"> <p>Stop the server</p><pre class="screen"> -[root root]# <strong class="userinput"><code>svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre> </li><li class="listitem"><p> @@ -41,32 +40,31 @@ </p></li><li class="listitem"> <p><span class="strong"><strong>Start the server</strong></span></p><pre class="screen"> -[root root]# <strong class="userinput"><code>svc -u /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>svc -u /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre> </li><li class="listitem"> <p> -<a name="upgrade-with-apm" id="upgrade-with-apm"></a><strong>Use -APM to upgrade the database. </strong> +<a name="upgrade-with-apm" id="upgrade-with-apm"></a><strong>Use APM to upgrade the database. </strong> </p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p>Browse to the package manager, <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/acs-admin/apm</code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install -packages.</span></span></code> +<li class="listitem"><p>Browse to the package manager, <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/acs-admin/apm</code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel">Install packages.</span></code> </p></li><li class="listitem"><p>Select the packages you want to install. This should be everything that says <code class="computeroutput">upgrade</code>, plus any new packages you want. It's safest to upgrade the kernel by itself, and then come back and upgrade the rest of the -desired packages in a second pass.</p></li><li class="listitem"><p>On the next screen, click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Install Packages</span></span></code> +desired packages in a second pass.</p></li><li class="listitem"><p>On the next screen, click <code class="computeroutput"><span class="guibutton">Install +Packages</span></code> </p></li><li class="listitem"> <p>When prompted, restart the server:</p><pre class="screen"> -[root root]# <strong class="userinput"><code>restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> </pre> -</li><li class="listitem"><p>Wait a minute, then browse to the package manager, <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/acs-admin/apm</code>.</p></li><li class="listitem"><p>Check that the kernel upgrade worked by clicking <code class="computeroutput"><span class="guilabel"><span class="guilabel">All</span></span></code> and making sure that -<code class="computeroutput">acs-kernel</code> version is -5.9.0.</p></li> +</li><li class="listitem"><p>Wait a minute, then browse to the package manager, <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/acs-admin/apm</code>.</p></li><li class="listitem"><p>Check that the kernel upgrade worked by clicking <code class="computeroutput"><span class="guilabel">All</span></code> and +making sure that <code class="computeroutput">acs-kernel</code> +version is 5.9.0.</p></li> </ol></div> </li><li class="listitem"><p> -<strong>Rollback. </strong>If anything goes wrong, +<strong>Rollback. </strong> If anything goes wrong, <a class="link" href="snapshot-backup" title="Recovery">roll back</a> to the backup snapshot.</p></li> </ol></div> </div> 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 -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html 7 Aug 2017 23:47:53 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.5-to-4.6.html 8 Nov 2017 09:42:12 -0000 1.29 @@ -1,12 +1,69 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading 4.5 or higher to 4.6.3</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-overview.html" title="Overview"><link rel="next" href="upgrade-4.6.3-to-5.html" title="Upgrading OpenACS 4.6.3 to 5.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-4.6.3-to-5.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-4.5-to-4.6"></a>Upgrading 4.5 or higher to 4.6.3</h2></div></div></div><a class="indexterm" name="idp140592104583224"></a><p>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. </p><p>If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug_number=632" target="_top">Bug #632</a></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>A computer with OpenACS 4.5.</p></li><li class="listitem" style="list-style-type: circle"><p><a class="ulink" href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 4.6 tarball</a> or CVS checkout/export.</p></li><li class="listitem" style="list-style-type: circle"><p>Required for Full Text Search on PostgreSQL: <a class="ulink" href="http://openfts.sourceforge.net" target="_top">OpenFTS 0.3.2</a></p></li></ul></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Make a Backup. </b>Back up the database and file system (see <a class="xref" href="snapshot-backup.html" title="Manual backup and recovery">the section called “Manual backup and recovery”</a>).</p></li><li class="listitem"><p><b>OPTIONAL: Upgrade OpenFTS. </b><a class="xref" href="upgrade-supporting.html#upgrade-openfts-0.2-to-0.3.2" title="Upgrading OpenFTS from 0.2 to 0.3.2">the section called “Upgrading OpenFTS from 0.2 to 0.3.2”</a></p></li><li class="listitem"><p> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading 4.5 or higher to 4.6.3</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-overview.html" title="Overview"><link rel="next" href="upgrade-4.6.3-to-5.html" title="Upgrading OpenACS 4.6.3 to 5.0"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-overview.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-4.6.3-to-5.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-4.5-to-4.6"></a>Upgrading 4.5 or higher to 4.6.3</h2></div></div></div> + + <a class="indexterm" name="idp140623160154424"></a> + <p>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. </p> + <p>If upgrading from 4.4, you need to manually run acs-kernel/sql/postgres/upgrade-4.4-4.5.sql. See <a class="ulink" href="http://openacs.org/bugtracker/openacs/bug?bug_number=632" target="_top">Bug #632</a></p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem" style="list-style-type: circle"><p>A computer with OpenACS 4.5.</p> + </li><li class="listitem" style="list-style-type: circle"><p><a class="ulink" href="http://openacs.org/projects/openacs/download/" target="_top">OpenACS 4.6 tarball</a> or CVS checkout/export.</p> + </li><li class="listitem" style="list-style-type: circle"><p>Required for Full Text Search on PostgreSQL: <a class="ulink" href="http://openfts.sourceforge.net" target="_top">OpenFTS 0.3.2</a></p> + </li></ul></div> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Make a Backup. </b> + Back up the database and file system (see <a class="xref" href="snapshot-backup.html" title="Manual backup and recovery">the section called “Manual backup and recovery”</a>). + </p> + </li><li class="listitem"> + <p> + <b>OPTIONAL: Upgrade OpenFTS. </b> + <a class="xref" href="upgrade-supporting.html#upgrade-openfts-0.2-to-0.3.2" title="Upgrading OpenFTS from 0.2 to 0.3.2">the section called “Upgrading OpenFTS from 0.2 to 0.3.2”</a> + </p> + </li><li class="listitem"> + <p> Stop the server - </p><pre class="screen">[root root]# <strong class="userinput"><code>svc -d /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li><li class="listitem"><p><b>Upgrade the file system. </b><a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a></p></li><li class="listitem"><p> + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>svc -d /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li><li class="listitem"> + <p> + <b>Upgrade the file system. </b> + <a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a> + </p> + </li><li class="listitem"> + <p> <span class="strong"><strong>Start the server</strong></span> - </p><pre class="screen">[root root]# <strong class="userinput"><code>svc -u /service/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li><li class="listitem"><p><a name="upgrade-with-apm"></a><b>Use APM to upgrade the database. </b></p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Browse to the package manager, <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/acs-admin/apm</code>.</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Install packages.</span></span></code></p></li><li class="listitem"><p>Select the packages you want to install. This should + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>svc -u /service/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li><li class="listitem"> + <p><a name="upgrade-with-apm"></a> + <b>Use APM to upgrade the database. </b> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Browse to the package manager, <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/acs-admin/apm</code>.</p> + </li><li class="listitem"> + <p>Click <code class="computeroutput"><span class="guilabel">Install packages.</span></code></p> + </li><li class="listitem"> + <p>Select the packages you want to install. This should be everything that says <code class="computeroutput">upgrade</code>, plus any new packages you want. It's safest to upgrade the kernel by itself, and then come back and upgrade the rest of the - desired packages in a second pass.</p></li><li class="listitem"><p>On the next screen, click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Install Packages</span></span></code></p></li><li class="listitem"><p>When prompted, restart the server:</p><pre class="screen">[root root]# <strong class="userinput"><code>restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li><li class="listitem"><p>Wait a minute, then browse to the package manager, <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/acs-admin/apm</code>.</p></li><li class="listitem"><p>Check that the kernel upgrade worked by clicking <code class="computeroutput"><span class="guilabel"><span class="guilabel">All</span></span></code> and making sure that <code class="computeroutput">acs-kernel</code> version is 5.9.0.</p></li></ol></div></li><li class="listitem"><p><b>Rollback. </b>If anything goes wrong, <a class="link" href="snapshot-backup.html#recovery" title="Recovery">roll back</a> to the backup snapshot.</p></li></ol></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-4.6.3-to-5.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading OpenACS 4.6.3 to 5.0</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + desired packages in a second pass.</p> + </li><li class="listitem"> + <p>On the next screen, click <code class="computeroutput"><span class="guibutton">Install Packages</span></code></p> + </li><li class="listitem"> + <p>When prompted, restart the server:</p> + <pre class="screen">[root root]# <strong class="userinput"><code>restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li><li class="listitem"> + <p>Wait a minute, then browse to the package manager, <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/acs-admin/apm</code>.</p> + </li><li class="listitem"> + <p>Check that the kernel upgrade worked by clicking <code class="computeroutput"><span class="guilabel">All</span></code> and making sure that <code class="computeroutput">acs-kernel</code> version is 5.9.0.</p> + </li></ol></div> + </li><li class="listitem"> + <p> + <b>Rollback. </b> + If anything goes wrong, <a class="link" href="snapshot-backup.html#recovery" title="Recovery">roll back</a> to the backup snapshot. + </p> + </li></ol></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-overview.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-4.6.3-to-5.html">Next</a></td></tr><tr><td width="40%" align="left">Overview </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading OpenACS 4.6.3 to 5.0</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -11,12 +11,13 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="upgrade-4.6.3-to-5" id="upgrade-4.6.3-to-5"></a>Upgrading OpenACS 4.6.3 to 5.0</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p> -<strong>Oracle. </strong>This forum posting +<strong>Oracle. </strong> This forum posting documents <a class="ulink" href="http://openacs.org/forums/message-view?message_id=201394" target="_top">how to upgrade an Oracle installation from OpenACS 4.6.3 to 5</a> .</p></li><li class="listitem"> <p> -<strong>PostGreSQL. </strong>You must use PostGreSQL -7.3.x or newer to upgrade OpenACS beyond 4.6.3. See <a class="link" href="upgrade-supporting" title="Upgrading from PostGreSQL 7.2 to 7.3">Upgrade PostGreSQL to +<strong>PostGreSQL. </strong> You must use +PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See +<a class="link" href="upgrade-supporting" title="Upgrading from PostGreSQL 7.2 to 7.3">Upgrade PostGreSQL to 7.3</a>; <a class="xref" href="individual-programs" title="Table 2.2. Version Compatibility Matrix">Table 2.2, “Version Compatibility Matrix”</a> @@ -32,47 +33,47 @@ the rest: <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6" target="_top">/contrib/misc/upgrade_4.6_to_5.0.sh on HEAD</a>). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-kernel/sql/postgresql/upgrade</code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-kernel/sql/postgresql/upgrade</code></strong> </pre><p>Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as <code class="computeroutput"><strong class="userinput"><code>psql --f upgrade-4.6.3-4.6.4.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +-f upgrade-4.6.3-4.6.4.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong></code>. Run the scripts in this order (order is tentative, not verified):</p><pre class="programlisting"> -psql -f upgrade-4.6.3-4.6.4.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.6.4-4.6.5.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.6.5-4.6.6.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.7d-4.7.2d.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.7.2d-5.0d.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d-5.0d2.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d2-5.0d3.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d6-5.0d7.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d7-5.0d9.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d11-5.0d12.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0a4-5.0.0a5.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0b1-5.0.0b2.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0b2-5.0.0b3.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0b3-5.0.0b4.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +psql -f upgrade-4.6.3-4.6.4.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.6.4-4.6.5.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.6.5-4.6.6.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.7d-4.7.2d.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.7.2d-5.0d.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d-5.0d2.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d2-5.0d3.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d6-5.0d7.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d7-5.0d9.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d11-5.0d12.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0a4-5.0.0a5.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0b1-5.0.0b2.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0b2-5.0.0b3.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0b3-5.0.0b4.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </pre> </li><li class="listitem"> <p>Upgrade ACS Service Contracts manually:</p><pre class="screen"> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-service-contracts/sql/postgresql/upgrade</code></strong> -psql -f upgrade-4.7d2-4.7d3.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-service-contracts/sql/postgresql/upgrade</code></strong> +psql -f upgrade-4.7d2-4.7d3.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </pre> </li><li class="listitem"> -<p>Load acs-authentication data model.</p><pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<p>Load acs-authentication data model.</p><pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong></pre> </li><li class="listitem"> -<p>Load acs-lang data model.</p><pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-lang/sql/postgresql/acs-lang-create.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<p>Load acs-lang data model.</p><pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-lang/sql/postgresql/acs-lang-create.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong></pre> </li><li class="listitem"> <p>(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and -internationalization: create <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/tcl/zzz-postload.tcl +internationalization: create <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/tcl/zzz-postload.tcl containing:</p><pre class="programlisting"> if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang $::acs::rootdir/packages/acs-lang/acs-lang.info Index: openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html,v diff -u -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html 7 Aug 2017 23:47:53 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/upgrade-4.6.3-to-5.html 8 Nov 2017 09:42:12 -0000 1.19 @@ -1,28 +1,63 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading OpenACS 4.6.3 to 5.0</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-4.5-to-4.6.html" title="Upgrading 4.5 or higher to 4.6.3"><link rel="next" href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-4.5-to-4.6.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-5-0-dot.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-4.6.3-to-5"></a>Upgrading OpenACS 4.6.3 to 5.0</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Oracle. </b>This forum posting documents +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading OpenACS 4.6.3 to 5.0</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-4.5-to-4.6.html" title="Upgrading 4.5 or higher to 4.6.3"><link rel="next" href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-4.5-to-4.6.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-5-0-dot.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-4.6.3-to-5"></a>Upgrading OpenACS 4.6.3 to 5.0</h2></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Oracle. </b> + This forum posting documents <a class="ulink" href="http://openacs.org/forums/message-view?message_id=201394" target="_top"> how to upgrade an Oracle installation from OpenACS 4.6.3 to 5 </a>. - </p></li><li class="listitem"><p><b>PostGreSQL. </b>You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See <a class="link" href="upgrade-supporting.html#upgrade-postgres-7.2-to-7.3" title="Upgrading from PostGreSQL 7.2 to 7.3">Upgrade PostGreSQL to 7.3</a>; <a class="xref" href="individual-programs.html#compatibility-matrix" title="Table 2.2. Version Compatibility Matrix">Table 2.2, “Version Compatibility Matrix”</a> - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><a class="link" href="snapshot-backup.html" title="Manual backup and recovery">Back up the database and file system.</a></p></li><li class="listitem"><p><b>Upgrade the file system for packages/acs-kernel. </b><a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a></p></li><li class="listitem"><p>Upgrade the kernel manually. (There is a script to do most of the rest: <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6" target="_top">/contrib/misc/upgrade_4.6_to_5.0.sh on HEAD</a>). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-kernel/sql/postgresql/upgrade</code></strong></pre><p> - Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as <code class="computeroutput"><strong class="userinput"><code>psql -f upgrade-4.6.3-4.6.4.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></code>. Run the scripts in this order (order is tentative, not verified): - </p><pre class="programlisting">psql -f upgrade-4.6.3-4.6.4.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.6.4-4.6.5.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.6.5-4.6.6.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.7d-4.7.2d.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-4.7.2d-5.0d.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d-5.0d2.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d2-5.0d3.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d6-5.0d7.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d7-5.0d9.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0d11-5.0d12.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0a4-5.0.0a5.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0b1-5.0.0b2.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0b2-5.0.0b3.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql -f upgrade-5.0.0b3-5.0.0b4.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></pre></li><li class="listitem"><p>Upgrade ACS Service Contracts manually:</p><pre class="screen">[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-service-contracts/sql/postgresql/upgrade</code></strong> -psql -f upgrade-4.7d2-4.7d3.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</pre></li><li class="listitem"><p>Load acs-authentication data model.</p><pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li><li class="listitem"><p>Load acs-lang data model.</p><pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/acs-lang/sql/postgresql/acs-lang-create.sql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong></pre></li><li class="listitem"><p>(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/tcl/zzz-postload.tcl containing:</p><pre class="programlisting">if {![apm_package_installed_p acs-lang]} { + + </p> + </li><li class="listitem"> + <p> + <b>PostGreSQL. </b> + You must use PostGreSQL 7.3.x or newer to upgrade OpenACS beyond 4.6.3. See <a class="link" href="upgrade-supporting.html#upgrade-postgres-7.2-to-7.3" title="Upgrading from PostGreSQL 7.2 to 7.3">Upgrade PostGreSQL to 7.3</a>; <a class="xref" href="individual-programs.html#compatibility-matrix" title="Table 2.2. Version Compatibility Matrix">Table 2.2, “Version Compatibility Matrix”</a> + + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p><a class="link" href="snapshot-backup.html" title="Manual backup and recovery">Back up the database and file system.</a></p> + </li><li class="listitem"> + <p> + <b>Upgrade the file system for packages/acs-kernel. </b> + <a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a> + </p> + </li><li class="listitem"> + <p>Upgrade the kernel manually. (There is a script to do most of the rest: <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6" target="_top">/contrib/misc/upgrade_4.6_to_5.0.sh on HEAD</a>). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.)</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-kernel/sql/postgresql/upgrade</code></strong></pre> + <p> + Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as <code class="computeroutput"><strong class="userinput"><code>psql -f upgrade-4.6.3-4.6.4.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></code>. Run the scripts in this order (order is tentative, not verified): + </p> + <pre class="programlisting">psql -f upgrade-4.6.3-4.6.4.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.6.4-4.6.5.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.6.5-4.6.6.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.7d-4.7.2d.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-4.7.2d-5.0d.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d-5.0d2.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d2-5.0d3.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d6-5.0d7.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d7-5.0d9.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0d11-5.0d12.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0a4-5.0.0a5.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0b1-5.0.0b2.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0b2-5.0.0b3.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql -f upgrade-5.0.0b3-5.0.0b4.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></pre> + </li><li class="listitem"> + <p>Upgrade ACS Service Contracts manually:</p> + <pre class="screen">[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/ <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-service-contracts/sql/postgresql/upgrade</code></strong> +psql -f upgrade-4.7d2-4.7d3.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</pre> + </li><li class="listitem"> + <p>Load acs-authentication data model.</p> + <pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li><li class="listitem"> + <p>Load acs-lang data model.</p> + <pre class="screen"><strong class="userinput"><code>psql -f /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/acs-lang/sql/postgresql/acs-lang-create.sql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong></pre> + </li><li class="listitem"> + <p>(This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/tcl/zzz-postload.tcl containing:</p> + <pre class="programlisting">if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang $::acs::rootdir/packages/acs-lang/acs-lang.info lang::catalog::import -locales [list "en_US"] } @@ -37,13 +72,23 @@ acs-kernel 0 number \ security 1 1 parameter::set_value -package_id [ad_acs_kernel_id] -parameter UsePasswordWidgetForUsername -value 0 -}</pre></li><li class="listitem"><p>If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database. - </p></li><li class="listitem"><p>Upgrade other packages <a class="link" href="upgrade-4.5-to-4.6.html#upgrade-with-apm" title="Use APM to upgrade the database">via the APM</a></p></li></ol></div><p> - See also these forum posts: <a class="ulink" href="http://openacs.org/forums/message-view?message_id=143497" target="_top">Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results</a>, <a class="ulink" href="http://openacs.org/forums/message-view?message_id=152200" target="_top">OpenACS 5.0 Upgrade Experiences</a>.</p><p> +}</pre> + </li><li class="listitem"> + <p>If you can login, visit /acs-admin/apm and upgrade acs-kernel and acs-service-contract and uncheck the data model scripts. Restart. If everything is still working, make another backup of the database. + </p> + </li><li class="listitem"> + <p>Upgrade other packages <a class="link" href="upgrade-4.5-to-4.6.html#upgrade-with-apm" title="Use APM to upgrade the database">via the APM</a></p> + </li></ol></div> + <p> + See also these forum posts: <a class="ulink" href="http://openacs.org/forums/message-view?message_id=143497" target="_top">Forum OpenACS Development: 4.6.3 upgrade to 5-HEAD: final results</a>, <a class="ulink" href="http://openacs.org/forums/message-view?message_id=152200" target="_top">OpenACS 5.0 Upgrade Experiences</a>.</p> + + <p> There are a few things you might want to do once you've upgraded. First, the acs-kernel parameters need to be set to allow HREF and IMG tags, if you want users who can edit HTML to be able to insert HREF and IMG tags. Also, you might need to set the default language for your site. See the above link on OpenACS 5.0 Upgrade Experiences for details. - </p></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-4.5-to-4.6.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-5-0-dot.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading 4.5 or higher to 4.6.3 </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading an OpenACS 5.0.0 or greater installation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li></ul></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-4.5-to-4.6.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-5-0-dot.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading 4.5 or higher to 4.6.3 </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading an OpenACS 5.0.0 or greater installation</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -13,9 +13,9 @@ installation</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> <p> -<strong>Upgrading a stock site. </strong>If you have -no custom code, and your site is not in a CVS repository, upgrade -with these steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"> +<strong>Upgrading a stock site. </strong> If you +have no custom code, and your site is not in a CVS repository, +upgrade with these steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Go to <a class="ulink" href="/acs-admin/install" target="_top">/acs-admin/install/</a> and click "Upgrade Your System" in "Install from OpenACS Repository"</p></li><li class="listitem"><p>Select all of the packages you want to upgrade and proceed</p></li><li class="listitem"><p>After upgrade is complete, restart the server as indicated.</p></li><li class="listitem"><p>If you are using locales other than en_US, go to acs-lang/admin and "Import all Messages" to load the new translated @@ -24,7 +24,7 @@ </ol></div> </li><li class="listitem"> <p> -<strong>Upgrading a Custom or CVS site. </strong>If +<strong>Upgrading a Custom or CVS site. </strong> If you have custom code, and your site is in a CVS repository, upgrade with these steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p> 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 -r1.18 -r1.19 --- openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html 7 Aug 2017 23:47:53 -0000 1.18 +++ openacs-4/packages/acs-core-docs/www/upgrade-5-0-dot.html 8 Nov 2017 09:42:12 -0000 1.19 @@ -1,2 +1,38 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading an OpenACS 5.0.0 or greater installation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-4.6.3-to-5.html" title="Upgrading OpenACS 4.6.3 to 5.0"><link rel="next" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-4.6.3-to-5.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-openacs-files.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-5-0-dot"></a>Upgrading an OpenACS 5.0.0 or greater installation</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Upgrading a stock site. </b>If you have no custom code, and your site is not in a CVS repository, upgrade with these steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Go to <a class="ulink" href="/acs-admin/install" target="_top">/acs-admin/install/</a> and click "Upgrade Your System" in "Install from OpenACS Repository"</p></li><li class="listitem"><p>Select all of the packages you want to upgrade and proceed</p></li><li class="listitem"><p>After upgrade is complete, restart the server as indicated.</p></li><li class="listitem"><p>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.</p></li></ol></div></li><li class="listitem"><p><b>Upgrading a Custom or CVS site. </b>If you have custom code, and your site is in a CVS repository, upgrade with these steps:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p><b>Upgrade the file system for all packages in use. </b><a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a></p></li><li class="listitem"><p>Go to <a class="ulink" href="/acs-admin/install" target="_top">/acs-admin/install/</a> and click "Upgrade Your System" in "Install from local file system"</p></li><li class="listitem"><p>Select all of the packages you want to upgrade and proceed</p></li><li class="listitem"><p>After upgrade is complete, restart the server as indicated.</p></li><li class="listitem"><p>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.</p></li></ol></div></li></ul></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-4.6.3-to-5.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-openacs-files.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading OpenACS 4.6.3 to 5.0 </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading the OpenACS files</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading an OpenACS 5.0.0 or greater installation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-4.6.3-to-5.html" title="Upgrading OpenACS 4.6.3 to 5.0"><link rel="next" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-4.6.3-to-5.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-openacs-files.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-5-0-dot"></a>Upgrading an OpenACS 5.0.0 or greater installation</h2></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Upgrading a stock site. </b> + If you have no custom code, and your site is not in a CVS repository, upgrade with these steps: + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Go to <a class="ulink" href="/acs-admin/install" target="_top">/acs-admin/install/</a> and click "Upgrade Your System" in "Install from OpenACS Repository"</p> + </li><li class="listitem"> + <p>Select all of the packages you want to upgrade and proceed</p> + </li><li class="listitem"> + <p>After upgrade is complete, restart the server as indicated.</p> + </li><li class="listitem"> + <p>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.</p> + </li></ol></div> + </li><li class="listitem"> + <p> + <b>Upgrading a Custom or CVS site. </b> + If you have custom code, and your site is in a CVS repository, upgrade with these steps: + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p> + <b>Upgrade the file system for all packages in use. </b> + <a class="xref" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files">the section called “Upgrading the OpenACS files”</a> + </p> + </li><li class="listitem"> + <p>Go to <a class="ulink" href="/acs-admin/install" target="_top">/acs-admin/install/</a> and click "Upgrade Your System" in "Install from local file system"</p> + </li><li class="listitem"> + <p>Select all of the packages you want to upgrade and proceed</p> + </li><li class="listitem"> + <p>After upgrade is complete, restart the server as indicated.</p> + </li><li class="listitem"> + <p>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.</p> + </li></ol></div> + </li></ul></div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-4.6.3-to-5.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-openacs-files.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading OpenACS 4.6.3 to 5.0 </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading the OpenACS files</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -12,7 +12,7 @@ <a name="upgrade-openacs-files" id="upgrade-openacs-files"></a>Upgrading the OpenACS files</h2></div></div></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592101741160" id="idp140592101741160"></a>Chosing a Method to Upgrade your +<a name="idp140623160003576" id="idp140623160003576"></a>Chosing a Method to Upgrade your Files</h3></div></div></div><p>OpenACS is distributed in many different ways:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"><p>as a collection of files</p></li><li class="listitem"><p>as one big tarball</p></li><li class="listitem"><p>via CVS</p></li><li class="listitem"><p>via automatic download from within the APM (package manager)</p></li> </ul></div><p>Upgrades work by first changing the file system (via any of the @@ -27,26 +27,26 @@ </p> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592101796104" id="idp140592101796104"></a>Methods of upgrading OpenACS files</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> +<a name="idp140623160009080" id="idp140623160009080"></a>Methods of upgrading OpenACS files</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc;"> <li class="listitem"> <p> <strong>Upgrading files for a site which is not in a CVS -repository. </strong>Unpack the tarball into a new +repository. </strong> Unpack the tarball into a new directory and copy its contents on top of your working directory. Or just 'install software', select remote repository, and upgrade your files from there.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> [$OPENACS_SERVICE_NAME web]$ <strong class="userinput"><code>tar xzf /var/tmp/openacs-5-1.tar.gz</code></strong> [$OPENACS_SERVICE_NAME web]$ <strong class="userinput"><code>cp -r openacs-5-1/* openacs-4</code></strong> [$OPENACS_SERVICE_NAME openacs-upgrade]$ <strong class="userinput"><code>exit</code></strong> [root root]# -<span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cd /var/lib/aolserver tar xzf /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 -exit</span></span> +exit</span> </pre> </li><li class="listitem"> <p><span class="strong"><strong>Upgrading files for a site in a @@ -56,13 +56,13 @@ version, without overriding your own local customizations.</p><p>This diagram explains the basic idea. However, the labels are incorrect. Step 1(a) has been removed, and Step 1(b) should be labelled Step 1.</p><div class="figure"> -<a name="idp140592101750040" id="idp140592101750040"></a><p class="title"><strong>Figure 5.2. Upgrading a local CVS +<a name="idp140623159992456" id="idp140623159992456"></a><p class="title"><strong>Figure 5.2. Upgrading a local CVS repository</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/upgrade-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div></div> </div><br class="figure-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle;"> <li class="listitem"> <p> <strong>Step 0: Set up a working CVS -checkout. </strong>To get your OpenACS code into your +checkout. </strong> To get your OpenACS code into your local CVS repository, you will set up a working CVS checkout of OpenACS. When you want to update your site, you'll update the working CVS checkout, import those changes into your local CVS @@ -75,21 +75,21 @@ for each branch of OpenACS - if you are using OpenACS 5.1,x, you will need a 5.1 checkout. That will be good for 5.1, 5.11, 5.12, and so on. But when you want to upgrade to OpenACS 5.2, you'll -need to check out another branch.</p><p>The <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> tag identifies the -latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the -latest compatible version of each package. Each minor release of -OpenACS since 5.0 has this tagging structure. For example, OpenACS -5.1.x has <code class="computeroutput">openacs-5-1-compat</code>.</p><p>You will want to separately check out all the packages you are +need to check out another branch.</p><p>The <em class="replaceable"><code>openacs-5-1-compat</code></em> +tag identifies the latest released version of OpenACS 5.1 (ie, +5.1.3 or 5.1.4) and the latest compatible version of each package. +Each minor release of OpenACS since 5.0 has this tagging structure. +For example, OpenACS 5.1.x has <code class="computeroutput">openacs-5-1-compat</code>.</p><p>You will want to separately check out all the packages you are using.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> acs-core</code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r <em class="replaceable"><code>openacs-5-1-compat</code></em> acs-core</code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd openacs-4/packages</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span><span class="replaceable"><span class="replaceable">packagename packagename2...</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r <em class="replaceable"><code>openacs-5-1-compat</code></em><em class="replaceable"><code>packagename packagename2...</code></em> </code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd ../..</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-4 <span class="replaceable"><span class="replaceable">openacs-5-1</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-4 <em class="replaceable"><code>openacs-5-1</code></em> </code></strong> </pre><p>Make sure your working CVS checkout doesn't have the entire CVS tree from OpenACS. A good way to check this is if it has a @@ -101,50 +101,50 @@ code. </strong></p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square;"> <li class="listitem"> <p> -<strong>Update CVS. </strong>Update your local CVS +<strong>Update CVS. </strong> Update your local CVS working checkout (unless you just set it up).</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>openacs-5-1</code></em> </code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs up -Pd ChangeLog *.txt bin etc Tcl www packages/*</code></strong> </pre> </li><li class="listitem"> <p> <strong>Update a single package via cvs working -checkout. </strong>You can add or upgrade a single +checkout. </strong> You can add or upgrade a single package at a time, if you already have a cvs working directory.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/packages/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/packages/<em class="replaceable"><code>openacs-5-1</code></em> </code></strong> -[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code>cvs up -Pd <span class="replaceable"><span class="replaceable">packagename</span></span> +[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code>cvs up -Pd <em class="replaceable"><code>packagename</code></em> </code></strong> </pre><p>In the next section, the import must be tailored to just this package.</p> </li> </ul></div> </li><li class="listitem"> <p> -<strong>Step 2: Merge New OpenACS code. </strong>Now -that you have a local copy of the new OpenACS code, you need to +<strong>Step 2: Merge New OpenACS code. </strong> +Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.</p><p>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span> +[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>openacs-5-1</code></em> </code></strong> -[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS <span class="replaceable"><span class="replaceable">openacs-5-1</span></span> +[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> OpenACS <em class="replaceable"><code>openacs-5-1</code></em> </code></strong> </pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"> <h3 class="title">Tip</h3><p>If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly. In this example, we are adding the <code class="computeroutput">myfirstpackage</code> package.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-0</span></span>/package/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>openacs-5-0</code></em>/package/<em class="replaceable"><code>myfirstpackage</code></em> </code></strong> -[$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cvs -d /var/lib/cvs/ import -m "importing package" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> OpenACS openacs-5-1</code></strong> +[$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cvs -d /var/lib/cvs/ import -m "importing package" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/<em class="replaceable"><code>myfirstpackage</code></em> OpenACS openacs-5-1</code></strong> </pre> </div><p>Create a new directory as temporary working space to reconcile conflicts between the new files and your current work. The example @@ -153,9 +153,9 @@ This section should be improved to use tags instead of the keyword yesterday!</p><pre class="screen"> [$OPENACS_SERVICE_NAME openacs-5.1]$ <strong class="userinput"><code> cd /var/lib/aolserver</code></strong> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>rm -rf <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</code></strong> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>mkdir <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</code></strong> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cvs checkout -d <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade -jOpenACS:yesterday -jOpenACS -kk <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> > cvs.txt 2>&1</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>rm -rf <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>mkdir <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cvs checkout -d <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade -jOpenACS:yesterday -jOpenACS -kk <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> > cvs.txt 2>&1</code></strong> (CVS feedback here) </pre><p>The file /var/tmp/openacs-upgrade/cvs.txt contains the results of the upgrade. If you changed files that are part of the OpenACS @@ -167,16 +167,16 @@ excess lines. When you're finished, or if there aren't any conflicts, save and exit.</p><p>Once you've fixed any conflicts, commit the new code to your local tree.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cd <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</code></strong> -[$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade]$ <strong class="userinput"><code>cvs commit -m "Upgraded to 5.1"</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cd <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade</code></strong> +[$OPENACS_SERVICE_NAME <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade]$ <strong class="userinput"><code>cvs commit -m "Upgraded to 5.1"</code></strong> </pre> </li><li class="listitem"> <p> <strong>Step 3: Upgrade your local staging -site. </strong>Update your working tree with the new +site. </strong> Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed.</p><pre class="screen"> -[$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs up -Pd</code></strong> (CVS feedback) @@ -188,37 +188,39 @@ </li> </ul></div><p><span class="strong"><strong>Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)</strong></span></p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><pre class="screen"> -[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs up -Pd</code></strong> (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ </pre></li></ol></div> </div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="idp140592099085144" id="idp140592099085144"></a>Upgrading a Production Site Safely</h3></div></div></div><p>If you are upgrading a production OpenACS site which is on a +<a name="idp140623178368104" id="idp140623178368104"></a>Upgrading a Production Site Safely</h3></div></div></div><p>If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Declare a freeze on new cvs updates - ie, you cannot run cvs update on the production site</p></li><li class="listitem"><p>Make a manual backup of the production site in addition to the automated backups</p></li><li class="listitem"> <p>Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of ETP, blogger, and other -applications) into a "vendor branch" of the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> CVS tree, as +applications) into a "vendor branch" of the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> CVS tree, as described in "Upgrading a local CVS repository", step 1, above. As soon as we do this, any cvs update command on production might bring new code onto the production site, which would be -bad.</p><p>Do step 2 above (merging conflicts in a <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade working -tree).</p> +bad.</p><p>Do step 2 above (merging conflicts in a <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade +working tree).</p> </li><li class="listitem"><p>Manually resolve any conflicts in the working upgrade tree</p></li><li class="listitem"><p>Use the upgrade script and a recent backup of the production -database, to ake a new upgraded database called <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade. Now we -have a new website called <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade.</p></li><li class="listitem"><p>Test the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade site</p></li><li class="listitem"> -<p>If <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade is fully -functional, do the real upgrade.</p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p>Take down the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> site and put up a -"down for maintenance" page.</p></li><li class="listitem"><p>Repeat the upgrade with the most recent database</p></li><li class="listitem"><p>Test the that the new site is functional. If so, change the -upgraded site to respond to <span class="replaceable"><span class="replaceable">yourserver.net</span></span> requests. If not, bring -the original production site back up and return to the merge.</p></li> +database, to ake a new upgraded database called <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade. Now +we have a new website called <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade.</p></li><li class="listitem"><p>Test the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade +site</p></li><li class="listitem"> +<p>If <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade is +fully functional, do the real upgrade.</p><div class="orderedlist"><ol class="orderedlist" type="a"> +<li class="listitem"><p>Take down the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> site and put +up a "down for maintenance" page.</p></li><li class="listitem"><p>Repeat the upgrade with the most recent database</p></li><li class="listitem"><p>Test the that the new site is functional. If so, change the +upgraded site to respond to <em class="replaceable"><code>yourserver.net</code></em> requests. If not, +bring the original production site back up and return to the +merge.</p></li> </ol></div> </li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html 7 Aug 2017 23:47:53 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/upgrade-openacs-files.html 8 Nov 2017 09:42:12 -0000 1.29 @@ -1,8 +1,15 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading the OpenACS files</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation"><link rel="next" href="upgrade-supporting.html" title="Upgrading Platform components"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-5-0-dot.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-supporting.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-openacs-files"></a>Upgrading the OpenACS files</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592101741160"></a>Chosing a Method to Upgrade your Files</h3></div></div></div><p>OpenACS is distributed in many different ways: +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading the OpenACS files</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation"><link rel="next" href="upgrade-supporting.html" title="Upgrading Platform components"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-5-0-dot.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-supporting.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-openacs-files"></a>Upgrading the OpenACS files</h2></div></div></div> + + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623160003576"></a>Chosing a Method to Upgrade your Files</h3></div></div></div> + + <p>OpenACS is distributed in many different ways: </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>as a collection of files</p></li><li class="listitem"><p> as one big tarball</p></li><li class="listitem"><p> via CVS</p></li><li class="listitem"><p> via automatic download from within the APM (package manager)</p></li></ul></div><p> - </p><p>Upgrades work by first changing the file system (via any + </p> + + <p>Upgrades work by first changing the file system (via any of the previous methods), and then using the APM to scan the file system, find upgrade scripts, and execute them. Starting with OpenACS 5.0, the last method was added, which @@ -11,105 +18,220 @@ describes whether or not you need to be upgrading using this page or not: <a class="xref" href="upgrade-5-0-dot.html" title="Upgrading an OpenACS 5.0.0 or greater installation">the section called “Upgrading an OpenACS 5.0.0 or greater installation”</a> - </p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592101796104"></a>Methods of upgrading OpenACS files</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><b>Upgrading files for a site which is not in a CVS repository. </b>Unpack the tarball into a new directory and copy its + </p> + </div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623160009080"></a>Methods of upgrading OpenACS files</h3></div></div></div> + + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p> + <b>Upgrading files for a site which is not in a CVS repository. </b> + Unpack the tarball into a new directory and copy its contents on top of your working directory. Or just 'install software', select remote repository, and upgrade your files - from there.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + from there. + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> [$OPENACS_SERVICE_NAME web]$ <strong class="userinput"><code>tar xzf /var/tmp/openacs-5-1.tar.gz</code></strong> [$OPENACS_SERVICE_NAME web]$ <strong class="userinput"><code>cp -r openacs-5-1/* openacs-4</code></strong> [$OPENACS_SERVICE_NAME openacs-upgrade]$ <strong class="userinput"><code>exit</code></strong> [root root]# -<span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +<span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> cd /var/lib/aolserver tar xzf /var/tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 -exit</span></span></pre></li><li class="listitem"><p> +exit</span></pre> + </li><li class="listitem"> + <p> <span class="strong"><strong>Upgrading files for a site in a private CVS repository</strong></span> - </p><p>Many OpenACS site developers operate their own CVS + </p> + + <p>Many OpenACS site developers operate their own CVS repository to keep track of local customizations. In this section, we describe how to upgrade your local CVS repository with the latest OpenACS version, without overriding your own - local customizations. </p><p>This diagram explains the basic idea. However, the + local customizations. </p> + + <p>This diagram explains the basic idea. However, the labels are incorrect. Step 1(a) has been removed, and Step - 1(b) should be labelled Step 1.</p><div class="figure"><a name="idp140592101750040"></a><p class="title"><b>Figure 5.2. Upgrading a local CVS repository</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/upgrade-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div></div></div><br class="figure-break"><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p><b>Step 0: Set up a working CVS checkout. </b>To get your OpenACS code into your local CVS + 1(b) should be labelled Step 1.</p> + + <div class="figure"><a name="idp140623159992456"></a><p class="title"><b>Figure 5.2. Upgrading a local CVS repository</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/upgrade-cvs.png" align="middle" alt="Upgrading a local CVS repository"></div> + </div></div><br class="figure-break"> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"> + <p> + <b>Step 0: Set up a working CVS checkout. </b> + + + To get your OpenACS code into your local CVS repository, you will set up a working CVS checkout of OpenACS. When you want to update your site, you'll update the working CVS checkout, import those changes into your local CVS checkout, create a temporary CVS checkout to merge your local changes, fix any conflicts, commit your changes, and then update your site. It sounds complicated, but it's not too bad, and - it is the best way to work around CVS's limitations.</p><p>This part describes how to set up your working CVS + it is the best way to work around CVS's limitations. + </p> + <p>This part describes how to set up your working CVS checkout. Once it is set up, you'll be able to update any packages using the existing working CVS checkout. We use one dedicated directory for each branch of OpenACS - if you are using OpenACS 5.1,x, you will need a 5.1 checkout. That will be good for 5.1, 5.11, 5.12, and so on. But when you want to upgrade to OpenACS 5.2, you'll need to check out another - branch.</p><p>The <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has <code class="computeroutput">openacs-5-1-compat</code>.</p><p>You will want to separately check out all the + branch.</p> + + <p>The <em class="replaceable"><code>openacs-5-1-compat</code></em> tag identifies the latest released version of OpenACS 5.1 (ie, 5.1.3 or 5.1.4) and the latest compatible version of each package. Each minor release of OpenACS since 5.0 has this tagging structure. For example, OpenACS 5.1.x has <code class="computeroutput">openacs-5-1-compat</code>.</p> + + <p>You will want to separately check out all the packages you are using. - </p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + </p> + + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> acs-core</code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <em class="replaceable"><code>openacs-5-1-compat</code></em> acs-core</code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd openacs-4/packages</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <span class="replaceable"><span class="replaceable">openacs-5-1-compat</span></span> <span class="replaceable"><span class="replaceable">packagename packagename2...</span></span></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r <em class="replaceable"><code>openacs-5-1-compat</code></em> <em class="replaceable"><code>packagename packagename2...</code></em></code></strong> [$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd ../..</code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-4 <span class="replaceable"><span class="replaceable">openacs-5-1</span></span></code></strong></pre><p>Make sure your working CVS checkout doesn't have +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>mv openacs-4 <em class="replaceable"><code>openacs-5-1</code></em></code></strong></pre> + + <p>Make sure your working CVS checkout doesn't have the entire CVS tree from OpenACS. A good way to check this is if it has a contrib directory. If it does, you probably checked out the entire tree. You might want to start over, remove your working CVS checkout, and try again. - </p></li><li class="listitem"><p><b>Step 1: Import new OpenACS code. </b> - </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"><p><b>Update CVS. </b>Update your local CVS working checkout (unless - you just set it up). </p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs up -Pd ChangeLog *.txt bin etc Tcl www packages/*</code></strong></pre></li><li class="listitem"><p><b>Update a single package via cvs working checkout. </b>You can add or upgrade a single package at a time, if you already have a cvs working directory.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/packages/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span></code></strong> -[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code>cvs up -Pd <span class="replaceable"><span class="replaceable">packagename</span></span></code></strong></pre><p>In the next section, the import must be tailored to just this package.</p></li></ul></div></li><li class="listitem"><p><b>Step 2: Merge New OpenACS code. </b>Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur.</p><p>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</p><pre class="screen">[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-1</span></span></code></strong> -[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> OpenACS <span class="replaceable"><span class="replaceable">openacs-5-1</span></span></code></strong> - </pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly. In this example, we are adding the <code class="computeroutput">myfirstpackage</code> package.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> -[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">openacs-5-0</span></span>/package/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span></code></strong> -[$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cvs -d /var/lib/cvs/ import -m "importing package" <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/packages/<span class="replaceable"><span class="replaceable">myfirstpackage</span></span> OpenACS openacs-5-1</code></strong></pre></div><p>Create a new directory as temporary working space to + </p> + + </li><li class="listitem"> + <p> + <b>Step 1: Import new OpenACS code. </b> + + </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: square; "><li class="listitem"> + <p> + <b>Update CVS. </b> + Update your local CVS working checkout (unless + you just set it up). + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>openacs-5-1</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cvs up -Pd ChangeLog *.txt bin etc Tcl www packages/*</code></strong></pre> + </li><li class="listitem"> + <p> + <b>Update a single package via cvs working checkout. </b> + You can add or upgrade a single package at a time, if you already have a cvs working directory. + </p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/packages/<em class="replaceable"><code>openacs-5-1</code></em></code></strong> +[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code>cvs up -Pd <em class="replaceable"><code>packagename</code></em></code></strong></pre> + <p>In the next section, the import must be tailored to just this package.</p> + </li></ul></div><p> + </p> + </li><li class="listitem"> + <p> + <b>Step 2: Merge New OpenACS code. </b> + Now that you have a local copy of the new OpenACS code, you need to import it into your local CVS repository and resolve any conflicts that occur. + </p> + <p>Import the new files into your cvs repository; where they match existing files, they will become the new version of the file.</p> + + <pre class="screen">[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cd /var/lib/aolserver/<em class="replaceable"><code>openacs-5-1</code></em></code></strong> +[$OPENACS_SERVICE_NAME openacs-5-1]$ <strong class="userinput"><code> cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> OpenACS <em class="replaceable"><code>openacs-5-1</code></em></code></strong> + </pre> + + <div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3> + <p>If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly. In this example, we are adding the <code class="computeroutput">myfirstpackage</code> package.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> +[$OPENACS_SERVICE_NAME aolserver]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>openacs-5-0</code></em>/package/<em class="replaceable"><code>myfirstpackage</code></em></code></strong> +[$OPENACS_SERVICE_NAME myfirstpackage]$ <strong class="userinput"><code>cvs -d /var/lib/cvs/ import -m "importing package" <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/packages/<em class="replaceable"><code>myfirstpackage</code></em> OpenACS openacs-5-1</code></strong></pre> + </div> + + <p>Create a new directory as temporary working space to reconcile conflicts between the new files and your current work. The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day. This section should be - improved to use tags instead of the keyword yesterday!</p><pre class="screen">[$OPENACS_SERVICE_NAME openacs-5.1]$ <strong class="userinput"><code> cd /var/lib/aolserver</code></strong> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>rm -rf <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</code></strong> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>mkdir <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</code></strong> -[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cvs checkout -d <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade -jOpenACS:yesterday -jOpenACS -kk <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> > cvs.txt 2>&1</code></strong> -(CVS feedback here)</pre><p>The file /var/tmp/openacs-upgrade/cvs.txt contains the + improved to use tags instead of the keyword yesterday!</p> + <pre class="screen">[$OPENACS_SERVICE_NAME openacs-5.1]$ <strong class="userinput"><code> cd /var/lib/aolserver</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>rm -rf <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>mkdir <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade</code></strong> +[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cvs checkout -d <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade -jOpenACS:yesterday -jOpenACS -kk <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> > cvs.txt 2>&1</code></strong> +(CVS feedback here)</pre> + <p>The file /var/tmp/openacs-upgrade/cvs.txt contains the results of the upgrade. If you changed files that are part of the OpenACS tarball and those changes conflict, you'll have to manually reconcile them. Use the emacs command <code class="computeroutput">M-x sort-lines</code> (you may have to click Ctrl-space at the beginning of the - file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit.</p><p>Once you've fixed any conflicts, commit the new code - to your local tree. </p><pre class="screen">[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cd <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade</code></strong> -[$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade]$ <strong class="userinput"><code>cvs commit -m "Upgraded to 5.1"</code></strong></pre></li><li class="listitem"><p><b>Step 3: Upgrade your local staging site. </b>Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed.</p><pre class="screen">[$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + file, and go to the end, and then try M-x sort-lines) and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit.</p> + <p>Once you've fixed any conflicts, commit the new code + to your local tree. </p> + <pre class="screen">[$OPENACS_SERVICE_NAME tmp]$ <strong class="userinput"><code>cd <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade</code></strong> +[$OPENACS_SERVICE_NAME <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade]$ <strong class="userinput"><code>cvs commit -m "Upgraded to 5.1"</code></strong></pre> </li><li class="listitem"> + <p> + <b>Step 3: Upgrade your local staging site. </b> + Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed. + </p> +<pre class="screen">[$OPENACS_SERVICE_NAME <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs up -Pd</code></strong> (CVS feedback) [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>exit</code></strong> -[root root]# </pre></li></ul></div></li></ul></div><p> +[root root]# </pre> + </li></ul></div> + </li></ul></div> + <p> <span class="strong"><strong>Upgrading files for a site using the OpenACS CVS repository (cvs.openacs.org)</strong></span> - </p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><pre class="screen">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + </p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <pre class="screen">[$OPENACS_SERVICE_NAME ~]$ <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <strong class="userinput"><code>cvs up -Pd</code></strong> (CVS feedback) -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140592099085144"></a>Upgrading a Production Site Safely</h3></div></div></div><p>If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Declare a freeze on new cvs updates - ie, you cannot run cvs update - on the production site</p></li><li class="listitem"><p> +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</pre> + </li></ol></div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp140623178368104"></a>Upgrading a Production Site Safely</h3></div></div></div> + + <p>If you are upgrading a production OpenACS site which is on a private CVS tree, this process lets you do the upgrade without risking extended downtime or an unusable site:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Declare a freeze on new cvs updates - ie, you cannot run cvs update + on the production site</p> + </li><li class="listitem"> + <p> Make a manual backup of the production site in addition to the - automated backups</p></li><li class="listitem"><p>Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of + automated backups</p> + </li><li class="listitem"> + <p>Import the new code (for example, OpenACS 5.0.4, openacs-5-0-compat versions of ETP, blogger, and other applications) into a "vendor branch" of the - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> CVS tree, as described in "Upgrading a local CVS repository", step 1, above. + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> CVS tree, as described in "Upgrading a local CVS repository", step 1, above. As soon as we do this, any cvs update command on production might bring new code onto the production site, which - would be bad.</p><p>Do step 2 above (merging conflicts in a <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade working tree).</p></li><li class="listitem"><p> + would be bad.</p> + <p>Do step 2 above (merging conflicts in a <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade working tree).</p> + </li><li class="listitem"> + <p> Manually resolve any conflicts in the working upgrade tree - </p></li><li class="listitem"><p>Use the upgrade script and a recent backup of the production database, to ake - a new upgraded database called <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade. Now we - have a new website called <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade. - </p></li><li class="listitem"><p> - Test the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade site - </p></li><li class="listitem"><p>If <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>-upgrade is fully functional, do the real upgrade.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Take down the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> site and put up a "down for maintenance" page.</p></li><li class="listitem"><p>Repeat the upgrade with the most recent database</p></li><li class="listitem"><p>Test the that the new site is functional. If so, change the upgraded site to respond to - <span class="replaceable"><span class="replaceable">yourserver.net</span></span> requests. If not, bring the original production site back up and return to the merge.</p></li></ol></div></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-5-0-dot.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-supporting.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading an OpenACS 5.0.0 or greater installation </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading Platform components</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> + </li><li class="listitem"> + <p>Use the upgrade script and a recent backup of the production database, to ake + a new upgraded database called <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade. Now we + have a new website called <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade. + </p> + </li><li class="listitem"> + <p> + Test the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade site + </p> + </li><li class="listitem"> + <p>If <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>-upgrade is fully functional, do the real upgrade.</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Take down the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> site and put up a "down for maintenance" page.</p> + </li><li class="listitem"> + <p>Repeat the upgrade with the most recent database</p> + </li><li class="listitem"> + <p>Test the that the new site is functional. If so, change the upgraded site to respond to + <em class="replaceable"><code>yourserver.net</code></em> requests. If not, bring the original production site back up and return to the merge.</p> + </li></ol></div> + </li></ol></div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-5-0-dot.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-supporting.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading an OpenACS 5.0.0 or greater installation </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading Platform components</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade-overview.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade-overview.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade-overview.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -26,23 +26,23 @@ upgrade scripts, and prompt you to restart the server. After restarting the server again, the upgrade is complete.</p></li> </ol></div><div class="figure"> -<a name="idp140592104571672" id="idp140592104571672"></a><p class="title"><strong>Figure 5.1. Upgrading with the +<a name="idp140623159984264" id="idp140623159984264"></a><p class="title"><strong>Figure 5.1. Upgrading with the APM</strong></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/upgrade-apm.png" align="middle" alt="Upgrading with the APM"></div></div> </div><br class="figure-break"><p>It's always a good idea to precede an upgrade attempt with a <a class="link" href="snapshot-backup" title="Manual backup and recovery">snapshot backup</a>.</p><div class="table"> -<a name="idp140592104575352" id="idp140592104575352"></a><p class="title"><strong>Table 5.1. Assumptions in this +<a name="idp140623160218856" id="idp140623160218856"></a><p class="title"><strong>Table 5.1. Assumptions in this section</strong></p><div class="table-contents"><table class="table" summary="Assumptions in this section" cellspacing="0" border="1"> <colgroup> <col><col> </colgroup><tbody> <tr> -<td>name of OpenACS user</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td> +<td>name of OpenACS user</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> -<td>OpenACS server name</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td> +<td>OpenACS server name</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> -<td>Root of OpenACS file tree</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME</span></span></td> +<td>Root of OpenACS file tree</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME</code></em></td> </tr><tr> -<td>Database backup directory</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</span></span></td> +<td>Database backup directory</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</code></em></td> </tr> </tbody> </table></div> Index: openacs-4/packages/acs-core-docs/www/upgrade-overview.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-overview.html,v diff -u -r1.28 -r1.29 --- openacs-4/packages/acs-core-docs/www/upgrade-overview.html 7 Aug 2017 23:47:53 -0000 1.28 +++ openacs-4/packages/acs-core-docs/www/upgrade-overview.html 8 Nov 2017 09:42:12 -0000 1.29 @@ -1,7 +1,36 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="next" href="upgrade-4.5-to-4.6.html" title="Upgrading 4.5 or higher to 4.6.3"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-4.5-to-4.6.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-overview"></a>Overview</h2></div></div></div><p>Starting with Version 4.5, all OpenACS core packages support +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Overview</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="next" href="upgrade-4.5-to-4.6.html" title="Upgrading 4.5 or higher to 4.6.3"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-4.5-to-4.6.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-overview"></a>Overview</h2></div></div></div> + + <p>Starting with Version 4.5, all OpenACS core packages support automatic upgrade. That means that, if you have OpenACS 4.5 or better, you should always be able to upgrade all of your core packages automatically. If you haven't changed anything, no manual intervention should be required. If you are running - OpenACS prior to 4.5, upgrading will require manual effort.</p><p>If all of these conditions are true:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>Your OpenACS Core is 5.0.0 or later</p></li><li class="listitem"><p>You do not keep your OpenACS site in a local CVS repository</p></li><li class="listitem"><p>You do not have any custom code</p></li></ul></div><p>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:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Browse to the <a class="ulink" href="/acs-admin/install/" target="_top">Installer</a>.</p></li><li class="listitem"><p>Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.</p></li><li class="listitem"><p>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.</p></li></ol></div><div class="figure"><a name="idp140592104571672"></a><p class="title"><b>Figure 5.1. Upgrading with the APM</b></p><div class="figure-contents"><div class="mediaobject" align="center"><img src="images/upgrade-apm.png" align="middle" alt="Upgrading with the APM"></div></div></div><br class="figure-break"><p>It's always a good idea to precede an upgrade attempt with a <a class="link" href="snapshot-backup.html" title="Manual backup and recovery">snapshot backup</a>.</p><div class="table"><a name="idp140592104575352"></a><p class="title"><b>Table 5.1. Assumptions in this section</b></p><div class="table-contents"><table class="table" summary="Assumptions in this section" cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>name of OpenACS user</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>OpenACS server name</td><td><span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>Root of OpenACS file tree</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME</span></span></td></tr><tr><td>Database backup directory</td><td><span class="replaceable"><span class="replaceable">/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</span></span></td></tr></tbody></table></div></div><br class="table-break"></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-4.5-to-4.6.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 5. Upgrading </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading 4.5 or higher to 4.6.3</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + OpenACS prior to 4.5, upgrading will require manual effort.</p> + <p>If all of these conditions are true:</p> + <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> + <p>Your OpenACS Core is 5.0.0 or later</p> + </li><li class="listitem"> + <p>You do not keep your OpenACS site in a local CVS repository</p> + </li><li class="listitem"> + <p>You do not have any custom code</p> + </li></ul></div> + <p>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:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Browse to the <a class="ulink" href="/acs-admin/install/" target="_top">Installer</a>.</p> + </li><li class="listitem"> + <p>Click install or upgrade under "Install from OpenACS Repository" and select the packages to install or upgrade.</p> + </li><li class="listitem"> + <p>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.</p> + </li></ol></div> + <div class="figure"><a name="idp140623159984264"></a><p class="title"><b>Figure 5.1. Upgrading with the APM</b></p><div class="figure-contents"> + + <div class="mediaobject" align="center"><img src="images/upgrade-apm.png" align="middle" alt="Upgrading with the APM"></div> + </div></div><br class="figure-break"> + + <p>It's always a good idea to precede an upgrade attempt with a <a class="link" href="snapshot-backup.html" title="Manual backup and recovery">snapshot backup</a>.</p> + <div class="table"><a name="idp140623160218856"></a><p class="title"><b>Table 5.1. Assumptions in this section</b></p><div class="table-contents"> + + <table class="table" summary="Assumptions in this section" cellspacing="0" border="1"><colgroup><col><col></colgroup><tbody><tr><td>name of OpenACS user</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>OpenACS server name</td><td><em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>Root of OpenACS file tree</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME</code></em></td></tr><tr><td>Database backup directory</td><td><em class="replaceable"><code>/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup</code></em></td></tr></tbody></table> + </div></div><br class="table-break"> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-4.5-to-4.6.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter 5. Upgrading </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Upgrading 4.5 or higher to 4.6.3</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -17,9 +17,9 @@ describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"> -<p>Uninstall the old OpenFTS Engine from the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> database.</p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p><span class="bold"><strong>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/openfts</code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Drop OpenFTS -Engine</span></span></code> +<p>Uninstall the old OpenFTS Engine from the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> database.</p><div class="orderedlist"><ol class="orderedlist" type="a"> +<li class="listitem"><p><span class="bold"><strong>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/openfts</code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel">Administration</span></code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton">Drop OpenFTS +Engine</span></code> </strong></span></p></li> </ol></div> </li><li class="listitem"> @@ -50,39 +50,40 @@ exit </pre><p>In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> - [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/pgsql/share/contrib/openfts.sql</code></strong> + [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/pgsql/share/contrib/openfts.sql</code></strong> CREATE CREATE - [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</code></strong> + [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</code></strong> BEGIN CREATE (~30 more lines) [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>exit</code></strong> [root root]# - <span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/pgsql/share/contrib/openfts.sql -psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql -exit</span></span> + <span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/pgsql/share/contrib/openfts.sql +psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql +exit</span> </pre> </li><li class="listitem"> <p> <strong>OPTIONAL: Install the new OpenFTS -Engine. </strong>If you want to upgrade the OpenFTS +Engine. </strong> If you want to upgrade the OpenFTS Engine, do these steps. (You must have already upgraded the OpenFTS driver to 0.3.2.)</p><div class="orderedlist"><ol class="orderedlist" type="a"> -<li class="listitem"><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/admin/site-map</code> +<li class="listitem"><p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/admin/site-map</code> </p></li><li class="listitem"><p>On the <code class="computeroutput">openfts</code> line, click -on <code class="computeroutput"><span class="guilabel"><span class="guilabel">set parameters</span></span></code>.</p></li><li class="listitem"><p>Change the value of <code class="computeroutput">openfts_tcl_src_path</code> from <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.2/</code> to +on <code class="computeroutput"><span class="guilabel">set +parameters</span></code>.</p></li><li class="listitem"><p>Change the value of <code class="computeroutput">openfts_tcl_src_path</code> from <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.2/</code> to <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.3.2/</code> -</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Set -Parameters</span></span></code> +</p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton">Set +Parameters</span></code> </p></li><li class="listitem"><pre class="screen"> -[root root]# restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -</pre></li><li class="listitem"><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/openfts</code> -</p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Initialize OpenFTS -Engine</span></span></code> +[root root]# restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +</pre></li><li class="listitem"><p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/openfts</code> +</p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel">Administration</span></code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton">Initialize OpenFTS +Engine</span></code> </strong></span></p></li> </ol></div> </li> @@ -100,18 +101,18 @@ they don't match. Also some functions use casting commands that no longer work in 7.3 and these functions must be recreated.</p><p>To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the -upgrade script <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/bin/pg_7.2to7.3_upgrade_helper.pl</code> +upgrade script <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/bin/pg_7.2to7.3_upgrade_helper.pl</code> on the dump file, and reply the dump. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=109337" target="_top">Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?</a>. Example:</p><div class="orderedlist"><ol class="orderedlist" type="1"> <li class="listitem"><p>Back up the database as per <a class="xref" href="snapshot-backup" title="PostgreSQL">PostgreSQL</a>.</p></li><li class="listitem"> <p>Run the upgrade script on the backup file.</p><pre class="screen"> -[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> +[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> - [$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>]# <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/bin</code></strong> + [$OPENACS_SERVICE_NAME <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>]# <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/bin</code></strong> [$OPENACS_SERVICE_NAME bin]$ <strong class="userinput"><code>./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ - /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> + /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> </code></strong> ================================================================== looking for function acs_object__check_object_ancest in oacs @@ -137,8 +138,8 @@ 5433, say). create a second postgres user to differentiate between the two postgres installs. When you do ./configure, you'll need to include --prefix=$HOME to ensure that it is installed in the -postgres73 user's home directory.</p></li><li class="listitem"><p>Change the path in <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>'s .bashrc or -.bash_profile (or both) files to reflect the new postgres73 user +postgres73 user's home directory.</p></li><li class="listitem"><p>Change the path in <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>'s .bashrc +or .bash_profile (or both) files to reflect the new postgres73 user directory. Also add in the PGPORT.</p></li><li class="listitem"><p>Restore the database from dump as per the <a class="link" href="snapshot-backup" title="Postgres">recovery instructions</a>.</p></li> </ol></div> Index: openacs-4/packages/acs-core-docs/www/upgrade-supporting.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade-supporting.html,v diff -u -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 7 Aug 2017 23:47:53 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/upgrade-supporting.html 8 Nov 2017 09:42:12 -0000 1.22 @@ -1,39 +1,83 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading Platform components</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files"><link rel="next" href="maintenance-web.html" title="Chapter 6. Production Environments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-openacs-files.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-supporting"></a>Upgrading Platform components</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="upgrade-openfts-0.2-to-0.3.2"></a>Upgrading OpenFTS from 0.2 to 0.3.2</h3></div></div></div><p>OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Uninstall the old OpenFTS Engine from the <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> database.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p><span class="bold"><strong>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/openfts</code>.</strong></span> - </p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Drop OpenFTS Engine</span></span></code></strong></span></p></li></ol></div></li><li class="listitem"><p>Build and install the new OpenFTS driver and supporting Tcl procedures. (This section of shell code is not fully documented; please exercise care.)</p><pre class="screen">cd /usr/local/src/ +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Upgrading Platform components</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="upgrade.html" title="Chapter 5. Upgrading"><link rel="previous" href="upgrade-openacs-files.html" title="Upgrading the OpenACS files"><link rel="next" href="maintenance-web.html" title="Chapter 6. Production Environments"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="upgrade-openacs-files.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Upgrading</th><td width="20%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="upgrade-supporting"></a>Upgrading Platform components</h2></div></div></div> + + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="upgrade-openfts-0.2-to-0.3.2"></a>Upgrading OpenFTS from 0.2 to 0.3.2</h3></div></div></div> + + <p>OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time.</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Uninstall the old OpenFTS Engine from the <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> database.</p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p><span class="bold"><strong>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/openfts</code>.</strong></span> + </p> + </li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel">Administration</span></code>.</strong></span></p> + </li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton">Drop OpenFTS Engine</span></code></strong></span></p> + </li></ol></div> + </li><li class="listitem"> + <p>Build and install the new OpenFTS driver and supporting Tcl procedures. (This section of shell code is not fully documented; please exercise care.)</p> + <pre class="screen">cd /usr/local/src/ tar xzf /var/tmp/Search-OpenFTS-tcl-0.3.2.tar.gz chown -R root.root Search-OpenFTS-tcl-0.3.2/ cd Search-OpenFTS-tcl-0.3.2/ ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/ cd aolserver/ make - </pre><p> + </pre> + <p> Back up the old fts driver as a precaution and install the newly - compiled one</p><pre class="screen">mv /usr/local/aolserver/bin/nsfts.so /usr/local/aolserver/bin/nsfts-0.2.so + compiled one</p> + <pre class="screen">mv /usr/local/aolserver/bin/nsfts.so /usr/local/aolserver/bin/nsfts-0.2.so cp nsfts.so /usr/local/aolserver/bin - </pre><p>Build and install the OpenFTS code for PostGresSQL</p><pre class="screen">cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ + </pre> + <p>Build and install the OpenFTS code for PostGresSQL</p> + <pre class="screen">cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.2.3/contrib /usr/local/src/postgresql-7.2.3/contrib/pgsql_contrib_openfts make su - postgres cd tsearch/ make make install - exit</pre><p>In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> - [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/pgsql/share/contrib/openfts.sql</code></strong> + exit</pre> + <p>In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> + [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/pgsql/share/contrib/openfts.sql</code></strong> CREATE CREATE - [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</code></strong> + [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql</code></strong> BEGIN CREATE (~30 more lines) [$OPENACS_SERVICE_NAME dev]$ <strong class="userinput"><code>exit</code></strong> [root root]# - <span class="action"><span class="action">su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/pgsql/share/contrib/openfts.sql -psql <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql -exit</span></span></pre></li><li class="listitem"><p><b>OPTIONAL: Install the new OpenFTS Engine. </b>If you want to upgrade the OpenFTS Engine, do these + <span class="action">su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> +psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/pgsql/share/contrib/openfts.sql +psql <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em> -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql +exit</span></pre> + </li><li class="listitem"> + <p> + <b>OPTIONAL: Install the new OpenFTS Engine. </b> + If you want to upgrade the OpenFTS Engine, do these steps. (You must have already upgraded the OpenFTS driver to - 0.3.2.)</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/admin/site-map</code></p></li><li class="listitem"><p>On the <code class="computeroutput">openfts</code> line, click on <code class="computeroutput"><span class="guilabel"><span class="guilabel">set parameters</span></span></code>.</p></li><li class="listitem"><p>Change the value of <code class="computeroutput">openfts_tcl_src_path</code> from <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.2/</code> to <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.3.2/</code></p></li><li class="listitem"><p>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Set Parameters</span></span></code></p></li><li class="listitem"><pre class="screen">[root root]# restart-aolserver <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></pre></li><li class="listitem"><p>Browse to <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver</span></span>/openfts</code></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel"><span class="guilabel">Administration</span></span></code>.</strong></span></p></li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton"><span class="guibutton">Initialize OpenFTS Engine</span></span></code></strong></span></p></li></ol></div></li></ol></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="upgrade-postgres-7.2-to-7.3"></a>Upgrading from PostGreSQL 7.2 to 7.3</h3></div></div></div><p>An OpenACS database created in PostGreSQL 7.2 will not + 0.3.2.) + </p> + <div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"> + <p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/admin/site-map</code></p> + </li><li class="listitem"> + <p>On the <code class="computeroutput">openfts</code> line, click on <code class="computeroutput"><span class="guilabel">set parameters</span></code>.</p> + </li><li class="listitem"> + <p>Change the value of <code class="computeroutput">openfts_tcl_src_path</code> from <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.2/</code> to <code class="computeroutput">/usr/local/src/Search-OpenFTS-tcl-0.3.2/</code></p> + </li><li class="listitem"> + <p>Click <code class="computeroutput"><span class="guibutton">Set Parameters</span></code></p> + </li><li class="listitem"> + <pre class="screen">[root root]# restart-aolserver <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></pre> + </li><li class="listitem"> + <p>Browse to <code class="computeroutput">http://<em class="replaceable"><code>yourserver</code></em>/openfts</code></p> + </li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guilabel">Administration</span></code>.</strong></span></p> + </li><li class="listitem"><p><span class="bold"><strong>Click <code class="computeroutput"><span class="guibutton">Initialize OpenFTS Engine</span></code></strong></span></p> + </li></ol></div> + </li></ol></div> + </div> + <div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="upgrade-postgres-7.2-to-7.3"></a>Upgrading from PostGreSQL 7.2 to 7.3</h3></div></div></div> + + <p>An OpenACS database created in PostGreSQL 7.2 will not work correctly in PostGreSQL 7.3. This is because 7.2 truncates function names to 31 characters, but 7.3 does not. This does not cause problems in 7.2, because truncation occurs both at @@ -42,13 +86,19 @@ names in the database remain truncated but the function calls are not, and so they don't match. Also some functions use casting commands that no longer work in 7.3 and these functions - must be recreated.</p><p> - To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script <code class="computeroutput">/var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/bin/pg_7.2to7.3_upgrade_helper.pl</code> on the dump file, and reply the dump. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=109337" target="_top">Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?</a>. Example:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Back up the database as per <a class="xref" href="snapshot-backup.html#postgres-snapshot-backup" title="PostgreSQL">PostgreSQL</a>.</p></li><li class="listitem"><p>Run the upgrade script on the backup file.</p><pre class="screen">[root root]# <strong class="userinput"><code>su - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> - [$OPENACS_SERVICE_NAME <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>]# <strong class="userinput"><code>cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>/bin</code></strong> + must be recreated.</p> + <p> + To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script <code class="computeroutput">/var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/bin/pg_7.2to7.3_upgrade_helper.pl</code> on the dump file, and reply the dump. See <a class="ulink" href="http://openacs.org/forums/message-view?message_id=109337" target="_top">Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?</a>. Example:</p> + <div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"> + <p>Back up the database as per <a class="xref" href="snapshot-backup.html#postgres-snapshot-backup" title="PostgreSQL">PostgreSQL</a>.</p> + </li><li class="listitem"> + <p>Run the upgrade script on the backup file.</p> + <pre class="screen">[root root]# <strong class="userinput"><code>su - <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> + [$OPENACS_SERVICE_NAME <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>]# <strong class="userinput"><code>cd /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>/bin</code></strong> [$OPENACS_SERVICE_NAME bin]$ <strong class="userinput"><code>./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ - /var/lib/aolserver/<span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span></code></strong> + /var/lib/aolserver/<em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em></code></strong> ================================================================== looking for function acs_object__check_object_ancest in oacs grep result: /var/lib/aolserver/aufrecht-dev/packages/acs-kernel/sql/postgresql/acs-objects-create.sql:create function acs_object__check_object_ancestors (integer,integer,integer) @@ -57,23 +107,37 @@ <span class="emphasis"><em>(many lines omitted)</em></span> [$OPENACS_SERVICE_NAME bin]$ - </pre></li><li class="listitem"><p>Use perl to replace <code class="computeroutput">timestamp</code> with <code class="computeroutput">timestamptz</code> in the dump file. See example perl code in step two in <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6" target="_top">/contrib/misc/upgrade_4.6_to_5.0.sh</a></p></li><li class="listitem"><p>Create a new user for PostgreSQL 7.3.x, as per the + </pre> + </li><li class="listitem"> + <p>Use perl to replace <code class="computeroutput">timestamp</code> with <code class="computeroutput">timestamptz</code> in the dump file. See example perl code in step two in <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/contrib/misc/upgrade_4.6_to_5.0.sh?r=1.6" target="_top">/contrib/misc/upgrade_4.6_to_5.0.sh</a></p> + + </li><li class="listitem"> + <p>Create a new user for PostgreSQL 7.3.x, as per the Postgres installation guide. Keep in mind that your installation location is different, and your startup script (/etc/init.d/postgres73 should be named differently. You might even need to edit that file to make the paths correct). You'll also need to add <code class="computeroutput">export PGPORT=5434</code> to the .bashrc and/or .bash_profile for the postgres73 user. - </p></li><li class="listitem"><p>Install PostgreSQL 7.3.x. Note that you PostgreSQL + </p> + </li><li class="listitem"> + <p>Install PostgreSQL 7.3.x. Note that you PostgreSQL must listen on a different port in order to work correctly, so you'll need to edit the configuration file (/usr/local/pgsql73/data/postgresql.conf) and change the port (to 5433, say). create a second postgres user to differentiate between the two postgres installs. When you do ./configure, you'll need to include --prefix=$HOME to ensure that it is installed in the - postgres73 user's home directory.</p></li><li class="listitem"><p>Change the path in - <span class="replaceable"><span class="replaceable">$OPENACS_SERVICE_NAME</span></span>'s .bashrc or + postgres73 user's home directory.</p> + </li><li class="listitem"> + <p>Change the path in + <em class="replaceable"><code>$OPENACS_SERVICE_NAME</code></em>'s .bashrc or .bash_profile (or both) files to reflect the new postgres73 - user directory. Also add in the PGPORT.</p></li><li class="listitem"><p>Restore the database from dump as per the <a class="link" href="snapshot-backup.html#restore-postgres" title="Postgres">recovery instructions</a>.</p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-openacs-files.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading the OpenACS files </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Chapter 6. Production Environments</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + user directory. Also add in the PGPORT.</p> + </li><li class="listitem"> + <p>Restore the database from dump as per the <a class="link" href="snapshot-backup.html#restore-postgres" title="Postgres">recovery instructions</a>.</p> + </li></ol></div> + </div> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="upgrade-openacs-files.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maintenance-web.html">Next</a></td></tr><tr><td width="40%" align="left">Upgrading the OpenACS files </td><td width="20%" align="center"><a accesskey="u" href="upgrade.html">Up</a></td><td width="40%" align="right"> Chapter 6. Production Environments</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/upgrade.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/upgrade.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/upgrade.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -18,11 +18,9 @@ files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting">Upgrading Platform components</a></span></dt> </dl> -</div><div class="authorblurb"> -<p>by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel Aufrecht</a> -</p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div> +</div><span style="color: red"><authorblurb></span><p><span style="color: red">by <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">Joel +Aufrecht</a> +</span></p><span style="color: red"></authorblurb></span> </div> <include src="/packages/acs-core-docs/lib/navfooter" leftLink="how-do-I" leftLabel="Prev" leftTitle="How Do I?" Index: openacs-4/packages/acs-core-docs/www/upgrade.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/upgrade.html,v diff -u -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/upgrade.html 7 Aug 2017 23:47:53 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/upgrade.html 8 Nov 2017 09:42:12 -0000 1.32 @@ -1,5 +1,14 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 5. Upgrading</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="how-do-I.html" title="How Do I?"><link rel="next" href="upgrade-overview.html" title="Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="how-do-I.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="upgrade"></a>Chapter 5. Upgrading</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="upgrade-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></span></dt><dt><span class="sect1"><a href="upgrade-4.6.3-to-5.html">Upgrading OpenACS 4.6.3 to 5.0</a></span></dt><dt><span class="sect1"><a href="upgrade-5-0-dot.html">Upgrading an OpenACS 5.0.0 or greater installation</a></span></dt><dt><span class="sect1"><a href="upgrade-openacs-files.html">Upgrading the OpenACS files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting.html">Upgrading Platform components</a></span></dt></dl></div><div class="authorblurb"><p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="how-do-I.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-overview.html">Next</a></td></tr><tr><td width="40%" align="left">How Do I? </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Chapter 5. Upgrading</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="acs-admin.html" title="Part II. Administrator's Guide"><link rel="previous" href="how-do-I.html" title="How Do I?"><link rel="next" href="upgrade-overview.html" title="Overview"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="how-do-I.html">Prev</a> </td><th width="60%" align="center">Part II. Administrator's Guide</th><td width="20%" align="right"> <a accesskey="n" href="upgrade-overview.html">Next</a></td></tr></table><hr></div><div class="chapter"><div class="titlepage"><div><div><h2 class="title"><a name="upgrade"></a>Chapter 5. Upgrading</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="sect1"><a href="upgrade-overview.html">Overview</a></span></dt><dt><span class="sect1"><a href="upgrade-4.5-to-4.6.html">Upgrading 4.5 or higher to 4.6.3</a></span></dt><dt><span class="sect1"><a href="upgrade-4.6.3-to-5.html">Upgrading OpenACS 4.6.3 to 5.0</a></span></dt><dt><span class="sect1"><a href="upgrade-5-0-dot.html">Upgrading an OpenACS 5.0.0 or greater installation</a></span></dt><dt><span class="sect1"><a href="upgrade-openacs-files.html">Upgrading the OpenACS files</a></span></dt><dt><span class="sect1"><a href="upgrade-supporting.html">Upgrading Platform components</a></span></dt></dl></div> + + <span style="color: red"><authorblurb> + <p>by <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">Joel Aufrecht</a></p> + </authorblurb></span> + + + + + + + +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="how-do-I.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="upgrade-overview.html">Next</a></td></tr><tr><td width="40%" align="left">How Do I? </td><td width="20%" align="center"><a accesskey="u" href="acs-admin.html">Up</a></td><td width="40%" align="right"> Overview</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/uptime.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/uptime.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/uptime.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/uptime.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -11,7 +11,7 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="uptime" id="uptime"></a>External uptime validation</h2></div></div></div><p>The <a class="ulink" href="http://uptime.openacs.org/uptime/" target="_top">OpenACS uptime site</a> can monitor your site and send you an email whenever your site fails to respond. If you test -the url <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>/SYSTEM/dbtest.tcl</code>, +the url <code class="computeroutput">http://<em class="replaceable"><code>yourserver.test</code></em>/SYSTEM/dbtest.tcl</code>, you should get back the string <code class="computeroutput">success</code>.</p> </div> <include src="/packages/acs-core-docs/lib/navfooter" Index: openacs-4/packages/acs-core-docs/www/uptime.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/uptime.html,v diff -u -r1.15 -r1.16 --- openacs-4/packages/acs-core-docs/www/uptime.html 7 Aug 2017 23:47:53 -0000 1.15 +++ openacs-4/packages/acs-core-docs/www/uptime.html 8 Nov 2017 09:42:12 -0000 1.16 @@ -1,2 +1,5 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>External uptime validation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="analog-setup.html" title="Set up Log Analysis Reports"><link rel="next" href="maint-performance.html" title="Diagnosing Performance Problems"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="analog-setup.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="maint-performance.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="uptime"></a>External uptime validation</h2></div></div></div><p>The <a class="ulink" href="http://uptime.openacs.org/uptime/" target="_top">OpenACS uptime site</a> can monitor your site and send you an email whenever your site fails to respond. If you test the url <code class="computeroutput">http://<span class="replaceable"><span class="replaceable">yourserver.test</span></span>/SYSTEM/dbtest.tcl</code>, you should get back the string <code class="computeroutput">success</code>.</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analog-setup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maint-performance.html">Next</a></td></tr><tr><td width="40%" align="left">Set up Log Analysis Reports </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Diagnosing Performance Problems</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>External uptime validation</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="maintenance-web.html" title="Chapter 6. Production Environments"><link rel="previous" href="analog-setup.html" title="Set up Log Analysis Reports"><link rel="next" href="maint-performance.html" title="Diagnosing Performance Problems"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="analog-setup.html">Prev</a> </td><th width="60%" align="center">Chapter 6. Production Environments</th><td width="20%" align="right"> <a accesskey="n" href="maint-performance.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="uptime"></a>External uptime validation</h2></div></div></div> + + <p>The <a class="ulink" href="http://uptime.openacs.org/uptime/" target="_top">OpenACS uptime site</a> can monitor your site and send you an email whenever your site fails to respond. If you test the url <code class="computeroutput">http://<em class="replaceable"><code>yourserver.test</code></em>/SYSTEM/dbtest.tcl</code>, you should get back the string <code class="computeroutput">success</code>.</p> + </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="analog-setup.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="maint-performance.html">Next</a></td></tr><tr><td width="40%" align="left">Set up Log Analysis Reports </td><td width="20%" align="center"><a accesskey="u" href="maintenance-web.html">Up</a></td><td width="40%" align="right"> Diagnosing Performance Problems</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/variables.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.adp,v diff -u -r1.2 -r1.3 --- openacs-4/packages/acs-core-docs/www/variables.adp 7 Aug 2017 23:47:53 -0000 1.2 +++ openacs-4/packages/acs-core-docs/www/variables.adp 8 Nov 2017 09:42:12 -0000 1.3 @@ -11,15 +11,15 @@ <div class="titlepage"><div><div><h2 class="title" style="clear: both"> <a name="variables" id="variables"></a>Variables</h2></div></div></div><div class="sect2"> <div class="titlepage"><div><div><h3 class="title"> -<a name="variables-datetime" id="variables-datetime"></a>Date and Time Variables</h3></div></div></div><div class="authorblurb"> -<div class="cvstag">($‌Id: variables.xml,v 1.3 2006/07/17 05:38:37 -torbenb Exp $)</div><p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">joel\@aufrecht.org</a> +<a name="variables-datetime" id="variables-datetime"></a>Date and Time Variables</h3></div></div></div><span style="color: red"><authorblurb></span><p><span style="color: red"><span class="cvstag">($‌Id: +variables.xml,v 1.3 2006/07/17 05:38:37 torbenb Exp +$)</span></span></p><p>By <a class="ulink" href="mailto:joel\@aufrecht.org" target="_top">joel\@aufrecht.org</a> </p> -OpenACS docs are written by the named authors, and may be edited by -OpenACS documentation staff.</div><p>Starting with OpenACS 5.0 and the introduction of acs-lang, we +</authorblurb> +<p>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 <a class="ulink" href="/api-doc/proc-view?proc=lc%5ftime%5ffmt" target="_top">lc_time_fmt</a> to format it for display.</p><div class="example"> -<a name="idp140592120153288" id="idp140592120153288"></a><p class="title"><strong>Example 12.1. Getting datetime from +<a name="idp140623173823464" id="idp140623173823464"></a><p class="title"><strong>Example 12.1. Getting datetime from the database ANSI-style</strong></p><div class="example-contents"><pre class="programlisting"> 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/variables.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/variables.html,v diff -u -r1.31 -r1.32 --- openacs-4/packages/acs-core-docs/www/variables.html 7 Aug 2017 23:47:53 -0000 1.31 +++ openacs-4/packages/acs-core-docs/www/variables.html 8 Nov 2017 09:42:12 -0000 1.32 @@ -1,15 +1,30 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Variables</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="next" href="automated-testing-best-practices.html" title="Automated Testing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="automated-testing-best-practices.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="variables"></a>Variables</h2></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="variables-datetime"></a>Date and Time Variables</h3></div></div></div><div class="authorblurb"><div class="cvstag">($Id$)</div><p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">joel@aufrecht.org</a></p> - OpenACS docs are written by the named authors, and may be edited - by OpenACS documentation staff. - </div><p>Starting with OpenACS 5.0 and the introduction of acs-lang, +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Variables</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="eng-standards-plsql.html" title="PL/SQL Standards"><link rel="next" href="automated-testing-best-practices.html" title="Automated Testing"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="automated-testing-best-practices.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="variables"></a>Variables</h2></div></div></div> + + +<div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="variables-datetime"></a>Date and Time Variables</h3></div></div></div> + +<span style="color: red"><authorblurb> +<p><span class="cvstag">($Id$)</span></p> + +<p>By <a class="ulink" href="mailto:joel@aufrecht.org" target="_top">joel@aufrecht.org</a></p> +</authorblurb></span> + + <p>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 <a class="ulink" href="/api-doc/proc-view?proc=lc%5ftime%5ffmt" target="_top">lc_time_fmt</a> to format it for display.</p><div class="example"><a name="idp140592120153288"></a><p class="title"><b>Example 12.1. Getting datetime from the database ANSI-style</b></p><div class="example-contents"><pre class="programlisting">db_multirow -extend { mydate_pretty } { + ANSI format and then using <a class="ulink" href="/api-doc/proc-view?proc=lc%5ftime%5ffmt" target="_top">lc_time_fmt</a> to format it for display.</p> + <div class="example"><a name="idp140623173823464"></a><p class="title"><b>Example 12.1. Getting datetime from the database ANSI-style</b></p><div class="example-contents"> + + <pre class="programlisting">db_multirow -extend { mydate_pretty } { select to_char(mydate, 'YYYY-MM-DD HH24:MI:SS') as mydate_ansi, ... ... } { set mydate_ansi [lc_time_system_to_conn $mydate_ansi] set mydate_pretty [lc_time_fmt $mydate_ansi "%x %X"] } -</pre></div></div><br class="example-break"></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="automated-testing-best-practices.html">Next</a></td></tr><tr><td width="40%" align="left">PL/SQL Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Automated Testing</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> +</pre> + </div></div><br class="example-break"> + +</div> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="eng-standards-plsql.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="automated-testing-best-practices.html">Next</a></td></tr><tr><td width="40%" align="left">PL/SQL Standards </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Automated Testing</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/win2k-installation.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/win2k-installation.html,v diff -u -r1.50 -r1.51 --- openacs-4/packages/acs-core-docs/www/win2k-installation.html 7 Aug 2017 23:47:53 -0000 1.50 +++ openacs-4/packages/acs-core-docs/www/win2k-installation.html 8 Nov 2017 09:42:12 -0000 1.51 @@ -1,5 +1,9 @@ <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'> -<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Installation Guide for Windows</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="openacs.html" title="Install OpenACS 5.9.0"><link rel="next" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="win2k-installation"></a>OpenACS Installation Guide for Windows</h2></div></div></div><p>A binary version of OpenACS and NaviServer is maintained by Maurizio +<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>OpenACS Installation Guide for Windows</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.2"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="complete-install.html" title="Chapter 3. Complete Installation"><link rel="previous" href="openacs.html" title="Install OpenACS 5.9.0"><link rel="next" href="mac-installation.html" title="OpenACS Installation Guide for Mac OS X"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Complete Installation</th><td width="20%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="win2k-installation"></a>OpenACS Installation Guide for Windows</h2></div></div></div> + + + <p>A binary version of OpenACS and NaviServer is maintained by Maurizio Martignano and is available from <a class="ulink" href="http://www.spazioit.com/pages_en/sol_inf_en/windows-openacs_en/" target="_top">Spazio IT</a> - </p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Install OpenACS 5.9.0 </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Mac OS X</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> + </p> +</div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="openacs.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="mac-installation.html">Next</a></td></tr><tr><td width="40%" align="left">Install OpenACS 5.9.0 </td><td width="20%" align="center"><a accesskey="u" href="complete-install.html">Up</a></td><td width="40%" align="right"> OpenACS Installation Guide for Mac OS X</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html> Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml,v diff -u -r1.30 -r1.31 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 7 Aug 2017 23:47:55 -0000 1.30 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 8 Nov 2017 09:42:12 -0000 1.31 @@ -73,7 +73,7 @@ [root tmp]# </screen> <para>Debian users:</para> <screen><action>apt-get install psgml</action></screen> - <para>Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For debian, <computeroutput>apt-get install nxml</computeroutput>.</para> + <para>Note: The new nxml mode for emacs, when used in combination with psgml, provides a pretty good set of functionality that makes DocBook editing much less painless. In particular, nxml does syntax testing in real-time so that you can see syntax errors immediately instead of in the output of the xsltproc hours or days later. For Debian, <computeroutput>apt-get install nxml</computeroutput>.</para> </sect1> <sect1 id="install-daemontools"> @@ -206,143 +206,25 @@ </sect1> <sect1 id="install-qmail"> <title>Install qmail (OPTIONAL)</title> - <para>Qmail is a Mail Transfer Agent. It handles incoming and + <para>Qmail is a secure, reliable, efficient, simple Mail Transfer Agent. It handles incoming and outgoing mail. Install qmail if you want your OpenACS server to send and receive mail, and you don't want to use an alternate MTA.</para> - <para>Red Hat 9: all djb tools (qmail, daemontools, ucspi) will - fail to compile in Red Hat 9 because of changes to glibc (<ulink url="http://moni.csi.hu/pub/glibc-2.3.1/">patches</ulink>)</para> + <orderedlist> <listitem> <formalpara> - <title>Install ucspi</title> - <para>This program handles incoming tcp connections. - <link linkend="ucspi-download">Download ucspi</link> and install it.</para> - </formalpara> - <screen>[root root]# <userinput>cd /usr/local/src</userinput> -[root src]# <userinput>wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz</userinput> -[root src]# <userinput>tar xzf ucspi-tcp-0.88.tar.gz</userinput> -<action>cd /usr/local/src -wget http://cr.yp.to/ucspi-tcp/ucspi-tcp-0.88.tar.gz -tar xzf ucspi-tcp-0.88.tar.gz </action></screen> - <para>Red Hat 9 only</para> -<screen><action>wget http://moni.csi.hu/pub/glibc-2.3.1/ucspi-tcp-0.88.errno.patch -cd ucspi-tcp-0.88 -patch -p1 <../ucspi-tcp-0.88.errno.patch -cd ..</action></screen> - <para>All platforms continue:</para> -<screen>[root src]# <userinput>cd ucspi-tcp-0.88</userinput> -[root ucspi-tcp-0.88]#<userinput> make</userinput> -( cat warn-auto.sh; \ -echo 'main="$1"; shift'; \<emphasis>(many lines omitted)</emphasis> -./compile instcheck.c -./load instcheck hier.o auto_home.o unix.a byte.a -[root ucspi-tcp-0.88]# <userinput>make setup check</userinput> -./install -./instcheck -[root ucspi-tcp-0.88]# -<action> -cd ucspi-tcp-0.88 -make -make setup check</action></screen> - <para>Verify that ucspi-tcp was installed successfully by -running the tcpserver program which is part of ucspi-tcp:</para> - <screen>[root ucspi-tcp-0.88]# <userinput>tcpserver</userinput> -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]# -</screen> - <para><indexterm> - <primary>qmail</primary> - <secondary>rcpthosts error message</secondary> - </indexterm> -(I'm not sure if this next step is 100% necessary, but when I skip it -I get problems. If you get the error <computeroutput>553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1)</computeroutput> then you need to do this.) AOLserver sends outgoing mail via the ns_sendmail -command, which pipes a command to the sendmail executable. Or, in our -case, the qmail replacement wrapper for the sendmail executable. In -some cases, though, the outgoing mail requset is apparently sent -through tcp/ip, so that it comes to qmail from 127.0.0.1 (a special IP -address that means the local machine - the "loopback" interface). -Unless this mail is addressed to the same machine, qmail thinks that -it's an attempt to relay mail, and rejects it. So these two commands -set up an exception so that any mail sent from 127.0.0.1 is allowed to -send outgoing mail.</para> - <screen>[root ucspi-tcp-0.88]# <userinput>cp /tmp/&tarballpath;/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp</userinput> -[root ucspi-tcp-0.88]# <userinput>tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp</userinput> -<action>cp /tmp/&tarballpath;/packages/acs-core-docs/www/files/tcp.smtp.txt /etc/tcp.smtp -tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp </action></screen> - </listitem> - <listitem> - <formalpara> - <title>Install Qmail</title> - <indexterm> - <primary>qmail</primary> - <secondary>installation</secondary> - </indexterm> - <para></para> - </formalpara> - <para><link linkend="ucspi-download">Download qmail</link>, - set up the standard supporting users and build the binaries:</para> - <screen>[root root]# <userinput>cd /usr/local/src</userinput> -[root src]# <userinput>wget http://www.qmail.org/netqmail-1.04.tar.gz</userinput> -[root src]# <userinput>tar xzf netqmail-1.04.tar.gz</userinput> ---15:04:11-- http://www.qmail.org/netqmail-1.04.tar.gz - => `netqmail-1.04.tar.gz' -Resolving www.qmail.org... done. -Connecting to www.qmail.org[192.203.178.37]:80... connected. -HTTP request sent, awaiting response... 200 OK -Length: 242,310 [application/x-gunzip] - -88% [===============================> ] 214,620 22.93K/s ETA 00:01 - -15:04:21 (24.04 KB/s) - `netqmail-1.04.tar.gz' saved [242310/242310] - -[root src]# <userinput>mkdir /var/qmail</userinput> -[root src]#<userinput> groupadd nofiles</userinput> -[root src]# <userinput>useradd -g nofiles -d /var/qmail/alias alias</userinput> -[root src]# <userinput>useradd -g nofiles -d /var/qmail qmaild</userinput> -[root src]# <userinput>useradd -g nofiles -d /var/qmail qmaill</userinput> -[root src]# <userinput>useradd -g nofiles -d /var/qmail qmailp</userinput> -[root src]# <userinput>groupadd qmail</userinput> -[root src]# <userinput>useradd -g qmail -d /var/qmail qmailq</userinput> -[root src]# <userinput>useradd -g qmail -d /var/qmail qmailr</userinput> -[root src]# <userinput>useradd -g qmail -d /var/qmail qmails</userinput> -[root src]# <userinput>cd netqmail-1.04</userinput> -[root netqmail-1.04]# <userinput>./collate.sh</userinput> - -You should see 7 lines of text below. If you see anything -else, then something might be wrong. -[1] Extracting qmail-1.03... -[2] Patching qmail-1.03 into netqmail-1.04. Look for errors below: - 20 -[4] The previous line should say 20 if you used GNU patch. -[5] Renaming qmail-1.03 to netqmail-1.04... -[6] Continue installing qmail using the instructions found at: -[7] http://www.lifewithqmail.org/lwq.html#installation -[root netqmail-1.04]# <userinput>cd netqmail-1.04</userinput> -[root netqmail-1.04]# <userinput>make setup check</userinput> -( cat warn-auto.sh; \ -echo CC=\'`head -1 conf-cc`\'; \<emphasis>(many lines omitted)</emphasis> -./install -./instcheck -<action>cd /usr/local/src -wget http://www.qmail.org/netqmail-1.04.tar.gz -tar xzf netqmail-1.04.tar.gz -mkdir /var/qmail -groupadd nofiles -useradd -g nofiles -d /var/qmail/alias alias -useradd -g nofiles -d /var/qmail qmaild -useradd -g nofiles -d /var/qmail qmaill -useradd -g nofiles -d /var/qmail qmailp -groupadd qmail -useradd -g qmail -d /var/qmail qmailq -useradd -g qmail -d /var/qmail qmailr -useradd -g qmail -d /var/qmail qmails -cd netqmail-1.04 -./collate.sh -cd netqmail-1.04 -make setup check</action></screen> - <para>Replace sendmail with qmail's wrapper.</para> + <title>Install qmail</title> + <para>QMail is available as standard Debian/Ubuntu package, + rpms for Fedora/Redhat/CenTOS are available from <ulink + url="https://en.wikipedia.org/wiki/Qmail/">QMail wiki + page</ulink></para> + </formalpara> + </listitem> + <listitem> + <formalpara> + <para>Replace sendmail with qmail's wrapper.</para> + </formalpara> <indexterm> <primary>sendmail</primary> <secondary>removing</secondary> @@ -496,510 +378,25 @@ <primary>full text search</primary> <secondary>installation</secondary> </indexterm> - <para>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 tsearch2 module form PostgreSQL - contrib. This is included with the PostgreSQL full source - distribution. It is also available with the PostgreSQL contrib - package provided by most distribution packages. On debian it is - called postgresql-contrib.</para> - <orderedlist> - <listitem> - <para>For PostgreSQL 7.3 or 7.4, download the - http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz - tsearch2 patch - to correctly restore from a pg_dump backup. If you installed - tsearch2 from a package, you can use the - http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql - regprocedure script to update the database after tsearch2 is - installed into it. TODO link to section describing how to fix - an existing tsearch2 database with this patch.</para> - </listitem> - <listitem> - <para>As of May 9, 2004 there is a source patch available - for - tsearch2. The patch provides changes to the pg_ts_ - configuration - tables to allow for easy dump and restore of a database - containing - tsearch2. The patch is available here : <ulink url=" - http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz"> - [http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz]</ulink></para> + <para>In earlier versions of PostgreSQL (7.4), tsearch2 was a contrib + module. With PostgreSQL 9.*, it was included in the standard + PostgreSQL package with minor naming changes (e.g. the function + "rank" became "ts_rank"). PostgreSQL 9 included a backward + compatibility module named "tsearch2". Newer OpenACS + installations (at least 5.9.0 or newer) do not + need the compatiblity package. In PostgreSQL 10 the tsearch2 + compatiblity package has been removed. + </para> + <para> + On new OpenACS installations for PostgreSQL, install the + tsearch2-driver package via "/acs-admin/install/" and mount the + search package under "/search" via "/admin/site-map" if + necessary. + </para> - <para>To apply this patch, download the mentioned file and - place it in your postgreSQL source tree ($PGSQL_SRC). This - patch makes the backup and restore procedures very - simple.</para> - <screen> - [postgres pgsql]$ <userinput>cd /tmp</userinput> - [postgres tmp]$ <userinput>wget http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_7.4.patch.gz</userinput> - [postgres pgsql]$ <userinput>cd /usr/local/src/postgresql-7.4.5/</userinput> - [postgres postgresql-7.4.5] <userinput>gunzip /tmp/regprocedure_7.4.patch.gz</userinput> - [postgres postgresql-7.4.5] <userinput>patch -b -p1 < regprocedure_7.4.patch</userinput> - </screen> - <para>If you have a working version of tsearch2 in your - database, you - do not need to re-install the tsearch2 module. Just - apply the patch - and run make. This patch only affects the tsearch2.sql - file. You - can run the SQL script found : <ulink url=" - http://www.sai.msu.su/~megera/postgres/gist/tsearch/V2/regprocedure_update.sql"> - [right here]</ulink> This script will make the - modifications found in - the patch, and update the fields from the existing - data. From this - point on, you can dump and restore the database in a - normal - fashion. Without this patch, you must follow the - instructions later - in this document for backup and restore.</para> - <para>This patch is only needed for tsearch2 in PostgreSQL - versions - 7.3.x and 7.4.x. The patch has been applied to the - sources for - 8.0.</para> - </listitem> - <listitem> - <para>Install Tsearch2. This is a PostgreSQL module - that the tsearch2-driver OpenACS package requires. These - instructions assume you are using the latest point - release of PostgreSQL 7.4.5.</para> - <screen>[root root]# <userinput>su - postgres</userinput> -[postgres pgsql]$ <userinput>cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2/</userinput> -[postgres tsearch2]$ <userinput>make</userinput> -[postgres tsearch2]$ <userinput>make install</userinput> -mkdir /usr/local/pgsql/share/contrib -mkdir /usr/local/pgsql/doc/contrib -(2 lines omitted) -/bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so -[postgres tsearch]$ <userinput>exit</userinput> -logout - -[root root]# -<action>su - postgres -cd /usr/local/src/postgresql-7.4.5/contrib/tsearch2 -make -make install -exit</action></screen> - </listitem> - </orderedlist> </sect2> - - <sect2 id="install-fts-engine"> - <title>Install Full Text Search Engine Package in OpenACS</title> - <orderedlist> - <listitem> - <para>Click <computeroutput><guilabel>Admin</guilabel></computeroutput> on the top of the default home page. If prompted, log in with the account and password you entered during install.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install -software</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install -new service</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the - <computeroutput><guilabel>Install</guilabel></computeroutput> - link next to Tsearch2 Driver. If you have installed tsearch2 - into your PostgreSQL database, the installer will - automatically enable tsearch in your OpenACS database instance.</para> - </listitem> - - <listitem><para>Restart the service.</para> -<screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</screen></listitem> - - <listitem><para>Wait a minute, then browse back to the home page.</para> - </listitem> - - <listitem><para>Click on <computeroutput><guilabel>Admin</guilabel></computeroutput> on the top of the screen.</para> - </listitem> - - <listitem><para>Click on <computeroutput><guilabel>Main Site Administration</guilabel></computeroutput> in the "Subsite Administration" section.</para> - </listitem> - - <listitem><para>Click on <computeroutput><guilabel>Site Map</guilabel></computeroutput> in the "Advanced Features" section.</para> - </listitem> - - <listitem> - <para>Mount the Search interface in the site map.</para> - <orderedlist> - <listitem><para>Click the -<computeroutput><guilabel>new sub folder</guilabel></computeroutput> link on the -Main Site line. </para></listitem> - <listitem><para>Type <userinput>search</userinput> -and click <computeroutput><guibutton>New</guibutton></computeroutput>. </para></listitem> - <listitem><para>Click the <computeroutput><guilabel>new -application</guilabel></computeroutput> link on the <computeroutput><guilabel>search</guilabel></computeroutput> - line. </para></listitem> - <listitem><para>Type <userinput>search</userinput> -where it says -<computeroutput><guilabel>untitled</guilabel></computeroutput>, choose -<computeroutput><guilabel>search</guilabel></computeroutput> from the -drop-down list, and click -<computeroutput><guibutton>New</guibutton></computeroutput>. -</para></listitem> - <listitem><para>Click the -<computeroutput><guilabel>Parameters</guilabel></computeroutput> link - next to the Search package istance.</para></listitem> - <listitem><para>Type <userinput>tsearch2-driver</userinput> -where it says -<computeroutput><guilabel>openfts-driver</guilabel></computeroutput> - in the - <computeroutput><guilabel>FtsEngineDriver</guilabel></computeroutput> parameter. -</para></listitem> - - - </orderedlist> - </listitem> - <listitem> - <para>Restart the service.</para> - <screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</screen> - </listitem> - <listitem><para>Wait a minute, then click on <computeroutput><guilabel>Main Site</guilabel></computeroutput> at the top of the page.</para> - </listitem> - - </orderedlist> - </sect2> - <sect2 id="install-fts-content-provider"> - <title>Enable Full Text Search in packages</title> - <para>Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package</para> - <orderedlist> - <listitem> - <para>Install the package. - <orderedlist> - <listitem> - <para>Click <computeroutput><guilabel>Admin</guilabel></computeroutput> on the top of the default home page. If prompted, log in with the account and password you entered during install.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install - software</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install - new application</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install</guilabel></computeroutput> link next to Weblogger.</para> - </listitem> - <listitem> - <para>Install all required packages as well (always say okay until you shall restart the server)</para> - </listitem> - </orderedlist> - </para> - </listitem> - <listitem> - <para>Load the service contracts datamodell and enable the service contract</para> - <screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>cd packages/lars-blogger/sql/postgresql</userinput> -[$OPENACS_SERVICE_NAME postgresql]$ psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f lars-blogger-sc-create.sql</screen> -<para>Note: Usually this script is called <replaceable>package_name</replaceable>-sc-create.sql</para> - </listitem> - <listitem> - <para>Restart the service.</para> - <screen>[$OPENACS_SERVICE_NAME postgresql]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> - [$OPENACS_SERVICE_NAME postgresl]$</screen> - </listitem> - </orderedlist> - <para>If you are lucky, Full Text Search is enabled now, if not consult <ulink url="http://openacs.org/forums/message-view?message_id=154759">http://openacs.org/forums/message-view?message_id=154759</ulink>. This link also contains some hints on how to make sure it is enabled.</para> - </sect2> </sect1> - - <sect1 id="install-full-text-search-openfts"> - <title>Install Full Text Search using OpenFTS (deprecated see tsearch2)</title> - <authorblurb> - <para>By <ulink url="mailto:joel@aufrecht.org">Joel Aufrecht</ulink> and <ulink url="mailto:openacs@sussdorff.de">Malte Sussdorff</ulink></para> - </authorblurb> - <para>OpenFTS and tsearch1 use is deprecated in favor of - Tsearch2. See - <xref linkend="install-full-text-search-tsearch2"></xref>. Tsearch2 is much easier to install, requiring only - compilation of one module from PostgreSQL contrib, with an - automated install process using the tsearch2-driver package.</para> - - <sect2 id="install-openfts"> - <title>Install OpenFTS module</title> - <indexterm> - <primary>full text search</primary> - <secondary>installation</secondary> - </indexterm> - <para>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 <link linkend="openfts-download">openfts - tarball</link> in <computeroutput>/tmp</computeroutput>.</para> - <orderedlist> - <listitem> - <para>Install Tsearch. This is a PostgreSQL module that - OpenFTS requires.</para> - <screen>[root root]# <userinput>su - postgres</userinput> -[postgres pgsql]$ <userinput>cd /usr/local/src/postgresql-7.3.4/contrib/tsearch/</userinput> -[postgres tsearch]$ <userinput>make</userinput> -sed 's,MODULE_PATHNAME,$libdir/tsearch,g' tsearch.sql.in >tsearch.sql -/usr/bin/flex -8 -Ptsearch_yy -o'parser.c' parser.l<emphasis>(many lines omitted)</emphasis> -rm -f libtsearch.so -ln -s libtsearch.so.0.0 libtsearch.so -[postgres tsearch]$ <userinput>make install</userinput> -mkdir /usr/local/pgsql/share/contrib -mkdir /usr/local/pgsql/doc/contrib -(2 lines omitted) -/bin/sh ../../config/install-sh -c -m 755 libtsearch.so.0.0 /usr/local/pgsql/lib/tsearch.so -[postgres tsearch]$ <userinput>exit</userinput> -logout -[root root]# -<action>su - postgres -cd /usr/local/src/postgresql-7.3.4/contrib/tsearch -make -make install -exit</action></screen> - </listitem> - <listitem> - <para>Unpack the OpenFTS tarball and compile and install - the driver.</para> - <screen>[root root]# <userinput>cd /usr/local/src</userinput> -[root src]# <userinput>tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz</userinput> -[root src]# <userinput>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/</userinput> -[root Search-OpenFTS-tcl-0.3.2]# <userinput>./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/</userinput> -checking prefix... /usr/local -checking for gcc... gcc -<emphasis>(many lines omitted)</emphasis> -configure: creating ./config.status -config.status: creating Makefile.global -[root Search-OpenFTS-tcl-0.3.2]#<userinput> make</userinput> -(cd parser; make all) -make[1]: Entering directory `/usr/local/src/Search-OpenFTS-tcl-0.3.2/parser' -<emphasis>(many lines omitted)</emphasis> -packages provided were {Lingua::Stem::Snowball 0.3.2} -processed fts_base_snowball.tcl -[root Search-OpenFTS-tcl-0.3.2]# <userinput>cd aolserver</userinput> -[root aolserver]# <userinput>make</userinput> -gcc -c -fPIC -DPACKAGE=\"OPENFTS\" -DVERSION=\"0.3.2\" -DHAVE_UNISTD_H=1 -DSTDC_HEADERS=1 -DHAVE_SYS_TYPES_H=1 -DHAVE_SYS_STAT_H=1 -DHAVE_STDLIB_H=1 -DHAVE_STR -<emphasis>(many lines omitted)</emphasis> -n_stem.o italian_stem.o norwegian_stem.o portuguese_stem.o russian_stem.o nsfts.o -o nsfts.so -[root aolserver]# <userinput>cp nsfts.so /usr/local/aolserver/bin/</userinput> -[root aolserver]# -<action>cd /usr/local/src -tar xzf /tmp/Search-OpenFTS-tcl-0.3.2.tar.gz -cd /usr/local/src/Search-OpenFTS-tcl-0.3.2/ -./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver --with-tcl=/usr/lib/ -make -cd AOLserver -make -cp nsfts.so /usr/local/aolserver/bin -</action></screen> - </listitem> - <listitem> - <para>Build some supplemental modules.</para> - <screen>[root aolserver]# <userinput>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2</userinput> -[root Search-OpenFTS-tcl-0.3.2]# <userinput>cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib</userinput> -[root Search-OpenFTS-tcl-0.3.2]# <userinput>cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts</userinput> -[root pgsql_contrib_openfts]#<userinput> make</userinput> -sed 's,MODULE_PATHNAME,$libdir/openfts,g' openfts.sql.in >openfts.sql -gcc -O2 -Wall -Wmissing-prototypes -Wmissing-declarations -fpic -I. -I../../src/include -c -o openfts.o openfts.c -gcc -shared -o openfts.so openfts.o -rm openfts.o -[root pgsql_contrib_openfts]# <userinput>su postgres</userinput> -[postgres pgsql_contrib_openfts]$ <userinput>make install</userinput> -/bin/sh ../../config/install-sh -c -m 644 openfts.sql /usr/local/pgsql/share/contrib -/bin/sh ../../config/install-sh -c -m 755 openfts.so /usr/local/pgsql/lib -/bin/sh ../../config/install-sh -c -m 644 ./README.openfts /usr/local/pgsql/doc/contrib -[postgres pgsql_contrib_openfts]$<userinput> exit</userinput> -[root pgsql_contrib_openfts]# -<action>cd /usr/local/src/Search-OpenFTS-tcl-0.3.2 -cp -r pgsql_contrib_openfts /usr/local/src/postgresql-7.3.4/contrib -cd /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts -make -su postgres -make install -exit</action></screen> - </listitem> - </orderedlist> - </sect2> - - <sect2 id="install-openfts-postgres"> - <title>Install OpenFTS prerequisites in PostgreSQL instance</title> - <indexterm> - <primary>full text search</primary> - <secondary>installation</secondary> - </indexterm> - <para>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 <link - linkend="install-openfts">install</link> the PostgreSQL - OpenFTS module and prerequisites.)</para> - <screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>/usr/local/pgsql/bin/psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql</userinput> -BEGIN -CREATE -<emphasis>(many lines omitted)</emphasis> -INSERT 0 1 -COMMIT -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>/usr/local/pgsql/bin/psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql</userinput> -CREATE -CREATE -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ -<action>/usr/local/pgsql/bin/psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql -/usr/local/pgsql/bin/psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql</action></screen> - <note> - <para> - If you get the error - <computeroutput>ERROR: could not access file "$libdir/tsearch": no such file or directory</computeroutput> - It is probably because PostgreSQL's libdir configuration variable points to a diffent directory than where tsearch is. - You can find out where PostgreSQL expects to find tsearch via - <screen><userinput>pg_config --pkglibdir</userinput></screen> - </para> - </note> - </sect2> - - <sect2 id="enable-openfts"> - <title>Enable OpenFTS in config.tcl</title> - <para>If you have <link linkend="install-openfts">installed OpenFTS</link>, you can enable it for this service. Uncomment this line from <computeroutput>config.tcl</computeroutput>. (To uncomment a line in a Tcl file, remove the <computeroutput>#</computeroutput> at the beginning of the line.)</para> - <programlisting>#ns_param nsfts ${bindir}/nsfts.so</programlisting> - </sect2> - - <sect2 id="install-fts-engine-openfts"> - <title>Install Full Text Search Engine</title> - <orderedlist> - <listitem> - <para>Click <computeroutput><guilabel>Admin</guilabel></computeroutput> on the top of the default home page. If prompted, log in with the account and password you entered during install.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install -software</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install -new service</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install</guilabel></computeroutput> link next to OpenFTS Driver.</para> - </listitem> - - <listitem><para>Restart the service.</para> -<screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</screen></listitem> - - <listitem><para>Wait a minute, then browse back to the home page.</para> - </listitem> - - <listitem><para>Click on <computeroutput><guilabel>Admin</guilabel></computeroutput> on the top of the screen.</para> - </listitem> - - <listitem><para>Click on <computeroutput><guilabel>Main Site Administration</guilabel></computeroutput> in the "Subsite Administration" section.</para> - </listitem> - - <listitem><para>Click on <computeroutput><guilabel>Site Map</guilabel></computeroutput> in the "Advanced Features" section.</para> - </listitem> - - <listitem> - <para>Mount the OpenFTS Full Text Search Engine in the site map.</para> - <orderedlist> - <listitem><para>Click the <computeroutput><guilabel>new sub folder</guilabel></computeroutput> link on the "/" line, the first line under Main Site:/.</para></listitem> - <listitem><para>Type <userinput>openfts</userinput> -and click <computeroutput><guibutton>New</guibutton></computeroutput>.</para></listitem> - <listitem><para>On the new <computeroutput><guilabel>openfts</guilabel></computeroutput> line, click the <computeroutput><guilabel>mount</guilabel></computeroutput> link.</para></listitem> - <listitem><para>Click <computeroutput><guilabel>OpenFTS -Driver</guilabel></computeroutput>.</para></listitem> - <listitem><para>On the <computeroutput><guilabel>openfts</guilabel></computeroutput> line, click <computeroutput><guilabel>set parameters</guilabel></computeroutput>.</para> - </listitem> - <listitem><para>Change <computeroutput><guilabel>openfts_tcl_src_path</guilabel></computeroutput> to <userinput>/usr/local/src/Search-OpenFTS-tcl-0.3.2/</userinput> and click <computeroutput><guibutton>Set Parameters</guibutton></computeroutput> - </para> - </listitem> - </orderedlist> - </listitem> - <listitem> - <para>Mount the Search interface in the site map.</para> - <orderedlist> - <listitem><para>Click the -<computeroutput><guilabel>new sub folder</guilabel></computeroutput> link on the -Main Site line. </para></listitem> - <listitem><para>Type <userinput>search</userinput> -and click <computeroutput><guibutton>New</guibutton></computeroutput>. </para></listitem> - <listitem><para>Click the <computeroutput><guilabel>new -application</guilabel></computeroutput> link on the <computeroutput><guilabel>search</guilabel></computeroutput> - line. </para></listitem> - <listitem><para>Type <userinput>search</userinput> -where it says -<computeroutput><guilabel>untitled</guilabel></computeroutput>, choose -<computeroutput><guilabel>search</guilabel></computeroutput> from the -drop-down list, and click -<computeroutput><guibutton>New</guibutton></computeroutput>. -</para></listitem> - </orderedlist> - </listitem> - <listitem> - <para>Restart the service.</para> - <screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</screen> - </listitem> - <listitem><para>Wait a minute, then click on <computeroutput><guilabel>Main Site</guilabel></computeroutput> at the top of the page.</para> - </listitem> - <listitem> - <para>Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS.</para> - <para>Near the bottom of the page, click on the <computeroutput><guilabel>OpenFTS Driver</guilabel></computeroutput> link. Click on <computeroutput><guilabel>Administration</guilabel></computeroutput>. -Click on <computeroutput><guilabel>Initialize OpenFTS Engine</guilabel></computeroutput>. -Click <computeroutput><guibutton>Initialize OpenFTS Engine</guibutton></computeroutput>. </para> - </listitem> - <listitem> - <para>Add the FTS Engine service contract</para> - <orderedlist> - <listitem><para>Click on the <computeroutput><guilabel>DevAdmin</guilabel></computeroutput>. </para></listitem> - <listitem><para>Click on the <computeroutput><guilabel>Service Contract</guilabel></computeroutput> link. </para></listitem> - <listitem><para>On the <computeroutput><guilabel>FtsEngineDriver</guilabel></computeroutput> -line, click -<computeroutput><guilabel>Install</guilabel></computeroutput>. -</para></listitem> - </orderedlist> - </listitem> - <listitem> - <para>Restart the service.</para> - <screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> -[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$</screen> - </listitem> - </orderedlist> - </sect2> - <sect2 id="install-fts-content-provider-openfts"> - <title>Enable Full Text Search in packages</title> - <para>Enabling Full Text Search in packages at the moment is not trivial. It involves a couple of steps, which I will illustrate taking lars-blogger as an example package</para> - <orderedlist> - <listitem> - <para>Install the package. - <orderedlist> - <listitem> - <para>Click <computeroutput><guilabel>Admin</guilabel></computeroutput> on the top of the default home page. If prompted, log in with the account and password you entered during install.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install - software</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install - new application</guilabel></computeroutput> link.</para> - </listitem> - - <listitem><para>Click on the <computeroutput><guilabel>Install</guilabel></computeroutput> link next to Weblogger.</para> - </listitem> - <listitem> - <para>Install all required packages as well (always say okay until you shall restart the server)</para> - </listitem> - </orderedlist> - </para> - </listitem> - <listitem> - <para>Load the service contracts datamodell and enable the service contract</para> - <screen>[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ <userinput>cd packages/lars-blogger/sql/postgresql</userinput> -[$OPENACS_SERVICE_NAME postgresql]$ psql <replaceable>$OPENACS_SERVICE_NAME</replaceable> -f lars-blogger-sc-create.sql</screen> -<para>Note: Usually this script is called <replaceable>package_name</replaceable>-sc-create.sql</para> - </listitem> - <listitem> - <para>Restart the service.</para> - <screen>[$OPENACS_SERVICE_NAME postgresql]$ <userinput>svc -t /service/<replaceable>$OPENACS_SERVICE_NAME</replaceable></userinput> - [$OPENACS_SERVICE_NAME postgresl]$</screen> - </listitem> - </orderedlist> - <para>If you are lucky, Full Text Search is enabled now, if not consult <ulink url="http://openacs.org/forums/message-view?message_id=154759">http://openacs.org/forums/message-view?message_id=154759</ulink>. This link also contains some hints on how to make sure it is enabled.</para> - </sect2> - </sect1> - <sect1 id="install-nsopenssl"> <title>Install nsopenssl</title> <authorblurb>