Install OpenACS &version;
by Vinod KurupDownloading OpenACS Download the OpenACS &version; software
to the /tmp directory:
Login as nsadmin
and untar the downloaded components into
/web directory. The OpenACS
&version; 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/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
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 Oracle for OpenACSYou 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
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
(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 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
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-oracleRedHat 7.3 and 8.0 users: set the the LD_ASSUME_KERNEL environment
variable in your nsd-oracle script:
export LD_ASSUME_KERNEL=2.2.5 Prepare PostgreSQL for OpenACS
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 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 :
nsadmin:/web$ cd
nsadmin:~$ cp /tmp/nsd-postgres.txt ./bin/nsd-postgres
nsadmin:~$ chmod 700 ./bin/nsd-postgresConfiguring AOLserver
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 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 .
If you don't see the login page, view your 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 nsdUsing the OpenACS Installer
Now that you've got AOLserver up and running, let's install OpenACS
&version;.
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
&version; is now up and running!
Keep AOLserver alive
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 .
Important: You need to set up
either inittab or daemontools, not both!Editing inittab
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 -t /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:345:respawn:/usr/local/aolserver/bin/nsd-postgres -i -u nsadmin -g web -t /usr/local/aolserver/birdnotes.tclImportant: 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.
Install daemontools
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/svscanRed HatRPMs 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
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 . 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.
Running AOLserver on Port 80
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.Deleting a tablespaceSkip down for instructions on .
Deleting an Oracle 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 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;Deleting a PostgreSQL tablespace
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($Id: openacs.xml,v 1.5.2.3 2002/11/22 04:56:36 danw Exp $)