Author: matthieu
Date: Tue Nov 3 16:51:30 2015
New Revision: 1712344
URL: http://svn.apache.org/viewvc?rev=1712344&view=rev
Log:
JAMES-1626 Add configuration documentation
Added:
james/project/trunk/server/src/site/xdoc/config-cassandra.xml
james/project/trunk/server/src/site/xdoc/config-elasticsearch.xml
james/project/trunk/server/src/site/xdoc/config-guice.xml
james/project/trunk/server/src/site/xdoc/quick-start-cassandra.xml
Modified:
james/project/trunk/server/src/site/xdoc/index.xml
Added: james/project/trunk/server/src/site/xdoc/config-cassandra.xml
URL:
http://svn.apache.org/viewvc/james/project/trunk/server/src/site/xdoc/config-cassandra.xml?rev=1712344&view=auto
==============================================================================
--- james/project/trunk/server/src/site/xdoc/config-cassandra.xml (added)
+++ james/project/trunk/server/src/site/xdoc/config-cassandra.xml Tue Nov 3
16:51:30 2015
@@ -0,0 +1,49 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<document>
+
+ <properties>
+ <title>Apache James Server 3 - Cassandra Configuration</title>
+ </properties>
+
+<body>
+
+ <section name="Cassandra Configuration">
+
+ <p>Consult <a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/cassandra-template.properties";>cassandra-template.properties</a>
to get some examples and hints.</p>
+
+ <dl>
+ <dt><strong>cassandra.ip</strong></dt>
+ <dd>Is the IP (or host) of the Cassandra used. (cluster is not yet
supported)</dd>
+ <dt><strong>cassandra.port</strong></dt>
+ <dd>Is the port used to connect to Cassandra.</dd>
+ <dt><strong>cassandra.keyspace</strong></dt>
+ <dd>Is the name of the keyspace used by James.</dd>
+ <dt><strong>cassandra.replication.factor</strong></dt>
+ <dd>Is the replication factor. (should be 1, as cluster is not yet
supported)</dd>
+ </dl>
+
+<p>If you want more explanation about Cassandra configuration, you should
visit the dedicated <a
href="http://docs.datastax.com/en/cassandra/2.1/cassandra/gettingStartedCassandraIntro.html";>documentation</a>.</p>
+
+ </section>
+
+</body>
+
+</document>
Added: james/project/trunk/server/src/site/xdoc/config-elasticsearch.xml
URL:
http://svn.apache.org/viewvc/james/project/trunk/server/src/site/xdoc/config-elasticsearch.xml?rev=1712344&view=auto
==============================================================================
--- james/project/trunk/server/src/site/xdoc/config-elasticsearch.xml (added)
+++ james/project/trunk/server/src/site/xdoc/config-elasticsearch.xml Tue Nov
3 16:51:30 2015
@@ -0,0 +1,45 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<document>
+
+ <properties>
+ <title>Apache James Server 3 - ElasticSearch Configuration</title>
+ </properties>
+
+<body>
+
+ <section name="ElasticSearch Configuration">
+
+ <p>Consult <a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/elasticsearch-template.properties";>elasticsearch-template.properties</a>
to get some examples and hints.</p>
+
+ <dl>
+ <dt><strong>elasticsearch.clusterName</strong></dt>
+ <dd>Is the name of the cluster used by James.</dd>
+ <dt><strong>elasticsearch.masterHost</strong></dt>
+ <dd>Is the IP (or host) of the ElasticSearch master</dd>
+ </dl>
+
+<p>If you want more explanation about ElasticSearch configuration, you should
visit the dedicated <a
href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html";>documentation</a>.</p>
+
+ </section>
+
+</body>
+
+</document>
Added: james/project/trunk/server/src/site/xdoc/config-guice.xml
URL:
http://svn.apache.org/viewvc/james/project/trunk/server/src/site/xdoc/config-guice.xml?rev=1712344&view=auto
==============================================================================
--- james/project/trunk/server/src/site/xdoc/config-guice.xml (added)
+++ james/project/trunk/server/src/site/xdoc/config-guice.xml Tue Nov 3
16:51:30 2015
@@ -0,0 +1,99 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<document>
+
+ <properties>
+ <title>Apache James Server 3 - Guice configuration</title>
+ </properties>
+
+<body>
+
+ <section name="Guice configure Apache James Server">
+
+ <p>Such configuration is only developed for Cassandra backend.</p>
+ <p>You are encouraged to contribute by developing a new backend guice
module.
+ Have a look to the <i>james-server-cassandra-guice</i> artifact.
+ </p>
+
+ <p>We provide a sample-configuration folder with needed files to run
James.
+ You can start by copying it and modify these files according to your
needs.</p>
+
+ <p>You can/must configure James for the following:</p>
+
+ <table>
+
+ <tr>
+ <th>Config File Sample</th>
+ <th>Config Area</th>
+ <th>Config Comment</th>
+ </tr>
+
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/cassandra-template.properties";>cassandra-template.properties</a></td>
+ <td><a href="config-cassandra.html">Cassandra Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/dnsservice-template.xml";>dnsservice.xml</a></td>
+ <td><a href="config-dnsservice.html">DNS Service Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/elasticsearch-template.properties";>elasticsearch-template.properties</a></td>
+ <td><a href="config-elasticsearch.html">ElasticSearch
Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/imapserver-template.xml";>imapserver.xml</a></td>
+ <td><a href="config-imap4.html">IMAP4 Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/lmtpserver-template.xml";>lmtpserver.xml</a></td>
+ <td><a href="config-smtp-lmtp.html">LMTP Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/mailetcontainer-template.xml";>mailetcontainer.xml</a></td>
+ <td><a href="config-mailetcontainer.html">Mailet Container
Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/pop3server-template.xml";>pop3server.xml</a></td>
+ <td><a href="config-pop3.html">POP3 Configuration</a></td>
+ <td></td>
+ </tr>
+ <tr>
+ <td><a
href="http://svn.apache.org/repos/asf/james/server/trunk/app/src/main/resources/smtpserver-template.xml";>smtpserver.xml</a></td>
+ <td><a href="config-smtp-lmtp.html">SMTP Configuration</a></td>
+ <td></td>
+ </tr>
+
+ </table>
+
+ <p>See also more specific configurations related to <a
href="config-ssl-tls.html">TLS</a>,
+ <a href="config-sieve.html">Sieve</a> and
+ <a href="config-antispam.html">Antispam</a>.</p>
+
+ </section>
+
+</body>
+
+</document>
Modified: james/project/trunk/server/src/site/xdoc/index.xml
URL:
http://svn.apache.org/viewvc/james/project/trunk/server/src/site/xdoc/index.xml?rev=1712344&r1=1712343&r2=1712344&view=diff
==============================================================================
--- james/project/trunk/server/src/site/xdoc/index.xml (original)
+++ james/project/trunk/server/src/site/xdoc/index.xml Tue Nov 3 16:51:30 2015
@@ -64,6 +64,12 @@
<a href="manage.html">manage</a>, <a
href="monitor.html">monitor</a>
and <a href="dev.html">develop</a> Apache James Server.</p>
+ <p>
+ We are currently working on an experimental module which goal is to
simplify the configuration process.
+ This module only supports the <a
href="config-guice.html">Cassandra</a> backend yet,
+ and may be <a href="quick-start-cassandra.html">started</a> with
docker.
+ </p>
+
<p>Download Apache James Mail Server 3.0-beta4 and <a
href="quick-start.html">quick-start</a> it!</p>
<p>
<span class="minibutton btn-download">
@@ -120,10 +126,12 @@
<subsection name="Configurable">
- <p>Configure the stores,... via the well-known Spring framework -
<a href="config.html">read more</a>.</p>
+ <p>Configure the stores,...</p>
+ <p>via the well-known Spring framework - <a
href="config.html">read more</a>.</p>
<p><img src="images/conf/config-example.png" /></p>
+ <p>or via the Guice module - <a href="config-guice.html">read
more</a>.</p>
</subsection>
</td></tr>
Added: james/project/trunk/server/src/site/xdoc/quick-start-cassandra.xml
URL:
http://svn.apache.org/viewvc/james/project/trunk/server/src/site/xdoc/quick-start-cassandra.xml?rev=1712344&view=auto
==============================================================================
--- james/project/trunk/server/src/site/xdoc/quick-start-cassandra.xml (added)
+++ james/project/trunk/server/src/site/xdoc/quick-start-cassandra.xml Tue Nov
3 16:51:30 2015
@@ -0,0 +1,187 @@
+<?xml version="1.0"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<document>
+
+ <properties>
+ <title>Apache James Server 3 - Quick Start for Cassandra backend</title>
+ </properties>
+
+<body>
+
+<section name="Quick Start for Cassandra backend">
+
+ <p>The goal of the document is to allow anyone to start with James on Docker
as an operational mail server.</p>
+ <p>The method described bellow should not be used in production.</p>
+
+<source>
+Step 0: Requirements
+####################
+
+ * Java 8 SDK
+ * 512MB RAM (launches with -Xmx512M - can use less, can need more, depending
on load)
+ * Docker 1.7.1+
+ * Maven 3.3
+
+Step 1: Download
+#################
+
+ * Clone the James git repository
+
+<i>$ git clone git://git.apache.org/james-project.git</i>
+
+Step 3: Compile
+###############
+
+ * Compile the Guice Cassandra project
+
+<i>$ mvn package -DskipTests -am -pl server/container/cassandra-guice</i>
+
+Step 3: Deploy
+##############
+
+3.1. Deploy Cassandra (optional)
+You may skip this part if you already have a running Cassandra on your network.
+
+<i>$ docker run --name=cassandra cassandra</i>
+
+3.2. Deploy ElasticSearch (optional)
+You may skip this part if you already have a running ElasticSearch on your
network.
+
+<i>$ docker run --name=elasticsearch elasticsearch:1.5.2</i>
+
+Step 4: Configure
+#################
+
+ * Follow the <a href="config-guice.html">Cassandra guice</a> configuration
documentation.
+ * We need to provide the key we will use for TLS. For obvious reasons, this
is not provided in this git.
+
+Copy your TSL keys to ./conf/keystore or generate it using :
+
+<i>$ keytool -genkey -alias james -keyalg RSA -keystore ./conf/keystore</i>
+
+You will have to put the keystore password in the right xml files
(imapserver.xml, pop3server.xml, smtpserver.xml)
+
+Step 5: Start
+#############
+
+ * Run James
+
+<i>$ java -Dworking.directory=<b>WORKING_PATH</b> -jar
server/container/cassandra-guice/target/james-server-cassandra-guice-beta5-SNAPSHOT.jar</i>
+
+Where :
+- <b>WORKING_PATH</b> is the path where are located your configuration file
folder.
+
+Step 6: Create Domains and Users
+################################
+
+Time to add domains and users.
+
+<i>$ java -jar
server/container/cli/target/james-server-cli-3.0.0-beta5-SNAPSHOT.jar -h
127.0.0.1 -p 9999 adddomain <b>DOMAIN</b></i>
+
+<i>$ java -jar
server/container/cli/target/james-server-cli-3.0.0-beta5-SNAPSHOT.jar -h
127.0.0.1 -p 9999 adduser <b>USER_MAIL_ADDRESS</b> <b>PASSWORD</b></i>
+
+Where :
+- <b>DOMAIN</b> is the domain you want to handle with this server.
+- <b>USER_MAIL_ADDRESS</b> is the mail address that will be used by this user.
+- <b>PASSWORD</b> is the password that will be used by this user.
+
+Step 8: Test
+############
+
+$ telnet <b>HOSTNAME</b> 25
+Trying <b>HOSTNAME</b>...
+Connected to <b>HOSTNAME</b>.
+Escape character is '^]'.
+220 172.16.1.131 SMTP Server (JAMES SMTP Server 3.0-beta4) ready Sat, 6 Nov
2010 17:31:33 +0100 (CET)
+ehlo test
+250-172.16.1.131 Hello test (aoscommunity.com [127.0.0.1])
+250-PIPELINING
+250-ENHANCEDSTATUSCODES
+250 8BITMIME
+mail from:<YOUR_NAME@YOUR_DOMAIN>
+250 2.1.0 Sender <YOUR_NAME@YOUR_DOMAIN> OK
+rcpt to:<YOUR_NAME@YOUR_DOMAIN>
+250 2.1.5 Recipient <YOUR_NAME@YOUR_DOMAIN> OK
+data
+354 Ok Send data ending with <CRLF>.<CRLF>
+subject: test
+
+this is a test
+.
+250 2.6.0 Message received
+quit
+Connection closed by foreign host.
+
+Step 8: Manage
+##############
+
+8.1. Manage via james-cli
+
+ usage:
+<i>$ java -jar
server/container/cli/target/james-server-cli-3.0.0-beta5-SNAPSHOT.jar -h
127.0.0.1 -p 9999</i>
+
+ Available commands:
+ adduser </username> </password>
+ removeuser </username>
+ listusers
+ adddomain </domainname>
+ removedomain </domainname>
+ listdomains
+
+8.2. Manage via JMX
+
+ * Launch jconsole (or any other JMX client) and connect on
URL=service:jmx:rmi:///jndi/rmi://localhost:<b>HOSTNAME</b>/jmxrmi
+ * Select the MBeans tab and open the org.apache.james node to view
attributes and execute operations.
+
+Step 9: Monitor
+###############
+
+ * Monitor the ./log/james-server.log log file.
+
+ * Monitor via JMX (launch any JMX client and connect to
URL=service:jmx:rmi:///jndi/rmi://<b>HOSTNAME</b>:9999/jmxrmi)
+
+ * Check ./var folder usage
+
+ mail
+ +-error
+ +-address-error
+ +-relay-denied
+ +-spam
+
+ store
+ +-maildir
+ +-derby
+ +-jackrabbit
+ +-activemq
+ +-brokers
+ +-james
+ +-blob-transfer
+ +-outgoing
+ +-spool
+
+ * Check /tmp folder usage
+
+</source>
+
+</section>
+
+</body>
+
+</document>
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
