<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>OpenACS Installation Guide for Windows2000</title><meta name="generator" content="DocBook XSL Stylesheets V1.58.1"><link rel="home" href="index.html" title="OpenACS Documentation"><link rel="up" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="previous" href="win-install.html" title="Chapter�5.�Installing on Windows"><link rel="next" href="mac-install.html" title="Chapter�6.�Installing on a Macintosh"><link rel="stylesheet" href="openacs.css" type="text/css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="images/alex.jpg" border="0"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><th width="60%" align="center">Chapter�5.�Installing on Windows</th><td width="20%" align="right"> <a accesskey="n" href="mac-install.html">Next</a></td></tr></table><hr></div><div class="sect1" lang="en"><div class="titlepage"><div><h2 class="title" style="clear: both"><a name="win2k-installation"></a>OpenACS Installation Guide for Windows2000</h2></div></div><div class="authorblurb"><p><p>By <a href="mailto:mburke@arsdigita.com" target="_top">Matthew Burke</a> and <a href="mailto:curtisg@arsdigita.com" target="_top">Curtis Galloway</a></p><br>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</p></div><p><span class="strong">NOTE:</span> These instructions were
valid for ACS v4, but have not been tested with OpenACS. Currently
(8/2002), the best option to get OpenACS 4.7.0d running on Windows
is to use <a href="http://vmware.com" target="_top">VMware</a> and John
Sequeira's <a href="http://www.pobox.com/~johnseq/projects/oasisvm/" target="_top">Oasis VM
distribution</a>
</p><div class="itemizedlist"><ul type="disc"><li><p>Source: <a href="http://software.arsdigita.com/dist" target="_top">http://software.arsdigita.com/dist</a></p></li><li><p>Bug reports: <a href="mailto:acs-bugs@arsdigita.com" target="_top">acs-bugs@arsdigita.com</a></p></li><li><p>Philosophy: <a href="http://photo.net/wtr/thebook/community" target="_top">http://photo.net/wtr/thebook/community</a>
(the community chapter of <span class="emphasis"><em>Philip and Alex's Guide to Web
Publishing</em></span>)</p></li><li><p>Technical background: <a href="http://photo.net/wtr/thebook/" target="_top">http://photo.net/wtr/thebook/</a></p></li></ul></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-overview"></a>Overview</h3></div></div><p>
With the recent release of a win32 version of AOLserver, it is now
possible to run the OpenACS on Windows2000 and Windows98. This document
explains the steps necessary to get the OpenACS installed and running on your
machine. </p><div>Note:</div><p> We do not recommend running a production
server on Windows98. But the platform is more than sufficient for working
the <a href="http://photo.net/teaching/one-term-web" target="_top">problem sets</a> and
for getting a feel for the OpenACS.
</p><p>You'll need to use the ArsDigita binary distribution of AOLserver
for the Win32 platform, which contains patches for several problems we
have come across in the default AOLserver binary distribution. See <a href="/aol3" target="_top">the ArsDigita AOLserver 3 distribution page</a> for
details.</p><p>You can download the binary distribution from <a href="http://arsdigita.com/download" target="_top">the ArsDigita download page</a>
under "ArsDigita AOLserver 3 Binary Distribution for Win32."
Please read the release notes in the distribution for configuration notes
specific to the version you are downloading.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-prerequisites"></a>Prerequisites</h3></div></div><div class="itemizedlist"><ul type="disc"><li><p>Windows 2000 or Windows 98</p></li><li><p><a href="http://www.winzip.com" target="_top">WinZip</a> or any tool that can
extract gzipped/tarred archives.</p></li><li><p><a href="ftp://ftp.blarg.net/users/amol/zsh" target="_top">zsh</a> (free;
included in the binary distribution). If this link is broken try <a href="http://www.zsh.org" target="_top">http://www.zsh.org</a>.</p></li><li><p><a href="http://www.oracle.com" target="_top">Oracle 8</a> relational database
management system</p></li><li><p><a href="http://www.aolserver.com" target="_top">AOLserver</a> (free)</p></li><li><p><a href="http://arsdigita.com/free-tools/oracle-driver" target="_top">ArsDigita
Oracle driver for AOLserver</a> (free)</p></li></ul></div><p> It is helpful if you have Oracle interMedia Text for full-text searches.
We're also trying to make our system work with the PLS System,
available free from <a href="http://www.pls.com" target="_top">http://www.pls.com</a>.
</p><p>Although the <tt>zsh</tt> shell is the only command-line tool
required to install the OpenACS, if you are a UNIX person used to typing
<tt>ls</tt> instead of <tt>dir</tt> you'll get along much
better with the Cygwin toolkit from RedHat (available at <a href="http://sourceware.cygnus.com/cygwin" target="_top">http://sourceware.cygnus.com/cygwin</a>).
This is a development library and set of tools that gives you a very
UNIX-like environment under Windows. In particular, it includes
<tt>bash</tt>, <tt>gzip</tt> and <tt>tar</tt>, which you can
use to perform the OpenACS installation instead of WinZip and zsh.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-oracle"></a>Your Oracle installation</h3></div></div><p>
When you install Oracle, a good rule of thumb is "every default
setting is wrong." We will not discuss Oracle configuration here
except to mention that the OpenACS requires Oracle's NLS_DATE_FORMAT
parameter be set to 'YYYY-MM-DD'. Fixing this depends on whether
Oracle Administration Assistant for Windows NT (<span class="emphasis"><em>yes,
that's Windows <div>NT</div>)</em></span> will run on your
machine or not (in some cases, it will complain about Microsoft Managment
Console not being installed). </p><p>If it runs on your machine, proceed as follows:</p><div class="orderedlist"><ol type="1"><li><p>Run Oracle Administration Assistant for Windows NT</p></li><li><p>Navigate using the Explorer-style control in the left panel and
select the Oracle Home for the database you wish to use.</p></li><li><p>Bring up its properties dialog and add a parameter NLS_DATE_FORMAT
with value 'YYYY-MM-DD' (<span class="emphasis"><em>without the
quotes</em></span>)</p></li><li><p>Verify the date format by logging into the database using SQL Plus
and run the following query: <tt>select sysdate from
dual;</tt></p></li></ol></div><p>Otherwise you will need to perform a little registry surgery as
follows:</p><div class="orderedlist"><ol type="1"><li><p>Run <tt>regedit</tt> and navigate down the registry keys to
<tt>HKEY_LOCAL_MACHINE\Software\ORACLE</tt>.</p></li><li><p>
Choose the appropriate subtree; this will be <tt>HOME0</tt> if
you only have on einstallation of Oracle.
</p><div class="blockquote"><blockquote class="blockquote"><p>
If you are an Oracle achiever and have more than one Oracle
installation on your machine, you will see <tt>HOME0, HOME1,
HOME2</tt>, etc. Choose the subtree that corresponds to the
Oracle installtion you wish to use with the OpenACS.
</p></blockquote></div><p>
</p></li><li><p>If the <tt>NLS_DATE_FORMAT</tt> key is already present,
double-click on its value and change it to 'YYYY-MM-DD'
(<span class="emphasis"><em>without the quotes</em></span>). If the key does not
exist, choose <tt>Edit->New->String Value</tt> from the menu
and type <tt>NLS_DATE_FORMAT</tt> for the name of the new value to
create it. Then double-click on the empty value to change it.</p></li><li><p>Verify the date format by logging into the database using SQL Plus
and run the following query: <tt>select sysdate from
dual;</tt></p></li></ol></div><p>For more information on Oracle configuration look at <a href="http://photo.net/wtr/oracle-tips" target="_top">http://photo.net/wtr/oracle-tips</a>
or search the <a href="http://photo.net/bboard/q-and-a?topic=web/db" target="_top">Web/db Q&A
Forum</a>. One other note: the "nuke a user" admin page and
Intermedia won't run unless you set <tt>open_cursors = 500</tt>
for your database. For more information on Oracle configuration look at
<a href="http://photo.net/wtr/oracle-tips.html" target="_top">http://photo.net/wtr/oracle-tips.html</a>
or search the <a href="http://photo.net/bboard/q-and-a.tcl?topic=web/db" target="_top">Web/db Q&A
Forum</a>. One other note: the "nuke a user" admin page and
Intermedia won't run unless you set <tt>open_cursors = 500</tt>
for your database.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-acs-binary"></a>The ArsDigita binary installation</h3></div></div><p>
Extract the ArsDigita AOLserver distribution onto the <tt>C:</tt>
drive into the default <tt>aol30</tt> directory. You can install it
on any drive, but it will make your life easier if you keep the AOLserver
binary and your OpenACS instance on the same drive. For the rest of these
instructions, we'll assume that you used drive <tt>C:</tt>.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-untar-acs"></a>Untar the OpenACS</h3></div></div><p>
We recommend rooting webserver content in <tt>c:\web</tt>. Since most
servers these days are expected to run multiple services from multiple IP
addresses, each server gets a subdirectory from <tt>c:\web</tt>. For
example, <tt>http://scorecard.org</tt> would be rooted at
<tt>c:\web\scorecard</tt> on one of our machines and if
<tt>http://jobdirect.com</tt> were on the same box then it would be
at <tt>c:\web\jobdirect</tt>.
</p><p>For the sake of argument, we're going to assume that your service
is called "yourdomain", is going to be at
<tt>http://yourdomain.com</tt> and is rooted at
<tt>c:\web\yourdomain</tt> in the Windows 2000 file system. Note that
you'll find our definitions files starting out with
"yourdomain.com".</p><div class="itemizedlist"><ul type="disc"><li><p>download the OpenACS (see <a href="#source" target="_top">above</a>) into
<tt>c:\temp\acs.tar.gz</tt></p></li><li><p>use WinZip (or equivalent) to extract the files to
<tt>c:\web\yourdomain</tt></p></li></ul></div><p>
You'll now find that <tt>c:\web\yourdomain\www</tt> contains the
document root and <tt>c:\web\yourdomain\tcl</tt> contains Tcl scripts
that are loaded when the AOLserver starts up.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-data-model"></a>Feeding Oracle the Data Model</h3></div></div><p>
The entire server will behave in an unhappy manner if it connects to
Oracle and finds that, for example, the users table does not exist. Thus
you need to connect to Oracle as whatever user the AOLserver will connect
as, and feed Oracle the table definitions.
</p><div class="itemizedlist"><ul type="disc"><li><p>
load the <tt>states</tt>, <tt>country_codes</tt> and
<tt>counties</tt> tables using the <tt>load-geo-tables</tt>
shell script in the <tt>c:\web\yourdomain\www\install</tt>
directory. You will need to open a console window and run </p><pre class="programlisting">
zsh load-geo-tables foo/foopassword
</pre><p>
You most likely will see a slew of "Commit point reached . . .
" messages. This does not indicate a problem.
</p></li><li><p>
cd to <tt>c:\web\yourdomain\www\doc\sql</tt> 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
</p><pre class="programlisting">
sqlplus foo/foopassword < load-data-model.sql
</pre></li><li><p>
If you have interMedia installed, while still in
<tt>c:\web\yourdomain\www\doc\sql</tt>, run
</p><pre class="programlisting">
zsh load-site-wide-search foo foopassword ctxsys-password
</pre><p>
Note that there's no slash between <tt>foo</tt> and
<tt>foopassword</tt> here. The third argument,
<tt>ctxsys-password</tt>, is the password for interMedia
Text's special ctxsys user.
</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-aolserver"></a>Configuring AOLServer</h3></div></div><p>You will need two configuration files. The first is a Tcl file with
configuration information for AOLserver. This should be called
<tt>yourdomain</tt> and should be located in
<tt>c:\aolserve3_0</tt>. The second is an .ini file that configures
the OpenACS and is discussed <a href="#ini" target="_top">below</a>. Note that pathnames in
<tt>yourdomain</tt> must use forward slashes rather than the Windows
back slashes. This is also true for the .ini file.</p><p>The following items must be defined in <tt>yourdomain</tt>:</p><div class="itemizedlist"><ul type="disc"><li><p>three database pools: main, subquery, and log. They must be named
as such. The default pool will be "main".</p></li><li><p>the auxconfig directory which contains the .ini file:
<tt>c:\web\yourdomain\parameters</tt></p></li><li><p>the pageroot: <tt>c:\web\yourdomain\www</tt></p></li><li><p>the directory containing the TclLibrary:
<tt>c:\web\yourdomain\tcl</tt></p></li></ul></div><p>
You can use <a href="/doc/files/winnsd.txt" target="_top">our template file</a> as a starting
point (<span class="emphasis"><em>you'll need to save this file with a rather than .txt
extension</em></span>).
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="wint2install-configure-acs"></a>Configuring OpenACS itself</h3></div></div><p>
If you want a system that works, go to
<tt>c:\web\yourdomain\parameters</tt> and copy <tt>ad.ini</tt> to
<tt>yourdomain.ini</tt> (<span class="emphasis"><em>or any other name different from
<tt>ad.ini</tt></em></span>). You don't actually have to delete
<tt>ad.ini</tt>.
</p><p>Each section of <tt>yourdomain.ini</tt> has a hardcoded
"yourservername" in the name (e.g.
<tt>[ns/server/yourservername/acs]</tt>). This means that the OpenACS
will ignore your configuration settings unless your AOLserver name
happens to be "yourservername". Therefore you must go through
<tt>yourdomain.ini</tt> and change "yourservername" to
whatever you're calling this particular AOLserver (<span class="emphasis"><em>look at the
server name in the <tt>nsd</tt> file for a reference</em></span>).</p><p>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 <tt>yourdomain.ini</tt> to change system-wide parameters.
If you want to see how some of these are used, a good place to look is
<tt>c:\web\yourdomain\tcl\ad-defs</tt>. The Tcl function,
<tt>ad_parameter</tt>, is used to grab parameter values from the .ini
file.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="wi2kinstall-starting-service"></a>Starting the Service</h3></div></div><p>
Now you're ready to start things up. Before installing as a Windows
service, you might want to test the setup for configuration errors. Open
up a console window and go to <tt>c:\aol30</tt>. Then run
</p><pre class="programlisting">
bin\nsd -ft yourdomain.tcl
</pre><p> This will print all the AOLserver messages to the console so you can see
them.
</p><p>Try to connect to your new server with a web browser. If you see the
message "Error in serving group pages", you probably forgot to
copy the ad.ini file in <tt>c:\web\yourdomain\parameters</tt> If
everything seems ok, you can kill the server with Control-c and then
issue the following command to install as a Windows service:</p><pre class="programlisting">
bin\nsd -I -s yourdomain -t yourdomain.tcl
</pre><p> You can now configure error recovery and other Windows aspects of the
service from the Services control panel. If you make further changes to
<tt>yourdomain</tt> or <tt>yourdomain.ini</tt> you should stop
and start the service from the Services control panel.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-configure-permissions"></a>Configuring Permissions</h3></div></div><p>
Now, you need to protect the proper administration directories of the
OpenACS. You decide the policy although we recommend requiring the admin
directories be accessible only via an SSL connection. Here are the
directories to consider protecting:
</p><div class="itemizedlist"><ul type="disc"><li><p>/doc (or at least /doc/sql/ since some AOLserver configurations
will allow a user to execute SQL files)</p></li><li><p>/admin</p></li><li><p>any private admin dirs for a module you might have written that are
not underneath the /admin directory</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-add-yourself"></a>Adding Yourself as a User and Making Yourself a Sysadmin</h3></div></div><p>
The ArsDigita Community System will define two users: system and
anonymous. It will also define a user group of system administrators.
You'll want to add yourself as a user (at /register/ ) and then add
yourself as as member of the site-wide administration group. Start by
logging out as yourself and logging in as the system user (email of
"system"). Change the system user's password. Visit the
<tt>https://yourservername.com/admin/ug/</tt> directory and add your
personal user as a site-wide administrator. Now you're bootstrapped!
</p><p>If you do not know what the system user's password is connect to
Oracle using SQL Plus and run the following query:</p><pre class="programlisting">
select password from users where last_name = 'system';
</pre></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-closing-down-access"></a>Closing Down Access</h3></div></div><p>
The OpenACS ships with a user named "anonymous" (email
"anonymous") to serve as a content owner. If you're
operating a restricted-access site, make sure to change the anonymous
user's password. In recent versions of the OpenACS you cannot log into
"anonymous" because the account does not have a valid user
state. Log in as a sysadmin and change the anonymous user's password
from <tt>https://yourservername/admin/users</tt>. You should read the
documentation for <a href="user-registration" target="_top">user registration and
access control</a> and decide what the appropriate user state is for
anonymous on your site.
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-where-is-what"></a>Where to Find What</h3></div></div><p>
A few pointers:
</p><div class="itemizedlist"><ul type="disc"><li><p>the /register directory contains the login and registration
scripts. You can easily redirect someone to /register/index to have
them login or register.</p></li><li><p>the /pvt directory is for user-specific pages. They can only be
accessed by people who have logged in.</p></li></ul></div></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-make-sure-it-works"></a>Making sure that it works</h3></div></div><p>
Run the acceptance tests in <a href="/doc/acceptance-test" target="_top">/doc/acceptance-test</a>
</p></div><div class="sect2" lang="en"><div class="titlepage"><div><h3 class="title"><a name="win2kinstall-multiple-acs"></a>Running Multiple Instances of the OpenACS</h3></div></div><p>
You can run multiple instances of the OpenACS on a physical machine but they
must each be set up as a separate Windows service. Each instance of the
OpenACS must have its own:
</p><div class="itemizedlist"><ul type="disc"><li><p>Oracle tablespace and a user account with the appropriate
permissions on that tablespace. Each of these tablespaces must have the
OpenACS data model loaded.</p></li><li><p>file with the appropriate settings including server name,
auxconfig, ipaddress, and port.</p></li><li><p>Copy of the acs files in an appropriate directory under
<tt>c:\web</tt>.</p></li></ul></div><p> Suppose you wish to run two services: <tt>lintcollectors.com</tt> and
<tt>iguanasdirect.com</tt>. You would need the following:
</p><div class="itemizedlist"><ul type="disc"><li><p>an Oracle tablespace, <tt>lintcollectors</tt> with a user
<tt>lintcollectors</tt> and password <tt>secretlint</tt></p></li><li><p>an Oracle tablespace, <tt>iguanasdirect</tt> with a user
<tt>iguanasdirect</tt> and password <tt>secretiguanas</tt></p></li></ul></div><p> For each of these tablespaces/users you would load the OpenACS data model as
described <a href="#data" target="_top">above</a>. Then in <tt>c:\aolserver3_0</tt>
create files for each service, i.e. <tt>lintcollectors</tt> and
<tt>iguanasdirect</tt>. These files would point to their respective
pageroots, <tt>c:\web\lintcollectors\www</tt> and
<tt>c:\web\iguanasdirect\www</tt>; their respective auxconfigdirs,
<tt>c:\web\lintcollectors\parameters</tt> and
<tt>c:\web\iguanasdirect\parameters</tt>; etc. In the respective
auxconfigdirs would be the files <tt>lintcollectors.ini</tt> and
<tt>iguanasdirect.ini</tt>.
</p><p>Now open a console window and go to <tt>c:\aol30</tt>. You'll
start up the two services as follows:</p><pre class="programlisting">
bin\nsd -I -s lintcollectors -t lintcollectors.tcl
bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl
</pre><p> In the services control panel you should see two services:
<tt>AOLserver-lintcollectors</tt> and
<tt>AOLserver-iguanasdirect</tt>.
</p><div class="cvstag">($Id: win2k-installation.html,v 1.11 2003/06/28 05:07:03 joela Exp $)</div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="win-install.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="mac-install.html">Next</a></td></tr><tr><td width="40%" align="left">Chapter�5.�Installing on Windows </td><td width="20%" align="center"><a accesskey="u" href="win-install.html">Up</a></td><td width="40%" align="right"> Chapter�6.�Installing on a Macintosh</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a><center><a href="http://openacs.org/doc/win2k-installation.html#comments">View comments on this page at openacs.org</a></center></body></html>