server/apps/distributed-app/README.adoc

= Guice-Distributed Server How-to

== Requirements

 * Java 21 SDK

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

    $ docker network create --driver bridge james

Third party compulsory dependencies:

 * Cassandra 4.0
 * OpenSearch 2.1.0
 * RabbitMQ-Management 3.8.18
 * Zenko Cloudserver or AWS S3

[source]
----
$ docker run -d --network james -p 9042:9042 --name=cassandra cassandra:4.1.5
$ docker run -d --network james -p 9200:9200 --name=opensearch --env 'discovery.type=single-node' --env 'DISABLE_SECURITY_PLUGIN=true' --env 'DISABLE_INSTALL_DEMO_CONFIG=true' opensearchproject/opensearch:2.14.0
$ docker run -d --network james -p 5672:5672 -p 15672:15672 --name=rabbitmq rabbitmq:3.13.3-management
$ docker run -d --network james -p 8000:8000 --env 'REMOTE_MANAGEMENT_DISABLE=1' --env 'SCALITY_ACCESS_KEY_ID=accessKey1' --env 'SCALITY_SECRET_ACCESS_KEY=secretKey1' --name=s3 registry.scality.com/cloudserver/cloudserver:8.7.25
----

== Docker distribution

To import the image locally:

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

Then run it along with its dependency:

[source]
----
docker compose up -d
----

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]
----
  james:
    ...
    environment:
      - JAVA_TOOL_OPTIONS=-Xmx500m -Xms500m
----

[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]
----
  james:
    ...
    environment:
      - JAVA_TOOL_OPTIONS=-javaagent:/root/glowroot.jar
----
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]
----
  james:
    ...
    environment:
      - DOMAIN=domain.tld
----

== Running without docker

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/apps/distributed-app/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.

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 --generate-keystore
----

In the case of quick start James without manually creating a keystore (e.g. for development), just input the command argument `--generate-keystore` when running,
James will auto-generate keystore file with the default setting that is declared in `jmap.properties` (tls.keystoreURL, tls.secret)

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

Note that binding ports below 1024 requires administrative rights.