Installing the ArsDigita Community System v 3.3

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

1. Downloading the ACS
2. Prepare Oracle for the ACS
3. Setup nightly Oracle exports
4. Installing the ACS into Oracle
5. Configuring AOLServer
6. Ensuring that your service starts automatically on boot.
7. Appendix A: How to Transfer Data.
8. Appendix B: Running AOLServer on Port 80
9. Appendix C: Deleting a tablespace.

Downloading the ACS.

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

• Login as nsadmin and uncompress the downloaded components into /web. Substitute the correct file name into the line below. 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-3.3.tar.gz --directory=/web
  
  ; Stay logged in as nsadmin.
  

• You should now have a 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 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
  

• The ACS is configured by a single parameter file which is always stored in /web/service_name/parameters/. The name of the configuration file is not important, as long as it is not ad.ini. This is the name of the default file shipped with the ACS. Make a copy of this file and modify it to taste. You do not need to delete ad.ini.

  $ cd /web/service_name/parameters
  $ cp ad.ini service_name.ini
  Open service_name.ini your favorite editor.
  

  Use a text replace command to replace instances of "yourservername" with service_name. You should also scan the file and replace items such as "yourdomain Network" with a more appropriate setting. Consider at least setting the system name, the publisher name, and the email address of the system owner. You should also set all e-mail addresses to an actual e-mail account that can receive mail. Many pages display the system name at the top, so you should set this as well. You can revisit this file at any time to update the configuration.

TOP

Prepare Oracle for ACS

• Verify this 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 separate 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 will enable you to separate your Oracle system and database files onto separate disks for optimized performance. For more information on such a configuration, see Chapter 12 of the 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 exports 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.

Set up nightly Oracle exports

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

Installing the ACS into Oracle.

• Make sure that you can login to Oracle using your special service_name account created in step 1. Login as nsadmin.

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

• Load the states, country_codes and counties tables using the load-geo-tables shell script in the /web/service_name/www/install directory.

  $ cd /web/service_name/www/install
  $ ./load-geo-tables service_name/database_password
  

  You should see a long set of text scroll by. It should terminate with lines that look like this, but the numbers may be different.

  loading currency_codes.ctl...
  
  SQL*Loader: Release 8.1.6.1.0 - Production on Sun Jun 11 18:15:36 2000
  
  (c) Copyright 1999 Oracle Corporation.  All rights reserved.
  
  Commit point reached - logical record count 64
  Commit point reached - logical record count 128
  Commit point reached - logical record count 162
  loading states.ctl...
  
  SQL*Loader: Release 8.1.6.1.0 - Production on Sun Jun 11 18:15:44 2000
  
  (c) Copyright 1999 Oracle Corporation.  All rights reserved.
  
  Commit point reached - logical record count 64
  Commit point reached - logical record count 69
  

• Load the ACS data models.

  The data models are the heart of the ACS. They define all of the table structures, referential integrity constraints, and procedures that enable the community system.

  $ cd /web/service_name/www/doc/sql
  $ sqlplus service_name/database_password < load-data-model.sql
  ; This should take about 15 minutes.  Ignore the vast lines of text
  ; that will fill the screen.
  

• Load the site-wite-search module

  $ cd /web/service_name/www/doc/sql
  $ ./load-site-wide-search service_name database_password ctxsys_password
  SQL> exit
  

  Watch the screen carefully for errors. If you see any errors, that means something went wrong and site wide search is not enabled. Attempt to resolve the issue and then try the script again.

  If you can't remember the password for the ctxsys user, do::

  $ svrmgrl
  SVRMGR> connect internal;
  SVRMGR> alter user ctxsys identified by ctxsys_password;
  SVRMGR> exit;
  

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 system. 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/aol30/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 this appendix.

  Variable to replace	Target Value
  service_database_username	service_name
  service_database_password	database_password
  AOL_HOME	/home/aol30
  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 /home/aol30/bin
  $ cp /tmp/nsd-oracle.txt nsd-oracle
  $ chmod 700 /home/aol30/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    
  $ /home/aol30/bin/nsd-oracle -c /home/aol30/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 you do, try to login. Specify a username of system and a password of changeme.

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

Troubleshooting

• You see a page with the message Error Serving Group Pages.

  Take the following actions:

  1. Edit /home/aol30/service_name.ini Make sure that there is a line auxconfigdir=/web/service_name/parameters and that it is correct.
  2. Make sure that there is a file /web/service_name/parameters/service_name.ini. Edit this file and replace the default values if necessary.
  3. Kill your old AOLServer and restart it using the commands above for testing it.

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

• 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
  $ /home/aol30/bin/nsd-oracle -c /home/aol30/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:/home/aol30/bin/nsd-oracle -i -c /home/aol30/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;