<?xml version='1.0' ?>
<!DOCTYPE book 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="aolserver4" xreflabel="Install AOLserver 4">
  <title>Install AOLserver 4</title>

  <authorblurb>
    <para>by <ulink url="mailto:sussdorff@sussdorff.de">Malte Sussdorff</ulink></para>
  </authorblurb>

  <orderedlist>
    <listitem>
      <formalpara>
        <title>Check suitability of previously installed TCL</title>
        <para>Start tcl (type <userinput>tclsh</userinput> or find it using <userinput>which tclsh</userinput>).
        </para>
      </formalpara>
      <screen>[root root]% <userinput>info exists tcl_platform(threaded)</userinput>
1
[root root]% <userinput>info patchlevel</userinput>
8.4.7
[root root]%
<action>tclsh
info exists tcl_platform(threaded)
info patchlevel
</action></screen>
      <para>If the first command returns anything other than <computeroutput>1</computeroutput>, 
        then tcl is not threaded. If tcl is threaded and the version is 8.4 or higher, then installing
        tcl from source is optional.
      </para>
      <formalpara id="tcl-download">
        <title>Retrieve TCL 8.4 (or higher)</title>
        <para>Download and install TCL 8.4 from source</para>
      </formalpara>
        <para>Note for Debian users: you can apt-get install
      tcl8.4-dev if you have the right version (stable users will need
      to add tcl8.4 to their sources.list file as described on the
      <link linkend="postgres">Install Postgres</link> page). You'll
      have to use /usr/lib/tcl8.4/ instead of /usr/local/lib when you
      try to find the tcl libraries, however.</para>

      <para>If you have not installed TCL already, download the latest TCL version from Sourceforge</para>
      <para><emphasis role="bold">Debian:</emphasis>
        <computeroutput><action>apt-get install
            tcl8.4 tcl8.4-dev</action></computeroutput> and proceed to
        the next step.  In that step, replace
      <computeroutput>--with-tcl=/usr/local/lib/</computeroutput> with
        <computeroutput>--with-tcl=/usr/lib/tcl8.4</computeroutput>.</para>
      <para>Remember that you have to be root if you want to follow these instructions. On Mac OS X type <userinput>sudo su -</userinput> to become root.</para>
      <para>Alternatively use <userinput>curl -L -O</userinput> instead of <userinput>wget</userinput> (especially on Mac OS X).</para>
      <screen>[root root]# <userinput>cd /usr/local/src</userinput>
[root src]# <userinput>wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz</userinput>
[root src]# <userinput>tar xfz tcl8.4.9-src.tar.gz</userinput>
[root src]# <userinput>cd tcl8.4.9/unix</userinput>
[root unix]# <userinput>./configure --enable-threads</userinput>
[root unix]# <userinput>make install</userinput>
[root root]# 
<action>cd /usr/local/src
wget http://heanet.dl.sourceforge.net/sourceforge/tcl/tcl8.4.9-src.tar.gz
tar xfz tcl8.4.9-src.tar.gz
cd tcl8.4.9/unix
./configure --enable-threads
make install</action>
      </screen>
    </listitem>
    <listitem id="aolserver4-download">
      <formalpara>
        <title>Retrieve AOLserver</title>
        <para>Download the aolserver from CVS.</para>
      </formalpara>
      <screen>[root root]# <userinput>cd /usr/local/src</userinput>
[root src]# <userinput>mkdir aolserver40r10</userinput>
[root src]# <userinput>cd aolserver40r10</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver login</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co  -r aolserver_v40_r10 aolserver</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nscache</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nspostgres</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nssha1</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle</userinput>
[root aolserver]# <userinput>wget http://www.tdom.org/tDOM-0.7.8.tar.gz</userinput>
[root aolserver]# <userinput>tar xvfz tDOM-0.7.8.tar.gz</userinput>
[root aolserver]# <userinput>cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</userinput>
[root root]# 
<action>cd /usr/local/src
mkdir aolserver40r10
cd aolserver40r10
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r aolserver_v40_r10 aolserver
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nscache
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nspostgres
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co nssha1
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/aolserver co -r v2_7 nsoracle
wget http://www.tdom.org/files/tDOM-0.8.0.tar.gz
tar xvfz tDOM-0.8.0.tar.gz
cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/tcllib co -r tcllib-1-8 tcllib</action></screen>
    </listitem>
    <listitem id="aolserver4-install">
      <formalpara>
        <title>Configure, compile and install AOLserver</title>
        <para>Many people need to run more than one version of AOLserver in parallel.  This section accomodates future upgrades by installing AOLserver 4 in <computeroutput>/usr/local/aolserver40r9</computeroutput>.</para>
      </formalpara>
        <screen>[root aolserver]# <userinput>cd /usr/local/src/aolserver40r10/aolserver</userinput>
[root aolserver]# <userinput>./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/</userinput>
[root aolserver]# <userinput>make install</userinput>
<action>cd /usr/local/src/aolserver40r10/aolserver
./configure --prefix=/usr/local/aolserver40r10 --with-tcl=/usr/local/lib/
make install
</action></screen>
      <para>If you are using gcc 4 or later, see <ulink url="http://openacs.org/forums/message-view?message_id=309814">http://openacs.org/forums/message-view?message_id=309814</ulink></para>
      <para>If this is the only version of AOLserver in use, or is the default version, create a symlink.  If not, then be sure to use <computeroutput>/usr/local/aolserver40r10</computeroutput> instead of <computeroutput>/usr/local/aolserver</computeroutput> in the steps below and check both scripts and makefiles to ensure they use the correct path.</para>
      <screen>[root aolserver]# <userinput>ln -s /usr/local/aolserver40r10 /usr/local/aolserver</userinput></screen>
    </listitem>
    <listitem id="aolserver4-modules-install">
      <formalpara>
        <title>Configure, compile and install the modules</title>
          <para>
          <orderedlist>
            <listitem id="aolserver4-nscache-install">
              <para>Install nscache</para>
              <screen>[root aolserver]# <userinput>cd /usr/local/src/aolserver40r10/nscache</userinput>
[root nscache]# <userinput>make install AOLSERVER=/usr/local/aolserver</userinput></screen>
            </listitem>
            <listitem id="aolserver4-nsoracle-install">
              <para>Install nsoracle (if you want to use Oracle)</para>
              <screen>[root nscache]# <userinput>cd ../nsoracle</userinput>
[root nsoracle]# <userinput>make install AOLSERVER=/usr/local/aolserver</userinput></screen>

            <para>OpenACS looks for the Oracle driver at
            /usr/local/aolserver/bin/ora8.so, but some versions of
            nsoracle may create nsoracle.so instead. In that case, you
            can symlink (<userinput>ln -s nsoracle.so ora8.so</userinput>) to fix it. </para>
            </listitem>
            <listitem id="aolserver4-nspostgres-install">
              <para>Install nspostgres (if you want to use Postgres)</para>
              <screen>[root nscache]# <userinput>cd ../nspostgres</userinput>
[root nspostgres]# <userinput>export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/pgsql/lib:/usr/local/aolserver/lib</userinput>
[root nspostgres]# <userinput>make install POSTGRES=LSB ACS=1 INST=/usr/local/aolserver  AOLSERVER=/usr/local/aolserver</userinput>
              </screen>
              <para>If you get errors like:</para>
              <programlisting>nspostgres.c: In function `Ns_PgTableList':
nspostgres.c:679: warning: passing arg 3 of `Tcl_DStringAppend' as signed due to prototype</programlisting>
              <para>then PostGreSQL is probably not in the standard location.  The location of PostGreSQL is very dependent on which method was used to install it.  To correct the problem, replace <computeroutput>LSB</computeroutput> with the path to the path to your PostGreSQL installation.  Often this is <computeroutput>/usr/local/pgsql</computeroutput>.</para>

              <para>You can use the
              <computeroutput>ldd</computeroutput> command to verify
              that all libraries are linked in: 
                <userinput>ldd /usr/local/src/aolserver40r10/nspostgres/nspostgres.so</userinput>
              </para>

              <para>If you run into problems with libpq.a do the following (and repeat the step above)</para>
              <screen>[root nspostgres]# <userinput>ranlib /usr/local/pgsql/lib/libpq.a</userinput></screen>
              <para>If you run into problems with the linker, edit the Makefile. Add <computeroutput>-lnsdb</computeroutput> to the <computeroutput>MODLIBS</computeroutput> var.</para>
              <programlisting>MODLIBS = -L$(PGLIB) -lpq <emphasis role="bold">-lnsdb</emphasis></programlisting>
            </listitem>
            <listitem id="aolserver4-nssha1-install">
              <para>Install nssha1</para>
              <screen>[root nspostgres]# <userinput>cd ../nssha1</userinput></screen>
              <para>Now install nssha1:</para>
              <screen>[root nssha1]# <userinput>make install AOLSERVER=/usr/local/aolserver</userinput></screen>
              <para>If the make fails you will have to edit nssha1.c. Comment out the following 2 lines (lines 139-140):        </para>
              <programlisting><emphasis role="bold">//</emphasis> typedef unsigned int u_int32_t;
<emphasis role="bold">//</emphasis> typedef unsigned char u_int8_t;</programlisting>
            </listitem>
            <listitem id="aolserver4-tdom-install">
              <para>Install tDOM</para>
              <screen>[root nssha1]# <userinput>cd ../tDOM-0.8.0/unix</userinput></screen>
              <para>Edit the <computeroutput>CONFIG</computeroutput> file. Uncomment the instructions meant for AOLserver 4, but edit it to look like this:</para>
              <screen>../configure --enable-threads --disable-tdomalloc
          --prefix=/usr/local/aolserver --with-tcl=/usr/local/lib</screen>
              <para>Note that the location of the Tcl library may vary on differnt platforms (e.g. for Debian 3.0: --with-tcl=/usr/lib/tcl8.4)</para>
              <para>Now you can compile and configure tDOM</para>
              <screen>[root unix]# <userinput>sh CONFIG</userinput>
[root unix]# <userinput>make install</userinput></screen>
            </listitem>
            <listitem id="aolserver4-tcllib-install">
              <para>Install TCLLIB</para>
              <screen>[root nssha1]# <userinput>cd ../tcllib</userinput></screen>
              <para>Configure and compile TCLLIB</para>
              <screen>[root unix]# <userinput>./configure -prefix=/usr/local/aolserver40r10</userinput>
[root unix]# <userinput>make install</userinput></screen>
            </listitem>
          </orderedlist>
          </para>
      </formalpara>
    </listitem>
    <listitem id="aolserver4-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 to
	  communicate with the database.  There is one script for
	  Oracle and one for PostgreSQL.  They do not conflict. If you plan
	  to use both databases, install both.


      Note that this section requires you to have OpenACS files available, which
      you can get through CVS, through a tarball, or by other
      means. You can come back to this section after you acquire the
      OpenACS code, but don't forget to come back. (Note to
      maintainers: this should be moved to the next page and
      integrated into the text there)
    </para>
      </formalpara>
      <itemizedlist>
            <listitem>
              <para>Oracle</para>
              <screen>[root aolserver]# <userinput>cd /usr/local/aolserver/bin</userinput>
[root bin]# <userinput>cp /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>
      <para>You may need to edit these scripts if you are not using
      /usr/local/aolserver as the directory of Aolserver4.</para>
    </listitem>
    <listitem>
      <formalpara>
        <title>Change startup script (optional).</title>
      <para>If you want to run AOLserver on a port below 1024 (normally, for a webserver you will use 80), you will have to change the 	  <computeroutput>/var/lib/aolserver/<replaceable>service0</replaceable>/etc/daemontools/run</computeroutput> script according to the documentation found there (namely: Add the -b <replaceable>yourip:yourport</replaceable> switch)</para></formalpara>
    </listitem>
    <listitem>
      <para><link linkend="install-aolserver-permissions">Test AOLserver</link>.</para>
    </listitem>
  </orderedlist>
  <para><phrase role="cvstag">($Id: aolserver4.xml,v 1.30 2006/07/17 05:38:37 torbenb Exp $)</phrase></para>
</sect1>
