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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
