You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by bt...@apache.org on 2020/06/01 07:31:56 UTC
[james-project] 01/02: JAMES-3187 Restructured documentation
This is an automated email from the ASF dual-hosted git repository.
btellier pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 9651480c1933ab8d1292666547996e68ff7b4aa1
Author: David Leangen <da...@leangen.net>
AuthorDate: Tue May 19 11:24:08 2020 +0900
JAMES-3187 Restructured documentation
---
docs/antora.yml | 10 +--
docs/modules/ROOT/nav.adoc | 2 +-
docs/modules/ROOT/pages/index.adoc | 32 ++++++--
docs/modules/admin/nav.adoc | 1 -
docs/modules/admin/pages/index.adoc | 4 -
docs/modules/{ops => community}/nav.adoc | 0
docs/modules/community/pages/index.adoc | 5 ++
docs/modules/concepts/nav.adoc | 11 +++
docs/modules/concepts/pages/index.adoc | 29 +++++++
docs/modules/concepts/pages/mail/index.adoc | 15 ++++
docs/modules/concepts/pages/mail/messages/imf.adoc | 83 +++++++++++++++++++
.../concepts/pages/mail/messages/index.adoc | 14 ++++
.../modules/concepts/pages/mail/messages/mime.adoc | 92 +++++++++++++++++++++
docs/modules/concepts/pages/mail/mime/james.adoc | 3 +
.../concepts/pages/mail/protocols/imap.adoc | 4 +
.../concepts/pages/mail/protocols/index.adoc | 16 ++++
.../concepts/pages/mail/protocols/jmap.adoc | 4 +
.../modules/concepts/pages/mail/protocols/pop.adoc | 4 +
.../concepts/pages/mail/protocols/smtp.adoc | 67 +++++++++++++++
docs/modules/concepts/pages/processing/index.adoc | 5 ++
docs/modules/{doc => customization}/nav.adoc | 0
docs/modules/customization/pages/index.adoc | 3 +
docs/modules/dev/pages/index.adoc | 4 -
docs/modules/{dev => development}/nav.adoc | 0
docs/modules/development/pages/index.adoc | 5 ++
docs/modules/doc/pages/index.adoc | 11 ---
docs/modules/ops/pages/index.adoc | 4 -
docs/modules/servers/nav.adoc | 5 ++
.../pages/15-minute-demo.adoc} | 10 +--
.../pages/5-minute-demo.adoc} | 8 +-
docs/modules/servers/pages/demo.adoc | 13 +++
docs/modules/servers/pages/distributed.adoc | 5 ++
docs/modules/servers/pages/index.adoc | 84 +++++++++++++++++++
docs/modules/servers/pages/local.adoc | 5 ++
docs/modules/servers/pages/redundant.adoc | 5 ++
docs/modules/servers/pages/run.adoc | 94 ++++++++++++++++++++++
docs/modules/user/nav.adoc | 6 --
docs/modules/user/pages/build.adoc | 4 -
docs/modules/user/pages/index.adoc | 23 ------
docs/modules/user/pages/learn.adoc | 4 -
docs/modules/user/pages/try.adoc | 10 ---
41 files changed, 610 insertions(+), 94 deletions(-)
diff --git a/docs/antora.yml b/docs/antora.yml
index a7cff65..c451f20 100644
--- a/docs/antora.yml
+++ b/docs/antora.yml
@@ -3,8 +3,8 @@ title: Apache James Reference Book
version: '3.5'
prerelease: Alpha
nav:
-- modules/user/nav.adoc
-- modules/ops/nav.adoc
-- modules/admin/nav.adoc
-- modules/dev/nav.adoc
-- modules/doc/nav.adoc
+- modules/concepts/nav.adoc
+- modules/servers/nav.adoc
+- modules/customization/nav.adoc
+- modules/development/nav.adoc
+- modules/community/nav.adoc
diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc
index 94db0dc..ee807cf 100644
--- a/docs/modules/ROOT/nav.adoc
+++ b/docs/modules/ROOT/nav.adoc
@@ -1 +1 @@
-* Apache James Reference Book
+* Apache James Reference Documentation
diff --git a/docs/modules/ROOT/pages/index.adoc b/docs/modules/ROOT/pages/index.adoc
index b0fd779..e65d2c9 100644
--- a/docs/modules/ROOT/pages/index.adoc
+++ b/docs/modules/ROOT/pages/index.adoc
@@ -1,15 +1,31 @@
= Welcome
-Welcome to the Apache James Reference Book! This Book is for version {page-version} of James.
+Welcome to the Apache James Reference Documentation! These documents are for version {page-version} of James.
-Apache James is the **J**ava **A**pache **M**ail **E**nterprise **S**erver. It boasts of a modular architecture based on a rich set of components that run on the JVM. With James, you can create your own custom enterprise email solution.
+Apache James is a flexible email platform that provides out-of-the-box mail servers that you can start
+using in production immediately.
+James runs on the JVM and is highly customizable.
This Reference Book is divided into the following Parts:
-* xref:main:user:index.adoc[User Manual]
-* xref:main:ops:index.adoc[Operator Manual]
-* xref:main:admin:index.adoc[Administrator Guide]
-* xref:main:dev:index.adoc[Developer Resources]
-* xref:main:doc:index.adoc[About this documentation]
+* xref:main:concepts:index.adoc[James Core Concepts]
+** These are the core concepts that describe what James is all about.
+ Start here if you want to learn more about what James can do
+ and how it is designed.
+* xref:main:servers:index.adoc[James Servers]
+** We provide a few out-of-the-box servers that you can
+ choose from depending on your needs. Start here if you just
+ want to get up and running quickly with a working production-grade mail server.
+* xref:main:customization:index.adoc[Customization]
+** Shows how you can customize any James server with the
+ functionalities that you need.
+ Check out this section if you have special business or technical
+ needs and are interested in a custom solution.
+* xref:main:development:index.adoc[James Developer Guide]
+** A guide aimed at experienced developers, describing
+ how you can assemble your own specialized server.
+* xref:main:community:index.adoc[James Community]
+** All about the Apache James community, and how you can be
+ part of this active and dynamic group, too!
-Please note that this Reference Book is a **living document**. It is subject to change. You are currently reading version {page-version}. If you find anything that is unclear, unfinished, or confusing, please do not hestiate to xref:main:doc:index.adoc[lend us a hand].
+Please note that this Reference Documentation is a **living document**. It is subject to change. You are currently reading version {page-version}. If you find anything that is unclear, unfinished, or confusing, please do not hestiate to xref:main:community:index.adoc[lend us a hand].
diff --git a/docs/modules/admin/nav.adoc b/docs/modules/admin/nav.adoc
deleted file mode 100644
index 31f850e..0000000
--- a/docs/modules/admin/nav.adoc
+++ /dev/null
@@ -1 +0,0 @@
-* xref:index.adoc[]
diff --git a/docs/modules/admin/pages/index.adoc b/docs/modules/admin/pages/index.adoc
deleted file mode 100644
index 53ed8f0..0000000
--- a/docs/modules/admin/pages/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Apache James Administrator Guide
-:navtitle: Administrator Guide
-
-(TODO)
diff --git a/docs/modules/ops/nav.adoc b/docs/modules/community/nav.adoc
similarity index 100%
rename from docs/modules/ops/nav.adoc
rename to docs/modules/community/nav.adoc
diff --git a/docs/modules/community/pages/index.adoc b/docs/modules/community/pages/index.adoc
new file mode 100644
index 0000000..5cf5498
--- /dev/null
+++ b/docs/modules/community/pages/index.adoc
@@ -0,0 +1,5 @@
+= Apache James Community
+:navtitle: Community
+
+(TODO)
+
diff --git a/docs/modules/concepts/nav.adoc b/docs/modules/concepts/nav.adoc
new file mode 100644
index 0000000..7dc1e62
--- /dev/null
+++ b/docs/modules/concepts/nav.adoc
@@ -0,0 +1,11 @@
+* xref:index.adoc[]
+** xref:mail/index.adoc[]
+*** xref:mail/messages/index.adoc[]
+**** xref:mail/messages/imf.adoc[]
+**** xref:mail/messages/mime.adoc[]
+*** xref:mail/protocols/index.adoc[]
+**** xref:mail/protocols/smtp.adoc[]
+**** xref:mail/protocols/pop.adoc[]
+**** xref:mail/protocols/imap.adoc[]
+**** xref:mail/protocols/jmap.adoc[]
+** xref:processing/index.adoc[]
diff --git a/docs/modules/concepts/pages/index.adoc b/docs/modules/concepts/pages/index.adoc
new file mode 100644
index 0000000..bcb5174
--- /dev/null
+++ b/docs/modules/concepts/pages/index.adoc
@@ -0,0 +1,29 @@
+= Apache James Core Concepts
+:navtitle: Concepts
+
+The core domain of Apache James is intimitely related to email communications.
+Therefore this section is divided into two parts:
+
+ * <<emails,The James Model of the Email Messaging Domain>>
+ * <<processing,The James Model of Email Processing>>
+
+[#emails]
+== Email Messaging Domain
+
+Electronic Mail (often written as "e-mail" or "email") is a means of
+exchanging messages over a data network. In our context, it is obvious
+that we mean "electronic mail" and not "postal mail", so we usually just
+write "mail".
+
+Building a complex system like James requires a clear and consistent
+xref:mail/index.adoc[domain model for email].
+
+
+[#processing]
+== James Email Processing
+
+There are many ways to peel a potato. James has its own particular
+xref:processing/index.adoc[model for processing mail],
+based mostly on the concept of a "Mailet". The idea of Mailet-based
+processing was heavily inspired by the https://en.wikipedia.org/wiki/Java_servlet[Servlet]
+concept.
diff --git a/docs/modules/concepts/pages/mail/index.adoc b/docs/modules/concepts/pages/mail/index.adoc
new file mode 100644
index 0000000..9cf9451
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/index.adoc
@@ -0,0 +1,15 @@
+= All About Emails
+:navtitle: Emails
+
+The https://en.wikipedia.org/wiki/History_of_email[history of email] has resulted
+in a convoluted patchwork of standards and practices, which can be very difficult
+to understand and decipher. Fortunately, James has your back.
+
+We have built up our own view of emails that allows us to process messages in a
+consistent and comprehensible way.
+
+To help you understand how James approaches emails, we have divided this section
+up into the following parts:
+
+ * xref:mail/messages/index.adoc[]
+ * xref:mail/protocols/index.adoc[]
diff --git a/docs/modules/concepts/pages/mail/messages/imf.adoc b/docs/modules/concepts/pages/mail/messages/imf.adoc
new file mode 100644
index 0000000..886c5f0
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/messages/imf.adoc
@@ -0,0 +1,83 @@
+= Internet Message Format
+:navtitle: IMF
+
+== Overview
+
+What people casually call "email" actually refers more specifically to a
+text message written in a specified format called
+https://en.wikipedia.org/wiki/Email["Internet Message Format"] or "IMF".
+After the first IMF specification was published in 1982 there was no looking back.
+Email took the world by storm. Today it is arguably the most prevalent means of
+communicating with a distant party.
+
+IMF is very basic, and is limited to only specifying a syntax for text messages.
+For the transmission of images, audio, or other types of data we need to make
+use of the xref:mail/messages/mime.adoc[MIME] specification.
+Although IMF forms the base standard upon which
+email is based, email today is rarely used without MIME. We therefore consider
+for practical purposes that an email message is essentially the equivalent of
+a MIME message.
+
+
+
+== Specifications
+
+The specifications for Internet Message Format (IMF) form the basis of what we commonly
+call "email".
+
+=== RFC822
+
+https://tools.ietf.org/html/rfc822[RFC822] ("Standard for the Format of ARPA Internet Text Messages")
+was the original standard that defined the format of an email. It was obsoleted by
+<<RFC2822>>. The definition of an email under this standard was an attempt to take the lessons
+learned from the ARPANET and extend the use of text messaging to a broader context.
+
+Electronic mail messages are defined as having contents and an envelope. The contents
+consist of header fields and, optionally, a body. The body is nothing more than
+a (potentially empty) sequence of lines of text.
+
+Although this sounds like a an extremely simple concept, to get two completely separate systems
+to agree and understand each other is a surprisingly complex problem that most people
+today take for granted. Most of RFC822 deals with the nitty-gritty of formatting and parsing
+this type of text message.
+
+This specification deals with the headers, additionally relating them to the sending and
+forwarding of messages. The body content is dealt with in <<RFC2045>>
+
+
+
+=== RFC2822
+
+https://tools.ietf.org/html/rfc2822[RFC2822] ("Internet Message Format")
+obsoletes <<RFC822>>, and was obsoleted by <<RFC5322>>.
+
+The standard builds on RFC822, but limits its scope to only the sytax of the
+message, and obsoletes much of what was defined by RFC822. The envelope was
+split into a separate specification, <<RFC2821>>.
+
+
+
+
+=== RFC5322
+
+https://tools.ietf.org/html/rfc5322[RFC5322] ("Internet Message Format")
+was published in 2008.
+It obsoletes <<RFC2822>> and is currently the specification still actually in use.
+
+It builds on RFC2822, updating it to the then-current context and obsoleting
+outdated parts of RFC2822.
+
+
+
+
+== James Model
+
+While the general description of IMF is not sufficient for building a complex
+system like James, the technical specifications are unfortunately
+very messy and overly-complex due to their history and the context in which
+they were developed.
+
+Since modern-day messaging almost always requires MIME, and since the
+separation between IMF and MIME is not really useful from a usage perspective,
+James considers an "email" to be both IMF- an MIME-compliant. For all intents
+and purposes, James does not consider the concept of IMF in its domain model.
diff --git a/docs/modules/concepts/pages/mail/messages/index.adoc b/docs/modules/concepts/pages/mail/messages/index.adoc
new file mode 100644
index 0000000..8a9b488
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/messages/index.adoc
@@ -0,0 +1,14 @@
+= Email Messages
+:navtitle: Messages
+
+An email message is essentially a simple text message that is communicated
+from one party to another. It is no miracle that two unknown parties are
+able to communicate; rather rather we can thank a set of standards that
+allow any two unrelated systems to process an email even if the system owners
+do not know each other.
+
+The two most important standards upon which today's emails are based
+are:
+
+ * xref:mail/messages/imf.adoc[Internet Mail Format] (IMF)
+ * xref:mail/messages/mime.adoc[Multipurpose Internet Mail Extensions] (MIME)
diff --git a/docs/modules/concepts/pages/mail/messages/mime.adoc b/docs/modules/concepts/pages/mail/messages/mime.adoc
new file mode 100644
index 0000000..fbd45e5
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/messages/mime.adoc
@@ -0,0 +1,92 @@
+= Multipurpose Internet Mail Extensions
+:navtitle: MIME
+
+== Overview
+
+The base format of an email message is xref:mail/messages/imf.adoc[Internet Message Format"],
+but most contemporary messages use a format called
+https://en.wikipedia.org/wiki/MIME["Multipurpose Internet Mail Extensions"].
+MIME specifies how to extend a valid IMF message, dealing with character encodings,
+various file formats, and many other odds and ends that make email what it is today.
+
+A user of email rarely has to be concerned with the MIME specifications. Usually the
+communications system should take care of all the nitty gritty, and even then MIME
+processing is usually at a very low level. For this reason, the blissfully simple
+conception of a simple "email" is usually just fine from the perspective of a user
+and even in most cases for a developer.
+
+
+
+
+== Specifications
+
+Multipurpose Internet Mail Extensions, or just MIME, functions much like an extension
+to IMF in order to:
+
+ * Add different character sets for internationalization
+ * Allow for processing of media types other than plain text
+
+=== RFC2045
+
+https://tools.ietf.org/html/rfc2045[RFC2045] ("Multipurpose Internet Mail Extensions
+Part One: Format of Internet Message Bodies")
+describes the message body format of an email. It is part of a serious of MIME
+specifications including <<RFC2046>>, <<RFC2047>>, <<RFC2048>>, and <<RFC2049>>.
+This particular document in the series specifies the various headers that
+are used to describe the structure of a MIME message.
+
+
+
+=== RFC2046
+
+https://tools.ietf.org/html/rfc2046[RFC2046] ("Multipurpose Internet Mail Extensions
+Part Two: Media Types") describes the various MIME media types, such as
+plain text, images, videos, etc. It is part of the serious of MIME specifications
+that includes <<RFC2045>>, <<RFC2047>>, <<RFC2048>>, and <<RFC2049>>.
+
+
+
+
+=== RFC2047
+
+https://tools.ietf.org/html/rfc2047[RFC2047] ("MIME Part Three:
+Message Header Extensions for Non-ASCII Text") describes, as the
+title indicates, header extensions for non-ASCII text. It is part
+of the series of MIME specifications that includes
+<<RFC2045>>, <<RFC2046>>, <<RFC2048>>, and <<RFC2049>>.
+
+
+
+
+=== RFC2048
+
+https://tools.ietf.org/html/rfc2048[RFC2048] ("Multipurpose Internet Mail Extensions
+Part Four: Registration Procedures") describes the procedure for registering a MIME
+type. It is not directly relevant to James, but is part of the MIME series that includes
+<<RFC2045>>, <<RFC2046>>, <<RFC2047>>, and <<RFC2049>>.
+
+This specification was obsoleted by https://tools.ietf.org/html/rfc4288[RFC4288]
+(which itself was obsoleted by https://tools.ietf.org/html/rfc6838[RFC6838]) and
+https://tools.ietf.org/html/rfc4289[RFC4289].
+
+
+
+=== RFC2049
+
+https://tools.ietf.org/html/rfc2049[RFC2049] ("Multipurpose Internet Mail Extensions
+Part Five: Conformance Criteria and Examples") mainly describes what portions of MIME
+must be supported by a conformant MIME implementation. It is part of the series that includes
+<<RFC2045>>, <<RFC2046>>, <<RFC2047>>, and <<RFC2049>>.
+
+
+
+== James Model
+
+While a general, non-technical description of MIME is useful for most users
+and developers, it is not sufficient for building a complex system like James. Meanwhile,
+the technical specifications are unfortunately very messy and overly-complex due to
+their history and the context in which they were developed. To make dealing with
+emails possible and practical, James has defined its own version of what it means
+to be an email.
+
+(TODO need a reference, please!)
diff --git a/docs/modules/concepts/pages/mail/mime/james.adoc b/docs/modules/concepts/pages/mail/mime/james.adoc
new file mode 100644
index 0000000..7879639
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/mime/james.adoc
@@ -0,0 +1,3 @@
+Added as a dummy file because there is an orphaned comment in GitHub that I am unable to resolve.
+
+Will this workaround work???
diff --git a/docs/modules/concepts/pages/mail/protocols/imap.adoc b/docs/modules/concepts/pages/mail/protocols/imap.adoc
new file mode 100644
index 0000000..2454663
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/imap.adoc
@@ -0,0 +1,4 @@
+= Message Access (IMAP)
+:navtitle: IMAP
+
+(TODO)
diff --git a/docs/modules/concepts/pages/mail/protocols/index.adoc b/docs/modules/concepts/pages/mail/protocols/index.adoc
new file mode 100644
index 0000000..729438e
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/index.adoc
@@ -0,0 +1,16 @@
+= Transmission Protocols
+:navtitle: Protocols
+
+The true value of emails is that any one party can communicate with any
+other party located virtually anywhere. All they need are a common understanding
+of a xref:mail/messages/index.adoc[message format], and a means of
+transmitting the message.
+
+Transmitting email messages between parties requires a mutually-known standard.
+It turns out that there are several standard protocols used for the
+transmission of email messages, each with a different purpose:
+
+ ** xref:mail/protocols/smtp.adoc[Message Transport]
+ ** xref:mail/protocols/pop.adoc[Electronic Post]
+ ** xref:mail/protocols/imap.adoc[Remote Message Access]
+ ** xref:mail/protocols/jmap.adoc[Application Data Transfer]
diff --git a/docs/modules/concepts/pages/mail/protocols/jmap.adoc b/docs/modules/concepts/pages/mail/protocols/jmap.adoc
new file mode 100644
index 0000000..2c2fdb4
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/jmap.adoc
@@ -0,0 +1,4 @@
+= Application Data Transfer (JMAP)
+:navtitle: JMAP
+
+(TODO)
diff --git a/docs/modules/concepts/pages/mail/protocols/pop.adoc b/docs/modules/concepts/pages/mail/protocols/pop.adoc
new file mode 100644
index 0000000..b0116d8
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/pop.adoc
@@ -0,0 +1,4 @@
+= Electronic Post (POP)
+:navtitle: POP
+
+(TODO)
diff --git a/docs/modules/concepts/pages/mail/protocols/smtp.adoc b/docs/modules/concepts/pages/mail/protocols/smtp.adoc
new file mode 100644
index 0000000..f24a876
--- /dev/null
+++ b/docs/modules/concepts/pages/mail/protocols/smtp.adoc
@@ -0,0 +1,67 @@
+= Simple Mail Transfer Protocol (SMTP)
+:navtitle: SMTP
+
+== Overview
+
+When the original specification for Simple Mail Transfer Protocol, or SMTP,
+was published almost 40 years ago together with
+xref:mail/messages/imf.adoc[IMF], Email as we know it today was born.
+
+
+
+== Specifications
+
+=== RFC821
+
+https://tools.ietf.org/html/rfc821[RFC821] ("Simple Mail Transfer Protocol")
+was the original SMTP specification published in 1982.
+It was obsoleted by <<RFC2821>> in 2001.
+
+== RFC2821
+
+https://tools.ietf.org/html/rfc2821[RFC2821] ("Simple Mail Transfer Protocol") replaced
+<<RFC821>>. It was itself replaced by <<RFC5321>> in 2008.
+
+== RFC 5321
+
+https://tools.ietf.org/html/rfc5321[RFC5321] is the currently used standard for
+"Simple Mail Transfer Protocol", or "SMTP". It is "a specification of the basic
+protocol for Internet electronic mail transport". If you are interested in all
+the gory details, we recommend that you read this document.
+
+This specification has many dependencies with xref:mail/messages/imf.adoc[IMF],
+xref:mail/messages/mime.adoc[MIME], and other technical concepts, which can quickly
+become utterly confusing.
+
+Here, we provide a very short and simplified description of those portions of the
+specification that we felt were interesting enough to repeat here.
+
+As the spec mentions, "SMTP transports a mail object", a mail object being described
+as an object that contains both an envelope and content. An SMTP client connects
+to a server and communicates via a session. Both client and server provide a
+mail transport service, and are therefore act as "Mail Transfer Agents", or
+"MTAs". A mail originates and terminates with a "Mail User Agent" ("MUA").
+On the originating side, a MUA may, for instance, collect mail to be transmitted
+by a user and hand it off to an MTA. On the terminating side, an MTA would
+hand a mail off to an MUA.
+
+"SMTP sessions are stateful, with both parties carefully maintaining a
+common view of the current state." The session is initiated by the client,
+which establishes a two-way channel to an SMTP server. The session must either
+close successful (or with a failure message), else delivery is considered to
+have failed.
+
+
+
+== James Model
+
+(TODO: explain how all this is modeled in James)
+
+
+
+
+== Try It!
+
+Add a section to the demo, and connect manuall via an SMTP session
+
+
diff --git a/docs/modules/concepts/pages/processing/index.adoc b/docs/modules/concepts/pages/processing/index.adoc
new file mode 100644
index 0000000..61a0223
--- /dev/null
+++ b/docs/modules/concepts/pages/processing/index.adoc
@@ -0,0 +1,5 @@
+= Mail Processing Domain Model
+:navtitle: Processing
+
+(TODO)
+
diff --git a/docs/modules/doc/nav.adoc b/docs/modules/customization/nav.adoc
similarity index 100%
rename from docs/modules/doc/nav.adoc
rename to docs/modules/customization/nav.adoc
diff --git a/docs/modules/customization/pages/index.adoc b/docs/modules/customization/pages/index.adoc
new file mode 100644
index 0000000..99c4bf0
--- /dev/null
+++ b/docs/modules/customization/pages/index.adoc
@@ -0,0 +1,3 @@
+= Apache James Customization
+:navtitle: Customization
+
diff --git a/docs/modules/dev/pages/index.adoc b/docs/modules/dev/pages/index.adoc
deleted file mode 100644
index db73ae1..0000000
--- a/docs/modules/dev/pages/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Apache James Developer Resources
-:navtitle: Developer Resources
-
-(TODO)
diff --git a/docs/modules/dev/nav.adoc b/docs/modules/development/nav.adoc
similarity index 100%
rename from docs/modules/dev/nav.adoc
rename to docs/modules/development/nav.adoc
diff --git a/docs/modules/development/pages/index.adoc b/docs/modules/development/pages/index.adoc
new file mode 100644
index 0000000..56db0cd
--- /dev/null
+++ b/docs/modules/development/pages/index.adoc
@@ -0,0 +1,5 @@
+= Apache James Developer Guide
+:navtitle: Developer Guide
+
+(TODO)
+
diff --git a/docs/modules/doc/pages/index.adoc b/docs/modules/doc/pages/index.adoc
deleted file mode 100644
index 163a381..0000000
--- a/docs/modules/doc/pages/index.adoc
+++ /dev/null
@@ -1,11 +0,0 @@
-= About this documentation
-:navtitle: About this documentation
-
-This documentation was produced with Antora.
-
-We know that this documentation is lacking. We are slowing working on making it better.
-To that end, we would **love** to get your help!
-
-This section explains how to work with Antora and the Apache James Reference Book.
-
-(TODO)
diff --git a/docs/modules/ops/pages/index.adoc b/docs/modules/ops/pages/index.adoc
deleted file mode 100644
index d11c829..0000000
--- a/docs/modules/ops/pages/index.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Apache James Operator Manual
-:navtitle: Operator Manual
-
-(TODO)
diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc
new file mode 100644
index 0000000..78f97b3
--- /dev/null
+++ b/docs/modules/servers/nav.adoc
@@ -0,0 +1,5 @@
+* xref:index.adoc[]
+** xref:demo.adoc[]
+** xref:local.adoc[]
+** xref:redundant.adoc[]
+** xref:distributed.adoc[]
diff --git a/docs/modules/user/pages/try/15_minutes.adoc b/docs/modules/servers/pages/15-minute-demo.adoc
similarity index 93%
rename from docs/modules/user/pages/try/15_minutes.adoc
rename to docs/modules/servers/pages/15-minute-demo.adoc
index 6fbad69..18498ff 100644
--- a/docs/modules/user/pages/try/15_minutes.adoc
+++ b/docs/modules/servers/pages/15-minute-demo.adoc
@@ -1,6 +1,6 @@
-= Try James in 15 minutes
+= Long Demo
-In this tutorial, we will set up a runing James demo using a prepared Docker image.
+In this demo (~15 minutes), we will set up a runing James demo using a prepared Docker image.
We will then test the server by connecting with an email client. Finally, we
will connect to the server via the REST-based Admin API.
@@ -57,7 +57,7 @@ docker exec james java -jar /root/james-cli.jar \
-h \<<HOST>> -p \<<PORT>> \<<COMMAND>>
----
-In this tutorial, we are using host 127.0.0.1 and port 9999, so every command looks like:
+In this demo, we are using host 127.0.0.1 and port 9999, so every command looks like:
----
docker exec james java -jar /root/james-cli.jar \
@@ -66,7 +66,7 @@ docker exec james java -jar /root/james-cli.jar \
Host 127.0.0.1 is of course localhost, and the use of port 9999 is completely arbitrary.
-To make this tutorial a little easier, set this up as a bash script by copying and pasting this script:
+To make this demo a little easier to use, set this up as a bash script by copying and pasting this script:
[source,bash]
----
@@ -123,7 +123,7 @@ You should now see your newly created user:
== Connect to the server with an email client
****
-For this tutorial, we will use Thunderbird, as it is available in multiple languages
+For this demo, we will use Thunderbird, as it is available in multiple languages
on Windows, Mac, and Linux.
Go to https://www.thunderbird.net to download Thunderbird.
diff --git a/docs/modules/user/pages/try/5_minutes.adoc b/docs/modules/servers/pages/5-minute-demo.adoc
similarity index 88%
rename from docs/modules/user/pages/try/5_minutes.adoc
rename to docs/modules/servers/pages/5-minute-demo.adoc
index a885eb3..bf710c9 100644
--- a/docs/modules/user/pages/try/5_minutes.adoc
+++ b/docs/modules/servers/pages/5-minute-demo.adoc
@@ -1,6 +1,6 @@
-= Try James in 5 minutes
+= Short Demo
-In this short tutorial, we will set up a runing James demo very quickly
+In this short demo (~5 minutes), we will set up a runing James demo very quickly
using a prepared Docker image.
Then you will add a domain, and a user account within that domain.
@@ -38,7 +38,7 @@ docker exec james java -jar /root/james-cli.jar \
-h \<<HOST>> -p \<<PORT>> \<<COMMAND>>
----
-In this tutorial, we are using host 127.0.0.1 and port 9999, so every command looks like:
+In this demo, we are using host 127.0.0.1 and port 9999, so every command looks like:
----
docker exec james java -jar /root/james-cli.jar \
@@ -48,7 +48,7 @@ docker exec james java -jar /root/james-cli.jar \
Host 127.0.0.1 is of course localhost, and the use of port 9999 is completely arbitrary.
****
-To make this tutorial a little easier, set this up as a bash script by copying and pasting this script:
+To make this demo a little easier to use, set this up as a bash script by copying and pasting this script:
[source,bash]
----
diff --git a/docs/modules/servers/pages/demo.adoc b/docs/modules/servers/pages/demo.adoc
new file mode 100644
index 0000000..a752a2a
--- /dev/null
+++ b/docs/modules/servers/pages/demo.adoc
@@ -0,0 +1,13 @@
+= Server Demo
+:navtitle: Demo
+
+The James Demo Server sets up a light-weight, disposable mail server
+so you can try it out easily on your own local machine.
+
+ * xref:main:servers:5-minute-demo.adoc[Short demo] (~5 minutes)
+ ** Set up a demo server
+ ** Create a new user with the CLI
+ * xref:main:servers:15-minute-demo.adoc[Long demo] (~15 minutes)
+ ** Same steps as above
+ ** Interact with the server via the Admin API
+ ** Test the server with an email client
diff --git a/docs/modules/servers/pages/distributed.adoc b/docs/modules/servers/pages/distributed.adoc
new file mode 100644
index 0000000..b795e46
--- /dev/null
+++ b/docs/modules/servers/pages/distributed.adoc
@@ -0,0 +1,5 @@
+= James Distributed Mail Server
+:navtitle: Distributed
+
+(TODO)
+
diff --git a/docs/modules/servers/pages/index.adoc b/docs/modules/servers/pages/index.adoc
new file mode 100644
index 0000000..3786e81
--- /dev/null
+++ b/docs/modules/servers/pages/index.adoc
@@ -0,0 +1,84 @@
+= 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.
+
+The available James Servers are:
+
+ * <<demo,James Demo Mail Server>>
+ * <<local,James Local Mail Server>>
+ * <<redundant,James Redundant Mail Server>>
+ * <<distributed,James Distributed Mail Server>>
+
+
+[#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.
+
+
+[#local]
+== 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*].
+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.
+
+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
+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
+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
+
+
+
+
+[#redundant]
+== James Redundant 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*].
+
+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
+
+
+
+
+[#distributed]
+== James Distributed Mail Server
+
+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
+
+
diff --git a/docs/modules/servers/pages/local.adoc b/docs/modules/servers/pages/local.adoc
new file mode 100644
index 0000000..8783dcf
--- /dev/null
+++ b/docs/modules/servers/pages/local.adoc
@@ -0,0 +1,5 @@
+= James Local Mail Server
+:navtitle: Local
+
+(TODO)
+
diff --git a/docs/modules/servers/pages/redundant.adoc b/docs/modules/servers/pages/redundant.adoc
new file mode 100644
index 0000000..659034a
--- /dev/null
+++ b/docs/modules/servers/pages/redundant.adoc
@@ -0,0 +1,5 @@
+= James Redundant Mail Server
+:navtitle: Redundant
+
+(TODO)
+
diff --git a/docs/modules/servers/pages/run.adoc b/docs/modules/servers/pages/run.adoc
new file mode 100644
index 0000000..70a71ca
--- /dev/null
+++ b/docs/modules/servers/pages/run.adoc
@@ -0,0 +1,94 @@
+= Run James in Production
+:navtitle: Run
+
+James provides a number of *profiles* out of the box.
+These profiles have been tested and verified so you can
+get set up quickly with a production mail server that you
+can use with confidence.
+
+The available profiles are:
+
+ * <<minimal,James Minimal Profile>>
+ * <<basic,James Basic Profile>>
+ * <<advanced,James Advanced Profile>>
+ * <<distributed,James Distributed Profile>>
+
+
+
+[#minimal]
+== James Minimal Profile
+
+If you are not sure which profile you should be using, then
+you probably ought to be using the *James Minimal Profile*.
+
+This profile 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
+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
+*James Minimal Profile* will help you reduce the risk of running into
+production issues.
+
+This profile 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
+
+(TODO: Add link to details page)
+
+
+[#basic]
+== James Basic Profile
+
+This profile is intended to be relatively easy to use, but provides additional features with regards
+to data storage and management. Of course, these additional features come at the cost of more
+operational complexity. You will have to now deal with a relational database and all the fun
+that comes with it. However, if you are already an expert at relational database management,
+then this profile should be a natural choice for you.
+
+This profile is:
+
+ * Suggested for smaller deployments that require data persisted in a relational database
+ * Appropriate for most operators provided that you understand relational databases and data indexing
+ * Less complex than most profiles, but also less performant
+
+(TODO: Add link to details page)
+
+
+[#advanced]
+== James Advanced Profile
+
+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 *James Advanced Profile*.
+
+This profile is:
+
+ * Intended for use by experienced operators only
+ * Used for mid-sized to large deployments
+ * More performant than the Minimal and Basic Profiles, but also more complex
+
+
+(TODO: Add link to details page)
+
+
+
+[#distributed]
+== James Distributed Profile
+
+The *James Distributed Profile* is a heavy-duty industrial enterprise mail server.
+
+This profile is:
+
+ * Intended for use by experts only
+ * Use for large-scale distributed deployments
+ * The most feature-rich profile, but also by far the most complex
+
+
+(TODO: Add link to details page)
+
+
diff --git a/docs/modules/user/nav.adoc b/docs/modules/user/nav.adoc
deleted file mode 100644
index b2cfd2e..0000000
--- a/docs/modules/user/nav.adoc
+++ /dev/null
@@ -1,6 +0,0 @@
-* xref:index.adoc[]
-** xref:try.adoc[]
-*** xref:try/5_minutes.adoc[]
-*** xref:try/15_minutes.adoc[]
-** xref:learn.adoc[]
-** xref:build.adoc[]
diff --git a/docs/modules/user/pages/build.adoc b/docs/modules/user/pages/build.adoc
deleted file mode 100644
index 28e483a..0000000
--- a/docs/modules/user/pages/build.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Build your own custom mail server
-:navtitle: Build
-
-(TODO)
diff --git a/docs/modules/user/pages/index.adoc b/docs/modules/user/pages/index.adoc
deleted file mode 100644
index 41ff7af..0000000
--- a/docs/modules/user/pages/index.adoc
+++ /dev/null
@@ -1,23 +0,0 @@
-= Apache James User Manual
-:navtitle: User Manual
-
-link:https://gitter.im/apache/james-project[image:https://badges.gitter.im/apache/james-project.svg[Join the chat at link:https://gitter.im/apache/james-project]]
-
-image::james-logo.png[James logo]
-
-*James* stands for *Java Apache Mail Enterprise Server*.
-
-James has a modular architecture based on a rich set of components that form a
-complete, stable, secure and customizable mail server running on the JVM.
-
-Supported protocols include: IMAP, SMTP, JMAP, and POP3.
-
-This user manual provides information to get you up and running quickly with James.
-You can also refer to the Administrator Guide, Developer Resources, and
-Operator Manual for additional information about James from different perspectives.
-
-== How to...
-
- * xref::try.adoc[Try James in 5 minutes]
- * xref::build.adoc[Learn more about the architecture]
- * xref::build.adoc[Build your own custom mail server]
diff --git a/docs/modules/user/pages/learn.adoc b/docs/modules/user/pages/learn.adoc
deleted file mode 100644
index 543ea00..0000000
--- a/docs/modules/user/pages/learn.adoc
+++ /dev/null
@@ -1,4 +0,0 @@
-= Learn more about the architecture
-:navtitle: Learn
-
-You can read about James in the https://james.apache.org/documentation.html[Documentation] section on the James website.
diff --git a/docs/modules/user/pages/try.adoc b/docs/modules/user/pages/try.adoc
deleted file mode 100644
index a40260d..0000000
--- a/docs/modules/user/pages/try.adoc
+++ /dev/null
@@ -1,10 +0,0 @@
-= Try James
-:navtitle: Try
-
- * xref:main:user:try/5_minutes.adoc[Try James in 5 minutes]
- ** Set up a demo server
- ** Create a new user with the CLI
- * xref:main:user:try/15_minutes.adoc[Try James in 15 minutes]
- ** Same steps as above
- ** Interact with the server via the Admin API
- ** Test the server with an email client
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org