Distributed James Server — Run with docker

Running via docker-compose

Requirements: docker & docker-compose installed.

When you try James this way, you will use the most current state of James. It will be configured to run with Cassandra & OpenSearch. All those three components will be started with a single command.

You can retrieve the docker-compose file : ( docker-compose file and james image name should be changed)

$ wget https://raw.githubusercontent.com/apache/james-project/master/server/apps/distributed-app/docker-compose.yml

Then, you just have to start the services:

$ docker-compose up -d

Wait a few seconds in order to have all those services start up. You will see the following log when James is available: james | Started : true

A default domain, james.local, has been created. You can see this by running:

$ docker exec james james-cli -h 127.0.0.1 -p 9999 listdomains

James will respond to IMAP port 143 and SMTP port 25. You have to create users before playing with james. You may also want to create other domains. Follow the 'Useful commands' section for more information about James CLI.

Run with docker

Requirements

Compile the whole project:

mvn clean install -DskipTests -T 4

Then load the distributed server docker image:

docker load -i server/apps/distributed-app/target/jib-image.tar

Alternatively we provide convenience distribution for the latest release:

docker pull apache/james:distributed-3.7.4

Running

Firstly, create your own user network on Docker for the James environment:

$ docker network create --driver bridge james

You need a running cassandra in docker which connects to james network. To achieve this run:

$ docker run -d --network james --name=cassandra cassandra:3.11.10

You need a running rabbitmq in docker which connects to james network. To achieve this run:

$ docker run -d --network james --name=rabbitmq rabbitmq:3.9.18-management

You need a running Zenko Cloudserver objectstorage in docker which connects to james network. To achieve this run:

$ docker run -d --network james --env 'REMOTE_MANAGEMENT_DISABLE=1' --env 'SCALITY_ACCESS_KEY_ID=accessKey1' --env 'SCALITY_SECRET_ACCESS_KEY=secretKey1' --name=s3 zenko/cloudserver:8.2.6

You need a running OpenSearch in docker which connects to james network. To achieve this run:

$ docker run -d --network james -p 9200:9200 --name=opensearch --env 'discovery.type=single-node' opensearchproject/opensearch:2.1.0

If you want to use all the JMAP search capabilities, you may also need to start Tika container which connects to james network:

$ docker run -d --network james --name=tika apache/tika:1.28.2

You can find more explanation on the need of Tika in this page.

To run this container :

$ docker run --network james --hostname HOSTNAME -p "25:25" -p 80:80 -p "110:110" -p "143:143" -p "465:465" -p "587:587" -p "993:993" -p "127.0.0.1:8000:8000" --name james_run
    -v $PWD/keystore:/root/conf/keystore -t apache/james:distributed-3.7.4 --generate-keystore

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.

Webadmin port binding is restricted to loopback as users are not authenticated by default on webadmin server. Thus you should avoid exposing it in production. Note that the above example assumes 127.0.0.1 is your loopback interface for convenience but you should change it if this is not the case on your machine.

If you want to pass additional options to the underlying java command, you can configure a JAVA_TOOL_OPTIONS env variable, for example add:

--env "JAVA_TOOL_OPTIONS=-Xms256m -Xmx2048m"

To have log file accessible on a volume, add -v $PWD/logs:/logs option to the above command line, where $PWD/logs is your local directory to put files in.

Specific keystore

Alternatively, you can also generate a keystore in your conf folder with the following command, and drop --generate-keystore option:

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

Instrumentation

You can use Glowroot to instrumentalize James. It is packaged as part of the docker distribution to easily enable valuable performances insights. Disabled by default, its java agent can easily be enabled:

--env "JAVA_TOOL_OPTIONS=-javaagent:/root/glowroot.jar" -p "4000:4000"

By default, the Glowroot UI is accessible from every machines in the network as defined in the destination/admin.json. Which you could configure before building the image, if you want to restrict its accessibility to localhost for example. See the Glowroot post installation steps for more details.

Or by mapping the 4000 port to the IP of the desired network interface, for example -p 127.0.0.1:4000:4000.

Handling attachment indexing

You can handle attachment text extraction before indexing in OpenSearch. This makes attachments searchable. To enable this:

Run tika connect to james network:

$ docker run -d --network james --name tika apache/tika:1.28.2

Run James:

$ docker run --network james --hostname HOSTNAME -p "25:25" -p 80:80 -p "110:110" -p "143:143" -p "465:465" -p "587:587" -p "993:993" -p "127.0.0.1:8000:8000"
    --name james_run -v $PWD/keystore:/root/conf/keystore -t apache/james:distributed-latest