| -Prev | -Chapter 2. Installing on Unix/Linux | -Next - | -
|---|
-
Download the OpenACS 4.5 software +
Download the OpenACS 4.5 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. -
-+
+ Login as nsadmin + and untar the downloaded components into + /web directory. The OpenACS + 4.5 tarball is currently named + openacs-4-5-release.tgz. Replace + openacs-4-5-release.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-
+nsadmin:/web$ tar xzf /tmp/openacs-4-5-release.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 + 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 + 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 + 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$ mv openacs-4 birdnotes nsadmin:/web$ ls -l total 4 -drwxr-xr-x 8 nsadmin nsadmin 4096 Dec 20 14:37 birdnotes-
+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 +
You should be logged on as nsadmin for this step and you should make sure that nsadmin is in the - dba group.
-+ dba group.
Verify nsadmin membership by typing groups when you login: @@ -111,8 +70,7 @@ 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: @@ -121,8 +79,7 @@ SVRMGR> connect internal Connected. -
+
Determine where the system tablespaces are stored:
@@ -137,8 +94,7 @@ /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 @@ -152,24 +108,18 @@ 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:
-+ 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:~$-
+nsadmin:~$
As nsadmin, create a tablespace for the service. It is important that the tablespace can autoextend. This allows the @@ -178,185 +128,132 @@ 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.
-+ 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);-
+SVRMGR> create tablespace birdnotes + datafile '/ora8/m02/oradata/ora8/birdnotes01.dbf' + size 50M + autoextend on + next 10M + maxsize 300M + extent management local + uniform size 32K;
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 + birdnotespassword as our password.
+ Write down what you specify as service_name (i.e. birdnotes) and - database_password + 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;-
+
+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 + service_name account:+nsadmin:~$ sqlplus birdnotes/birdnotespassword SQL> select sysdate from dual; SYSDATE ---------- 2001-12-20 -SQL> exit-+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 + service-name (i.e. birdnotes) -
-
-nsadmin:/web$ createdb birdnotes
-CREATE DATABASE
-Next we'll set up AOLserver so that it has the proper environment +
+nsadmin:/web$ createdb birdnotes
+CREATE DATABASENext 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 :
-+ /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-
+ 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 +
+ 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, + 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 +
+ 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
+
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):
-+ 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-+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/-
+
+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/log/birdnotes-error.log) + (/usr/local/aolserver/log/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.5. -
-+
You should see a page from the webserver titled OpenACS Installation: Welcome. You will be warned if your version of @@ -366,118 +263,80 @@ 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-
+
+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
-+
+nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tclGive 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.5 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!
-+
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 @@ -487,330 +346,208 @@ 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-
+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.
-+ 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 +nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl +nsadmin:~$ restart-aolserver birdnotes Killing 23727 nsadmin:~$ killall nsd -nsd: no process killed-+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 + 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.
-+ working.
Assuming that the restart-aolserver script worked, login as root and open /etc/inittab for - editing.
-+ editing.nsadmin:~$ su - Password: ************ -root:~# emacs -nw /etc/inittab-
+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 +
+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.
-+ /etc/inittab.root:~# killall nsd nsd: no process killed -root:~# /sbin/init q-
+root:~# /sbin/init q
See if it worked by running the restart-aolserver script - again.
-
-root:~# restart-aolserver birdnotes
-Killing 23750
-+ again.
+root:~# restart-aolserver birdnotes
+Killing 23750If processes were killed, congratulations, your server is now automated for startup and shutdown. -
-Installation instructions: -
-
+- -
- Debian
- -
root:~# apt-get install daemontools-installer root:~# build-daemontools root:~# # answer 'yes' when asked to create symlink from /service to /var/lib/svscan-- Red Hat
-RPMs for RH 6.2 and RPM 7.1 are available +
- Red Hat
- -
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. -
- Other distributions
-+
- Other distributions
- -
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: -
-+ /web/birdnotes: +nsadmin:~$ cd /web/birdnotes -nsadmin:/web/birdnotes$ emacs run-+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-+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-+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-+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-+root:~# svgroup web /service/birdnotes
This command will give the web group permission to use svc commands - on the birdnotes server. -
-+ 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 +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 +
+ 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. -
-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;
-+ 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;
-+ this user. If it still does not work, do:
+SVRMGR> select username, sid, serial# from v$session where lower(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
-