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.7 -r1.8 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 25 May 2003 19:17:10 -0000 1.7 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/openacs.xml 24 Jun 2003 03:37:05 -0000 1.8 @@ -27,7 +27,7 @@ You should already have downloaded the OpenACS tarball to the /tmp directory. If - noot, download the OpenACS + not, download the OpenACS tarball and save it in /tmp and proceed: @@ -140,87 +140,10 @@ chmod -R 700 service0/ exit - - - Add the Service to CVS - OPTIONAL - - cvs - setup - - If this is a development server, you may want to add - it to a CVS - repository.. - - - - - Create and set permissions on a subdirectory in the local cvs repository. - [root@yourserver root]# mkdir /cvsroot/service0 -[root@yourserver root]# chown service0.web /cvsroot/service0 -[root@yourserver root]# -mkdir /cvsroot/service0 -chown service0.web /cvsroot/service0 - - - Add the repository location to the user environment. - [root@yourserver root]# su - service0 -[service0@yourserver service0]$ emacs .bashrc - Put this string into /home/service0/.bashrc: - export CVSROOT=/cvsroot - [service0@yourserver service0]$ exit -logout - -[root@yourserver root]# - - - Import all files into cvs. In order to work on - files with source control, the files must be checked out - from cvs. So we will import, move aside, and then check - out all of the files. In the cvs import command, - service0 - refers to the cvs repository to use; it uses the CVSROOT - plus this string, - i.e. - /cvsroot/service0. - "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@yourserver root]# su - service0 -[service0@yourserver service0]$ cd /web/service0 -[service0@yourserver service0]$ cvs import -m "initial install" service0 OpenACS &cvsversiontag; -N service0/license.txt -N service0/readme.txt -(many lines omitted) -N service0/www/SYSTEM/flush-memoized-statement.tcl - -No conflicts created by this import - -[service0@yourserver service0]$ -su - service0 -cd /web/service0 -cvs import -m "initial install" service0 OpenACS &cvsversiontag; - Move the original directory to a temporary location, and check out the cvs repository in its place. If the service starts correctly, come back and remove the temporary copy of the uploaded files. - [service0@yourserver service0]$ cd .. -[service0@yourserver web]$ mv service0 service0.orig -[service0@yourserver web]$ cvs checkout service0 -cvs checkout: Updating service0 -U service0/license.txt -(many lines omitted) -U service0/www/SYSTEM/dbtest.tcl -U service0/www/SYSTEM/flush-memoized-statement.tcl -[service0@yourserver web]$ exit -logout - -[root@yourserver web]# -cd .. -mv service0 service0.orig -cvs checkout service0 -exit - - - + Add the Service to CVS (OPTIONAL) + Set up several additional directories in the service root: etc is for configuration and control files, log is for error and request (web page hit) log files, and database-backup is for database backup files. If you did the CVS step, note that these new directories are excluded from that step so that you can decide whether or not you want your logs and config files in source control. @@ -240,7 +163,7 @@ Prepare Oracle for OpenACS - OPTIONAL - if you won't be using Oracle, skip to If you won't be using Oracle, skip to You should be sure that your user account @@ -449,25 +372,8 @@ Add this line to the file. 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. 0 1 * * * /usr/local/pgsql/bin/vacuumdb --analyze service0 - - Add Full Text Search Support - OPTIONAL - - full text search - installation - - If you are installing Full Text Search, add required packages to the new database. - [service0@yourserver service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql -BEGIN -CREATE -(many lines omitted) -INSERT 0 1 -COMMIT -[service0@yourserver service0]$ /usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql -CREATE -CREATE -[service0@yourserver service0]$ -/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/tsearch/tsearch.sql -/usr/local/pgsql/bin/psql service0 -f /usr/local/src/postgresql-7.2.4/contrib/pgsql_contrib_openfts/openfts.sql + + Add Full Text Search Support (OPTIONAL) [service0@yourserver service0]$ exit @@ -541,69 +447,22 @@ debug - Set to true for a very verbose error log, including many lines for every page view, success or failure. - - - + + + AOLServer is very configurable. These settings should get you started, but for more options, read the AOLServer docs. - OPTIONAL: To run OpenFTS, uncomment this line from config.tcl. (To uncomment a line in a tcl file, remove the # at the beginning of the line.) - #ns_param nsfts ${bindir}/nsfts.so + Enable OpenFTS Full Text Search (OPTIONAL) - OPTIONAL: To run nsopenssl: - - - Uncomment this line from config.tcl. - #ns_param nsopenssl ${bindir}/nsopenssl.so - - - - Prepare a certificate directory for the service. - [service0@yourserver etc]$ mkdir /web/service0/etc/certs -[service0@yourserver etc]$ chmod 700 /web/service0/etc/certs -[service0@yourserver etc]$ -mkdir /web/service0/etc/certs -chmod 700 /web/service0/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@yourserver service0]$ cd /web/service0/etc/certs -[service0@yourserver certs]$ perl /usr/share/ssl/misc/CA -newcert -Using configuration from /usr/share/ssl/openssl.cnf -Generating a 1024 bit RSA private key -...++++++ -.......++++++ -writing new private key to 'newreq.pem' -Enter PEM pass phrase: - Enter a pass phrase for the CA certificate. Then, answer the rest of the questions. At the end you should see this: - Certificate (and private key) is in newreq.pem -[service0@yourserver 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@yourserver misc]# openssl rsa -in newreq.pem -out keyfile.pem -read RSA key -Enter PEM pass phrase: -writing RSA key -[service0@yourserver certs]$ - To create the certificate file, we take the combined file, copy it, and strip out the key. - [service0@yourserver certs]$ cp newreq.pem certfile.pem -[root@yourserver misc]# emacs certfile.pem - Strip out the section that looks like - -----BEGIN RSA PRIVATE KEY----- -Proc-Type: 4,ENCRYPTED -DEK-Info: DES-EDE3-CBC,F3EDE7CA1B404997 -S/Sd2MYA0JVmQuIt5bYowXR1KYKDka1d3DUgtoVTiFepIRUrMkZlCli08mWVjE6T -(11 lines omitted) -1MU24SHLgdTfDJprEdxZOnxajnbxL420xNVc5RRXlJA8Xxhx/HBKTw== ------END RSA PRIVATE KEY----- - - + Install nsopenssl + for SSL support. (OPTIONAL) @@ -614,9 +473,22 @@ Kill any current running AOLserver processes and start a new - one. (Note, if you are using Oracle, rather than PostgreSQL, replace + one. If you are using Oracle, rather than PostgreSQL, replace nsd-postgres with - nsd-oracle). If you are using port 80, you must be root for this step. + nsd-oracle). + If you want to use port 80, there are complications. + First, Aolserver must be root to use system ports such as + 80, but refuses to run as root for security reasons. Thus + you must start 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 + /etc/passwd and then put those numbers into + the command line via -u + 501 -g + 502. Second, 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@yourserver etc]$ killall nsd nsd: no process killed [service0@yourserver service0]$ /usr/local/aolserver/bin/nsd-postgres -t /web/service0/etc/config.tcl @@ -625,8 +497,7 @@ - Attempt to connect to the service from a web browser as you did - You should specify a URL like: + Attempt to connect to the service from a web browser. You should specify a URL like: http://yourserver.test:8000 @@ -650,100 +521,9 @@ killall nsd. - - OPTIONAL - Automate AOLserver keepalive - - Assuming AOLserver started cleanly in the previous step, we'll set it up so that it's always running, and automatically restarts whenever it dies or is stopped. This step is strongly recommended, even for development sites, because it makes install and maintenance much simpler. - - The Reference Platform uses Daemontools to control AOLserver. A simpler method, using init, is here. - - - Daemontools must already be installed. If not, install it. - - - Each service controlled by daemontools must have a directory in /service. That directory must have a file called run. Daemontools then creates additional files and directories to track status and log. Create the appropriate directory as /web/service0/etc/daemontools, copy the prepared run file, and set permissions. If your server is not called service0, edit /web/service0/etc/run accordingly. - [service0@yourserver log]$ cd /web/service0/etc -[service0@yourserver etc]$ mkdir daemontools -[service0@yourserver etc]$ cp /web/service0/packages/acs-core-docs/www/files/run.txt daemontools/run -[service0@yourserver etc]$ chmod 700 daemontools/run -cd /web/service0/etc -mkdir daemontools -cp /web/service0/packages/acs-core-docs/www/files/run.txt daemontools/run -chmod 700 daemontools/run - - - Kill 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@yourserver etc]$ killall nsd -nsd: no process killed -[service0@yourserver etc]$ exit - -[root@yourserver root]# ln -s /web/service0/etc/daemontools/ /service/service0 - Verify that AOLserver is running. - [root@yourserver root]# ps -auxw | grep nsd -service0 5562 14.2 6.2 22436 15952 ? S 11:55 0:04 /usr/local/aolserver/bin/nsd -it /web/service0/etc/config.tcl -u serve -root 5582 0.0 0.2 3276 628 pts/0 S 11:55 0:00 grep nsd -[root@yourserver root]# - - - The user service0 can now control the service service0 with these commands: - - - - svc -d /service/service0 - - Bring the server down - - - - - - svc -u /service/service0 - - Start the server up and leave it in keepalive mode. - - - - - - svc -o /service/service0 - - Start the server up once. Do not restart it if it stops. - - - - - - svc -t /service/service0 - - Stop and immediately restart the server. - - - - - - svc -k /service/service0 - - 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. - - - - - - 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@yourserver root]# svgroup web /service/service0 -[root@yourserver root]# - - - Verify that the controls work. You may want to tail -f /web/service0/log/service0-error.log in another window, so you can see what happens when you type these commands. - - - - Most of this information comes from Tom Jackson's AOLServer+Daemontools - Mini-HOWTO. - - - + Automate + AOLserver keepalive (OPTIONAL) @@ -835,217 +615,37 @@ - OPTIONAL - Install Full Text Search. - + + Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled + OpenFTS, you can now install the OpenFTS Driver package and + Full Text Search Engine package in the OpenACS service. - - Click Package Manager on the right side of the default home page. If prompted, log in with the account and password you entered during install. - - - Click on the Install -packages link. - - - On the next screen, after it loads, click on Uncheck all boxes, then click the second checkbox next to OpenFTS Driver 4.2. This will automatically check the first box. Then click Next. - - Click Install Packages - - Restart the service. -[service0@yourserver service0]$ svc -t /service/service0 -[service0@yourserver service0]$ - - Wait a minute, then browse back to the home page. - - - Click on Site Map on the top right side of the screen. - - - - Mount the OpenFTS Full Text Search Engine in the site map. - - Click the new sub folder link on the "/" line, the first line under Main Site:/. - Type openfts -and click New. - On the new openfts line, click the mount link. - Click OpenFTS -Driver. - On the openfts line, click set parameters. - - Change openfts_tcl_src_path to /usr/local/src/Search-OpenFTS-tcl-0.3.2/ and click Set Parameters - - - - - - Mount the Search interface in the site map. - - Click the -new sub folder link on the -Main Site line. - Type search -and click New. - Click the new -application link on the search - line. - Type search -where it says -untitled, choose -search from the -drop-down list, and click -New. - - - - - Restart the service. - [service0@yourserver service0]$ svc -t /service/service0 -[service0@yourserver service0]$ - - Wait a minute, then click on Main Site at the top of the page. - - - Initialize the OpenFTS Engine. This creates a set of tables in the database to support FTS. - Near the bottom of the page, click on the OpenFTS Driver link. Click on Administration. -Click on Initialize OpenFTS Engine. -Click Initialize OpenFTS Engine. - - - Add the FTS Engine service contract - - Click on the Main -Site. - Click on the ACS -Service Contract link near the bottom of the home page. - On the FtsEngineDriver -line, click -Install. - - - - - Restart the service. - [service0@yourserver service0]$ svc -t /service/service0 -[service0@yourserver service0]$ - - - Test FTS. (INCOMPLETE). Add a package that supports search,like "note," add some content, and search for it. - - - - Back up the New Service - OPTIONAL - This is a very good time to back the service, even if it's not a production service. Making a backup now lets you roll back to this initial, clean setup at any point in the future, without repeating the install process. A full OpenACS service backup includes everything in the /web/service0/ directory. At this point it's probably sufficient to back up just the database, because you can recover the files from a tarball. - Note that, if you did the CVS options in this document, the /web/service0/etc directory is not included in cvs and you may want to add it. + Next Steps - - PostGreSQL - Create a backup file and verify that it was created and has a reasonable size (several megabytes). - - [service0@yourserver service0]$ mkdir /web/service0/database-backup -[service0@yourserver service0]$ pg_dump -f /web/service0/database-backup/initial_backup.dmp service0 -[service0@yourserver service0]$ ls -al /web/service0/database-backup -total 1425 -drwxr-xr-x 2 service0 web 1024 Mar 9 14:13 . -drwx------ 11 service0 web 1024 Mar 9 14:11 .. --rw-r--r-- 1 service0 web 1449826 Mar 9 14:13 initial_backup.dmp -[service0@yourserver service0]$ -mkdir /web/service0/database-backup -pg_dump -f /web/service0/database-backup/initial_backup.dmp service0 -ls -al /web/service0/database-backup + This is a good time to make a backup of your service. If this is a + production site, you should set up automatic nightly backups. - - Oracle - INCOMPLETE - - + If you want traffic reports, set up analog or another log + processing program. - - - - - Set up Automated Backup - OPTIONAL - Backup can encompass all files in /web/service0. For a development server, putting the files in cvs is sufficient. (It's important then to back up the cvs repository!) - - A quick way to automate database backup is a cron job. This is not recommended for production and is not part of the Reference Platform, because it is not cross-platform and can fail silently. More thorough methods are documented in - [service0@yourserver service0]$ export EDITOR=emacs;crontab -e - Add this line to the file. 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. - 0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_$(date +%Y-%m-%d).dmp service0 - If you plan to back up the whole /web/service0 directory, then it would be redundant to keep a history of database backups. In that case, set up the cron job to overwrite the previous backup each time: - 0 1 * * * /usr/local/pgsql/bin/pg_dump -f /web/service0/database-backup/service0_nightly.dmp service0 - - - - Set up Log Analysis Reports - OPTIONAL - - Analog is a program with processes webserver access logs, - performs DNS lookup, and outputs HTML reports. Analog should - already be - installed. A modified configuration file is included in - the OpenACS tarball. - - - [root@yourserver src]# su - service0 -[service0@yourserver service0]$ cd /web/service0 -[service0@yourserver service0]$ cp /web/service0/packages/acs-core-docs/www/files/analog.cfg.txt etc/analog.cfg -[service0@yourserver service0]$ mkdir www/log -[service0@yourserver service0]$ cp -r /usr/share/analog-5.31/images www/log/ -[service0@yourserver service0]$ -su - service0 -cd /web/service0 -cp /web/service0/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 -/web/service0/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 /web/service0/www/log/traffic.html to use a private -directory. + Follow the instruction on the home page to + change the appearance of your service or add more + packages. (more information) - - Run it. - [service0@yourserver service0]$ /usr/share/analog-5.31/analog -G -g/web/service0/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 - (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@yourserver service0]$ - 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@yourserver service0]$ exit -logout - -[root@yourserver root]# emacs /etc/cron.daily/analog - Put this into the file: - #!/bin/sh - -/usr/share/analog-5.31/analog -G -g/web/service0/etc/analog.cfg - [root@yourserver root]# chmod 755 /etc/cron.daily/analog - Test it by running the script. - [root@yourserver root]# sh /etc/cron.daily/analog - Browse to http://yourserver.test/log/traffic.html - - - - - - Next Steps - - Test your backup and recovery procedure. - - Follow the instruction on the home page to change the appearance of your service or add more packages. - Proceed to the tutorial to learn how to develop your own packages. + Test your backup and recovery procedure. +