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 eb7510bee9ad66ae44c41b93e48308a77a10914c Author: Benoit Tellier <[email protected]> AuthorDate: Sun Jul 5 22:31:04 2020 +0700 JAMES-3302 Documentation skeleton for the distributed James server --- docs/modules/servers/nav.adoc | 14 ++++++++++++++ docs/modules/servers/pages/distributed.adoc | 18 +++++++++++++++++- .../servers/pages/distributed/architecture.adoc | 16 ++++++++++++++++ .../servers/pages/distributed/configure/index.adoc | 7 +++++++ .../servers/pages/distributed/extend/index.adoc | 18 ++++++++++++++++++ .../pages/distributed/extend/mail-processing.adoc | 3 +++ .../pages/distributed/extend/mailbox-listeners.adoc | 3 +++ .../servers/pages/distributed/extend/smtp-hooks.adoc | 3 +++ .../pages/distributed/extend/webadmin-routes.adoc | 3 +++ .../servers/pages/distributed/operate/cli.adoc | 4 ++++ .../servers/pages/distributed/operate/guide.adoc | 4 ++++ .../servers/pages/distributed/operate/index.adoc | 20 ++++++++++++++++++++ .../servers/pages/distributed/operate/metrics.adoc | 4 ++++ .../servers/pages/distributed/operate/webadmin.adoc | 4 ++++ .../servers/pages/distributed/run-docker.adoc | 4 ++++ docs/modules/servers/pages/distributed/run.adoc | 4 ++++ 16 files changed, 128 insertions(+), 1 deletion(-) diff --git a/docs/modules/servers/nav.adoc b/docs/modules/servers/nav.adoc index b978f9a..ffd4c6e 100644 --- a/docs/modules/servers/nav.adoc +++ b/docs/modules/servers/nav.adoc @@ -5,3 +5,17 @@ ** xref:local.adoc[] ** xref:redundant.adoc[] ** xref:distributed.adoc[] +*** xref:distributed/architecture.adoc[] +*** xref:distributed/run.adoc[] +*** xref:distributed/run-docker.adoc[] +*** xref:distributed/configure/index.adoc[] +*** xref:distributed/operate/index.adoc[] +**** xref:distributed/operate/guide.adoc[] +**** xref:distributed/operate/webadmin.adoc[] +**** xref:distributed/operate/metrics.adoc[] +**** xref:distributed/operate/cli.adoc[] +*** xref:distributed/extend/index.adoc[] +**** xref:distributed/extend/mail-processing.adoc[] +**** xref:distributed/extend/mailbox-listeners.adoc[] +**** xref:distributed/extend/smtp-hooks.adoc[] +**** xref:distributed/extend/webadmin-routes.adoc[] diff --git a/docs/modules/servers/pages/distributed.adoc b/docs/modules/servers/pages/distributed.adoc index b795e46..9f298bf 100644 --- a/docs/modules/servers/pages/distributed.adoc +++ b/docs/modules/servers/pages/distributed.adoc @@ -1,5 +1,21 @@ = James Distributed Mail Server :navtitle: Distributed -(TODO) +The Distributed server offers an easy way to scale email server. Based on +noSQL solutions, it is intended to be easy to operate for large +deployments, without needing sharding and protocol aware load balancing. +This server is: + +* Intended for use by experts only +* Used for large-scale distributed deployments +* Is designed for Mail Delivery use cases but can also carry out mail processing +* The most feature-rich server, but also by far the most complex + +You will find information about its +xref:main:servers:distributed:architecture.adoc[architecture], how to +xref:main:servers:distributed:run.adoc[run it], how to +xref:main:servers:distributed:run-docker.adoc[run it with Docker], how to +xref:main:servers:distributed:configure/index.adoc[configure it], how to +xref:main:servers:distributed:operate/index.adoc[operate it], how to +xref:main:servers:distributed:extend/index.adoc[extend it]. diff --git a/docs/modules/servers/pages/distributed/architecture.adoc b/docs/modules/servers/pages/distributed/architecture.adoc new file mode 100644 index 0000000..73de370 --- /dev/null +++ b/docs/modules/servers/pages/distributed/architecture.adoc @@ -0,0 +1,16 @@ += Architecture + +This sections presents the Distributed Server architecture. + +In order to deliver its promises, the Distributed Server leverages the following storage strategies: + +(TODO picture) + + * *Cassandra* is used for metadata storage + * The *blob store* storage interface is responsible of storing potentially large binary data. For instance + email bodies, headers or attachments. Different technologies can be used: *Cassandra*, or *Object Storage* +(S3 or Swift) + * *ElasticSearch* component empowers full text search on emails. + * *RabbitMQ* enables James nodes of a same cluster to collaborate together. + * *Tika* (optional) enables text extraction from attachments, thus improving full text search results. + * *SpamAssassin* (optional) can be used for Spam detection and user feedback is supported. diff --git a/docs/modules/servers/pages/distributed/configure/index.adoc b/docs/modules/servers/pages/distributed/configure/index.adoc new file mode 100644 index 0000000..dae4ee1 --- /dev/null +++ b/docs/modules/servers/pages/distributed/configure/index.adoc @@ -0,0 +1,7 @@ += Configuration + +This section presents how to configure the Distributed server. + +The following configuration files are exposed: + +(TODO) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/extend/index.adoc b/docs/modules/servers/pages/distributed/extend/index.adoc new file mode 100644 index 0000000..ee0b7e2 --- /dev/null +++ b/docs/modules/servers/pages/distributed/extend/index.adoc @@ -0,0 +1,18 @@ += Extending the behavior of the Distributed Server + +The Distributed Server exposes several interfaces allowing the user to write custom extensions in +order to extend the Distributed Server behavior. + +Writing *Mailets* and *Matchers* allows one to supply custom components for the +xref:main:servers:distributed:extend:mail-processing.adoc[Mail Processing] and +enables to take decisions, and implement your business logic at the transport level. + +Writing xref:main:servers:distributed:extend:mailbox-listeners.adoc[Mailbox listeners] enables to +react to your user interaction with their mailbox. This powerful tool allows build advanced features +for mail delivery servers. + +Writing xref:main:servers:distributed:extend:smtp-hooks.adoc[SMTP hookd] enables to +add features to your SMTP server. + +Writing xref:main:servers:distributed:extend:webadmin-routes.adoc[WebAdmin routes] enables to +add features to the WebAdmin REST API. diff --git a/docs/modules/servers/pages/distributed/extend/mail-processing.adoc b/docs/modules/servers/pages/distributed/extend/mail-processing.adoc new file mode 100644 index 0000000..372737e --- /dev/null +++ b/docs/modules/servers/pages/distributed/extend/mail-processing.adoc @@ -0,0 +1,3 @@ += Custom mail processing components + +(TODO) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/extend/mailbox-listeners.adoc b/docs/modules/servers/pages/distributed/extend/mailbox-listeners.adoc new file mode 100644 index 0000000..5435605 --- /dev/null +++ b/docs/modules/servers/pages/distributed/extend/mailbox-listeners.adoc @@ -0,0 +1,3 @@ += Custom Mailbox Listeners + +(TODO can http://james.apache.org/howTo/custom-listeners.html be used ?) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/extend/smtp-hooks.adoc b/docs/modules/servers/pages/distributed/extend/smtp-hooks.adoc new file mode 100644 index 0000000..8d58288 --- /dev/null +++ b/docs/modules/servers/pages/distributed/extend/smtp-hooks.adoc @@ -0,0 +1,3 @@ += Custom SMTP hooks + +(TODO) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/extend/webadmin-routes.adoc b/docs/modules/servers/pages/distributed/extend/webadmin-routes.adoc new file mode 100644 index 0000000..7362f6a --- /dev/null +++ b/docs/modules/servers/pages/distributed/extend/webadmin-routes.adoc @@ -0,0 +1,3 @@ += Custom WebAdmin routes + +(TODO) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/operate/cli.adoc b/docs/modules/servers/pages/distributed/operate/cli.adoc new file mode 100644 index 0000000..35d6fee --- /dev/null +++ b/docs/modules/servers/pages/distributed/operate/cli.adoc @@ -0,0 +1,4 @@ += Command Line Interface + +(TODO migrate and adapt content from +https://github.com/linagora/james-project/blob/master/src/site/markdown/server/manage-cli.md) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/operate/guide.adoc b/docs/modules/servers/pages/distributed/operate/guide.adoc new file mode 100644 index 0000000..87adad0 --- /dev/null +++ b/docs/modules/servers/pages/distributed/operate/guide.adoc @@ -0,0 +1,4 @@ += Operator guide + +(TODO migrate and adapt content from +https://github.com/linagora/james-project/blob/master/src/site/markdown/server/manage-guice-distributed-james.md) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/operate/index.adoc b/docs/modules/servers/pages/distributed/operate/index.adoc new file mode 100644 index 0000000..4c62a69 --- /dev/null +++ b/docs/modules/servers/pages/distributed/operate/index.adoc @@ -0,0 +1,20 @@ += Operate the Distributed server + +The following pages detail how to operate the Distributed server. + +Once you have a Distributed James server up and running you then need to ensure it operates correctly. +You may also need to perform some operation maintenance or recover from incidents. This section covers +these topics. + +The xref:main:servers:distributed:operate:webadmin.adoc[WebAdmin Restfull administration API] is the +recommended way to operate the Distributed James server. It allows managing and interacting with most +server components. + +The xref:main:servers:distributed:operate:cli.adoc[Command line interface] allows to interact with some +server components. However it relies on JMX technologies and its use is discouraged. + +The xref:main:servers:distributed:operate:metrics.adoc[metrics] allows to build latency and throughput +graphs, that can be visualized, for instance in *Grafana*. + +Finally, we did put together a xref:main:servers:distributed:operate:metrics.adoc[detailed guide] for +distributed James operators. diff --git a/docs/modules/servers/pages/distributed/operate/metrics.adoc b/docs/modules/servers/pages/distributed/operate/metrics.adoc new file mode 100644 index 0000000..e46ca99 --- /dev/null +++ b/docs/modules/servers/pages/distributed/operate/metrics.adoc @@ -0,0 +1,4 @@ += Metrics + +(TODO migrate and adapt content from +https://github.com/linagora/james-project/blob/master/src/site/xdoc/server/metrics.xml) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/operate/webadmin.adoc b/docs/modules/servers/pages/distributed/operate/webadmin.adoc new file mode 100644 index 0000000..ed1b75a --- /dev/null +++ b/docs/modules/servers/pages/distributed/operate/webadmin.adoc @@ -0,0 +1,4 @@ += WebAdmin REST administration API + +(TODO migrate and adapt content from +https://github.com/linagora/james-project/blob/master/src/site/markdown/server/manage-webadmin.md) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/run-docker.adoc b/docs/modules/servers/pages/distributed/run-docker.adoc new file mode 100644 index 0000000..806e6dd --- /dev/null +++ b/docs/modules/servers/pages/distributed/run-docker.adoc @@ -0,0 +1,4 @@ += Run with docker + +(TODO adapt content from +https://github.com/linagora/james-project#run-james-with-guice--cassandra--rabbitmq--swift--elasticsearch) \ No newline at end of file diff --git a/docs/modules/servers/pages/distributed/run.adoc b/docs/modules/servers/pages/distributed/run.adoc new file mode 100644 index 0000000..d04f912 --- /dev/null +++ b/docs/modules/servers/pages/distributed/run.adoc @@ -0,0 +1,4 @@ += Run + +(TODO adapt content from +https://github.com/linagora/james-project/blob/master/src/site/markdown/server/install/guice-cassandra-rabbitmq-swift.md) \ No newline at end of file --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
