server/apps/cassandra-app/README.adoc

= Cassandra Guice Server How-to

*DEPRECATION*: See JAMES-3766. Removal of cassandra-app is planned after Apache James 3.8.0 release.

Users are encouraged to migrate to the distributed server.

*WARNING*: This server only targets single James node deployment on top of a shared database.

It does not target deployments with multiple James nodes as is misses inter-node communication capabilities.

*WARNING*: JAMES-3591 Cassandra is not made to store large binary content, its use will be suboptimal compared to
alternatives (namely S3 compatible BlobStores backed by for instance S3, MinIO or Ozone)

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

[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' opensearchproject/opensearch:2.14.0
----

== 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/apps/cassandra-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.

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-cassandra-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:cassandra-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:cassandra-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:cassandra-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:cassandra-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
----