Index: openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml,v diff -u -r1.16 -r1.17 --- openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml 11 Mar 2004 09:16:56 -0000 1.16 +++ openacs-4/packages/acs-core-docs/www/xml/releasing-openacs.xml 14 May 2004 14:10:26 -0000 1.17 @@ -25,23 +25,23 @@ .LRN: this must be repeated for .LRN modules (dotlrn-core in the dotlrn cvs tree) and for any modified modules in the .LRN prerequisites (dotlrn-prereq in openacs cvs tree). My current working model is that I bulk-update .LRN and OpenACS core but that I don't touch dotlrn-prereq modules - I just use the most recent release and it's up to individual package developers to tag and release those packages when they change. This model is already broken because following it means that dotlrn-prereqs don't get new translations. - Update /var/lib/aolserver/service0/packages/acs-core-docs/www/xml/variables.ent with the new version number. + Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/variables.ent with the new version number. - Add new section in /var/lib/aolserver/service0/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml + Add new section in /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml/for-everyone/release-notes.xml Regenerate all HTML docs - cd /var/lib/aolserver/service0/packages/acs-core-docs/www/xml + cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/xml make - Update /var/lib/aolserver/service0/readme.txt with the new version number + Update /var/lib/aolserver/$OPENACS_SERVICE_NAME/readme.txt with the new version number - Update version number in all of the core packages. Here's a bash/perl script which works but could be made easier to use. Run it from /var/lib/aolserver/service0/packages: + Update version number in all of the core packages. Here's a bash/perl script which works but could be made easier to use. Run it from /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages: #!/bin/sh # run this file from ../packages to renumber all .info version numbers @@ -73,7 +73,7 @@ Rubuild the Changelog Rebuild the Changelog. I use a tool called cvs2cl. Run this command from the package root to automatically generate a Changelog file in the same dir: - cd /var/lib/aolserver/service0 + cd /var/lib/aolserver/$OPENACS_SERVICE_NAME perl /var/tmp/cvs2cl/cvs2cl.pl -F oacs-5-0 --delta openacs-5-0-0-final:oacs-5-0 Commit changes @@ -290,7 +290,7 @@ Tag the updated work.: - cd /var/lib/aolserver/service0/packages/myfirstpackage + cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage cvs tag myfirstpackages-1-0-0-final cvs tag -F openacs-5-0-compat Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml,v diff -u -r1.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml 12 Feb 2004 13:51:42 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/cvs.xml 14 May 2004 14:10:27 -0000 1.8 @@ -23,19 +23,19 @@ Create and set permissions on a subdirectory in the local cvs repository. - [root root]# mkdir /cvsroot/service0 -[root root]# chown service0.service0 /cvsroot/service0 + [root root]# mkdir /cvsroot/$OPENACS_SERVICE_NAME +[root root]# chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAME [root root]# -mkdir /cvsroot/service0 -chown service0.service0 /cvsroot/service0 +mkdir /cvsroot/$OPENACS_SERVICE_NAME +chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /cvsroot/$OPENACS_SERVICE_NAME Add the repository location to the user environment. On some systems, you may get better results with .bash_profile instead of .bashrc. - [root root]# su - service0 -[service0 service0]$ emacs .bashrc - Put this string into /home/service0/.bashrc: + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc + Put this string into /home/$OPENACS_SERVICE_NAME/.bashrc: export CVSROOT=/cvsroot - [service0 service0]$ exit + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit logout [root root]# @@ -45,53 +45,53 @@ 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, - service0 + $OPENACS_SERVICE_NAME refers to the cvs repository to use; it uses the CVSROOT plus this string, i.e. - /cvsroot/service0. + /cvsroot/$OPENACS_SERVICE_NAME. "OpenACS" is the vendor tag, and "&cvsversiontag;" is the release tag. These tags will be useful in upgrading and branching. -m sets the version comment. - [root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs import -m "initial install" service0 OpenACS &cvsversiontag; -N service0/license.txt -N service0/readme.txt + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs import -m "initial install" $OPENACS_SERVICE_NAME OpenACS &cvsversiontag; +N $OPENACS_SERVICE_NAME/license.txt +N $OPENACS_SERVICE_NAME/readme.txt (many lines omitted) -N service0/www/SYSTEM/flush-memoized-statement.tcl +N $OPENACS_SERVICE_NAME/www/SYSTEM/flush-memoized-statement.tcl No conflicts created by this import -[service0 service0]$ exit +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]# -su - service0 -cd /var/lib/aolserver/service0 -cvs import -m "initial install" service0 OpenACS &cvsversiontag; +su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +cvs import -m "initial install" $OPENACS_SERVICE_NAME OpenACS &cvsversiontag; exit Move the original directory to a temporary location, and check out the cvs repository in its place. - [root root]# mv /var/lib/aolserver/service0 /var/tmp -[root root]# mkdir /var/lib/aolserver/service0 -[root root]# chown service0.service0 /var/lib/aolserver/service0 -[root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver -[service0 aolserver]$ cvs checkout service0 -cvs checkout: Updating service0 -U service0/license.txt + [root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME /var/tmp +[root root]# mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME +[root root]# chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /var/lib/aolserver/$OPENACS_SERVICE_NAME +[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ cvs checkout $OPENACS_SERVICE_NAME +cvs checkout: Updating $OPENACS_SERVICE_NAME +U $OPENACS_SERVICE_NAME/license.txt (many lines omitted) -U service0/www/SYSTEM/dbtest.tcl -U service0/www/SYSTEM/flush-memoized-statement.tcl -[service0 aolserver]$ exit +U $OPENACS_SERVICE_NAME/www/SYSTEM/dbtest.tcl +U $OPENACS_SERVICE_NAME/www/SYSTEM/flush-memoized-statement.tcl +[$OPENACS_SERVICE_NAME aolserver]$ exit logout [root root]# -mv /var/lib/aolserver/service0 /var/tmp -mkdir /var/lib/aolserver/service0 -chown service0.service0 /var/lib/aolserver/service0 -su - service0 +mv /var/lib/aolserver/$OPENACS_SERVICE_NAME /var/tmp +mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME +chown $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME /var/lib/aolserver/$OPENACS_SERVICE_NAME +su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver -cvs checkout service0 +cvs checkout $OPENACS_SERVICE_NAME exit Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml,v diff -u -r1.24 -r1.25 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 13 May 2004 20:24:27 -0000 1.24 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-advanced.xml 14 May 2004 14:10:27 -0000 1.25 @@ -32,13 +32,13 @@ www/doc directory. For this tutorial, you should instead install the pre-written documentation files for the tutorial app. Log in - as service0, create the standard + as $OPENACS_SERVICE_NAME, create the standard directories, and copy the prepared documentation: - [service0 service0]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/ -[service0 myfirstpackage]$ mkdir -p www/doc/xml -[service0 myfirstpackage]$ cd www/doc/xml -[service0 xml]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/myfirstpackage/* . -[service0 xml]$ + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/ +[$OPENACS_SERVICE_NAME myfirstpackage]$ mkdir -p www/doc/xml +[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www/doc/xml +[$OPENACS_SERVICE_NAME xml]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/myfirstpackage/* . +[$OPENACS_SERVICE_NAME xml]$ OpenACS uses DocBook for documentation. DocBook is an XML standard for semantic markup of documentation. That means that the tags you use indicate meaning, not intended @@ -57,7 +57,7 @@ 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: - [service0 xml]$ make + [$OPENACS_SERVICE_NAME xml]$ make cd .. ; /usr/bin/xsltproc ../../../acs-core-docs/www/xml/openacs.xsl xml/index.xml Writing requirements-introduction.html for chapter(requirements-introduction) Writing requirements-overview.html for chapter(requirements-overview) @@ -73,7 +73,7 @@ Writing admin-guide.html for chapter(admin-guide) Writing bi01.html for bibliography Writing index.html for book -[service0 xml]$ +[$OPENACS_SERVICE_NAME xml]$ Verify that the documentation was generated and reflects your changes by browsing to http://yoursite:8000/myfirstpackage/doc @@ -85,20 +85,20 @@ traverse the directory tree manually and add as you go. (More on CVS) - [service0 xml]$ cd .. -[service0 doc]$ cd .. -[service0 www]$ cd .. -[service0 myfirstpackage]$ cd .. -[service0 packages]$ cvs add myfirstpackage/ -Directory /cvsroot/service0/packages/myfirstpackage added to the repository -[service0 packages]$ cd myfirstpackage/ -[service0 myfirstpackage]$ cvs add www -Directory /cvsroot/service0/packages/myfirstpackage/www added to the repository -[service0 myfirstpackage]$ cd www -[service0 www]$ cvs add doc -Directory /cvsroot/service0/packages/myfirstpackage/www/doc added to the repository -[service0 www]$ cd doc -[service0 doc]$ cvs add * + [$OPENACS_SERVICE_NAME xml]$ cd .. +[$OPENACS_SERVICE_NAME doc]$ cd .. +[$OPENACS_SERVICE_NAME www]$ cd .. +[$OPENACS_SERVICE_NAME myfirstpackage]$ cd .. +[$OPENACS_SERVICE_NAME packages]$ cvs add myfirstpackage/ +Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage added to the repository +[$OPENACS_SERVICE_NAME packages]$ cd myfirstpackage/ +[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs add www +Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www added to the repository +[$OPENACS_SERVICE_NAME myfirstpackage]$ cd www +[$OPENACS_SERVICE_NAME www]$ cvs add doc +Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc added to the repository +[$OPENACS_SERVICE_NAME www]$ cd doc +[$OPENACS_SERVICE_NAME doc]$ cvs add * cvs add: cannot add special file `CVS'; skipping cvs add: scheduling file `admin-guide.html' for addition cvs add: scheduling file `bi01.html' for addition @@ -121,27 +121,27 @@ 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/service0/packages/myfirstpackage/www/doc/xml added to the repository +Directory /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc/xml added to the repository cvs add: use 'cvs commit' to add these files permanently -[service0 doc]$ cd xml -[service0 xml]$ cvs add Makefile index.xml +[$OPENACS_SERVICE_NAME doc]$ cd xml +[$OPENACS_SERVICE_NAME xml]$ cvs add Makefile index.xml cvs add: scheduling file `Makefile' for addition cvs add: scheduling file `index.xml' for addition cvs add: use 'cvs commit' to add these files permanently -[service0 xml]$ cd ../../.. -[service0 myfirstpackage]$ cvs commit -m "new package" +[$OPENACS_SERVICE_NAME xml]$ cd ../../.. +[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs commit -m "new package" cvs commit: Examining . cvs commit: Examining www cvs commit: Examining www/doc cvs commit: Examining www/doc/xml -RCS file: /cvsroot/service0/packages/myfirstpackage/www/doc/admin-guide.html,v +RCS file: /cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc/admin-guide.html,v done Checking in www/doc/admin-guide.html; -/cvsroot/service0/packages/myfirstpackage/www/doc/admin-guide.html,v <-- admin-guide.html +/cvsroot/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/doc/admin-guide.html,v <-- admin-guide.html initial revision: 1.1 done (many lines omitted) -[service0 myfirstpackage]$ +[$OPENACS_SERVICE_NAME myfirstpackage]$
Upgrading a local CVS repository @@ -200,11 +200,11 @@ access to data that users aren't interested in or aren't allowed to see you will need dedicated admin pages. The conventional place to put those dedicated admin pages is in the - /var/lib/aolserver/service0/packages/myfirstpackage/www/admin + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin directory. -[service0 www]$ mkdir admin -[service0 www]$ cd admin +[$OPENACS_SERVICE_NAME www]$ mkdir admin +[$OPENACS_SERVICE_NAME www]$ cd admin Even if your application doesn't need any admin pages of its own you will usually need at least one simple page with a bunch of links to existing @@ -213,7 +213,7 @@ categories. The listing below adds a link to the Parameters UI of our package. -[service0 admin]$ vi index.adp +[$OPENACS_SERVICE_NAME admin]$ vi index.adp <master> <property name="title">@title;noquote@</property> @@ -223,7 +223,7 @@ <li><a href="@parameters_url@" title="Set parameters" class="action_link">Set parameters</a></li> </ul> -[service0 admin]$ vi index.tcl +[$OPENACS_SERVICE_NAME admin]$ vi index.tcl ad_page_contract {} { } -properties { @@ -259,7 +259,7 @@ In order to display the link to the admin page only to users that have admin privileges add the following code near the top of -/var/lib/aolserver/service0/packages/myfirstpackage/www/admin/index.tcl: +/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl: @@ -275,7 +275,7 @@ In -/var/lib/aolserver/service0/packages/myfirstpackage/www/admin/index.adp put: +/var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp put: <if @admin_p@ ne nil> @@ -323,7 +323,7 @@ The way to achieve this is is to provide a link to the Category Management pages. Add the following snippet to your - /var/lib/aolserver/service0/packages/myfirstpackage/www/admin/index.tcl + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.tcl file: @@ -333,7 +333,7 @@ and the following snippet to your - /var/lib/aolserver/service0/packages/myfirstpackage/www/admin/index.adp + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www/admin/index.adp file: @@ -422,7 +422,7 @@ script execution. The database commands: - [service0@yourserver www]$ emacs note-delete.xql + [$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.xql <?xml version="1.0"?> <queryset> <fullquery name="do_delete"> @@ -437,7 +437,7 @@ </fullquery> </queryset> And the adp page: - [service0@yourserver www]$ emacs note-delete.adp + [$OPENACS_SERVICE_NAME@yourserver www]$ emacs note-delete.adp <master> <property name="title">@title@</property> <property name="context">{@title@}</property> @@ -830,15 +830,15 @@ Using .vuh files for pretty urls .Vuh files are special cases of .tcl files, used for rewriting incoming urls. We can use a vuh file to prettify the uri for our notes. Instead of note-edit?item_id=495, we can use note/495. To do this, we will need a new .vuh file for redirection and we will need to change the referring links in note-list. First, add the vuh: - [service0 service0]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/www -[service0 www]$ emacs note.vuh + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www +[$OPENACS_SERVICE_NAME www]$ emacs note.vuh Paste this into the file: example missing We parse the incoming request and treat everything after the final / as the item id. Note that this simple redirection will lose any additional query parameters passed in. Many OpenACS objects maintain a pretty-name, which is a unique, human-readable string, usually derived from title, which makes an even better 'pretty url' than a numeric id; this requires that your display page be able to look up an item based on pretty id. We use rp_form_put to store the item id in the internal register that the next page is expecting, and then redirects the request in process internally (ie, without a browser refresh). Next, modify note-list so that its link is of the new form.: - [service0 www]$ emacs ../lib/note-edit.tcl + [$OPENACS_SERVICE_NAME www]$ emacs ../lib/note-edit.tcl db_multirow \ -extend { Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml 27 Apr 2004 00:53:41 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-db.xml 14 May 2004 14:10:27 -0000 1.13 @@ -64,8 +64,8 @@ by the API browser. The string $Id:$ will automatically be expanded when the file is checked in to cvs. -[service0 ~]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/sql/postgresql -[service0 postgresql]$ emacs myfirstpackage-create.sql +[$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/sql/postgresql +[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-create.sql Paste the text below into the file, save, and close.
The Database Creation Script @@ -79,33 +79,33 @@ with objects from other packages. Create a database file to drop everything if the package is uninstalled. -[service0 postgresql]$ emacs myfirstpackage-drop.sql +[$OPENACS_SERVICE_NAME postgresql]$ emacs myfirstpackage-drop.sql
Database Deletion Script example missing
(like the creation script the drop script calls a PL/pgSQL function: content_type__drop_type Run the create script manually to add your tables and functions. - [service0 postgresql]$ psql -f myfirstpackage-create.sql + [$OPENACS_SERVICE_NAME postgresql]$ psql -f myfirstpackage-create.sql psql:myfirstpackage-create.sql:15: NOTICE: CREATE TABLE / PRIMARY KEY will create implicit index 'mfp_notes_pkey' for table 'mfp_notes' psql:myfirstpackage-create.sql:15: NOTICE: CREATE TABLE will create implicit trigger(s) for FOREIGN KEY check(s) content_type__create_type --------------------------- 0 (1 row) -[service0 postgresql]$ +[$OPENACS_SERVICE_NAME postgresql]$ If there are errors, use them to debug the sql file and try again. If there are errors in the database table creation, you may need to run the drop script to drop the table so that you can recreate it. The drop script will probably have errors since some of the things it's trying to drop may be missing. They can be ignored. Once you get the same output as shown above, test the drop script: - [service0 postgresql]$ psql -f myfirstpackage-drop.sql + [$OPENACS_SERVICE_NAME postgresql]$ psql -f myfirstpackage-drop.sql content_type__drop_type ------------------------- 0 (1 row) -[service0 postgresql]$ +[$OPENACS_SERVICE_NAME postgresql]$ Once both scripts are working without errors, run the create script one last time and proceed. - [service0 postgresql]$ psql -f myfirstpackage-create.sql + [$OPENACS_SERVICE_NAME postgresql]$ psql -f myfirstpackage-create.sql \ No newline at end of file Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml,v diff -u -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml 23 Mar 2004 15:37:19 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-debug.xml 14 May 2004 14:10:27 -0000 1.10 @@ -25,7 +25,7 @@ steps like looking directly at tables and testing stored procedures. Start emacs. Type M-x sql-postgres. Press enter for - server name and use service0 for + server name and use $OPENACS_SERVICE_NAME for database name. You can use C-(up arrow) and C-(down arrow) for command history. @@ -38,7 +38,7 @@ To set up real-time monitoring of the AOLserver error - log, type less /var/lib/aolserver/service0/log/openacs-dev-error.log + log, type less /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/openacs-dev-error.log F to show new log entries in real time (like tail -f) C-c to stop and F to start it up again. G goes to the end. @@ -101,9 +101,9 @@ It seems to me that a lot of people have been asking for some guidelines on how to write automated tests. I've done several tests by now and have found the process to be extremely easy and useful. It's a joy to work with automated testing once you get the hang of it. Create the directory that will contain the test script and edit the script file. The directory location and file name are standards which are recognized by the automated testing package: - [service0 www]$ mkdir /var/lib/aolserver/service0/packages/myfirstpackage/tcl/test -[service0 www]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/tcl/test -[service0 test]$ emacs myfirstpackages-procs.tcl + [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test +[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/test +[$OPENACS_SERVICE_NAME test]$ emacs myfirstpackages-procs.tcl Write the tests. This is obviously the big step :) The script should first call ad_library like any normal -procs.tcl file: ad_library { ... Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml 26 Feb 2004 15:28:37 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial-pages.xml 14 May 2004 14:10:27 -0000 1.13 @@ -15,7 +15,7 @@ Install some API As a workaround for missing content-repository functionality, copy a provided file into the directory for tcl files: - cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/service0/packages/myfirstpackage/tcl/ + cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/note-procs.tcl /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/tcl/ To make this file take effect, go to the APM and choose "Reload changed" for "MyFirstPackage". @@ -43,30 +43,30 @@ database-specific SQL. The default page in any directory is index, so we'll build that first, starting with the tcl file: - [service0 postgresql]$ cd /var/lib/aolserver/service0/packages/myfirstpackages/www -[service0 www]$ emacs index.tcl + [$OPENACS_SERVICE_NAME postgresql]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackages/www +[$OPENACS_SERVICE_NAME www]$ emacs index.tcl Paste this into the file. example missing Now index.adp: example missing You can test your work by viewing the page. 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. - [service0 www]$ mkdir /var/lib/aolserver/service0/packages/myfirstpackage/lib -[service0 www]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/lib -[service0 lib]$ emacs note-list.tcl + [$OPENACS_SERVICE_NAME www]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib +[$OPENACS_SERVICE_NAME www]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/lib +[$OPENACS_SERVICE_NAME lib]$ emacs note-list.tcl example missing -[service0 lib]$ emacs note-list.adp +[$OPENACS_SERVICE_NAME lib]$ emacs note-list.adp example missing 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. - [service0 lib]$ cd /var/lib/aolserver/service0/packages/myfirstpackage/www -[service0 www]$ emacs note-edit.tcl + [$OPENACS_SERVICE_NAME lib]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www +[$OPENACS_SERVICE_NAME www]$ emacs note-edit.tcl example missing -[service0 www]$ emacs note-edit.adp +[$OPENACS_SERVICE_NAME www]$ emacs note-edit.adp example missing And the delete page. Since it has no UI, there is only a tcl page, and no adp page. -[service0 www]$ emacs note-delete.tcl +[$OPENACS_SERVICE_NAME www]$ emacs note-delete.tcl example missing Index: openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml,v diff -u -r1.13 -r1.14 --- openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 26 Apr 2004 18:23:13 -0000 1.13 +++ openacs-4/packages/acs-core-docs/www/xml/developers-guide/tutorial.xml 14 May 2004 14:10:27 -0000 1.14 @@ -73,7 +73,7 @@ Name of development account - service0 + $OPENACS_SERVICE_NAME New Package key @@ -139,7 +139,7 @@ This creates a package rooted at - /var/lib/aolserver/service0/packages/myfirstpackage. + /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage. This is the "home directory" of our new package, and all files in the package will be within this directory. @@ -167,13 +167,13 @@ By mounting the package, we've caused all requests to http://yourserver.test:8000/my-first-package - to be satisfied from the files at /var/lib/aolserver/service0/packages/myfirstpackage/www. + to be satisfied from the files at /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/myfirstpackage/www. Quick start The remainder of the tutorial walks you through each file one at a time as you create the package. You can skip all this, and get a working package, by doing the following: - cd /var/lib/aolserver/service0/packages/acs-core-docs/www/files/tutorial -psql service0 -f myfirstpackage-create.sql + cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/tutorial +psql $OPENACS_SERVICE_NAME -f myfirstpackage-create.sql cp note-edit.* note-delete.tcl index.* ../../../../myfirstpackage/www/ mkdir ../../../../myfirstpackage/lib cp note-list.* ../../../../myfirstpackage/lib/ Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml,v diff -u -r1.9 -r1.10 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml 21 Apr 2004 09:49:46 -0000 1.9 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver4.xml 14 May 2004 14:10:28 -0000 1.10 @@ -181,7 +181,7 @@ Change startup script (optional). - 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 /var/lib/aolserver/service0/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch) + 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 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run script according to the documentation found there (namely: Add the -b yourip:yourport switch) Test AOLserver. Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml,v diff -u -r1.4 -r1.5 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml 11 Mar 2004 15:34:28 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/configuring.xml 14 May 2004 14:10:28 -0000 1.5 @@ -54,10 +54,10 @@ How do I put custom functionality on front page of a new site? - Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/service0/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it: + Every page within an OpenACS site is part of a subsite More information). The home page of the entire site is the front page is a special, default instance of a subsite, served from /var/lib/aolserver/$OPENACS_SERVICE_NAME/www. If an index page is not found there, the default index page for all subsites is used. To customize the code on the front page, copy the default index page from the Subsite package to the Main site and edit it: - cp /var/lib/aolserver/service0/packages/acs-subsite/www/index* /var/lib/aolserver/service0/www + cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-subsite/www/index* /var/lib/aolserver/$OPENACS_SERVICE_NAME/www Edit the new index.adp to change the text; you shouldn't need to edit index.tcl unless you are adding new functionality. @@ -73,14 +73,14 @@ A templated page uses an ADP/TCL pair. The first line in the ADP file is usually: <master> - If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/service0/www, this is /var/lib/aolserver/service0/www/default-master.adp and the associated .tcl file. + If it appears exactly like this, without any arguments, the template processer uses default-master for that subsite. For pages in /var/lib/aolserver/$OPENACS_SERVICE_NAME/www, this is /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/default-master.adp and the associated .tcl file. - The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/service0/www/site-master.adp and .tcl) + The default-master is itself a normal ADP page. It draws the subsite navigation elements and invokes site-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/site-master.adp and .tcl) - The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/service0/www/blank-master.adp and .tcl). + The site-master draws site-wide navigation elements and invokes blank-master (/var/lib/aolserver/$OPENACS_SERVICE_NAME/www/blank-master.adp and .tcl). Blank-master does HTML housekeeping and provides a framework for special sitewide navigation "meta" elements such as Translator widgets and Admin widgets. @@ -125,7 +125,7 @@ Finding the problem - We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/service0/packages/events/www/event-info.tcl. It contains this line: + We start with the page that has the error. In the URL it's http://myserver.net/events/event-info.tcl, so open the file /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/events/www/event-info.tcl. It contains this line: set can_register_p [events::security::can_register_for_event_p -event_id $event_id] We need to know what that procedure does, so go to /api-doc, paste events::security::can_register_for_event_p into the ACS Tcl API Search box, and click Feeling Lucky. The next pages shows the proc, and we click "show source" to see more information. The body of the proc is simply Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml,v diff -u -r1.6 -r1.7 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml 26 Feb 2004 15:28:39 -0000 1.6 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/database-maintenance.xml 14 May 2004 14:10:28 -0000 1.7 @@ -35,7 +35,7 @@ Change the OpenACS service's configuration file to point to the remote database. Edit - /var/lib/aolserver/service0/etc/config.tcl + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl and change to @@ -60,14 +60,14 @@ option. This command will drop the user and every database object the user owns. - SVRMGR> drop user service0 cascade; + SVRMGR> drop user $OPENACS_SERVICE_NAME cascade; If this does not work because svrmgrl "cannot drop a user that is currently connected", make sure to kill the AOLserver using this user. If it still does not work, do: - SVRMGR> select username, sid, serial# from v$session where lower(username)='service0'; + SVRMGR> select username, sid, serial# from v$session where lower(username)='$OPENACS_SERVICE_NAME'; and then SVRMGR> alter system kill session 'sid, serial#'; @@ -81,7 +81,7 @@ If you feel the need to delete everything related to the service, you can also issue the following: - SVRMGR> drop tablespace service0 including contents cascade constraints; + SVRMGR> drop tablespace $OPENACS_SERVICE_NAME including contents cascade constraints; @@ -95,11 +95,11 @@ your server in /etc/inittab, reread the inittab with /sbin/init q, and then restart-aolserver - service0. + $OPENACS_SERVICE_NAME. Then, to drop the db, just do: -[service0 ~]$ dropdb service0 +[$OPENACS_SERVICE_NAME ~]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASE @@ -128,7 +128,7 @@ We'll set vacuum up to run nightly at 1 AM. Add the following line: -0 1 * * * /usr/local/pgsql/bin/vacuumdb service0 +0 1 * * * /usr/local/pgsql/bin/vacuumdb $OPENACS_SERVICE_NAME ($Id$) Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml,v diff -u -r1.14 -r1.15 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml 14 May 2004 13:28:11 -0000 1.14 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/maintenance.xml 14 May 2004 14:10:28 -0000 1.15 @@ -16,7 +16,7 @@ Starting and Stopping an OpenACS instance. - The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/service0/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script. + The simplest way to start and stop and OpenACS site is to run the startup shell script provided, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. This runs as a regular task, and logs to the logfile. To stop the site, kill the script. A more stable way to run OpenACS is with a "keepalive" mechanism of some sort, so that whenever the server halts or is stopped for a reset, it restarts automatically. This is recommended for development and production servers. The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here. @@ -49,62 +49,62 @@ Hence, the AOLserver instance for your development server is started by the file - /service/service0/run. + /service/$OPENACS_SERVICE_NAME/run. But we use a symlink to make it easier to add and remove stuff from the /service, so the actual location is - /var/lib/aolserver/service0etc/daemontools/run. + /var/lib/aolserver/$OPENACS_SERVICE_NAMEetc/daemontools/run. Daemontools creates additional files and directories to track status and log. A daemontools directory is included in the OpenACS tarball at - /var/lib/aolserver/service0/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run. + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools. To use it, first ill any existing AOLserver instances. As root, link the daemontools directory into the /service directory. Daemontools' svscan process checks this directory every five seconds, and will quickly execute run. - [service0 etc]$ killall nsd + [$OPENACS_SERVICE_NAME etc]$ killall nsd nsd: no process killed -[service0 etc]$ emacs /var/lib/aolserver/service0/etc/daemontools/run -[service0 etc]$ exit +[$OPENACS_SERVICE_NAME etc]$ emacs /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run +[$OPENACS_SERVICE_NAME etc]$ exit -[root root]# ln -s /var/lib/aolserver/service0/etc/daemontools/ /service/service0 +[root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/ /service/$OPENACS_SERVICE_NAME Verify that AOLserver is running. [root root]# ps -auxw | grep nsd -service0 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/service0/etc/config.tcl -u serve +$OPENACS_SERVICE_NAME 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl -u serve root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd [root root]# - The user service0 can now control the service service0 with these commands: + The user $OPENACS_SERVICE_NAME can now control the service $OPENACS_SERVICE_NAME with these commands: - svc -d /service/service0 - + svc -d /service/$OPENACS_SERVICE_NAME - Bring the server down - svc -u /service/service0 - + svc -u /service/$OPENACS_SERVICE_NAME - Start the server up and leave it in keepalive mode. - svc -o /service/service0 - + svc -o /service/$OPENACS_SERVICE_NAME - Start the server up once. Do not restart it if it stops. - svc -t /service/service0 - + svc -t /service/$OPENACS_SERVICE_NAME - Stop and immediately restart the server. - svc -k /service/service0 - + svc -k /service/$OPENACS_SERVICE_NAME - Sends the server a KILL signal. This is like KILL -9. AOLserver exits immediately. If svc -t fails to fully kill AOLserver, use this option. This does not take the server out of keepalive mode, so it should still bounce back up immediately. @@ -115,20 +115,20 @@ Install a script to automate the stopping and starting - of AOLserver services via daemontools. You can then restart a service via restart-aolserver service0 - [root root]# cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver + of AOLserver services via daemontools. You can then restart a service via restart-aolserver $OPENACS_SERVICE_NAME + [root root]# cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/restart-aolserver-daemontools.txt /usr/local/bin/restart-aolserver [root root]# chmod 755 /usr/local/bin/restart-aolserver [root root]# At this point, these commands will work only for the - root user. Grant permission for the web group to use svc commands on the service0 server. - [root root]# svgroup web /service/service0 + root user. Grant permission for the web group to use svc commands on the $OPENACS_SERVICE_NAME server. + [root root]# svgroup web /service/$OPENACS_SERVICE_NAME [root root]# - Verify that the controls work. You may want to tail -f /var/lib/aolserver/service0/log/service0-error.log in another window, so you can see what happens when you type these commands. + Verify that the controls work. You may want to tail -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log in another window, so you can see what happens when you type these commands. @@ -165,10 +165,10 @@ aolserver supervise (a child of svscanboot) - /service/service0/run - /var/lib/aolserver/service0/log/error.log - /var/lib/aolserver/service0/log/service0.log - svc -k /service/service0 + /service/$OPENACS_SERVICE_NAME/run + /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/error.log + /var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME.log + svc -k /service/$OPENACS_SERVICE_NAME postgresql @@ -335,7 +335,7 @@ Services on different ports To run a different service on another port but the same ip, simply repeat replacing - service0, and change the + $OPENACS_SERVICE_NAME, and change the set httpport 8000 set httpsport 8443 to different values. @@ -487,17 +487,17 @@ Prepare a certificate directory for the service. - [service0 etc]$ mkdir /var/lib/aolserver/service0/etc/certs -[service0 etc]$ chmod 700 /var/lib/aolserver/service0/etc/certs -[service0 etc]$ -mkdir /var/lib/aolserver/service0/etc/certs -chmod 700 /var/lib/aolserver/service0/etc/certs + [$OPENACS_SERVICE_NAME etc]$ mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME etc]$ chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME etc]$ +mkdir /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +chmod 700 /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs It takes two files to support an SSL connection. The certificate is the public half of the key pair - the server sends the certificate to browser requesting ssl. The key is the private half of the key pair. In addition, the certificate must be signed by Certificate Authority or browsers will protest. Each web browser ships with a built-in list of acceptable Certificate Authorities (CAs) and their keys. Only a site certificate signed by a known and approved CA will work smoothly. Any other certificate will cause browsers to produce some messages or block the site. Unfortunately, getting a site certificate signed by a CA costs money. In this section, we'll generate an unsigned certificate which will work in most browsers, albeit with pop-up messages. Use an OpenSSL perl script to generate a certificate and key. - [service0 service0]$ cd /var/lib/aolserver/service0/etc/certs -[service0 certs]$ perl /usr/share/ssl/misc/CA -newcert + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/certs +[$OPENACS_SERVICE_NAME certs]$ perl /usr/share/ssl/misc/CA -newcert Using configuration from /usr/share/ssl/openssl.cnf Generating a 1024 bit RSA private key ...++++++ @@ -506,15 +506,15 @@ Enter PEM pass phrase: Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this: Certificate (and private key) is in newreq.pem -[service0 certs]$ +[$OPENACS_SERVICE_NAME certs]$ newreq.pem contains our certificate and private key. The key is protected by a passphrase, which means that we'll have to enter the pass phrase each time the server starts. This is impractical and unnecessary, so we create an unprotected version of the key. Security implication: if anyone gets access to the file keyfile.pem, they effectively own the key as much as you do. Mitigation: don't use this key/cert combo for anything besides providing ssl for the web site. [root misc]# openssl rsa -in newreq.pem -out keyfile.pem read RSA key Enter PEM pass phrase: writing RSA key -[service0 certs]$ +[$OPENACS_SERVICE_NAME certs]$ To create the certificate file, we take the combined file, copy it, and strip out the key. - [service0 certs]$ cp newreq.pem certfile.pem + [$OPENACS_SERVICE_NAME certs]$ cp newreq.pem certfile.pem [root misc]# emacs certfile.pem Strip out the section that looks like -----BEGIN RSA PRIVATE KEY----- @@ -538,46 +538,46 @@ the OpenACS tarball. - [root src]# su - service0 -[service0 service0]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg -[service0 service0]$ mkdir www/log -[service0 service0]$ cp -r /usr/share/analog-5.31/images www/log/ -[service0 service0]$ -su - service0 -cd /var/lib/aolserver/service0 -cp /var/lib/aolserver/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg + [root src]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cp /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ mkdir www/log +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cp -r /usr/share/analog-5.31/images www/log/ +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ +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.31/images www/log/ Edit -/var/lib/aolserver/service0/etc/analog.cfg and change the variable in HOSTNAME "[my +/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg and change the variable in HOSTNAME "[my organisation]" to reflect your website title. If you don't want the traffic log to be publicly visible, change -OUTFILE /var/lib/aolserver/service0/www/log/traffic.html to use a private +OUTFILE /var/lib/aolserver/$OPENACS_SERVICE_NAME/www/log/traffic.html to use a private directory. Run it. - [service0 service0]$ /usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/share/analog-5.31/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg /usr/share/analog-5.31/analog: analog version 5.31/Unix /usr/share/analog-5.31/analog: Warning F: Failed to open DNS input file - /home/service0/dnscache: ignoring it + /home/$OPENACS_SERVICE_NAME/dnscache: ignoring it (For help on all errors and warnings, see docs/errors.html) /usr/share/analog-5.31/analog: Warning R: Turning off empty Search Word Report -[service0 service0]$ +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ Verify that it works by browing to http://yourserver.test:8000/log/traffic.html Automate this by creating a file in /etc/cron.daily. - [service0 service0]$ exit + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit logout [root root]# emacs /etc/cron.daily/analog Put this into the file: #!/bin/sh -/usr/share/analog-5.31/analog -G -g/var/lib/aolserver/service0/etc/analog.cfg +/usr/share/analog-5.31/analog -G -g/var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/analog.cfg [root root]# chmod 755 /etc/cron.daily/analog Test it by running the script. [root root]# sh /etc/cron.daily/analog @@ -647,7 +647,7 @@ Identify a runaway Oracle query: first, use ps aux or top to get the UNIX process ID of a runaway Oracle process. Log in to SQL*Plus as the admin: - [service0 ~]$ svrmgrl + [$OPENACS_SERVICE_NAME ~]$ svrmgrl Oracle Server Manager Release 3.1.7.0.0 - Production Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml,v diff -u -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 12 Mar 2004 13:44:58 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 14 May 2004 14:10:28 -0000 1.22 @@ -44,18 +44,18 @@ for each different service. A service name should be a single word, letters and numbers only. If the name of your site is one word, that would be a good choice. For - example "service0" might be the service name for the - service0.net + example "$OPENACS_SERVICE_NAME" might be the service name for the + $OPENACS_SERVICE_NAME.net community. We'll leave the password blank, which prevents login by password, for increased security. The only way to log in will be with ssh certificates. The only people who should log in are developers for that specific instance. Add this user, and put - it in the service0 group so that it + it in the $OPENACS_SERVICE_NAME group so that it can use database and server commands associated with that group. -[root root]# useradd service0 +[root root]# useradd $OPENACS_SERVICE_NAME [root root]# @@ -68,27 +68,27 @@ service's dedicated user. We put it there so that it is not overwritten when we do the main CVS checkout to the target location. - [root root]# su - service0 -[service0 service0]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot co -d install openacs-4/etc/install + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot co -d install openacs-4/etc/install cvs server: Updating install U install/README U install/TODO ... many lines omitted ... U install/tcl/twt-procs.tcl U install/tcl/user-procs.tcl -[service0 service0]$ cd install -[service0 install]$ emacs install.tcl +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd install +[$OPENACS_SERVICE_NAME install]$ emacs install.tcl - Edit the installation configuration file, /home/service0/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000. + Edit the installation configuration file, /home/$OPENACS_SERVICE_NAME/install/install.tcl and update the site-specific values, such as the new service's IP address and name, which will be written into the new service's config.tcl file. If your system is different from the one described in the previous sections, check the file paths as well. Set do_checkout=yes to create a new OpenACS site directly from a CVS checkout, or =no if you have a fully configured site and just want to rebuild it (drop and recreate the database and repeat the installation). If you have followed a stock installation, the default configuration will work without changes and will install an OpenACS site at 127.0.0.1:8000. Run the install script install.sh as root: - [service0 service0]$ exit -[root root]# sh /home/service0/install/install.sh -/home/service0/install/install.sh: Starting installation with config_file -/home/service0/install/install.tcl. Using serverroot=/var/lib/aolserver/ -service0, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit +[root root]# sh /home/$OPENACS_SERVICE_NAME/install/install.sh +/home/$OPENACS_SERVICE_NAME/install/install.sh: Starting installation with config_file +/home/$OPENACS_SERVICE_NAME/install/install.tcl. Using serverroot=/var/lib/aolserver/ +$OPENACS_SERVICE_NAME, server_url=http://0.0.0.0:8000, do_checkout=yes, do_install=yes, dotlrn=no, and database=postgres., use_daemontools=true ... many lines omitted ... -Tue Jan 27 11:50:59 CET 2004: Finished (re)installing /var/lib/aolserver/service0. +Tue Jan 27 11:50:59 CET 2004: Finished (re)installing /var/lib/aolserver/$OPENACS_SERVICE_NAME. ###################################################################### New site URL: http://127.0.0.1:8000 admin email : admin@yourserver.net @@ -107,27 +107,27 @@ /tmp and proceed: - Unpack the OpenACS tarball and rename it to service0. Secure the directory so that only the owner can access it. Check the permissions by listing the directory. - [root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver -[service0 aolserver]$ tar xzf /tmp/&tarballpath;.tgz -[service0 aolserver]$ mv &tarballpath; service0 -[service0 aolserver]$ chmod -R 775 service0 -[service0 aolserver]$ chown -R service0.service0 service0 -[service0 aolserver]$ ls -al + Unpack the OpenACS tarball and rename it to $OPENACS_SERVICE_NAME. Secure the directory so that only the owner can access it. Check the permissions by listing the directory. + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /tmp/&tarballpath;.tgz +[$OPENACS_SERVICE_NAME aolserver]$ mv &tarballpath; $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ ls -al total 3 drwxrwx--- 3 root web 1024 Mar 29 16:41 . drwxr-xr-x 25 root root 1024 Mar 29 16:24 .. -drwx------ 7 service0 web 1024 Jan 6 14:36 service0 -[service0 aolserver]$ exit +drwx------ 7 $OPENACS_SERVICE_NAME web 1024 Jan 6 14:36 $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ exit logout [root root]# -su - service0 +su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver tar xzf /tmp/&tarballpath;.tgz -mv &tarballpath; service0 -chmod -R 755 service0 -chgrp -R service0.service0 service0 +mv &tarballpath; $OPENACS_SERVICE_NAME +chmod -R 755 $OPENACS_SERVICE_NAME +chgrp -R $OPENACS_SERVICE_NAME.$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME exit @@ -144,22 +144,22 @@ You should be sure that your user account - (e.g. service0) is in the + (e.g. $OPENACS_SERVICE_NAME) is in the dba group. Verify membership by typing groups when you login: - [service0 ~]$ groups + [$OPENACS_SERVICE_NAME ~]$ groups dba web If you do not see these groups, take the following action: - [service0 ~]$ su - + [$OPENACS_SERVICE_NAME ~]$ su - Password: ************ -[root ~]# adduser service0 dba +[root ~]# adduser $OPENACS_SERVICE_NAME dba If you get an error about an undefined group, then add that group manually: @@ -176,7 +176,7 @@ Connect to Oracle using svrmgrl and login: - [service0 ~]$ svrmgrl + [$OPENACS_SERVICE_NAME ~]$ svrmgrl SVRMGR> connect internal Connected. @@ -220,13 +220,13 @@ SVRMGR> exit -[service0 ~]$ su - +[$OPENACS_SERVICE_NAME ~]$ su - Password: ************ [root ~]# mkdir -p /ora8/m02/oradata/ora8/ -[root ~]# chown service0:web /ora8/m02/oradata/ora8 +[root ~]# chown $OPENACS_SERVICE_NAME:web /ora8/m02/oradata/ora8 [root ~]# chmod 775 /ora8/m02/oradata/ora8 [root ~]# exit -[service0 ~]$ +[$OPENACS_SERVICE_NAME ~]$ @@ -241,10 +241,10 @@ tablespace. - [service0 ~]$ svrmgrl + [$OPENACS_SERVICE_NAME ~]$ svrmgrl SVRMGR> connect internal; -SVRMGR> create tablespace service0 - datafile '/ora8/m02/oradata/ora8/service001.dbf' +SVRMGR> create tablespace $OPENACS_SERVICE_NAME + datafile '/ora8/m02/oradata/ora8/$OPENACS_SERVICE_NAME01.dbf' size 50M autoextend on next 10M @@ -256,24 +256,24 @@ Create a database user for this service. Give the user access to the tablespace and rights to connect. We'll use - service0password as our password. + $OPENACS_SERVICE_NAMEpassword as our password. Write down what you specify as service_name - (i.e. service0) + (i.e. $OPENACS_SERVICE_NAME) and database_password - (i.e. service0password). You + (i.e. $OPENACS_SERVICE_NAMEpassword). You will need this information for configuring exports and AOLserver. -SVRMGR> create user service0 identified by service0password default tablespace service0 - temporary tablespace temp quota unlimited on service0; -SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to service0; -SVRMGR> revoke unlimited tablespace from service0; -SVRMGR> alter user service0 quota unlimited on service0; +SVRMGR> create user $OPENACS_SERVICE_NAME identified by $OPENACS_SERVICE_NAMEpassword default tablespace $OPENACS_SERVICE_NAME + temporary tablespace temp quota unlimited on $OPENACS_SERVICE_NAME; +SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to $OPENACS_SERVICE_NAME; +SVRMGR> revoke unlimited tablespace from $OPENACS_SERVICE_NAME; +SVRMGR> alter user $OPENACS_SERVICE_NAME quota unlimited on $OPENACS_SERVICE_NAME; SVRMGR> exit; @@ -286,7 +286,7 @@ Make sure that you can login to Oracle using your service_name account: - [service0 ~]$ sqlplus service0/service0password + [$OPENACS_SERVICE_NAME ~]$ sqlplus $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAMEpassword SQL> select sysdate from dual; SYSDATE ---------- @@ -313,31 +313,31 @@ Create a user in the database matching the service name. With default PostgreSQL authentication, a system user connecting locally automatically authenticates as the postgres user of the same name, if one exists. We currently use postgres "super-users" for everything, which means that anyone with access to any of the openacs system accounts on a machine has full access to all postgresql databases on that machine. [root root]# su - postgres -[postgres pgsql]$ createuser -a -d service0 +[postgres pgsql]$ createuser -a -d $OPENACS_SERVICE_NAME CREATE USER [postgres pgsql]$ exit logout [root root]# - Create a database with the same name as our service name, service0. - [root root]# su - service0 -[service0 service0]$ createdb -E UNICODE service0 + Create a database with the same name as our service name, $OPENACS_SERVICE_NAME. + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ createdb -E UNICODE $OPENACS_SERVICE_NAME CREATE DATABASE -[service0 service0]$ -su - service0 -createdb -E UNICODE service0 +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ +su - $OPENACS_SERVICE_NAME +createdb -E UNICODE $OPENACS_SERVICE_NAME Automate daily database Vacuuming. This is a process which cleans out discarded data from the database. A quick way to automate vacuuming is to edit the cron file for the database user. Recommended: VACUUM ANALYZE every hour and VACUUM FULL ANALYZE every day. Postgres Vacuuming - [service0 service0]$ export EDITOR=emacs;crontab -e + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ export EDITOR=emacs;crontab -e Add these lines to the file. The vacuum command cleans up temporary structures within a PostGreSQL database, and can improve performance. We vacuum gently every hour and completely every day. The numbers and stars at the beginning are cron columns that specify when the program should be run - in this case, whenever the minute is 0 and the hour is 1, i.e., 1:00 am every day, and every (*) day of month, month, and day of week. Type man 5 crontab for more information. - 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0 -0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze service0 + 0 1-23 * * * /usr/local/pgsql/bin/vacuumdb --analyze $OPENACS_SERVICE_NAME +0 0 * * * /usr/local/pgsql/bin/vacuumdb --full --analyze $OPENACS_SERVICE_NAME Depending on your distribution, you may receive email when the crontab items are executed. If you @@ -370,16 +370,16 @@ specific port, e.g. port 80. In order for OpenACS to work, you need to configure a virtual server. The Reference Platform uses a configuration file included in the OpenACS tarball, - /var/lib/aolserver/service0/etc/config.tcl. + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl. Open it in an editor to adjust the parameters. AOLserver configuration - [root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver/service0/etc -[service0 etc]$ emacs config.tcl + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc +[$OPENACS_SERVICE_NAME etc]$ emacs config.tcl You can continue without changing any values in the file. However, if you don't change address to match the computer's ip address, you won't be able to browse to your server from other machines. @@ -400,7 +400,7 @@ address - The IP address of the server. If you are hosting multiple IPs on one computer, this is the address specific to the web site. Each virtual server will ignore any requests directed at other addresses. - server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses service0. + server - This is the keyword that, by convention, identifies the service. It is also used as part of the path for the service root, as the name of the user for running the service, as the name of the database, and in various dependent places. The Reference Platform uses $OPENACS_SERVICE_NAME. @@ -452,23 +452,23 @@ Kill any current running AOLserver processes and start a new - one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/service0/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run. + one. The recommended way to start an AOLserver process is by running the included script, /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/run. If you are not using the default file paths and names, you will need to edit run. If you want to use port 80, there are complications. AOLserver must be root to use system ports such as 80, but refuses to run as root for security reasons. So, we call the run script as root and specify a non-root user ID and Group ID which AOLserver will switch to after claiming the port. To do so, find the UID and GID of the - service0 user via - grep service0 + $OPENACS_SERVICE_NAME user via + grep $OPENACS_SERVICE_NAME /etc/passwd and then put those numbers into the command line via -u 501 -g 502. In AOLserver 4, you must also send a -b flag. Do this by editing the run file as indicated in the comments. If you are root then killall will affect all OpenACS services on the machine, so if there's more than one you'll have to do ps -auxw | grep nsd and selectively kill by job number. - [service0 etc]$ killall nsd + [$OPENACS_SERVICE_NAME etc]$ killall nsd nsd: no process killed -[service0 service0]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/service0/etc/config.tcl -[service0 service0]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file... +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/config.tcl +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: starting to read config file... [08/Mar/2003:18:13:29][32131.8192][-main-] Notice: nsd.tcl: finished reading config file. @@ -480,13 +480,13 @@ url="files/openacs-start.html">this. If you imported your files into cvs, now that you know it worked you can erase the temp - directory with rm -rf /var/lib/aolserver/service0.orig. + directory with rm -rf /var/lib/aolserver/$OPENACS_SERVICE_NAME.orig. If you don't see the login page, view your error log - (/var/lib/aolserver/service0/log/service0-error.log) + (/var/lib/aolserver/$OPENACS_SERVICE_NAME/log/$OPENACS_SERVICE_NAME-error.log) to make sure the service is starting without any problems. The most common errors here are trying to start a port 80 server while not root, failing to connect because of @@ -579,7 +579,7 @@ AOLserver to restart itself (ie. inittab or daemontools), you'll need to manually restart your service. - [service0 service0]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/service0/config.tcl + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/aolserver/bin/nsd-postgres -t /var/lib/aolserver/$OPENACS_SERVICE_NAME/config.tcl @@ -634,8 +634,8 @@ database, because those environmental variables are set by the wrapper scripts nsd-postgres and nsd-oracle. - [root root]# su - service0 -[service0 service0]$ emacs .bashrc + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines. @@ -660,11 +660,11 @@ Test this by logging out and back in as - service0 and checking the paths. - [service0 service0]$ exit + $OPENACS_SERVICE_NAME and checking the paths. + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit logout -[root src]# su - service0 -[service0 ~]$ env +[root src]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME ~]$ env Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml,v diff -u -r1.12 -r1.13 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 7 May 2004 02:33:34 -0000 1.12 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/os.xml 14 May 2004 14:10:28 -0000 1.13 @@ -36,6 +36,8 @@ a Mail Transport Agent, such as exim or sendmail (or install qmail from source) + In order to cut and paste the example code into your shell, you must first do . + To install a machine to the specifications of the Reference Platform, do the walkthrough of the Red Hat 8.0 Install for OpenACS. ($Id$) 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.17 -r1.18 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 19 Apr 2004 10:06:01 -0000 1.17 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/other-software.xml 14 May 2004 14:10:28 -0000 1.18 @@ -568,18 +568,18 @@ to work, you must also install the PostgreSQL OpenFTS module and prerequisites.) - [service0 service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql BEGIN CREATE (many lines omitted) INSERT 0 1 COMMIT -[service0 service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ /usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql CREATE CREATE -[service0 service0]$ -/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql -/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ +/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/tsearch/tsearch.sql +/usr/local/pgsql/bin/psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.3.4/contrib/pgsql_contrib_openfts/openfts.sql @@ -607,8 +607,8 @@ Restart the service. -[service0 service0]$ svc -t /service/service0 -[service0 service0]$ +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ Wait a minute, then browse back to the home page. @@ -660,8 +660,8 @@ Restart the service. - [service0 service0]$ svc -t /service/service0 -[service0 service0]$ + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ Wait a minute, then click on Main Site at the top of the page. @@ -684,8 +684,8 @@ Restart the service. - [service0 service0]$ svc -t /service/service0 -[service0 service0]$ + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ svc -t /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ @@ -718,14 +718,14 @@ Load the service contracts datamodell and enable the service contract - [service0 service0]$ cd packages/lars-blogger/sql/postgresql -[service0 postgresql]$ psql service0 -f lars-blogger-sc-create.sql + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd packages/lars-blogger/sql/postgresql +[$OPENACS_SERVICE_NAME postgresql]$ psql $OPENACS_SERVICE_NAME -f lars-blogger-sc-create.sql Note: Usually this script is called package_name-sc-create.sql Restart the service. - [service0 postgresql]$ svc -t /service/service0 - [service0 postgresl]$ + [$OPENACS_SERVICE_NAME postgresql]$ svc -t /service/$OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME postgresl]$ If you are lucky, Full Text Search is enabled now, if not consult http://openacs.org/forums/message-view?message_id=154759. This link also contains some hints on how to make sure it is enabled. @@ -876,12 +876,12 @@ Install Squirrelmail for use as a webmail system for OpenACS This section is work in progress. It will detail how you can install Squirrelmail as a webmail frontend for OpenACS, thereby neglecting the need to have a seperate webmail package within OpenACS - [service0 service0]# cd www -[service0 www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.2.tar.gz -[service0 www]# tar xfz squirrelmail-1.4.2.tar.gz -[service0 www]# mv squirrelmail-1.4.2 mail -[service0 www]# cd mail/config -[service0 www]# ./conf.pl + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd www +[$OPENACS_SERVICE_NAME www]# wget http://cesnet.dl.sourceforge.net/sourceforge/squirrelmail/squirrelmail-1.4.2.tar.gz +[$OPENACS_SERVICE_NAME www]# tar xfz squirrelmail-1.4.2.tar.gz +[$OPENACS_SERVICE_NAME www]# mv squirrelmail-1.4.2 mail +[$OPENACS_SERVICE_NAME www]# cd mail/config +[$OPENACS_SERVICE_NAME www]# ./conf.pl Now you are about to configure Squirrelmail. The configuration heavily depends on your setup, so no instructions are given here. Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml,v diff -u -r1.21 -r1.22 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml 15 Feb 2004 11:28:44 -0000 1.21 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/overview.xml 14 May 2004 14:10:28 -0000 1.22 @@ -101,18 +101,23 @@ This is text that you will see and type in a command shell, including text you may have to change. It is followed by a list of just the commands, - which you can copy and paste. The command prompt varies by system; in the examples we use the form[service0 aolserver]$, where service0 is the current user and aolserver is the current directory. The root prompt is shown ending in # and all other prompts in $. + which you can copy and paste. The command prompt varies by system; in the examples we use the form[$OPENACS_SERVICE_NAME aolserver]$, where $OPENACS_SERVICE_NAME is the current user and aolserver is the current directory. The root prompt is shown ending in # and all other prompts in $. -[root root]# su - service0 -[service0 aolserver]$ svc -d /service/service0 -[service0 aolserver]$ dropdb service0 +[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ svc -d /service/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASE -[service0 aolserver]$ createdb service0 +[$OPENACS_SERVICE_NAME aolserver]$ createdb $OPENACS_SERVICE_NAME CREATE DATABASE -su - service0 -svc -d /service/service0 -dropdb service0 -createdb service0 +su - $OPENACS_SERVICE_NAME +svc -d /service/$OPENACS_SERVICE_NAME +dropdb $OPENACS_SERVICE_NAME +createdb $OPENACS_SERVICE_NAME + + Setting a global shell variable for cut and paste + In order to cut and paste the instructions into your shell, you must set the environment variable $OPENACS_SERVICE_NAME. In order to set it globally so that it works for any new users or special service users you may create, edit the file /etc/profile and add this line: + + export OPENACS_SERVICE_NAME=service0 @@ -136,21 +141,21 @@ OpenACS service - service0 + $OPENACS_SERVICE_NAME - service0 + $OPENACS_SERVICE_NAME (set to service0 in default install) OpenACS service account - service0 + $OPENACS_SERVICE_NAME OpenACS database name - service0 + $OPENACS_SERVICE_NAME Root of OpenACS service file tree (SERVERROOT) - /var/lib/aolserver/service0 + /var/lib/aolserver/$OPENACS_SERVICE_NAME Location of source code tarballs for new software @@ -164,15 +169,15 @@ Database backup directory - /var/lib/aolserver/service0/database-backup + /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup Service config files - /var/lib/aolserver/service0/etc + /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc Service log files - /var/lib/aolserver/service0/log + /var/lib/aolserver/$OPENACS_SERVICE_NAME/log Compile directory Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml,v diff -u -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml 27 Feb 2004 11:20:58 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/postgres.xml 14 May 2004 14:10:28 -0000 1.24 @@ -158,9 +158,9 @@ sudo niutil -createprop / /users/postgres gid 201 sudo niutil -createprop / /users/postgres uid 502 sudo niutil -createprop / /users/postgres home /usr/local/pgsql -sudo niutil -create / /users/service0 -sudo niutil -createprop / /users/service0 gid 201 -sudo niutil -createprop / /users/service0 uid 201 +sudo niutil -create / /users/$OPENACS_SERVICE_NAME +sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME gid 201 +sudo niutil -createprop / /users/$OPENACS_SERVICE_NAME uid 201 mkdir -p /usr/local/pgsql chown -R postgres:web /usr/local/pgsql /usr/local/src/postgresql-7.4.1 chmod 750 /usr/local/pgsql @@ -469,7 +469,7 @@ Install the startup script: cd /Library/StartupItems/ -tar xfz /var/lib/aolserver/service0/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz +tar xfz /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-core-docs/www/files/osx-postgres-startup-item.tgz Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml,v diff -u -r1.10 -r1.11 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml 18 Feb 2004 14:51:18 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/recovery.xml 14 May 2004 14:10:28 -0000 1.11 @@ -75,11 +75,11 @@ OpenACS installations comprise files and database contents. If you follow the reference install and put all files, including configuration files, in - /var/lib/aolserver/service0/, + /var/lib/aolserver/$OPENACS_SERVICE_NAME/, and back up the database nightly to a file in - /var/lib/aolserver/service0/database-backup, + /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup, then you can apply standard file-based backup strategies to - /var/lib/aolserver/service0 + /var/lib/aolserver/$OPENACS_SERVICE_NAME @@ -191,15 +191,15 @@ PostgreSQL Create a backup file and verify that it was created and has a reasonable size (several megabytes). - [root root]# su - service0 -[service0 service0]$ pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp service0 -[service0 service0]$ ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp --rw-rw-r-x 1 service0 service0 4005995 Feb 21 18:28 /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp -[service0 service0]$ exit + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp +-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]$ exit [root root]# -su - service0 -pg_dump -f /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp openacs-dev -ls -al /var/lib/aolserver/service0/database-backup/before_upgrade_to_4.6.dmp +su - $OPENACS_SERVICE_NAME +pg_dump -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp openacs-dev +ls -al /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/before_upgrade_to_4.6.dmp exit @@ -240,34 +240,34 @@ The last clause, - /var/lib/aolserver/service0/, + /var/lib/aolserver/$OPENACS_SERVICE_NAME/, specifies the starting point for backup. Tar defaults to recursive backup. - [root root]# su - service0 -[service0 service0]$ tar -cpsz --exclude /var/lib/aolserver/service0/etc/daemontools/supervise \ - --file /tmp/service0-backup.tar.gz /var/lib/aolserver/service0/ + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ tar -cpsz --exclude /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools/supervise \ + --file /tmp/$OPENACS_SERVICE_NAME-backup.tar.gz /var/lib/aolserver/$OPENACS_SERVICE_NAME/ tar: Removing leading `/' from member names -[service0 service0]$ +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ Suffer a catastrophic failure on your production system (We'll simulate this step) - [root root]# svc -d /service/service0 -[root root]# mv /var/lib/aolserver/service0/ /var/lib/aolserver/service0.lost -[root root]# rm /service/service0 -rm: remove symbolic link `/service/service0'? y -[root root]# ps -auxw | grep service0 -root 1496 0.0 0.0 1312 252 ? S 16:58 0:00 supervise service0 + [root root]# svc -d /service/$OPENACS_SERVICE_NAME +[root root]# mv /var/lib/aolserver/$OPENACS_SERVICE_NAME/ /var/lib/aolserver/$OPENACS_SERVICE_NAME.lost +[root root]# rm /service/$OPENACS_SERVICE_NAME +rm: remove symbolic link `/service/$OPENACS_SERVICE_NAME'? y +[root root]# ps -auxw | grep $OPENACS_SERVICE_NAME +root 1496 0.0 0.0 1312 252 ? S 16:58 0:00 supervise $OPENACS_SERVICE_NAME [root root]# kill 1496 -[root root]# ps -auxw | grep service0 +[root root]# ps -auxw | grep $OPENACS_SERVICE_NAME [root root]# su - postgres -[postgres pgsql]$ dropdb service0 +[postgres pgsql]$ dropdb $OPENACS_SERVICE_NAME DROP DATABASE -[postgres pgsql]$ dropuser service0 +[postgres pgsql]$ dropuser $OPENACS_SERVICE_NAME DROP USER [postgres pgsql]$ exit logout @@ -284,15 +284,15 @@ You can do this with standard backup processes or by keeping copies of the install material (OS CDs, OpenACS tarball and supporting software) and repeating the install - guide. Recreate the service user (service0). + guide. Recreate the service user ($OPENACS_SERVICE_NAME). Restore the OpenACS files and database backup file. - [root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver -[service0 aolserver]$ tar xzf /tmp/service0-backup.tar.gz -[service0 aolserver]$ chmod -R 775 service0 -[service0 aolserver]$ chown -R service0.web service0 + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ tar xzf /tmp/$OPENACS_SERVICE_NAME-backup.tar.gz +[$OPENACS_SERVICE_NAME aolserver]$ chmod -R 775 $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ chown -R $OPENACS_SERVICE_NAME.web $OPENACS_SERVICE_NAME Restore the database @@ -310,7 +310,7 @@ Invoke the import command - imp service0/service0 FILE=/var/lib/aolserver/service0/database-backup/nighty_backup.dmp FULL=Y + imp $OPENACS_SERVICE_NAME/$OPENACS_SERVICE_NAME FILE=/var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/nighty_backup.dmp FULL=Y @@ -320,32 +320,32 @@ If the database user does not already exist, create it. [root root]# su - postgres -[postgres ~]$ createuser service0 +[postgres ~]$ createuser $OPENACS_SERVICE_NAME Shall the new user be allowed to create databases? (y/n) y Shall the new user be allowed to create more new users? (y/n) y CREATE USER [postgres ~]$ exit Because of a bug in Postgres backup-recovery, database objects are not guaranteed to be created in the right order. In practice, running the OpenACS initialization script is always sufficient to create any out-of-order database objects. Next, restore the database from the dump file. The restoration will show some error messages at the beginning for objects that were pre-created from the OpenACS initialization script, which can be ignored. -[root root]# su - service0 -[service0 ~]$ createdb service0 +[root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME ~]$ createdb $OPENACS_SERVICE_NAME CREATE DATABASE -[service0 ~]$ psql -f /var/lib/aolserver/service0/packages/acs-kernel/sql/postgresql/postgresql.sql service0 +[$OPENACS_SERVICE_NAME ~]$ psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/postgresql.sql $OPENACS_SERVICE_NAME (many lines omitted) -[service0 ~]$ psql service0 < /var/lib/aolserver/service0/database-backup/database-backup.dmp +[$OPENACS_SERVICE_NAME ~]$ psql $OPENACS_SERVICE_NAME < /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup/database-backup.dmp (many lines omitted) -[service0 ~]$ exit +[$OPENACS_SERVICE_NAME ~]$ exit [postgres ~]$ exit logout Activate the service - [root root]# ln -s /var/lib/aolserver/service0/etc/daemontools /service/service0 + [root root]# ln -s /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/daemontools /service/$OPENACS_SERVICE_NAME [root root]# sleep 10 -[root root]# svgroup web /service/service0 +[root root]# svgroup web /service/$OPENACS_SERVICE_NAME @@ -354,13 +354,13 @@ Automated Backup - The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in /var/lib/aolserver/service0/database-backup and then backs up all of /var/lib/aolserver/service0 to a single zip file, and then copies that zip file to another computer. + The recommended backup strategy for a production sit is to use an automated script which first backs up the database to a file in /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup and then backs up all of /var/lib/aolserver/$OPENACS_SERVICE_NAME to a single zip file, and then copies that zip file to another computer. Make sure that the manual backup process described above works. - Customize the default backup script. Edit /var/lib/aolserver/service0/etc/backup.sh with your specific parameters. + Customize the default backup script. Edit /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh with your specific parameters. @@ -370,7 +370,7 @@ Set this file to run automatically by adding a line to root's crontab. (Typically, with export EDITOR=emacs; crontab -e.) This example runs the backup script at 1:30 am every day. - 30 1 * * * * sh /var/lib/aolserver/service0/etc/backup.sh + 30 1 * * * * sh /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc/backup.sh @@ -384,32 +384,32 @@ current system time, down to the minute. For maximum safety, you can apply a tag to your current files. You will still need to back up your database. - Note that, if you did the CVS options in this document, the /var/lib/aolserver/service0/etc directory is not included in cvs and you may want to add it. - [root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs commit -m "last-minute commits before upgrade to 4.6" + Note that, if you did the CVS options in this document, the /var/lib/aolserver/$OPENACS_SERVICE_NAME/etc directory is not included in cvs and you may want to add it. + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs commit -m "last-minute commits before upgrade to 4.6" cvs commit: Examining . cvs commit: Examining bin (many lines omitted) -[service0 service0]$ cvs tag before_upgrade_to_4_6 +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs tag before_upgrade_to_4_6 cvs server: Tagging bin T bin/acs-4-0-publish.sh T bin/ad-context-server.pl (many lines omitted) -[service0 service0]$ exit +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]# -su - service0 -cd /var/lib/aolserver/service0 +su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/$OPENACS_SERVICE_NAME cvs commit -m "last-minute commits before upgrade to 4.6" cvs tag before_upgrade_to_4_6 exit To restore files from a cvs tag such as the one used above: - [root root]# su - service0 -[service0 service0]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs up -r current -[service0 service0]$ exit -su - service0 -cd /var/lib/aolserver/service0 + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -r current +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit +su - $OPENACS_SERVICE_NAME +cd /var/lib/aolserver/$OPENACS_SERVICE_NAME cvs up -r current ($Id$) Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml,v diff -u -r1.23 -r1.24 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 10 May 2004 21:42:39 -0000 1.23 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/upgrade.xml 14 May 2004 14:10:28 -0000 1.24 @@ -57,19 +57,19 @@ name of OpenACS user - service0 + $OPENACS_SERVICE_NAME OpenACS server name - service0 + $OPENACS_SERVICE_NAME Root of OpenACS file tree - /var/lib/aolserver/service0 + /var/lib/aolserver/$OPENACS_SERVICE_NAME Database backup directory - /var/lib/aolserver/service0/database-backup + /var/lib/aolserver/$OPENACS_SERVICE_NAME/database-backup @@ -110,7 +110,7 @@ Stop the server - [root root]# svc -d /service/service0 + [root root]# svc -d /service/$OPENACS_SERVICE_NAME @@ -122,7 +122,7 @@ Start the server - [root root]# svc -u /service/service0 + [root root]# svc -u /service/$OPENACS_SERVICE_NAME @@ -149,7 +149,7 @@ When prompted, restart the server: - [root root]# restart-aolserver service0 + [root root]# restart-aolserver $OPENACS_SERVICE_NAME Wait a minute, then browse to the package manager, http://yourserver/acs-admin/apm. @@ -194,42 +194,42 @@ Upgrade the kernel manually. (There is a script to do most of the rest: /contrib/misc/upgrade_4.6_to_5.0.sh on HEAD). You'll still have to do a lot of stuff manually, but automated trial and error is much more fun.) - [root root]# su - service0 -[service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-kernel/sql/postgresql/upgrade + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-kernel/sql/postgresql/upgrade - Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql service0. Run the scripts in this order (order is tentative, not verified): + Manually execute each of the upgrade scripts in sequence, either from within psql or from the command line with commands such as psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME. Run the scripts in this order (order is tentative, not verified): - psql -f upgrade-4.6.3-4.6.4.sql service0 -psql -f upgrade-4.6.4-4.6.5.sql service0 -psql -f upgrade-4.6.5-4.6.6.sql service0 -psql -f upgrade-4.7d-4.7.2d.sql service0 -psql -f upgrade-4.7.2d-5.0d.sql service0 -psql -f upgrade-5.0d-5.0d2.sql service0 -psql -f upgrade-5.0d2-5.0d3.sql service0 -psql -f upgrade-5.0d6-5.0d7.sql service0 -psql -f upgrade-5.0d7-5.0d9.sql service0 -psql -f upgrade-5.0d11-5.0d12.sql service0 -psql -f upgrade-5.0.0a4-5.0.0a5.sql service0 -psql -f upgrade-5.0.0b1-5.0.0b2.sql service0 -psql -f upgrade-5.0.0b2-5.0.0b3.sql service0 -psql -f upgrade-5.0.0b3-5.0.0b4.sql service0 + psql -f upgrade-4.6.3-4.6.4.sql $OPENACS_SERVICE_NAME +psql -f upgrade-4.6.4-4.6.5.sql $OPENACS_SERVICE_NAME +psql -f upgrade-4.6.5-4.6.6.sql $OPENACS_SERVICE_NAME +psql -f upgrade-4.7d-4.7.2d.sql $OPENACS_SERVICE_NAME +psql -f upgrade-4.7.2d-5.0d.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0d-5.0d2.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0d2-5.0d3.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0d6-5.0d7.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0d7-5.0d9.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0d11-5.0d12.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0.0a4-5.0.0a5.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0.0b1-5.0.0b2.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0.0b2-5.0.0b3.sql $OPENACS_SERVICE_NAME +psql -f upgrade-5.0.0b3-5.0.0b4.sql $OPENACS_SERVICE_NAME Upgrade ACS Service Contracts manually: - [service0 aolserver]$ cd /var/lib/aolserver/ service0/packages/acs-service-contracts/sql/postgresql/upgrade -psql -f upgrade-4.7d2-4.7d3.sql service0 + [$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/ $OPENACS_SERVICE_NAME/packages/acs-service-contracts/sql/postgresql/upgrade +psql -f upgrade-4.7d2-4.7d3.sql $OPENACS_SERVICE_NAME Load acs-authentication data model. - psql -f /var/lib/aolserver/service0/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql service0 + psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/openacs-5/packages/acs-authentication/sql/postgresql/acs-authentication-create.sql $OPENACS_SERVICE_NAME Load acs-lang data model. - psql -f /var/lib/aolserver/service0/packages/acs-lang/sql/postgresql/acs-lang-create.sql service0 + psql -f /var/lib/aolserver/$OPENACS_SERVICE_NAME/packages/acs-lang/sql/postgresql/acs-lang-create.sql $OPENACS_SERVICE_NAME - (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create service0/tcl/zzz-postload.tcl containing: + (This step may overlap with the two previous steps, but I think it's harmless?) Create a file which will be executed on startup which takes care of a few issues with authentication and internationalization: create $OPENACS_SERVICE_NAME/tcl/zzz-postload.tcl containing: if {![apm_package_installed_p acs-lang]} { apm_package_install -enable -mount_path acs-lang [acs_root_dir]/packages/acs-lang/acs-lang.info lang::catalog::import -locales [list "en_US"] @@ -330,13 +330,13 @@ Upgrading files for a site which is not in a CVS repository Unpack the tarball into a new directory and copy its contents on top of your working directory. - [root root]# su - service0 -[service0 aolserver]$ cd /var/lib/aolserver -[service0 web]$ tar xzf /tmp/openacs-5-1.tar.gz -[service0 web]$ cp -r openacs-5-1/* openacs-4 -[service0 openacs-upgrade]$ exit + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME web]$ tar xzf /tmp/openacs-5-1.tar.gz +[$OPENACS_SERVICE_NAME web]$ cp -r openacs-5-1/* openacs-4 +[$OPENACS_SERVICE_NAME openacs-upgrade]$ exit [root root]# -su - service0 +su - $OPENACS_SERVICE_NAME cd /var/lib/aolserver tar xzf /tmp/openacs-5-1.tgz cp -r openacs-5-1/* openacs-4 @@ -366,10 +366,10 @@ (a): via tarball Download a current tarball and unpack the new files into a working directory. - [root root]# su - service0 -[service0 aolserver]$ cd /tmp -[service0 tmp]$ tar xzf openacs-5-1.tar.gz -[service0 tmp]$ cd openacs-5-1 + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /tmp +[$OPENACS_SERVICE_NAME tmp]$ tar xzf openacs-5-1.tar.gz +[$OPENACS_SERVICE_NAME tmp]$ cd openacs-5-1 @@ -380,26 +380,26 @@ packages you are using. - [root root]# su - service0 -[service0 aolserver]$ cd /var/lib/aolserver -[service0 aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core -[service0 aolserver]$ cd openacs-4/packages -[service0 aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... -[service0 aolserver]$ cd ../.. -[service0 aolserver]$ mv openacs-4 openacs-5-1 + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat acs-core +[$OPENACS_SERVICE_NAME aolserver]$ cd openacs-4/packages +[$OPENACS_SERVICE_NAME aolserver]$ cvs -d :pserver:anonymous@openacs.org:/cvsroot checkout -r openacs-5-1-compat packagename packagename2... +[$OPENACS_SERVICE_NAME aolserver]$ cd ../.. +[$OPENACS_SERVICE_NAME aolserver]$ mv openacs-4 openacs-5-1 If this checkout already exists, you can simply update it instead of recreating it. - [root root]# su - service0 -[service0 aolserver]$ cd /var/lib/aolserver/openacs-5-1 -[service0 aolserver]$ cvs up -Pd + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 +[$OPENACS_SERVICE_NAME aolserver]$ cvs up -Pd (c) A single package via cvs working checkout You can add or upgrade a single package at a time, if you already have a cvs working directory. - [root root]# su - service0 -[service0 aolserver]$ cd /var/lib/aolserver/openacs-5-1 -[service0 openacs-5-1]$ cvs up -d myfirstpackage + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-1 +[$OPENACS_SERVICE_NAME openacs-5-1]$ cvs up -d myfirstpackage In the next section, the import must be tailored to just this package. @@ -411,36 +411,36 @@ Import the new files into your cvs repository; where they match existing files, they will become the new version of the file. - [service0 openacs-5-1]$ cd /var/lib/aolserver/openacs-5-1 - [service0 openacs-5-1]$ cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" service0 OpenACS openacs-5-1 + [$OPENACS_SERVICE_NAME openacs-5-1]$ cd /var/lib/aolserver/openacs-5-1 + [$OPENACS_SERVICE_NAME openacs-5-1]$ cvs -d /var/lib/cvs import -m "upgrade to OpenACS 5.1" $OPENACS_SERVICE_NAME OpenACS openacs-5-1 If adding or upgrading a single package, run the cvs import from within the base directory of that package, and adjust the cvs command accordingly. In this example, we are adding the myfirstpackage package. - [root root]# su - service0 -[service0 aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage -[service0 myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" service0/packages/myfirstpackage OpenACS openacs-5-1 + [root root]# su - $OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME aolserver]$ cd /var/lib/aolserver/openacs-5-0/package/myfirstpackage +[$OPENACS_SERVICE_NAME myfirstpackage]$ cvs -d /var/lib/cvs/ import -m "importing package" $OPENACS_SERVICE_NAME/packages/myfirstpackage OpenACS openacs-5-1 Create a new directory as temporary working space to reconcile conflicts between the new files and your current work. The example uses the cvs keyword yesterday, making the assumption that you haven't checked in new code to your local tree in the last day. - [service0 openacs-4.6]$ cd /var/lib/aolserver -[service0 tmp]$ mkdir service0-upgrade -[service0 tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS -kk service0 > cvs.txt 2>&1 + [$OPENACS_SERVICE_NAME openacs-4.6]$ cd /var/lib/aolserver +[$OPENACS_SERVICE_NAME tmp]$ mkdir $OPENACS_SERVICE_NAME-upgrade +[$OPENACS_SERVICE_NAME tmp]$ cvs checkout -d openacs-upgrade -jOpenACS:yesterday -jOpenACS -kk $OPENACS_SERVICE_NAME > cvs.txt 2>&1 (CVS feedback here) The file /tmp/openacs-upgrade/cvs.txt contains the results of the upgrade. If you changed files that are part of the OpenACS tarball and those changes conflict with the 4.5-4.6 upgrade, you'll have to manually reconcile them. Use the emacs command M-x sort-lines and then, for each line that starts with a C, open that file and manually resolve the conflict by deleting the excess lines. When you're finished, or if there aren't any conflicts, save and exit. Once you've fixed any conflicts, commit the new code to your local tree. - [service0 tmp]$ cd openacs-upgrade -[service0 openacs-upgrade]$ cvs commit -m "Upgraded to 4.6" + [$OPENACS_SERVICE_NAME tmp]$ cd openacs-upgrade +[$OPENACS_SERVICE_NAME openacs-upgrade]$ cvs commit -m "Upgraded to 4.6" Step 3: Upgrade your local staging site Update your working tree with the new files. The CVS flags ensure that new directories are created and pruned directories destroyed. -[service0 openacs-upgrade]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs up -Pd +[$OPENACS_SERVICE_NAME openacs-upgrade]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) -[service0 service0]$ exit +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit [root root]# @@ -451,10 +451,10 @@ - [service0 ~]$ cd /var/lib/aolserver/service0 -[service0 service0]$ cvs up -Pd + [$OPENACS_SERVICE_NAME ~]$ cd /var/lib/aolserver/$OPENACS_SERVICE_NAME +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ cvs up -Pd (CVS feedback) -[service0 service0]$ +[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ @@ -473,10 +473,10 @@ 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 - service0 CVS tree, as described in "Upgrading a local CVS repository", step 1, above. + $OPENACS_SERVICE_NAME CVS tree, as described in "Upgrading a local CVS repository", step 1, above. As soon as we do this, any cvs update command on production might bring new code onto the production site, which would be bad. - Do step 2 above (merging conflicts in a service0-upgrade working tree). + Do step 2 above (merging conflicts in a $OPENACS_SERVICE_NAME-upgrade working tree). @@ -485,20 +485,20 @@ Use the upgrade script and a recent backup of the production database, to ake - a new upgraded database called service0-upgrade. Now we - have a new website called service0-upgrade. + a new upgraded database called $OPENACS_SERVICE_NAME-upgrade. Now we + have a new website called $OPENACS_SERVICE_NAME-upgrade. - Test the service0-upgrade site + Test the $OPENACS_SERVICE_NAME-upgrade site - If service0-upgrade is fully functional, do the real upgrade. + If $OPENACS_SERVICE_NAME-upgrade is fully functional, do the real upgrade. - Take down the service0 site and put up a "down for maintenance" page. + Take down the $OPENACS_SERVICE_NAME site and put up a "down for maintenance" page. Repeat the upgrade with the most recent database @@ -520,7 +520,7 @@ OpenACS Full Text Search requires several pieces: the OpenFTS code, some database functions, and the OpenFTS Engine. This section describes how to upgrade OpenFTS from 0.2 to 0.3.2 and upgrade the search engine on an OpenACS site at the same time. - Uninstall the old OpenFTS Engine from the service0 database. + Uninstall the old OpenFTS Engine from the $OPENACS_SERVICE_NAME database. Browse to http://yourserver/openfts. @@ -557,19 +557,19 @@ make install exit In order for the OpenACS 4.6 OpenFTS Engine to use the OpenFTS 0.3.2 driver, we need some commands added to the database. - [root root]# su - service0 - [service0 dev]$ psql service0 -f /usr/local/pgsql/share/contrib/openfts.sql + [root root]# su - $OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql CREATE CREATE - [service0 dev]$ psql service0 -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql + [$OPENACS_SERVICE_NAME dev]$ psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql BEGIN CREATE (~30 more lines) - [service0 dev]$ exit + [$OPENACS_SERVICE_NAME dev]$ exit [root root]# - su - service0 -psql service0 -f /usr/local/pgsql/share/contrib/openfts.sql -psql service0 -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql + su - $OPENACS_SERVICE_NAME +psql $OPENACS_SERVICE_NAME -f /usr/local/pgsql/share/contrib/openfts.sql +psql $OPENACS_SERVICE_NAME -f /usr/local/src/postgresql-7.2.3/contrib/tsearch/tsearch.sql exit @@ -593,7 +593,7 @@ Click Set Parameters - [root root]# restart-aolserver service0 + [root root]# restart-aolserver $OPENACS_SERVICE_NAME Browse to http://yourserver/openfts @@ -619,27 +619,27 @@ casting commands that no longer work in 7.3 and these functions must be recreated. - To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/service0/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example: + To upgrade an OpenACS site from PostGreSQL 7.2 to 7.3, first upgrade the kernel to 4.6.3. Then, dump the database, run the upgrade script /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin/pg_7.2to7.3_upgrade_helper.pl on the dump file, and reply the dump. See Forum OpenACS Q&A: PG 7.2->7.3 upgrade gotcha?. Example: Back up the database as per . Run the upgrade script on the backup file. - [root root]# su - service0 - [service0 service0]# cd /var/lib/aolserver/service0/bin - [service0 bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ + [root root]# su - $OPENACS_SERVICE_NAME + [$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]# cd /var/lib/aolserver/$OPENACS_SERVICE_NAME/bin + [$OPENACS_SERVICE_NAME bin]$ ./pg_7.2to7.3_upgrade_helper.pl \ ../database-backup/nightly.dmp \ ../database-backup/upgrade-7.3.dmp \ - /var/lib/aolserver/service0 + /var/lib/aolserver/$OPENACS_SERVICE_NAME ================================================================== looking for function acs_object__check_object_ancest in oacs grep result: /var/lib/aolserver/aufrecht-dev/packages/acs-kernel/sql/postgresql/acs-objects-create.sql:create function acs_object__check_object_ancestors (integer,integer,integer) replacing acs_object__check_object_ancest with acs_object__check_object_ancestors (many lines omitted) - [service0 bin]$ + [$OPENACS_SERVICE_NAME bin]$ @@ -670,7 +670,7 @@ Change the path in - service0's .bashrc or + $OPENACS_SERVICE_NAME's .bashrc or .bash_profile (or both) files to reflect the new postgres73 user directory. Also add in the PGPORT.