server/apps/distributed-pop3-app/README.adoc

= Guice-Distributed POP3 Server How-to

This server diverges from the distributed server by only using MessageId backed by a TimeUUID as a message identifier,
thus is multi-datacenter friendly, however comes with a reduced feature set (only supports SMTP protocol).

== 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
 * RabbitMQ-Management 3.8.18
 * Zenko Cloudserver or AWS S3

[source]
----
$ docker run -d --network james -p 9042:9042 --name=cassandra cassandra:4.1.9
$ docker run -d --network james -p 5672:5672 -p 15672:15672 --name=rabbitmq rabbitmq:4.1.1-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 ghcr.io/scality/cloudserver:c1ba296859690c1cbbec609aaae430f6b04b4745
----

== 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-pop3-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 apache/james:distributed-pop3-latest
----

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]
----
docker run --network james apache/james:distributed-pop3-latest --generate-keystore
----

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-pop3-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-pop3-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
----