Install Oracle 8.1.7

If you are installing PostGreSQL instead of Oracle, skip this
section.

OpenACS 5.9.0 will install with Oracle 9i but has not been
extensively tested so may still have bugs or tuning issues. See
Andrew Piskorski's Oracle 9i notes for
guidance.

This installation guide attempts to present all of the
information necessary to complete an OpenACS installation. We try
hard to make all of the steps possible in one pass, rather than
having a step which amounts to "go away and develop a profound
understanding of software X and then come back and, in 99% of all
cases, type these two lines." The exception to our rule is
Oracle production systems. This page describes a set of steps to
get a working Oracle development server, but it is unsuitable for production systems.
If you will be using OpenACS on Oracle in a production environment,
you will experience many problems unless you develop a basic
understanding of Oracle which is outside the scope of this
document. T

This document assumes that you'll be installing Oracle on
the same box as AOLserver. For more details on a remote Oracle
installation, see Daryl Biberdorf's document.

Each Oracle release comes with extensive and usually quite
well-written documentation. Your first step should be to thoroughly
read the release notes for your operating system and your Oracle
version. Find the docs here:

It is generally useful to run a particular Oracle version with
its latest patchset. At the time of writing these were 8.1.7.4 and
9.2.0.5, both of which are considered to be very stable.

To be able to download a patchset, you need a (to-pay-for)
account on Metalink. You may find the appropriate patchset
by following Andrew's suggestion.

Things to Keep in Mind

Oracle is very well-documented software, the online
documentation comes with printable PDFs and full-text search.
Altogether there is more than 20.000 pages of documentation, so do
not expect to understand Oracle within in a few hours. The best
starting pointing into Oracle is the Concepts book. Here's the
8i version and the 9.2 version.

Throughout these instructions, we will refer to a number of
configurable settings and advise certain defaults. With the
exception of passwords, we advise you to follow these defaults
unless you know what you are doing. Subsequent documents will
expect that you used the defaults, so a change made here will
necessitate further changes later. For a guide to the defaults,
please see the section
called “Defaults”.

In order for OpenACS to work properly you need to set the
environment appropriately.

Pre-Installation Tasks

Though Oracle 8.1.7 has an automated installer, we still need to
perform several manual, administrative tasks before we can launch
it. You must perform all of these steps as the root user. We recommend entering the X
window system as a normal user and then doing a su -. This command gives you full root
access.

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.

Use a text editor to edit the .bash_profile file in the oracle account home directory.

[oracle ~]$ emacs .bash_profile

You may get this error trying to start emacs:

Xlib: connection to ":0.0" refused by server
Xlib: Client is not authorized to connect to Server
emacs: Cannot connect to X server :0.
Check the DISPLAY environment variable or use `-d'.
Also use the `xhost' program to verify that it is set to permit
connections from your machine.

Save the file by typing CTRL-X
CTRL-S and then exit by typing CTRL-X CTRL-C. Alternatively, use the
menus.

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

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:

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

Note

Some people have had trouble with this step on RedHat 7.3 and
8.0. If so, try the following steps before calling ./runInstaller:

Execute the following command: /usr/i386-glibc21-linux/bin/i386-glibc21-linux-env.sh

Type export
LD_ASSUME_KERNEL=2.2.5

The "File Locations" screen in the OUI:

"Source" path should have been prefilled with
"(wherever you mounted the CDROM)/stage/products.jar"

"destination" path says "/ora8/m01/app/oracle/product/8.1.7"

If the destination is not correct it is because your environment
variables are not set properly. Make sure you logged on as
oracle using su - oracle. If so, edit the ~/.bash_profile as you did in the section called “Pre-Installation
Tasks”

In addition to the defaults, make sure that "Oracle SQLJ
8.1.7.0," "Oracle Protocol Support 8.1.7.0.0," and
"Linux Documentation 8.1.7.0.0" are also checked.

Click "Next"

A progress bar will appear for about 1 minute.

The "Component Locations" screen in the OUI

Click on the "Java Runtime Environment 1.1.8" It
should have the path "/ora8/m01/app/oracle/jre/1.1.8"

Click "Next"

A progress bar will appear for about 1 minute.

The "Privileged Operation System Groups" screen in the
OUI

Enter "dba" for "Database Administrator (OSDBA)
Group"

Enter "dba" for the "Database Operator (OSOPER)
Group"

Click "Next"

A progress bar will appear for about 1 minute.

The "Authentication Methods" screen

Click "Next"

The next screen is "Choose JDK home directory"

Keep the default path: /usr/local/java

Click "Next"

The "Create a Database" screen in the OUI

Select "No" as we will do this later, after some
important configuration changes.

Click "Next"

The next screen is "Oracle Product Support"

TCP should be checked with "Status" listed as
Required

Click "Next"

The "Summary" screen in the OUI

Check the "Space Requirements" section to verify you
have enough disk space for the install.

Check that "(144 products)" is in the "New
Installations" section title.

Click "Install"

A progress bar will appear for about 20 - 30 minutes. Now is a
good time to take a break.

A "Setup Privileges" window will popup towards the end
of the installation asking you to run a script as root

Run the script. Switch to the oracle user first to set the
environment appropriately and then do su to get root privileges, while
keeping the oracle user's environment.

[joeuser ~]$ su - oracle
Password: *********
[oracle ~]$ su
Password: *********
[root ~]# /ora8/m01/app/oracle/product/8.1.7/root.sh
; You should see the following.
Creating Oracle Inventory pointer file (/etc/oraInst.loc)
Changing groupname of /ora8/m01/app/oracle/oraInventory to oinstall.
# /ora8/m01/app/oracle/product/8.1.7/root.sh
Running Oracle8 root.sh script...
The following environment variables are set as:
ORACLE_OWNER= oracle
ORACLE_HOME= /ora8/m01/app/oracle/product/8.1.7
ORACLE_SID= ora8
Enter the full pathname of the local bin directory: [/usr/local/bin]:
Press ENTER here to accept default of /usr/local/bin
Creating /etc/oratab file...
Entry will be added to the /etc/oratab file by
Database Configuration Assistants when a database is created
Finished running generic part of root.sh script.
Now product-specific root actions will be performed.
IMPORTANT NOTE: Please delete any log and trace files previously
created by the Oracle Enterprise Manager Intelligent
Agent. These files may be found in the directories
you use for storing other Net8 log and trace files.
If such files exist, the OEM IA may not restart.

Do not follow the instructions on deleting trace and log files,
it is not necessary.

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

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

The "Configuration Tools" screen in the OUI

This window displays the config tools that will automatically be
launched.

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

Make sure the "Perform Typical installation" is
not selected.

Click "Next"

The "Directory Service Access" screen in the "Net
8 Configuration Assistant"

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

Select "Create a database"

Click "Next"

The "Select database type" screen in the ODCA

Select "Custom"

Click "Next"

The "Primary Database Type" window in ODCA

Select "Multipurpose"

Click "Next"

The "concurrent users" screen of the ODCA

Select "60" concurrent users.

Click "Next"

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:

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.

Automating Startup &
Shutdown

You will want to automate the database startup and shutdown
process. It's probably best to have Oracle spring to life when
you boot up your machine.

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:

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 will see this line.

ora8:/ora8/m01/app/oracle/product/8.1.7:N

By the way, if you changed the service name or have multiple
databases, the format of this file is:

service_name:$ORACLE_HOME:Y || N (for
autoload)

Change the last letter from "N" to "Y". This
tells Oracle that you want the database to start when the machine
boots. It should look like this.

ora8:/ora8/m01/app/oracle/product/8.1.7:Y

Save the file & quit the terminal.

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)

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.

Troubleshooting Oracle
Dates

Oracle has an internal representation for storing the data based
on the number of seconds elapsed since some date. However, for the
purposes of inputing dates into Oracle and getting them back out,
Oracle needs to be told to use a specific date format. By default,
it uses an Oracle-specific format which isn't copacetic. You
want Oracle to use the ANSI-compliant date format which is of form
'YYYY-MM-DD'.

To fix this, you should include the following line in
$ORACLE_HOME/dbs/initSID.ora or for the default case, $ORACLE_HOME/dbs/initora8.ora

nls_date_format = "YYYY-MM-DD"

You test whether this solved the problem by firing up
sqlplus and typing:

SQL> select sysdate from dual;

You should see back a date like 2000-06-02. If some of the date is chopped
off, i.e. like 2000-06-0,
everything is still fine. The problem here is that sqlplus is simply truncating the output.
You can fix this by typing:

SQL> column sysdate format a15
SQL> select sysdate from dual;

If the date does not conform to this format, double-check that
you included the necessary line in the init scripts. If it still
isn't working, make sure that you have restarted the database
since adding the line: