[Amavisadmin-svn] SF.net SVN: amavisadmin: [53] amavisadmin/branches/documentation_1_0/docs/ instal
Status: Beta
Brought to you by:
streindl
Menu
▾
▴
[Amavisadmin-svn] SF.net SVN: amavisadmin: [53] amavisadmin/branches/documentation_1_0/docs/ installationguide.xml
|
From: <str...@us...> - 2007-01-27 12:02:22
|
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><Context>
+ <!-- ... other global settings ... -->
+ <WatchedResource>WEB-INF/web.xml</WatchedResource>
+ <!-- ... other global settings ... -->
+ <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>"
+ />
+ <!-- ... other global settings ... -->
+</Context></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:~> </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:~> </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:~> </prompt><userinput>gunzip @distname@.tar.gz
+</userinput><prompt>sreindl@linux-fest:~> </prompt></screen>
+
+ <para>for gzip compressed files or</para>
+
+ <screen><prompt>sreindl@linux-fest:~> </prompt><userinput>bunzip2 @distname@.tar.bz2
+</userinput><prompt>sreindl@linux-fest:~> </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:~> </prompt><userinput>cd /tmp
+</userinput><prompt>sreindl@linux-fest:/tmp> </prompt><userinput>tar xfv @distname@.tar
+</userinput><computeroutput>... </computeroutput><lineannotation>Several lines of output</lineannotation>
+<prompt>sreindl@linux-fest:/tmp> </prompt><userinput>cd @distname@
+</userinput><prompt>sreindl@linux-fest:/tmp/@distname@></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@> </prompt><userinput>psql --username=amavis amavis <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@> </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.
|
