JAMES-3187 Updates to "Basic Server" section of the new documentation

docs/modules/servers/nav.adoc

@@ -2,8 +2,14 @@
 ** xref:demo.adoc[]
 *** xref:servers:5-minute-demo.adoc[]
 *** xref:servers:15-minute-demo.adoc[]
-** xref:local.adoc[]
-** xref:redundant.adoc[]
+** xref:basic/index.adoc[]
+*** xref:basic/context.adoc[]
+*** xref:basic/objectives.adoc[]
+*** xref:basic/concepts.adoc[]
+*** xref:basic/architecture.adoc[]
+*** xref:basic/conf/index.adoc[]
+*** xref:basic/help.adoc[]
+** xref:extendable.adoc[]
 ** xref:distributed.adoc[]
 *** xref:distributed/architecture.adoc[]
 *** xref:distributed/run.adoc[]
@@ -20,3 +26,4 @@
 **** xref:distributed/extend/mailbox-listeners.adoc[]
 **** xref:distributed/extend/smtp-hooks.adoc[]
 **** xref:distributed/extend/webadmin-routes.adoc[]
+** xref:test.adoc[]

docs/modules/servers/pages/basic/architecture.adoc

@@ -0,0 +1,4 @@
+= James Basic Server — Architecture
+:navtitle: Architecture
+
+(TODO)

docs/modules/servers/pages/basic/concepts.adoc

@@ -0,0 +1,14 @@
+= James Basic Server — Background Concepts
+:navtitle: Concepts
+
+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]
+
+ * 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
+ * xref:concepts:/storage/index.adoc[Email storage]

docs/modules/servers/pages/basic/conf/index.adoc

@@ -0,0 +1,213 @@
+= 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
+  ** 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: 
+----
+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
+  ** 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 ????
+ * Database (james-database.properties)
+ * 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)
+ * 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)
+ * 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)
+
+
+== Notes
+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.
+
+
+
+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:
+
+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.
+
+----
+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.
+
+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
+////

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 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
+ * 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

docs/modules/servers/pages/basic/help.adoc

@@ -0,0 +1,52 @@
+= James Basic Server — Where to get help
+:navtitle: Help
+
+////
+
+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.
+
+////
+
+////
+Comment this out until there is agreement.
+== 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.
+////
+
+(Redo this once there is consensus in the community.)

docs/modules/servers/pages/basic/index.adoc

@@ -0,0 +1,21 @@
+= James Basic Mail Server
+:navtitle: Basic 
+
+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.
+
+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/conf/index.adoc[Configuration]
+ * xref:basic/help.adoc[Where to go for help]

docs/modules/servers/pages/basic/objectives.adoc

@@ -0,0 +1,30 @@
+= James Basic Server — Objectives
+: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 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 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 configurations.
+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 Basic 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
+ * Multi-domain (virtual domain) support
+ * Administration of users either via a command-line tool or the admin api
+
+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].