Quick Start for Cassandra backend

The goal of the document is to allow anyone to start a James instance as an operational mail server.

The two methods described bellow should not be used in production.

First method, from James source code:

Step 0: Requirements
####################

  * Java 8 SDK
  * 2GB RAM
  * Docker 1.7.1+
  * Maven 3.3

Step 1: Download
#################

  * Clone the James git repository

$ git clone git://git.apache.org/james-project.git

Step 3: Compile
###############

  * Compile the Guice Cassandra project
  
$ mvn package -DskipTests --also-make --projects server/container/guice/cassandra-guice

  * Compile the James CLI project
  
$ mvn package -DskipTests -am -pl server/container/cli

Step 3: Deploy
##############

3.1. Deploy Cassandra (optional)
You may skip this part if you already have a running Cassandra on your network.

$ docker run --detach=true --name=cassandra cassandra:2.2.3

3.2. Deploy ElasticSearch (optional)
You may skip this part if you already have a running ElasticSearch on your network.

$ docker run --detach=true --name=elasticsearch elasticsearch:2.2.1

Step 4: Configure
#################

  * Follow the Cassandra guice 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 TLS keys to ./conf/keystore or generate it using :

$ keytool -genkey -alias james -keyalg RSA -keystore ./conf/keystore

You will have to put the keystore password in the right xml files (imapserver.xml, pop3server.xml, smtpserver.xml)

You are welcome to use the default configuration which can be found in the $PWD/dockerfiles/run/guice/cassandra/destination/conf folder.

Step 5: Start
#############

  * Run James

$ sudo java -Dworking.directory=WORKING_PATH -jar server/container/guice/cassandra-guice/target/james-server-cassandra-guice.jar

Where :
- WORKING_PATH is the path of the folder which contains your configuration files.

You have to run this command with the superuser, has some default ports are lower than 1000 (default imap, smtp...).
You may get rid of that by overriding the default configuration

Step 6: Create Domains and Users
################################

Time to add domains and users.

$ java -jar server/container/cli/target/james-server-cli.jar -h 127.0.0.1 -p 9999  adddomain DOMAIN

$ java -jar server/container/cli/target/james-server-cli.jar -h 127.0.0.1 -p 9999  adduser USER_MAIL_ADDRESS PASSWORD

Where :
- DOMAIN is the domain you want to handle with this server
- USER_MAIL_ADDRESS user's email
- PASSWORD user's password

Step 7: Test
############

$ telnet HOSTNAME 25
Trying HOSTNAME...
Connected to HOSTNAME.
Escape character is '^]'.
220 172.16.1.131 SMTP Server (JAMES SMTP Server 3.0.0) ready Wed, 20 Jul 2017 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: 
$ java -jar server/container/cli/target/james-server-cli.jar -h 127.0.0.1 -p 9999

  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:HOSTNAME/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://HOSTNAME: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

Second method, with docker-compose:

Step 0: Requirements
####################

  * 2GB RAM
  * Docker 1.7.1+
  * wget

Step 1: Download
#################

  * Get the James docker-compose file

$ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml

Step 2: Start
#############

  * Run James

$ docker-compose up

Step 3: Create Domains and Users
################################

Time to add domains and users.

$ docker exec james java -jar /root/james-cli.jar -h 127.0.0.1 -p 9999 adddomain DOMAIN

$ docker exec james java -jar /root/james-cli.jar -h 127.0.0.1 -p 9999  adduser USER_MAIL_ADDRESS PASSWORD

Where :
- DOMAIN is the domain you want to handle with this server
- USER_MAIL_ADDRESS user's email
- PASSWORD user's password


Step 4: Test
############

$ telnet HOSTNAME 25
Trying HOSTNAME...
Connected to HOSTNAME.
Escape character is '^]'.
220 172.16.1.131 SMTP Server (JAMES SMTP Server 3.0.0) ready Wed, 20 Jul 2017 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 5: Manage
##############

5.1. Manage via james-cli

  usage: 
$ docker exec james java -jar /root/james-cli.jar -h 127.0.0.1 -p 9999

  Available commands:
    adduser </username> </password>
    removeuser </username>
    listusers
    adddomain </domainname>
    removedomain </domainname>
    listdomains

5.2. Manage via JMX

  * Launch jconsole (or any other JMX client) and connect on URL=service:jmx:rmi:///jndi/rmi://localhost:HOSTNAME/jmxrmi
  * Select the MBeans tab and open the org.apache.james node to view attributes and execute operations.

Step 6: 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://HOSTNAME: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