Use daemontools supervise and svc, or inittab, to automate server startup and shutdown.

Install Full Text Search (OPTIONAL). If you have installed OpenFTS and enabled OpenFTS, you can now install the OpenFTS Driver package and Full Text Search Engine package in the OpenACS service.

This is a good time to make a backup of your service. If this is a production site, you should set up automatic nightly backups.

If you want traffic reports, set up analog or another log processing program.

Follow the instruction on the home page to change the appearance of your service or add more packages. (more information)

Proceed to the tutorial to learn how to develop your own packages.

Set up database environment variables for the site user. Depending on how you installed Oracle or PostGreSQL, these settings may be necessary for working with the database while logged in as the service user. They do not directly affect the service's run-time connection with the database, because those environmental variables are set by the wrapper scripts nsd-postgres and nsd-oracle.

[root root]# su - $OPENACS_SERVICE_NAME

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ emacs .bashrc

Put in the appropriate lines for the database you are running. If you will use both databases, put in both sets of lines.

Test this by logging out and back in as $OPENACS_SERVICE_NAME and checking the paths.

[$OPENACS_SERVICE_NAME $OPENACS_SERVICE_NAME]$ exit
logout
[root src]# su - $OPENACS_SERVICE_NAME

[$OPENACS_SERVICE_NAME ~]$ env

Test your backup and recovery procedure.

Set up the section called “External uptime validation”.

displaying objects and their properties

manipulating or acting on objects in some way (by creating, editing, linking, etc)

housing procedures, packages, data models and other prerequisite code Essentially, we want our files named in a fashion that reflects their purpose.

For naming files that enable a specific action on an object, use this format:

For example, the page to erase a user's portrait from the database is /admin/users/portrait-erase.tcl.

However, modules typically deal with only one primary type of object - e.g., the Bookmarks module deals mainly with bookmarks - and so action-type files in modules don't need to be specified by the object they act on. Example: the user pages for the Bookmarks module live in the /bookmarks/ directory, and so there is no need to name the bookmark editing page with a redundant url: /bookmarks/bookmark-edit.tcl. Instead, we omit the object type, and use this convention:

Thus, the page to edit a bookmark is /bookmarks/edit.tcl.

For naming files that display the properties of a primary object - such as the bookmark object within the bookmark module - use this convention:

For example, the page to view one bookmark is /bookmarks/one.tcl. Note that no verb is necessary for display-type files.

Otherwise, if the object to be displayed is not the primary feature of a module, simply omit the verb and use the object name:

For example, the page to view the properties of an ecommerce product is /ecommerce/product.tcl.

For naming files in a page flow, use the convention:

where foobar is determined by the above rules.

Typically, we use a three-step page flow when taking user information:

Put data model files in /www/doc/sql, and name them for the modules towards which they are used:

For files that contain module-specific procedures, use the convention:

For files that contain procedures that are part of the core ACS, use the convention:

A mandatory documentation string is the first argument. This has the standard form with javadoc-style @author, @cvs-id, etc, and should contain a short description of the recieved variables and any necessary explanations.

The second argument specifies the page inputs. The syntax for switches/flags (e.g. multiple-list, array, etc.) uses a colon (:) followed by any number of flags separated by commas (,), e.g. foo:integer,multiple,trim. In particular, multiple and array are the flags that correspond to the old ad_page_variables flags.

There are new flags: trim, notnull and optional. They do what you'd expect; values will not be trimmed, unless you mark them for it; empty strings are valid input, unless you specify notnull; and a specified variable will be considered required, unless you declare it optional.

ad_page_contract can do validation for you: the flags integer and sql_identifier will make sure that the values supplied are integers/sql_identifiers. The integer flag will also trim leading zeros. Note that unless you specify notnull, both will accept the empty string.

Note that ad_page_contract does not generate QQvariables, which were automatically created by ad_page_variables and set_the_usual_form_variables. The use of bind variables makes such previous variable syntax obsolete.

Oracle 8i Release Documentation

Oracle 9i Release Documentation

Oracle 10g Release Documentation

Login as a non-root user and start X by typing startx

[joeuser ~]$ startx

Open a terminal window type and login as root

[joeuser ~]$ su -
Password: ***********
[root ~]#

Create and setup the oracle group and oracle account

We need to create a user oracle, which is used to install the product, as well as starting and stopping the database.

[root ~]# groupadd dba
[root ~]# groupadd oinstall
[root ~]# groupadd oracle
[root ~]# useradd -g dba -G oinstall,oracle -m oracle
[root ~]# passwd oracle

You will be prompted for the New Password and Confirmation of that password.

Setup the installation location for Oracle. While Oracle can reside in a variety of places in the file system, OpenACS has adopted /ora8 as the base directory.

Note: the Oracle install needs about 1 GB free on /ora8 to install successfully.

[root ~]# mkdir /ora8
root:/ora8# cd /ora8
root:/ora8# mkdir -p m01 m02 m03/oradata/ora8
root:/ora8# chown -R oracle.dba /ora8
root:/ora8# exit

Set up the oracle user's environment

Make sure that you do not add any lines like the following

# NLS_LANG=american
# export NLS_LANG

These lines will change the Oracle date settings and will break OpenACS since OpenACS depends on the ANSI date format, YYYY-MM-DD dates.

Log out as oracle

[oracle ~]$ exit

Log back in as oracle and double check that your environment variables are as intended. The env command lists all of the variables that are set in your environment, and grep shows you just the lines you want (those with ORA in it).

[joeuser ~]$ su - oracle
[oracle ~]$ env | grep ORA

If it worked, you should see:

ORACLE_SID=ora8
ORACLE_BASE=/ora8/m01/app/oracle
ORACLE_TERM=vt100
ORACLE_HOME=/ora8/m01/app/oracle/product/8.1.7
ORA_NLS33=/ora8/m01/app/oracle/product/8.1.7/ocommon/nls/admin/data

If not, try adding the files to ~/.bashrc instead of .bash_profile. Then logout and log back in again. Also, be certain you are doing su - oracle and not just su oracle. The - means that .bashrc and .bash_profile will be evaluated.

Make sure that /bin, /usr/bin, and /usr/local/bin are in your path by typing:

[oracle ~]$ echo $PATH
/bin:/usr/bin:/usr/local/bin:/usr/bin/X11:/usr/X11R6/bin:/home/oracle/bin:/ora8/m01/app/oracle/product/8.1.7/bin

If they are not, then add them to the .bash_profile by changing the PATH statement above to PATH=$PATH:/usr/local/bin:$ORACLE_HOME/bin

Log in as oracle and start X if not already running. Start a new terminal:

[joeuser ~]$ xhost +localhost
[joeuser ~]$ su - oracle
Password: **********
[oracle ~]$ export DISPLAY=localhost:0.0

Find the runInstaller script

Check to make sure the file is there.

oracle:/where/oracle/Disk1$ ls
doc  index.htm  install  runInstaller  stage  starterdb

If you don't see runInstaller, you are in the wrong directory.

Run the installer

oracle:/where/oracle/Disk1$ ./runInstaller

A window will open that welcomes you to the 'Oracle Universal Installer' (OUI). Click on "Next"

The "File Locations" screen in the OUI:

The "Unix Group Name" screen in the OUI:

The "Available Products" screen in the OUI:

The "Installation Types" screen

The "Available Product Components" screen

The "Component Locations" screen in the OUI

The "Privileged Operation System Groups" screen in the OUI

The "Authentication Methods" screen

The next screen is "Choose JDK home directory"

The "Create a Database" screen in the OUI

The next screen is "Oracle Product Support"

The "Summary" screen in the OUI

[root ~]# exit
[joeuser ~]$ exit

Go back to the pop-up window and click "OK"

The "Configuration Tools" screen in the OUI

The "Welcome" screen in the "net 8 Configuration Assistant"

The "Listener Configuration, Listener Name" screen in the "Net 8 Configuration Assistant"

The "Listener Configuration, Select Protocols" screen in the "Net 8 Configuration Assistant"

The "Listener Configuration TCP/IP Protocol" screen in the "Net 8 Configuration Assistant"

The "Listener Configuration, More Listeners" screen in the "Net 8 Configuration Assistant"

The "Listener Configuration Done" screen in the "Net 8 Configuration Assistant"

The "Naming Methods Configuration" screen in the "Net 8 Configuration Assistant"

The "Done" screen in the "Net 8 Configuration Assistant"

The "End of Installation" screen in the OUI

Make sure you are running X. Open up a terminal and su to oracle and then run the dbassist program.

[joeuser ~]$ xhost +localhost
[joeuser ~]$ su - oracle
Password: *********
[oracle ~]$ export DISPLAY=localhost:0.0
[oracle ~]$ dbassist

The "Welcome" screen in the Oracle Database Configuration Agent (ODCA)

The "Select database type" screen in the ODCA

The "Primary Database Type" window in ODCA

The "concurrent users" screen of the ODCA

Select "Dedicated Server Mode", click "Next"

Accept all of the options, and click Next Oracle Visual Information Retrieval may be grayed out. If so, you can ignore it; just make sure that everything else is checked.

For "Global Database Name", enter "ora8"; for "SID", also enter "ora8" (it should do this automatically). Click "Change Character Set and select UTF8. Click "Next".

Accept the defaults for the next screen (control file location). Click "Next"

Go to the "temporary" and "rollback" tabs, and change the Size (upper-right text box) to 150MB. Click "Next"

Increase the redo log sizes to 10000K each. Click "Next"

Use the default checkpoint interval & timeout. Click "Next"

Increase "Processes" to 100; "Block Size" to 4096 (better for small Linux boxes; use 8192 for a big Solaris machine).

Accept the defaults for the Trace File Directory. Click "Next"

Finally, select "Save information to a shell script" and click "Finish" (We're going to examine the contents of this file before creating our database.)

Click the "Save" button. Oracle will automatically save it to the correct directory and with the correct file name. This will likely be /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib/sqlora8.sh

It will alert you that the script has been saved successfully.

Now we need to customize the database configuration a bit. While still logged on as oracle, edit the database initialization script (run when the db loads). The scripts are kept in $ORACLE_HOME/dbs and the name of the script is usually initSID.ora where SID is the SID of your database. Assuming your $ORACLE_HOME matches our default of /ora8/m01/app/oracle/product/8.1.7, the following will open the file for editing.

[oracle ~]$ emacs /ora8/m01/app/oracle/product/8.1.7/dbs/initora8.ora

Add the following line to the end:

nls_date_format = "YYYY-MM-DD"

Now find the open_cursors line in the file. If you're using emacs scroll up to the top of the buffer and do CTRL-S and type open_cursors to find the line. The default is 100. Change it to 500.

open_cursors = 500

Save the file. In emacs, do CTRL-X CTRL-S to save followed by CTRL-X CTRL-C to exit or use the menu.

At this point, you are ready to initiate database creation. We recommend shutting down X to free up some RAM unless you have 256 MB of RAM or more. You can do this quickly by doing a CRTL-ALT-BACKSPACE, but make sure you have saved any files you were editing. You should now be returned to a text shell prompt. If you get sent to a graphical login screen instead, switch to a virtual console by doing CRTL-ALT-F1. Then login as oracle.

Change to the directory where the database creation script is and run it:

[oracle ~]$ cd /ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib
oracle:/ora8/m01/app/oracle/product/8.1.7/assistants/dbca/jlib$ ./sqlora8.sh

In some instances, Oracle will save the file to /ora8/m01/app/oracle/product/8.1.7/assistants/dbca Try running the script there if your first attempt does not succeed.

Your database will now be built. It will take > 1 hour - no fooling. You will see lots of errors scroll by (like: "ORA-01432: public synonym to be dropped does not exist") Fear not, this is normal.

Eventually, you'll be returned to your shell prompt. In the meantime, relax, you've earned it.

You need to download the "Oracle Acceptance Test" file. It's available here and at http://philip.greenspun.com/wtr/oracle/acceptance-sql.txt. Save the file to /var/tmp

In the oracle shell, copy the file.

[oracle ~]$ cp /var/tmp/acceptance-sql.txt /var/tmp/acceptance.sql

Once you've got the acceptance test file all set, stay in your term and type the following:

[oracle ~]$ sqlplus system/manager

SQL*Plus should startup. If you get an ORA-01034: Oracle not Available error, it is because your Oracle instance is not running. You can manually start it as the oracle user.

[oracle ~]$ svrmgrl
SVRMGR> connect internal
SVRMGR> startup

Now that you're into SQL*Plus, change the default passwords for system, sys, and ctxsys to "alexisahunk" (or to something you'll remember):

SQL> alter user system identified by alexisahunk;
SQL> alter user sys identified by alexisahunk;
SQL> alter user ctxsys identified by alexisahunk;

Verify that your date settings are correct.

SQL> select sysdate from dual;

If you don't see a date that fits the format YYYY-MM-DD, please read the section called “Troubleshooting Oracle Dates”.

At this point we are going to hammer your database with an intense acceptance test. This usually takes around 30 minutes.

SQL> @ /var/tmp/acceptance.sql

; A bunch of lines will scroll by.  You'll know if the test worked if
; you see this at the end:

SYSDATE
----------
2000-06-10

SQL>

Many people encounter an error regarding maximum key length:

ERROR at line 1:
ORA-01450: maximum key length (758) exceeded

This error occurs if your database block size is wrong and is usually suffered by people trying to load OpenACS into a pre-existing database. Unfortunately, the only solution is to create a new database with a block size of at least 4096. For instructions on how to do this, see the section called “Creating the First Database” above. You can set the parameter using the dbassist program or by setting the DB_BLOCK_SIZE parameter in your database's creation script.

If there were no errors, then consider yourself fortunate. Your Oracle installation is working.

Oracle includes a script called dbstart that can be used to automatically start the database. Unfortunately, the script shipped in the Linux distribution does not work out of the box. The fix is simple. Follow these directions to apply it. First, save dbstart to /var/tmp. Then, as oracle, do the following:

[oracle ~]$ cp /var/tmp/dbstart.txt /ora8/m01/app/oracle/product/8.1.7/bin/dbstart 
[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/dbstart

While you're logged in as oracle, you should configure the oratab file to load your database at start. Edit the file /etc/oratab:

You need a script to automate startup and shutdown. Save oracle8i.txt in /var/tmp. Then login as root and install the script. (Debian users: substitute /etc/init.d for /etc/rc.d/init.d throughout this section)

[oracle ~]$ su -
[root ~]# cp /var/tmp/oracle8i.txt /etc/rc.d/init.d/oracle8i
[root ~]# chown root.root /etc/rc.d/init.d/oracle8i
[root ~]# chmod 755 /etc/rc.d/init.d/oracle8i

Test the script by typing the following commands and checking the output. (Debian Users: as root, do mkdir /var/lock/subsys first)

[root ~]# /etc/rc.d/init.d/oracle8i stop
Oracle 8i auto start/stop
Shutting Oracle8i:
Oracle Server Manager Release 3.1.7.0.0 - Production

Copyright (c) 1997, 1999, Oracle Corporation.  All
Rights Reserved.

Oracle8i Enterprise Edition Release 8.1.7.0.1 -
Production
With the Partitioning option
JServer Release 8.1.7.0.1 - Production

SVRMGR> Connected.
SVRMGR> Database closed.
Database dismounted.
ORACLE instance shut down.
SVRMGR>
Server Manager complete.
Database "ora8" shut down.
      
[root ~]# /etc/rc.d/init.d/oracle8i start
Oracle 8i auto start/stop
Starting Oracle8i: 
SQL*Plus: Release 8.1.7.0.0 - Production on Wed Mar 6 17:56:02 2002

(c) Copyright 2000 Oracle Corporation.  All rights reserved.

SQL> Connected to an idle instance.
SQL> ORACLE instance started.

Total System Global Area   84713632 bytes
Fixed Size                    73888 bytes
Variable Size              76079104 bytes
Database Buffers            8388608 bytes
Redo Buffers                 172032 bytes
Database mounted.
Database opened.
SQL> Disconnected

Database "ora8" warm started.

Database "ora8" warm started.

If it worked, then run these commands to make the startup and shutdown automatic.

You also need some scripts to automate startup and shutdown of the Oracle8i listener. The listener is a name server that allows your Oracle programs to talk to local and remote databases using a standard naming convention. It is required for Intermedia Text and full site search.

Download these three scripts into /var/tmp

Now issue the following commands (still as root).

[root ~]# su - oracle
[oracle ~]$ cp /var/tmp/startlsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
[oracle ~]$ cp /var/tmp/stoplsnr.txt /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr    
[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/startlsnr
[oracle ~]$ chmod 755 /ora8/m01/app/oracle/product/8.1.7/bin/stoplsnr
[oracle ~]$ exit
[root ~]# cp /var/tmp/listener8i.txt /etc/rc.d/init.d/listener8i
[root ~]# cd /etc/rc.d/init.d
root:/etc/rc.d/init.d# chmod 755 listener8i

Test the listener automation by running the following commands and checking the output.

root:/etc/rc.d/init.d# ./listener8i stop
Oracle 8i listener start/stop
Shutting down Listener for 8i: 
LSNRCTL for Linux: Version 8.1.7.0.0 - Production on 06-MAR-2002 18:28:49

(c) Copyright 1998, Oracle Corporation.  All rights reserved.

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost.localdomain)(PORT=1521)))
The command completed successfully

    
root:/etc/rc.d/init.d# ./listener8i start
Oracle 8i listener start/stop
Starting the Listener for 8i: 
LSNRCTL for Linux: Version 8.1.7.0.0 - Production on 06-MAR-2002 18:28:52

(c) Copyright 1998, Oracle Corporation.  All rights reserved.

Starting /ora8/m01/app/oracle/product/8.1.7/bin/tnslsnr: please wait...

TNSLSNR for Linux: Version 8.1.7.0.0 - Production
System parameter file is /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora
Log messages written to /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log
Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=tcp)(HOST=localhost.localdomain)(PORT=1521)))
Listening on: (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=EXTPROC)))

Connecting to (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=localhost.localdomain)(PORT=1521)))
STATUS of the LISTENER
------------------------
Alias                     LISTENER
Version                   TNSLSNR for Linux: Version 8.1.7.0.0 - Production
Start Date                06-MAR-2002 18:28:53
Uptime                    0 days 0 hr. 0 min. 0 sec
Trace Level               off
Security                  OFF
SNMP                      OFF
Listener Parameter File   /ora8/m01/app/oracle/product/8.1.7/network/admin/listener.ora
Listener Log File         /ora8/m01/app/oracle/product/8.1.7/network/log/listener.log
Services Summary...
  PLSExtProc        has 1 service handler(s)
  ora8      has 1 service handler(s)
The command completed successfully

This test will verify that the listener is operating normally. Login into the database using the listener naming convention.

sqlplususername/password/@SID

[root ~]# su - oracle
[oracle ~]$ sqlplus system/alexisahunk@ora8

SQL> select sysdate from dual;

SYSDATE
----------
2002-02-22

SQL> exit
[oracle ~]$ exit
[root ~]#

Test the automation

As a final test, reboot your computer and make sure Oracle comes up. You can do this by typing

[root ~]# /sbin/shutdown -r -t 0 now

Log back in and ensure that Oracle started automatically.

[joeuser ~]$ su - oracle
[oracle ~]$ sqlplus system/alexisahunk@ora8

SQL> exit

Dropping a tablespace