Author: eric
Date: Sun Oct 31 08:22:02 2010
New Revision: 1029274
URL: http://svn.apache.org/viewvc?rev=1029274&view=rev
Log:
Update / Remove uneeded installation steps.
Modified:
james/server/trunk/src/site/xdoc/installation.xml
Modified: james/server/trunk/src/site/xdoc/installation.xml
URL:
http://svn.apache.org/viewvc/james/server/trunk/src/site/xdoc/installation.xml?rev=1029274&r1=1029273&r2=1029274&view=diff
==============================================================================
--- james/server/trunk/src/site/xdoc/installation.xml (original)
+++ james/server/trunk/src/site/xdoc/installation.xml Sun Oct 31 08:22:02 2010
@@ -29,164 +29,137 @@
<subsection name="Java Virtual Machine">
-<p>James requires a Java Runtime Environment of Java version 1.5 or higher
installed to run the
-James application. The exact JREs available depend on the platform. A JRE
must be downloaded and
-installed before James can run. In addition, the environment variable
JAVA_HOME should be set to
-the JRE home directory before running James.</p>
-
-<p>James 3.0 has been successfully tested on OpenJDK, Sun JDK and IBM JDK</p>
+ <p>James requires a Java Runtime Environment of Java version 1.5 or higher
installed to run the
+ James application. The exact JREs available depend on the platform. A JRE
must be downloaded and
+ installed before James can run. In addition, the environment variable
JAVA_HOME should be set to
+ the JRE home directory before running James.</p>
+
+ <p>James 3.0 has been successfully tested on OpenJDK, Sun JDK and IBM JDK</p>
</subsection>
<subsection name="System Requirements">
+
+ <p>On Unix platforms, root access will be required to run James. On these
platforms, access to ports
+ below 1024 is generally restricted to the root user. As SMTP, POP3, and
IMAP all need to open
+ server sockets on such ports in standard configurations, James requires root
access.</p>
+
+ <p>Obviously James also requires sufficient disk space, processor power, and
network bandwidth. But,
+ other than what's been discussed here, it has no additional special
requirements.</p>
+
+ <p>James needs by default 512 MB RAM, but may need more depending on the
load.</p>
-<p>On Unix platforms, root access will be required to run James. On these
platforms, access to ports
-below 1024 is generally restricted to the root user. As SMTP, POP3, and IMAP
all need to open
-server sockets on such ports in standard configurations, James requires root
access.</p>
+</subsection>
-<p>Obviously James also requires sufficient disk space, processor power, and
network bandwidth. But,
-other than what's been discussed here, it has no additional special
requirements.</p>
+</section>
-<p>James needs by default 512 MB RAM, but may need more depending on the
load.</p>
+<section name="Installing the Binary">
-</subsection>
+ <p>Obtain the full James binary distribution from the <a
href="http://james.apache.org/download.cgi";>James
+ release mirrors</a>. Unpack the archive into your James installation
directory. Go to the bin subdirectory of the
+ installation directory and run "./james start".</p>
</section>
-<section name="Installation Comments">
+<section name="Step 0: Build - only for source packages">
+
+ <p>If you have downloaded a binary distribution, you do not need to build
James.
+ Proceed directory to Step 1.</p>
+
+ <p>If you have download a source package, process to the <a
href="dev_build.html">build</a>.</p>
-<p>James installation involves a number of steps, each of which is described
in some detail in the
-following sections. But as this sequence of steps has confused some users in
the past, additional
-comments seem warranted.</p>
-<p>It is important to realize that the James configuration files are not
unpacked from the James
-distribution until the first time James is started. This is a consequence of
the design of the
-Avalon Phoenix container used to run James. Once James has been started, the
distribution will
-be unpacked. The server should be stopped, the configuration files edited,
and the server restarted.</p>
-<p>So the installation sequence is: <b>1) Start, 2) Stop, 3) Edit, 4)
Restart</b>.</p>
</section>
-<section name="Installing the Binary">
-<subsection name="Installing a Stand-alone James Server">
-<p>Obtain the full James binary distribution from the <a
href="http://james.apache.org/download.cgi";>James
-release mirrors</a>. Unpack the archive into your James installation
directory. Go to the bin subdirectory of the
-installation directory and run the "run" script (either run.sh or run.bat,
depending on your platform). The configuration
-file is now unpacked and available for editing.</p>
-</subsection>
-<subsection name="Deploying a James Server in a Pre-Existing Phoenix
Container">
-<p><strong>Warning!</strong> - James requires Phoenix version 4.0.x to run.
There is a known issue with logging in Phoenix 4.0, so version
-4.0.1 or higher is strongly recommended. Before attempting to deploy James in
a Phoenix container, please make sure
-it meets these version criteria.</p>
-<p>Deploying James in Phoenix is fairly easy. Obtain the james.sar file from
the <a href="http://james.apache.org/download.cgi";>James
-release mirrors</a>. It can be found in the "Other Binaries"
-area of the distribution directory. After downloading the james.sar,
-simply place it in the apps subdirectory of your Phoenix installation.
Restart Phoenix, and the james.sar should unpack and you
-will be ready to configure your James installation.</p>
-</subsection>
+
+<section name="Step 1: Deploy">
+
+ <p>Extract or copy all the files in the archive or dist
+ directory into your installation directory. </p>
+
+</section>
+
+<section name="Step 2: Configure">
+
+ <p>After installing the binary, the next step is to adjust the initial
configuration. The server should be stopped, and then
+ configuration can proceed. The most essential configuration is set in the
config.xml file. This file can be
+ found in the apps/james/SAR-INF subdirectory of the installation
directory.</p>
+
+ <p>The out of the box configuration makes certain assumptions and has some
default values that are unlikely to
+ be appropriate for real-world servers. There are a few issues that should
be addressed immediately upon installation:</p>
+ <ul>
+ <li>RemoteManager Administrator Account - Before the RemoteManager
service can be used to add users to this server
+ installation an administrator account must be created. More information
can be found <a href="remotemanager_configuration.html">here</a>.</li>
+ <li>DNS Servers - James needs to have access to a DNS server for domain
resolution. The out of the box
+ configuration assumes that there is a DNS server on localhost. In
general administrators will have to change
+ the configuration to point to a valid DNS server. This can be done by
adjusting the dnsserver configuration
+ block in the config.xml. More information can be found <a
href="serverwide_configuration.html">here</a>.</li>
+ <li>Managed Domain Names/IP Addresses - Out of the box, James only
handles mail that is sent to recipients at
+ localhost. It will attempt to deliver all other email to remote SMTP
servers. To allow James to handle email
+ for your domain or IP address, you simply need to add the appropriate
domain name or IP address to the servernames
+ section of the config.xml. More information can be found <a
href="serverwide_configuration.html">here</a>.</li>
+ <li>Postmaster Address - More information can be found <a
href="serverwide_configuration.html">here</a>.</li>
+ </ul>
+
+ <p>In addition to adjusting these parameters, you may wish to consult the
documentation for a discussion of
+ common configurations. A list of such configurations, as well as the steps
necessary to configure them, can
+ be found <a href="index.html">here</a>.</p>
+
+ <p>Read the short and snappy documentation at docs/index.html for a proper
+ overview of configuring the system.</p>
+ <p><b>Summary</b> (for impatient people)</p>
+ <p>M$ users should just run /bin/run.bat. Unix users will find run.sh under
the
+ same directory. A JVM must be present and its location specified in the
JAVA_HOME
+ environment variable. Set this on windows at the command prompt with
something
+ similar to "set JAVA_HOME=\jdk1.3\bin" on *nix with
JAVA_HOME=/jdk1.3/</p>
+
+ <p>Running [run* --help] will provide a simple command line help. </p>
+
+ <p>Most UNIX systems require superuser privileges to open sockets below 1024,
+ which includes the IANA-standard SMTP (on port 25) and POP3 (on port
110).
+ These default ports can be changed in the conf.xml file. (Obviously, you
+ would then need to reconfigure your clients. This may not be an option if
+ you want to receive mail from external mailservers.)</p>
+
+ <p>The Avalon framework will unpack the necessary configuration files you
will
+ need to start the server. Wait until it is running, stop it again
(ctrl-c), and
+ edit the configuration (thereafter *nix users can run the server in the
background
+ using ./run.sh &). For basic use, you only need to set two items in
the
+ JAMES.conf.xml file: a root password for the remote administration
facility
+ and the IP address of a DNS server. Once you have edited the configuration
files,
+ press 'Enter' on the terminal where Avalon is waiting. </p>
+
</section>
-<section name="Step 0: Building. (only necessary for daily snapshots)">
-<p> If you have downloaded a binary distribution, you do not need to build
James.
- Proceed directory to Step 1. </p>
-<p> To compile James from the source code you need <a
href="http://ant.apache.org/";>Ant</a>.
- This is a Java-tailored, XML-configured, extensible build or make system. We
- are currently using Ant 1.4, which is included in the source
distribution.</p>
-<p> If you have downloaded a daily snapshot, you need to build a distribution.
- James includes Ant to compile and package its distribution. Extract the
snapshot
- to your favorite directory, cd to that directory and run the build by
calling "build"
- or "./build.sh" which will create an unpacked binary distribution
- in the dist directory, but no archives.</p>
-<p>This "./dist" directory is the distribution directory used in Step 1 and
beyond.
- You may either cd to ./dist, or you may copy and rename the dist directory
to your
- installation directory.</p>
-<p>If you prefer you can run build with the "dist" task "build dist"
- (or "./build.sh dist"). This will create the distribution in the
"./dist"
- directory as well as create .tgz and .zip copies of this directory, however
it may
- require other resources to build the documentation. </p>
-<p> <strong>Warning!</strong> Any changes you've made in the 'dist' directory
- will be lost after a recompilation. If you are making changes to the
conf.xml
- or other files, we recommend you backup and then change the copies in src to
- avoid losing work. </p>
-</section> <section name="Step 1: Installation.">
-<p> Download distibution. Extract or copy all the files in the archive or dist
- directory intto your installation directory. </p>
-</section>
-
-<section name="Step 2: Configuration.">
-<p>After installing the binary, the next step is to adjust the initial
configuration. The server should be stopped, and then
-configuration can proceed. The most essential configuration is set in the
config.xml file. This file can be
-found in the apps/james/SAR-INF subdirectory of the installation directory.</p>
-<p>The out of the box configuration makes certain assumptions and has some
default values that are unlikely to
-be appropriate for real-world servers. There are a few issues that should be
addressed immediately upon installation:</p>
-<ul>
-<li>RemoteManager Administrator Account - Before the RemoteManager service can
be used to add users to this server
-installation an administrator account must be created. More information can
be found <a href="remotemanager_configuration.html">here</a>.</li>
-<li>DNS Servers - James needs to have access to a DNS server for domain
resolution. The out of the box
-configuration assumes that there is a DNS server on localhost. In general
administrators will have to change
-the configuration to point to a valid DNS server. This can be done by
adjusting the dnsserver configuration
-block in the config.xml. More information can be found <a
href="serverwide_configuration.html">here</a>.</li>
-<li>Managed Domain Names/IP Addresses - Out of the box, James only handles
mail that is sent to recipients at
-localhost. It will attempt to deliver all other email to remote SMTP servers.
To allow James to handle email
-for your domain or IP address, you simply need to add the appropriate domain
name or IP address to the servernames
-section of the config.xml. More information can be found <a
href="serverwide_configuration.html">here</a>.</li>
-<li>Postmaster Address - More information can be found <a
href="serverwide_configuration.html">here</a>.</li>
-</ul>
-<p>In addition to adjusting these parameters, you may wish to consult the
documentation for a discussion of
-common configurations. A list of such configurations, as well as the steps
necessary to configure them, can
-be found <a href="index.html">here</a>.</p>
- <p>Read the short and snappy documentation at docs/index.html for a proper
- overview of configuring the system.</p>
- <p>
- <b>Summary</b> (for impatient people)
- </p>
-
-<p> M$ users should just run /bin/run.bat. Unix users will find run.sh under
the
- same directory. A JVM must be present and its location specified in the
JAVA_HOME
- environment variable. Set this on windows at the command prompt with
something
- similar to "set JAVA_HOME=\jdk1.3\bin" on *nix with
JAVA_HOME=/jdk1.3/</p>
-<p> Running [run* --help] will provide a simple command line help. </p>
- <p>
- Most UNIX systems require superuser privileges to open sockets below 1024,
- which includes the IANA-standard SMTP (on port 25) and POP3 (on port 110).
- These default ports can be changed in the conf.xml file. (Obviously, you
- would then need to reconfigure your clients. This may not be an option if
- you want to receive mail from external mailservers.)
- </p>
-
-<p> The Avalon framework will unpack the necessary configuration files you
will
- need to start the server. Wait until it is running, stop it again (ctrl-c),
and
- edit the configuration (thereafter *nix users can run the server in the
background
- using ./run.sh &). For basic use, you only need to set two items in the
- JAMES.conf.xml file: a root password for the remote administration facility
- and the IP address of a DNS server. Once you have edited the configuration
files,
- press 'Enter' on the terminal where Avalon is waiting. </p>
-</section>
-
-<section name="Step 4: Kickstart.">
-<p>Once you have edited the configuration file you will need to restart James
so that the changes take
-effect. When James starts, a list of the James services and the ports on
which they are listening should
-be displayed on the console. Additional information about the system
configuration is printed in the James log files
-upon startup.</p>
-<p>Finally, after configuration is complete, it will be necessary to create
user accounts before the James server
-will be fully operational. Instructions on creating user accounts can be
found
-<a href="adding_users.html">here</a>.</p>
+<section name="Step 3: Kickstart">
+
+ <p>Once you have edited the configuration file you will need to restart
James so that the changes take
+ effect. When James starts, a list of the James services and the ports on
which they are listening should
+ be displayed on the console. Additional information about the system
configuration is printed in the James log files
+ upon startup.</p>
+
+ <p>Finally, after configuration is complete, it will be necessary to create
user accounts before the James server
+ will be fully operational. Instructions on creating user accounts can be
found
+ <a href="adding_users.html">here</a>.</p>
+
<p>Once started you'll see a message saying Avalon is running. This means
that
- Avalon has loaded JAMES and every other needed Block (see /logs/avalon.log)
- and is now waiting for a socket request.
- Since at the beginning James is empty, it will not have any local users
- registered.
- To register a local user open a telnet session with localhost on port 4555,
- log in as root ("root[enter]
<password-you-set-in-conf.xml>[enter]") and
- type "help" for a list of available commands in the "JAMES remote
- administrator tool". It is really a basic set but should allow you to test
- installation.</p>
+ Avalon has loaded JAMES and every other needed Block (see
/logs/avalon.log)
+ and is now waiting for a socket request.
+ Since at the beginning James is empty, it will not have any local users
+ registered.
+ To register a local user open a telnet session with localhost on port
4555,
+ log in as root ("root[enter]
<password-you-set-in-conf.xml>[enter]") and
+ type "help" for a list of available commands in the "JAMES remote
+ administrator tool". It is really a basic set but should allow you to
test
+ installation.</p>
<p>Once you have some local users registered, try sending mail to one of them
- @localhost with SMTP (port 25) (assuming you have not changed the default
- server names in the conf.xml file). You'll see the mail appear under
- ../var/mail/localinbox/[user].
- Try now to retrieve that mail using POP3 (port 110).
- Trace out JAMES actions in /logs/*info.log.
- Actions that will be taken by JAMES on incoming mail are configured in
- the mailet pipe line (/conf/JAMES.conf.xml). Look at it if you want to
- understand what's happening.</p>
+ @localhost with SMTP (port 25) (assuming you have not changed the default
+ server names in the conf.xml file). You'll see the mail appear under
+ ../var/mail/localinbox/[user].
+ Try now to retrieve that mail using POP3 (port 110).
+ Trace out JAMES actions in /logs/*info.log.
+ Actions that will be taken by JAMES on incoming mail are configured in
+ the mailet pipe line (/conf/JAMES.conf.xml). Look at it if you want to
+ understand what's happening.</p>
+
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
