server/apps/distributed-app/README.adoc

= Guice-Distributed Server How-to

== Requirements

 * Java 11 SDK

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

    $ docker network create --driver bridge james

Third party compulsory dependencies:

 * Cassandra 3.11.10
 * ElasticSearch 7.10.2
 * RabbitMQ-Management 3.8.18
 * Zenko Cloudserver or AWS S3

[source]
----
$ docker run -d --network james -p 9042:9042 --name=cassandra cassandra:3.11.10
$ docker run -d --network james -p 9200:9200 --name=elasticsearch --env 'discovery.type=single-node' docker.elastic.co/elasticsearch/elasticsearch:7.10.2
$ docker run -d --network james -p 5672:5672 -p 15672:15672 --name=rabbitmq rabbitmq:3.9.18-management
$ 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
----

== Running

To run james, you have to create a directory containing required configuration files.

James requires the configuration to be in a subfolder of working directory that is called
**conf**. A [sample directory](https://github.com/apache/james-project/tree/master/server/container/guice/cassandra-rabbitmq-guice/sample-configuration)
is provided with some default values you may need to replace, especially compulsory third party software endpoints.

You will need to update its content to match your needs.

You also need to generate a keystore with the following command:

[source]
----
$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
----

Once everything is set up, you just have to run the jar with:

[source]
----
$ java -Dworking.directory=. -Dlogback.configurationFile=conf/logback.xml -Djdk.tls.ephemeralDHKeySize=2048 -jar james-server-distributed-app.jar
----

Note that binding ports below 1024 requires administrative rights.

== Docker distribution

To import the image locally:

[source]
----
docker image load -i target/jib-image.tar
----

Then run it:

[source]
----
docker run --network james apache/james:distributed-latest
----

For security reasons you are required to generate your own keystore, that you can mount into the container via a volume:

[source]
----
keytool -genkey -alias james -keyalg RSA -keystore keystore
docker run --network james -v $PWD/keystore:/root/conf/keystore docker run apache/james:distributed-latest
----

Use the [JAVA_TOOL_OPTIONS environment option](https://github.com/GoogleContainerTools/jib/blob/master/docs/faq.md#jvm-flags)
to pass extra JVM flags. For instance:

[source]
----
docker run --network james -e "JAVA_TOOL_OPTIONS=-Xmx500m -Xms500m" apache/james:distributed-latest
----

[Glowroot APM](https://glowroot.org/) is packaged as part of the docker distribution to easily enable valuable performances insights.
Disabled by default, its java agent can easily be enabled:


[source]
----
docker run --network james -e "JAVA_TOOL_OPTIONS=-javaagent:/root/glowroot.jar" apache/james:distributed-latest
----
The [CLI](https://james.apache.org/server/manage-cli.html) can easily be used:


[source]
----
docker exec CONTAINER-ID james-cli ListDomains
----

Note that you can create a domain via an environment variable. This domain will be created upon James start:

[source]
----
--environment DOMAIN=domain.tld
----