[Amavisadmin-svn] SF.net SVN: amavisadmin: [53] amavisadmin/branches/documentation_1_0/docs/ instal

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

Revision: 53
          http://amavisadmin.svn.sourceforge.net/amavisadmin/?rev=53&view=rev
Author:   streindl
Date:     2007-01-27 04:02:15 -0800 (Sat, 27 Jan 2007)

Log Message:
-----------
docs/installationguide.xml:
* Initial draft

Modified Paths:
--------------
    amavisadmin/branches/documentation_1_0/docs/installationguide.xml

Modified: amavisadmin/branches/documentation_1_0/docs/installationguide.xml
===================================================================

--- amavisadmin/branches/documentation_1_0/docs/installationguide.xml	2007-01-25 20:39:12 UTC (rev 52)
+++ amavisadmin/branches/documentation_1_0/docs/installationguide.xml	2007-01-27 12:02:15 UTC (rev 53)
@@ -156,7 +156,8 @@
 
             <itemizedlist>
               <listitem>
-                <para>java-1_5_0-sun-1.5.0_update10-2.1</para>
+                <para><filename>java-1_5_0-sun-1.5.0_update10-2.1</filename>
+                or a more recent version.</para>
               </listitem>
             </itemizedlist>
           </listitem>
@@ -164,39 +165,7 @@
       </variablelist>
     </section>
 
-    <section id="sec-download-and-install-tomcat">
-      <title>Apache Tomcat</title>
-
-      <para>Apache Tomcat can be downloaded and installed for various
-      Operating Systems. For Microsoft Windows and other operating systems and
-      several Linux distributions there are binary packages available that
-      work usually out of the box.</para>
-
-      <para>For the development and testing Apache Tomcat release 5.5.17 has
-      been used. The current version 5.5.20 lacks some files for mail handling
-      and therefore this version has not been taken into consideration as
-      there's from my point of view no need to install the newer version if
-      the old version is working fine.</para>
-
-      <para>Version 5.5.17 of Apache Tomcat can be downloaded for example
-      from</para>
-
-      <para><ulink
-      url="http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.17/">http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.17/</ulink></para>
-
-      <para>You should also look for <ulink
-      url="http://www.apache.org/dyn/closer.cgi">mirrors</ulink> to reduce
-      load on the apache servers.</para>
-
-      <para>After downloading the (usually) binary distribution you can
-      install tomcat. This is dependend on your operating system and vendor.
-      Therefore please check the manuals how to install tomcat. You might find
-      <ulink
-      url="http://tomcat.apache.org/tomcat-5.5-doc/setup.html">http://tomcat.apache.org/tomcat-5.5-doc/setup.html</ulink>
-      an intersting source of information about how to install tomcat.</para>
-    </section>
-
-    <section>
+    <section id="sec-postgresql-database">
       <title>PostgreSQL database</title>
 
       <para>This document does not describe how to setup the PostgreSQL
@@ -215,7 +184,7 @@
       Other versions might work also but no tests have been done to ensure
       working on different releases of PostgreSQL.</para>
 
-      <section>
+      <section id="sec-creating-the-database-for-storing-amavisd-data">
         <title>Creating the database for storing Amavisd-new data</title>
 
         <para>It makes sense (from performance, sizing and other aspects like
@@ -225,7 +194,7 @@
         In addition PostgreSQL offers the possibility to move parts of the
         data to other filesystems/paths by using tablespaces.</para>
 
-        <section>
+        <section id="sec-creating-a-functional-database-user">
           <title>Creating a functional database user</title>
 
           <para>It makes sense to create a functional user that is used by the
@@ -266,7 +235,7 @@
           </note>
         </section>
 
-        <section>
+        <section id="sec-creating-a-tablespace">
           <title>Creating a tablespace</title>
 
           <para>For maintainability I would suggest to create the database
@@ -322,7 +291,7 @@
 <prompt>postgres=#</prompt></screen></para>
         </section>
 
-        <section>
+        <section id="sec-creating-the-database">
           <title>Creating the database</title>
 
           <para>After doing the preparation steps described in the sections
@@ -355,7 +324,7 @@
         </section>
       </section>
 
-      <section>
+      <section id="sec-create-sql-data-model">
         <title>Create SQL data model</title>
 
         <para>With the Amavisd-new distribution, a README-file is distributed
@@ -387,9 +356,112 @@
         finalizing this step your database should be ready to run
         amavisd-new.</para>
       </section>
+
+      <section id="sec-download-postgres-jdbc">
+        <title>Download PostgreSQL JDBC driver</title>
+
+        <para>In addition to the standard PostgreSQL distribution you need the
+        JDBC driver that builds the interface between Java and PostgreSQL. The
+        JDBC driver is either part of the binary distribution itself or it can
+        be downloaded from <ulink
+        url="http://jdbc.postgresql.org/download.html">http://jdbc.postgresql.org/download.html</ulink>.
+        It is important that the version 3 JDBC driver (for JDK 1.4.x/1.5)
+        will be downloaded.</para>
+      </section>
     </section>
 
-    <section>
+    <section id="sec-download-and-install-tomcat">
+      <title>Apache Tomcat</title>
+
+      <para>Apache Tomcat can be downloaded and installed for various
+      Operating Systems. For Microsoft Windows and other operating systems and
+      several Linux distributions there are binary packages available that
+      work usually out of the box.</para>
+
+      <para>For the development and testing Apache Tomcat release 5.5.17 has
+      been used. The current version 5.5.20 lacks some files for mail handling
+      and therefore this version has not been taken into consideration as
+      there's from my point of view no need to install the newer version if
+      the old version is working fine.</para>
+
+      <para>Version 5.5.17 of Apache Tomcat can be downloaded for example from
+      <ulink
+      url="http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.17/">http://archive.apache.org/dist/tomcat/tomcat-5/v5.5.17/</ulink>.
+      You should also look for <ulink
+      url="http://www.apache.org/dyn/closer.cgi">mirrors</ulink> to reduce
+      load on the apache servers.</para>
+
+      <para>After downloading the (usually) binary distribution you can
+      install tomcat. This is dependend on your operating system and vendor.
+      Therefore please check the manuals how to install tomcat. You might find
+      <ulink
+      url="http://tomcat.apache.org/tomcat-5.5-doc/setup.html">http://tomcat.apache.org/tomcat-5.5-doc/setup.html</ulink>
+      an intersting source of information about how to install tomcat.</para>
+
+      <section>
+        <title>Installing the database connection</title>
+
+        <para>An important step after installing PostgreSQL is the creation of
+        the database resource that is used by AmavisAdmin to actually connect
+        to the database. There's a
+        <filename>$CATALINA_HOME/conf/context.xml</filename>, where you can
+        store resource definitions that are available for all applications
+        running on this instance of Tomcat (for other options how to define
+        resources, please refer to <ulink
+        url="http://tomcat.apache.org/tomcat-5.5-doc/config/context.html">http://tomcat.apache.org/tomcat-5.5-doc/config/context.html</ulink>).
+        </para>
+
+        <para>To run AmavisAdmin, you need to define a database connection
+        resource named <varname>amavisDB</varname>. An example context.xml
+        file might look like this: </para>
+
+        <programlisting>&lt;Context&gt;
+  &lt;!-- ... other global settings ... --&gt;
+  &lt;WatchedResource&gt;WEB-INF/web.xml&lt;/WatchedResource&gt;
+  &lt;!-- ... other global settings ... --&gt;
+  &lt;Resource auth="container"
+            type="javax.sql.Datasource"
+            name="jdbc/amavisDB"
+            driverClassName="org.postgresql.Driver" 
+            url="jdbc:postgresql://<replaceable>localhost:5432/amavis</replaceable>"
+            username="<replaceable>amavis</replaceable>"
+            password="<replaceable>amavis</replaceable>"
+            /&gt;
+  &lt;!-- ... other global settings ... --&gt;
+&lt;/Context&gt;</programlisting>
+
+        <para>You have to ensure that the last three entries in the list (url,
+        username and password) are matching the settings that you have defined
+        while installing the database (see <xref
+        linkend="sec-postgresql-database" />).</para>
+
+        <para>On top of this you have to copy the postgres JDBC driver to the
+        directory <filename
+        class="directory">$CATALINA_HOME/common/lib</filename>.</para>
+      </section>
+
+      <section id="sec-starting-tomcat">
+        <title>Starting Tomcat</title>
+
+        <para>After finishing the steps above you should start Tomcat now to
+        see that everything is running smooth. By running</para>
+
+        <screen><prompt>sreindl@linux-fest:~&gt; </prompt><userinput>$CATALINA_HOME/bin/startup.sh</userinput>
+<computeroutput>Using CATALINA_BASE:   /opt/apache-tomcat-5.5.17
+Using CATALINA_HOME:   /opt/apache-tomcat-5.5.17
+Using CATALINA_TMPDIR: /opt/apache-tomcat-5.5.17/temp
+Using JRE_HOME:       /usr/lib64/jvm/java/jre
+</computeroutput><prompt>sreindl@linux-fest:~&gt; </prompt></screen>
+
+        <para>You should have a look now in the <filename
+        class="directory">$CATALINA_HOME/log</filename> directory and scan the
+        log files appearing there for errors (esp. the files
+        <filename>catalina*</filename> and
+        <filename>localhost*</filename>).</para>
+      </section>
+    </section>
+
+    <section id="sec-download-and-install-amavisd-new">
       <title>Amavisd-new</title>
 
       <para>The Amavisd-new application can be downloaded from the <ulink
@@ -438,7 +510,7 @@
           another application.</para>
         </callout>
 
-        <callout arearefs="pl-amavis-inet-socket-port">
+        <callout arearefs="pl-amavis-conf-protocol">
           <para>This line defines the general protocol to be used for talking
           to amavisd-new. As described above, the PDP-protocol is the right
           value here.</para>
@@ -492,7 +564,7 @@
 
           <listitem>
             <para>If this variable is set to sql, virus mail texts are stored
-            in the database. </para>
+            in the database.</para>
           </listitem>
         </varlistentry>
 
@@ -523,11 +595,112 @@
       accessable to the users.</para>
     </section>
 
-    <section>
+    <section id="sec-install-amavis-admin">
       <title>AmavisAdmin</title>
 
-      <para>To install AmavisAdmin, you can download the distribtion file from
-      <?target aSAsAS?></para>
+      <para>To install AmavisAdmin, you can download the distribution file
+      from the AmavisAdmin project at sourceforge.net: <ulink
+      url="http://sourceforge.net/project/showfiles.php?group_id=187080">http://sourceforge.net/project/showfiles.php?group_id=187080</ulink>.
+      There you have the different versions available. As this version is
+      based on AmavisAdmin version @version@, please select the appropriate
+      section and download the file <filename>@distfile@</filename>.</para>
+
+      <section id="sec-install-amavisadmin-on-unix">
+        <title>Installation of AmavisAdmin on a Unix/Linux operating
+        system</title>
+
+        <para>After downloading the distribution, the files have to be
+        untarred. Depending on the format you have to use
+        <command>gunzip</command> (for files with the extension
+        <filename>.gz</filename>) or <command>bunzip2</command> (files with
+        the extension <filename>.bz2</filename>) to uncompress the files
+        first:</para>
+
+        <screen><prompt>sreindl@linux-fest:~&gt; </prompt><userinput>gunzip @distname@.tar.gz
+</userinput><prompt>sreindl@linux-fest:~&gt; </prompt></screen>
+
+        <para>for gzip compressed files or</para>
+
+        <screen><prompt>sreindl@linux-fest:~&gt; </prompt><userinput>bunzip2 @distname@.tar.bz2
+</userinput><prompt>sreindl@linux-fest:~&gt; </prompt></screen>
+
+        <para>After uncompressing there should be a file named
+        <filename>@tarfile@.tar</filename>. This file can now be extracted
+        with the <command>tar</command> command:</para>
+
+        <screen><prompt>sreindl@linux-fest:~&gt; </prompt><userinput>cd /tmp
+</userinput><prompt>sreindl@linux-fest:/tmp&gt; </prompt><userinput>tar xfv @distname@.tar
+</userinput><computeroutput>...           </computeroutput><lineannotation>Several lines of output</lineannotation>
+<prompt>sreindl@linux-fest:/tmp&gt; </prompt><userinput>cd @distname@
+</userinput><prompt>sreindl@linux-fest:/tmp/@distname@&gt;</prompt></screen>
+
+        <para>The following sections let you first update your database
+        system, deploy your web application and configure the AmavisAdmin
+        software.</para>
+      </section>
+
+      <section id="sec-perform-database-update">
+        <title>Updating the database for AmavisAdmin</title>
+
+        <para>For several purposes the database model used by Amavisd-new has
+        to be enhanced by several items, this process can be done by running a
+        script on the database that performs the steps:</para>
+
+        <screen><prompt>sreindl@linux-fest:/tmp/@distname@&gt; </prompt><userinput>psql --username=amavis amavis &lt;db/postgres/update_v0_v1.sql
+</userinput><computeroutput>...      </computeroutput><lineannotation>Several lines of output / Only warnings should appear</lineannotation>
+<prompt>sreindl@linux-fest:/tmp/@distname@&gt; </prompt></screen>
+
+        <para>After running this script, several tables have been updated
+        (i.e. new columns have been added) and several new tables have been
+        created. In addition some entries have been inserted into the new
+        table to enable AmavisAdmin to recognize that the database has been
+        changed and in addition some jobs have been inserted to perform
+        further migration of existing database entries.</para>
+      </section>
+
+      <section id="sec-deploy-AmavisAdmin">
+        <title>Deploy the AmavisAdmin application</title>
+
+        <para>The deployment of the AmavisAdmin application is quite simple.
+        For deploying the application to Tomcat you just need to copy the war
+        file to the folder <filename
+        class="directory">$CATALINA_HOME/webapps/</filename>. Tomcat is
+        unpacking and initializing the application by itself. That's
+        it.</para>
+      </section>
+
+      <section id="sec-AmavisAdmin-initial-configuration">
+        <title>Configuration of AmavisAdmin</title>
+
+        <para>After deploying the application you need to set several
+        configuration parameters before the actual application can be
+        executed. The configuration can be started by pointing your web
+        browser to the starting page of your AmavisAdmin installation (e.g.
+        <ulink
+        url="http://localhost:8080/AmavisAdmin">http://localhost:8080/AmavisAdmin</ulink>).
+        About what can be configured and the configuration fields itself you
+        can find an explanation in the AmavisAdmin user guide. You should also
+        enable the maintenance jobs that are running inside the application
+        server. This can be done by selecting the menu item
+        <guimenuitem>Jobs</guimenuitem> after logging in the first time as an
+        administrator.</para>
+
+        <para>After performing the configuration you are ready to use
+        AmavisAdmin. For more details abount administration and use of
+        AmavisAdmin please refer to the user guide.</para>
+      </section>
     </section>
   </section>
+
+  <section id="sec-building-amavsiadmin-from-scratch">
+    <title>Building AmavisAdmin from scratch</title>
+
+    <warning>
+      <para>Please be aware that the development has been done on a single
+      machine only. There might be hard dependencies due to the fact that it
+      has been never tested to build this stuff on another machine.</para>
+    </warning>
+
+    <remark>To be filled</remark>
+  </section>
 </article>
\ No newline at end of file


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.




[Amavisadmin-svn] SF.net SVN: amavisadmin: [53] amavisadmin/branches/documentation_1_0/docs/ instal

[Amavisadmin-svn] SF.net SVN: amavisadmin: [53] amavisadmin/branches/documentation_1_0/docs/ installationguide.xml