| Prev | Chapter 2. Installing on Unix/Linux | Next |
|---|
+
Download the OpenACS 4.5 software + OpenACS docs are written by the named authors, but may be edited + by OpenACS documentation staff. +
Download the OpenACS 4.6 software to the /tmp directory:
- 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 + + Create a directory called web + inside your home directory and untar the downloaded components + there. Set the permissions as directed. The OpenACS 4.6 + tarball is currently named + openacs-4-6-release.tgz. Replace + openacs-4-6-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
+joeuser:~$ mkdir -p web +joeuser:~$ chown joeuser.web web +joeuser:~$ cd web +joeuser:~/web$ tar xzf /tmp/openacs-4-6-release.tgz +joeuser:~/web$ chown -R joeuser.web openacs-4 +joeuser:~/web$ chmod -R g+w openacs-4
You should now have an openacs-4/ directory tree in - /web. Rename this directory to + ~/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 @@ -33,49 +37,54 @@ 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+joeuser:~/web$ ls -l +drwxrwxr-x 8 joeuser web 4096 Nov 27 09:32 openacs-4 +joeuser:~/web$ mv openacs-4 birdnotes +joeuser:~/web$ ls -l +drwxrwxr-x 8 joeuser web 4096 Dec 20 14:37 birdnotes
+ + Finally create a directory for the AOLserver logs. + +
+joeuser:~/web$ mkdir birdnotes/log
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 +
+ + You should be sure that your user account + (e.g. joeuser) is in the + dba group. + +
+ Verify membership by typing groups when you login:
-nsadmin:~$ groups -nsadmin dba web+joeuser:~$ groups +dba web If you do not see these groups, take the following action:
-nsadmin:~$ su - +joeuser:~$ su - Password: ************ -root:~# usermod -g nsadmin -G dba,web nsadmin+root:~# adduser joeuser dba If you get an error about an undefined group, then add that group manually:
root:~# groupadd dba -root:~# groupadd nsadmin root:~# groupadd webMake sure to logout as root when you are finished with this step and log back in as - nsadmin. + your regular user.
Connect to Oracle using svrmgrl and login:
-nsadmin:~$ svrmgrl +joeuser:~$ svrmgrl SVRMGR> connect internal Connected.@@ -104,33 +113,35 @@ 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 + 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 -
+joeuser:~$ su -
Password: ************
root:~# mkdir -p /ora8/m02/oradata/ora8/
-root:~# chown nsadmin.web /ora8/m02/oradata/ora8
+root:~# chown joeuser.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 +joeuser:~$
+ 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. + +
+joeuser:~$ svrmgrl + SVRMGR> connect internal; SVRMGR> create tablespace birdnotes datafile '/ora8/m02/oradata/ora8/birdnotes01.dbf' @@ -161,7 +172,7 @@
Make sure that you can login to Oracle using your service_name account:
-nsadmin:~$ sqlplus birdnotes/birdnotespassword +joeuser:~$ sqlplus birdnotes/birdnotespassword SQL> select sysdate from dual; SYSDATE @@ -178,20 +189,28 @@ 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 +joeuser:~/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
+joeuser:~/web$ cd +joeuser:~$ su - +Password: ******** +root:~# cd /usr/local/aolserver/bin +root:/usr/local/aolserver/bin# cp /tmp/nsd-postgres.txt ./nsd-postgres +root:/usr/local/aolserver/bin# chmod 755 nsd-postgres +root:/usr/local/aolserver/bin# exit
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 @@ -201,14 +220,16 @@ 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 + + Modify it for your needs and save it inside your + ~/web/birdnotes directory. (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
+joeuser:~$ cp /tmp/openacs4.tcl.txt ./web/birdnotes/nsd.tcl +joeuser:~$ chmod 600 ./web/birdnotes/nsd.tcl +joeuser:~$ emacs ./web/birdnotes/nsd.tcl
Specifically, you'll have set the following variables
server - This is the name of @@ -224,7 +245,12 @@ *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
+ server on a different port, enter it here
+ + user_account - The account that will both + own OpenACS files and connect to the database (for Postgresql). + +
AOLServer is very configurable. These settings should get you started, but for more options, read the AOLServer docs. @@ -233,26 +259,27 @@ one. (Note, if you are using Oracle, rather than PostgreSQL, replace nsd-postgres with nsd-oracle):
-nsadmin:~$ killall nsd
+joeuser:~$ killall nsd
; Should probably see:
nsd: no process killed
-nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl+joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.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/log/birdnotes-error.log) + (~/web/birdnotes/log/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. + 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. + 4.6.
You should see a page from the webserver titled OpenACS Installation: @@ -263,28 +290,36 @@ 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: + should see a string of output messages from the database as the + datamodel is 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. + + 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 + + The following page shows the results of loading the core 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. + 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. + Create User. +
You should see a page, "OpenACS Installation: Set System Information" allowing you to name your service. Fill out the @@ -297,11 +332,11 @@ 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+joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.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.5 is now up and running! + 4.6 is now up and running!
Now, we'll describe how to start AOLserver automatically on boot, or whenever else the service dies. @@ -347,7 +382,7 @@ have Perl installed and also a symbolic link to it in /usr/local/bin.
-nsadmin:~$ su - +joeuser:~$ su - Password: *********** root:~# cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver root:~# chown root.web /usr/local/bin/restart-aolserver @@ -360,194 +395,206 @@ 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 +joeuser:~$ killall nsd nsd: no process killed -nsadmin:~$ /usr/local/aolserver/bin/nsd-postgres -t /usr/local/aolserver/birdnotes.tcl -nsadmin:~$ restart-aolserver birdnotes +joeuser:~$ /usr/local/aolserver/bin/nsd-postgres -t ~/web/birdnotes/nsd.tcl +joeuser:~$ restart-aolserver birdnotes Killing 23727 -nsadmin:~$ killall nsd +joeuser:~$ 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 -
+ 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.
+joeuser:~$ 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.
+ 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 nobody -g web -t /home/joeuser/web/birdnotes/nsd.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.
+ 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. -
+ If processes were killed, congratulations, your server is now + automated for startup and shutdown. +
- Installation instructions: + Installation instructions: -
+
- Debian
- 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
+root:~# build-daemontools +
- 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
- You can download the source directly from the author's site - at http://cr.yp.to/daemontools/install.html. + 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: -
+
+
+ Create a file called run inside + ~/web/birdnotes: +
+joeuser:~$ cd web/birdnotes +joeuser:~/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 -
+exec /usr/local/aolserver/bin/nsd-postgres -it /home/joeuser/web/birdnotes/nsd.tcl -u nobody -g web+ + As root, change the ownership of this file. We also need to delete + any logs that may be present from previous testing. If they are + owned by users other than nobody, + then AOLserver willl not be able to append to them. + +
+joeuser:~/web/birdnotes$ rm log/* +joeuser:~/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:~# chown root.root /home/joeuser/web/birdnotes/run +root:~# chmod 700 /home/joeuser/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:~# ln -s /home/joeuser/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, you should be able to use the + restart-aolserver script described + in Editing inittab. Daemontools, however, + provides you with more precise control. +
-
- 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. -
+ svc -d /service/birdnotes - + Bring the server down + +
+ + svc -u /service/birdnotes - + Start the server up. Also, restart it whenever it stops. + +
+ + svc -o /service/birdnotes - + Start the server up once. Do not restart it if it stops. + +
+ + svc -t /service/birdnotes - + Stop and immediately restart the server + +
+ + svc -k /service/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. -
+ 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 + ~/web/birdnotes/log/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.
+joeuser:~$ # first, bring the server down +joeuser:~$ svc -d /service/birdnotes +joeuser:~$ # now, start the server up +joeuser:~$ svc -u /service/birdnotes +joeuser:~$ # wait for server to come up, then restart it +joeuser:~$ svc -t /service/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 + nsd.tcl config file. +
+ 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:
+ 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:
+ 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 DATABASEThen, to drop the db, just do:
+joeuser:~$ dropdb birdnotes
+DROP DATABASE