Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml,v diff -u -N -r1.10 -r1.10.14.1 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml 17 Jul 2006 05:38:38 -0000 1.10 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/win2kinstall.xml 9 Jun 2016 08:44:50 -0000 1.10.14.1 @@ -5,493 +5,14 @@ %myvars; ]> -OpenACS Installation Guide for Windows2000 +OpenACS Installation Guide for Windows - -by Matthew Burke and Curtis Galloway - - - NOTE: These instructions were - valid for ACS v4, but have not been tested with OpenACS and the ArsDigita binary - distributions are no longer available. - Currently + A version of OpenACS and NaviServer is maintained by Maurizio + Martignano ans is available from (10/2003), the best option to get OpenACS &version; running on Windows is to use VMware and John Sequeira's Oasis VM - distribution + url="http://www.spazioit.com/pages_en/sol_inf_en/windows-openacs_en/">Spazio + IT - - - - Source: http://openacs.org/projects/openacs/download - - Bug reports: http://openacs.org/bugtracker/openacs - - Philosophy: http://photo.net/wtr/thebook/community - (the community chapter of Philip and Alex's Guide to Web - Publishing) - - Technical background: http://photo.net/wtr/thebook/ - - - - - -Overview - - 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. Note: We do not recommend running a production - server on Windows98. But the platform is more than sufficient for working - the problem sets and - for getting a feel for the OpenACS. - - 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 the ArsDigita AOLserver 3 distribution page for - details. - - You can download the binary distribution from the ArsDigita download page - 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. - - - - -Prerequisites - - - - Windows 2000 or Windows 98 - - WinZip or any tool that can - extract gzipped/tarred archives. - - zsh (free; - included in the binary distribution). If this link is broken try http://www.zsh.org. - - Oracle 8 relational database - management system - - AOLserver (free) - - - Oracle driver for AOLserver (free) - - - 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 http://www.pls.com. - - Although the zsh shell is the only command-line tool - required to install the OpenACS, if you are a UNIX person used to typing - ls instead of dir you'll get along much - better with the Cygwin toolkit from RedHat (available at http://sourceware.cygnus.com/cygwin). - This is a development library and set of tools that gives you a very - UNIX-like environment under Windows. In particular, it includes - bash, gzip and tar, which you can - use to perform the OpenACS installation instead of WinZip and zsh. - - - -Your Oracle installation - - 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 (yes, - that's Windows NT) will run on your - machine or not (in some cases, it will complain about Microsoft Managment - Console not being installed). - - If it runs on your machine, proceed as follows: - - - Run Oracle Administration Assistant for Windows NT - - Navigate using the Explorer-style control in the left panel and - select the Oracle Home for the database you wish to use. - - Bring up its properties dialog and add a parameter NLS_DATE_FORMAT - with value 'YYYY-MM-DD' (without the - quotes) - - Verify the date format by logging into the database using SQL Plus - and run the following query: select sysdate from - dual; - - - Otherwise you will need to perform a little registry surgery as - follows: - - - Run regedit and navigate down the registry keys to - HKEY_LOCAL_MACHINE\Software\ORACLE. - - - 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 OpenACS. -
- - - 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. - - 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://photo.net/wtr/oracle-tips - or search the OpenACS forums. One other note: the "nuke a user" admin page and - Intermedia won't run unless you set open_cursors = 500 - for your database. - - - - -The ArsDigita binary installation - - Extract the ArsDigita AOLserver distribution onto the C: - drive into the default aol30 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 C:. - - - - -Untar the OpenACS - - We recommend rooting webserver content in c:\web. Since most - servers these days are expected to run multiple services from multiple IP - addresses, each server gets a subdirectory from c:\web. For - example, http://scorecard.org would be rooted at - c:\web\scorecard on one of our machines and if - http://jobdirect.com were on the same box then it would be - at c:\web\jobdirect. - - 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 Windows 2000 file system. Note that - you'll find our definitions files starting out with - "yourdomain.com". - - - download the OpenACS (see above) into - c:\temp\acs.tar.gz - - use WinZip (or equivalent) to extract the files to - c:\web\yourdomain - - - You'll now find that c:\web\yourdomain\www contains the - document root and c:\web\yourdomain\tcl contains Tcl scripts - that are loaded when the AOLserver starts up. - - - - -Feeding Oracle the Data Model - - 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. - - - - 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 - - - - - - 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 OpenACS 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 - - - - You can use our template file as a starting - point (you'll need to save this file with a rather than .txt - extension). - - - - -Configuring OpenACS itself - - If you want a system that works, go to - c:\web\yourdomain\parameters and copy ad.ini to - yourdomain.ini (or any other name different from - ad.ini). You don't actually have to delete - ad.ini. - - Each section of yourdomain.ini has a hardcoded - "yourservername" in the name (e.g. - [ns/server/yourservername/acs]). This means that the OpenACS - 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 - - 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 c:\aol30. Then run - - - -bin\nsd -ft yourdomain.tcl - - - This will print all the AOLserver messages to the console so you can see - them. - - 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 c:\web\yourdomain\parameters If - everything seems ok, you can kill the server with Control-c and then - issue the following command to install as a Windows service: - - -bin\nsd -I -s yourdomain -t yourdomain.tcl - - - You can now configure error recovery and other Windows aspects of the - service from the Services control panel. If you make further changes to - yourdomain or yourdomain.ini you should stop - and start the service from the Services control panel. - - - - -Configuring Permissions - - 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: - - - /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 - - OpenACS 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 - https://yourservername.com/admin/ug/ directory and add your - personal user as a site-wide administrator. Now you're bootstrapped! - - 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 - - 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 https://yourservername/admin/users. You should read the - documentation for user registration and - access control and decide what the appropriate user state is for - anonymous on your site. - - - - -Where to Find What - - A few pointers: - - - 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 - - Run the acceptance tests in /doc/acceptance-test - - - - -Running Multiple Instances of the OpenACS - - 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: - - - Oracle tablespace and a user account with the appropriate - permissions on that tablespace. Each of these tablespaces must have the - OpenACS 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. - - Suppose you wish to run two services: lintcollectors.com and - iguanasdirect.com. You would need the following: - - - an Oracle tablespace, lintcollectors with a user - lintcollectors and password secretlint - - an Oracle tablespace, iguanasdirect with a user - iguanasdirect and password secretiguanas - - For each of these tablespaces/users you would load the OpenACS data model as - described above. Then in c:\aolserver3_0 - create files for each service, i.e. lintcollectors and - iguanasdirect. These files would point to their respective - pageroots, c:\web\lintcollectors\www and - c:\web\iguanasdirect\www; their respective auxconfigdirs, - c:\web\lintcollectors\parameters and - c:\web\iguanasdirect\parameters; etc. In the respective - auxconfigdirs would be the files lintcollectors.ini and - iguanasdirect.ini. - - Now open a console window and go to c:\aol30. You'll - start up the two services as follows: - - -bin\nsd -I -s lintcollectors -t lintcollectors.tcl -bin\nsd -I -s iguanasdirect -t iguanasdirect.tcl - - - In the services control panel you should see two services: - AOLserver-lintcollectors and - AOLserver-iguanasdirect. - - - - - -($Id$) - -