From 4ffee10706e247bcbda16029c5ab25e8624a25c5 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Sun, 14 Jun 2020 17:11:10 +0900 Subject: [PATCH 01/12] JAMES-3187 Updates to "Local Server" section of the new documentation --- docs/modules/servers/nav.adoc | 8 ++++- docs/modules/servers/pages/index.adoc | 4 +-- docs/modules/servers/pages/local.adoc | 5 --- .../servers/pages/local/architecture.adoc | 5 +++ .../modules/servers/pages/local/concepts.adoc | 5 +++ .../servers/pages/local/conf/index.adoc | 23 +++++++++++++ docs/modules/servers/pages/local/config.adoc | 5 +++ .../servers/pages/local/dependencies.adoc | 5 +++ docs/modules/servers/pages/local/help.adoc | 5 +++ docs/modules/servers/pages/local/index.adoc | 19 +++++++++++ .../servers/pages/local/objectives.adoc | 34 +++++++++++++++++++ 11 files changed, 110 insertions(+), 8 deletions(-) delete mode 100644 docs/modules/servers/pages/local.adoc create mode 100644 docs/modules/servers/pages/local/architecture.adoc create mode 100644 docs/modules/servers/pages/local/concepts.adoc create mode 100644 docs/modules/servers/pages/local/conf/index.adoc create mode 100644 docs/modules/servers/pages/local/config.adoc create mode 100644 docs/modules/servers/pages/local/dependencies.adoc create mode 100644 docs/modules/servers/pages/local/help.adoc create mode 100644 docs/modules/servers/pages/local/index.adoc create mode 100644 docs/modules/servers/pages/local/objectives.adoc diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 78e7f7b0947..1c36257c885 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -2,7 +2,13 @@ ** xref:demo.adoc[] *** xref:servers:5-minute-demo.adoc[] *** xref:servers:15-minute-demo.adoc[] -** xref:local.adoc[] +** xref:local/index.adoc[] +*** xref:local/objectives.adoc[] +*** xref:local/concepts.adoc[] +*** xref:local/architecture.adoc[] +*** xref:local/dependencies.adoc[] +*** xref:local/config.adoc[] +*** xref:local/help.adoc[] ** xref:redundant.adoc[] ** xref:distributed.adoc[] *** xref:distributed/architecture.adoc[] diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 3786e81de4d..6a4792477d6 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -24,7 +24,7 @@ to give James a quick spin on their local machine. == James Local Mail Server If you are not sure which server you should be using, then -you probably ought to be using the xref:local.adoc[*Local Server*]. +you probably ought to be using the xref:local/index.adoc[*Local Server*]. This server uses the local file system to store emails, which tends to considerably simplify the system. To safeguard your emails, you only need a simple generic backup solution that works with a data @@ -36,7 +36,7 @@ have a huge amount of emails to process, then usually the simplicity is well worth the loss of some functionality. The last thing you need is to have to resolve difficult issues on a production server when you have not yet acquired the requisite knowledge to deal with those issues. Using the -xref:local.adoc[*Local Server*] will help you reduce the risk of running into +xref:local/index.adoc[*Local Server*] will help you reduce the risk of running into production issues. This server is: diff --git a/docs/modules/servers/pages/local.adoc b/docs/modules/servers/pages/local.adoc deleted file mode 100644 index 8783dcf81b1..00000000000 --- a/docs/modules/servers/pages/local.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Local Mail Server -:navtitle: Local - -(TODO) - diff --git a/docs/modules/servers/pages/local/architecture.adoc b/docs/modules/servers/pages/local/architecture.adoc new file mode 100644 index 00000000000..bc5b64143ac --- /dev/null +++ b/docs/modules/servers/pages/local/architecture.adoc @@ -0,0 +1,5 @@ += James Local Server — Architecture +:navtitle: Architecture + +(TODO) + diff --git a/docs/modules/servers/pages/local/concepts.adoc b/docs/modules/servers/pages/local/concepts.adoc new file mode 100644 index 00000000000..e33c69816d9 --- /dev/null +++ b/docs/modules/servers/pages/local/concepts.adoc @@ -0,0 +1,5 @@ += James Local Server — Concepts +:navtitle: Concepts + +(TODO) + diff --git a/docs/modules/servers/pages/local/conf/index.adoc b/docs/modules/servers/pages/local/conf/index.adoc new file mode 100644 index 00000000000..f612cb9882b --- /dev/null +++ b/docs/modules/servers/pages/local/conf/index.adoc @@ -0,0 +1,23 @@ += James Local Mail Server Configuration +:navtitle: Configuration + + * Domain names (domainlist.xml) + * Database (james-database.properties) + * LMTP (lmtpserver.xml) + * POP3 (pop3server.xml) + * DNS (dnsservice.xml) + * Loggin (logback.xml) + * ??? (jmx.properties) + * ??? (recipientrewritetable.xml) + * ??? (extensions.properties) + * JWT (jwt_publickey) + * Mailets (mailetcontainer.xml) + * SMTP (smtpserver.xml) + * Health checks (healthcheck.properties) + * Mail storage (mailrepositorystore.xml) + * User storage (usersrepository.xml) + * IMAP (imapserver.xml) + * ??? (listeners.xml) + * Sieve filters (managesieveserver.xml) + * Web admin (webadmin.properties) + diff --git a/docs/modules/servers/pages/local/config.adoc b/docs/modules/servers/pages/local/config.adoc new file mode 100644 index 00000000000..02c16abcf57 --- /dev/null +++ b/docs/modules/servers/pages/local/config.adoc @@ -0,0 +1,5 @@ += James Local Server — Configuration +:navtitle: Configuration + +(TODO) + diff --git a/docs/modules/servers/pages/local/dependencies.adoc b/docs/modules/servers/pages/local/dependencies.adoc new file mode 100644 index 00000000000..415b1e8b031 --- /dev/null +++ b/docs/modules/servers/pages/local/dependencies.adoc @@ -0,0 +1,5 @@ += James Local Server — Dependencies +:navtitle: Dependencies + +(TODO) + diff --git a/docs/modules/servers/pages/local/help.adoc b/docs/modules/servers/pages/local/help.adoc new file mode 100644 index 00000000000..6c6267def65 --- /dev/null +++ b/docs/modules/servers/pages/local/help.adoc @@ -0,0 +1,5 @@ += James Local Server — Where to get help +:navtitle: Help + +(TODO) + diff --git a/docs/modules/servers/pages/local/index.adoc b/docs/modules/servers/pages/local/index.adoc new file mode 100644 index 00000000000..f3681c6d890 --- /dev/null +++ b/docs/modules/servers/pages/local/index.adoc @@ -0,0 +1,19 @@ += James Local Mail Server +:navtitle: Local + +If you are not sure which server you should be using, then +you probably ought to be using the Local Server. + +At this time, the server is not entirely "out-of-the-box", because there +is some work you will have to do in order to get the server up and running. +However, the work that needs to be done is quite minimal. We will walk you +through the configuration in these documents. Hopefully in the near future +the installation will be made even simpler. + + * xref:local/objectives.adoc[Objectives and motivation of the Local Server] + * xref:local/concepts.adoc[Useful background concepts] + * xref:local/architecture.adoc[Overview of architecture] + * xref:local/dependencies.adoc[Dependencies and requirements] + * xref:local/config.adoc[Configuration] + * xref:local/help.adoc[Where to go for help] + diff --git a/docs/modules/servers/pages/local/objectives.adoc b/docs/modules/servers/pages/local/objectives.adoc new file mode 100644 index 00000000000..e45db9b9b07 --- /dev/null +++ b/docs/modules/servers/pages/local/objectives.adoc @@ -0,0 +1,34 @@ += James Local Server — Objectives +:navtitle: Objectives + +The objective of the Local Server is to be as simple and minimalistic as possible, +while still being useful. Many people wish to have a basic mail server that they +can customize, without necessarily requiring a complex distributed system. +The Local Server is intended to be an entry-level server that is accessible to +those who want a mail server, but who don't want to have to learn about all the +complexities of a new system. + +This server is therefore intended to be the simplest to set up and use in +production. +Of all the James Servers, it has the least amount of dependencies and +complexities. +If you are not sure which of the James servers is best for you, you should +probably choose this one. + +The default configuration of the Local Server includes the following features: + + * Secure SMTP (SSL/TLS) over port 465 + * Secure IMAP4 (SSL/TLS) over port 993 + * Local Mailbox support + ** Files are stored locally on the filesystem + ** Optionally use a volume if you are a Docker or Kubernetes user + ** Data can be backed up simply by backing up the filesystem / volume + * Multi-domain (virtual domain) support + ** Up to xxx domains + ** Up to yyy users per domain + * Administration of users either via a command-line tool or the admin api + + +Optionally, more advanced users can adapt the Local Server to their needs by +updating the xref:local/conf/index.adoc[configuration files] and building a new Docker image +(currently unsupported). From 88ca5431a91e7e98385eaeac14c87d996c625936 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Wed, 17 Jun 2020 13:52:24 +0900 Subject: [PATCH 02/12] JAMES-3187 Small updates to configuration details --- docs/modules/servers/nav.adoc | 2 +- .../servers/pages/local/conf/index.adoc | 84 ++++++++++++++++++- docs/modules/servers/pages/local/config.adoc | 5 -- docs/modules/servers/pages/local/index.adoc | 2 +- 4 files changed, 82 insertions(+), 11 deletions(-) delete mode 100644 docs/modules/servers/pages/local/config.adoc diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 1c36257c885..0d249ee22ad 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -7,7 +7,7 @@ *** xref:local/concepts.adoc[] *** xref:local/architecture.adoc[] *** xref:local/dependencies.adoc[] -*** xref:local/config.adoc[] +*** xref:local/conf/index.adoc[] *** xref:local/help.adoc[] ** xref:redundant.adoc[] ** xref:distributed.adoc[] diff --git a/docs/modules/servers/pages/local/conf/index.adoc b/docs/modules/servers/pages/local/conf/index.adoc index f612cb9882b..0ff251d0ed1 100644 --- a/docs/modules/servers/pages/local/conf/index.adoc +++ b/docs/modules/servers/pages/local/conf/index.adoc @@ -1,15 +1,39 @@ = James Local Mail Server Configuration :navtitle: Configuration +== Configuration by feature + + * Domain names — provide the default domain names that ???? + * Database (james-database.properties) + * LMTP (lmtpserver.xml) + * POP3 (pop3server.xml) + * DNS (dnsservice.xml) + * Loggin (logback.xml) + * James CLI (jmx.properties) + * Email rewriting (recipientrewritetable.xml) + * Guice extensions (extensions.properties) + * JWT (jwt_publickey) + * Mailets (mailetcontainer.xml) + * SMTP (smtpserver.xml) + * Health checks (healthcheck.properties) + * Mail storage (mailrepositorystore.xml) + * User storage (usersrepository.xml) + * IMAP (imapserver.xml) + * Mailbox event listeners (listeners.xml) + * Sieve filters (managesieveserver.xml) + * Web admin (webadmin.properties) + +== Configuration file index + * Domain names (domainlist.xml) * Database (james-database.properties) * LMTP (lmtpserver.xml) * POP3 (pop3server.xml) * DNS (dnsservice.xml) * Loggin (logback.xml) - * ??? (jmx.properties) - * ??? (recipientrewritetable.xml) - * ??? (extensions.properties) + * James CLI (jmx.properties) + * Email rewriting (recipientrewritetable.xml) + * Guice extensions (extensions.properties) * JWT (jwt_publickey) * Mailets (mailetcontainer.xml) * SMTP (smtpserver.xml) @@ -17,7 +41,59 @@ * Mail storage (mailrepositorystore.xml) * User storage (usersrepository.xml) * IMAP (imapserver.xml) - * ??? (listeners.xml) + * Mailbox event listeners (listeners.xml) * Sieve filters (managesieveserver.xml) * Web admin (webadmin.properties) + + +== Notes +Jmx protocol is used by James cli to interactwith the server. Jmx is known to be insecure, and we have as a project to rewrite the cli for james servers in order to rely on webadmin. + + + +Scenarios for address rewriting + +The following scenarios are examples of how you can use address rewriting: + +Group consolidation: Some organizations segment their internal businesses into separate domains that are based on business or technical requirements. This configuration can cause email messages to appear as if they come from separate groups or even separate organizations. + +The following example shows how an organization, Contoso, Ltd., can hide its internal subdomains from external recipients: + +Outbound messages from the northamerica.contoso.com, europe.contoso.com, and asia.contoso.com domains are rewritten so they appear to originate from a single contoso.com domain. All messages are rewritten as they pass through Edge Transport servers that provide SMTP connectivity between the whole organization and the Internet. + +Inbound messages to contoso.com recipients are relayed by the Edge Transport server to a Mailbox server. The message is delivered to the correct recipient based on the proxy address that's configured on the recipient's mailbox. + +Mergers and acquisitions: An acquired company might continue to run as a separate business, but you can use address rewriting to make the two organizations appear as if they're one integrated organization. + +The following example shows how Contoso, Ltd. can hide the email domain of the newly acquired company, Fourth Coffee: + +Contoso, Ltd. wants all outbound messages from Fourth Coffee's Exchange organization to appear as if they originate from contoso.com. All messages from both organizations are sent through the Edge Transport servers at Contoso, Ltd., where email messages are rewritten from user@fourthcoffee.com to user@contoso.com. + +Inbound messages to user@contoso.com are rewritten and routed to user@fourthcoffee.com mailboxes. Inbound messages that are sent to user@fourthcoffee.com are routed directly to Fourth Coffee's email servers. + +Partners: Many organizations use external partners to provide services for their customers, other organizations, or their own organization. To avoid confusion, the organization might replace the email domain of the partner organization with its own email domain. + +The following example shows how Contoso, Ltd. can hide a partner's email domain: + +Contoso, Ltd. provides support for the larger Wingtip Toys organization. Wingtip Toys wants a unified email experience for its customers, and it requires all messages from support personnel at Contoso, Ltd. to appear as if they were sent from Wingtip Toys. All outbound messages that relate to Wingtip Toys are sent through their Edge Transport servers, and all contoso.com email addresses are rewritten to wingtiptoys.com email addresses. + +Inbound messages for support@wingtiptoys.com are accepted by Wingtip Toy's Edge Transport servers, rewritten, and then routed to the support@contoso.com email address. + +Message properties modified by address rewriting + +A standard SMTP email message consists of a message envelope and message content. The message envelope contains information that's required for transmitting and delivering the message between SMTP messaging servers. The message content contains message header fields (collectively called the message header) and the message body. The message envelope is described in RFC 2821, and the message header is described in RFC 2822. + +When a sender composes an email message and submits it for delivery, the message contains the basic information that's required to comply with SMTP standards, such as a sender, a recipient, the date and time that the message was composed, an optional subject line, and an optional message body. This information is contained in the message itself and, by definition, in the message header. + +The sender's mail server generates a message envelope for the message by using the sender's and recipient's information found in the message header. It then transmits the message to the Internet for delivery to the recipient's messaging server. Recipients never see the message envelope because it's generated by the message transmission process, and it isn't actually part of the message. + +Address rewriting changes an email address by rewriting specific fields in the message header or message envelope. Address rewriting changes several fields in outbound messages, but only one field in inbound email messages. The following table shows which SMTP header fields are rewritten in outbound and inbound messages. + + + + +https://www.exim.org/exim-html-current/doc/html/spec_html/ch-address_rewriting.html + + +:wq diff --git a/docs/modules/servers/pages/local/config.adoc b/docs/modules/servers/pages/local/config.adoc deleted file mode 100644 index 02c16abcf57..00000000000 --- a/docs/modules/servers/pages/local/config.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Local Server — Configuration -:navtitle: Configuration - -(TODO) - diff --git a/docs/modules/servers/pages/local/index.adoc b/docs/modules/servers/pages/local/index.adoc index f3681c6d890..df18cfb0fb5 100644 --- a/docs/modules/servers/pages/local/index.adoc +++ b/docs/modules/servers/pages/local/index.adoc @@ -14,6 +14,6 @@ the installation will be made even simpler. * xref:local/concepts.adoc[Useful background concepts] * xref:local/architecture.adoc[Overview of architecture] * xref:local/dependencies.adoc[Dependencies and requirements] - * xref:local/config.adoc[Configuration] + * xref:local/conf/index.adoc[Configuration] * xref:local/help.adoc[Where to go for help] From 3749f7409ffd55705e954d7e9d010aa511fe5f13 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Thu, 18 Jun 2020 13:40:01 +0900 Subject: [PATCH 03/12] JAMES-3187 Added some notes (to remove) --- .../servers/pages/local/self-hosting.notes | 90 +++++++++++++++++++ 1 file changed, 90 insertions(+) create mode 100644 docs/modules/servers/pages/local/self-hosting.notes diff --git a/docs/modules/servers/pages/local/self-hosting.notes b/docs/modules/servers/pages/local/self-hosting.notes new file mode 100644 index 00000000000..d3cc88877b5 --- /dev/null +++ b/docs/modules/servers/pages/local/self-hosting.notes @@ -0,0 +1,90 @@ +The name of the project is "Jame Self Hosting Sandbox", and I see the term "self hosting" in a few places... So it sounds like it is important, but what is that intended to mean? + +I would like to understand better the intention behind the term. + + + +I would say "self hosting" means individuals having bought a domain name and want to install their own mail server for hosting their personal emails. Volumetry is small. They want control on their data. + +One generally tricky point about this kind of set up is getting third parties (like eg GMail) trusting your setup. It would be important to document a checklist regarding Mail Exchange trust like: + + I'm not an open spam relay + MX record registered for my domain + Reverse DNS setted up for MX servers + SPF records setted up + DKIM signature setted up +(which is slightly external to James as DNS setup is required) + + + +A "how to" regarding this is a MUST have in my opinion http://james.apache.org/howTo/index.html + + + +Just a thought based on the ideas you wrote here... + +But what if the mission of James were to "help people self-host their email" as an alternative to providers like gmail etc. + +Right now James is very obscure and is only for total tekkie geeks. If we modify the target, perhaps this could be the mission. + +The way of accomplishing this is: + +Provide in-depth "concept" articles +Provide more "how tos" for important things +Make James easier to install and operate +wdyt? + + +It would be more like: + +Apache James give you the ability to "self-host" email. Many companies and individuals are unable to develop their own mail infrastructure, but often feel trapped into using services like gmail, yahoo, etc. James provides a low-cost alternative for those who desire the freedom to use email the way they want. + +Or something like that. + + + +Apache James give you the ability to "self-host" email. Many companies and individuals are unable to develop their own mail infrastructure, but often feel trapped into using services like gmail, yahoo, etc. James provides a low-cost alternative for those who desire the freedom to use email the way they want. + +This should be the goal of the Basic server. + +Regarding "Advanced server": + +Free email servers are generaly old, written in complex languages (C) and extending their behavior is not one of there main concerns. + +Apache James Advanced server have been designed with extensibility in mind. It provides several extension mechanisms allowing you to easily configure and extend the behavior of your email server in order to make it fits your needs. Java and other JVM languages can be used to write your own extensions. +And for the Apache James Distributed server: + +Scaling out IMAP mail server is notoriously difficult, as Mail server generally relies on technologies that don't scale well. Apache James server had been designed on top of modern distributed middlewares that allow you to scale it out just like any other modern web applications, reducing the management overhead of large scale deployments. +We could be thinking of, regarding the testing server: + +Embed a tiny, zero external dependency, easy to configure, feature complete, testing mail server to test the email logics for your code. Could be run directly in your JVM tests or spawn via docker. +Would that go in your direction? + + +For the Basic server we should manage to be less "teckie oriented". + +However "Advanced servers" branding should be compelling for "teckies" and discourage other operators. + + +Very nice! + +That gives me an idea for the naming, then: + +Basic Server (for self-hosting - should be very simple) +Extendable Server (for customizing - can be more complex) +Advanced Server (for just about everything else, including "Distributed" - no holds barred) +wdyt? + + +In the wording above I really prefer the term Distributed Server to Advanced Server as (as my little description above in #9 (comment) demonstrates it) 'distributed server' addresses a all category of advanced users concerns. + +I prefer branding the "distributed" term as this is a selling argument. + + + +IMO the Advanced server should be configured as local per default but configurable to redundant if needed. + +Technically: let's use a default embedded derby database for it, but if needed the operator can connect it with a PostgresSQL server for instance. + + + From 607e1184261b8c854b53b6bc0db5e59c5d27246d Mon Sep 17 00:00:00 2001 From: David Leangen Date: Thu, 18 Jun 2020 13:47:45 +0900 Subject: [PATCH 04/12] JAMES-3187 Renamed "Local" to "Basic" --- docs/modules/servers/nav.adoc | 14 +++++++------- .../servers/pages/basic/architecture.adoc | 5 +++++ .../modules/servers/pages/basic/concepts.adoc | 5 +++++ .../pages/{local => basic}/conf/index.adoc | 2 +- .../servers/pages/basic/dependencies.adoc | 5 +++++ docs/modules/servers/pages/basic/help.adoc | 5 +++++ docs/modules/servers/pages/basic/index.adoc | 19 +++++++++++++++++++ .../pages/{local => basic}/objectives.adoc | 12 ++++++------ .../pages/{local => basic}/self-hosting.notes | 0 docs/modules/servers/pages/index.adoc | 10 +++++----- .../servers/pages/local/architecture.adoc | 5 ----- .../modules/servers/pages/local/concepts.adoc | 5 ----- .../servers/pages/local/dependencies.adoc | 5 ----- docs/modules/servers/pages/local/help.adoc | 5 ----- docs/modules/servers/pages/local/index.adoc | 19 ------------------- 15 files changed, 58 insertions(+), 58 deletions(-) create mode 100644 docs/modules/servers/pages/basic/architecture.adoc create mode 100644 docs/modules/servers/pages/basic/concepts.adoc rename docs/modules/servers/pages/{local => basic}/conf/index.adoc (99%) create mode 100644 docs/modules/servers/pages/basic/dependencies.adoc create mode 100644 docs/modules/servers/pages/basic/help.adoc create mode 100644 docs/modules/servers/pages/basic/index.adoc rename docs/modules/servers/pages/{local => basic}/objectives.adoc (76%) rename docs/modules/servers/pages/{local => basic}/self-hosting.notes (100%) delete mode 100644 docs/modules/servers/pages/local/architecture.adoc delete mode 100644 docs/modules/servers/pages/local/concepts.adoc delete mode 100644 docs/modules/servers/pages/local/dependencies.adoc delete mode 100644 docs/modules/servers/pages/local/help.adoc delete mode 100644 docs/modules/servers/pages/local/index.adoc diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 0d249ee22ad..a1de6e737d6 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -2,13 +2,13 @@ ** xref:demo.adoc[] *** xref:servers:5-minute-demo.adoc[] *** xref:servers:15-minute-demo.adoc[] -** xref:local/index.adoc[] -*** xref:local/objectives.adoc[] -*** xref:local/concepts.adoc[] -*** xref:local/architecture.adoc[] -*** xref:local/dependencies.adoc[] -*** xref:local/conf/index.adoc[] -*** xref:local/help.adoc[] +** xref:basic/index.adoc[] +*** xref:basic/objectives.adoc[] +*** xref:basic/concepts.adoc[] +*** xref:basic/architecture.adoc[] +*** xref:basic/dependencies.adoc[] +*** xref:basic/conf/index.adoc[] +*** xref:basic/help.adoc[] ** xref:redundant.adoc[] ** xref:distributed.adoc[] *** xref:distributed/architecture.adoc[] diff --git a/docs/modules/servers/pages/basic/architecture.adoc b/docs/modules/servers/pages/basic/architecture.adoc new file mode 100644 index 00000000000..73380919809 --- /dev/null +++ b/docs/modules/servers/pages/basic/architecture.adoc @@ -0,0 +1,5 @@ += James Basic Server — Architecture +:navtitle: Architecture + +(TODO) + diff --git a/docs/modules/servers/pages/basic/concepts.adoc b/docs/modules/servers/pages/basic/concepts.adoc new file mode 100644 index 00000000000..85edaf2c135 --- /dev/null +++ b/docs/modules/servers/pages/basic/concepts.adoc @@ -0,0 +1,5 @@ += James Basic Server — Concepts +:navtitle: Concepts + +(TODO) + diff --git a/docs/modules/servers/pages/local/conf/index.adoc b/docs/modules/servers/pages/basic/conf/index.adoc similarity index 99% rename from docs/modules/servers/pages/local/conf/index.adoc rename to docs/modules/servers/pages/basic/conf/index.adoc index 0ff251d0ed1..d99ec80b056 100644 --- a/docs/modules/servers/pages/local/conf/index.adoc +++ b/docs/modules/servers/pages/basic/conf/index.adoc @@ -1,4 +1,4 @@ -= James Local Mail Server Configuration += James Basic Mail Server Configuration :navtitle: Configuration == Configuration by feature diff --git a/docs/modules/servers/pages/basic/dependencies.adoc b/docs/modules/servers/pages/basic/dependencies.adoc new file mode 100644 index 00000000000..d3a3f64bd52 --- /dev/null +++ b/docs/modules/servers/pages/basic/dependencies.adoc @@ -0,0 +1,5 @@ += James Basic Server — Dependencies +:navtitle: Dependencies + +(TODO) + diff --git a/docs/modules/servers/pages/basic/help.adoc b/docs/modules/servers/pages/basic/help.adoc new file mode 100644 index 00000000000..b8466b3aa3f --- /dev/null +++ b/docs/modules/servers/pages/basic/help.adoc @@ -0,0 +1,5 @@ += James Basic Server — Where to get help +:navtitle: Help + +(TODO) + diff --git a/docs/modules/servers/pages/basic/index.adoc b/docs/modules/servers/pages/basic/index.adoc new file mode 100644 index 00000000000..394733d2552 --- /dev/null +++ b/docs/modules/servers/pages/basic/index.adoc @@ -0,0 +1,19 @@ += James Basic Mail Server +:navtitle: Basic + +If you are not sure which server you should be using, then +you probably ought to be using the Basic Server. + +At this time, the server is not entirely "out-of-the-box", because there +is some work you will have to do in order to get the server up and running. +However, the work that needs to be done is quite minimal. We will walk you +through the configuration in these documents. Hopefully in the near future +the installation will be made even simpler. + + * xref:basic/objectives.adoc[Objectives and motivation of the Basic Server] + * xref:basic/concepts.adoc[Useful background concepts] + * xref:basic/architecture.adoc[Overview of architecture] + * xref:basic/dependencies.adoc[Dependencies and requirements] + * xref:basic/conf/index.adoc[Configuration] + * xref:basic/help.adoc[Where to go for help] + diff --git a/docs/modules/servers/pages/local/objectives.adoc b/docs/modules/servers/pages/basic/objectives.adoc similarity index 76% rename from docs/modules/servers/pages/local/objectives.adoc rename to docs/modules/servers/pages/basic/objectives.adoc index e45db9b9b07..194d74d161c 100644 --- a/docs/modules/servers/pages/local/objectives.adoc +++ b/docs/modules/servers/pages/basic/objectives.adoc @@ -1,10 +1,10 @@ -= James Local Server — Objectives += James Basic Server — Objectives :navtitle: Objectives -The objective of the Local Server is to be as simple and minimalistic as possible, +The objective of the Basic Server is to be as simple and minimalistic as possible, while still being useful. Many people wish to have a basic mail server that they can customize, without necessarily requiring a complex distributed system. -The Local Server is intended to be an entry-level server that is accessible to +The Basic Server is intended to be an entry-level server that is accessible to those who want a mail server, but who don't want to have to learn about all the complexities of a new system. @@ -15,7 +15,7 @@ complexities. If you are not sure which of the James servers is best for you, you should probably choose this one. -The default configuration of the Local Server includes the following features: +The default configuration of the Basic Server includes the following features: * Secure SMTP (SSL/TLS) over port 465 * Secure IMAP4 (SSL/TLS) over port 993 @@ -29,6 +29,6 @@ The default configuration of the Local Server includes the following features: * Administration of users either via a command-line tool or the admin api -Optionally, more advanced users can adapt the Local Server to their needs by -updating the xref:local/conf/index.adoc[configuration files] and building a new Docker image +Optionally, more advanced users can adapt the Basic Server to their needs by +updating the xref:basic/conf/index.adoc[configuration files] and building a new Docker image (currently unsupported). diff --git a/docs/modules/servers/pages/local/self-hosting.notes b/docs/modules/servers/pages/basic/self-hosting.notes similarity index 100% rename from docs/modules/servers/pages/local/self-hosting.notes rename to docs/modules/servers/pages/basic/self-hosting.notes diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 6a4792477d6..860cd3e64af 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -9,7 +9,7 @@ a production-grade Mail Server that you can use with confidence. The available James Servers are: * <> - * <> + * <> * <> * <> @@ -20,11 +20,11 @@ The xref:demo.adoc[James Server Demo] is intended for those who just want to give James a quick spin on their local machine. -[#local] -== James Local Mail Server +[#basic] +== James Basic Mail Server If you are not sure which server you should be using, then -you probably ought to be using the xref:local/index.adoc[*Local Server*]. +you probably ought to be using the xref:basic/index.adoc[*BasicServer*]. This server uses the local file system to store emails, which tends to considerably simplify the system. To safeguard your emails, you only need a simple generic backup solution that works with a data @@ -36,7 +36,7 @@ have a huge amount of emails to process, then usually the simplicity is well worth the loss of some functionality. The last thing you need is to have to resolve difficult issues on a production server when you have not yet acquired the requisite knowledge to deal with those issues. Using the -xref:local/index.adoc[*Local Server*] will help you reduce the risk of running into +xref:basic/index.adoc[*Basic Server*] will help you reduce the risk of running into production issues. This server is: diff --git a/docs/modules/servers/pages/local/architecture.adoc b/docs/modules/servers/pages/local/architecture.adoc deleted file mode 100644 index bc5b64143ac..00000000000 --- a/docs/modules/servers/pages/local/architecture.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Local Server — Architecture -:navtitle: Architecture - -(TODO) - diff --git a/docs/modules/servers/pages/local/concepts.adoc b/docs/modules/servers/pages/local/concepts.adoc deleted file mode 100644 index e33c69816d9..00000000000 --- a/docs/modules/servers/pages/local/concepts.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Local Server — Concepts -:navtitle: Concepts - -(TODO) - diff --git a/docs/modules/servers/pages/local/dependencies.adoc b/docs/modules/servers/pages/local/dependencies.adoc deleted file mode 100644 index 415b1e8b031..00000000000 --- a/docs/modules/servers/pages/local/dependencies.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Local Server — Dependencies -:navtitle: Dependencies - -(TODO) - diff --git a/docs/modules/servers/pages/local/help.adoc b/docs/modules/servers/pages/local/help.adoc deleted file mode 100644 index 6c6267def65..00000000000 --- a/docs/modules/servers/pages/local/help.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Local Server — Where to get help -:navtitle: Help - -(TODO) - diff --git a/docs/modules/servers/pages/local/index.adoc b/docs/modules/servers/pages/local/index.adoc deleted file mode 100644 index df18cfb0fb5..00000000000 --- a/docs/modules/servers/pages/local/index.adoc +++ /dev/null @@ -1,19 +0,0 @@ -= James Local Mail Server -:navtitle: Local - -If you are not sure which server you should be using, then -you probably ought to be using the Local Server. - -At this time, the server is not entirely "out-of-the-box", because there -is some work you will have to do in order to get the server up and running. -However, the work that needs to be done is quite minimal. We will walk you -through the configuration in these documents. Hopefully in the near future -the installation will be made even simpler. - - * xref:local/objectives.adoc[Objectives and motivation of the Local Server] - * xref:local/concepts.adoc[Useful background concepts] - * xref:local/architecture.adoc[Overview of architecture] - * xref:local/dependencies.adoc[Dependencies and requirements] - * xref:local/conf/index.adoc[Configuration] - * xref:local/help.adoc[Where to go for help] - From 300f9323a90842af7d26a36bdd9cfdabb84e2271 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Thu, 18 Jun 2020 13:54:57 +0900 Subject: [PATCH 05/12] JAMES-3187 Changed "Redundant" to "Extendable" --- docs/modules/servers/nav.adoc | 2 +- docs/modules/servers/pages/extendable.adoc | 5 +++++ docs/modules/servers/pages/index.adoc | 8 ++++---- docs/modules/servers/pages/redundant.adoc | 5 ----- 4 files changed, 10 insertions(+), 10 deletions(-) create mode 100644 docs/modules/servers/pages/extendable.adoc delete mode 100644 docs/modules/servers/pages/redundant.adoc diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index a1de6e737d6..72a22e56e3e 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -9,7 +9,7 @@ *** xref:basic/dependencies.adoc[] *** xref:basic/conf/index.adoc[] *** xref:basic/help.adoc[] -** xref:redundant.adoc[] +** xref:extendable.adoc[] ** xref:distributed.adoc[] *** xref:distributed/architecture.adoc[] *** xref:distributed/run.adoc[] diff --git a/docs/modules/servers/pages/extendable.adoc b/docs/modules/servers/pages/extendable.adoc new file mode 100644 index 00000000000..565d49f98eb --- /dev/null +++ b/docs/modules/servers/pages/extendable.adoc @@ -0,0 +1,5 @@ += James Extendable Mail Server +:navtitle: Extendable + +(TODO) + diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 860cd3e64af..01d37f8ce29 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -10,7 +10,7 @@ The available James Servers are: * <> * <> - * <> + * <> * <> @@ -50,12 +50,12 @@ This server is: -[#redundant] -== James Redundant Mail Server +[#extendable] +== James Extendable Mail Server When your requirements start to get a little more serious (let's say in the tens of millions of emails), then you may want to -start to consider using the xref:redundant.adoc[*Redundant Server*]. +start to consider using the xref:extendable.adoc[*Extendable Server*]. This server provides data redundancy so that it can stay live at all times, even in the rare case that your data gets corrupted. diff --git a/docs/modules/servers/pages/redundant.adoc b/docs/modules/servers/pages/redundant.adoc deleted file mode 100644 index 659034ac824..00000000000 --- a/docs/modules/servers/pages/redundant.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Redundant Mail Server -:navtitle: Redundant - -(TODO) - From 4e7b039597315abf384bde31909d37eceb770c78 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Thu, 18 Jun 2020 13:55:12 +0900 Subject: [PATCH 06/12] JAMES-3187 Added stub for Test Server --- docs/modules/servers/nav.adoc | 1 + docs/modules/servers/pages/index.adoc | 6 ++++++ docs/modules/servers/pages/test.adoc | 5 +++++ 3 files changed, 12 insertions(+) create mode 100644 docs/modules/servers/pages/test.adoc diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 72a22e56e3e..76a139d3294 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -26,3 +26,4 @@ **** xref:distributed/extend/mailbox-listeners.adoc[] **** xref:distributed/extend/smtp-hooks.adoc[] **** xref:distributed/extend/webadmin-routes.adoc[] +** xref:test.adoc[] diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index 01d37f8ce29..f9b8093d4ec 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -12,6 +12,7 @@ The available James Servers are: * <> * <> * <> + * <> [#demo] @@ -82,3 +83,8 @@ This server is: * The most feature-rich server, but also by far the most complex + +[#test] +== James Test Server + +The xref:test.adoc[*Test Server*] is, as the name suggests, for testing purposes. diff --git a/docs/modules/servers/pages/test.adoc b/docs/modules/servers/pages/test.adoc new file mode 100644 index 00000000000..a6820d8bf43 --- /dev/null +++ b/docs/modules/servers/pages/test.adoc @@ -0,0 +1,5 @@ += James Test Server +:navtitle: Test + +(TODO) + From 363cbe1cc3373c96c7a6a9b5f5159e59cf03972f Mon Sep 17 00:00:00 2001 From: David Leangen Date: Thu, 18 Jun 2020 21:13:28 +0900 Subject: [PATCH 07/12] JAMES-3187 Updated contents relating to Basic Server --- docs/modules/servers/nav.adoc | 2 +- .../servers/pages/basic/architecture.adoc | 3 +- .../modules/servers/pages/basic/concepts.adoc | 12 ++- .../servers/pages/basic/conf/.index.adoc.swp | Bin 0 -> 28672 bytes .../servers/pages/basic/conf/index.adoc | 55 ++++++++++++ docs/modules/servers/pages/basic/context.adoc | 25 ++++++ .../servers/pages/basic/dependencies.adoc | 5 -- docs/modules/servers/pages/basic/index.adoc | 20 +++-- .../servers/pages/basic/objectives.adoc | 23 +++-- docs/modules/servers/pages/index.adoc | 79 ++++++++---------- 10 files changed, 150 insertions(+), 74 deletions(-) create mode 100644 docs/modules/servers/pages/basic/conf/.index.adoc.swp create mode 100644 docs/modules/servers/pages/basic/context.adoc delete mode 100644 docs/modules/servers/pages/basic/dependencies.adoc diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index 76a139d3294..d5a9b28cca2 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -3,10 +3,10 @@ *** xref:servers:5-minute-demo.adoc[] *** xref:servers:15-minute-demo.adoc[] ** xref:basic/index.adoc[] +*** xref:basic/context.adoc[] *** xref:basic/objectives.adoc[] *** xref:basic/concepts.adoc[] *** xref:basic/architecture.adoc[] -*** xref:basic/dependencies.adoc[] *** xref:basic/conf/index.adoc[] *** xref:basic/help.adoc[] ** xref:extendable.adoc[] diff --git a/docs/modules/servers/pages/basic/architecture.adoc b/docs/modules/servers/pages/basic/architecture.adoc index 73380919809..330236de08e 100644 --- a/docs/modules/servers/pages/basic/architecture.adoc +++ b/docs/modules/servers/pages/basic/architecture.adoc @@ -1,5 +1,4 @@ = James Basic Server — Architecture :navtitle: Architecture -(TODO) - +[Please help] diff --git a/docs/modules/servers/pages/basic/concepts.adoc b/docs/modules/servers/pages/basic/concepts.adoc index 85edaf2c135..e66f1e379ea 100644 --- a/docs/modules/servers/pages/basic/concepts.adoc +++ b/docs/modules/servers/pages/basic/concepts.adoc @@ -1,5 +1,13 @@ -= James Basic Server — Concepts += James Basic Server — Background Concepts :navtitle: Concepts -(TODO) +Before embarking on your adventure with the **James Basic Server**, we +highly recommend that you familiarize yourself with the following concepts: +[TODO: provide links and ensure that articles exist for each of these topics] + + * James User Model + * SMTP + * IMAP + * Secured email communications + * Email storage diff --git a/docs/modules/servers/pages/basic/conf/.index.adoc.swp b/docs/modules/servers/pages/basic/conf/.index.adoc.swp new file mode 100644 index 0000000000000000000000000000000000000000..fe7c82d1264781933eeda62a2ece58a5045a16d0 GIT binary patch literal 28672 zcmeI4e~cu@RmaF)Ply{dXu^?r0?_x-DDYJY9F!`~Yn=jI3g`InNH z{`z$vdDU@RzIKC-4&>7L{*tim1!2t(o34Mp`+g-OSogg~TtDshbiCM)!qd8$)LUUQ zuJ^*$z}Im-*3qVp;(Fih@U7v-UbEf|gLd5uT6(MIa`X8ZRo5yFR2rC~foq+;OMA>z zzxk%0R5x6IV#+<$Pn8BL4OAMaG*D@v(mP-&pjK&6371C<6U4P1f-+?L~PzQJ*x0TTbu&i{XPo#Q+Q{s?>;dA#fe|@->e0J0Jx6!MAZ1{3&=0oB~I|?chg&177CP|9S8U zunktgRp2>3^YxDNb?|xc6gUeW0C$3Gz{@|(HSi?(0MOu0@MiE| zI4fQRPl89l!=MW~;1GB#xDtE|r^T1Rv)~C3f&*XyTn+vWr^x5P6JQIR0{g(#;2StJ z{t^5G_$s&s{1kW_xEWjlE(hmuygUOwhQsBfnbRfTkM~BQ0|tFX0z@48Udv6qFj!XW zVNa_t>bQaTUh`9|V%_QKAW=zIdy(>jL`Q+^tHvPq0v*RXmfu2d>${PgXw?dPt{24I z?Mbh8_Hh}BEjg*TJZIN)BXK6t@3VUOTI?~cuxav(EjDIh*v*tJ(U7iemKOA~N zN5xGYxRDperV)C}?e)nbQDIwk!=c&^2SzXv%WbtHWTGX*$V+&3*>ToKPq*Paaffuq z;og=aQ6&kRp|5B)q*|)6tqw~Hi)#9wG|=eVZ6-r6=}H5UUb0wfN}lGSGeI~E{P z-dHyWkzP=4&{9LKy6z^@(E#Bi2{Ce`l~NmG!bIdVSu-hV=}&ak(sYvC?Qcup4Ryn9 z^}L|w+;x{a8YViX1?o0+Qa5NF7u5Xd7MS&Qlz2McCAX}5s9m)^pOF)*`JNj{@5zs8 zTef<>xp9r&ZG>B$&|BjT3xVaS}%GQ1hrXiX+_* zV~?M+`QAbi(+HQ#FGX0B}@Qrt_*A_+5{n3l_b z7~BaHgg(p~bNJ+jnm;{EPW1;3-)o-H+eRJt4!kB~ehV$c%mWCF|6gW)P}(pafNDO{ zO|S1Ur_%0D+=f4Hl^tRSj;zABw^b%~B|)7 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 Tyy@u$nR~{j0bKCC9M1m$UqNE7 literal 0 HcmV?d00001 diff --git a/docs/modules/servers/pages/basic/conf/index.adoc b/docs/modules/servers/pages/basic/conf/index.adoc index d99ec80b056..18eb8b44fb7 100644 --- a/docs/modules/servers/pages/basic/conf/index.adoc +++ b/docs/modules/servers/pages/basic/conf/index.adoc @@ -1,6 +1,60 @@ = James Basic Mail Server Configuration :navtitle: Configuration +== JIRA Issues + +* dnsservice.xml - DNS Service Configuration -> https://issues.apache.org/jira/browse/JAMES-3219 + ** Status: to be removed +* domainlist.xml - Domain List Configuration -> https://issues.apache.org/jira/browse/JAMES-3220 + ** Status: to be removed +* events.xml - Event system Configuration (Spring only) + ** Status: Spring only, so n/a +* fetchmail.xml- FetchMail Configuration (Spring only) + ** Status: Spring only, so n/a +* imapserver.xml - IMAP4 Configuration -> https://issues.apache.org/jira/browse/JAMES-3229 + ** Status: +* jmap.properties - JMAP Configuration (Guice only) -> https://issues.apache.org/jira/browse/JAMES-3230 + ** Status: +* lmtpserver.xml - LMTP Configuration -> https://issues.apache.org/jira/browse/JAMES-3231 + ** Status: +* mailrepositorystore.xml - Mail Repository Stores Configuration -> https://issues.apache.org/jira/browse/JAMES-3232 + ** Status: +* mailbox.xml - Mailbox Configuration (Spring only) + ** Status: Spring only, so n/a +* mailetcontainer.xml - Mailet Container Configuration -> https://issues.apache.org/jira/browse/JAMES-3233 + ** Status: +* pop3server.xml - POP3 Configuration -> https://issues.apache.org/jira/browse/JAMES-3234 + ** Status: +* mailbox.xml - Quota Configuration (Spring only) + ** Status: Spring only, so n/a +* recipientrewritetable.xml - Recipient Rewrite Table Configuration -> https://issues.apache.org/jira/browse/JAMES-3235 + ** Status: +* smtpserver.xml - SMTP Configuration -> https://issues.apache.org/jira/browse/JAMES-3236 + ** Status: +* usersrepository.xml - Users Configuration -> https://issues.apache.org/jira/browse/JAMES-3237 + ** Status: +* webadmin.properties - WebAdmin Configuration -> https://issues.apache.org/jira/browse/JAMES-3238 + ** Status: +* jmx.properties -> https://issues.apache.org/jira/browse/JAMES-3240 + ** Status: +* extensions.properties -> https://issues.apache.org/jira/browse/JAMES-3241 + ** Status: +* jwt_publickey -> https://issues.apache.org/jira/browse/JAMES-3242a + ** Status: +* healthcheck.properties -> https://issues.apache.org/jira/browse/JAMES-3243 + ** Status: +* listeners.xml -> https://issues.apache.org/jira/browse/JAMES-3244 + ** Status: +* managesieveserver.xml -> https://issues.apache.org/jira/browse/JAMES-3245 + ** Status: +* spring-server.xml - System Configuration + ** Status: Spring only, so n/a +* james-database.properties & META-INF/persistence.xml -> https://issues.apache.org/jira/browse/JAMES-3246 + ** Status: +* log4j.properties & logback.xml -> https://issues.apache.org/jira/browse/JAMES-3239 + ** Status: + + == Configuration by feature * Domain names — provide the default domain names that ???? @@ -8,6 +62,7 @@ * LMTP (lmtpserver.xml) * POP3 (pop3server.xml) * DNS (dnsservice.xml) + ** Waiting for confirmation: can this be removed from Basic? * Loggin (logback.xml) * James CLI (jmx.properties) * Email rewriting (recipientrewritetable.xml) diff --git a/docs/modules/servers/pages/basic/context.adoc b/docs/modules/servers/pages/basic/context.adoc new file mode 100644 index 00000000000..f56f8228b28 --- /dev/null +++ b/docs/modules/servers/pages/basic/context.adoc @@ -0,0 +1,25 @@ += James Basic Server — Context +:navtitle: Context + +Email has been around in one form or another for more than 50 years. +It is arguably one of the most resilient applications or our day, and +may even be called **THE** killer app of our time. Most of us, if not +all but the most unfortunate, use email on a regular basis. If you are +reading this page over the web, it is almost 100% certain that you have +used and continue to use email. + +Despite its ubiquity, the vast majority of people do not control their +own email infrastructure. Although, unlike telecommunications or electricity +for example, the barriers to owning and maintaining your own infrastructure +are very low, individuals and companies alike usually defer to the large +email providers for this essential service. +Although relying on the big providers is easy, what they offer is often +limited and in some cases much more costly than it ought to be. + +The Apache James Community is dedicated to liberating email. Our missing +is to make email hosting both easy and fun. We do this by: + + * Providing an easy-to-use self-hosted server for amateur Operators + * Providing an extendable server for those more experienced Operators + * Providing a distributed solution for heavy-duty projects + * Ensuring that James remains a flexible, reliable technology platform diff --git a/docs/modules/servers/pages/basic/dependencies.adoc b/docs/modules/servers/pages/basic/dependencies.adoc deleted file mode 100644 index d3a3f64bd52..00000000000 --- a/docs/modules/servers/pages/basic/dependencies.adoc +++ /dev/null @@ -1,5 +0,0 @@ -= James Basic Server — Dependencies -:navtitle: Dependencies - -(TODO) - diff --git a/docs/modules/servers/pages/basic/index.adoc b/docs/modules/servers/pages/basic/index.adoc index 394733d2552..76659112f9d 100644 --- a/docs/modules/servers/pages/basic/index.adoc +++ b/docs/modules/servers/pages/basic/index.adoc @@ -1,19 +1,21 @@ = James Basic Mail Server :navtitle: Basic -If you are not sure which server you should be using, then -you probably ought to be using the Basic Server. +The **James Basic Server** is intended for xref:concepts:user/index.adoc#Operator[Operators] +who are just getting initiated with operating their own +xref:concepts/???[Self-Hosted] mail server. -At this time, the server is not entirely "out-of-the-box", because there -is some work you will have to do in order to get the server up and running. -However, the work that needs to be done is quite minimal. We will walk you -through the configuration in these documents. Hopefully in the near future -the installation will be made even simpler. +The server is intended to be a mostly "out-of-the-box" solution. +With a few small interactions necessary to configure the system, you should +be up and running in no time with all the standard features. +These documents will present all the concepts that underpin this server, +and will walk you through its installation and configuration. If you run into +trouble, we explain how you can get help from the James Community. + + * xref:basic/context.adoc[The context of contemporary email] * xref:basic/objectives.adoc[Objectives and motivation of the Basic Server] * xref:basic/concepts.adoc[Useful background concepts] * xref:basic/architecture.adoc[Overview of architecture] - * xref:basic/dependencies.adoc[Dependencies and requirements] * xref:basic/conf/index.adoc[Configuration] * xref:basic/help.adoc[Where to go for help] - diff --git a/docs/modules/servers/pages/basic/objectives.adoc b/docs/modules/servers/pages/basic/objectives.adoc index 194d74d161c..1ae7dad3206 100644 --- a/docs/modules/servers/pages/basic/objectives.adoc +++ b/docs/modules/servers/pages/basic/objectives.adoc @@ -2,16 +2,15 @@ :navtitle: Objectives The objective of the Basic Server is to be as simple and minimalistic as possible, -while still being useful. Many people wish to have a basic mail server that they -can customize, without necessarily requiring a complex distributed system. +while still being useful. Many people wish to have a basic self-hosted mail server that they +can use without having to become a deep technical expert. The Basic Server is intended to be an entry-level server that is accessible to -those who want a mail server, but who don't want to have to learn about all the -complexities of a new system. +those who want a self-hosted mail server, but who don't want to have to learn about all the +complexities of email communications. This server is therefore intended to be the simplest to set up and use in production. -Of all the James Servers, it has the least amount of dependencies and -complexities. +Of all the James Servers, it has the least amount of dependencies and configurations. If you are not sure which of the James servers is best for you, you should probably choose this one. @@ -22,13 +21,11 @@ The default configuration of the Basic Server includes the following features: * Local Mailbox support ** Files are stored locally on the filesystem ** Optionally use a volume if you are a Docker or Kubernetes user - ** Data can be backed up simply by backing up the filesystem / volume * Multi-domain (virtual domain) support - ** Up to xxx domains - ** Up to yyy users per domain * Administration of users either via a command-line tool or the admin api + * ????? What else should go here? ????? - -Optionally, more advanced users can adapt the Basic Server to their needs by -updating the xref:basic/conf/index.adoc[configuration files] and building a new Docker image -(currently unsupported). +We have disabled all of the insecure communications and require SSL. If you have +a specific requirement to use an insecure protocol, or if the above list does not +satisfy your needs, then after having successfully set up this server you may want +to move on to the xref:extendable.adoc[Extendable Server]. diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc index f9b8093d4ec..48e548017b2 100644 --- a/docs/modules/servers/pages/index.adoc +++ b/docs/modules/servers/pages/index.adoc @@ -1,10 +1,14 @@ = Apache James Mail Servers :navtitle: Servers -James offers a number of ready-made Mail Servers. The servers are intended -for those with typcial use cases, and can be used out-of-the-box. These -servers have been tested and verified so you can get set up quickly with -a production-grade Mail Server that you can use with confidence. +James offers five types of ready-made Mail Servers. The servers are intended +for those with different needs, ranging from xref:concepts:user/index.adoc#Operators[Operators] +who are interested in setting up a server for the first time, to experienced teams of +xref:concepts:user/index.adoc#Developer[Developers] +looking to deploy an advanced distributed system. +Each of the servers has been tested and verified so you can +deploy a production-grade +xref:concepts/insert-link[Mail Server] with confidence. The available James Servers are: @@ -12,61 +16,55 @@ The available James Servers are: * <> * <> * <> - * <> + * <> +If you are just checking out James for the first time, then we highly recommend +investigating the servers in this order: + +. Initiate yourself with James by using the <> +. Install the <> +. If and only if the Basic Server is not enough, then try the <> [#demo] == James Demo Server -The xref:demo.adoc[James Server Demo] is intended for those who just want -to give James a quick spin on their local machine. +The xref:demo.adoc[Demo Server] is intended for those who just want +to give James a quick spin on their local machine to see what all +the fuss is about. + [#basic] == James Basic Mail Server -If you are not sure which server you should be using, then -you probably ought to be using the xref:basic/index.adoc[*BasicServer*]. -This server uses the local file system to store emails, which tends -to considerably simplify the system. To safeguard your emails, you -only need a simple generic backup solution that works with a data -volume. +If you just want to get up and running quickly, if you have very simple needs, +or you want to try deploying a mail server for the first time, then the +xref:basic/index.adoc[*Basic Server*] is the right choice for you. If you are +not sure which server you should be using, then this server is probably the right +choice. This server is intended to be the simplest to set up and use in production. -It has the least amount of dependencies and complexities. If you do not yet -have a huge amount of emails to process, then usually the simplicity is -well worth the loss of some functionality. The last thing you need is +It has the least amount of complexity and configurations to worry about. +The last thing you need is to have to resolve difficult issues on a production server when you have not yet acquired the requisite knowledge to deal with those issues. Using the xref:basic/index.adoc[*Basic Server*] will help you reduce the risk of running into production issues. -This server is: - - * Suggested for use with smaller deployments - * Appropriate for use by most operators - * The preferred choice for most installations - * Endowed with fewer dependencies, which makes it simpler and less risky to use in production - * Only dependent on your local file system for data storage, so very easy to manage - - [#extendable] == James Extendable Mail Server -When your requirements start to get a little more serious -(let's say in the tens of millions of emails), then you may want to -start to consider using the xref:extendable.adoc[*Extendable Server*]. - -This server provides data redundancy so that it can stay live at -all times, even in the rare case that your data gets corrupted. - -This server is: - - * Intended for use by experienced operators only - * Used for mid-sized to large deployments - * More performant than the Minimal and Basic Server, but also more complex +When your requirements start to get a little more serious, or you +start to feel adventurous and want to begin your own email adventure, +you can consider using the xref:extendable.adoc[*Extendable Server*]. +This server is intended for experts who understand the consequences of +what they are doing. It provides extension mechanisms, configurations, +and integration points to customize its behavior. Unless you are processing +millions of emails on a daily basis (in which case you should consider the +<>), this server should cover just about +any email needs you may have. @@ -76,11 +74,8 @@ This server is: The xref:distributed.adoc[*Distributed Server*] is a heavy-duty industrial enterprise mail server. -This server is: - - * Intended for use by experts only - * Use for large-scale distributed deployments - * The most feature-rich server, but also by far the most complex +This is the most feature-rich server, but also by far the most complex, +and is intended for experts only. From 72b5f92b8b8ca9db455a54444750c574098ec26d Mon Sep 17 00:00:00 2001 From: David Leangen Date: Fri, 19 Jun 2020 20:37:58 +0900 Subject: [PATCH 08/12] JAMES-3187 Update docs/modules/servers/pages/basic/conf/index.adoc. Co-authored-by: Rene Cordier --- docs/modules/servers/pages/basic/conf/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/servers/pages/basic/conf/index.adoc b/docs/modules/servers/pages/basic/conf/index.adoc index 18eb8b44fb7..d55c0b645db 100644 --- a/docs/modules/servers/pages/basic/conf/index.adoc +++ b/docs/modules/servers/pages/basic/conf/index.adoc @@ -102,7 +102,7 @@ == Notes -Jmx protocol is used by James cli to interactwith the server. Jmx is known to be insecure, and we have as a project to rewrite the cli for james servers in order to rely on webadmin. +Jmx protocol is used by James cli to interact with the server. Jmx is known to be insecure, and we have as a project to rewrite the cli for james servers in order to rely on webadmin. From fd5805aba01e3729d7dccbd4881cdd1915d1edd9 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Fri, 19 Jun 2020 20:42:02 +0900 Subject: [PATCH 09/12] JAMES-3187 Update docs/modules/servers/pages/basic/context.adoc. Co-authored-by: Rene Cordier --- docs/modules/servers/pages/basic/context.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/servers/pages/basic/context.adoc b/docs/modules/servers/pages/basic/context.adoc index f56f8228b28..f4704a9b0d2 100644 --- a/docs/modules/servers/pages/basic/context.adoc +++ b/docs/modules/servers/pages/basic/context.adoc @@ -16,7 +16,7 @@ email providers for this essential service. Although relying on the big providers is easy, what they offer is often limited and in some cases much more costly than it ought to be. -The Apache James Community is dedicated to liberating email. Our missing +The Apache James Community is dedicated to liberating email. Our mission is to make email hosting both easy and fun. We do this by: * Providing an easy-to-use self-hosted server for amateur Operators From ad1e11d12c9675331f36bc1639bd7818b0c2c338 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Sat, 20 Jun 2020 11:45:23 +0900 Subject: [PATCH 10/12] JAMES-3187 Added help contents --- .../servers/pages/basic/conf/.index.adoc.swp | Bin 28672 -> 0 bytes .../servers/pages/basic/conf/index.adoc | 3 -- docs/modules/servers/pages/basic/help.adoc | 51 +++++++++++++++++- .../servers/pages/basic/self-hosting.notes | 6 +++ 4 files changed, 56 insertions(+), 4 deletions(-) delete mode 100644 docs/modules/servers/pages/basic/conf/.index.adoc.swp diff --git a/docs/modules/servers/pages/basic/conf/.index.adoc.swp b/docs/modules/servers/pages/basic/conf/.index.adoc.swp deleted file mode 100644 index fe7c82d1264781933eeda62a2ece58a5045a16d0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 28672 zcmeI4e~cu@RmaF)Ply{dXu^?r0?_x-DDYJY9F!`~Yn=jI3g`InNH z{`z$vdDU@RzIKC-4&>7L{*tim1!2t(o34Mp`+g-OSogg~TtDshbiCM)!qd8$)LUUQ zuJ^*$z}Im-*3qVp;(Fih@U7v-UbEf|gLd5uT6(MIa`X8ZRo5yFR2rC~foq+;OMA>z zzxk%0R5x6IV#+<$Pn8BL4OAMaG*D@v(mP-&pjK&6371C<6U4P1f-+?L~PzQJ*x0TTbu&i{XPo#Q+Q{s?>;dA#fe|@->e0J0Jx6!MAZ1{3&=0oB~I|?chg&177CP|9S8U zunktgRp2>3^YxDNb?|xc6gUeW0C$3Gz{@|(HSi?(0MOu0@MiE| zI4fQRPl89l!=MW~;1GB#xDtE|r^T1Rv)~C3f&*XyTn+vWr^x5P6JQIR0{g(#;2StJ z{t^5G_$s&s{1kW_xEWjlE(hmuygUOwhQsBfnbRfTkM~BQ0|tFX0z@48Udv6qFj!XW zVNa_t>bQaTUh`9|V%_QKAW=zIdy(>jL`Q+^tHvPq0v*RXmfu2d>${PgXw?dPt{24I z?Mbh8_Hh}BEjg*TJZIN)BXK6t@3VUOTI?~cuxav(EjDIh*v*tJ(U7iemKOA~N zN5xGYxRDperV)C}?e)nbQDIwk!=c&^2SzXv%WbtHWTGX*$V+&3*>ToKPq*Paaffuq z;og=aQ6&kRp|5B)q*|)6tqw~Hi)#9wG|=eVZ6-r6=}H5UUb0wfN}lGSGeI~E{P z-dHyWkzP=4&{9LKy6z^@(E#Bi2{Ce`l~NmG!bIdVSu-hV=}&ak(sYvC?Qcup4Ryn9 z^}L|w+;x{a8YViX1?o0+Qa5NF7u5Xd7MS&Qlz2McCAX}5s9m)^pOF)*`JNj{@5zs8 zTef<>xp9r&ZG>B$&|BjT3xVaS}%GQ1hrXiX+_* zV~?M+`QAbi(+HQ#FGX0B}@Qrt_*A_+5{n3l_b z7~BaHgg(p~bNJ+jnm;{EPW1;3-)o-H+eRJt4!kB~ehV$c%mWCF|6gW)P}(pafNDO{ zO|S1Ur_%0D+=f4Hl^tRSj;zABw^b%~B|)7 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 Tyy@u$nR~{j0bKCC9M1m$UqNE7 diff --git a/docs/modules/servers/pages/basic/conf/index.adoc b/docs/modules/servers/pages/basic/conf/index.adoc index d55c0b645db..7eb0619bd84 100644 --- a/docs/modules/servers/pages/basic/conf/index.adoc +++ b/docs/modules/servers/pages/basic/conf/index.adoc @@ -149,6 +149,3 @@ Address rewriting changes an email address by rewriting specific fields in the m https://www.exim.org/exim-html-current/doc/html/spec_html/ch-address_rewriting.html - -:wq - diff --git a/docs/modules/servers/pages/basic/help.adoc b/docs/modules/servers/pages/basic/help.adoc index b8466b3aa3f..7a7f0698a05 100644 --- a/docs/modules/servers/pages/basic/help.adoc +++ b/docs/modules/servers/pages/basic/help.adoc @@ -1,5 +1,54 @@ = James Basic Server — Where to get help :navtitle: Help -(TODO) +//// +This information is based on the email discussion from here: + --> https://www.mail-archive.com/server-dev@james.apache.org/msg66420.html + +However, I am not satisfied that I have properly captured the community's +opinion, and there are only a few people who have contributed to the +thread. + +Would be good to have some comments on this content. + +It could just be that I don't like the content. But if that is what the +community thinks, then that is what we should write. + +//// + +== Warning + +Please note that if you want to try to use James, you are pretty +much on your own. + +James is intended for use only by the current committers, or perhaps only by +competent developers only who have the ability to understand the code as it +exists now and can make changes themselves without any help. What you see +is what you get. Take it or leave it. + +The James Community is made up of people who "scratch their own itch". +If you have a problem with the code or the documentation, then please +step up and fix it rather than asking for help. + +If you are a user who wants to try to use James, you should seriously +consider hiring a professional organization to help you. Most likely, +James is not for you. + +You can try filing issues, but there is absolutely no guarantee it will be +fixed. If you are lucky and a developer has the same problem as you, then +it may be fixed. Or if one of the developers is feeling particularly generous and wants +to volunteer their valuable time to help you, it may happen. There is no +way to know unless you try. + +On the other hand, the developers would **love** for you to do stuff that +they are not interested in doing, like documentation. If you don't know anything +about the code, it would be a good way to help out until you can eventually +join the exclusive committer club, too. + + +== Communications + + * Mailing List + * Glitter + * Anything else?? diff --git a/docs/modules/servers/pages/basic/self-hosting.notes b/docs/modules/servers/pages/basic/self-hosting.notes index d3cc88877b5..279d640c990 100644 --- a/docs/modules/servers/pages/basic/self-hosting.notes +++ b/docs/modules/servers/pages/basic/self-hosting.notes @@ -88,3 +88,9 @@ Technically: let's use a default embedded derby database for it, but if needed t + +https://dmatthews.org/email_auth.html +https://dmatthews.org/java_email.html + + + From dce0a5c3de402e96931f3d1f7ceca0efda7bd6a8 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Sat, 15 Aug 2020 10:51:22 +0900 Subject: [PATCH 11/12] JAMES-3187 Tidy up a bit in preparation for merge --- docs/modules/servers/pages/basic/architecture.adoc | 2 +- docs/modules/servers/pages/basic/concepts.adoc | 9 +++++---- docs/modules/servers/pages/basic/conf/index.adoc | 5 ++++- docs/modules/servers/pages/basic/help.adoc | 10 ++++------ docs/modules/servers/pages/basic/objectives.adoc | 1 - 5 files changed, 14 insertions(+), 13 deletions(-) diff --git a/docs/modules/servers/pages/basic/architecture.adoc b/docs/modules/servers/pages/basic/architecture.adoc index 330236de08e..706900ac8f8 100644 --- a/docs/modules/servers/pages/basic/architecture.adoc +++ b/docs/modules/servers/pages/basic/architecture.adoc @@ -1,4 +1,4 @@ = James Basic Server — Architecture :navtitle: Architecture -[Please help] +(TODO) diff --git a/docs/modules/servers/pages/basic/concepts.adoc b/docs/modules/servers/pages/basic/concepts.adoc index e66f1e379ea..e68c0c1290e 100644 --- a/docs/modules/servers/pages/basic/concepts.adoc +++ b/docs/modules/servers/pages/basic/concepts.adoc @@ -6,8 +6,9 @@ highly recommend that you familiarize yourself with the following concepts: [TODO: provide links and ensure that articles exist for each of these topics] - * James User Model - * SMTP - * IMAP + * xref:concepts:user/index.adoc[James User Model] + * xref:concepts:protocols/smtp.adoc[SMTP] + * xref:concepts:protocols/imap.adoc[IMAP] +// What link should go here?? * Secured email communications - * Email storage + * xref:concepts:/storage/index.adoc[Email storage] diff --git a/docs/modules/servers/pages/basic/conf/index.adoc b/docs/modules/servers/pages/basic/conf/index.adoc index 7eb0619bd84..e4817a9e570 100644 --- a/docs/modules/servers/pages/basic/conf/index.adoc +++ b/docs/modules/servers/pages/basic/conf/index.adoc @@ -1,6 +1,9 @@ = James Basic Mail Server Configuration :navtitle: Configuration +(Work in progress.) + +//// == JIRA Issues * dnsservice.xml - DNS Service Configuration -> https://issues.apache.org/jira/browse/JAMES-3219 @@ -148,4 +151,4 @@ Address rewriting changes an email address by rewriting specific fields in the m https://www.exim.org/exim-html-current/doc/html/spec_html/ch-address_rewriting.html - +//// diff --git a/docs/modules/servers/pages/basic/help.adoc b/docs/modules/servers/pages/basic/help.adoc index 7a7f0698a05..f4578cd7078 100644 --- a/docs/modules/servers/pages/basic/help.adoc +++ b/docs/modules/servers/pages/basic/help.adoc @@ -17,6 +17,8 @@ community thinks, then that is what we should write. //// +//// +Comment this out until there is agreement. == Warning Please note that if you want to try to use James, you are pretty @@ -45,10 +47,6 @@ On the other hand, the developers would **love** for you to do stuff that they are not interested in doing, like documentation. If you don't know anything about the code, it would be a good way to help out until you can eventually join the exclusive committer club, too. +//// - -== Communications - - * Mailing List - * Glitter - * Anything else?? +(Redo this once there is consensus in the community.) diff --git a/docs/modules/servers/pages/basic/objectives.adoc b/docs/modules/servers/pages/basic/objectives.adoc index 1ae7dad3206..e8f95e3cdb1 100644 --- a/docs/modules/servers/pages/basic/objectives.adoc +++ b/docs/modules/servers/pages/basic/objectives.adoc @@ -23,7 +23,6 @@ The default configuration of the Basic Server includes the following features: ** Optionally use a volume if you are a Docker or Kubernetes user * Multi-domain (virtual domain) support * Administration of users either via a command-line tool or the admin api - * ????? What else should go here? ????? We have disabled all of the insecure communications and require SSL. If you have a specific requirement to use an insecure protocol, or if the above list does not From b22bd8eb9719784bfa2cf79a964aba6fa6675d98 Mon Sep 17 00:00:00 2001 From: David Leangen Date: Sat, 15 Aug 2020 11:26:48 +0900 Subject: [PATCH 12/12] JAMES-3187 Added some notes from chibenwa --- .../servers/pages/basic/conf/index.adoc | 59 +++++++++++++++++++ 1 file changed, 59 insertions(+) diff --git a/docs/modules/servers/pages/basic/conf/index.adoc b/docs/modules/servers/pages/basic/conf/index.adoc index e4817a9e570..4666e3d2577 100644 --- a/docs/modules/servers/pages/basic/conf/index.adoc +++ b/docs/modules/servers/pages/basic/conf/index.adoc @@ -48,6 +48,43 @@ ** Status: * listeners.xml -> https://issues.apache.org/jira/browse/JAMES-3244 ** Status: +---- +Comment from chibenwa: +chibenwa on Jun 15 Member +Mailbox listeners allows to react upon users mailbox events like "message added", "message deleted"... + + @dleangen +dleangen on Jun 15 Author Member +Thanks! + + @dleangen +dleangen on Jun 15 Author Member +Sorry, are these the same as SMTP Hooks that are described on the old website? + +Where can I find examples of these? + + @chibenwa +chibenwa on Jun 15 Member +No it is different. + +SMTP hooks are to add functionalities to the SMTP protocols. + +Here MailboxListener allow to react upon any mailbox changes whatever the protocol. + +See http://james.apache.org/server/config-listeners.html + + @dleangen +dleangen on Jun 15 Author Member +Ah, hehe. Ok, makes sense. I read the page at the url you pasted. + +Are there any examples anywhere? + + @mbaechler +mbaechler on Jun 16 Member +If you look at example of users in the code, the quota-search feature is a good example : https://github.com/apache/james-project/blob/master/mailbox/plugin/quota-search-elasticsearch/src/main/java/org/apache/james/quota/search/elasticsearch/events/ElasticSearchQuotaMailboxListener.java + +It allows to index quota usage per user into ElasticSearch +---- * managesieveserver.xml -> https://issues.apache.org/jira/browse/JAMES-3245 ** Status: * spring-server.xml - System Configuration @@ -110,6 +147,20 @@ Jmx protocol is used by James cli to interact with the server. Jmx is known to b Scenarios for address rewriting +---- +Comment from chibenwa: + +chibenwa on Jun 17 Member +https://github.com/apache/james-project/blob/master/src/site/xdoc/server/config-recipientrewritetable.xml (not yet deployed on current website :-( tries to provide wording about Recipient Rewriting and use cases. + + @chibenwa +chibenwa on Jun 17 Member +Maybe address rewriting needs to be moved in the concept part? + + @dleangen +dleangen on Jun 17 Author Member +Yes, definitely. Anything that requires knowledge of any concept should be there. +---- The following scenarios are examples of how you can use address rewriting: @@ -119,6 +170,14 @@ The following example shows how an organization, Contoso, Ltd., can hide its int Outbound messages from the northamerica.contoso.com, europe.contoso.com, and asia.contoso.com domains are rewritten so they appear to originate from a single contoso.com domain. All messages are rewritten as they pass through Edge Transport servers that provide SMTP connectivity between the whole organization and the Internet. +---- +Comment from chibenwa: +chibenwa on Jun 17 Member +We speak of a domain alias here. I would more formulate it: + +External email can send emails to northamerica.contoso.com, europe.contoso.com, ... +Internal users can send email from northamerica.contoso.com, europe.contoso.com, ... +---- Inbound messages to contoso.com recipients are relayed by the Edge Transport server to a Mailbox server. The message is delivered to the correct recipient based on the proxy address that's configured on the recipient's mailbox. Mergers and acquisitions: An acquired company might continue to run as a separate business, but you can use address rewriting to make the two organizations appear as if they're one integrated organization.