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
commit 17bf4d1bfe4f766bcebc98936c5c16d846ce2e6d Author: Benoit TELLIER <[email protected]> AuthorDate: Fri Aug 28 13:06:24 2026 +0700 [DOC] JPA server Antora documentation --- .../james-hexagons-extensions-jpa.png | Bin 0 -> 37501 bytes .../servers/assets/images/storage_james_jpa.png | Bin 0 -> 121613 bytes docs/modules/servers/nav.adoc | 57 ++++++ docs/modules/servers/pages/index.adoc | 14 +- .../jpa/architecture/implemented-standards.adoc | 10 ++ .../servers/pages/jpa/architecture/index.adoc | 196 +++++++++++++++++++++ .../pages/jpa/configure/collecting-contacts.adoc | 13 ++ .../pages/jpa/configure/collecting-events.adoc | 13 ++ .../servers/pages/jpa/configure/database.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/dns.adoc | 13 ++ .../servers/pages/jpa/configure/domainlist.adoc | 13 ++ .../servers/pages/jpa/configure/droplists.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/dsn.adoc | 13 ++ .../servers/pages/jpa/configure/extensions.adoc | 13 ++ .../servers/pages/jpa/configure/healthcheck.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/imap.adoc | 13 ++ .../modules/servers/pages/jpa/configure/index.adoc | 38 ++++ docs/modules/servers/pages/jpa/configure/jmx.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/jvm.adoc | 18 ++ .../servers/pages/jpa/configure/kerberos.adoc | 13 ++ .../servers/pages/jpa/configure/listeners.adoc | 15 ++ .../pages/jpa/configure/mailetcontainer.adoc | 13 ++ .../servers/pages/jpa/configure/mailets.adoc | 18 ++ .../pages/jpa/configure/mailrepositorystore.adoc | 21 +++ .../servers/pages/jpa/configure/matchers.adoc | 16 ++ .../servers/pages/jpa/configure/mta-sts.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/oidc.adoc | 15 ++ docs/modules/servers/pages/jpa/configure/pop3.adoc | 13 ++ .../pages/jpa/configure/recipientrewritetable.adoc | 13 ++ .../configure/remote-delivery-error-handling.adoc | 15 ++ .../servers/pages/jpa/configure/server.adoc | 13 ++ .../modules/servers/pages/jpa/configure/sieve.adoc | 13 ++ .../servers/pages/jpa/configure/smtp-hooks.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/smtp.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/spam.adoc | 13 ++ docs/modules/servers/pages/jpa/configure/ssl.adoc | 13 ++ .../pages/jpa/configure/usersrepository.adoc | 13 ++ .../servers/pages/jpa/configure/webadmin.adoc | 14 ++ .../servers/pages/jpa/customization/imap.adoc | 9 + .../servers/pages/jpa/customization/index.adoc | 10 ++ .../pages/jpa/customization/mail-processing.adoc | 9 + .../pages/jpa/customization/mailbox-listeners.adoc | 9 + .../pages/jpa/customization/smtp-hooks.adoc | 9 + .../pages/jpa/customization/webadmin-routes.adoc | 9 + docs/modules/servers/pages/jpa/index.adoc | 61 +++++++ docs/modules/servers/pages/jpa/operate/cli.adoc | 9 + docs/modules/servers/pages/jpa/operate/guide.adoc | 45 +++++ docs/modules/servers/pages/jpa/operate/index.adoc | 11 ++ .../modules/servers/pages/jpa/operate/logging.adoc | 11 ++ .../modules/servers/pages/jpa/operate/metrics.adoc | 15 ++ .../servers/pages/jpa/operate/migrating.adoc | 13 ++ .../pages/jpa/operate/performanceChecklist.adoc | 79 +++++++++ .../servers/pages/jpa/operate/security.adoc | 12 ++ .../servers/pages/jpa/operate/webadmin.adoc | 30 ++++ .../operate/webadmin/admin-mail-queues-extend.adoc | 1 + .../operate/webadmin/admin-mailboxes-extend.adoc | 1 + .../operate/webadmin/admin-messages-extend.adoc | 1 + docs/modules/servers/pages/jpa/run/index.adoc | 17 ++ docs/modules/servers/pages/jpa/run/run-docker.adoc | 93 ++++++++++ docs/modules/servers/pages/jpa/run/run-java.adoc | 66 +++++++ .../architecture/implemented-standards.adoc | 10 ++ .../servers/partials/configure/database.adoc | 112 ++++++++++++ .../configure/forCoreComponentsPartial.adoc | 18 +- .../partials/configure/forExtensionsPartial.adoc | 8 +- .../partials/configure/forProtocolsPartial.adoc | 18 +- .../configure/forStorageDependenciesPartial.adoc | 8 +- docs/modules/servers/partials/configure/jvm.adoc | 12 ++ .../servers/partials/configure/listeners.adoc | 3 +- .../servers/partials/configure/mailets.adoc | 14 ++ .../partials/configure/mailrepositorystore.adoc | 5 + .../servers/partials/configure/matchers.adoc | 6 + docs/modules/servers/partials/configure/oidc.adoc | 2 + .../configure/remote-delivery-error-handling.adoc | 6 + .../servers/partials/customization/index.adoc | 5 + docs/modules/servers/partials/jpa/deprecated.adoc | 10 ++ docs/modules/servers/partials/operate/guide.adoc | 7 + docs/modules/servers/partials/operate/index.adoc | 2 + docs/modules/servers/partials/operate/metrics.adoc | 12 ++ .../modules/servers/partials/operate/security.adoc | 9 + .../modules/servers/partials/operate/webadmin.adoc | 40 +++++ docs/ui-overrides/partials/head-styles.hbs | 16 ++ 81 files changed, 1564 insertions(+), 25 deletions(-) diff --git a/docs/modules/servers/assets/images/customization/james-hexagons-extensions-jpa.png b/docs/modules/servers/assets/images/customization/james-hexagons-extensions-jpa.png new file mode 100644 index 0000000000..5422c88f1f Binary files /dev/null and b/docs/modules/servers/assets/images/customization/james-hexagons-extensions-jpa.png differ diff --git a/docs/modules/servers/assets/images/storage_james_jpa.png b/docs/modules/servers/assets/images/storage_james_jpa.png new file mode 100644 index 0000000000..91ce657160 Binary files /dev/null and b/docs/modules/servers/assets/images/storage_james_jpa.png differ diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 222eadc0a7..90a755b8d1 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -142,4 +142,61 @@ *** xref:postgres/benchmark/index.adoc[] **** xref:postgres/benchmark/db-benchmark.adoc[] **** xref:postgres/benchmark/james-benchmark.adoc[] +** xref:jpa/index.adoc[] +*** xref:jpa/architecture/index.adoc[] +**** xref:jpa/architecture/implemented-standards.adoc[] +*** xref:jpa/run/index.adoc[] +**** xref:jpa/run/run-java.adoc[Run with Java] +**** xref:jpa/run/run-docker.adoc[Run with Docker] +*** xref:jpa/configure/index.adoc[] +**** Protocols +***** xref:jpa/configure/server.adoc[Common Server Configuration] +***** xref:jpa/configure/oidc.adoc[OIDC Configuration] +***** xref:jpa/configure/kerberos.adoc[Kerberos GSSAPI Configuration] +***** xref:jpa/configure/imap.adoc[imapserver.xml] +***** xref:jpa/configure/jmx.adoc[jmx.properties] +***** xref:jpa/configure/smtp.adoc[smtpserver.xml & lmtpserver.xml] +***** xref:jpa/configure/smtp-hooks.adoc[Packaged SMTP hooks] +***** xref:jpa/configure/pop3.adoc[pop3server.xml] +***** xref:jpa/configure/webadmin.adoc[webadmin.properties] +***** xref:jpa/configure/ssl.adoc[SSL & TLS] +***** xref:jpa/configure/sieve.adoc[Sieve & ManageSieve] +**** Storage dependencies +***** xref:jpa/configure/database.adoc[james-database.properties] +**** Core components +***** xref:jpa/configure/dns.adoc[dnsservice.xml] +***** xref:jpa/configure/domainlist.adoc[domainlist.xml] +***** xref:jpa/configure/droplists.adoc[DropLists] +***** xref:jpa/configure/healthcheck.adoc[healthcheck.properties] +***** xref:jpa/configure/mailetcontainer.adoc[mailetcontainer.xml] +***** xref:jpa/configure/mailets.adoc[Packaged Mailets] +***** xref:jpa/configure/matchers.adoc[Packaged Matchers] +***** xref:jpa/configure/mailrepositorystore.adoc[mailrepositorystore.xml] +***** xref:jpa/configure/recipientrewritetable.adoc[recipientrewritetable.xml] +***** xref:jpa/configure/usersrepository.adoc[usersrepository.xml] +**** Extensions +***** xref:jpa/configure/extensions.adoc[extensions.properties] +***** xref:jpa/configure/listeners.adoc[listeners.xml] +***** xref:jpa/configure/jvm.adoc[jvm.properties] +***** xref:jpa/configure/spam.adoc[Anti-Spam setup] +***** xref:jpa/configure/remote-delivery-error-handling.adoc[About RemoteDelivery error handling] +***** xref:jpa/configure/collecting-contacts.adoc[Contact collection] +***** xref:jpa/configure/collecting-events.adoc[Event collection] +***** xref:jpa/configure/dsn.adoc[ESMTP DSN support] +***** xref:jpa/configure/mta-sts.adoc[MTA-STS] +*** xref:jpa/operate/index.adoc[Operate] +**** xref:jpa/operate/guide.adoc[] +**** xref:jpa/operate/performanceChecklist.adoc[] +**** xref:jpa/operate/logging.adoc[] +**** xref:jpa/operate/webadmin.adoc[] +**** xref:jpa/operate/metrics.adoc[] +**** xref:jpa/operate/migrating.adoc[] +**** xref:jpa/operate/cli.adoc[] +**** xref:jpa/operate/security.adoc[] +*** xref:jpa/customization/index.adoc[] +**** xref:jpa/customization/imap.adoc[] +**** xref:jpa/customization/mail-processing.adoc[] +**** xref:jpa/customization/mailbox-listeners.adoc[] +**** xref:jpa/customization/smtp-hooks.adoc[] +**** xref:jpa/customization/webadmin-routes.adoc[] ** xref:test.adoc[] diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 351dfa53ff..d0b69b746e 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -1,7 +1,7 @@ = Apache James Mail Servers :navtitle: Servers -James offers four types of ready-made Mail Servers. The servers are intended +James offers five types of ready-made Mail Servers. The servers are intended for those with different needs, ranging from Operators who are interested in setting up a server for the first time, to experienced teams of Developers @@ -15,6 +15,7 @@ The available James Servers are: * <<demo,James Demo Mail Server>> * <<distributed,James Distributed Mail Server>> * <<postgres,James Postgres Mail Server>> + * <<jpa,James JPA Mail Server>> (deprecated) * <<test,James Test Server>> If you are just checking out James for the first time, then we highly recommend @@ -50,6 +51,17 @@ variant of the distributed server with Postgres as the database. +[#jpa] +== James JPA Mail Server + +The xref:jpa/index.adoc[*JPA Server*] is a single node server storing all its data within a +relational database, accessed through JPA. + +*It is deprecated*: it is not actively maintained anymore, lacks major James features, and may be removed in a +future release. Use the <<postgres,Postgres Server>> instead. + + + [#test] == James Test Server diff --git a/docs/modules/servers/pages/jpa/architecture/implemented-standards.adoc b/docs/modules/servers/pages/jpa/architecture/implemented-standards.adoc new file mode 100644 index 0000000000..8a36870480 --- /dev/null +++ b/docs/modules/servers/pages/jpa/architecture/implemented-standards.adoc @@ -0,0 +1,10 @@ += JPA James Server — Implemented standards +:navtitle: Implemented standards + +:server-name: JPA James server +:no-jmap: +:no-acl: + +include::partial$jpa/deprecated.adoc[] + +include::partial$architecture/implemented-standards.adoc[] diff --git a/docs/modules/servers/pages/jpa/architecture/index.adoc b/docs/modules/servers/pages/jpa/architecture/index.adoc new file mode 100644 index 0000000000..8181bd1063 --- /dev/null +++ b/docs/modules/servers/pages/jpa/architecture/index.adoc @@ -0,0 +1,196 @@ += JPA James Server — Architecture +:navtitle: Architecture + +:server-name: JPA James server +:backend-name: the database +:xref-base: jpa +:pages-path: jpa +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +This section presents the {server-name} architecture. + +== Storage + +The {server-name} is a single node deployment, and leverages the following storage strategies: + +image::storage_james_jpa.png[Storage responsibilities for the {server-name}] + +* A *relational database*, accessed through JDBC and JPA, holds all the structured data: domains, users, +recipient rewriting rules, Sieve scripts, mailboxes, message metadata as well as message content. +* The *local file system* backs the Lucene full text search index, the ActiveMQ mail queue and the file mail +repositories. +* *link:https://spamassassin.apache.org/[SpamAssassin] or link:https://rspamd.com/[Rspamd]* (optional) can be +used for Spam detection, and user feedback is supported. + +Unlike the xref:distributed/index.adoc[Distributed] and xref:postgres/index.adoc[Postgres] servers, there is no +BlobStore: message headers and bodies are stored within the database itself, and no object storage can be +plugged in. + +== Protocols + +The following protocols are supported and can be used to interact with the {server-name}: + +* *SMTP* +* *IMAP* +* xref:{xref-base}/operate/webadmin.adoc[WebAdmin] REST Administration API +* *LMTP* +* *POP3* + +The following protocol should be considered experimental: + +* *ManagedSieve* + +*JMAP is not supported* by this application. + +Read more on xref:{xref-base}/architecture/implemented-standards.adoc[implemented standards]. + +== Components + +This section presents the various components of the {server-name}, providing context about their interactions, +and about their implementations. + +=== High level view + +Here is a high level view of the various server components and their interactions: + +image::server-components.png[Server components mobilized for SMTP & IMAP] + +* The SMTP protocol receives a mail, and enqueues it on the MailQueue. +* The MailetContainer will start processing the mail asynchronously and will take business decisions like storing +the email locally in a user mailbox. The behaviour of the MailetContainer is highly customizable thanks to the +Mailets and the Matchers composability. +* The Mailbox component is responsible for storing a user's mails. +* The user can use the IMAP or the POP3 protocol to retrieve and read his mails. + +These components are presented more in depth below. + +=== Mail processing + +Mail processing allows to take asynchronously business decisions on received emails. + +Here are its components: + +* The `spooler` takes mail out of the mailQueue and executes mail processing within the `mailet container`. +* The `mailet container` synchronously executes the user defined logic. This 'logic' is written through the use +of `mailet`, `matcher` and `processor`. +* A `mailet` represents an action: mail modification, envelop modification, a side effect, or stop processing. +* A `matcher` represents a condition to execute a mailet. +* A `processor` is a flow of pair of `matcher` and `mailet` executed sequentially. The `ToProcessor` mailet is a +`goto` instruction to start executing another `processor`. +* A `mail repository` allows storage of a mail as part of its processing. The default configuration relies on the +`file` protocol, thus storing those mails on the local file system: +** `{mailet-repository-path-prefix}://var/mail/error/` : unexpected errors that occurred during mail processing. +Emails impacted by performance related exceptions, or logical bug within James code are typically stored here. +These mails could be reprocessed once the cause of the error is fixed. The `Mail.error` field can help diagnose +the issue. Correlation with logs can be achieved via the use of the `Mail.name` field. +** `{mailet-repository-path-prefix}://var/mail/address-error/` : mail addressed to a non-existing recipient of a +handled local domain. These mails could be reprocessed once the user is created, for instance. +** `{mailet-repository-path-prefix}://var/mail/relay-denied/` : mail for whom relay was denied: missing +authentication can, for instance, be a cause. In addition to prevent disasters upon miss configuration, an email +review of this mail repository can help refine a host spammer blacklist. +** `{mailet-repository-path-prefix}://var/mail/rrt-error/` : runtime error upon Recipient Rewriting occurred. +This is typically due to a loop. + +Read more about xref:{xref-base}/configure/mailetcontainer.adoc[mail processing configuration]. + +=== Mail Queue + +An email queue is a mandatory component of SMTP servers. It decouples email reception from email processing: +queued emails wait for processing until the recipient is available to receive them. + +The {server-name} relies on an *embedded ActiveMQ broker*, persisting its data on the local file system. As a +consequence the mail queue is not shared between James instances, and mails enqueued on a node can only be +processed by that same node. + +Delays are supported, which allows exponential wait delays upon remote delivery retries. + +=== Mailbox + +Storage for emails belonging to users. + +Metadata, headers and bodies are all stored within the database. Attachments are stored in the database as well, +provided `attachmentStorage.enabled` is set within +xref:{xref-base}/configure/database.adoc[james-database.properties]. + +==== Search index + +Emails are indexed in an embedded link:https://lucene.apache.org/[Lucene] index, living on the local file system, +in order to empower email search. Text extraction relies on an in-JVM Jsoup based text extractor: no Tika server +can be plugged in. + +Being local, that index cannot be shared across instances, and needs to be rebuilt - via the +xref:{xref-base}/operate/webadmin.adoc#_reindexing_all_mails[reIndexing WebAdmin tasks] - if it is lost. + +==== Quotas + +Current quotas of users are held in a database projection. Limitations can be defined per user, per domain or +globally. + +==== Event Bus + +The {server-name} relies on an event bus system to enrich mailbox capabilities. Each operation performed on the +mailbox will trigger related events, that are processed asynchronously, in memory, on the node that emitted them. + +Many different kind of events can be triggered during a mailbox operation, such as: + +* `MailboxEvent`: event related to an operation regarding a mailbox: +** `MailboxDeletion`: a mailbox has been deleted +** `MailboxAdded`: a mailbox has been added +** `MailboxRenamed`: a mailbox has been renamed +** `MailboxACLUpdated`: a mailbox got its rights and permissions updated +* `MessageEvent`: event related to an operation regarding a message: +** `Added`: messages have been added to a mailbox +** `Expunged`: messages have been expunged from a mailbox +** `FlagsUpdated`: messages had their flags updated +** `MessageMoveEvent`: messages have been moved from a mailbox to another +* `QuotaUsageUpdatedEvent`: event related to quota update + +Mailbox listeners can register themselves on this event bus system to be called when an event is fired. Read more +about xref:{xref-base}/configure/listeners.adoc[listeners configuration] and +xref:{xref-base}/customization/mailbox-listeners.adoc[writing your own listeners]. + +Note that, unlike the Distributed server, the event dead letter of the {server-name} is kept *in memory*: events +that failed to be processed are lost upon restart. + +=== Data + +Storage for domains and users. + +Domains and users are persisted in the database. Users can alternatively be managed via a LDAP (read only), see +xref:{xref-base}/configure/usersrepository.adoc[usersrepository.xml]. + +=== Recipient rewrite tables + +Storage of Recipients Rewriting rules, in the database. + +James allows using various mapping types for better expressing the intent of your address rewriting logic: + +* *Domain mapping*: Rewrites the domain of mail addresses. Use it for technical purposes, user will not be +allowed to use the source in their FROM address headers. Domain mappings can be managed via the CLI and added via +xref:{xref-base}/operate/webadmin.adoc#_domain_mappings[WebAdmin]. +* *Domain aliases*: Rewrites the domain of mail addresses. Express the idea that both domains can be used +inter-changeably. Domain aliases can be managed via +xref:{xref-base}/operate/webadmin.adoc#_get_the_list_of_aliases_for_a_domain[WebAdmin]. +* *Forwards*: Replaces the source address by another one. Vehicles the intent of forwarding incoming mails to +other users. Forwards can be managed via xref:{xref-base}/operate/webadmin.adoc#_address_forwards[WebAdmin]. +* *Groups*: Replaces the source address by another one. Vehicles the intent of a group registration (feature poor +mailing list). Groups can be managed via xref:{xref-base}/operate/webadmin.adoc#_address_group[WebAdmin]. +* *Aliases*: Replaces the source address by another one. Represents a user owned mail address, with which he can +interact as if it was his main mail address. Aliases can be managed via +xref:{xref-base}/operate/webadmin.adoc#_address_aliases[WebAdmin]. +* *Address mappings*: Replaces the source address by another one. Use for technical purposes, this mapping type +does not hold specific intent. Address mappings can be managed via the CLI or via +xref:{xref-base}/operate/webadmin.adoc#_address_mappings[WebAdmin]. +* *Regex mappings*: Applies the regex on the supplied address. Regex mappings can be managed via the CLI or via +xref:{xref-base}/operate/webadmin.adoc#_regex_mapping[WebAdmin]. +* *Error*: Throws an error upon processing. Errors can be managed via the CLI. + +=== Task Manager + +Allows to control and schedule long running tasks run by other components. Among others it enables scheduling, +progress monitoring and cancellation of long running tasks. + +The {server-name} runs a memory based task manager: tasks are executed by the node they were submitted to, and +their history is lost upon restart. diff --git a/docs/modules/servers/pages/jpa/configure/collecting-contacts.adoc b/docs/modules/servers/pages/jpa/configure/collecting-contacts.adoc new file mode 100644 index 0000000000..f04b057634 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/collecting-contacts.adoc @@ -0,0 +1,13 @@ += JPA James Server — Contact collection +:navtitle: Contact collection + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/collecting-contacts.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/collecting-events.adoc b/docs/modules/servers/pages/jpa/configure/collecting-events.adoc new file mode 100644 index 0000000000..61b6dee047 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/collecting-events.adoc @@ -0,0 +1,13 @@ += JPA James Server — Event collection +:navtitle: Event collection + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/collecting-events.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/database.adoc b/docs/modules/servers/pages/jpa/configure/database.adoc new file mode 100644 index 0000000000..a1401eb900 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/database.adoc @@ -0,0 +1,13 @@ += JPA James Server — james-database.properties +:navtitle: james-database.properties + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/database.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/dns.adoc b/docs/modules/servers/pages/jpa/configure/dns.adoc new file mode 100644 index 0000000000..2777175ca0 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/dns.adoc @@ -0,0 +1,13 @@ += JPA James Server — dnsservice.xml +:navtitle: dnsservice.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/dns.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/domainlist.adoc b/docs/modules/servers/pages/jpa/configure/domainlist.adoc new file mode 100644 index 0000000000..406c1a0afb --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/domainlist.adoc @@ -0,0 +1,13 @@ += JPA James Server — domainlist.xml +:navtitle: domainlist.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/domainlist.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/droplists.adoc b/docs/modules/servers/pages/jpa/configure/droplists.adoc new file mode 100644 index 0000000000..bb5cb11646 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/droplists.adoc @@ -0,0 +1,13 @@ += JPA James Server — DropLists +:navtitle: DropLists + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/droplists.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/dsn.adoc b/docs/modules/servers/pages/jpa/configure/dsn.adoc new file mode 100644 index 0000000000..5d29754357 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/dsn.adoc @@ -0,0 +1,13 @@ += JPA James Server — Delivery Submission Notifications +:navtitle: ESMTP DSN support + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/dsn.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/extensions.adoc b/docs/modules/servers/pages/jpa/configure/extensions.adoc new file mode 100644 index 0000000000..02823869db --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/extensions.adoc @@ -0,0 +1,13 @@ += JPA James Server — extensions.properties +:navtitle: extensions.properties + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/extensions.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/healthcheck.adoc b/docs/modules/servers/pages/jpa/configure/healthcheck.adoc new file mode 100644 index 0000000000..94b899b78e --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/healthcheck.adoc @@ -0,0 +1,13 @@ += JPA James Server — healthcheck.properties +:navtitle: healthcheck.properties + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/healthcheck.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/imap.adoc b/docs/modules/servers/pages/jpa/configure/imap.adoc new file mode 100644 index 0000000000..326fe1e9fc --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/imap.adoc @@ -0,0 +1,13 @@ += JPA James Server — imapserver.xml +:navtitle: imapserver.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/imap.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/index.adoc b/docs/modules/servers/pages/jpa/configure/index.adoc new file mode 100644 index 0000000000..28ffaee100 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/index.adoc @@ -0,0 +1,38 @@ += JPA James Server — Configuration +:navtitle: Configuration + +:no-batchsizes: + +include::partial$jpa/deprecated.adoc[] + +This section presents how to configure the JPA James server. + +The JPA James server relies on separated files for configuring various components. Some files follow a *xml* +format and some others follow a *property* format. Some files can be omitted, in which case the functionality can +be disabled, or rely on reasonable defaults. + +The following configuration files are exposed: + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:xref-base: jpa/configure +:server-name: JPA James server +:no-jmap: +:no-vault: + +include::partial$configure/forProtocolsPartial.adoc[] + +== For storage dependencies + +** xref:{xref-base}/database.adoc[*james-database.properties*] tells James which relational database to use, and +how to connect to it. This file is required. link:{sample-configuration-prefix-url}/james-database.properties[example] + +Unlike the other James applications, the JPA James server needs no other storage dependency: full text search is +backed by an embedded Lucene index and the mail queue by an embedded ActiveMQ broker, both living on the local +file system. As a consequence *blobstore.properties*, *opensearch.properties*, *rabbitmq.properties*, +*redis.properties*, *tika.properties* and *search.properties* are not supported. + +include::partial$configure/forCoreComponentsPartial.adoc[] + +include::partial$configure/forExtensionsPartial.adoc[] + +include::partial$configure/systemPropertiesPartial.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/jmx.adoc b/docs/modules/servers/pages/jpa/configure/jmx.adoc new file mode 100644 index 0000000000..4e3b1f2115 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/jmx.adoc @@ -0,0 +1,13 @@ += JPA James Server — jmx.properties +:navtitle: jmx.properties + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/jmx.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/jvm.adoc b/docs/modules/servers/pages/jpa/configure/jvm.adoc new file mode 100644 index 0000000000..694ce26184 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/jvm.adoc @@ -0,0 +1,18 @@ += JPA James Server — jvm.properties +:navtitle: jvm.properties + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +:no-jmap: +:no-blobstore: +:no-rabbitmq: +:no-acl: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/jvm.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/kerberos.adoc b/docs/modules/servers/pages/jpa/configure/kerberos.adoc new file mode 100644 index 0000000000..1631d07833 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/kerberos.adoc @@ -0,0 +1,13 @@ += JPA James Server — Kerberos GSSAPI Configuration +:navtitle: Kerberos GSSAPI Configuration + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/kerberos.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/listeners.adoc b/docs/modules/servers/pages/jpa/configure/listeners.adoc new file mode 100644 index 0000000000..7eaec34383 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/listeners.adoc @@ -0,0 +1,15 @@ += JPA James Server — listeners.xml +:navtitle: listeners.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +:no-quota-mailing: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/listeners.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/mailetcontainer.adoc b/docs/modules/servers/pages/jpa/configure/mailetcontainer.adoc new file mode 100644 index 0000000000..b59a07aa57 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/mailetcontainer.adoc @@ -0,0 +1,13 @@ += JPA James Server — mailetcontainer.xml +:navtitle: mailetcontainer.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/mailetcontainer.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/mailets.adoc b/docs/modules/servers/pages/jpa/configure/mailets.adoc new file mode 100644 index 0000000000..02d8b6518e --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/mailets.adoc @@ -0,0 +1,18 @@ += JPA James Server — Mailets +:navtitle: Packaged Mailets + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +:no-jmap: +:no-icalendar: + +:no-vacation: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/mailets.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/mailrepositorystore.adoc b/docs/modules/servers/pages/jpa/configure/mailrepositorystore.adoc new file mode 100644 index 0000000000..146b9afd02 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/mailrepositorystore.adoc @@ -0,0 +1,21 @@ += JPA James Server — mailrepositorystore.xml +:navtitle: mailrepositorystore.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file +:mail-repository-protocol: file +:mail-repository-class: org.apache.james.mailrepository.file.FileMailRepository +:no-blobstore: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/mailrepositorystore.adoc[] + +NOTE: In addition to the protocols declared in `mailrepositorystore.xml`, the JPA application always registers the +`jpa` protocol, backed by `org.apache.james.mailrepository.jpa.JPAMailRepository`, which stores the mails within the +relational database rather than on the local file system. + diff --git a/docs/modules/servers/pages/jpa/configure/matchers.adoc b/docs/modules/servers/pages/jpa/configure/matchers.adoc new file mode 100644 index 0000000000..c5ee08d6fd --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/matchers.adoc @@ -0,0 +1,16 @@ += JPA James Server — Matchers +:navtitle: Packaged Matchers + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +:no-jmap: +:no-dlp: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/matchers.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/mta-sts.adoc b/docs/modules/servers/pages/jpa/configure/mta-sts.adoc new file mode 100644 index 0000000000..fb24feeab9 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/mta-sts.adoc @@ -0,0 +1,13 @@ += JPA James Server — MTA-STS +:navtitle: MTA-STS + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/mta-sts.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/oidc.adoc b/docs/modules/servers/pages/jpa/configure/oidc.adoc new file mode 100644 index 0000000000..c97f65ccd0 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/oidc.adoc @@ -0,0 +1,15 @@ += JPA James Server — OIDC Configuration +:navtitle: OIDC Configuration + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +:no-jmap: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/oidc.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/pop3.adoc b/docs/modules/servers/pages/jpa/configure/pop3.adoc new file mode 100644 index 0000000000..517f2f8f70 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/pop3.adoc @@ -0,0 +1,13 @@ += JPA James Server — pop3server.xml +:navtitle: pop3server.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/pop3.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/recipientrewritetable.adoc b/docs/modules/servers/pages/jpa/configure/recipientrewritetable.adoc new file mode 100644 index 0000000000..d29ab4dfcc --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/recipientrewritetable.adoc @@ -0,0 +1,13 @@ += JPA James Server — recipientrewritetable.xml +:navtitle: recipientrewritetable.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/recipientrewritetable.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/remote-delivery-error-handling.adoc b/docs/modules/servers/pages/jpa/configure/remote-delivery-error-handling.adoc new file mode 100644 index 0000000000..0b1e5f3e91 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/remote-delivery-error-handling.adoc @@ -0,0 +1,15 @@ += JPA James Server — About RemoteDelivery error handling +:navtitle: About RemoteDelivery error handling + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +:no-rabbitmq: + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/remote-delivery-error-handling.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/server.adoc b/docs/modules/servers/pages/jpa/configure/server.adoc new file mode 100644 index 0000000000..4537595e86 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/server.adoc @@ -0,0 +1,13 @@ += JPA James Server — Common Server Configuration +:navtitle: Common Server Configuration + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/server.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/sieve.adoc b/docs/modules/servers/pages/jpa/configure/sieve.adoc new file mode 100644 index 0000000000..e536680e18 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/sieve.adoc @@ -0,0 +1,13 @@ += JPA James Server — Sieve & ManageSieve +:navtitle: Sieve & ManageSieve + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/sieve.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/smtp-hooks.adoc b/docs/modules/servers/pages/jpa/configure/smtp-hooks.adoc new file mode 100644 index 0000000000..1e817c9504 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/smtp-hooks.adoc @@ -0,0 +1,13 @@ += JPA James Server — SMTP Hooks +:navtitle: Packaged SMTP hooks + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/smtp-hooks.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/smtp.adoc b/docs/modules/servers/pages/jpa/configure/smtp.adoc new file mode 100644 index 0000000000..b78cef3279 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/smtp.adoc @@ -0,0 +1,13 @@ += JPA James Server — smtpserver.xml +:navtitle: smtpserver.xml & lmtpserver.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/smtp.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/spam.adoc b/docs/modules/servers/pages/jpa/configure/spam.adoc new file mode 100644 index 0000000000..88b80eec46 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/spam.adoc @@ -0,0 +1,13 @@ += JPA James Server — Anti-Spam configuration +:navtitle: Anti-Spam setup + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/spam.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/ssl.adoc b/docs/modules/servers/pages/jpa/configure/ssl.adoc new file mode 100644 index 0000000000..610271c2d0 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/ssl.adoc @@ -0,0 +1,13 @@ += JPA James Server — SSL & TLS configuration +:navtitle: SSL & TLS + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/ssl.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/usersrepository.adoc b/docs/modules/servers/pages/jpa/configure/usersrepository.adoc new file mode 100644 index 0000000000..7ee4821512 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/usersrepository.adoc @@ -0,0 +1,13 @@ += JPA James Server — usersrepository.xml +:navtitle: usersrepository.xml + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server +:backend-name: the database +:mailet-repository-path-prefix: file + +include::partial$jpa/deprecated.adoc[] + +include::partial$configure/usersrepository.adoc[] diff --git a/docs/modules/servers/pages/jpa/configure/webadmin.adoc b/docs/modules/servers/pages/jpa/configure/webadmin.adoc new file mode 100644 index 0000000000..2886e626f9 --- /dev/null +++ b/docs/modules/servers/pages/jpa/configure/webadmin.adoc @@ -0,0 +1,14 @@ += JPA James Server — webadmin.properties +:navtitle: webadmin.properties + +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:pages-path: jpa +:xref-base: jpa +:server-name: JPA James server + +include::partial$jpa/deprecated.adoc[] + +NOTE: The JPA James server is packaged without the JWT module: the `jwt.enable` and `jwt.publickeypem.url` +options documented below have no effect. Authentication of the WebAdmin API relies on static passwords only. + +include::partial$configure/webadmin.adoc[] diff --git a/docs/modules/servers/pages/jpa/customization/imap.adoc b/docs/modules/servers/pages/jpa/customization/imap.adoc new file mode 100644 index 0000000000..85b6ef8d78 --- /dev/null +++ b/docs/modules/servers/pages/jpa/customization/imap.adoc @@ -0,0 +1,9 @@ += Custom IMAP processing +:navtitle: Custom IMAP processing + +:pages-path: jpa +:xref-base: jpa + +include::partial$jpa/deprecated.adoc[] + +include::partial$customization/imap.adoc[] diff --git a/docs/modules/servers/pages/jpa/customization/index.adoc b/docs/modules/servers/pages/jpa/customization/index.adoc new file mode 100644 index 0000000000..320703d971 --- /dev/null +++ b/docs/modules/servers/pages/jpa/customization/index.adoc @@ -0,0 +1,10 @@ += JPA James Mail Server — Extending behaviour +:navtitle: Extending behaviour + +:pages-path: jpa +:xref-base: jpa +:no-jmap: + +include::partial$jpa/deprecated.adoc[] + +include::partial$customization/index.adoc[] diff --git a/docs/modules/servers/pages/jpa/customization/mail-processing.adoc b/docs/modules/servers/pages/jpa/customization/mail-processing.adoc new file mode 100644 index 0000000000..0d23068a67 --- /dev/null +++ b/docs/modules/servers/pages/jpa/customization/mail-processing.adoc @@ -0,0 +1,9 @@ += Custom mail processing components +:navtitle: Custom mail processing components + +:pages-path: jpa +:xref-base: jpa + +include::partial$jpa/deprecated.adoc[] + +include::partial$customization/mail-processing.adoc[] diff --git a/docs/modules/servers/pages/jpa/customization/mailbox-listeners.adoc b/docs/modules/servers/pages/jpa/customization/mailbox-listeners.adoc new file mode 100644 index 0000000000..0e50bc45f9 --- /dev/null +++ b/docs/modules/servers/pages/jpa/customization/mailbox-listeners.adoc @@ -0,0 +1,9 @@ += Custom Mailbox Listeners +:navtitle: Custom Mailbox Listeners + +:pages-path: jpa +:xref-base: jpa + +include::partial$jpa/deprecated.adoc[] + +include::partial$customization/mailbox-listeners.adoc[] diff --git a/docs/modules/servers/pages/jpa/customization/smtp-hooks.adoc b/docs/modules/servers/pages/jpa/customization/smtp-hooks.adoc new file mode 100644 index 0000000000..a96fbdcd1f --- /dev/null +++ b/docs/modules/servers/pages/jpa/customization/smtp-hooks.adoc @@ -0,0 +1,9 @@ += Custom SMTP hooks +:navtitle: Custom SMTP hooks + +:pages-path: jpa +:xref-base: jpa + +include::partial$jpa/deprecated.adoc[] + +include::partial$customization/smtp-hooks.adoc[] diff --git a/docs/modules/servers/pages/jpa/customization/webadmin-routes.adoc b/docs/modules/servers/pages/jpa/customization/webadmin-routes.adoc new file mode 100644 index 0000000000..3c214f3adb --- /dev/null +++ b/docs/modules/servers/pages/jpa/customization/webadmin-routes.adoc @@ -0,0 +1,9 @@ += Custom WebAdmin routes +:navtitle: Custom WebAdmin routes + +:pages-path: jpa +:xref-base: jpa + +include::partial$jpa/deprecated.adoc[] + +include::partial$customization/webadmin-routes.adoc[] diff --git a/docs/modules/servers/pages/jpa/index.adoc b/docs/modules/servers/pages/jpa/index.adoc new file mode 100644 index 0000000000..7c00c59a0f --- /dev/null +++ b/docs/modules/servers/pages/jpa/index.adoc @@ -0,0 +1,61 @@ += JPA James Mail Server +:navtitle: JPA James Application + +include::partial$jpa/deprecated.adoc[] + +The JPA James server is a *single node* mail server, storing all of its data within a relational database. +It is packaged as the link:https://github.com/apache/james-project/tree/master/server/apps/jpa-app[jpa-app] +application. + +Data access is done through JDBC, and mapped with the link:https://openjpa.apache.org/[Apache OpenJPA] +implementation of the Java Persistence Architecture, in order to avoid vendor specific SQL. James thus runs on +top of most relational databases: H2 (the default, embedded), MariaDB, MySQL, PostgreSQL... provided the +corresponding JDBC driver is supplied. + +Emails, mailboxes, users, domains, rewriting rules and Sieve scripts are all stored in that single database. No +other third party software is required: full text search relies on an embedded +link:https://lucene.apache.org/[Lucene] index and the mail queue on an embedded ActiveMQ broker, both living on +the local file system. + +== Supported features + +The following protocols are supported: + +* *SMTP* and *LMTP* +* *IMAP* +* *POP3* +* *ManageSieve* +* The xref:jpa/operate/webadmin.adoc[WebAdmin] REST administration API + +The *JMAP* protocol is *not* available in this application: use the +xref:postgres/index.adoc[Postgres James server] or the xref:distributed/index.adoc[Distributed James server] if +you need it. + +The following components are not available either: the Deleted Messages Vault, the BlobStore and its object +storage backends, OpenSearch based search, and the RabbitMQ based distributed mail queue and event bus. The event +dead letter is kept in memory, and is thus lost upon restart. + +Mailbox sharing is not supported either: the JPA mailbox does not persist ACLs, hence +link:https://datatracker.ietf.org/doc/html/rfc4314.html[RFC-4314] IMAP ACL is not implemented. + +== Deprecation and alternatives + +This application is deprecated. Beyond the missing features listed above, it is bound to a single node - the +Lucene index, the ActiveMQ mail queue and the file mail repositories are local to the instance - which prevents +both horizontal scaling and high availability. The underlying OpenJPA stack is fully blocking, and barely +maintained upstream. + +The xref:postgres/index.adoc[Postgres James server] supersedes it: it also targets small to medium SQL based +deployments, but relies on the reactive `r2dbc` driver, is actively maintained, and supports the full James +feature set. Read xref:postgres/objectives.adoc[its objectives] for further details, and +xref:jpa/operate/migrating.adoc[the migration guide] to move your data over. + +== Read further + +In this section of the documentation, we will introduce you to: + +* xref:jpa/architecture/index.adoc[Architecture of the JPA James server] +* xref:jpa/run/index.adoc[Run the JPA James server] +* xref:jpa/configure/index.adoc[Configure the JPA James server] +* xref:jpa/operate/index.adoc[Operate the JPA James server] +* xref:jpa/customization/index.adoc[Extend the JPA James server] diff --git a/docs/modules/servers/pages/jpa/operate/cli.adoc b/docs/modules/servers/pages/jpa/operate/cli.adoc new file mode 100644 index 0000000000..2daa712f28 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/cli.adoc @@ -0,0 +1,9 @@ += JPA James Server — Command Line Interface +:navtitle: Command Line Interface + +:xref-base: jpa +:server-name: JPA James server + +include::partial$jpa/deprecated.adoc[] + +include::partial$operate/cli.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/guide.adoc b/docs/modules/servers/pages/jpa/operate/guide.adoc new file mode 100644 index 0000000000..40e9ceb0c3 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/guide.adoc @@ -0,0 +1,45 @@ += JPA James Server — Operator guide +:navtitle: Operator guide + +:xref-base: jpa +:pages-path: jpa +:mailet-repository-path-prefix: file +:backend-name: database +:sample-configuration-prefix-url: https://github.com/apache/james-project/blob/master/server/apps/jpa-app/sample-configuration +:server-name: JPA James server +:no-opensearch: +:no-rabbitmq: +:no-vault: + +include::partial$jpa/deprecated.adoc[] + +include::partial$operate/guide.adoc[] + +== Search index + +The JPA James server indexes emails within an embedded Lucene index, stored on the local file system, next to the +working directory. It is neither replicated nor shared: a lost or corrupted index needs to be rebuilt. + +Failures upon indexing are reported in the `ERROR` logs, and the corresponding events are stored in the *in +memory* event dead letter - which means they do not survive a restart. When events were lost, the WebAdmin +reIndexing tasks are the way to recover: + +* xref:{xref-base}/operate/webadmin.adoc#_reindexing_all_mails[reIndex all mails], +* or xref:{xref-base}/operate/webadmin.adoc#_reindexing_a_mailbox_mails[reIndex mails from a mailbox]. + +When checking the result of a reIndexing task, you might have failed reprocessed mails. You can still use the +task ID to +xref:{xref-base}/operate/webadmin.adoc#_fixing_previously_failed_reindexing[reprocess previously failed reIndexing mails]. + +_Note_: keep in mind that reindexing can be a very long operation depending on the volume of mails you have stored. + +== Database maintenance + +All the structured data, including message content, lives in the relational database. We recommend: + +* Setting up a *backup* policy for that database: it holds all of your users emails. +* Monitoring the disk usage of the database, of the Lucene index, of the ActiveMQ broker and of the file mail +repositories. +* Keeping statistics up to date, and monitoring slow queries, as advised by your database vendor. + +Read the xref:{xref-base}/operate/performanceChecklist.adoc[performance checklist] for further tuning advices. diff --git a/docs/modules/servers/pages/jpa/operate/index.adoc b/docs/modules/servers/pages/jpa/operate/index.adoc new file mode 100644 index 0000000000..41bb440d91 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/index.adoc @@ -0,0 +1,11 @@ += JPA James Server — Operate the JPA server +:navtitle: Operate the JPA server + +:xref-base: jpa +:server-name: JPA James server +:server-tag: JPA +:no-opensearch: + +include::partial$jpa/deprecated.adoc[] + +include::partial$operate/index.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/logging.adoc b/docs/modules/servers/pages/jpa/operate/logging.adoc new file mode 100644 index 0000000000..607b9e86ed --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/logging.adoc @@ -0,0 +1,11 @@ += JPA James Server — Logging +:navtitle: Logging + +:xref-base: jpa +:server-name: JPA James server +:server-tag: JPA +:backend-name: database + +include::partial$jpa/deprecated.adoc[] + +include::partial$operate/logging.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/metrics.adoc b/docs/modules/servers/pages/jpa/operate/metrics.adoc new file mode 100644 index 0000000000..452b2b70bb --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/metrics.adoc @@ -0,0 +1,15 @@ += JPA James Server — Metrics +:navtitle: Metrics + +:other-metrics: JDBC connection pool metrics +:xref-base: jpa +:server-name: JPA James server + +:no-jmap: +:no-tika: +:no-blobstore: + + +include::partial$jpa/deprecated.adoc[] + +include::partial$operate/metrics.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/migrating.adoc b/docs/modules/servers/pages/jpa/operate/migrating.adoc new file mode 100644 index 0000000000..a477af06d6 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/migrating.adoc @@ -0,0 +1,13 @@ += JPA James Server — Migrating existing data +:navtitle: Migrating existing data + +:xref-base: jpa +:server-name: JPA James server + +include::partial$jpa/deprecated.adoc[] + +TIP: The very same procedure can be used to migrate *away* from the JPA James server: run it against a freshly +deployed xref:postgres/index.adoc[Postgres James server] to copy the mailboxes of your users over, which is the +recommended path given this application is deprecated. + +include::partial$operate/migrating.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/performanceChecklist.adoc b/docs/modules/servers/pages/jpa/operate/performanceChecklist.adoc new file mode 100644 index 0000000000..2054081163 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/performanceChecklist.adoc @@ -0,0 +1,79 @@ += JPA James Server — Performance checklist +:navtitle: Performance checklist + +:xref-base: jpa + +include::partial$jpa/deprecated.adoc[] + +This guide aims to help operators of the JPA James server refine their configuration and set up to achieve better +performance. + +CAUTION: The JPA James server is a single node application: it cannot be scaled horizontally, and its throughput +is ultimately bound by the one of a single JVM and of a single database. If the recommendations below are not +enough, consider migrating to the xref:postgres/index.adoc[Postgres James server]. + +== Database setup + +* Do not run production workloads on the default embedded *H2* database: it is meant for tests and evaluation. +Use a real database server - MariaDB, MySQL, PostgreSQL - as documented in +xref:{xref-base}/configure/database.adoc[james-database.properties]. +* Run the database on commodity hardware with attached SSD. HDD disks are to be banned for such workloads. +* Size the JDBC connection pool according to your traffic and to the maximum connection count of your database. +Within `james-database.properties`: + +.... +datasource.maxTotal=32 +datasource.minIdle=4 +datasource.testOnBorrow=true +datasource.validationQuery=select 1 +datasource.validationQueryTimeoutSec=2 +.... + +* Keep an eye on the growth of the message tables: message content is stored within the database itself. + +== Local storage + +The Lucene index, the ActiveMQ mail queue and the file mail repositories all live on the local file system, and +are latency sensitive. Place the James working directory on a local SSD, and monitor its free space. + +== James configuration + +=== IMAP / SMTP + +We recommend against resolving client connection DNS names. This behaviour can be disabled via a system property +within xref:{xref-base}/configure/jvm.adoc[jvm.properties]: + +.... +james.protocols.mdc.hostname=false +.... + +Concurrent IMAP request count is a critical setting. In +xref:{xref-base}/configure/imap.adoc[imapserver.xml]: + +.... +<concurrentRequests>200</concurrentRequests> +<maxQueueSize>4096</maxQueueSize> +.... + +Other recommendations include avoiding unnecessary work upon IMAP IDLE, and not starting dedicated BOSS threads: + +.... +<ignoreIDLEUponProcessing>false</ignoreIDLEUponProcessing> +<bossWorkerCount>0</bossWorkerCount> +.... + +=== Mail processing + +* Remove unneeded listeners and mailets. +* Reduce duplication of Matchers within +xref:{xref-base}/configure/mailetcontainer.adoc[mailetcontainer.xml]. +* Monitor the size of the `file://var/mail/error/` mail repository. + +=== Other generic recommendations + +* Limit usage of the `DEBUG` log level. `INFO` should be more than decent in most cases. +* While GC tuning 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 +.... diff --git a/docs/modules/servers/pages/jpa/operate/security.adoc b/docs/modules/servers/pages/jpa/operate/security.adoc new file mode 100644 index 0000000000..5a5a49adf6 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/security.adoc @@ -0,0 +1,12 @@ += JPA James Server — Security checklist +:navtitle: Security checklist + +:xref-base: jpa +:backend-name: database +:no-jmap: + +:no-jmap: + +include::partial$jpa/deprecated.adoc[] + +include::partial$operate/security.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/webadmin.adoc b/docs/modules/servers/pages/jpa/operate/webadmin.adoc new file mode 100644 index 0000000000..f3ee8efb70 --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/webadmin.adoc @@ -0,0 +1,30 @@ += JPA James Server — WebAdmin REST administration API +:navtitle: WebAdmin REST administration API + +:server-name: JPA James server +:xref-base: jpa +:backend-name: database +:no-jmap: +:no-vault: +:no-blobstore: +:no-dlp: +:no-vacation: +:no-delegation: +:no-messages-route: +:no-tasks-cleanup: +:no-rabbitmq: +:no-opensearch: +:no-backend-healthcheck: +:admin-mail-queues-extend: servers:jpa/operate/webadmin/admin-mail-queues-extend.adoc +:admin-messages-extend: servers:jpa/operate/webadmin/admin-messages-extend.adoc +:admin-mailboxes-extend: servers:jpa/operate/webadmin/admin-mailboxes-extend.adoc + +include::partial$jpa/deprecated.adoc[] + +NOTE: Only the routes actually bound by the JPA application are documented here. Compared to the +xref:distributed/index.adoc[Distributed] and xref:postgres/index.adoc[Postgres] servers, the JPA James server +exposes neither the JMAP related routes (identities, fast view projections, filtering rules, uploads), nor the +Deleted Messages Vault, the blob garbage collection, the mailbox export/restore, the DLP configuration, the +vacation settings, the user delegation, the `/messages` routes nor the task cleanup route. + +include::partial$operate/webadmin.adoc[] diff --git a/docs/modules/servers/pages/jpa/operate/webadmin/admin-mail-queues-extend.adoc b/docs/modules/servers/pages/jpa/operate/webadmin/admin-mail-queues-extend.adoc new file mode 100644 index 0000000000..d5f42c2e8d --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/webadmin/admin-mail-queues-extend.adoc @@ -0,0 +1 @@ +// The JPA server does not expose additional routes here diff --git a/docs/modules/servers/pages/jpa/operate/webadmin/admin-mailboxes-extend.adoc b/docs/modules/servers/pages/jpa/operate/webadmin/admin-mailboxes-extend.adoc new file mode 100644 index 0000000000..d5f42c2e8d --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/webadmin/admin-mailboxes-extend.adoc @@ -0,0 +1 @@ +// The JPA server does not expose additional routes here diff --git a/docs/modules/servers/pages/jpa/operate/webadmin/admin-messages-extend.adoc b/docs/modules/servers/pages/jpa/operate/webadmin/admin-messages-extend.adoc new file mode 100644 index 0000000000..d5f42c2e8d --- /dev/null +++ b/docs/modules/servers/pages/jpa/operate/webadmin/admin-messages-extend.adoc @@ -0,0 +1 @@ +// The JPA server does not expose additional routes here diff --git a/docs/modules/servers/pages/jpa/run/index.adoc b/docs/modules/servers/pages/jpa/run/index.adoc new file mode 100644 index 0000000000..53154e9f4d --- /dev/null +++ b/docs/modules/servers/pages/jpa/run/index.adoc @@ -0,0 +1,17 @@ += JPA James Server — Run +:navtitle: Run + +include::partial$jpa/deprecated.adoc[] + +This section presents guidance to all current deployment types of the JPA James server. + +== Run with Java + +Build your own Apache James JPA artifacts and start xref:jpa/run/run-java.adoc[running it directly on a Java +Virtual Machine]. + +== Run with Docker + +An `apache/james:jpa-latest` image is published, and a docker-compose demonstrating a MariaDB set up is provided. + +You can start xref:jpa/run/run-docker.adoc[running James with a few simple Docker commands]. diff --git a/docs/modules/servers/pages/jpa/run/run-docker.adoc b/docs/modules/servers/pages/jpa/run/run-docker.adoc new file mode 100644 index 0000000000..3d414d6745 --- /dev/null +++ b/docs/modules/servers/pages/jpa/run/run-docker.adoc @@ -0,0 +1,93 @@ += JPA James Server — Run with docker +:navtitle: Run with docker + +include::partial$jpa/deprecated.adoc[] + +== Running a single container + +Requirement: docker installed. + +[source,bash] +---- +$ docker run apache/james:jpa-latest +---- + +The image can also be built locally, then imported: + +[source,bash] +---- +$ docker image load -i server/apps/jpa-app/target/jib-image.tar +---- + +Use the +link:https://github.com/GoogleContainerTools/jib/blob/master/docs/faq.md#jvm-flags[JAVA_TOOL_OPTIONS environment option] +to pass extra JVM flags. For instance: + +[source,bash] +---- +$ docker run -e "JAVA_TOOL_OPTIONS=-Xmx500m -Xms500m" apache/james:jpa-latest +---- + +For security reasons you are required to generate your own keystore, that you can mount into the container via a +volume: + +[source,bash] +---- +$ keytool -genkey -alias james -keyalg RSA -keystore keystore +$ docker run -v $PWD/keystore:/root/conf/keystore apache/james:jpa-latest +---- + +In order to quickly start James without manually creating a keystore (e.g. for development), just pass the +`--generate-keystore` command argument: James will auto-generate a keystore file with the default settings. + +[source,bash] +---- +$ docker run --network james apache/james:jpa-latest --generate-keystore +---- + +A domain can be created upon James start via an environment variable: + +[source,bash] +---- +$ docker run --environment DOMAIN=domain.tld apache/james:jpa-latest +---- + +The xref:jpa/operate/cli.adoc[CLI] can easily be used: + +[source,bash] +---- +$ docker exec CONTAINER-ID james-cli ListDomains +---- + +link:https://glowroot.org/[Glowroot APM] is packaged as part of the docker distribution to easily enable valuable +performance insights. Disabled by default, its java agent can easily be enabled: + +[source,bash] +---- +$ docker run -e "JAVA_TOOL_OPTIONS=-javaagent:/root/glowroot.jar" apache/james:jpa-latest +---- + +== Running via docker-compose + +We do ship a +link:https://github.com/apache/james-project/blob/master/server/apps/jpa-app/docker-compose.yml[docker-compose] +file demonstrating the JPA application usage on top of MariaDB. In order to run it: + +[source,bash] +---- +# 1. Download the driver: +$ wget https://repo1.maven.org/maven2/org/mariadb/jdbc/mariadb-java-client/2.7.2/mariadb-java-client-2.7.2.jar + +# 2. Generate the keystore with the default password `james72laBalle`: +$ keytool -genkey -alias james -keyalg RSA -keystore keystore + +# 3. Start MariaDB +$ docker-compose up -d mariadb + +# 4. Start James +$ docker-compose up james +---- + +The driver JAR is mounted at `/root/libs/james-jdbc-driver.jar` in order to be added to the classpath, and the +matching `james-database.properties` is mounted within the `conf` folder. Read +xref:jpa/configure/database.adoc#_using_alternative_jdbc_drivers[this section] for further details. diff --git a/docs/modules/servers/pages/jpa/run/run-java.adoc b/docs/modules/servers/pages/jpa/run/run-java.adoc new file mode 100644 index 0000000000..4bd20ae9a5 --- /dev/null +++ b/docs/modules/servers/pages/jpa/run/run-java.adoc @@ -0,0 +1,66 @@ += JPA James Server — Run with Java +:navtitle: Run with Java + +include::partial$jpa/deprecated.adoc[] + +== Building + +=== Requirements + +* Java {java-version} SDK +* Maven 3 + +=== Building the artifacts + +An usual compilation using maven will produce two artifacts into the `server/apps/jpa-app/target` directory: + +* james-server-jpa-app.jar +* james-server-jpa-app.lib + +You can for example run in the base of +link:https://github.com/apache/james-project[this git repository]: + +.... +mvn clean install -DskipTests +.... + +== Running + +=== Requirements + +* Java {java-version} SDK +* A relational database. By default the embedded H2 database is used, and requires no set up. See +xref:jpa/configure/database.adoc[james-database.properties] for using another one. + +=== James launch + +To run james, you have to create a directory containing the required configuration files. + +James requires the configuration to be in a subfolder of the working directory that is called *conf*. A +link:https://github.com/apache/james-project/tree/master/server/apps/jpa-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. + +You also need to generate a keystore with the following command: + +[source,bash] +---- +$ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore +---- + +Once everything is set up, you just have to run the jar. Note that the OpenJPA java agent needs to be supplied, +as it performs the runtime enhancement of the JPA entities: + +[source,bash] +---- +$ java -javaagent:james-server-jpa-app.lib/openjpa-4.1.1.jar \ + -Dworking.directory=. \ + -Djdk.tls.ephemeralDHKeySize=2048 \ + -Dlogback.configurationFile=conf/logback.xml \ + -jar james-server-jpa-app.jar +---- + +Note that binding ports below 1024 requires administrative rights. + +Read xref:jpa/configure/database.adoc#_using_alternative_jdbc_drivers[this section] in order to run on top of a +database other than H2. diff --git a/docs/modules/servers/partials/architecture/implemented-standards.adoc b/docs/modules/servers/partials/architecture/implemented-standards.adoc index 86770ae1c9..f277927c66 100644 --- a/docs/modules/servers/partials/architecture/implemented-standards.adoc +++ b/docs/modules/servers/partials/architecture/implemented-standards.adoc @@ -76,11 +76,20 @@ The following IMAP specifications are implemented: - link:https://www.rfc-editor.org/rfc/rfc8514.html[RFC-8514] IMAP SAVEDATE Extension - link:https://www.rfc-editor.org/rfc/rfc8514.html[RFC-9394] IMAP PARTIAL Extension for Paged SEARCH and FETCH +ifndef::no-acl[] Partially implemented specifications: - link:https://datatracker.ietf.org/doc/html/rfc4314.html[RFC-4314] IMAP ACL - ACLs can be created and managed but mailbox not belonging to one account cannot, as of today, be accessed in IMAP. +endif::[] +ifdef::no-acl[] +The following specification is *not* implemented: + - link:https://datatracker.ietf.org/doc/html/rfc4314.html[RFC-4314] IMAP ACL + - The {server-name} does not persist mailbox ACLs, and does not support mailbox sharing. +endif::[] + +ifndef::no-jmap[] == JMAP - link:https://datatracker.ietf.org/doc/html/rfc8620[RFC-8620] Json Metadata Application Protocol (JMAP) @@ -101,6 +110,7 @@ Some methods / types are not yet implemented, some implementations are naive, an Users are invited to read these limitations before using actively the JMAP RFC-8621 implementation, and should ensure their client applications only uses supported operations. +endif::[] == POP3 - link:https://www.ietf.org/rfc/rfc1939.txt[RFC-1939] Post Office Protocol - Version 3 diff --git a/docs/modules/servers/partials/configure/database.adoc b/docs/modules/servers/partials/configure/database.adoc new file mode 100644 index 0000000000..5451e7d550 --- /dev/null +++ b/docs/modules/servers/partials/configure/database.adoc @@ -0,0 +1,112 @@ +This file is required. It tells James which relational database to use, and how to connect to it. + +Consult this link:{sample-configuration-prefix-url}/james-database.properties[example] +to get some examples and hints. + +James accesses the database through JDBC, and maps its entities with the +link:https://openjpa.apache.org/[Apache OpenJPA] implementation of the Java Persistence Architecture, in order to +avoid vendor specific SQL. + +The database instance needs to be reachable from the James server. The account being used requires the usual +`SELECT`, `INSERT`, `UPDATE` and `DELETE` privileges, as well as table creation privileges: the schema is created +upon the first start. + +== Connection settings + +.james-database.properties content +|=== +| Property name | explanation + +| database.driverClassName +| The class name of the JDBC driver to be used. The driver needs to be on the classpath, see +<<_using_alternative_jdbc_drivers>>. + +| database.url +| The JDBC connection URL for your database. + +| database.username +| The user of the database account to be used by this connection. + +| database.password +| The password of the database account to be used by this connection. + +| attachmentStorage.enabled +| Optional. Boolean, defaults to `false`. Enables storing attachments in the database. +*WARNING*: this storage is not designed for large binary content (no more than 1 GB of data). +|=== + +The default configuration relies on the embedded link:https://h2database.com[H2] database, which requires no +additional set up but is only suited for tests and small deployments: + +.... +database.driverClassName=org.h2.Driver +database.url=jdbc:h2:file:../var/store/h2db;DB_CLOSE_DELAY=-1 +database.username=app +database.password=app +.... + +== Connection pooling + +The JPA datasource and connection pooling is delegated to +link:https://commons.apache.org/proper/commons-dbcp/configuration.html[commons-dbcp2]. All the properties prefixed +with `datasource.` are passed to DBCP2, through the `openjpa.ConnectionProperties` OpenJPA property. Amongst others: + +* `datasource.testOnBorrow` +* `datasource.validationQuery` (this one is database specific) +* `datasource.validationQueryTimeoutSec` +* `datasource.initialSize` +* `datasource.minIdle` +* `datasource.maxTotal` + +.... +# Validate the data source before using it +datasource.testOnBorrow=true +datasource.validationQueryTimeoutSec=2 +datasource.validationQuery=select 1 +# The maximum number of active connections, or negative for no limit. +datasource.maxTotal=8 +.... + +Note that connection pooling requires the `openjpa.Multithreaded` property to be set to `true`, which is the default. + +== OpenJPA tuning + +All the properties prefixed with `openjpa.` are passed to the OpenJPA library as configuration. See the +link:https://openjpa.apache.org/builds/3.2.2/apache-openjpa/docs/ref_guide_conf_openjpa.html[OpenJPA reference guide] +for a complete list. + +[#_using_alternative_jdbc_drivers] +== Using alternative JDBC drivers + +Only the H2 driver is shipped by default. Using another database requires adding its JDBC driver to the classpath. + +With the ZIP package, add the driver JAR to the classpath, and start the main class explicitly: + +.... +java \ + -javaagent:james-server-jpa-app.lib/openjpa-4.1.1.jar \ + -Dworking.directory=. \ + -Djdk.tls.ephemeralDHKeySize=2048 \ + -Dlogback.configurationFile=conf/logback.xml \ + -cp "james-server-jpa-app.jar:james-server-jpa-app.lib/*:jdbc-driver.jar" \ + org.apache.james.JPAJamesServerMain +.... + +With docker, mount the driver JAR at `/root/libs/james-jdbc-driver.jar`: + +.... +docker run -v $PWD/mariadb-java-client-2.7.2.jar:/root/libs/james-jdbc-driver.jar apache/james:jpa-latest +.... + +Here is a MariaDB example, see this +link:{sample-configuration-prefix-url}/james-database-mariadb.properties[sample file]: + +.... +database.driverClassName=org.mariadb.jdbc.Driver +database.url=jdbc:mariadb://mariadb/test +database.username=test +database.password=test +.... + +When using PostgreSQL, add `standard_conforming_strings=off` to your PostgreSQL configuration, otherwise queries +relying on `LIKE ... ESCAPE` fail with `Invalid escape string`. diff --git a/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc b/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc index 2ea8a96102..aef59f9c29 100644 --- a/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc +++ b/docs/modules/servers/partials/configure/forCoreComponentsPartial.adoc @@ -2,14 +2,16 @@ By omitting these files, sane default values are used. -** xref:{xref-base}/batchsizes.adoc[*batchsizes.properties*] allows to configure mailbox read batch sizes link:{sample-configuration-prefix-url}/sample-configuration/batchsizes.properties[example] -** xref:{xref-base}/dns.adoc[*dnsservice.xml*] allows to configure DNS resolution link:{sample-configuration-prefix-url}/sample-configuration/dnsservice.xml[example] -** xref:{xref-base}/domainlist.adoc[*domainlist.xml*] allows to configure Domain storage link:{sample-configuration-prefix-url}/sample-configuration/domainlist.xml[example] -** xref:{xref-base}/healthcheck.adoc[*healthcheck.properties*] allows to configure periodical healthchecks link:{sample-configuration-prefix-url}/sample-configuration/healthcheck.properties[example] -** xref:{xref-base}/mailetcontainer.adoc[*mailetcontainer.xml*] allows configuring mail processing link:{sample-configuration-prefix-url}/sample-configuration/mailetcontainer.xml[example] +ifndef::no-batchsizes[] +** xref:{xref-base}/batchsizes.adoc[*batchsizes.properties*] allows to configure mailbox read batch sizes link:{sample-configuration-prefix-url}/batchsizes.properties[example] +endif::[] +** xref:{xref-base}/dns.adoc[*dnsservice.xml*] allows to configure DNS resolution link:{sample-configuration-prefix-url}/dnsservice.xml[example] +** xref:{xref-base}/domainlist.adoc[*domainlist.xml*] allows to configure Domain storage link:{sample-configuration-prefix-url}/domainlist.xml[example] +** xref:{xref-base}/healthcheck.adoc[*healthcheck.properties*] allows to configure periodical healthchecks link:{sample-configuration-prefix-url}/healthcheck.properties[example] +** xref:{xref-base}/mailetcontainer.adoc[*mailetcontainer.xml*] allows configuring mail processing link:{sample-configuration-prefix-url}/mailetcontainer.xml[example] *** xref:{xref-base}/mailets.adoc[This page] list matchers that can be used out of the box with the {server-name}. *** xref:{xref-base}/matchers.adoc[This page] list matchers that can be used out of the box with the {server-name}. -** xref:{xref-base}/mailrepositorystore.adoc[*mailrepositorystore.xml*] enables registration of allowed MailRepository protcols and link them to MailRepository implementations link:{sample-configuration-prefix-url}/sample-configuration/mailrepositorystore.xml[example] -** xref:{xref-base}/recipientrewritetable.adoc[*recipientrewritetable.xml*] enables advanced configuration for the Recipient Rewrite Table component link:{sample-configuration-prefix-url}/sample-configuration/recipientrewritetable.xml[example] +** xref:{xref-base}/mailrepositorystore.adoc[*mailrepositorystore.xml*] enables registration of allowed MailRepository protcols and link them to MailRepository implementations link:{sample-configuration-prefix-url}/mailrepositorystore.xml[example] +** xref:{xref-base}/recipientrewritetable.adoc[*recipientrewritetable.xml*] enables advanced configuration for the Recipient Rewrite Table component link:{sample-configuration-prefix-url}/recipientrewritetable.xml[example] *** xref:{xref-base}/matchers.adoc[This page] allows choosing the indexing technology. -** xref:{xref-base}/usersrepository.adoc[*usersrepository.xml*] allows configuration of user storage link:{sample-configuration-prefix-url}/sample-configuration/usersrepository.xml[example] +** xref:{xref-base}/usersrepository.adoc[*usersrepository.xml*] allows configuration of user storage link:{sample-configuration-prefix-url}/usersrepository.xml[example] diff --git a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc index b3fed8beb5..f0ddeacd23 100644 --- a/docs/modules/servers/partials/configure/forExtensionsPartial.adoc +++ b/docs/modules/servers/partials/configure/forExtensionsPartial.adoc @@ -2,9 +2,11 @@ By omitting these files, no extra behaviour is added. -** xref:{xref-base}/vault.adoc[*deletedMessageVault.properties*] allows to configure the DeletedMessageVault link:{sample-configuration-prefix-url}/sample-configuration/deletedMessageVault.properties[example] -** xref:{xref-base}/listeners.adoc[*listeners.xml*] enables configuration of Mailbox Listeners link:{sample-configuration-prefix-url}/sample-configuration/listeners.xml[example] -** xref:{xref-base}/extensions.adoc[*extensions.properties*] allows to extend James behaviour by loading your extensions in it link:{sample-configuration-prefix-url}/sample-configuration/extensions.properties[example] +ifndef::no-vault[] +** xref:{xref-base}/vault.adoc[*deletedMessageVault.properties*] allows to configure the DeletedMessageVault link:{sample-configuration-prefix-url}/deletedMessageVault.properties[example] +endif::[] +** xref:{xref-base}/listeners.adoc[*listeners.xml*] enables configuration of Mailbox Listeners link:{sample-configuration-prefix-url}/listeners.xml[example] +** xref:{xref-base}/extensions.adoc[*extensions.properties*] allows to extend James behaviour by loading your extensions in it link:{sample-configuration-prefix-url}/extensions.properties[example] ** xref:{xref-base}/jvm.adoc[*jvm.properties*] lets you specify additional system properties without cluttering your command line ** xref:{xref-base}/spam.adoc[This page] documents Anti-Spam setup with SpamAssassin, Rspamd. ** xref:{xref-base}/remote-delivery-error-handling.adoc[This page] proposes a simple strategy for RemoteDelivery error handling. diff --git a/docs/modules/servers/partials/configure/forProtocolsPartial.adoc b/docs/modules/servers/partials/configure/forProtocolsPartial.adoc index 0999218482..258519935a 100644 --- a/docs/modules/servers/partials/configure/forProtocolsPartial.adoc +++ b/docs/modules/servers/partials/configure/forProtocolsPartial.adoc @@ -2,14 +2,16 @@ By omitting these files, the underlying protocols will be disabled. -** xref:{xref-base}/imap.adoc[*imapserver.xml*] allows configuration for the IMAP protocol link:{sample-configuration-prefix-url}imapserver.xml[example] -** xref:{xref-base}/jmap.adoc[*jmap.properties*] allows to configure the JMAP protocol link:{sample-configuration-prefix-url}jmap.properties[example] -** xref:{xref-base}/jmx.adoc[*jmx.properties*] allows configuration of JMX being used by the Command Line Interface link:{sample-configuration-prefix-url}jmx.properties[example] -** xref:{xref-base}/smtp.adoc#_lmtp_configuration[*lmtpserver.xml*] allows configuring the LMTP protocol link:{sample-configuration-prefix-url}lmtpserver.xml[example] -** *managesieveserver.xml* allows configuration for ManagedSieve (unsupported) link:{sample-configuration-prefix-url}managesieveserver.xml[example] -** xref:{xref-base}/pop3.adoc[*pop3server.xml*] allows configuration for the POP3 protocol (experimental) link:{sample-configuration-prefix-url}pop3server.xml[example] -** xref:{xref-base}/smtp.adoc[*smtpserver.xml*] allows configuration for the SMTP protocol link:{sample-configuration-prefix-url}smtpserver.xml[example] +** xref:{xref-base}/imap.adoc[*imapserver.xml*] allows configuration for the IMAP protocol link:{sample-configuration-prefix-url}/imapserver.xml[example] +ifndef::no-jmap[] +** xref:{xref-base}/jmap.adoc[*jmap.properties*] allows to configure the JMAP protocol link:{sample-configuration-prefix-url}/jmap.properties[example] +endif::[] +** xref:{xref-base}/jmx.adoc[*jmx.properties*] allows configuration of JMX being used by the Command Line Interface link:{sample-configuration-prefix-url}/jmx.properties[example] +** xref:{xref-base}/smtp.adoc#_lmtp_configuration[*lmtpserver.xml*] allows configuring the LMTP protocol link:{sample-configuration-prefix-url}/lmtpserver.xml[example] +** *managesieveserver.xml* allows configuration for ManagedSieve (unsupported) link:{sample-configuration-prefix-url}/managesieveserver.xml[example] +** xref:{xref-base}/pop3.adoc[*pop3server.xml*] allows configuration for the POP3 protocol (experimental) link:{sample-configuration-prefix-url}/pop3server.xml[example] +** xref:{xref-base}/smtp.adoc[*smtpserver.xml*] allows configuration for the SMTP protocol link:{sample-configuration-prefix-url}/smtpserver.xml[example] *** xref:{xref-base}/smtp-hooks.adoc[This page] list SMTP hooks that can be used out of the box with the {server-name}. -** xref:{xref-base}/webadmin.adoc[*webadmin.properties*] enables configuration for the WebAdmin protocol link:{sample-configuration-prefix-url}webadmin.properties[example] +** xref:{xref-base}/webadmin.adoc[*webadmin.properties*] enables configuration for the WebAdmin protocol link:{sample-configuration-prefix-url}/webadmin.properties[example] ** xref:{xref-base}/ssl.adoc[This page] details SSL & TLS configuration. ** xref:{xref-base}/sieve.adoc[This page] details Sieve setup and how to enable ManageSieve. \ No newline at end of file diff --git a/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc b/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc index 2d498aeda1..7c2ee4e5b0 100644 --- a/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc +++ b/docs/modules/servers/partials/configure/forStorageDependenciesPartial.adoc @@ -2,10 +2,10 @@ Except specific documented cases, these files are required, at least to establish a connection with the storage components. -** xref:{xref-base}/blobstore.adoc[*blobstore.properties*] allows to configure the BlobStore link:{sample-configuration-prefix-url}/sample-configuration/blob.properties[example] +** xref:{xref-base}/blobstore.adoc[*blobstore.properties*] allows to configure the BlobStore link:{sample-configuration-prefix-url}/blob.properties[example] -** xref:{xref-base}/opensearch.adoc[*opensearch.properties*] allows to configure OpenSearch driver link:{sample-configuration-prefix-url}/sample-configuration/opensearch.properties[example] -** xref:{xref-base}/rabbitmq.adoc[*rabbitmq.properties*] allows configuration for the RabbitMQ driver link:{sample-configuration-prefix-url}/sample-configuration/rabbitmq.properties[example] +** xref:{xref-base}/opensearch.adoc[*opensearch.properties*] allows to configure OpenSearch driver link:{sample-configuration-prefix-url}/opensearch.properties[example] +** xref:{xref-base}/rabbitmq.adoc[*rabbitmq.properties*] allows configuration for the RabbitMQ driver link:{sample-configuration-prefix-url}/rabbitmq.properties[example] ** xref:{xref-base}/redis.adoc[*redis.properties*] allows configuration for the Redis driver link:https://github.com/apache/james-project/blob/fabfdf4874da3aebb04e6fe4a7277322a395536a/server/mailet/rate-limiter-redis/redis.properties[example], that is used by optional distributed rate limiting component. -** xref:{xref-base}/tika.adoc[*tika.properties*] allows configuring Tika as a backend for text extraction link:{sample-configuration-prefix-url}/sample-configuration/tika.properties[example] \ No newline at end of file +** xref:{xref-base}/tika.adoc[*tika.properties*] allows configuring Tika as a backend for text extraction link:{sample-configuration-prefix-url}/tika.properties[example] \ No newline at end of file diff --git a/docs/modules/servers/partials/configure/jvm.adoc b/docs/modules/servers/partials/configure/jvm.adoc index c52b966fa2..b1116d7701 100644 --- a/docs/modules/servers/partials/configure/jvm.adoc +++ b/docs/modules/servers/partials/configure/jvm.adoc @@ -65,6 +65,7 @@ james.protocols.mdc.hostname=false Optional. Boolean. Defaults to true. +ifndef::no-blobstore[] == Change the encoding type used for the blobId By default, the blobId is encoded in base64 url. The property `james.blob.id.hash.encoding` allows to change the encoding type. @@ -102,6 +103,8 @@ james.s3.sdk.checksum.backward.compatibility=false ---- To disable S3 checksum backward compatibility. +endif::[] +ifndef::no-jmap[] == JMAP Quota draft compatibility Some JMAP clients depend on the JMAP Quota draft specifications. The property `james.jmap.quota.draft.compatibility` allows @@ -147,6 +150,8 @@ Ex in `jvm.properties`: james.jmap.mdc.original.ip.header=x-real-ip ---- +endif::[] +ifndef::no-blobstore[] == Enable S3 metrics James supports extracting some S3 client-level metrics e.g. number of connections being used, time to acquire an S3 connection, total time to finish a S3 request... @@ -162,6 +167,7 @@ james.s3.metrics.enabled=false ---- To disable the S3 metrics. +endif::[] == Reactor Stream Prefetch Prefetch to use in Reactor to stream convertions (S3 => InputStream). Default to 1. @@ -202,6 +208,7 @@ james.relaxed.mailbox.name.validation=true ---- To relax validat ing `\*` and `%` characters in the mailbox name. Be careful as `%` and `*` are ambiguous for the LIST / LSUB commands that interpret those as wildcard thus returning all mailboxes matching the pattern. +ifndef::no-blobstore[] == Customizing blob deduplication settings ---- @@ -212,6 +219,8 @@ james.deduplicating.blobstore.thread.switch.threshold=32768 james.deduplicating.blobstore.file.threshold=10240 ---- +endif::[] +ifndef::no-rabbitmq[] == Configuring Distributed Task Manager Turning Distributed Task Manager single active consumer off allows for all @@ -231,6 +240,8 @@ Defaults to `1`. james.task.rabbitmq.qos=4 ---- +endif::[] +ifndef::no-acl[] == Allow users to have rights for shares of different domain Typically, preventing users to obtain rights for shares of another domain is a useful security layer. @@ -244,6 +255,7 @@ Ex in `jvm.properties` james.rights.crossdomain.allow=false ---- +endif::[] == Drop IMAP Recent handling This allows for dropping the legacy IMAP flag support, considering all emails as recent. This has no impact on modern diff --git a/docs/modules/servers/partials/configure/listeners.adoc b/docs/modules/servers/partials/configure/listeners.adoc index 0328c20132..f8a135433d 100644 --- a/docs/modules/servers/partials/configure/listeners.adoc +++ b/docs/modules/servers/partials/configure/listeners.adoc @@ -76,6 +76,7 @@ Please note that a `rspamd.properties` file is needed. Read also xref:{pages-path}/configure/spam.adoc[this page] for extra configuration required to support this feature. +ifndef::no-quota-mailing[] === QuotaThresholdCrossingListener Sends emails to users exceeding 80% and 99% of their quota to warn them (for instance). @@ -162,4 +163,4 @@ To mitigate this issue you might reach your administrator in order to increase y .... This MailboxListener is supported. - +endif::[] diff --git a/docs/modules/servers/partials/configure/mailets.adoc b/docs/modules/servers/partials/configure/mailets.adoc index 58505fc87a..4fd1fb85d0 100644 --- a/docs/modules/servers/partials/configure/mailets.adoc +++ b/docs/modules/servers/partials/configure/mailets.adoc @@ -25,17 +25,27 @@ include::partial$DSNBounce.adoc[] include::partial$Expires.adoc[] +ifndef::no-jmap[] include::partial$ExtractMDNOriginalJMAPMessageId.adoc[] +endif::[] include::partial$Forward.adoc[] +ifndef::no-icalendar[] include::partial$ICalendarParser.adoc[] +endif::[] +ifndef::no-icalendar[] include::partial$ICALToHeader.adoc[] +endif::[] +ifndef::no-icalendar[] include::partial$ICALToJsonAttribute.adoc[] +endif::[] +ifndef::no-icalendar[] include::partial$ICSSanitizer.adoc[] +endif::[] include::partial$LocalDelivery.adoc[] @@ -103,7 +113,9 @@ include::partial$StripAttachment.adoc[] include::partial$SplitMail.adoc[] +ifndef::no-jmap[] include::partial$TextCalendarBodyToAttachment.adoc[] +endif::[] include::partial$ToProcessor.adoc[] @@ -111,7 +123,9 @@ include::partial$ToRepository.adoc[] include::partial$ToSenderDomainRepository.adoc[] +ifndef::no-vacation[] include::partial$VacationMailet.adoc[] +endif::[] include::partial$WithPriority.adoc[] diff --git a/docs/modules/servers/partials/configure/mailrepositorystore.adoc b/docs/modules/servers/partials/configure/mailrepositorystore.adoc index 7e87f9e713..2ab15aa7c8 100644 --- a/docs/modules/servers/partials/configure/mailrepositorystore.adoc +++ b/docs/modules/servers/partials/configure/mailrepositorystore.adoc @@ -30,5 +30,10 @@ to get some examples and hints. </mailrepositorystore> ---- +ifndef::no-blobstore[] Only the *{mail-repository-class}* is available by default for the {server-name}. Mails metadata are stored in {mail-repository-protocol} while the headers and bodies are stored within the xref:{pages-path}/architecture/index.adoc#_blobstore[BlobStore]. +endif::[] +ifdef::no-blobstore[] +Only the *{mail-repository-class}* is available by default for the {server-name}. +endif::[] diff --git a/docs/modules/servers/partials/configure/matchers.adoc b/docs/modules/servers/partials/configure/matchers.adoc index 2faa837d92..a2fb5f6e6d 100644 --- a/docs/modules/servers/partials/configure/matchers.adoc +++ b/docs/modules/servers/partials/configure/matchers.adoc @@ -11,7 +11,9 @@ include::partial$AtMost.adoc[] include::partial$AtMostPriority.adoc[] +ifndef::no-dlp[] include::partial$DLP.adoc[] +endif::[] include::partial$FetchedFrom.adoc[] @@ -93,7 +95,9 @@ include::partial$SenderIsNull.adoc[] include::partial$SenderIsRegex.adoc[] +ifndef::no-jmap[] include::partial$SentByJmap.adoc[] +endif::[] include::partial$SentByMailet.adoc[] @@ -159,7 +163,9 @@ Here is the syntax to adopt in *mailetcontainer.xml*: <matcher name="relay-allowed" match="org.apache.james.mailetcontainer.impl.matchers.Or"> <matcher match="SMTPAuthSuccessful"/> <matcher match="SentByMailet"/> +ifndef::no-jmap[] <matcher match="org.apache.james.jmap.mailet.SentByJmap"/> +endif::[] <matcher match="RemoteAddrInNetwork=127.0.0.1, 10.2.*, 193.50.151.*"/> </matcher> diff --git a/docs/modules/servers/partials/configure/oidc.adoc b/docs/modules/servers/partials/configure/oidc.adoc index 193c15e742..b03b59fbfa 100644 --- a/docs/modules/servers/partials/configure/oidc.adoc +++ b/docs/modules/servers/partials/configure/oidc.adoc @@ -1,6 +1,8 @@ James supports OIDC via both `XOAUTH2` and `OAUTHBEARER` for Managesieve, IMAP, and SMTP. +ifndef::no-jmap[] JMAP RFC-8621 also supports OIDC bearer authentication via `OidcAuthenticationStrategy`. +endif::[] OIDC is not supported for POP3 and LMTP. We provide an link:https://github.com/apache/james-project/tree/master/examples/oidc[example] of an OIDC setup. It uses Keycloak as identity provider, but usage of other providers is possible. diff --git a/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc b/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc index 076833a7ed..d218fb483c 100644 --- a/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc +++ b/docs/modules/servers/partials/configure/remote-delivery-error-handling.adoc @@ -1,3 +1,4 @@ +ifndef::no-rabbitmq[] The advanced server mailQueue implemented by combining RabbitMQ for messaging and {mailet-repository-path-prefix} for administrative operation does not support delays. @@ -11,6 +12,11 @@ However, for operators willing to inter-operate with a limited set of well-ident limitation can be reconsidered. The main concern then become error handling for remote mail server failures. The following document will present a well tested strategy for Remote Delivery error handling leveraging standards Mail Processing components and mechanisms. +endif::[] +ifdef::no-rabbitmq[] +Error handling upon remote mail server failures is a recurring operational concern. The following document presents a +well tested strategy for Remote Delivery error handling, leveraging standard Mail Processing components and mechanisms. +endif::[] == Expectations diff --git a/docs/modules/servers/partials/customization/index.adoc b/docs/modules/servers/partials/customization/index.adoc index e5c45d79c3..0be6a95aee 100644 --- a/docs/modules/servers/partials/customization/index.adoc +++ b/docs/modules/servers/partials/customization/index.adoc @@ -1,6 +1,11 @@ == Available extension mechanisms +ifndef::no-jmap[] image::customization/james-hexagons-extensions.png[Extension mechanisms for the James Server] +endif::[] +ifdef::no-jmap[] +image::customization/james-hexagons-extensions-jpa.png[Extension mechanisms for the James Server] +endif::[] The James Server exposes several interfaces allowing the user to write custom extensions in order to extend the James Server behavior. diff --git a/docs/modules/servers/partials/jpa/deprecated.adoc b/docs/modules/servers/partials/jpa/deprecated.adoc new file mode 100644 index 0000000000..b4bbd39ecf --- /dev/null +++ b/docs/modules/servers/partials/jpa/deprecated.adoc @@ -0,0 +1,10 @@ +[WARNING.deprecation-banner] +==== +*The JPA James server is deprecated.* +It is kept for backward compatibility only, receives no new features, and may be removed in a future release. It +is a single node application, relies on the barely maintained blocking OpenJPA stack, and lacks major James +features (JMAP, distributed search, Deleted Messages Vault...). + +New deployments should use the xref:postgres/index.adoc[Postgres James server] instead: it targets the same SQL +based, small to medium deployments, with a reactive and actively maintained implementation. +==== diff --git a/docs/modules/servers/partials/operate/guide.adoc b/docs/modules/servers/partials/operate/guide.adoc index cdf2f4a6d4..4bbae2239f 100644 --- a/docs/modules/servers/partials/operate/guide.adoc +++ b/docs/modules/servers/partials/operate/guide.adoc @@ -124,6 +124,7 @@ xref:{xref-base}/operate/webadmin.adoc#_redeliver_group_events[redeliver group e or even just xref:{xref-base}/operate/webadmin.adoc#_redeliver_a_single_event[redeliver a single event]. +ifndef::no-opensearch[] == OpenSearch Indexing A projection of messages is maintained in OpenSearch via a listener @@ -194,8 +195,10 @@ restart _Note_: keep in mind that reindexing can be a very long operation depending on the volume of mails you have stored. +endif::[] == Mail Queue +ifndef::no-rabbitmq[] === Fine tune configuration for RabbitMQ In order to adapt mail queue settings to the actual traffic load, an @@ -208,6 +211,7 @@ thus is expensive. Size recurring metric reporting thus introduces performance issues. As such, we advise setting `mailqueue.size.metricsEnabled=false`. +endif::[] === Managing email queues Managing an email queue is an easy task if you follow this procedure: @@ -223,6 +227,7 @@ trash emails in the email queue you have this procedure to follow: * All mails from the given mail queue will be deleted with xref:{xref-base}/operate/webadmin.adoc#_clearing_a_mail_queue[Clearing a mail queue]. +ifndef::no-vault[] == Deleted Message Vault We recommend the administrator to @@ -268,3 +273,5 @@ You can delete all deleted messages older than the configured xref:{xref-base}/operate/webadmin.adoc#_deleted_messages_vault[Purge Deleted Messages]. We recommend calling this API in CRON job on 1st day each month. + +endif::[] \ No newline at end of file diff --git a/docs/modules/servers/partials/operate/index.adoc b/docs/modules/servers/partials/operate/index.adoc index e3b5ec8b67..84cb2dd372 100644 --- a/docs/modules/servers/partials/operate/index.adoc +++ b/docs/modules/servers/partials/operate/index.adoc @@ -21,4 +21,6 @@ We did put together a xref:{xref-base}/operate/guide.adoc[detailed guide] for We also included a guide for xref:{xref-base}/operate/migrating.adoc[migrating existing data] into the {server-tag} server. +ifndef::no-opensearch[] Additional functional visualisations can be set up using OpenSearch dashboards as documented in link:https://github.com/apache/james-project/tree/master/examples/opensearch-dahsboard[this example]. +endif::[] diff --git a/docs/modules/servers/partials/operate/metrics.adoc b/docs/modules/servers/partials/operate/metrics.adoc index 5f4ecaa1fa..6eebc0f78a 100644 --- a/docs/modules/servers/partials/operate/metrics.adoc +++ b/docs/modules/servers/partials/operate/metrics.adoc @@ -84,14 +84,18 @@ Here are the available metrics : - Number of per queue number of enqueued mails - Number of sent emails - Number of delivered emails +ifndef::no-jmap[] - Diverse Response time percentiles, counts and rates for JMAP +endif::[] - Diverse Response time percentiles, counts and rates for IMAP - Diverse Response time percentiles, counts and rates for SMTP - Diverse Response time percentiles, counts and rates for WebAdmin - Diverse Response time percentiles, counts and rates for each Mail Queue - Per mailet and per matcher Response time percentiles - Diverse Response time percentiles, counts and rates for DNS +ifndef::no-tika[] - Tika HTTP client statistics +endif::[] - SpamAssassin TCP client statistics - Mailbox listeners statistics time percentiles - Mailbox listeners statistics requests rate @@ -102,18 +106,22 @@ Here are the available metrics : Here are the various relevant Grafana boards for the {server-name}: +ifndef::no-blobstore[] - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_BlobStore.json[BlobStore] : Rates and percentiles for the BlobStore component +endif::[] - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_DNS_Dashboard.json[DNS] : Latencies and query counts for DNS resolution. - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_IMAP_Board.json[IMAP] : Latencies for the IMAP protocol - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_IMAP_CountBoard.json[IMAP counts] : Request counts for the IMAP protocol +ifndef::no-jmap[] - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_JMAP_Board.json[JMAP] : Latencies for the JMAP protocol - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_JMAP_CountBoard.json[JMAP counts] : Request counts for the JMAP protocol +endif::[] - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_JVM.json[JVM] : JVM statistics (heap, gcs, etc...) - https://github.com/apache/james-project/tree/master/server/grafana-reporting/prometheus-datasource/James_MAILET.json[Mailets] : @@ -128,9 +136,11 @@ SMTP latencies reports Request count for the SMTP protocol === Dashboard samples +ifndef::no-jmap[] Latencies for the JMAP protocol + image::JMAP_board.png[JMAP] +endif::[] Latencies for the IMAP protocol + @@ -140,9 +150,11 @@ JVM Statistics + image::JVM_board.png[JVM] +ifndef::no-blobstore[] BlobStore Statistics + image::BlobStore.png[BlobStore] +endif::[] webAdmin Statistics + diff --git a/docs/modules/servers/partials/operate/security.adoc b/docs/modules/servers/partials/operate/security.adoc index e94641cfd6..dcaf5d3404 100644 --- a/docs/modules/servers/partials/operate/security.adoc +++ b/docs/modules/servers/partials/operate/security.adoc @@ -15,8 +15,10 @@ to do so might result in *information disclosure*. - *Phishing*: Crafted emails that tricks the user into doing unintended actions. - *Viruses*: An attacker sends an attachment that contains an exploit that could run if a user opens it. - *Denial of service*: A small request may result in a very large response and require considerable work on the server... +ifndef::no-jmap[] - *Denial of service*: A malicious JMAP client may use the JMAP push subscription to attempt to flood a third party server with requests, creating a denial-of-service attack and masking the attacker’s true identity. +endif::[] - *Dictionary Harvest Attacks*: An attacker can rely on SMTP command reply code to know if a user exists or not. This can be used to obtain the list of local users and later use those address as targets for other attacks. @@ -54,7 +56,12 @@ failures. - 5. Ensure that xref:{xref-base}/configure/webadmin.adoc[WebAdmin] is not exposed unencrypted to the outer world. Doing so trivially exposes yourself. You can either disable it, activate JWT security, or restrict it to listen only on localhost. +ifndef::no-jmap[] - 6. Set up `HTTPS` for http based protocols, namely *JMAP* and *WebAdmin*. We recommend the use of a reverse proxy like Nginx. +endif::[] +ifdef::no-jmap[] + - 6. Set up `HTTPS` for *WebAdmin*. We recommend the use of a reverse proxy like Nginx. +endif::[] - 7. Set up link:https://james.apache.org/howTo/spf.html[SPF] and link:https://james.apache.org/howTo/dkim.html[DKIM] for your outgoing emails to be trusted. @@ -64,9 +71,11 @@ for your outgoing emails to be trusted. or xref:{xref-base}/configure/jmx.adoc[disabling JMX]. JMX is needed to use the existing CLI application but webadmin do offer similar features. Set the `jmx.remote.x.mlet.allow.getMBeansFromURL` to `false` to disable JMX remote code execution feature. +ifndef::no-jmap[] - 9. If JMAP is enabled, be sure that JMAP PUSH cannot be used for server side request forgery. This can be xref:{xref-base}/configure/jmap.adoc[configured] using the `webpush.prevent.server.side.request.forgery=true` property, forbidding push to private addresses. +endif::[] === Best practice: Should diff --git a/docs/modules/servers/partials/operate/webadmin.adoc b/docs/modules/servers/partials/operate/webadmin.adoc index 2a31b75cad..a5f11aa393 100644 --- a/docs/modules/servers/partials/operate/webadmin.adoc +++ b/docs/modules/servers/partials/operate/webadmin.adoc @@ -69,14 +69,19 @@ explanations. Supported health checks include: +ifndef::no-backend-healthcheck[] * *{backend-name} backend*: {backend-name} storage. +endif::[] +ifndef::no-opensearch[] * *OpenSearch Backend*: OpenSearch storage. +endif::[] * *EventDeadLettersHealthCheck* * *Guice application lifecycle* * *JPA Backend*: JPA storage. * *MailReceptionCheck* We rely on a configured user, send an email to him and assert that the email is well received, and can be read within the given configured period. Unhealthy means that the email could not be received before reacing the timeout. +ifndef::no-jmap[] * *MessageFastViewProjection* Health check of the component storing JMAP properties which are fast to retrieve. Those properties are computed in advance from messages and persisted in order to archive a better performance. @@ -86,7 +91,10 @@ time-window. We piggyback the projection update on missed JMAP read in order to decrease the outdated time window for a given entry. The health is determined by the ratio of missed projection reads. (lower than 10% causes `degraded`) +endif::[] +ifndef::no-rabbitmq[] * *RabbitMQ backend*: RabbitMQ messaging. +endif::[] Response codes: @@ -357,6 +365,7 @@ tasks with the given status are returned. Example of date format: `2023-04-15T07:23:27.541254+07:00` and `2023-04-15T07%3A23%3A27.541254%2B07%3A00` once URL encoded. +ifndef::no-tasks-cleanup[] === Cleaning up old tasks .... @@ -365,6 +374,7 @@ curl -XDELETE http://ip:port/tasks?olderThan=30day Will start a task which will cleanup old tasks still referenced in the TaskManager. +endif::[] === Endpoints returning a task Many endpoints do generate a task. @@ -709,6 +719,7 @@ Response codes: * 400: The user is invalid * 404: The user is unknown +ifndef::no-delegation[] === Add a delegated user of a base user .... @@ -769,6 +780,7 @@ Response codes: Note: Delegation is only available on top of {backend-name} products and not implemented yet on top of JPA backends. +endif::[] === Change a username .... @@ -873,6 +885,7 @@ Valid status includes: - `FAILED`: Error encountered while executing this step. Check the logs. - `ABORTED`: Won't be executed because of previous step failures. +ifndef::no-jmap[] === Retrieving the user identities .... @@ -1004,6 +1017,8 @@ Response codes: Resource name ``username'' represents a valid user Resource name ``identityId'' represents an existing user identity +endif::[] +ifndef::no-vacation[] == Administrating vacation settings === Get vacation settings @@ -1062,6 +1077,7 @@ Response codes: * 204: The vacation settings were successfully disabled * 404: The user name is unknown +endif::[] == Administrating mailboxes === All mailboxes @@ -1086,6 +1102,7 @@ The kind of task scheduled depends on the action parameter. See below for details. +ifndef::no-jmap[] ==== Recomputing Global JMAP fast message view projection Message fast view projection stores message properties expected to be @@ -1231,6 +1248,7 @@ Response codes: * 201: Success. Corresponding task id is returned. * 400: Error in the request. Details can be found in the reported error. +endif::[] ==== ReIndexing action Be also aware of the limits of this API: @@ -1488,6 +1506,7 @@ during the reIndexing might be ignored. include::{admin-mailboxes-extend}[] +ifndef::no-messages-route[] == Administrating Messages === ReIndexing a single mail by messageId @@ -1524,9 +1543,11 @@ be altered. === Deleting old messages of all users +ifndef::no-vault[] *Note:* Consider enabling the xref:{xref-base}/configure/vault.adoc[Deleted Messages Vault] if you use this feature. +endif::[] Old messages tend to pile up in user INBOXes. An admin might want to delete these on behalf of the users, e.g. all messages older than 30 days: @@ -1647,6 +1668,7 @@ The response is a map of task id per user: link:#_running_a_filtering_rule_on_a_mailbox[More details about details returned by running a filtering rule on a mailbox]. +endif::[] == Administrating user mailboxes === Creating a mailbox @@ -1734,6 +1756,7 @@ Response codes: * 204: The user do not have mailboxes anymore * 404: The user name does not exist. Note that this check can be bypassed by specifying the `force` query parameter. +ifndef::no-blobstore[] === Exporting user mailboxes .... @@ -1788,6 +1811,7 @@ Note: The account must be empty for the restore to succeed. If the user already If you wish to really force the restoration on a non-empty user, you can add the `?force=true` query parameter. It will delete existing data of the user before proceeding with the restoration. +endif::[] === ReIndexing a user mails .... @@ -1939,6 +1963,7 @@ the following `additionalInformation`: } .... +ifndef::no-jmap[] === Running a filtering rule on a mailbox .... @@ -2016,6 +2041,7 @@ the following `additionalInformation`: Note: you can configure the maximum number of actions applied per mailbox by setting the JVM property `james.rules.triage.max.actions.per.mailbox`. The default value is 25000. This limit may help avoid the tombstone threshold issue on Cassandra backends when too many messages are moved or deleted at once. +endif::[] === Subscribing a user to all of its mailboxes .... @@ -2047,6 +2073,7 @@ The scheduled task will have the following type `SubscribeAllTask` and the follo } .... +ifndef::no-jmap[] === Recomputing User JMAP fast message view projection This action is only available for backends supporting JMAP protocol. @@ -2107,6 +2134,7 @@ Response codes: * 400: Error in the request. Details can be found in the reported error. * 404: User not found. +endif::[] == Administrating quotas === Administrating quotas by users @@ -3069,6 +3097,7 @@ Response codes: * 204: Operation succeeded +ifndef::no-jmap[] == Administrating Jmap Uploads === Cleaning upload repository @@ -3102,6 +3131,8 @@ the following `additionalInformation`: } .... +endif::[] +ifndef::no-blobstore[] == Running blob garbage collection When deduplication is enabled one needs to explicitly run a garbage collection in order to delete no longer referenced @@ -3145,6 +3176,7 @@ Where: filter in later runs. - *gcedBlobCount* is the count of blobs that were garbage collected. +endif::[] == Administrating Recipient rewriting === Address group @@ -4420,6 +4452,7 @@ Response codes: * 400: Invalid request * 404: The mail queue does not exist +ifndef::no-rabbitmq[] === RabbitMQ republishing a mail queue from {backend-name} .... @@ -4455,6 +4488,7 @@ The response body contains the id of the republishing task. include::{admin-mail-queues-extend}[] +endif::[] == Sending email over webAdmin .... @@ -4666,6 +4700,7 @@ Response codes: * 400: Invalid group name, insertion id or action argument * 404: No event with this insertionId +ifndef::no-vault[] == Deleted Messages Vault The `Deleted Message Vault plugin' allows you to keep users deleted @@ -5058,6 +5093,8 @@ The scheduled task will have the following type while: - user: delete deleted messages from this user - deleteMessageId: messageId of deleted messages will be delete +endif::[] +ifndef::no-dlp[] == Administrating DLP Configuration DLP (stands for Data Leak Prevention) is supported by James. A DLP @@ -5204,6 +5241,7 @@ This is an example of returned body. } .... +endif::[] == Server administration === Reloading server certificates @@ -5236,7 +5274,9 @@ connections, including: - IMAP protocol - SMTP protocol +ifndef::no-jmap[] - JMAP websocket and event source sub protocols +endif::[] James keeps track of active channels and would iterate through them, destroying corresponding channels. diff --git a/docs/ui-overrides/partials/head-styles.hbs b/docs/ui-overrides/partials/head-styles.hbs new file mode 100644 index 0000000000..33c8d0f06e --- /dev/null +++ b/docs/ui-overrides/partials/head-styles.hbs @@ -0,0 +1,16 @@ + <link rel="stylesheet" href="{{{uiRootPath}}}/css/site.css"> + <style> + /* Yellow banner used to flag deprecated applications, see the `deprecation-banner` role. */ + .doc .admonitionblock.deprecation-banner { + margin: 0 0 1.5rem; + } + .doc .admonitionblock.deprecation-banner td.content { + background: #fff8db; + border-left: 4px solid #f0b429; + color: #4a3b00; + } + .doc .admonitionblock.deprecation-banner td.icon i.icon-warning { + background-color: #f0b429; + color: #4a3b00; + } + </style> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
