How to install ACS on Windows

• source: http://software.arsdigita.com/dist
• bug reports: acs-bugs@arsdigita.com
• philosophy: http://www.photo.net/wtr/thebook/community (the community chapter of Philip and Alex's Guide to Web Publishing)
• technical background: http://www.photo.net/wtr/thebook/

Overview

Warning: As of April 26, 2000, AOLserver has serious threading problems when run under Windows. We are making these installation instructions availble for those of you who like living on the bleeding edge. Currently there are two patches/workarounds you should implement:

• You should install the patched version of nsthread.dll
• To reduce the chances of suffering from a memory leak, set the "ThreadTimeout" parameter under the "ns/server/<server-name>" section to a large value, like 5000000

Prerequisites

• Windows2000 or Windows98
• WinZip or any tool that can extract gzipped/tarred archives.
• zsh (free) If this link is broken try http://www.zsh.org.
• Oracle 8 relational database management system
• AOLserver (free)
• ArsDigita Oracle driver for AOLserver (free)

Your Oracle installation

1. Run Oracle Administration Assistant for Windows NT (yes, that's Windows NT)
2. Navigate using the Explorer-style control in the left panel and select the Oracle Home for the database you wish to use.
3. Bring up its properties dialog and add a parameter NLS_DATE_FORMAT with value 'YYYY-MM-DD' (without the quotes)
4. Verify the date format by logging into the database using SQL Plus and run the following query: select sysdate from dual;

To set the date format in Windows98 you will need to perform a little registry surgery as follows:

1. Run regedit and navigate down the registry keys to HKEY_LOCAL_MACHINE\Software\ORACLE.
2. Choose the appropriate subtree; this will be HOME0 if you only have on einstallation of Oracle.

   If you are an Oracle achiever and have more than one Oracle installation on your machine, you will see HOME0, HOME1, HOME2, etc. Choose the subtree that corresponds to the Oracle installtion you wish to use with the ACS.

3. If the NLS_DATE_FORMAT key is already present, double-click on its value and change it to 'YYYY-MM-DD' (without the quotes). If the key does not exist, choose Edit->New->String Value from the menu and type NLS_DATE_FORMAT for the name of the new value to create it. Then double-click on the empty value to change it.
4. Verify the date format by logging into the database using SQL Plus and run the following query: select sysdate from dual;

For more information on Oracle configuration look at http://www.photo.net/wtr/oracle-tips or search the Web/db Q&A Forum. One other note: the "nuke a user" admin page and Intermedia won't run unless you set open_cursors = 500 for your database.

The stock AOLserver installation

Extract AOLserver onto the C drive and rename the folder from aolserver3_0-win32-i386 to aolserver3_0 as this will save typing in console windows. Test the stock AOLserver distribution by running install-service.bat in c:\aolserver3_0\bin and then take a look at http://localhost:8000 (the stock configuration file puts the web service at port 8000). You should get an introductory page with links to AOLserver documentation, some test scripts and interesting links on aolserver.com.

When you've verified the stock AOLserver installation, run remove-service.bat in c:\aolserve3_0\bin and reboot your machine. Copy the ArsDigita Oracle driver, ora8.dll, to the directory with the AOLserver executable. If you followed our naming advice above, this should be c:\aolserver3_0\bin. Reboot your machine.

Untar the ACS

For the sake of argument, we're going to assume that your service is called "yourdomain", is going to be at http://yourdomain.com and is rooted at c:\web\yourdomain in the Windows2000 file system. Note that you'll find our definitions files starting out with "yourdomain.com".

• download the ACS (see above) into c:\temp\acs.tar.gz
• use WinZip (or equivalent) to extract the files to c:\web\yourdomain

Feeding Oracle the Data Model

• load the states, country_codes and counties tables using the load-geo-tables shell script in the c:\web\yourdomain\www\install directory. You will need to open a console window and run

  zsh load-geo-tables foo/foopassword

  You most likely will see a slew of "Commit point reached . . . " messages. This does not indicate a problem.

• cd to c:\web\yourdomain\www\doc\sql and feed Oracle the .sql files that you find there. There is a meta-loader file, load-data-model.sql, that includes the other files in the proper order. To use it, open a console window and run

  sqlplus foo/foopassword < load-data-model.sql

• This has not been tested. If you have interMedia installed, while still in c:\web\yourdomain\www\doc\sql, run

  zsh load-site-wide-search foo foopassword ctxsys-password

  Note that there's no slash between foo and foopassword here. The third argument, ctxsys-password, is the password for interMedia Text's special ctxsys user.

Configuring AOLServer

You will need two configuration files. The first is a Tcl file with configuration information for AOLserver. This should be called yourdomain and should be located in c:\aolserve3_0. The second is an .ini file that configures the ACS and is discussed below. Note that pathnames in yourdomain must use forward slashes rather than the Windows back slashes. This is also true for the .ini file.

The following items must be defined in yourdomain:

• three database pools: main, subquery, and log. They must be named as such. The default pool will be "main".
• the auxconfig directory which contains the .ini file: c:\web\yourdomain\parameters
• the pageroot: c:\web\yourdomain\www
• the directory containing the TclLibrary: c:\web\yourdomain\tcl

Each section of yourdomain.ini has a hardcoded "yourservername" in the name (e.g. [ns/server/yourservername/acs]). This means that the ACS will ignore your configuration settings unless your AOLserver name happens to be "yourservername". Therefore you must go through yourdomain.ini and change "yourservername" to whatever you're calling this particular AOLserver (look at the server name in the nsd file for a reference).

Unless you want pages that advertise a community called "Yourdomain Network" owned by "webmaster@yourdomain.com", you'll probably want to edit the text of yourdomain.ini to change system-wide parameters. If you want to see how some of these are used, a good place to look is c:\web\yourdomain\tcl\ad-defs. The Tcl function, ad_parameter, is used to grab parameter values from the .ini file.

Starting the Service

bin\nsd -it yourdomain

bin\nsd -I -s yourdomain -t yourdomain

Configuring Permissions

• /doc (or at least /doc/sql/ since some AOLserver configurations will allow a user to execute SQL files)
• /admin
• any private admin dirs for a module you might have written that are not underneath the /admin directory

Adding Yourself as a User and Making Yourself a Sysadmin

If you do not know what the system user's password is connect to Oracle using SQL Plus and run the following query:

select password from users where last_name = 'system';

Closing Down Access

Where to Find What

• the /register directory contains the login and registration scripts. You can easily redirect someone to /register/index to have them login or register.
• the /pvt directory is for user-specific pages. They can only be accessed by people who have logged in.

Making sure that it works

Appendix: Running Multiple Instances of the ACS

• Oracle tablespace and a user account with the appropriate permissions on that tablespace. Each of these tablespaces must have the ACS data model loaded.
• file with the appropriate settings including server name, auxconfig, ipaddress, and port.
• Copy of the acs files in an appropriate directory under c:\web.

• an Oracle tablespace, lintcollectors with a user lintcollectors and password secretlint
• an Oracle tablespace, iguanasdirect with a user iguanasdirect and password secretiguanas

Now open a console window and go to c:\aolserver3_0. You'll start up the two services as follows:

bin\nsd -I -s lintcollectors -t lintcollectors
bin\nsd -I -s iguanasdirect -t iguanasdirect