This document covers the installation of the ArsDigita Community System (ACS) step by step. It assumes that you have already installed Oracle and AOLserver.

Table of Contents

1. Downloading the ACS
2. Prepare Oracle for the ACS
3. Configuring AOLserver
4. Using the ACS Installer
5. Ensuring that Your Service Starts Automatically on Boot
6. Appendix A: How to Transfer Data
7. Appendix B: Running AOLserver on Port 80
8. Appendix C: Deleting a Tablespace
9. Appendix D: Setup Nightly Oracle Exports

Downloading the ACS

• Download the following from the ArsDigita download page to the /tmp directory:
  • ArsDigita Community System v 4.0.

• Login as nsadmin and uncompress the downloaded components into /web. Substitute the correct file name into the line below. Tip: If you type acs- and then press the TAB key, your shell should complete the file name for you.

  $ su - nsadmin
  ; Enter nsadmin's password.
  $ cd /tmp
  $ tar -xzvf acs-4.0.tar.gz --directory=/web
  
  ; Stay logged in as nsadmin.
      

• You should now have an acs/ 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. 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 "arfdigita" is the service name for the ArfDigita.org community.

  $ cd /web
  $ mv acs service_name
      

TOP

Prepare Oracle for ACS

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:

  $ groups
  nsadmin dba web
      

  If you do not see these groups, take the following action:

  $ su -		# Enter root password
  # usermod -g nsadmin -G dba,web nsadmin
      

  If you get an error about an undefined group, then add that group manually:

  # groupadd dba
  # groupadd nsadmin
  # 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:

  $ 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
  $ su -
  ; Enter root password.
  # mkdir -p /ora8/m02/oradata/ora8/
  # chown nsadmin.web /ora8/m02/oradata/ora8
  # chmod 775 /ora8/m02/oradata/ora8
  # exit
  $
      

• 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.

  $ svrmgrl
  
  SVRMGR> connect internal;
  SVRMGR> create tablespace service_name datafile '/ora8/m02/oradata/ora8/service_name01.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. (Substitute database_password with the appropriate password.)

  Write down what you specify as service_name and database_password. You will need this information for configuring exports and AOLserver.

  SVRMGR> create user service_name identified by database_password default tablespace service_name
  temporary tablespace temp quota unlimited on service_name;
  SVRMGR> grant connect, resource, ctxapp, javasyspriv, query rewrite to service_name;
  SVRMGR> revoke unlimited tablespace from service_name;
  SVRMGR> alter user service_name quota unlimited on service_name;
  SVRMGR> exit;
      

  Your table space is now ready. In case you are trying to delete a previous ACS installation, consult these commands in the appendix below.

• Make sure that you can login to Oracle using your service_name account:

  $ sqlplus service_name/database_password
  SQL> select sysdate from dual;
  
  SYSDATE
  ----------
  2000-06-11
  
  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 Oracle documentation.

Configuring 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 ACS to work, you need to configure a virtual server. Because the process is involved, we have prepared a sample virtual server configuration file.

• Allot an IP address: You must know what IP address has been assigned to your web service. If you don't know, contact your system administrator and find out. If you do not have a network connection, use localhost 127.0.0.1 Once you have installed a virtual server as described below, you should notify your sysadmin that you have claimed this IP.

• Save the template configuration file template-ini.ini into /tmp.

• Login as nsadmin:

  $ cp /tmp/template-ini.ini /home/aol31/service_name.ini
      

• Replace the following variables in the file as dictated below using a text editor. You must specify a service port for your web server to run. The standard HTTP port number is port 80. If you are already running a web server (such as Apache, then port 80 is likely no longer available. We recommend setting the service port to 8080 for a first time installation. No other service uses this port and special access is not required to use it. If you want to use port 80, please read Appendix B.

  Variable to replace	Target Value
  service_database_username	service_name
  service_database_password	database_password
  AOL_HOME	/home/aol31
  service_short_name	service_name
  service_short_description	a description of your service
  service_email	the email address of the maintainer
  ACS_HOME	/web/service_name
  service_ip_address	your ip address
  service_ip_name	your dns name
  service_port	what port to use (80 is standard HTTP port)
  service_ip_address_ssl	disabled by default
  service_ip_name_ssl	disabled by default
  service_port_ssl}	disabled by default

• Copy this nsd-oracle script into /tmp/nsd-oracle.txt:

  $ cd /usr/local/aolserver/bin
  $ cp /tmp/nsd-oracle.txt ./nsd-oracle
  $ chmod 700 /usr/local/aolserver/bin/nsd-oracle
      

  If you deviated from the Oracle installation defaults we specified, edit nsd-oracle as necessary.

• Kill any current running AOLserver processes and start a new one:

  $ killall -9 nsd
  ; Should probably see:
  nsd: no process killed    
  $ /usr/local/aolserver/bin/nsd-oracle -c /home/aol31/servername.ini
      

  Attempt to connect to the service from a web browser as you did in the AOLserver documentation. 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 the next section.

  If you don't see the login page, view your error log (/home/aol31/log/servername-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.

  $ killall -9 nsd
      

TOP

Using the ACS Installer

Assuming you got your AOLserver up and running previously,

• You should see a page from the webserver titled ACS Installation: Welcome. You will be warned if your version of the Oracle driver is out of date, if AOLserver cannot connect to the database, 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 ACS Kernel data model.

• The next page shows the results of loading the ACS Kernel data model - be prepared to wait 20-30 seconds as it works. You should see a string of "No errors." as the tables are created in Oracle. 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 "Done installing packages." - click Create Administrator.

• You should see a page, "ACS Installation: Create Administrator" with form fields to define the ACS site administrator. Fill out the fields as appropriate, and click Create User.

• You should see a page, "ACS Installation: Set System Information" allowing you to essentially name your service. Fill out the fields as appropriate, and click Set System Information

• You'll see the final Installer page, "ACS Installation: Complete." It will tell you that the server is being restarted; note that unless you already added your AOLserver entry to the inittab, you'll need to manually restart your service.

• After the server restarts and you reload the final page above, you should see a login screen, asking for your email address and password. Congratulations, ACS 4 is now up and running.

Troubleshooting

If you can't get to the login page, check for one of the below errors:

• If you don't see a page at all.

  Check the log file. Make sure there is a line like:

  Notice: nssock: listening on http://localhost.localdomain:8000
     

  If you can't find this line, look for a line specifying an error listening to a port. Such errors are caused if another process is listening to that port or if you don't have permission to access the port. Try using another port, perhaps 8086. You specify the port in /home/aol30/service_name.ini under [ns/server/service_name/module/nssock] Here is a sample for a computer programmed to listen to 127.0.0.1:8080. Try replacing the entries in your file with this one.

  [ns/server/service_name/module/nssock]
  timeout=120
  Address=127.0.0.1
  Hostname=127.0.0.1
  Port=8080
  

• Carefully scan the error log file for other entries flagged as errors. If you can't figure out what is wrong, try posting to the web/db bboard.

TOP

Ensure that Your Service Automatically Starts on Boot (or any other time the service dies)

This step should be completed as root. This can break every service on your machine, so proceed with caution.

• Copy this restart-aolserver 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.

  $ su - 
  ; Enter root password.    
  # cp /tmp/restart-aolserver.txt /usr/local/bin/restart-aolserver
  # chown root.web /usr/local/bin/restart-aolserver
  # chmod 4750 /usr/local/bin/restart-aolserver
  # ln -s /usr/bin/perl /usr/local/bin/perl
  # su - nsadmin
  

• Test the restart-aolserver script by making sure all servers are dead, starting a new server, and then killing it. You should see the following lines.

  $ killall -9 nsd
  nsd: no process killed
  $ /usr/local/aolserver/bin/nsd-oracle -c /home/aol31/service_name.ini
  $ restart-aolserver service_name
  Killing 23727 23728 23729 23730
  $ killall -9 nsd
  nsd: no process killed
  

  The numbers indicate the process ids (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.

  $ su -
  ; Enter root password
  # emacs -nw /etc/inittab    
  

• Copy this line into the bottom of the file as a template, making sure that the first field nss is unique.

  nss:2345:respawn:/usr/local/aolserver/bin/nsd-oracle -i -c /home/aol31/service_name.ini
  

• 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.

  # killall -9 nsd    
  # /sbin/init q
  

• Important: See if it worked by running the restart-aolserver script again.

  # restart-aolserver service_name
  Killing 23750 23753 23754 23756
  

Appendix A: How to Transfer Data

exp service_name/database_password file=foo.dmp consistent=y full=y

To import:

imp service_name/database_password file=foo.dmp [fromuser=olduser touser=service_name]

Appendix B: Running AOLserver on Port 80

User=nsadmin

These steps are required because 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.

TOP

Appendix C: Deleting a tablespace

drop user
service_name 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:

 select username, sid, serial# from v$session where username='service_name'; 

and then

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:

drop tablespace service_name including contents cascade constraints;

Appendix D: Set Up Nightly Oracle Exports

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 (see appendix). 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:

  $ su -
  ; Enter root password
  # cp /tmp/export-oracle.txt /usr/sbin/export-oracle
  # 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.

  # mkdir /ora8/m02/oracle-exports
  # chown oracle.dba /ora8/m02/oracle-exports
  # 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:

  # /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.

  # export EDITOR="emacs -nw"
  # 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.

  # crontab -l | grep export-oracle
  0 23 * * * /usr/sbin/export-oracle
  # exit
  ; Logout
      

  If you see the line, go ahead and log out.