This is an automated email from the ASF dual-hosted git repository.
chibenwa pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
The following commit(s) were added to refs/heads/master by this push:
new 3c944b84b7 [DOC] Refresh james benchmark (#3136)
3c944b84b7 is described below
commit 3c944b84b73f2d46af43f35335ac4ac2c7dae462
Author: Benoit TELLIER <[email protected]>
AuthorDate: Mon Aug 24 19:11:48 2026 +0700
[DOC] Refresh james benchmark (#3136)
---
.../distributed/benchmark/james-benchmark.adoc | 1 -
.../pages/postgres/benchmark/james-benchmark.adoc | 1 -
.../partials/benchmark/james-benchmark.adoc | 136 ++++++++++++++++-----
3 files changed, 103 insertions(+), 35 deletions(-)
diff --git
a/docs/modules/servers/pages/distributed/benchmark/james-benchmark.adoc
b/docs/modules/servers/pages/distributed/benchmark/james-benchmark.adoc
index fe5d0b7579..6aca3baf49 100644
--- a/docs/modules/servers/pages/distributed/benchmark/james-benchmark.adoc
+++ b/docs/modules/servers/pages/distributed/benchmark/james-benchmark.adoc
@@ -3,7 +3,6 @@
:server-name: Distributed James Server
:backend-database-extend-sample: Apache Cassandra 4 as main database: 3 nodes,
each node has 8 OVH vCores CPU and 30 GB memory limit (OVH b2-30 instance).
-:provision_file_url:
https://github.com/apache/james-project/tree/master/docs/modules/servers/pages/distributed/benchmark/provision.sh
:benchmark_prepare_extend: servers:distributed/benchmark/benchmark_prepare.adoc
:james-imap-base-performance-picture:
james-imap-base-performance-distributed.png
diff --git a/docs/modules/servers/pages/postgres/benchmark/james-benchmark.adoc
b/docs/modules/servers/pages/postgres/benchmark/james-benchmark.adoc
index 52bdec9769..d1ce0e0023 100644
--- a/docs/modules/servers/pages/postgres/benchmark/james-benchmark.adoc
+++ b/docs/modules/servers/pages/postgres/benchmark/james-benchmark.adoc
@@ -3,7 +3,6 @@
:server-name: Postgresql James server
:backend-database-extend-sample: PostgreSQL 16 as main database: 1 nodes (OVH
instance, 2 CPU / 7 GB RAM, 160 GB SSD)
-:provision_file_url:
https://github.com/apache/james-project/blob/d8225ed7c5ca8d79cde3b1c8755ee9ffcf462e29/server/apps/postgres-app/provision.sh
:benchmark_prepare_extend: servers:postgres/benchmark/benchmark_prepare.adoc
:james-imap-base-performance-picture: james-imap-base-performance-postgres.png
diff --git a/docs/modules/servers/partials/benchmark/james-benchmark.adoc
b/docs/modules/servers/partials/benchmark/james-benchmark.adoc
index 39ac7dd1c8..8afd0a0be4 100644
--- a/docs/modules/servers/partials/benchmark/james-benchmark.adoc
+++ b/docs/modules/servers/partials/benchmark/james-benchmark.adoc
@@ -28,70 +28,140 @@ include::{benchmark_prepare_extend}[]
Before doing the performance test, you should make sure you have a
{server-name} up and running with some provisioned testing
data so that it is representative of reality.
-Please follow these steps to provision testing data:
+We provision that data over IMAP with the `james-provisioning` tool: it
creates mailboxes and appends messages into
+**already existing** accounts. Message sizes follow a predefined distribution
(1% carry a 10 MB attachment, 4% a 5 MB one,
+5% a 1 MB one, 10% a 500 KB one, the rest are small sized), which averages
roughly 400 KB per message.
-* Prepare James with a custom `mailetcontainer.xml` having Random storing
mailet. This help us easily setting a good amount of
-provisioned emails.
+==== Create the test users
-Add this under transport processor
+The provisioning tool does not create accounts: create them first with
WebAdmin, and record their credentials in a CSV
+file (one `username,password` per line) that both the provisioning tool and
Gatling will later reuse.
-[source,xml]
-----
-<mailet match="All" class="RandomStoring"/>
-----
-
-* Modify {provision_file_url}[provision.sh]
-upon your need (number of users, mailboxes, emails to be provisioned).
+Retrieve the generated WebAdmin password from the James startup logs and
expose it to your shell. Omit this variable
+only when WebAdmin password authentication is explicitly disabled:
-Currently, this script provisions 10 users, 15 mailboxes and hundreds of
emails for example. Normally to make the performance test representative, you
-should provision thousands of users, thousands of mailboxes and millions of
emails.
-
-* Add the permission to execute the script:
----
-chmod +x provision.sh
+export WEBADMIN_PASSWORD="replace-with-generated-webadmin-password"
----
-* Install postfix (to get the smtp-source command):
+[source,bash]
----
-sudo apt-get install postfix
+WEBADMIN_BASE_URL="http://localhost:8000";
+DOMAIN_NAME="domain.org"
+USERS_COUNT=1000
+
+curl --fail --header "Password: ${WEBADMIN_PASSWORD}" -XPUT
${WEBADMIN_BASE_URL}/domains/${DOMAIN_NAME}
+
+for i in $(seq 1 $USERS_COUNT); do
+ username=user${i}@${DOMAIN_NAME}
+ curl --fail --header "Password: ${WEBADMIN_PASSWORD}" -XPUT
${WEBADMIN_BASE_URL}/users/${username} \
+ -d '{"password":"secret"}' -H "Content-Type: application/json"
+ echo "${username},secret" >> users.csv
+done
----
-* Retrieve the generated WebAdmin password from the James startup logs and
expose it to the provisioning script:
+Normally, to make the performance test representative, you should provision
thousands of users, thousands of mailboxes
+and millions of emails.
+
+==== Run the provisioning
+
+Adapt `provisioning.properties` upon your need (URL of the server, number of
mailboxes and emails to be provisioned,
+concurrency):
+
+[source,properties]
----
-export WEBADMIN_PASSWORD="replace-with-generated-webadmin-password"
+# IMAP(S) URL of the James server. Certificates are blindly trusted
+url=imaps://localhost:993
+
+# Count of mailboxes to create per user
+mailbox.count=4
+# Count of messages to create per folder
+message.per.folder.count=5
+# Count of messages to create in INBOX
+message.inbox.count=5
+
+# Count of threads of the IMAP client
+thread.count=8
+# Concurrent count of users to provision simultaneously
+concurrent.user.count=10
+# Connections to use per user
+connection.per.user.count=2
+# Read timeout of IMAP connections
+read.timeout.ms=180000
+# Connect timeout
+connect.timeout.ms=30000
+
+# Count of users to offset (ignore) in the provisioning
+users.offset=0
+# Count of users to provision
+# users.limit=100
----
-Omit this variable only when WebAdmin password authentication is explicitly
disabled.
+`provisioning.properties` and `users.csv` are read from the working directory
of the container (`/provisioning`), so
+both are meant to be mounted:
-* Run the provision script:
----
-./provision.sh
+docker run --rm --network host \
+ -v $PWD/provisioning.properties:/provisioning/provisioning.properties:ro \
+ -v $PWD/users.csv:/provisioning/users.csv:ro \
+ linagora/james-provisioning:latest
----
-After provisioning once, you should remove the Random storing mailet and move
on to performance testing phase.
+JVM options can be passed through `JAVA_TOOL_OPTIONS`, for instance `-e
JAVA_TOOL_OPTIONS=-Xmx2g`.
=== Provide performance testing method
We introduce the tailored https://github.com/linagora/james-gatling[James
Gatling] which bases on https://gatling.io/[Gatling - Load testing framework]
for performance testing against IMAP/JMAP servers. Other testing method is
welcome as long as you feel it is appropriate.
-Here are steps to do performance testing with James Gatling:
+The easiest way to run it is its Docker packaging, which ships the simulations
along with their `sbt` toolchain.
+
+* Get the runner image, either from Docker Hub:
+
+----
+docker pull linagora/james-gatling-runner:branch-master
+----
+
+Or build it from the sources of
https://github.com/linagora/james-gatling[James Gatling] - the build context is
the
+root of the project, so that the image ships the code being built:
+
+----
+docker build -f dockerfiles/docker-runner/Dockerfile -t james-gatling-runner .
+----
+
+* Point the runner to your {server-name} IMAP/JMAP server(s) with an
environment file. Start from the `sample.env` of the
+project:
+
+[source,properties]
+----
+IMAP_SERVER_HOSTNAME=james.example.com
+IMAP_PORT=993
+IMAP_PROTOCOL=imaps
+
+# Count of virtual users, and injection duration in minutes
+USER_COUNT=1000
+DURATION=60
+# Force the run to terminate after that many minutes, even if some virtual
users are still running
+MAX_DURATION=120
+----
-* Setup James Gatling with `sbt` build tool
+* Supply the test users: reuse the `users.csv` written when provisioning,
prepending the `username,password` header line
+that Gatling expects.
-* Configure the `Configuration.scala` to point to your {server-name} IMAP/JMAP
server(s). For more configuration details, please read
-https://github.com/linagora/james-gatling#readme[James Gatling Readme].
+* Run a simulation. Mounting `target/gatling` keeps the generated HTML reports
on your host once the container exits:
-* Run the performance testing simulation:
----
-$ sbt
-> gatling:testOnly SIMULATION_FQDN
+docker run --env-file sample.env \
+ --mount
type=bind,source="$(pwd)"/users.csv,target=/home/sbtuser/james-gatling/src/test/resources/users.csv
\
+ --mount
type=bind,source="$(pwd)"/results,target=/home/sbtuser/james-gatling/target/gatling
\
+ -it --rm linagora/james-gatling-runner:branch-master SIMULATION_FQDN
----
-In there: `SIMULATION_FQDN` is fully qualified class name of a performance
test simulation.
+In there: `SIMULATION_FQDN` is fully qualified class name of a performance
test simulation. Omitting it drops you into an
+`sbt` prompt inside the container, from which you can run `gatling:testOnly
SIMULATION_FQDN` interactively.
We did provide a lot of simulations in `org.apache.james.gatling.simulation`
path. You can have a look and choose the suitable simulation.
-`sbt gatling:testOnly
org.apache.james.gatling.simulation.imap.PlatformValidationSimulation` is a
good starting point. Or you can even customize your simulation also!
+`org.apache.james.gatling.simulation.imap.PlatformValidationSimulation` is a
good starting point. Or you can even customize your simulation also!
Some symbolic simulations we often use:
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
