You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by rc...@apache.org on 2024/07/08 04:13:19 UTC
(james-project) 01/02: [Antora] Add run section to postgresql documentation
This is an automated email from the ASF dual-hosted git repository.
rcordier pushed a commit to branch postgresql
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 0813d672c3cb32cbec3a89e31cb11a64a8796a38
Author: Rene Cordier <rc...@linagora.com>
AuthorDate: Fri Jun 28 14:54:16 2024 +0700
[Antora] Add run section to postgresql documentation
---
docs/modules/servers/nav.adoc | 2 +
docs/modules/servers/pages/postgres/index.adoc | 1 +
docs/modules/servers/pages/postgres/run/index.adoc | 16 ++-
.../servers/pages/postgres/run/run-docker.adoc | 145 +++++++++++++++++++++
.../servers/pages/postgres/run/run-java.adoc | 108 +++++++++++++++
5 files changed, 270 insertions(+), 2 deletions(-)
diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc
index bacba697e4..8ce2a0e664 100644
--- a/docs/modules/servers/nav.adoc
+++ b/docs/modules/servers/nav.adoc
@@ -90,6 +90,8 @@
**** xref:postgres/architecture/consistency-model.adoc[]
**** xref:postgres/architecture/specialized-instances.adoc[]
*** xref:postgres/run/index.adoc[]
+**** xref:postgres/run/run-java.adoc[Run with Java]
+**** xref:postgres/run/run-docker.adoc[Run with Docker]
*** xref:postgres/configure/index.adoc[]
**** Protocols
***** xref:postgres/configure/imap.adoc[imapserver.xml]
diff --git a/docs/modules/servers/pages/postgres/index.adoc b/docs/modules/servers/pages/postgres/index.adoc
index cf59a011f2..b3a8b8416f 100644
--- a/docs/modules/servers/pages/postgres/index.adoc
+++ b/docs/modules/servers/pages/postgres/index.adoc
@@ -12,3 +12,4 @@ with various storage and search solutions
In this section of the documentation, we will introduce you to:
* xref:postgres/objectives.adoc[Objectives and motivation of the Distributed Postgres Server]
+* xref:postgres/run/index.adoc[Run the Postgresql Server]
\ No newline at end of file
diff --git a/docs/modules/servers/pages/postgres/run/index.adoc b/docs/modules/servers/pages/postgres/run/index.adoc
index 3f9a101266..5b2eb99801 100644
--- a/docs/modules/servers/pages/postgres/run/index.adoc
+++ b/docs/modules/servers/pages/postgres/run/index.adoc
@@ -1,2 +1,14 @@
-= Distributed James Postgres Server — Run
-:navtitle: Run
\ No newline at end of file
+= Postgresql James Server — Run
+:navtitle: Run
+
+This sections presents guidance to all current deployment types of Postgresql James Server.
+
+== Run with Java
+
+Build your own Apache James Postgresql artifacts and start xref:postgres/run/run-java.adoc[Running it directly on a Java Virtual Machine].
+
+== Run with Docker
+
+We have prepared a docker-compose for Apache James to run with Postgresql & OpenSearch.
+
+You can start xref:postgres/run/run-docker.adoc[Running James with few simple Docker commands].
\ No newline at end of file
diff --git a/docs/modules/servers/pages/postgres/run/run-docker.adoc b/docs/modules/servers/pages/postgres/run/run-docker.adoc
new file mode 100644
index 0000000000..bb0204959a
--- /dev/null
+++ b/docs/modules/servers/pages/postgres/run/run-docker.adoc
@@ -0,0 +1,145 @@
+= Postgresql James Server — Run with docker
+:navtitle: Run with docker
+
+== Running via docker-compose
+
+Requirements: docker & docker-compose installed.
+
+When you try James this way, you will use the most current state of James.
+
+=== Running with Postgresql only
+
+It will be configured to run with Postgresql.
+All those components will be started with a single command.
+
+You can retrieve the docker-compose file : ( docker-compose file and james image name should be changed)
+
+ $ wget https://raw.githubusercontent.com/apache/james-project/master/server/apps/postgres-app/docker-compose.yml
+
+
+Then, you just have to start the services:
+
+ $ docker-compose up -d
+
+Wait a few seconds in order to have all those services start up. You will see the following log when James is available:
+james | Started : true
+
+A default domain, james.local, has been created. You can see this by running:
+
+ $ docker exec james james-cli -h 127.0.0.1 -p 9999 listdomains
+
+James will respond to IMAP port 143 and SMTP port 25.
+You have to create users before playing with james. You may also want to create other domains.
+Follow the 'Useful commands' section for more information about James CLI.
+
+=== Running distributed James
+
+We also have a distributed version of the James postgresql app with:
+
+* OpenSearch as a search indexer
+* S3 as the object storage
+* RabbitMQ as the event bus
+
+To run it, simply type:
+
+ $ docker compose -f docker-compose-distributed.yml up -d
+
+== Run with docker
+
+=== Requirements
+
+Compile the whole project:
+
+ mvn clean install -DskipTests -T 4
+
+Then load the James Postgresql server docker image:
+
+ docker load -i server/apps/postgres-app/target/jib-image.tar
+
+Alternatively we provide convenience distribution for the latest release:
+
+ docker pull apache/james:postgres-3.9.0
+
+=== Running with Postgresql only
+
+Firstly, create your own user network on Docker for the James environment:
+
+ $ docker network create --driver bridge james
+
+You need a running *Postgresql* in docker which connects to *james* network. To achieve this run:
+
+ $ docker run -d --network james --name=postgres --env 'POSTGRES_DB=james' --env 'POSTGRES_USER=james' --env 'POSTGRES_PASSWORD=secret1' postgres:16.0
+
+To run this container :
+
+ $ docker run --network james --hostname HOSTNAME -p "25:25" -p 80:80 -p "110:110" -p "143:143" -p "465:465" -p "587:587" -p "993:993" -p "127.0.0.1:8000:8000" --name james_run
+ -v $PWD/keystore:/root/conf/keystore -t apache/james:postgres-3.9.0 --generate-keystore
+
+Where :
+
+- HOSTNAME: is the hostname you want to give to your James container. This DNS entry will be used to send mail to your James server.
+
+Webadmin port binding is restricted to loopback as users are not authenticated by default on webadmin server. Thus you should avoid exposing it in production.
+Note that the above example assumes `127.0.0.1` is your loopback interface for convenience but you should change it if this is not the case on your machine.
+
+If you want to pass additional options to the underlying java command, you can configure a _JAVA_TOOL_OPTIONS_ env variable, for example add:
+
+ --env "JAVA_TOOL_OPTIONS=-Xms256m -Xmx2048m"
+
+To have log file accessible on a volume, add *-v $PWD/logs:/logs* option to the above command line, where *$PWD/logs* is your local directory to put files in.
+
+=== Running distributed
+
+Same as above, except that you need to run before James instances of RabbitMQ, S3 object storage and Opensearch.
+
+You need a running *rabbitmq* in docker which connects to *james* network. To achieve this run:
+
+ $ docker run -d --network james --name=rabbitmq rabbitmq:3.13.3-management
+
+You need a running *Zenko Cloudserver* objectstorage in docker which connects to *james* network. To achieve this run:
+
+ $ docker run -d --network james --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
+
+You need a running *OpenSearch* in docker which connects to *james* network. To achieve this run:
+
+$ docker run -d --network james -p 9200:9200 --name=opensearch --env 'discovery.type=single-node' opensearchproject/opensearch:2.14.0
+
+Then run James like in the section above.
+
+=== Specific keystore
+
+Alternatively, you can also generate a keystore in your conf folder with the
+following command, and drop `--generate-keystore` option:
+
+[source,bash]
+----
+$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
+----
+
+=== Instrumentation
+You can use link:https://glowroot.org/[Glowroot] to instrumentalize James. It is packaged as part of the docker distribution to easily enable valuable performances insights.
+Disabled by default, its java agent can easily be enabled:
+
+ --env "JAVA_TOOL_OPTIONS=-javaagent:/root/glowroot.jar" -p "4000:4000"
+
+By default, the Glowroot UI is accessible from every machines in the network as defined in the _destination/admin.json_.
+Which you could configure before building the image, if you want to restrict its accessibility to localhost for example.
+See the https://github.com/glowroot/glowroot/wiki/Agent-Installation-(with-Embedded-Collector)#user-content-optional-post-installation-steps[Glowroot post installation steps] for more details.
+
+Or by mapping the 4000 port to the IP of the desired network interface, for example `-p 127.0.0.1:4000:4000`.
+
+
+=== Handling attachment indexing
+
+You can handle attachment text extraction before indexing in OpenSearch. This makes attachments searchable. To enable this:
+
+Run tika connect to *james* network:
+
+ $ docker run -d --network james --name tika apache/tika:2.9.2.1
+
+Run James:
+
+ $ docker run --network james --hostname HOSTNAME -p "25:25" -p 80:80 -p "110:110" -p "143:143" -p "465:465" -p "587:587" -p "993:993" -p "127.0.0.1:8000:8000"
+ --name james_run -v $PWD/keystore:/root/conf/keystore -t apache/james:postgres-latest
+
+You can find more explanation on the need of Tika in this xref:postgres/configure/tika.adoc[page].
diff --git a/docs/modules/servers/pages/postgres/run/run-java.adoc b/docs/modules/servers/pages/postgres/run/run-java.adoc
new file mode 100644
index 0000000000..5cd113b874
--- /dev/null
+++ b/docs/modules/servers/pages/postgres/run/run-java.adoc
@@ -0,0 +1,108 @@
+= Postgresql James Server — Run
+:navtitle: Run
+
+== Building
+
+=== Requirements
+
+* Java 21 SDK
+* Maven 3
+
+=== Building the artifacts
+
+An usual compilation using maven will produce two artifacts into
+server/apps/postgres-app/target directory:
+
+* james-server-postgres-app.jar
+* james-server-postgres-app.lib
+
+You can for example run in the base of
+https://github.com/apache/james-project[this git repository]:
+
+....
+mvn clean install
+....
+
+== Running
+
+=== Running James with Postgresql only
+
+==== Requirements
+
+* Postgresql 16.0+
+
+==== James launch
+
+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 https://github.com/apache/james-project/tree/master/server/apps/postgres-app/sample-configuration[sample directory]
+is provided with some default values you may need to replace. You will need to update its content to match your needs.
+
+Also you might need to add the files like in the
+https://github.com/apache/james-project/tree/master/server/apps/postgres-app/sample-configuration-single[sample directory]
+to not have OpenSearch indexing enabled by default for the search.
+
+You need to have a Postgresql instance running. You can either install the server or launch it via docker:
+
+[source,bash]
+----
+$ docker run -d --network james -p 5432:5432 --name=postgres --env 'POSTGRES_DB=james' --env 'POSTGRES_USER=james' --env 'POSTGRES_PASSWORD=secret1' postgres:16.0
+----
+
+Once everything is set up, you just have to run the jar with:
+
+[source,bash]
+----
+$ java -Dworking.directory=. -jar target/james-server-postgres-app.jar --generate-keystore
+----
+
+Alternatively, you can also generate a keystore in your conf folder with the
+following command, and drop `--generate-keystore` option:
+
+[source,bash]
+----
+$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore
+----
+
+=== Running distributed James
+
+==== Requirements
+
+* Postgresql 16.0+
+* OpenSearch 2.1.0+
+* RabbitMQ-Management 3.8.17+
+* Swift ObjectStorage 2.15.1+ or Zenko Cloudserver or AWS S3
+
+==== James Launch
+
+If you want to use the distributed version of James Postgres app, you will need to add configuration in the conf folder
+like in the https://github.com/apache/james-project/tree/master/server/apps/postgres-app/sample-configuration-distributed[sample directory].
+
+You need to have a Postgresql, OpenSearch, S3 and RabbitMQ instance
+running. You can either install the servers or launch them via docker:
+
+[source,bash]
+----
+$ docker run -d --network james -p 5432:5432 --name=postgres --env 'POSTGRES_DB=james' --env 'POSTGRES_USER=james' --env 'POSTGRES_PASSWORD=secret1' postgres:16.0
+$ docker run -d --network james -p 9200:9200 --name=opensearch --env 'discovery.type=single-node' opensearchproject/opensearch:2.14.0
+$ docker run -d -p 5672:5672 -p 15672:15672 --name=rabbitmq rabbitmq:3.13.3-management
+$ docker run -d --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
+----
+
+Once everything is set up, you just have to run the jar like in the with Postgresql only section.
+
+==== Using AWS S3 of Zenko Cloudserver
+
+By default, James is configured with [Zenko Cloudserver](https://hub.docker.com/r/zenko/cloudserver) which is compatible with AWS S3, in `blobstore.propeties` as such:
+
+[source,bash]
+----
+implementation=s3
+objectstorage.namespace=james
+objectstorage.s3.endPoint=http://s3.docker.test:8000/
+objectstorage.s3.region=eu-west-1
+objectstorage.s3.accessKeyId=accessKey1
+objectstorage.s3.secretKey=secretKey1
+----
\ No newline at end of file
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org