<?xml version='1.0' ?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
               "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="aolserver" xreflabel="Install AOLserver 3.3oacs1">
  <title>Install AOLserver 3.3oacs1</title>

  <authorblurb>
    <para>by <ulink url="mailto:vinod@kurup.com">Vinod Kurup</ulink></para>
  </authorblurb>

  <para>We recommend the use of <link linkend="aolserver4">AOLserver 4.0.1</link> or later.  These instructions are retained as a resource.</para>
  <para>
    Debian users: we do not recommend installing Debian packages for
    Aolserver or Postgres. Several people have
    reported problems while trying to install using apt-get
    instead of from source. If you have the time to debug these
    and submit what you did, that's great, but if not, you
    should stick to installing from source. 
  </para>

  <orderedlist>
    <listitem id="aolserver-tarball">
      <formalpara>
        <title>Unpack the Aolserver tarball</title>
        <para>Download the <link
linkend="source-aolserver">aolserver tarball</link> and unpack it.</para>
      </formalpara>
      <screen>[root root]# <userinput>cd /usr/local/src</userinput>
[root src]# <userinput>wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz</userinput>
--15:38:08--  http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz
           => `aolserver3.3oacs1.tar.gz'
Resolving uptime.openacs.org... done.
Connecting to uptime.openacs.org[207.166.200.199]:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 3,858,074 [application/x-compressed]

100%[====================================>] 3,858,074     66.56K/s    ETA 00:00

15:39:05 (66.56 KB/s) - `aolserver3.3oacs1.tar.gz' saved [3858074/3858074]
[root src]# <userinput>tar xzf aolserver3.3oacs1.tar.gz</userinput>
[root src]#
<action>cd /usr/local/src
wget --passive http://uptime.openacs.org/aolserver-openacs/aolserver3.3oacs1.tar.gz
tar xzf aolserver3.3oacs1.tar.gz</action></screen>
      <para>This section also relies on some OpenACS files, which you can get with <xref linkend="openacs-unpack"/>.</para>
    </listitem>
    
    <listitem id="install-aolserver-compile">
      <formalpara>
        <title>Compile AOLserver</title>
      <para>Compile and install AOLserver.  First, prepare the installation directory and the source code.  The message about BUILD-MODULES can be ignored.</para>
      </formalpara>
      <screen>root@yourserver root]# <userinput>mkdir -p /usr/local/aolserver</userinput>
[root root]# <userinput>cd /usr/local/src/aolserver</userinput>
[root aolserver]# <userinput>./conf-clean</userinput>
cat: BUILD-MODULES: No such file or directory
Done.
[root aolserver]#<action>mkdir -p /usr/local/aolserver
cd /usr/local/src/aolserver
./conf-clean</action></screen>
      <para>
          If you are using Oracle, edit
          <computeroutput>conf-db</computeroutput> and change
          <computeroutput>postgresql</computeroutput> to
          <computeroutput>oracle</computeroutput>, or to the word
          <computeroutput>both</computeroutput> if you want both drivers
          installed.  In order to get nsoracle to compile, you may
          need to su - oracle, and then su (without the -) root to set
          the environment variables properly.
        </para>

      <para><computeroutput>conf-inst</computeroutput> should contain the
          location where AOLserver is to be installed.  Overwrite the
          tarball's default value with our default value, <computeroutput>/usr/local/aolserver</computeroutput>:</para>
      <screen>[root aolserver]# <userinput>echo "/usr/local/aolserver" > conf-inst</userinput>
[root aolserver]#</screen>
      
      <para><computeroutput>conf-make</computeroutput> should contain the
          name of the GNU Make command on your system. It defaults to
          <computeroutput>gmake</computeroutput>.  Debian users: <computeroutput><userinput>ln -s /usr/bin/make /usr/bin/gmake</userinput></computeroutput>.</para>
      <para>Set an environment variable that the nspostgres driver
      Makefile needs to compile correctly and run
          <computeroutput>conf</computeroutput>, which compiles
          AOLserver, the default modules, and the database driver, and
          installs them.</para>
      <para>Debian users, see
          warning above, but if you do use apt-get for AOLserver
          3.3+ad13 and postgresql from apt-get may need to 
          make these symlinks: <computeroutput>ln -s
          /usr/include/postgresql/ /usr/include/pgsql</computeroutput>
          and <computeroutput>ln -s /usr/lib/postgresql /usr/local/pgsql</computeroutput>)</para>
      <screen>[root aolserver]# <userinput>export POSTGRES=/usr/local/pgsql; ./conf</userinput>
Building in /usr/local/aolserver
with the following modules:
aolserver
nscache
nsrewrite
nssha1
nsxml
pgdriver
==================================================================
Starting Build Sat Mar  8 10:28:26 PST 2003
Running gmake in aolserver/; output in log/aolserver.log
<emphasis>(several minute delay here)</emphasis>
Running gmake in nscache/; output in log/nscache.log
Running gmake in nsrewrite/; output in log/nsrewrite.log
Running gmake in nssha1/; output in log/nssha1.log
Running gmake in nsxml/; output in log/nsxml.log
Running gmake in nspostgres/; output in log/nspostgres.log
Creating  ...
==================================================================
Done Building Sat Mar  8 10:31:35 PST 2003
[root aolserver]# </screen>
      
      <para>
          This takes about 5 minutes. It builds aolserver, several modules, and the database driver.  (Upgraders, note that the postgres database driver has changed from postgres.so to nspostgres.so).  All of the results are logged to files in <computeroutput>/usr/local/src/aolserver/log</computeroutput>.  If you run into problems running AOLserver, check these files for build errors.</para>
    </listitem>
    
    <listitem id="aolserver-db-wrapper">
      <formalpara>
        <title>Add a database-specific wrapper script.</title>
<para>This script
	  sets database environment variables before starting
	  AOLserver; this allows the AOLserver instance can
	  communicate with the database.  There is one script each for
	  Oracle and PostgreSQL.  They don't conflict, so if you plan
	  to use both databases, install both.</para>
      </formalpara>
      <itemizedlist>
            <listitem>
              <para>Oracle</para>
              <screen>[root aolserver]# <userinput>cd /usr/local/aolserver/bin</userinput>
[root bin]# <userinput>cp /var/tmp/&tarballpath;/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle</userinput>
[root bin]# <userinput>chmod 750 nsd-oracle</userinput>
[root bin]#
<action>cd /usr/local/aolserver/bin
cp /var/tmp/&tarballpath;/packages/acs-core-docs/www/files/nsd-oracle.txt ./nsd-oracle
chmod 750 nsd-oracle</action></screen>
            </listitem>
            <listitem>
              <para>PostgreSQL</para>
              <screen>[root aolserver]# <userinput>cd /usr/local/aolserver/bin</userinput>
[root bin]# <userinput>cp /var/tmp/&tarballpath;/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres</userinput>
[root bin]# <userinput>chmod 755 nsd-postgres</userinput>
[root bin]#
<action>cd /usr/local/aolserver/bin
cp /var/tmp/&tarballpath;/packages/acs-core-docs/www/files/nsd-postgres.txt ./nsd-postgres
chmod 755 nsd-postgres</action></screen>
        </listitem>
      </itemizedlist>
    </listitem>
    <listitem id="install-tdom">
      <formalpara>
        <title>Install tDOM</title>
        <para>Download the <link linkend="source-tdom">tDOM
        tarball</link>, unpack it, adjust the configuration file to match our patched
        distribution of aolserver, and compile it.</para>
      </formalpara>
      <screen>[root root]# <userinput>cd /usr/local/src</userinput>
[root src]# <userinput>wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz</userinput>
--16:40:58--  http://www.tdom.org/tDOM-0.7.8.tar.gz
           => `tDOM-0.7.8.tar.gz'
Resolving www.tdom.org... done.
Connecting to www.tdom.org[212.14.81.4]:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 826,613 [application/x-compressed]

100%[====================================>] 826,613      138.06K/s    ETA 00:00

16:41:04 (138.06 KB/s) - `tDOM-0.7.8.tar.gz' saved [826613/826613]

[root src]# <userinput>tar xzf tDOM-0.7.8.tar.gz</userinput>
[root src]# <userinput>cd tDOM-0.7.8/unix</userinput>
[root unix]#
<action>cd /usr/local/src
wget --passive http://www.tdom.org/tDOM-0.7.8.tar.gz
tar xzf tDOM-0.7.8.tar.gz
cd tDOM-0.7.8/unix</action> </screen>
      <para>Edit the file CONFIG and change this section:</para>
<programlisting># ----------------------------------------------------
# aolsrc="/usr/src/aolserver-3.4"
# ../configure --enable-threads --disable-tdomalloc \
#   --with-aolserver=$aolsrc \
#   --with-tcl=$aolsrc/tcl8.3.4/unix </programlisting>
<para>to</para>
<programlisting># ----------------------------------------------------
aolsrc="/usr/local/src/aolserver/aolserver"
../configure --enable-threads --disable-tdomalloc \
  --with-aolserver=$aolsrc \
  --with-tcl=$aolsrc/tcl8.3.2/unix</programlisting>
      <para>And configure and compile:</para>
      <screen>[root unix]# <userinput>sh CONFIG</userinput>
creating cache ./config.cache
checking for memmove... yes
  <emphasis>(many lines omitted)</emphasis>
creating Makefile
creating tdomConfig.sh
[root unix]# <userinput>make</userinput>
gcc -pipe -DHAVE_UNISTD_H=1 -DHAVE_LIMITS_H=1 -DTCL_THREADS=1
-DHAVE_GETCWD=1 -DHAVE_OPENDIR=1 -DHAVE_STRSTR=1 -DHAVE_STRTOL=1 
  <emphasis>(many lines omitted)</emphasis>
          -Wl,-rpath,/usr/local/lib -o tcldomsh;\
fi
[root unix]# <userinput>cp libtdom0.7.8.so /usr/local/aolserver/bin/</userinput>
[root unix]# <userinput>cd /usr/local/aolserver/bin/</userinput>
[root bin]# <userinput>ln -s libtdom0.7.8.so libtdom.so</userinput>
[root bin]#

<action>sh CONFIG
make
cp libtdom0.7.8.so /usr/local/aolserver/bin/
cd /usr/local/aolserver/bin
ln -s libtdom0.7.8.so libtdom.so</action></screen>
    </listitem>
    <listitem>
      <para><link linkend="install-nsopenssl">Install nsopenssl</link>
      (OPTIONAL)</para>
    </listitem>
    <listitem>
      <para><link linkend="install-openfts">Install Full Text Search with OpenFTS</link> (OPTIONAL)</para>
    </listitem>
    <listitem>
      <para><link linkend="install-nspam">Install nspam</link> (OPTIONAL)</para>
    </listitem>
    <listitem id="install-aolserver-permissions">
      <formalpara>
        <title>Test AOLserver</title>
      <para>In order to test AOLserver, we'll run it using the
      sample-config.tcl file provided in the AOLserver distribution,
      under the nobody user and <computeroutput>web</computeroutput>
      group.  The sample-config.tcl configuration writes to the
      default log locations, so we need to give it permission to do so
      or it will fail.  Grant the <computeroutput>web</computeroutput>
      group permission to write to
      <computeroutput>/usr/local/aolserver/log</computeroutput> and
      <computeroutput>/usr/local/aolserver/servers</computeroutput>.</para>
      </formalpara>
      <screen>[root root]# <userinput>cd /usr/local/aolserver</userinput>
[root aolserver]# <userinput>chown -R root.web log servers</userinput>
[root aolserver]# <userinput>chmod -R g+w log servers</userinput>
[root aolserver]# <userinput>ls -l</userinput>
total 32
drwxr-sr-x    2 root     root         4096 Mar  8 12:57 bin
drwxr-xr-x    3 root     root         4096 Mar  8 10:34 include
drwxr-sr-x    3 root     root         4096 Mar  8 10:34 lib
drwxrwsr-x    2 root     web          4096 Mar  8 10:31 log
drwxr-sr-x    3 root     root         4096 Mar  8 10:31 modules
-rw-r--r--    1 root     root         7320 Mar 31  2001 sample-config.tcl
drwxrwsr-x    3 root     web          4096 Mar  8 10:31 servers
[root aolserver]#
<action>
cd /usr/local/aolserver
chown -R root.web log servers
chmod -R g+w log servers
ls -l</action></screen>

      <para>Note: AOLserver4.x does not include a default start page, so we create one for this test. Type 
        <userinput>echo "Welcome to AOLserver" > /usr/local/aolserver40r8/servers/server1/pages/index.html</userinput>
      </para>
      <para>Now, we'll run a quick 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 start up the server at port 8000 of that
          IP address.</para>

      <screen>[root aolserver]# <userinput>./bin/nsd -t sample-config.tcl -u nobody -g web</userinput>
[root aolserver]# [08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: starting to read config file...
[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nsssl not loaded -- key/cert files do not exist.
[08/Mar/2003:15:07:18][31175.8192][-main-] Warning: config.tcl: nscp not loaded
-- user/password is not set.
[08/Mar/2003:15:07:18][31175.8192][-main-] Notice: config.tcl: finished reading
config file.</screen>

        <para>The first warning, about nsssl, can be ignored.  We won't be using nsssl; we'll be using nsopenssl instead, and we haven't fully configured it yet.  The nscp warning refers to the fact that, without a user and password in the config file, the administrative panel of AOLserver won't load.  We don't plan to use it and can ignore that error as well.  Any other warning or error is unexpected and probably a problem.</para>

      <para>

          Test to see if AOLserver is working by starting
          <computeroutput>Mozilla</computeroutput> or
          <computeroutput>Lynx</computeroutput> <emphasis>on the same
          computer</emphasis> and surfing over to your web page.  If
          you browse from another computer and the sample config file
          didn't guess your hostname or ip correctly, you'll get a
          false negative test.

        </para>

        <screen>[root aolserver]# <userinput>lynx localhost:8000</userinput></screen>

        <para>

          You should see a &quot;Welcome to AOLserver&quot; page. If this
          doesn't work, try going to
          <computeroutput>http://127.0.0.1:8000/</computeroutput>. If this
          still doesn't work, check out the <xref
          linkend="install-aolserver-troubleshooting"/> section below.  Note that you will not be able to browse to the web page from another machine, because AOLserver is only listening to the local address.

        </para>

      <para>Shutdown the test server:</para>
      <screen>[root aolserver]# <userinput>killall nsd</userinput>
[root aolserver]#</screen>

        <para>

          The <computeroutput>killall</computeroutput> command will kill
          all processes with the name <computeroutput>nsd</computeroutput>,
          but clearly this is not a good tool to use for managing your
          services in general. We cover this topic in the <xref
          linkend="install-openacs-keepalive"/> section.

        </para>
    </listitem>

    <listitem id="install-aolserver-troubleshooting"
          xreflabel="Troubleshooting AOLserver">
      <formalpara>
        <title>Troubleshooting.</title>
      <para>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
      <computeroutput>/usr/local/aolserver/log/server.log</computeroutput>.
      You should also try to find lines of the form:
    </para>
      </formalpara>
    <screen>
[01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: nssock: listening on http://localhost.localdomain:8000 (127.0.0.1:8000)
[01/Jun/2000:12:11:20][5914.4051][-nssock-] Notice: accepting connections</screen>

    <para>

      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
      <computeroutput>Error</computeroutput> instead of
      <computeroutput>Notice</computeroutput>.

    </para>

    <para>

      The <computeroutput>sample-config.tcl</computeroutput> file grabs
      your address and hostname from your OS settings.

    </para>

    <screen>
set hostname        [ns_info hostname]
set address         [ns_info address]</screen>

    <para>

      If you get an error that nssock can't get the requested address, you
      can set these manually. If you type 0.0.0.0, AOLserver will try to
      listen on all available addresses.  <emphasis>Note</emphasis>:
      <computeroutput>ns_info address</computeroutput> doesn't appear
      to be supported in current versions of AOLserver.

    </para>

    <screen>
set hostname        [ns_info hostname]
#set address         [ns_info address]
set address 0.0.0.0</screen>

    </listitem>
    <listitem>
      <para><link linkend="analog-install">Install
      Analog</link> web file analyzer. (OPTIONAL)</para>
    </listitem>
  </orderedlist>

  <para><phrase role="cvstag">($Id: aolserver.xml,v 1.22 2006/07/17 05:38:37 torbenb Exp $)</phrase></para>

</sect1>
