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 <hqt...@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-unsubscr...@james.apache.org For additional commands, e-mail: notifications-h...@james.apache.org