You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by bt...@apache.org on 2022/10/04 02:19:58 UTC
[james-project] 02/02: JAMES-3826 Example and 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 5673f005120920aefbfaa2c0454e02a3f3084558
Author: Quan Tran <hq...@linagora.com>
AuthorDate: Fri Sep 30 16:06:19 2022 +0700
JAMES-3826 Example and documentation
---
examples/README.md | 5 ++
examples/custom-healthcheck/README.md | 58 +++++++++++++
examples/custom-healthcheck/pom.xml | 60 ++++++++++++++
.../org/apache/james/examples/HealthCheckA.java | 41 ++++++++++
.../src/main/resources}/healthcheck.properties | 3 +
examples/pom.xml | 1 +
.../sample-configuration/healthcheck.properties | 4 +
.../modules/ROOT/pages/configure/healthcheck.adoc | 3 +
.../sample-configuration/healthcheck.properties | 4 +
.../sample-configuration/healthcheck.properties | 3 +
.../sample-configuration/healthcheck.properties | 3 +
.../sample-configuration/healthcheck.properties | 4 +
.../sample-configuration/healthcheck.properties | 3 +
src/homepage/howTo/custom-healthchecks.html | 95 ++++++++++++++++++++++
src/homepage/howTo/index.html | 7 ++
src/site/xdoc/server/config-healthcheck.xml | 3 +
16 files changed, 297 insertions(+)
diff --git a/examples/README.md b/examples/README.md
index 83e6dccd4b..a75beb75ff 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -49,6 +49,11 @@ interact with third party systems, do advance reporting...
[This example](custom-webadmin-route) shows how to write additional Webadmin routes!
+## Configure Custom Healthchecks
+
+[This example](custom-healthcheck) demonstrates how to write custom healthchecks for Apache James.
+This enables writing new custom healthcheck that fits your monitoring need.
+
## Write Custom James server assembly
[This example](custom-james-assembly) demonstrates how to write a custom assembly in order to write your own tailor-made server.
diff --git a/examples/custom-healthcheck/README.md b/examples/custom-healthcheck/README.md
new file mode 100644
index 0000000000..b9ce307c88
--- /dev/null
+++ b/examples/custom-healthcheck/README.md
@@ -0,0 +1,58 @@
+# Writing custom healthchecks
+
+Read this page [on the website](http://james.apache.org/howTo/custom-healthchecks.html).
+
+The current project demonstrates how to write custom healthchecks for Apache James.
+This enables writing new custom healthcheck that fits your monitoring need.
+
+Start by importing the dependencies:
+
+```
+<dependency>
+ <groupId>org.apache.james</groupId>
+ <artifactId>james-core</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.projectreactor</groupId>
+ <artifactId>reactor-core</artifactId>
+</dependency>
+```
+
+You can then start writing your first HealthCheck by implementing HealthCheck interface.
+
+You can compile this example project:
+
+```
+mvn clean install
+```
+
+Then embed your healthcheck into a James server. First configure your custom healthcheck into `healthcheck.properties`:
+
+```
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+additional.healthchecks=org.apache.james.examples.HealthCheckA
+```
+
+Create a keystore (default password being `james72laBalle`):
+
+```
+keytool -genkey -alias james -keyalg RSA -keystore keystore
+```
+
+Then start a James server with your JAR and the configuration:
+
+```
+$ docker run -d \
+ -v $PWD/healthcheck.properties:/root/conf/healthcheck.properties \
+ -v $PWD/healthcheck-extension.jar:/root/extensions-jars \
+ -v $PWD/keystore:/root/conf/keystore \
+ -p 25:25 \
+ apache/james:memory-latest
+```
+
+You can use `curl` command to get your healthcheck status:
+
+```
+$ curl -XGET http://172.17.0.2:8000/healthcheck
+```
\ No newline at end of file
diff --git a/examples/custom-healthcheck/pom.xml b/examples/custom-healthcheck/pom.xml
new file mode 100644
index 0000000000..a284033d45
--- /dev/null
+++ b/examples/custom-healthcheck/pom.xml
@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+<project xmlns="http://maven.apache.org/POM/4.0.0"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
+ <parent>
+ <artifactId>examples</artifactId>
+ <groupId>org.apache.james.examples</groupId>
+ <version>3.8.0-SNAPSHOT</version>
+ </parent>
+ <modelVersion>4.0.0</modelVersion>
+
+ <artifactId>custom-healthcheck</artifactId>
+ <name>Apache James :: Examples :: Custom HealthCheck</name>
+ <description>Example of how to extend James by adding your own healthcheck</description>
+
+ <dependencies>
+ <dependency>
+ <groupId>${james.groupId}</groupId>
+ <artifactId>james-core</artifactId>
+ <version>${project.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>io.projectreactor</groupId>
+ <artifactId>reactor-core</artifactId>
+ <version>3.4.18</version>
+ </dependency>
+ </dependencies>
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <source>11</source>
+ <target>11</target>
+ </configuration>
+ </plugin>
+ </plugins>
+ </build>
+
+</project>
\ No newline at end of file
diff --git a/examples/custom-healthcheck/src/main/java/org/apache/james/examples/HealthCheckA.java b/examples/custom-healthcheck/src/main/java/org/apache/james/examples/HealthCheckA.java
new file mode 100644
index 0000000000..061dde595d
--- /dev/null
+++ b/examples/custom-healthcheck/src/main/java/org/apache/james/examples/HealthCheckA.java
@@ -0,0 +1,41 @@
+/****************************************************************
+ * Licensed to the Apache Software Foundation (ASF) under one *
+ * or more contributor license agreements. See the NOTICE file *
+ * distributed with this work for additional information *
+ * regarding copyright ownership. The ASF licenses this file *
+ * to you under the Apache License, Version 2.0 (the *
+ * "License"); you may not use this file except in compliance *
+ * with the License. You may obtain a copy of the License at *
+ * *
+ * http://www.apache.org/licenses/LICENSE-2.0 *
+ * *
+ * Unless required by applicable law or agreed to in writing, *
+ * software distributed under the License is distributed on an *
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY *
+ * KIND, either express or implied. See the License for the *
+ * specific language governing permissions and limitations *
+ * under the License. *
+ ****************************************************************/
+
+package org.apache.james.examples;
+
+import org.apache.james.core.healthcheck.ComponentName;
+import org.apache.james.core.healthcheck.HealthCheck;
+import org.apache.james.core.healthcheck.Result;
+import org.reactivestreams.Publisher;
+
+import reactor.core.publisher.Mono;
+
+public class HealthCheckA implements HealthCheck {
+ public static final ComponentName COMPONENT_NAME = new ComponentName("A");
+
+ @Override
+ public ComponentName componentName() {
+ return COMPONENT_NAME;
+ }
+
+ @Override
+ public Publisher<Result> check() {
+ return Mono.just(Result.healthy(COMPONENT_NAME));
+ }
+}
diff --git a/server/apps/distributed-app/sample-configuration/healthcheck.properties b/examples/custom-healthcheck/src/main/resources/healthcheck.properties
similarity index 84%
copy from server/apps/distributed-app/sample-configuration/healthcheck.properties
copy to examples/custom-healthcheck/src/main/resources/healthcheck.properties
index 9f3bad1898..82f469fa8e 100644
--- a/server/apps/distributed-app/sample-configuration/healthcheck.properties
+++ b/examples/custom-healthcheck/src/main/resources/healthcheck.properties
@@ -28,3 +28,6 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+additional.healthchecks=org.apache.james.examples.HealthCheckA
\ No newline at end of file
diff --git a/examples/pom.xml b/examples/pom.xml
index 3f62bb442d..76130afe9c 100644
--- a/examples/pom.xml
+++ b/examples/pom.xml
@@ -47,5 +47,6 @@
<module>custom-smtp-hooks</module>
<module>custom-webadmin-route</module>
<module>metrics-graphite</module>
+ <module>custom-healthcheck</module>
</modules>
</project>
diff --git a/server/apps/cassandra-app/sample-configuration/healthcheck.properties b/server/apps/cassandra-app/sample-configuration/healthcheck.properties
index 9f3bad1898..284cfd85b8 100644
--- a/server/apps/cassandra-app/sample-configuration/healthcheck.properties
+++ b/server/apps/cassandra-app/sample-configuration/healthcheck.properties
@@ -28,3 +28,7 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+# additional.healthchecks=
+
diff --git a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/healthcheck.adoc b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/healthcheck.adoc
index 538dd30970..37c01f8c81 100644
--- a/server/apps/distributed-app/docs/modules/ROOT/pages/configure/healthcheck.adoc
+++ b/server/apps/distributed-app/docs/modules/ROOT/pages/configure/healthcheck.adoc
@@ -19,4 +19,7 @@ If not specified, the mail reception check is a noop.
| reception.check.timeout
| Period after which mail reception is considered faulty. Defaults to one minute.
+
+| additional.healthchecks
+| List of fully qualified HealthCheck class names in addition to James' default healthchecks. Default to empty list.
|===
\ No newline at end of file
diff --git a/server/apps/distributed-app/sample-configuration/healthcheck.properties b/server/apps/distributed-app/sample-configuration/healthcheck.properties
index 9f3bad1898..284cfd85b8 100644
--- a/server/apps/distributed-app/sample-configuration/healthcheck.properties
+++ b/server/apps/distributed-app/sample-configuration/healthcheck.properties
@@ -28,3 +28,7 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+# additional.healthchecks=
+
diff --git a/server/apps/distributed-pop3-app/sample-configuration/healthcheck.properties b/server/apps/distributed-pop3-app/sample-configuration/healthcheck.properties
index 9f3bad1898..c796fee60b 100644
--- a/server/apps/distributed-pop3-app/sample-configuration/healthcheck.properties
+++ b/server/apps/distributed-pop3-app/sample-configuration/healthcheck.properties
@@ -28,3 +28,6 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+# additional.healthchecks=
diff --git a/server/apps/jpa-app/sample-configuration/healthcheck.properties b/server/apps/jpa-app/sample-configuration/healthcheck.properties
index 9f3bad1898..c796fee60b 100644
--- a/server/apps/jpa-app/sample-configuration/healthcheck.properties
+++ b/server/apps/jpa-app/sample-configuration/healthcheck.properties
@@ -28,3 +28,6 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+# additional.healthchecks=
diff --git a/server/apps/jpa-smtp-app/sample-configuration/healthcheck.properties b/server/apps/jpa-smtp-app/sample-configuration/healthcheck.properties
index 9f3bad1898..284cfd85b8 100644
--- a/server/apps/jpa-smtp-app/sample-configuration/healthcheck.properties
+++ b/server/apps/jpa-smtp-app/sample-configuration/healthcheck.properties
@@ -28,3 +28,7 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+# additional.healthchecks=
+
diff --git a/server/apps/memory-app/sample-configuration/healthcheck.properties b/server/apps/memory-app/sample-configuration/healthcheck.properties
index 9f3bad1898..c796fee60b 100644
--- a/server/apps/memory-app/sample-configuration/healthcheck.properties
+++ b/server/apps/memory-app/sample-configuration/healthcheck.properties
@@ -28,3 +28,6 @@
# Duration must be greater or at least equals to 10 seconds.
# healthcheck.period=60s
+# List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+# additional.healthchecks=
diff --git a/src/homepage/howTo/custom-healthchecks.html b/src/homepage/howTo/custom-healthchecks.html
new file mode 100644
index 0000000000..c1deb63a0b
--- /dev/null
+++ b/src/homepage/howTo/custom-healthchecks.html
@@ -0,0 +1,95 @@
+---
+layout: howTo
+---
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+<!-- Main -->
+<div id="main">
+
+ <!-- Introduction -->
+ <section id="intro" class="main special">
+ <div class="">
+ <div class="content align-left">
+ <header class="major">
+ <h1><b>Configure Custom Healthchecks</b></h1>
+ </header>
+
+ <p>
+ The current project demonstrates how to write custom healthchecks for Apache James.
+ This enables writing new custom healthcheck that fits your monitoring need.
+ </p>
+
+ <p>
+ Find this example on <a href="https://github.com/apache/james-project/tree/master/examples/custom-healthcheck">GitHub</a>.
+ </p>
+
+ <p>
+ Start by importing the dependencies:
+ </p>
+
+ <pre><code>
+<dependency>
+ <groupId>org.apache.james</groupId>
+ <artifactId>james-core</artifactId>
+</dependency>
+<dependency>
+ <groupId>io.projectreactor</groupId>
+ <artifactId>reactor-core</artifactId>
+</dependency>
+ </code></pre>
+
+ <p>You can then start writing your first HealthCheck by implementing HealthCheck interface.</p>
+
+ <p>You can compile this example project:</p>
+
+ <pre><code>mvn clean install</code></pre>
+
+ <p>Then embed your healthcheck into a James server. First configure your custom healthcheck into <code>healthcheck.properties</code>:</p>
+
+ <pre><code># List of fully qualified HealthCheck class names in addition to James' default healthchecks.
+# Healthchecks need to be located within the classpath or in the ./extensions-jars folder.
+additional.healthchecks=org.apache.james.examples.HealthCheckA</code></pre>
+
+ <p>Create a keystore (default password being <code>james72laBalle</code>):</p>
+
+ <pre><code>keytool -genkey -alias james -keyalg RSA -keystore keystore</code></pre>
+
+ <p>Then start a James server with your JAR and the configuration:</p>
+
+ <pre><code>docker run -d \
+ -v $PWD/healthcheck.properties:/root/conf/healthcheck.properties \
+ -v $PWD/healthcheck-extension.jar:/root/extensions-jars \
+ -v $PWD/keystore:/root/conf/keystore \
+ -p 25:25 \
+ apache/james:memory-latest</code></pre>
+
+ <p>You can use <code>curl</code> command to get your healthcheck status:</p>
+
+ <pre><code>$ curl -XGET http://172.17.0.2:8000/healthcheck</code></pre>
+ </div>
+ <footer class="major">
+ <ul class="actions align-center">
+ <li><a href="index.html" class="button">go back to other how-tos</a></li>
+ </ul>
+ </footer>
+ </div>
+ </section>
+
+</div>
diff --git a/src/homepage/howTo/index.html b/src/homepage/howTo/index.html
index 928791bbd6..501e696bb7 100644
--- a/src/homepage/howTo/index.html
+++ b/src/homepage/howTo/index.html
@@ -102,6 +102,13 @@ layout: howTo
class="james-schema" >
<span class="fa fa-sitemap"></span>Configure Custom WebAdmin routes<span class="fa fa-long-arrow-right"></span>
</a>
+ <a href="custom-healthchecks.html"
+ data-lightbox="james-schema"
+ data-title="Configure Custom Healthchecks"
+ alt="Configure Custom Healthchecks"
+ class="james-schema" >
+ <span class="fa fa-sitemap"></span>Configure Custom Healthchecks<span class="fa fa-long-arrow-right"></span>
+ </a>
<a href="custom-james-assembly.html"
data-lightbox="james-schema"
data-title="Write Custom James server assembly"
diff --git a/src/site/xdoc/server/config-healthcheck.xml b/src/site/xdoc/server/config-healthcheck.xml
index 0e7e9a4e99..432af54a78 100644
--- a/src/site/xdoc/server/config-healthcheck.xml
+++ b/src/site/xdoc/server/config-healthcheck.xml
@@ -42,6 +42,9 @@
<dt><strong>reception.check.timeout</strong></dt>
<dd>Period after which mail reception is considered faulty. Defaults to one minute.</dd>
+
+ <dt><strong>additional.healthchecks</strong></dt>
+ <dd>List of fully qualified HealthCheck class names in addition to James' default healthchecks. Default to empty list.</dd>
</dl>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org