Installation Guide

Installation Guide

This guide details how to install a deployment version of the OCE system from the binary distribution.

Certain optional steps (where indicated) require a development environment to be set up.

Base Installation

The following tasks should be undertaken with a user account containing Administrator or root privileges.

Copy all frameworks from the Frameworks directory into the Apple third party frameworks directory.
- Mac OS X: /Library/Frameworks
- Windows: $NEXT_ROOT/Local/Library/Frameworks
  {where $NEXT_ROOT is the value of the NEXT_ROOT environment variable}

Copy all applications from the Applications directory into the Apple third party WebObjects application directory.
- Mac OS X: /Library/WebObjects/Applications
- Windows: $NEXT_ROOT/Local/Library/WebObjects/Applications

Install the log4j jar file from the Apache Log4J distribution into the Resources/Java subdirectory of the installed CassiniJava framework.

Install the commons-codec jar file from the Apache Commons Codec distribution into the Resources/Java subdirectory of the installed CassiniJava framework.

(If required) Obtain the JDBC driver jar files for the chosen database into the Java JRE ext directory.
- Mac OS X: /Library/Java/Extensions
- Windows: $WEBOBJECTS_JAVA_EXTENSIONS
  {where $WEBOBJECTS_JAVA_EXTENSIONS is the value of the WEBOBJECTS_JAVA_EXTENSIONS environment variable}

Set up a suitable blank database.
It is recommended the database be titled OCE.

A database account should be created for the database with SELECT / INSERT / UPDATE / DELETE / CREATE TABLE / DROP TABLE permissions granted.

Configure (or replace) the following EOModels in the frameworks described below for the database to be used.

OCE-Content framework: OCE_Content.eomodeld
OCE-Navigation framework: OCE_Navigation.eomodeld
OCE-Users framework: OCE_Users.eomodeld

In addition, set the connection dictionary information as required by the database for each EOModel.

NOTES:
- The default EOModels supplied are set up for use with a MySQL database.
- Example preconfigured EOModels for other common databases may be found in the software distribution under ExampleEOModels.
- If the required database is not listed, convert the datatypes for each EOModel using the "Switch Adaptor" functionality in the Apple EOModeler application, and carefully check the new database internal types.
  
  If in doubt about how to go about this procedure, contact the OCE distribution lists on SourceForge or Cassini Division for further advice.

Set up OCE with a chosen sample database.

The sample sites are listed as indidual directories under ExampleSites.

Open a command-line interface window.
Change directory to the following location:
- Mac OS X: /Library/WebObjects/Applications/CassiniEOUtil.woa
- Windows:$NEXT_ROOT/Local/Library/WebObjects/Applications/CassiniEOUtil.woa

CassiniEOUtil -import -schemaDrop -schemaCreate -path {sample_database_directory}
-modelPaths {list_of_model_paths}

```
{sample_database_directory}
```
is the path to the example database.

This will be located in the Database subdirectory of the chosen sample site.
For example:

D:/OCE/ExampleSites/OCEDemo-Trivial/Database
```
{list_of_model_paths}
```
is a comma-separated list of paths to the three EOModels (OCE_Content, OCE_Navigation, OCE_Users).
For example:
```
D:/Apple/Local/Library/Frameworks/OCE-Content.framework/Resources/OCE-Content.eomodeld,
D:/Apple/Local/Library/Frameworks/OCE-Users.framework/Resources/OCE-Users.eomodeld,
D:/Apple/Local/Library/Frameworks/OCE-Navigation.framework/Resources/OCE-Navigation.eomodeld
```
Some error messages may be displayed during the import process.
In general, messages of the form "table does not exist" may be ignored; other messages may indicate genuine errors.
It is a obviously near-impossible task to generalize the all the responses that could be generated for all possible databases.
Check the OCE SourceForge distribution lists for advice if necessary.

Example invocations:

Windows

CassiniEOUtil.cmd -import -schemaDrop -schemaCreate -path D:/OCE/ExampleSites/OCEDemo-Trivial/Database
 -modelPaths "D:/Apple/Local/Library/Frameworks/OCE-Content.framework/Resources/OCE-Content.eomodeld,
D:/Apple/Local/Library/Frameworks/OCE-Users.framework/Resources/OCE-Users.eomodeld,
D:/Apple/Local/Library/Frameworks/OCE-Navigation.framework/Resources/OCE-Navigation.eomodeld"

Mac OS X

./CassiniEOUtil -import -schemaDrop -schemaCreate -path "/oce/ExampleSites/OCEDemo-Trivial/Database" 
-modelPaths "/Library/Frameworks/OCE-Content.framework/Resources/OCE-Content.eomodeld,
/Library/Frameworks/OCE-Users.framework/Resources/OCE-Users.eomodeld,
/Library/Frameworks/OCE-Navigation.framework/Resources/OCE-Navigation.eomodeld"

Check the database has been installed correctly by running the OCE-UserAdmin application.

Start the OCE-UserAdmin web application by running ("double-clicking" on) the following:
- Mac OS X: /Library/WebObjects/Applications/OCE-UserAdmin.woa
- Windows:$NEXT_ROOT/Local/Library/WebObjects/Applications/OCE-UserAdmin.woa/OCE-UserAdmin.cmd
After a few moments a web browser window should appear prompting for a login.
Log in using one of the accounts specified by the chosen sample database.
(For example: for the OCEDemo-Trivial example site, enter demo, password demo.)

You should be directed to a new page containing a list of user accounts.

(Optional) Create new user accounts, assigning roles as appropriate.

Now quit the application, closing related browser/terminal windows.

Examine the navigational structure of the example site by running the OCE-SiteAdmin application.

Start the OCE-SiteAdmin web application by running ("double-clicking" on) the following:
- Mac OS X: /Library/WebObjects/Applications/OCE-SiteAdmin.woa
- Windows:$NEXT_ROOT/Local/Library/WebObjects/Applications/OCE-SiteAdmin.woa/OCE-SiteAdmin.cmd
After a few moments a web browser window should appear prompting for a login.
Log in using one of the accounts specified by the chosen sample database.
(For example: for the OCEDemo-Trivial example site, enter demo, password demo.)

You should be directed to a new page containing a top bar with a set of options.

Click on Edit Organisations and WebSites.
This should take you to a page listing all the current organisations.

Click on the WebSites arrow for a given organisation.
This should take you to a page listing all the current web sites for the chosen organisation.

Click on the Sections arrow for a given web site.
A hierarchical display of sections should appear.
If you click on Edit Section Details the settings for the root section of the site will be visible.

Now quit the application, closing related browser/terminal windows.
Configure an instance of OCE-Server to run from JavaMonitor.

(If necessary) Back up the wotaskd site configuration file first:
- Mac OS X: /Library/WebObjects/Configuration/SiteConfig.xml
- Windows:$NEXT_ROOT/Local/Library/WebObjects/Configuration/SiteConfig.xml
Check the JavaMonitor service/daemon is running.

Access the JavaMonitor front page using a web browser.

(If necessary) Add host machine details.

Configure an instance of OCE-Server to run using JavaMonitor.
(Consult the Apple documentation for how to do this if necessary.)

Start the instance in JavaMonitor (make sure the instance starts correctly).

(If necessary) Configure a WebObjects adaptor to work with the web server/wotaskd configuration.

(If necessary) Start the web server.

Try accessing the instance with a suitable URL from a web browser, e.g.:
- Apache: http://localhost/cgi-bin/WebObjects/OCE-Server
- IIS:http://localhost/scripts/WebObjects.dll/OCE-Server
You should see a page with the following text:
```
OCE-Server is running.
```
NOTE: Further instances of OCE-Server may be set up in JavaMonitor if desired - the application is fully scalable.

Content Publishing

Set up DNS/host details for the web site domain names as described in the README file for the chosen sample site.

Mac OS X platform:

One way of adding the new DNS details (or the local machine only) is via the SystemPreferences application.

Windows platform:

Add these entries into the naming system (DNS/WINS etc) operational on the Windows network.

The easiest way to do this (for local machine testing only) is via the Windows HOSTS file.
Add lines into $WINNT/System32/Drivers/etc/Hosts akin to the following:
```
127.0.0.1 mywebsite.test
```
Configure the web server to handle each virtual web site corresponding to each new DNS entry.

This is highly web-server specific - only general guidelines are provided for here.

Examples on how to do this are supplied under the Configuration directory for each sample database provided.
Specific web server guidance:

Apache

Create a new, separate directory which will act as the document root.
Add virtual host details as appropriate, e.g.:
```
	NameVirtualHosts *

	<VirtualHost *>
    		ServerName mywebsite.test	
		...
	</VirtualHost>
```
Stop and restart the web server (a full shutdown is recommended so that the new DNS details will be picked up).

You may need to stop/restart/quit the following:
- WebObjects Task Daemon
- The web browser
- The web server

NOTE: From this point onwards, we recommend referencing the OCE applications from the DNS domain for the site being published, e.g. http://mywebsite.test , rather than http://localhost (or similar). This is so that all the media assets (images etc) will appear and be referenced correctly from the given domain. If all assets for all sites are shared from one common directory then this may not be required.

(If required) Build any custom WebObjects component frameworks required by the sample sites.

You will need an appropriate OCE development environment set up to do this.
(If required) Compile a new version of the OCE-Server application which links in the additional frameworks.

You will need a copy of the OCE source distribution for this step, together with an appropriate OCE development environment set up.

Stop any previous running instances of the OCE-Server application.

Make a copy of the "OCE-Server" source code directory supplied in the distribution.

Import the directory into Eclipse.

Open the "OCE-Server" project.
Open the OCE-Server project.
Right-click on the OCE-Server project and select Properties. Select Java Build Path in the browser.

Click on the Libraries tab.

Click on WOFrameworks in the display. Then click the "Edit..." button.

Add the required frameworks in the checkbox browser view.

Click Finish and then OK.

Select menu Project -> Rebuild Project (highlighting the project to allow selection if necessary).

Reinstall the newly-built version of OCE-Server to the location configured previously in JavaMonitor, which is likely to be:
- Mac OS X: /Library/WebObjects/Applications/OCE-Server.woa
- Windows:$NEXT_ROOT/Local/Library/WebObjects/Applications/OCE-Server.woa
Set up the shared Perl configuration module.

Copy the OCEConfig.pm file in the Perl/Modules directory to a suitable location in the Perl include variable path ( @INC ).
[ HINT:Run perl -V from a CLI window to see what this is. A typical location is {Perl Home Directory}/lib. ]

Open the OCEConfig.pm file in a text editor.

Check the values within are correct for the current setup.
See the comments in the file for further details.
Copy all files under the Perl/CGIScripts directory to the web server's CGI directory.
Check all required Perl modules have been installed and configured.

Using a command line interface tool, attempt to run each Perl (.pl) script using the Perl interpreter.
For example:
```
perl 404Handler.pl
```
Check for messages warning of missing modules.
Install the missing modules as required (retrieve the most recent versions).

The following modules in particular are likely to be absent:
```
String::Random
Log::Log4perl
```
NOTES:
- (ActivePerl distributions) The ppm utility may be used to easily install missing modules, e.g.:
```
ppm install String::Random
```
  Note an active internet connection is required.
- (Log::Log4perl module) At the time of writing this module should be retrieved directly from SourceForge along with the following modules:
```
Log-Dispatch
Params-Validate
```
  Here is the current procedure for ActivePerl:
```
ppm install "http://log4perl.sourceforge.net/ppm/Log-Dispatch.ppd"

ppm install "http://log4perl.sourceforge.net/ppm/Params-Validate.ppd"

ppm install "http://log4perl.sourceforge.net/ppm/Log-Log4perl.ppd"
```
Open the following Perl CGI scripts and check the configurable values as described at the beginning of each file are correct.

404Handler.pl
DeleteFeature.pl

In particular, check the path to the Perl interpreter is correct (first line).
We recommend an absolute path is supplied, e.g.:
- Mac OS X:
```
#!/usr/bin/perl
```
- Windows:
```
#!D:/perl/bin/perl
```
Back up each file and change as necessary.
See the comments in each file for further details.
Check the web server can recognize Perl script extensions/ allows Perl CGI script execution.

Apache example: The following line should be added (if necessary) to the httpd.conf configuration file:
```
AddHandler cgi-script .pl
```
Restart the web server if necessary.
It should now be possible to publish the chosen sample web site on-demand by trawling the front page and associated hyperlinks.

Attempt to view the front page for one of the sample site DNS domains, e.g.:

http://mywebsite.test

If Page Not Found appears, OCE-Server may not be running, or the web server may not have been configured correctly.
- Check OCE-Server is running in JavaMonitor.
- Check the host DNS details are known by the current host.
  HINT: Enter ping {domain} from a command line window.
- Check the web server / WebObjects adaptor configuration.
- Check the CGI Perl scripts have been configured correctly.
- Check the log files generated by the Perl scripts for additional diagnostics.
  The logging level can be adjusted by editing the following line in each script;
  e.g. to set the logging level to DEBUG:
```
Log::Log4perl->easy_init( { level => $DEBUG, ...
```
If the page appears, but contains error messages, check the following:
- Check all the required frameworks have been linked into OCE-Server.
- Check all the required frameworks have been linked into OCE-Server.
- Check for component bugs / errors in the frameworks linked into OCE-Server.
- Check the sample database was set up correctly.
  Try re-importing the database.
  Examine any error messages carefully.