= Distributed James Server &mdash; Performance checklist
:navtitle: Performance checklist

This guide aims to help James operators refine their James configuration and set up to achieve better performance.

== Database setup

Cassandra, OpenSearch, RabbitMQ is a large topic in itself that we do not intend to cover here. Yet, here are some
very basic recommendation that are always beneficial to keep in mind.

We recommend:

* Running Cassandra, OpenSearch on commodity hardware with attached SSD. SAN disks are known to cause performance
issues for these technologies. HDD disks are to be banned for these performance related applications.
* We recommend getting an Object Storage SaaS offering that suites your needs. Most generalist S3 offers will suite
James needs.
* We do provide a guide on xref:[Database benchmarks] that can help identify and fix issues.

== James configuration

=== Cassandra

People tunning for performance would likely accept relaxing their consistency needs. James allows doing this.

**LightWeight Transactions (LWT)** can be disabled where they are not essential. This can be done within
xref:[cassandra.properties]:

....
mailbox.read.strong.consistency=false
message.read.strong.consistency=false
message.write.strong.consistency.unsafe=false
mailrepository.strong.consistency=false
....

Also, James allows for **Read repairs** where consistency checks are piggy backed on reads randomly. This of course
comes at a performance cost as it generates extre reads, thus minimizing read repair probability can help improving
performance. This can be done within
xref:[cassandra.properties]:

....
mailbox.read.repair.chance=0.00
mailbox.counters.read.repair.chance.max=0.000
mailbox.counters.read.repair.chance.one.hundred=0.000
....

One can also avoid some Cassandra requests by disabling ACLs (meaning users will only access to the mailboxes they own,
all mailbox-sharing features will thus not be achievable). This can be done within
xref:[cassandra.properties]:

....
acl.enabled=false
....

Important settings in the `` file includes:

* Throttling: if too low then the Cassandra cluster is under-utilized. If too high, request bursts can cause significant
Cassandra overload.

....
  advanced.throttler {
    class = org.apache.james.backends.cassandra.utils.LockLessConcurrencyLimitingRequestThrottler

    max-queue-size = 10000

    max-concurrent-requests = 192
  }
....

=== Object storage

We recommend the use of the blob store cache, which will be populated by email headers which shall be treated as metadata.

`blob.properties`:

....
cache.enable=true
cache.cassandra.ttl=1year
cache.cassandra.timeout=100ms
cache.sizeThresholdInBytes=16 KiB
....

=== RabbitMQ

We recommend against the use of the CassandraMailQueueView, as browsing and advanced queue management features
is unnecessary for Mail Delivery Agent and are not meaningful in the absence of delays.

Similarly, we recommend turning off queue size metrics, which are expensive to compute.

We also recommend against the use of publish confirms, which comes at a high performance price.

In `rabbitmq.properties`:

....
cassandra.view.enabled=false

mailqueue.size.metricsEnabled=false

event.bus.publish.confirm.enabled=false
mailqueue.publish.confirm.enabled=false
....

=== JMAP protocol

If you are not using JMAP, disabling it will avoid you the cost of populating related projections and thus is recommended.
Within `jmap.properties`:

....
enabled=false
....

We recommend turning on EmailQueryView as it enables resolution of mailbox listing against Cassandra, thus unlocking massive
stability / performance gains. Within `jmap.properties`:

....
view.email.query.enabled=true
....

=== IMAP / SMTP

We recommend against resolving client connection DNS names. This behaviour can be disabled via a system property within
`jvm.properties`:

....
james.protocols.mdc.hostname=false
....

Concurrent IMAP request count is the critical setting. In `imapServer.xml`:

....
<concurrentRequests>200</concurrentRequests>
<maxQueueSize>4096</maxQueueSize>
....

Other recommendation includes avoiding unecessary work upon IMAP IDLE, not starting dedicated BOSS threads:

....
<ignoreIDLEUponProcessing>false</ignoreIDLEUponProcessing>
<bossWorkerCount>0</bossWorkerCount>
....

=== Other generic recommendations

* Remove unneeded listeners / mailets
* Reduce duplication of Matchers within mailetcontainer.xml
* Limit usage of "DEBUG" loglevel. INFO should be more than decent in most cases.
* While GC tunning is a science in itself, we had good results with G1GC and a low pause time:

....
-Xlog:gc*:file=/root/gc.log -XX:MaxGCPauseMillis=20 -XX:ParallelGCThreads=2
....

* We recommand tunning bach sizes: `batchsizes.properties`. This allows, limiting parallel S3 reads, while loading many
messages concurrently on Cassandra, and improves IMAP massive operations support.

....
fetch.metadata=200
fetch.headers=30
fetch.body=30
fetch.full=30

copy=8192

move=8192
....