Apache James parent project

Table of Contents

• 1. About
• 2. Git configuration
• 3. Building in Docker
  • 3.1. Build the Docker image
  • 3.2. Run the build in Docker
• 4. Running James in docker
  • 4.1. Requirements
  • 4.2. How to ?
  • 4.3. Useful commands
• 5. Running deployement Tests
• 6. Under the hood

1. About

The main goal of this project is to provide a maven based parent project to Apache James.
So, building phase may be checked with a single command.

2. Git configuration

We are providing additional commands to git.
In order to install those commands, you have to modify the .git/config file by adding the following lines:

[include]
        path = ../gitconfig

List of added commands:

• git createbranches BRANCH: creates the branch BRANCH on this projects and all submodules

• git pushbranches REPO BRANCH: pushes the branch BRANCH on this project and all submodules in the REPO repositories

3. Building in Docker

Note	You need to install docker before going ahead. Please follow the installation process corresponding to your environment.

3.1. Build the Docker image

$ docker build -t james/parent .

3.2. Run the build in Docker

In order to run the build, you have to launch the following command:

$ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/destination:/destination -t james/parent -s -u URL BRANCH

Where:

• $PWD/.m2:/root/.m2: is the first volume used to share the maven repository,
  as we don’t want to download all dependencies on each build

• $PWD/destination:/destination: is the third volume used to get the compiled elements,
  as it is needed by the container that will run James.

• BRANCH: is the given git branch of the james-parent repository to build

• -s option: given tests will not be played while building. Not specifying means play tests.

• -u URL: Precise URL to clone. Default is to use /origin docker folder. In this case you have to provide the following volume :

• $PWD:/origin: is the second volume used to share the james-parent repository,
  as we don’t want to clone it in docker

Note : Using volumes on a remote host will not work. You can simply use the remote option :

$ docker run -v /destination -t james/parent  -s -u https://ci.open-paas.org/stash/scm/jwc/james-parent.git BRANCH

4. Running James in docker

4.1. Requirements

You should have the zip resulting of the build in the ./destination folder.

4.2. How to ?

You need a running cassandra in docker. To achieve this run :

$ docker run --name=cassandra cassandra

You need a running ElasticSearch in docker. To achieve this run :

$ docker run --name=elasticsearch elasticsearch:1.5.2

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 destination/conf/keystore or generate it using :

keytool -genkey -alias james -keyalg RSA -keystore destination/conf/keystore

Then we need to build james container :

$ docker build -f JamesRunDockerfile -t james_run ./

To run this container :

$ docker run --hostname HOSTNAME -p "25:25" -p "110:110" -p "143:143" -p "465:465" -p "587:587" -p "993:993" --link cassandra:cassandra --link elasticsearch:elasticsearch -t james_run

Where :

• HOSTNAME is the hostname you want to give to your James container. This DNS entry will be used to send mail to your James server.

4.3. Useful commands

4.3.1. How to add a domain ?

# Add DOMAIN to 127.0.0.1 in your host /etc/hosts
$ docker exec JAMES_CONTAINER_ID /root/james-server-app-3.0.0-beta5-SNAPSHOT/bin/james-cli.sh -h 127.0.0.1 -p 9999 adddomain DOMAIN

Where :

• DOMAIN is the domain you want to add.

• JAMES_CONTAINER_ID is the docker ID of your james container.

4.3.2. How to add a user ?

$ docker exec JAMES_CONTAINER_ID /root/james-server-app-3.0.0-beta5-SNAPSHOT/bin/james-cli.sh -h 127.0.0.1 -p 9999 adduser USER_MAIL_ADDRESS PASSWORD

Where :

• USER_MAIL_ADDRESS is the mail address that will be used by this user.

• PASSWORD is the password that will be used by this user.

• JAMES_CONTAINER_ID is the docker ID of your james container

You can then just add DOMAIN to your /etc/hosts and you can connect to your james account with for instance thunderbird.

4.3.3. How to manage SIEVE scripts ?

Each user can manage his SIEVE scripts threw the manage SIEVE mailet.

To use the manage SIEVE mailet :

• You need to create the user sievemanager@DOMAIN ( if you don’t, the SMTP server will check the domain, recognize it, and look for an absent local user, and will generate an error ).

• You can send Manage Sieve commands by mail to sievemanager@DOMAIN. Your subject must contain the command. Scripts needs to be added as attachments and need the ".sieve" extension.

To activate a script for a user, you need the following combinaison :

• PUTSCRIPT scriptname

• SETACTIVE scriptname

4.3.4. I want to retrieve users and password from my previous container

Some james data ( those non related to mailbox, eg : mail queue, domains, users, rrt, SIEVE scripts, mail repositories ) are not yet supported by our Cassandra implementation.

To keep these data when you run a new container, you can mount the following volume :

 -v /root/james-server-app-3.0.0-beta5-SNAPSHOT/var:WORKDIR/destination/var

Where :

• WORKDIR is the absolute path to your james-parent workdir.

Beware : you will have concurrency issues if multiple containers are running on this single volume.

5. Running deployement Tests

We wrote some MPT (James' Mail Protocols Tests subproject) deployement tests to validate a James deployement.

It uses the External-James module, that uses environment variables to locate a remote IMAP server and run integration tests against it.

For that, the target James Server needs to be configured with a domain domain and a user imapuser with password password. Read above documentation to see how you can do this.

You have to run MPT tests inside docker. As you need to use maven, the simplest option is to use james/parent image, and override the entry point ( as git and maven are already configured there ) :

$ docker run -t --entrypoint="/root/integration_tests.sh" -v $PWD/.m2:/root/.m2 james/parent REPO_URL BRANCH JAMES_IP JAMES_PORT

Where :

• REPO_URL : James parent repository URL

• BRANCH : Branch to use in order to build integration tests

• JAMES_IP : IP address or DNS entry for your James server

• JAMES_PORT : Port allocated to James' IMAP port.

6. Under the hood

Other Apache James projects are linked to this project by using git submodules.

The following commands will give you a working state for the given git branch:

$ git checkout BRANCH
$ git submodule init
$ git submodule update