Index: openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml,v diff -u -N -r1.1 -r1.2 --- openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 13 Mar 2001 22:59:26 -0000 1.1 +++ openacs-4/packages/acs-core-docs/www/xml/install-guide/aolserver.xml 1 Feb 2002 17:09:12 -0000 1.2 @@ -1,409 +1,406 @@ - -Installing AOlserver 3.1 + + Install AOLserver - -Setup User Accounts and Paths. + + Download the Distribution + + Mat Kovach is graciously maintaining an AOLServer distribution that + includes all the patches and modules needed to run OpenACS 4. These + instructions will describe how to install using his source + distribution. He also has binaries for SuSE 7.3 and OpenBSD 2.8 (and + perhaps more to come), currently located at uptime.openacs.org. + - You will need a special user account for running the ACS. We recommend - that you call this user nsadmin. This user will have a - special home directory for storing AOLserver, - /home/aol31 and a special group for the server files, - web as well. You will also need to create directories - for AOLserver, /usr/local/aolserver, and for web - services, /web to reside in. You must execute this step - as root. + + It's also possible to download all the pieces and patches yourself: + - - - Open up a terminal and run these commands: - -$ su - -; Enter ROOT password when prompted -# groupadd nsadmin -# groupadd web -# mkdir /home/aol31 -# useradd -g nsadmin -G dba,web -d /home/aol31 nsadmin -# passwd nsadmin -; Set password for nsadmin - -# mkdir /web -# mkdir /usr/local/aolserver -# chown nsadmin.web /home/aol31 -# chown nsadmin.web /web -# chown nsadmin.web /usr/local/aolserver -# chmod 775 /home/aol31 -# chmod 775 /web -# chmod 775 /usr/local/aolserver + + + AOLServer is available at aolserver.com + -# exit - - - + + ArsDigita's AOLServer distribution (including + internationalization patches, nscache, nsrewrite, nssha1 and the + oracle driver) is available at arsdigita.com + - - At this point, you should customize the nsadmin - login scripts. Login as nsadmin and add the - following lines to your ~nsadmin/.bash_profile - -export ORACLE_BASE=/ora8/m01/app/oracle -export ORACLE_HOME=$ORACLE_BASE/product/8.1.6 -export PATH=$PATH:$ORACLE_HOME/bin -export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib -export ORACLE_SID=ora8 -export ORACLE_TERM=vt100 -export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data - - + + The OpenACS PostgreSQL driver is available from OpenACS + - Be absolutely certain that you have entered these lines correctly - and that you have saved the file - a slight error in these lines can - lead to many inscrutable error messages. Logout and log back in so - these settings will take effect. - - + + nsxml is available at http://acs-misc.sourceforge.net. + - + + The patch that makes exec work + on BSD is available at sourceforge.net + - + + The patch that makes ns_uuencode + work for binary files is available at sourceforge.net + - -Download the Distribution + + The patch that makes AOLServer respect the + -g flag is available at sourceforge.net + + - Login as nsadmin and save files to the - /tmp directory. + - - - Download the AOLserver distribution and the Oracle driver (needed for - db connectivity and the ACS). You must download the source - distribution of AOLserver in order to compile the Oracle driver. + Download Mat's + AOLServer distribution to + /tmp - - AOLserver 3.1 - Source Distribution - Do not download a binary! + - Oracle Driver - 2.x - + +joeuser:~$ cd /tmp +joeuser:/tmp$ wget -c http://uptime.openacs.org/aolserver-openacs/aolserver3.3ad13-oacs1-beta-src.tar.gz +joeuser:/tmp$ cd + - We recommend saving these archives in the /tmp - directory on your server. - + - - Uncompress the downloaded components; you may need to substitute - different files names and account for directory names different from - the ones below -- these were the files as of 9/2000 : + As root, untar + aolserver3.3ad13-oacs1-beta-src.tar.gz + into /usr/local/src - - -$ cd /tmp {or wherever the archives are} -$ tar -xzf aolserver-src-3.1ad8.tar.gz -$ tar -xzf oracle-driver-2.3.tar.gz - - - + + + +joeuser:~$ su - +Password: ********** +root:~$ cd /usr/local/src +root:/usr/local/src# tar xzf /tmp/aolserver3.3ad13-oacs1-beta-src.tar.gz + + - - You should now have two directory trees in the current directory: - aolserver/ and oracle-driver-2.3/. - Move the oracle directory under the aolserver directory to make - compiling the Oracle driver easier: - -$ mv oracle-driver-2.3 aolserver - - - - + + Create the nsadmin user - + + You will need a special user account for running AOLServer. This user + will be called nsadmin and belong + top the special group web. + nsadmin's home directory will + be /usr/local/aolserver.You must + execute these steps as root. + - -Compile AOLserver - - - This step should be completed as the nsadmin user. You will compile - the AOLserver distribution and prepare for installation. - - Login as nsadmin and cd into the aolserver/ - directory where you untarred the source. You should be able to - compile directly from that location: - -$ su - nsadmin -; Enter nsadmin password -$ cd /tmp/aolserver -$ make all - - - - + Run these commands: + - + +root:/usr/local/src# cd +root:~# groupadd nsadmin +root:~# groupadd web +root:~# useradd -g nsadmin -G web -d /usr/local/aolserver nsadmin +root:~# passwd nsadmin +; Set password for nsadmin + +root:~# mkdir -p /web /usr/local/aolserver +root:~# chown -R nsadmin.web /usr/local/aolserver /web /usr/local/src/aolserver +root:~# chmod 775 /usr/local/aolserver /web +root:~# exit + + - -Compile the Oracle Driver + + + + Set up nsadmin's environment variables - Now you need to compile the Oracle driver to enable database - connectivity. + + At this point, you should customize the + nsadmin login scripts. Login as + nsadmin and add the following + lines to your + /usr/local/aolserver/.bash_profile: + - - - Change directories to the - aolserver/oracle-driver-2.3 directory and start the - compilation: + +joeuser:~$ su - nsadmin +Password: *********** +nsadmin:~$ emacs .bash_profile + - - -$ cd /tmp/aolserver/oracle-driver-2.3 -$ make all + + Add the first set of lines, if you're using Oracle. The 2nd set + of lines, if you're using PostgreSQL. Oracle + Note: These environment variables are specific for a + local Oracle installation communicating via IPC. If you are + connecting to a remote Oracle installation, you'll need to adjust + these appropriately. Also, make sure that the '8.1.7' matches + your Oracle version. + + + +# For Oracle +export ORACLE_BASE=/ora8/m01/app/oracle +export ORACLE_HOME=$ORACLE_BASE/product/8.1.7 +export PATH=$PATH:$ORACLE_HOME/bin +export LD_LIBRARY_PATH=$ORACLE_HOME/lib:/lib:/usr/lib +export ORACLE_SID=ora8 +export ORACLE_TERM=vt100 +export ORA_NLS33=$ORACLE_HOME/ocommon/nls/admin/data - +# For Postgres +export PATH=$PATH:/usr/local/pgsql/bin +export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib + - The following compiler warning may be ignored: - -ld: warning: type and size of dynamic symbol `sskgslgf' are not defined - + + Be absolutely certain that you have entered these lines correctly + and that you have saved the file - a slight error in these lines + can lead to many inscrutable error messages. Logout and log back + in so these settings will take effect. Use the + echo command to be sure that the + environment variables have been properly assigned. + - If the compilation failed, make sure the environment variables - above actually point to where you installed the AOLserver source - code. If you followed our instructions, this should not be a problem. - You can check the directories by doing: - -$ ls /tmp/aolserver/include - - + +nsadmin:~$ exit +joeuser:~$ su - nsadmin +Password: ********* +nsadmin:~$ echo $PATH +...some other directory paths...:/usr/local/pgsql/bin +nsadmin:~$ echo $LD_LIBRARY_PATH +:/usr/local/pgsql/lib + - If you don't see any files, then you have the wrong - directories. Verify your installation of Oracle and AOLserver and try - again. - - If compilation was successful, you should now have two new files - in /tmp/aolserver/oracle-driver-2.3, ora8.so and - ora8cass.so. - + + Note: The result should be different if you're using Oracle. + /ora8/m01/app/oracle/product/8.1.7 + should have been in $PATH. + + + + + Install libxml2 & headers - + - -Install AOLserver 3.1 + In order for nsxml to compile, you need libxml2 + (available from http://xmlsoft.org). On Debian, + this can be installed by doing apt-get install + libxml2-dev. Users of other distributions can + download rpms from ftp.gnome.org. You'll + need the libxml2 and + libxml2-devel packages. + + + + Compile and install AOLserver - You are now ready to install AOLserver. - - - Change directories to your AOLserver source distribution and run - make install to install the files: - - -$ cd /tmp/aolserver -$ make install - - - - The above will copy the compiled AOLserver files to - /usr/local/aolserver - - - + Prepare the distribution - - You should now have a /usr/local/aolserver/bin - directory. Copy the previously compiled Oracle drivers into it: - -$ cp /tmp/aolserver/oracle-driver-2.3/ora8.so /usr/local/aolserver/bin -$ cp /tmp/aolserver/oracle-driver-2.3/ora8cass.so /usr/local/aolserver/bin - - - + +nsadmin:~$ cd /usr/local/src/aolserver +nsadmin:/usr/local/src/aolserver$ ./conf-clean +cat: BUILD-MODULES: No such file or directory +Done. + + - - The latest version of the ArsDigita Community System requires Tcl - 8.3. Although this version of Tcl is included with AOLserver 3.1, it - is not activated by default. There is a symbolic link pointing from - nsd to nsd76 in - /tmp/aolserver/bin. Change this to point to - nsd8x: - -$ cd /usr/local/aolserver/bin -$ rm nsd -$ ln -s ./nsd8x ./nsd - - - + - - You will now test to ensure AOLserver is running correctly. You - should be able to cd into your aolserver directory and simply start - the server: - -Login as nsadmin. (it helps to be in X at this point) -$ cd /usr/local/aolserver -$ ./bin/nsd -t nsd.tcl - - + Put the name of the driver(s) that you want into + conf-db. This can be + postgresql, + oracle, or + both. + - As the AOLserver daemon starts up, you should see a few normal - warnings (listed below), which are safe to ignore. The first warning - means that the server is missing files for running - ssl, a necessary module for encrypted HTTPS. The - second warning means that the AOLserver control panel, a special - module for administering AOLserver, could not be loaded. If - you're interested in configuring and using either of these - modules, please see the AOLserver - documentation. - -Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist. -Warning: nsd.tcl: nscp not loaded -- user/password is not set. - - - + +nsadmin:/usr/local/src/aolserver$ echo "postgresql" > conf-db + + - - Test to see if AOLserver is working by starting Netscape - or Lynx, and surfing over to your web page: - -$ lynx localhost:8000 - - + - You should see a Welcome to AOLserver page. If - this doesn't work, try going to - http://127.0.0.1:8000/. - + conf-inst should contain the + location where AOLserver is to be installed. This defaults to + /usr/local/aolserver, so we + don't need to change anything. - - Shutdown the test server: - -$ killall nsd - - + - The killall command will kill all processes with the - name nsd, but clearly this is not a good tool to use for - managing your services in general. We cover this topic in the ACS documentation. - - + - On to installing the ArsDigita Community - System! - + conf-make should contain the + name of the GNU Make command on your system. It defaults to + gmake. You may need to change + this to make. + - + +nsadmin:/usr/local/src/aolserver$ echo "make" > conf-make + + - -Troubleshooting the AOLserver Install + Compile and install AOLserver and modules + +nsadmin:/usr/local/src/aolserver$ ./conf + + + This takes about 5 minutes. All of the results are logged to + files in + /usr/local/src/aolserver/log. Make + sure to check these files to see if any errors occurred. + + + - If you can't view the welcome page, it's likely there's a - problem with your server configuration. Start by viewing your AOLserver - log, which is in /usr/local/aolserver/log/server.log. - You should also try to find lines of the form: - -[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) -[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections - + - If you can find these lines, try entering the URL the server is - listening on. If you cannot find these lines, there must be an error - somewhere in the file. Search for lines beginning with the word - Error instead of Notice. + + Test AOLserver - + + + You will now test to ensure AOLserver is running correctly. We'll + use the sample config file provided with AOLserver. This file + will attempt to guess your IP address and hostname. It will then + set up the server at port 8000 of that IP address. + - -Defaults + +nsadmin:/usr/local/src/aolserver$ cd +nsadmin:~$ ./bin/nsd -t sample-config.tcl + + + As the AOLserver daemon starts up, you should see a few normal + warnings (listed below), which are safe to ignore. + - We used the following defaults while installing AOLserver: + +Warning: nsd.tcl: nsssl not loaded -- key/cert files do not exist. +Warning: nsd.tcl: nscp not loaded -- user/password is not set. + - - - - - - Variable + + The first warning means that the server is missing files for + running ssl, a necessary module + for encrypted HTTPS. See Scott Goodwin's excellent + documentation if you want to set up SSL. The second + warning means that the AOLserver control panel, a special module + for administering AOLserver, could not be loaded. If you're + interested in configuring nscp, please see the AOLserver + documentation. + - Value + - Reason - + + Test to see if AOLserver is working by starting + Mozilla or + Lynx, and surfing over to your + web page: + - - AOLserver Username + +nsadmin:~$ lynx localhost:8000 + - nsadmin + You should see a Welcome to AOLserver + page. If this doesn't work, try going to + http://127.0.0.1:8000/. If this still doesn't + work, check out the section below. + - AOLserver used to be NaviServer and this was the - standard username for the server. - + + Shutdown the test server: + +nsadmin:~$ killall nsd + - - AOLserver Directory + + The killall command will kill + all processes with the name nsd, + but clearly this is not a good tool to use for managing your + services in general. We cover this topic in the section. + + + - /usr/local/aolserver + + + + Troubleshooting the AOLserver Install - When you use "make install" AOLserver 3.1 - will be installed here. Note that this is different from previous - versions of AOLserver; the change conforms to Red Hat Package Manager - (RPM) specifications. - + If you can't view the welcome page, it's likely + there's a problem with your server configuration. Start by + viewing your AOLserver log, which is in + /usr/local/aolserver/log/server.log. + You should also try to find lines of the form: + +[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000) +[01/Jun/2000:12:11:20][5914.2051][-nssock-] Notice: accepting connections + - - nsadmin Home Directory + If you can find these lines, try entering the URL the server is + listening on. If you cannot find these lines, there must be an error + somewhere in the file. Search for lines beginning with the word + Error instead of + Notice. - /home/aol31 + The sample-config.tcl file grabs + your address and hostname from your OS settings. - The various files needed and generated by running - AOLserver 3.1 processes should be located here, such as server .ini - and log files. This is described in depth in the next page of the - install guide. - + +set hostname [ns_info hostname] +set address [ns_info address] + - - AOLserver Groups + If you get an error that nssock can't get the requested address, + you can set these manually: - nsadmin,web,dba + +#set hostname [ns_info hostname] +set hostname 127.0.0.1 +#set address [ns_info address] +set address 127.0.0.1 + - You should have a UNIX group for the server files, - nsadmin, and a group for the web content, web. Note that in order to - connect to Oracle using svrmgrl, your user must be - part of the dba group and this capability is needed - to install the ACS. - + + If you get an error that nssock can't assign the requested port, + then that port may already be taken by another service. Try specifying + a different port in the config file. + + - - AOLserver Source Directory - - /tmp/aolserver - - This is simply a convenient place to uncompress the - source. - - - - ORACLE_HOME - - /ora8/m01/app/oracle/product/8.1.6 - - This is the default Oracle installation - directory. - - - - - -($Id$) + ($Id$) - -