ACS Documentation :
ACS Installation Guide :
Installing the ArsDigita Community System v 4.0
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
- Downloading the ACS
- Prepare Oracle for the ACS
- Configuring AOLserver
- Using the ACS Installer
- Ensuring that Your Service Starts Automatically on Boot
- Appendix A: How to Transfer Data
- Appendix B: Running AOLserver on Port 80
- Appendix C: Deleting a Tablespace
- Appendix D: Setup Nightly Oracle Exports
Downloading the ACS
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.
TOP
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.
TOP
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
If the processes were killed, congratulations, your server is now
automated for startup and shutdown. On to the
Acceptance Tests!!
TOP
Appendix A: How to Transfer Data
If you are moving the service from one location to another, export
code for the old database and import into the new. If your database
has been hosed and you want to restore a backup, use the
imp command. These commands can be run from the shell,
you don't need to use
sqlplus.
To export:
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]
TOP
Appendix B: Running AOLserver on Port 80
If you want to run the service on port 80 (the default HTTP port), you
need to add some additional settings to your
service_name.ini file in
/home/aol30.
Under the
[ns/parameters] section, ensure that there is an entry
User=nsadmin
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.
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
Should it become necessary to rebuild a tablespace from scratch, you
can use the
drop user command with the
cascade option. This command will drop the user and
every database object the user owns.
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;
TOP
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.
bquinn@arsdigita.com
Last Modified: $Id: //websites/developer/prd/packages/acs-core-docs/www/install-guide/acs.html#1 $
