| +Prev� | +Chapter 1. High level information: What is OpenACS? | +�Next + | +
|---|
+
+ Compared to its predecessors, version 4 of OpenACS has a much + more structured organization, i.e. the most + significant change is found at the system architecture level, + reflected in the following hierarchy: +
+The
The
+
+ This document provides a high level overview of the kernel + package. Documentation for the other packages can be found elsewhere. +
+Table of Contents
++ According to Philip Greenspun: +
++ “The ArsDigita Community System it is a toolkit of software + that will help you build Web services with a collaborative dimension, + ranging from knowledge management within companies to B2C ecommerce + to product support and community among the customers. The software is + free and open-source and has been tested in heavy use since + 1995.” +
++ So that's what the ArsDigita Community System (ACS) is... what's + OpenACS? OpenACS was born when Don Baccus, Ben Adida, et al decided + to port ACS from Oracle to PostgreSQL, thus making it a fully + open-source solution. +
++ OpenACS 4 is the next generation of the web toolkit. It's based on + ACS 4, but no longer follows ArsDigita development. Unlike both ACS + (which required Oracle) and OpenACS 3.x (which required PostgreSQL), + OpenACS 4 allows you to use either database. It's also built in such + a way to allow enterprising hackers to extend it to other + databases. Don Baccus leads the development and numerous developers + (and non-developers) contribute from around the world. +
++ This document will describe how to install OpenACS 4 from scratch, + using the source code. We will assume that you have an OS installed, + but we'll discuss this more in the next section. For most of this + guide, we will assume that you are using Linux on a PC, but we'll + also point you to excellent step-by-step guides for other operating + systems. +
++ You will need a PC (or equivalent) with at least these minimum + requirements: +
+Pentium processor
128 MB RAM + (much more if you want Oracle)
4 GB hard drive
+ If you want to serve pages to people outside of your machine, you'll + need a network connection of some type. +
++ Note that these are minimum requirements to get a development system + up and running. For a production system, we recommend you read about + the ArsDigita + Server Architecture +
++ Running a reliable database-backed web server requires experience + with the server's environment, in this case UNIX. UNIX is not always + an intuitive environment and this guide cannot hope to explain every + nuance. You should be comfortable with the following tasks before + attempting an installation: +
++ Adding users, groups, setting passwords +
+ Starting an X server and running an X program remotely +
+ Basic file management using cp, rm, + mv, and cd +
+ Compiling a program using a Makefile +
+ If you've never done these things before, consider exploring UNIX in + greater depth before installing OpenACS. Some useful resources for + doing this are described in the Resources + section. +
++ All of the software that you will need is free and open-source, + except for Oracle. You can obtain a free copy of Oracle for + development purposes. This is described in the Acquire Oracle section. +
++ The basic steps to getting OpenACS up and running are: +
+Install an OS
Install a webserver (AOLServer)
Install a database (Oracle or + PostgreSQL)
Install a database + driver (allows the webserver to talk to the database) +
Configure the webserver and + database
Start the OpenACS + installer
+ We'll do our best to assure that following our instructions will get + you to the promised land. If something goes wrong, don't + panic. There's plenty of ways to get help. Here are some tips: +
++ Make sure that you keep track of what commands you are running + and their output. I like to do my installations in a shell inside + of emacs (M-x shell) so that I can save the output if needed. +
+ We'll point out where the error logs for the various pieces of + software are. Output from those logs will help us help you. Don't + worry if you feel overwhelmed by all the information in the error + logs. Over time, you'll find that they make more and more + sense. Soon, you'll actually look forward to errors so that you + can run to the log and diagnose the problem. +
+ Search the bboards at + openacs.org - you'll often find many people who have + struggled through the same spot that you're in. +
+ Ask questions at the irc channel on openprojects.net + (#openacs). They're knowledgeable and quite friendly if you can + keep them on topic. +
+ Post a question on the bboards. Make sure + you've done a search first. When you do post, be sure to include + your setup information (OS, etc) as well as the exact commands + that are failing with the accompanying error. If you want to post + stuff from your logs (please do!), be sure to enclose them in + <PRE></PRE> tags so that they don't get all jumbled + together. +
+ If you find errors in this document or if you have ideas about + making it better, please post them in our bug tracker - the + SDM. +
+ After reading through this tome, you may ask yourself if there is a + better way. And there is! Jonathan Marsden has done all the dirty + work to create RPMs for OpenACS4. These RPMs will install AOLServer, + all the AOLServer modules, PostgreSQL and OpenACS4 simply by typing + one magic command. They're currently at http://www.xc.org, + but will eventually also be available at http://openacs.org/software. They're + quite new and Jonathan invites (and is quite responsive to) + feedback. Leave comments at this thread. +
++ This document was created by Vinod Kurup, but it's really + just plagiarism from a number of documents that came before it. If + I've used something that you've written without proper credit, let me + know and I'll fix it right away. +
+These are a few of my sources:
++ Please also see the Credits section for more acknowledgements. +
++ Here are some resources that OpenACS users have found useful. +
++ + Philip + and Alex's Guide to Web Publishing - A very readable + guide to database-backed community websites. + +
+ + UNIX + Power Tools - An excellent introduction to the + command line tools and basic programs of UNIX + +
+ + UNIX + System Administration Handbook (formerly the "red book" + - now the "purple" book) + +
+ + UNIX + System Administrator's Bible - (LePage and Iarerra 1998; + IDG) + +
+ + Running + Linux
+ + Linux + in a Nutshell + +
+ + The UNIX + Reference Desk + +
Here are some tips from Don Baccus regarding backup strategy:
++ The need for making backups should be self-explanatory. There are + several strategies you can use. My own strategy for minimizing the + odds that I'll lose all my data is quite simple: +
++ The database is stored on a mirrored (RAID 1) disk. +
+ The machine has battery backup. +
+ Backups are made nightly onto a third disk on another controller +
+ FTP is used to copy the resulting backup to two separate remote + servers in two locations +
+ Rather than making remote copies, you might choose to dump to tape or + writeable CD media. Whatever strategy you use, it is important to + routinely check dumps to make sure they can be reloaded. The strategy + outlined above means that in the case of catastrophic failure, I'll + lose at most one day's data. + + By mirroring disks and using a battery backup, preferably one that + can trigger an automatic and controlled shutdown of the system when + the battery runs low, you greatly lower the odds of ever having to + use your nightly backup. Despite this, it is important to take + backups seriously if the data stored at your site is valuable to you + or your users. +
++ While you're working with Oracle, you should configure it to do + automatic exports. An export is a separate backup copy of the + database. This copy includes all of the database's state at the + time that the export was initiated. If your database is corrupted, + you can restore from one of these backups. You should do this step as + root. +
++ Download the backup script. Save the file export-oracle.txt as + /tmp/export-oracle.txt +
+ Login as root. The following commands will install the export script: +
++nsadmin:~$ su - +Password: *********** +root:~# cp /tmp/export-oracle.txt /usr/sbin/export-oracle +root:~# chmod 700 /usr/sbin/export-oracle+
+ Setup the export directory; this is the directory where backups will + be stored. We recommend the directory + /ora8/m02/oracle-exports.
++root:~# mkdir /ora8/m02/oracle-exports +root:~# chown oracle.dba /ora8/m02/oracle-exports +root:~# chmod 770 /ora8/m02/oracle-exports+
+ Now edit + /usr/sbin/export-oracle and + change the SERVICE_NAME and + DATABASE_PASSWORD fields to + their correct values. If you want to use a directory other than + /ora8/m02/oracle-exports, you + also need to change the + exportdir setting. +
++ Test the export procedure by running the command: +
++root:~# /usr/sbin/export-oracle +mv: /ora8/m02/oracle-exports/oraexport-service_name.dmp.gz: No such file or directory + +Export: Release 8.1.6.1.0 - Production on Sun Jun 11 18:07:45 2000 + +(c) Copyright 1999 Oracle Corporation. All rights reserved. + + +Connected to: Oracle8i Enterprise Edition Release 8.1.6.1.0 - Production +With the Partitioning option +JServer Release 8.1.6.0.0 - Production +Export done in US7ASCII character set and US7ASCII NCHAR character set +. exporting pre-schema procedural objects and actions +. exporting foreign function library names for user SERVICE_NAME +. exporting object type definitions for user SERVICE_NAME +About to export SERVICE_NAME's objects ... +. exporting database links +. exporting sequence numbers +. exporting cluster definitions +. about to export SERVICE_NAME's tables via Conventional Path ... +. exporting synonyms +. exporting views +. exporting stored procedures +. exporting operators +. exporting referential integrity constraints +. exporting triggers +. exporting indextypes +. exporting bitmap, functional and extensible indexes +. exporting posttables actions +. exporting snapshots +. exporting snapshot logs +. exporting job queues +. exporting refresh groups and children +. exporting dimensions +. exporting post-schema procedural objects and actions +. exporting statistics +Export terminated successfully without warnings.+
If you don't have any warnings, proceed to automate the + backups.
++ Automating backups is accomplished using the UNIX + crontab facility.
++ While still root, run the + following command. You can replace the + EDITOR="emacs -nw" + portion with whatever editor your prefer, such as + EDITOR=vi. +
++root:~# export EDITOR="emacs -nw" +root:~# crontab -e+
Now add the following line on a line by itself
++0 23 * * * /usr/sbin/export-oracle+
+ Save the file, exit the editor. Verify that the addition + succeeded by checking the output of the following command.
++root:~# crontab -l | grep export-oracle +0 23 * * * /usr/sbin/export-oracle +root:~# exit +; Logout+
If you see the line, go ahead and log out.
++ Dowload this script + to /tmp. At the top of the script + are several variables that you'll need to customize: +
++ bak - location where you want + local backups to be saved +
+ servername - name of your server + (and database instance) +
+ ftp_user - username on your ftp + account +
+ ftp_password - password on your + ftp account +
+ ftp_dir - path on the remote + server where your backups will be uploaded +
+ ftp_server - your ftp server +
+ + Next, we'll save this file to our server's + tcl directory so that it will be + loaded on startup. It will automatically be run every night at + midnight. Note that this script only backs up the database - not the + OpenACS scripts and file content. +
++nsadmin:~$ cp /tmp/acs-pgbackup-init.txt /web/birdnotes/tcl/acs-pgbackup-init.tcl +nsadmin:~$ restart-aolserver birdnotes+
+ That's it! The script will email you with each successful backup (or + if it fails, it will send you an email with the reason) +
++ The "vacuum" command must be run periodically to reclaim space. The + "vacuum analyze" form additionally collects statistics on the + disbursion of columns in the database, which the optimizer uses when + it calculates just how to execute queries. The availability of this + data can make a tremendous difference in the execution speed of + queries. This command can also be run from cron, but it probably makes + more sense to run this command as part of your nightly backup + procedure - if "vacuum" is going to screw up the database, you'd + prefer it to happen immediately after (not before!) you've made a + backup! The "vacuum" command is very reliable, but conservatism is + the key to good system management. So, if you're using the export + procedure described above, you don't need to do this extra step. +
+Edit your crontab:
++nsadmin:~$ crontab -e+
We'll set vacuum up to run nightly at 1 AM. Add the following + line:
++0 1 * * * /usr/local/pgsql/bin/vacuumdb birdnotes+
Starting another server is simply a matter of configuring another + aolserver instance, creating another database and pointing this + aolserver instance at a fresh copy of the OpenACS-4 code. We'll call + our new server birdnotes-dev +
++ Download another copy of openacs4.tcl.txt + into /tmp.
++nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes-dev.tcl +nsadmin:~$ chmod 660 birdnotes-dev.tcl +nsadmin:~$ emacs birdnotes-dev.tcl+
Just like in the section called “Configuring AOLserver”, + you'll need to set the server parameters appropriately. Be sure to + choose a different port than your original server and to set + server to + birdnotes-dev.
++ + Create a new database instance called + birdnotes-dev. Follow the instructions in + Prepare Oracle for OpenACS or Prepare PostgreSQL for OpenACS. + +
+ + You can either copy your current OpenACS installation: +
++nsadmin:~$ cd /web +nsadmin:~$ cp -r birdnotes birdnotes-dev+
+ Or Download the OpenACS + 4 software into /tmp again. +
++nsadmin:~$ cd /web +nsadmin:/web$ tar xzvf /tmp/alpha2.tgz +nsadmin:/web$ mv openacs-4 birdnotes-dev+
+ Start your new server! +
+
+nsadmin:/web$ cd
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes-dev.tcl
++ Visit the site with a web browser (using the port that you set + above). You should see the OpenACS installer. Once you install + the OpenACS datamodel, you'll also need to add your new aolserver + instance to /etc/inittab (or + daemontools) so it restarts automatically.
++ OpenACS uses the OpenFTS package to + implement site-wide-search. You'll need to have the Tcl development + libraries and headers installed. (Debian users: + apt-get install tcl8.3-dev) +
++ As root, download the + Search-OpenFTS driver. +
++nsadmin:~$ su - +Password: ********** +root:~# cd /tmp +root:/tmp# wget http://prdownloads.sourceforge.net/openfts/Search-OpenFTS-tcl-0.2.tar.gz +root:~# cd /usr/local/src +root:/usr/local/src# tar xzf /tmp/Search-OpenFTS-tcl-0.2.tar.gz +root:/usr/local/src# chown -R nsadmin.web Search-OpenFTS-tcl-0.2 +root:/usr/local/src# exit+
+ Configure it. Note that you may need to set + --with-tcl=(your Tcl library + location). For Debian, add this to the end of the + ./configure command: + --with-tcl=/usr/lib/tcl8.3 +
++nsadmin:~$ cd /usr/local/src/Search-OpenFTS-tcl-0.2 +nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ ./configure --with-aolserver-src=/usr/local/src/aolserver/aolserver+
+ In order to compile on Debian, I had to edit my + Makefile.global. Add + -I/usr/include/tcl8.3 to the + line where INC is defined, so it looks like this: +
++INC = ../include -I/usr/include/tcl8.3+
Then compile it:
++nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ make +nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2$ cd aolserver +nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ make+
+ Install it. You need to do this step as root since some of the + libraries will be installed alongside your TCL libraries and some + alongside your PostgreSQL libraries. +
++nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ su - +Password: *********** +root:~# cd /usr/local/src/Search-OpenFTS-tcl-0.2 +root:/usr/local/src/Search-OpenFTS-tcl-0.2# make install +root:/usr/local/src/Search-OpenFTS-tcl-0.2# exit +nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cp nsfts.so /usr/local/aolserver/bin/+
+ Add the following line to your aolserver config file (in our + example: + /usr/local/aolserver/birdnotes.tcl) + in the "ns_section ns/server/${server}/modules" section: +
+
+ ns_param nsfts ${bindir}/nsfts.so
++ Load the openFTS code into your database: +
++nsadmin:/usr/local/src/Search-OpenFTS-tcl-0.2/aolserver$ cd +nsadmin:~$ psql -f /web/birdnotes/packages/openfts-driver/sql/postgresql/load.sql birdnotes +nsadmin:~$ restart-aolserver birdnotes+
+ Open a browser and go to your server + (http://yourserver:port). Click on the "Package Manager" link in + the "Quick Links" section on the right side of the page. +
+ Click on the "Install packages" link and follow the instructions + to install the Note package and the OpenFTS Driver 4.2 package. +
+ Restart your server. + +
+nsadmin:~$ restart-aolserver birdnotes
+ + Give the server a few minutes to restart and then go back to your + server's front page and click on "Site Map" from the "Quick + Links" +
+ Create a "new sub folder" under "Main Site". Call the url + "openfts". +
Click "mount" to mount the OpenFTS driver at the url + "openfts" (despite what the system says about these packages not + being meant to be mounted) +
+ Create another folder under "Main Site" at the url + "search". Create a "new application". Call the application + "Search" and choose the "Search" package from the drop-down list. +
+ Create a third folder under "Main Site" at the url + "notes". Create a "new application". Call the application "Notes" + and choose the "Note" package from the drop-down list. +
+ Restart the server. +
+ Return to your home page. Near the bottom of the page, Click on + the "OpenFTS Driver" link. Then click on + "Administration". Finally, click on "Initialize OpenFTS + Engine". Accept the defaults and continue. +
+ Click on the "Main Site" link to get back to the home page. Now, + click on the "ACS Service Contract" link near the bottom of the + home page. +
+ Click on the link to "install" the FtsEngineDriver. Also, click + the link to install the Note content provider. +
+ Restart the server. You can try inserting some notes and then + going to the search page to search for stuff. Note that the + content may not get indexed immediately, so give it a few + minutes. +
Download the OpenACS 4 software + to the /tmp directory: +
+ Login as nsadmin and untar the + downloaded components into /web + directory. The alpha-2 tarball is currently named + alpha2.tgz. Replace + alpha2.tgz in the commands below + with whatever the current tarball is named. +
++joeuser:~$ su - nsadmin +Password: *********** +nsadmin:~$ cd /web +nsadmin:/web$ tar xzf /tmp/alpha2.tgz+
+ You should now have an + openacs-4/ directory tree in + /web. Rename this directory to + whatever you want your web service to be identified as. The name + of your web service is referred to as the + service_name. Since you can run multiple + separate web services under AOLserver, this identification is + used internally by AOLserver to differentiate your services from + one another. 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 + "birdnotes" might be the service name for the birdnotes.net + community. We'll use birdnotes as an example + in these docs. +
+
+nsadmin:/web$ ls -l
+total 4
+drwxr-xr-x 8 nsadmin nsadmin 4096 Nov 27 09:32 openacs-4
+nsadmin:/web$ mv openacs-4 birdnotes
+nsadmin:/web$ ls -l
+total 4
+drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotes
++ Skip ahead if you want to Prepare PostgreSQL for OpenACS +
+You should be logged on as + nsadmin for this step and you should + make sure that nsadmin is in the + dba group.
++ Verify nsadmin membership by typing + groups when you login: + +
+nsadmin:~$ groups +nsadmin dba web+ + If you do not see these groups, take the following action: + +
+nsadmin:~$ su - +Password: ************ +root:~# usermod -g nsadmin -G dba,web nsadmin+ + If you get an error about an undefined group, then add that group + manually: + +
+root:~# groupadd dba +root:~# groupadd nsadmin +root:~# groupadd web+ + Make sure to logout as root when + you are finished with this step and log back in as + nsadmin. +
+ Connect to Oracle using + svrmgrl and login: + +
+nsadmin:~$ svrmgrl + +SVRMGR> connect internal +Connected.+
+ Determine where the system tablespaces are stored: + +
+SVRMGR> select file_name from dba_data_files;+ Example results: + +
+/ora8/m01/app/oracle/oradata/ora8/system01.dbf +/ora8/m01/app/oracle/oradata/ora8/tools01.dbf +/ora8/m01/app/oracle/oradata/ora8/rbs01.dbf +/ora8/m01/app/oracle/oradata/ora8/temp01.dbf +/ora8/m01/app/oracle/oradata/ora8/users01.dbf +/ora8/m01/app/oracle/oradata/ora8/indx01.dbf +/ora8/m01/app/oracle/oradata/ora8/drsys01.dbf+
+ Using the above output, you should determine where + to store your tablespace. As a general rule, you'll want to + store your tablespace on a mount point under the + /ora8 directory that is separate + from the Oracle system data files. By default, the Oracle system + is on m01, so we will use + m02. This enables your Oracle + system and database files to be on separate disks for optimized + performance. For more information on such a configuration, see + Chapter + 12 of Philip's + book. For this example, we'll use + /ora8/m02/oradata/ora8/. +
+ Create the directory for the datafile; to do this, + exit from svrmgrl and login as + root for this step:
++SVRMGR> exit +nsadmin:~$ su - +Password: ************ +root:~# mkdir -p /ora8/m02/oradata/ora8/ +root:~# chown nsadmin.web /ora8/m02/oradata/ora8 +root:~# chmod 775 /ora8/m02/oradata/ora8 +root:~# exit +nsadmin:~$+
+ As nsadmin, create a tablespace for + the service. It is important that the tablespace can + autoextend. This allows the + tablespace's storage capacity to grow as the size of the data + grows. We set the pctincrease to be a very low value so that our + extents won't grow geometrically. We do not set it to 0 at + the tablespace level because this would affect Oracle's + ability to automatically coalesce free space in the + tablespace.
++nsadmin:~$ svrmgrl + +SVRMGR> connect internal; +SVRMGR> create tablespace birdnotes datafile '/ora8/m02/oradata/ora8/birdnotes01.dbf' size 50m autoextend on default storage (pctincrease 1);+
+ Create a database user for this service. Give the + user access to the tablespace and rights to connect. We'll use + birdnotespassword as our password.
++ Write down what you specify as service_name + (i.e. birdnotes) and + database_password + (i.e. birdnotespassword). You + will need this information for configuring exports and + AOLserver. +
++SVRMGR> create user birdnotes identified by birdnotespassword default tablespace birdnotes +temporary tablespace temp quota unlimited on birdnotes; +SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to birdnotes; +SVRMGR> revoke unlimited tablespace from birdnotes; +SVRMGR> alter user birdnotes quota unlimited on birdnotes; +SVRMGR> exit;+
+ Your table space is now ready. In case you are trying to delete a + previous OpenACS installation, consult these commands in the section called “Deleting a tablespace” below. +
++ Make sure that you can login to Oracle using your + service_name account:
++nsadmin:~$ sqlplus birdnotes/birdnotespassword +SQL> select sysdate from dual; + +SYSDATE +---------- +2001-12-20 + +SQL> exit+
+ You should see today's date in a format 'YYYY-MM-DD.' + If you can't login, try redoing step 1 again. If the date is + in the wrong format, make sure you followed the steps outlined in + the section called “Troubleshooting Oracle Dates” +
++ Next we'll set up AOLserver so that it has the proper environment + variables set before launching. Download this nsd-oracle script into + /tmp/nsd-oracle.txt : +
++nsadmin:~$ cp /tmp/nsd-oracle.txt ./bin/nsd-oracle +nsadmin:~$ chmod 700 ./bin/nsd-oracle+
+ Preparing PostgreSQL is just a little bit simpler than preparing + Oracle. We simply need to create a database with the name of our + service-name + (i.e. birdnotes) +
+
+nsadmin:/web$ createdb birdnotes
+CREATE DATABASE
+Next we'll set up AOLserver so that it has the proper environment + variables set before launching. Download this nsd-postgres script into + /tmp/nsd-postgres.txt :
++nsadmin:/web$ cd +nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres +nsadmin:~$ chmod 700 ./bin/nsd-postgres+
+ The AOLserver architecture lets you run an arbitrary number of + virtual servers. A virtual server is an HTTP service running on a + specific port, e.g. port 80. In order for the OpenACS to work, you + need to configure a virtual server. Because the process is involved, + we have prepared a sample virtual server configuration file. +
++ Download openacs4.tcl.txt + into /tmp. +
+ Modify it for your needs and save it in + /usr/local/aolserver/birdnotes.tcl + (Of course change birdnotes to + whatever you're using as your service-name +
+nsadmin:~$ cp /tmp/openacs4.tcl.txt ./birdnotes.tcl +nsadmin:~$ chmod 660 birdnotes.tcl +nsadmin:~$ emacs birdnotes.tcl+
+ Specifically, you'll have set the following variables +
++ server - This is the name of + the directory where your code resides. In our example above, we + used birdnotes. +
+db_name - In almost all cases, + this can be kept as a reference to $server. If for some reason, + the tablespace you are using is different than your servername, + then you can set it here. You should have a good reason for doing + this. +
+ servername - This is just a + *pretty* name for your server. For example, we might call ours + "Birdnotes.net Community" +
+httpport - If you want your + server on a different port, enter it here
+ AOLServer is very configurable. These settings should get you + started, but for more options, read the AOLServer + docs. +
++ Kill any current running AOLserver processes and start a new + one. (Note, if you are using Oracle, rather than PostgreSQL, replace + nsd-postgres with + nsd-oracle):
+
+nsadmin:~$ killall nsd
+; Should probably see:
+nsd: no process killed
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl
++ Attempt to connect to the service from a web browser as you did + in the Test AOLserver section. You should + specify a URL like: +
++http://ip_name:ip_port/+
+ You should see a page that looks like this - if so, go on to Using the OpenACS Installer. +
++ If you don't see the login page, view your error log + (/usr/local/aolserver/logs/birdnotes-error.log) + to make sure the service is starting without any problems. If you + need to make changes, don't forget to kill any running + servers. +
++nsadmin:~$ killall nsd+
+ Now that you've got AOLserver up and running, let's install OpenACS + 4. +
++ You should see a page from the webserver titled + OpenACS Installation: + Welcome. You will be warned if your version of + the database driver is out of date, if AOLserver cannot connect + to the database, if any modules are missing or out-of-date, or if + there are any problems with filesystem permissions on the server + side. But if everything is fine, you can click + Next to proceed to load the + OpenACS Kernel data model. +
+ The next page shows the results of loading the OpenACS Kernel + data model - be prepared to wait a few minutes as it works. You + should see a string of "No errors." as the tables are + created. You'll see the line: +
++Loading package .info files ... this will take a few minutes+
+ This will really take a few minutes. Have faith! Finally, + another Next button will appear at + the bottom - click it. +
++ The following page shows the results of loading the package data + models. You should see positive results for each of the + previously selected packages, but watch out for any + errors. Eventually, the page will display "Generating secret + tokens" and then "Done"- click + Next. +
+ You should see a page, "OpenACS Installation: Create + Administrator" with form fields to define the OpenACS site + administrator. Fill out the fields as appropriate, and click + Create User. +
+ You should see a page, "OpenACS Installation: Set System + Information" allowing you to name your service. Fill out the + fields as appropriate, and click Set System + Information +
+ You'll see the final Installer page, "OpenACS + Installation: Complete." It will tell you that the server is + being restarted; note that unless you already set up a way for + AOLServer to restart itself (ie. inittab or daemontools), + you'll need to manually restart your service. +
+
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl
++ Give the server a few minutes to start up. Then + reload the final page above. You should see the front page, with + an area to login near the upper right. Congratulations, OpenACS + 4 is now up and running! +
+ Now, we'll describe how to start AOLserver automatically on boot, + or whenever else the service dies. +
++ There are 2 ways of doing this - via inittab or via daemontools. The + second way is by far the better way. Using daemontools gives you much + finer control over your servers and avoids the hassle of messing with + /etc/inittab. But, we'll describe + the inittab way as this may be easier for some users. I encourage + everyone to follow the links provided which describe how to Install daemontools. +
++Important: You need to set up + either inittab or daemontools, not both!
++ This step should be completed as root. This can break every service + on your machine, so proceed with caution. +
++ There are 2 general steps to getting this working. +
++ Install a script called + restart-aolserver. This + script doesn't actually restart AOLserver - it just kills + it. +
+ Ask the OS to restart our service whenever it's not + running. We do this by adding a line to + /etc/inittab. +
+ Calling restart-aolserver + kills our service. The OS notices that our service is not + running, so it automatically restarts it. Thus, calling + restart-aolserver effectively + restarts our service. +
++ Copy this file into + /tmp/restart-aolserver.txt. +
+ This script needs to be SUID-root, which means + that the script will run as root. This is necessary to ensure + that the AOLserver processes are killed regardless of who owns + them. However the script should be executable by the + web group to ensure that the + users updating the web page can use the script, but that + general system users cannot run the script. You also need to + have Perl installed and also a symbolic link to it in + /usr/local/bin. +
++nsadmin:~$ su - +Password: *********** +root:~# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver +root:~# chown root.web /usr/local/bin/restart-aolserver +root:~# chmod 4750 /usr/local/bin/restart-aolserver +root:~# ln -s /usr/bin/perl /usr/local/bin/perl +root:~# exit+
+ Test the restart-aolserver + script. We'll first kill all running servers to clean the + slate. Then, we'll start one server and use + restart-aolserver to kill + it. If it works, then there should be no more servers + running. You should see the following lines.
++nsadmin:~$ killall nsd +nsd: no process killed +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl +nsadmin:~$ restart-aolserver birdnotes +Killing 23727 +nsadmin:~$ killall nsd +nsd: no process killed+
+ The number 23727 indicates the process id(s) (PIDs) of the + processes being killed. It is important that no processes are killed by the second + call to killall. If there are + processes being killed, it means that the script is not + working.
++ Assuming that the restart-aolserver + script worked, login as root and open + /etc/inittab for + editing.
++nsadmin:~$ su - +Password: ************ +root:~# emacs -nw /etc/inittab+
+ Copy this line into the bottom of the file as a template, + making sure that the first field + nss1 is unique. +
+
+nss1:2345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/birdnotes.tcl
++ Important: Make sure there is a + newline at the end of the file. If there is not a newline at + the end of the file, the system may suffer catastrophic + failures. +
+ Still as root, enter the following command to re-initialize + /etc/inittab.
++root:~# killall nsd +nsd: no process killed +root:~# /sbin/init q+
+ See if it worked by running the + restart-aolserver script + again.
+
+root:~# restart-aolserver birdnotes
+Killing 23750
++ If processes were killed, congratulations, your server is now + automated for startup and shutdown. +
++ + Installation instructions: + +
+
+root:~# apt-get install daemontools-installer +root:~# build-daemontools +root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan+
RPMs for RH 6.2 and RPM 7.1 are available + http://untroubled.org/rpms/daemontools. I + have not tested these, so I have no idea whether they work + properly. +
+ + You can download the source directly from the author's site + at http://cr.yp.to/daemontools/install.html. + +
+ Create a file called run inside + /web/birdnotes: +
++nsadmin:~$ cd /web/birdnotes +nsadmin:/web/birdnotes$ emacs run+
+ Copy this text into that file: +
++#!/bin/sh + +exec /usr/local/aolserver/bin/nsd-postgres -it /usr/local/aolserver/birdnotes.tcl -u nsadmin -g web+
+ As root, change the ownership of this file: +
++nsadmin:/web/birdnotes$ su - +Password: *********** +root:~# chown root.root /web/birdnotes/run +root:~# chmod 700 /web/birdnotes/run+
+ Now, we'll link our web root to the + /service directory. This causes + daemontools to monitor this directory. It should find your + run script and run it as soon as + you hit return. +
++root:~# killall nsd +root:~# ln -s /web/birdnotes /service +root:~# ps -A | grep nsd +19359 pts/3 00:00:08 nsd +19361 pts/3 00:00:00 nsd +19362 pts/3 00:00:00 nsd +19363 pts/3 00:00:00 nsd +19364 pts/3 00:00:00 nsd+
+ At this point, you should be able to use the + restart-aolserver script described + in Editing inittab. Daemontools, however, + allows you much more precision control. +
++ svc -d /web/birdnotes - Bring + the server down +
+ svc -u /web/birdnotes - Start + the server up. Also, restart it whenever it stops. +
+ svc -o /web/birdnotes - Start + the server up once. Do not restart it if it stops. +
+ svc -t /web/birdnotes - Stop + and immediately restart the server +
+ + svc -k /web/birdnotes - 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. + +
+ At this point, these commands will work only for the + root user. We can give a group + permission to run these commands as well. Download this script to + /tmp. +
++root:~# cp /tmp/svgroup.txt /usr/local/bin/svgroup +root:~# chmod 755 /usr/local/bin/svgroup +root:~# svgroup web /service/birdnotes+
+ This command will give the web + group permission to use svc commands + on the birdnotes server. +
++ Try it out. You may want to tail -f + /usr/local/aolserver/log/birdnotes-error.log in + another window, so you can see what happens when you type these + commands. +
++root:~# exit +nsadmin:~$ # first, bring the server down +nsadmin:~$ svc -d /web/birdnotes +nsadmin:~$ # now, start the server up +nsadmin:~$ svc -u /web/birdnotes +nsadmin:~$ # wait for server to come up, then restart it +nsadmin:~$ svc -t /web/birdnotes+
+ Most of this information comes from Tom Jackson's AOLServer+Daemontools + Mini-HOWTO. +
++ If you want to run the service on port 80 (the default HTTP port), + you need to set the port to 80 in your + service_name.tcl file in + /usr/local/aolserver. +
++ Moreover, you will need to start the service as + root. If you follow the instructions + above for automating + startup, this will be taken care of, but if you ever start the + server from the command line, be sure to su + - first. +
++ Port 80 is a privileged port. Only certain users + can claim it. When you start nsd as + root, it obtains the port, and then changes to run as whatever user + you specify in the server configuration file. This ensures a high + level of security, as the server, once started, is not running as + root. This mean that if someone was + able to exploit your web server to execute a command on your server, + they would not be able to gain root + access.
+Skip down for instructions on Deleting a PostgreSQL tablespace. +
++ Should it become necessary to rebuild a tablespace from scratch, + you can use the drop user command + in SVRMGRL with the cascade + option. This command will drop the user and every database object + the user owns.
+
+SVRMGR> drop user birdnotes 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 username='birdnotes';
+and then
++SVRMGR> alter system kill session 'sid,serial#';+
+ where sid and serial# are + replaced with the corresponding values for the open session.
+Use with caution!
++ If you feel the need to delete everything + related to the service, you can also issue the following:
+
+SVRMGR> drop tablespace birdnotes including contents cascade constraints;
++ Dropping a PostgreSQL tablespace is easy. You have to stop any + AOLserver instances that are using the database that you wish to + drop. If you're using daemontools, this is simple, just use the + 'down' flag (-d). If you're using inittab, you have to comment out + your server in /etc/inittab, + reread the inittab with /sbin/init + q, and then restart-aolserver + birdnotes.
+Then, to drop the db, just do:
+
+nsadmin:~$ dropdb birdnotes
+DROP DATABASE
++ We won't provide detailed instructions to install an operating system + since there are so many valid choices available and each OS has their + own installation procedures. +
++ Members of the OpenACS community use a variety of UNIX, Linux, BSD + and even (shudder!) Windows systems. The remainder of this guide will + be specific to Linux. Users of other OS's may find some helpful + information here, but we recommend that you instead use one of these + OS specific guides to install OpenACS 4. +
++ FreeBSD guide +
+ Mac OS X guide +
++ This guide is currently valid for Mac OS 10.04, but it's being + updated for OS 10.1 as we speak. In the meantime, eager 10.1 + users can see this bboard + thread for some help. +
++ This was written for ACS and has not yet been updated for + OpenACS.
++ I'm currently using Debian GNU/Linux, so this guide may show that + bias. Installation on any Linux distribution should be similar and + we'll try to point out differences where they exist. +
++ When you do install your system, be sure to set up enough swap space + - at least 400 MB for Oracle, less for PostgreSQL. A rule of thumb is + to set aside a swap partition which is twice your RAM size. +
++ Some things that you will need: +
+| Requirement | +Reason | +
|---|---|
| recent kernel | +Currently version 2.2.19 or + greater is the standard requirement. Some people are using 2.4.x + (2.4.16) kernels. | +
| bash | +Bash is the standard Linux shell. + We assume you are using bash for these instructions. If you're + not using bash, then you will need to substitute your shell's + conventions for setting environment variables when appropriate. + | +
| glib 2.1 (or greater) | +You need recent versions of + these libraries for Oracle to work properly. | +
| perl (and perl-suid) | ++ A few parts of the ACS require perl to work correctly. + (Debian users: apt-get install + perl-suid) | +
| GNU Make (3.76.1 or better) | ++ PostgreSQL and AOLServer require gmake to compile. Note that + on some linux distributions, GNU Make is simply named + make and there is no + gmake, whereas on BSD + distributions, make and + gmake are different. + | +
| Tcl 8.3 development package (headers, libraries) | ++ The site-wide-search service, OpenFTS, requires these to + compile. (Debian users: apt-get install + tcl8.3-dev) + | +
| libxml2 | ++ OpenACS 4 stores queries in XML files, so libxml2 is used to + parse these files. (Debian users: apt-get + install libxml2-dev) + | +
+ Locations: +
++ We'll compile stuff in + /usr/local/src +
+ PostgreSQL will go into /usr/local/pgsql +
+ AOLServer will go into /usr/local/aolserver +
+ The web root will go into /web +
+ Historically, OpenACS documentation has described using + /home/nsadmin as the home for + aolserver. Either location is fine as long as you are consistent. +
++ Here's a list of some helpful documentation for various OS's +
++ Painless Debian + GNU/Linux by Stephen van Egmond +
+ Once you get your OS installed, it's imperative that you secure your + installation. As Jon Griffin repeatedly warns us, "No distribution is + secure out of the box." Again, this topic is too big to cover properly + here, so see these links. +
++ Others? +
+ Skip this page if you're not interested in PostgreSQL. +
++ Download PostgreSQL 7.1.3 from the mirror closest to you. The list of + mirrors is at http://www.postgresql.org. Download + it to /tmp. +
++ As root, unpack it into + /usr/local/src +
++joeuser:~$ su - +Password: *********** +root:~# cd /usr/local/src +root:/usr/local/src# tar xzf /tmp/postgresql-7.1.3.tar.gz+
+ Still as root, create a user and + group (if you haven't done so before) for PostgreSQL. This is the + account that PostgreSQL will run as since it will not run as + root. Also give the postgres user a + password: +
++root:~# groupadd web +root:~# useradd -g web -d /usr/local/pgsql postgres +root:~# passwd postgres + +root:~# mkdir -p /usr/local/pgsql +root:~# chown -R postgres.web /usr/local/pgsql /usr/local/src/postgresql-7.1.3 +root:~# exit +logout +joeuser:~$ su - postgres +Password: ***********+
+ Edit /usr/local/pgsql/.bash_profile + so it looks like this: +
++LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib +PATH=$PATH:/usr/local/pgsql/bin + +export PATH LD_LIBRARY_PATH+
+ Logout and login again as postgres. Use the + echo command to make sure that + /usr/local/pgsql/bin is now in your + PATH +
++postgres:~$ exit +logout +joeuser:~$ su - postgres +Password: ************ +postgres:~$ echo $PATH +/usr/local/bin:/usr/bin:/bin: ... :/usr/local/pgsql/bin+
+ First, we run ./configure to set the + compilation options automatically. This is the point at which you can + configure PostgreSQL in various ways. For example, if you want to + enable Unicode support, add the flags + --enable-locale and + --enable-multibyte. If you want to + see what the other possibilities are, run ./configure + --help. +
++postgres:~$ cd /usr/local/src/postgresql-7.1.3 +postgres:/usr/local/src/postgresql-7.1.3$ ./configure +postgres:/usr/local/src/postgresql-7.1.3$ make all+
+ Compilation will take a while (about 10 minutes). Once it's done, you + will see the following message: +
++All of PostgreSQL is successfully made. Ready to install.+
+ Next, we'll install PostgreSQL. If all is successful, you'll see the + following “Thank You” message. +
++postgres:/usr/local/src/postgresql-7.1.3$ make install +... +Thank you for choosing PostgreSQL, the most advanced open source database engine.+
+ OpenFTS is the module that provides full text search to OpenACS 4. We + won't be installing it until later, but we'll set up a couple things + that are best done right now. +
++postgres:/usr/local/src/postgresql-7.1.3$ make install-all-headers +postgres:/usr/local/src/postgresql-7.1.3$ cd contrib/intarray +postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make +postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ make install+
The initdb command initializes + the database. pg_ctl is used to + start up PostgreSQL. +
++postgres:/usr/local/src/postgresql-7.1.3/contrib/intarray$ cd +postgres:~$ /usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data +postgres:~$ /usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /usr/local/pgsql/data/server.log start +postmaster successfully started+
+ PostgreSQL errors will be logged in + /usr/local/pgsql/data/server.log +
++ We have to install plpgsql into our PostgreSQL installation so that + we can use stored procedures. Fortunately, it's pretty easy. We'll + also create a database user named + nsadmin, so that aolserver can + access the database. (Don't worry that you don't have a + nsadmin user yet - we'll create that + in the next chapter.) +
++postgres:~$ createlang plpgsql template1 +postgres:~$ # Test if we succeeded +postgres:~$ createlang -l template1 + Procedural languages + Name | Trusted? | Compiler +---------+----------+---------- + plpgsql | t | PL/pgSQL +(1 row) +postgres:~$ createuser nsadmin +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+
+ Create a database and try some simple commands. The output should be + as shown. +
++postgres:~$ createdb mytestdb +CREATE DATABASE +postgres:~$ psql mytestdb +Welcome to psql, the PostgreSQL interactive terminal. + +Type: \copyright for distribution terms + \h for help with SQL commands + \? for help on internal slash commands + \g or terminate with semicolon to execute query + \q to quit + +mytestdb=# select current_timestamp; + timestamp +------------------------ + 2001-12-20 14:24:30-05 +(1 row) + +mytestdb=# create function test1() returns integer as 'begin return 1; end;' language 'plpgsql'; +CREATE +mytestdb=# select test1(); + test1 +------- + 1 +(1 row) + +mytestdb=# \q +postgres:~$ dropdb mytestdb +DROP DATABASE+
+ Download postgresql.txt to + /tmp. Then follow the instructions + specific to your distribution: +
+Debian:
++postgres:~$ su - +Password: *********** +root:~# cp /tmp/postgresql.txt /etc/init.d/postgresql +root:~# chown root.root /etc/init.d/postgresql +root:~# chmod 700 /etc/init.d/postgresql+
Test the script
++root:~# /etc/init.d/postgresql stop +Stopping PostgreSQL: ok+
+ If PostgreSQL successfully stopped, then use the following + command to make sure that the script is run appropriately at boot + and shutdown. +
++root:~# update-rc.d postgresql defaults + Adding system startup for /etc/init.d/postgresql ... + /etc/rc0.d/K20postgresql -> ../init.d/postgresql + /etc/rc1.d/K20postgresql -> ../init.d/postgresql + /etc/rc6.d/K20postgresql -> ../init.d/postgresql + /etc/rc2.d/S20postgresql -> ../init.d/postgresql + /etc/rc3.d/S20postgresql -> ../init.d/postgresql + /etc/rc4.d/S20postgresql -> ../init.d/postgresql + /etc/rc5.d/S20postgresql -> ../init.d/postgresql +root:~# /etc/init.d/postgresql start +Starting PostgreSQL: ok +root:~# exit +postgres:~$ exit+
Red Hat:
++postgres:~$ su - +Password: *********** +root:~# cp /tmp/postgresql.txt /etc/rc.d/init.d/postgresql +root:~# chown root.root /etc/rc.d/init.d/postgresql +root:~# chmod 700 /etc/rc.d/init.d/postgresql+
Test the script
++root:~# /etc/rc.d/init.d/postgresql stop +Stopping PostgreSQL: ok+
If PostgreSQL successfully stopped, then use the following + command to make sure that the script is run appropriately at boot + and shutdown. +
++root:~# chkconfig --add postgresql +root:~# chkconfig --list postgresql +; You should see: +postgresql 0:off 1:off 2:off 3:on 4:on 5:on 6:off +root:~# /etc/rc.d/init.d/postgresql start +Starting PostgreSQL: ok +root:~# exit +postgres:~$ exit+
SuSE:
++postgres:~$ su - +Password: *********** +root:~# cp /tmp/postgresql.txt /etc/rc.d/init.d/postgresql +root:~# chown root.root /etc/rc.d/init.d/postgresql +root:~# chmod 700 /etc/rc.d/init.d/postgresql+
Test the script
++root:~# /etc/rc.d/init.d/postgresql stop +Stopping PostgreSQL: ok+
+ If PostgreSQL successfully stopped, then use the following + command to make sure that the script is run appropriately at boot + and shutdown. +
++root:~# cd /etc/rc.d/init.d +root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql K20postgresql +root:/etc/rc.d/init.d# ln -s /etc/rc.d/init.d/postgresql S20postgresql +root:/etc/rc.d/init.d# cp K20postgresql rc2.d +root:/etc/rc.d/init.d# cp S20postgresql rc2.d +root:/etc/rc.d/init.d# cp K20postgresql rc3.d +root:/etc/rc.d/init.d# cp S20postgresql rc3.d +root:/etc/rc.d/init.d# cp K20postgresql rc4.d +root:/etc/rc.d/init.d# cp S20postgresql rc4.d +root:/etc/rc.d/init.d# cp K20postgresql rc5.d +root:/etc/rc.d/init.d# cp S20postgresql rc5.d +root:/etc/rc.d/init.d# rm K20postgresql +root:/etc/rc.d/init.d# rm S20postgresql+
+ Test configuration +
++root:/etc/rc.d/init.d # cd +root:~ # /etc/rc.d/init.d/rc2.d/S20postgresql start +Starting PostgreSQL: ok +root:~ # exit+
+ From now on, PostgreSQL should start automatically each time you boot + up and it should shutdown gracefully each time you shut down. (Note: + Debian defaults to starting all services on runlevels 2-5. Red Hat + defaults to starting services on 3-5. So, on Red Hat, PostgreSQL won't + start on runlevel 2 unless you alter the above commands a + little. This usually isn't a problem as Red Hat defaults to runlevel 3) +
++ Here are some links: +
+