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/07/10 01:49:10 UTC
[james-project] 08/09: JAMES-3302 Documentation skeleton for the
distributed James server
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 <bt...@linagora.com>
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: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org