You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@james.apache.org by jh...@apache.org on 2026/02/27 07:50:32 UTC

(james-project) branch master updated (0e683e077a -> e28b26bd86)

This is an automated email from the ASF dual-hosted git repository.

jhelou pushed a change to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git


    from 0e683e077a [devscout] fix antora doc version
     new d252250cc3 [JAMES-4175] improves documentation build repeatability
     new 2dee790b0a [JAMES-4175] fix maven site build
     new e28b26bd86 [JAMES-4175] fix website build instructions

The 3 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 docs/README.adoc                            |   1 +
 docs/README.md                              |  33 -------
 docs/modules/community/pages/website.adoc   | 145 ++++++++++++++++++++++------
 docs/modules/community/partials/antora.adoc |  60 ++++++++++++
 flake.nix                                   |   1 +
 pom.xml                                     | 119 +++++++++++++++++------
 src/homepage/.gitignore                     |   3 +
 src/homepage/Gemfile                        |   1 +
 src/homepage/Gemfile.lock                   |  81 ++++++++++++++++
 src/site/site.xml                           |  21 ++--
 10 files changed, 360 insertions(+), 105 deletions(-)
 create mode 120000 docs/README.adoc
 delete mode 100644 docs/README.md
 create mode 100644 docs/modules/community/partials/antora.adoc
 create mode 100644 src/homepage/.gitignore
 create mode 100644 src/homepage/Gemfile.lock


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org


(james-project) 03/03: [JAMES-4175] fix website build instructions

Posted by jh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

jhelou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit e28b26bd86eee68bb058d40b70f9e483570b8b53
Author: Jean Helou <je...@xn--gml-cma.com>
AuthorDate: Thu Feb 26 07:24:18 2026 +0100

    [JAMES-4175] fix website build instructions
    
    Ensures README is always aligned with antora build section in community/websitew
---
 docs/README.adoc                            |  1 +
 docs/README.md                              | 33 --------------
 docs/modules/community/pages/website.adoc   | 68 ++++++++++++++++++++---------
 docs/modules/community/partials/antora.adoc | 60 +++++++++++++++++++++++++
 4 files changed, 109 insertions(+), 53 deletions(-)

diff --git a/docs/README.adoc b/docs/README.adoc
new file mode 120000
index 0000000000..292bc3f151
--- /dev/null
+++ b/docs/README.adoc
@@ -0,0 +1 @@
+docs/modules/community/partials/antora.adoc
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index 2b5b72e315..0000000000
--- a/docs/README.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Building and serving documentation locally
-
-## Executing within source code
-
-(Clone `https://github.com/apache/james-project` locally, go into `docs` folder)
-
-**Step 1**: [Install Antora](https://docs.antora.org/antora/latest/install-and-run-quickstart/)
-
-**Step 2**: Build the Antora content locally
-
-```
-antora antora-playbook-local.yml
-```
-
-**Step 3**: Open `build/site/index.html` in your browser.
-
-## Building with Dockerfile
-
-To build the document from apache-james repository, you can use the Dockerfile provided in this folder.
-
-Build the Docker image:
-
-```
-docker build --build-arg JAMES_CHECKOUT=master -f Dockerfile -t james-site-antora .
-```
-
-Then run the Docker image:
-
-```
-docker run -p 80:80 james-site-antora
-```
-
-Go to `http://localhost` in your browser.
diff --git a/docs/modules/community/pages/website.adoc b/docs/modules/community/pages/website.adoc
index 69bff57cc2..4ece0bb671 100644
--- a/docs/modules/community/pages/website.adoc
+++ b/docs/modules/community/pages/website.adoc
@@ -1,7 +1,9 @@
 = Building and publishing the website
 :path: src/homepage
 
-The source code of website https://james.apache.org[james.apache.org] is located in {path}.
+The source code of website https://james.apache.org[james.apache.org] is
+located in {path}.
+
 Here are the instructions how to publish new changes to the website.
 
 The website is currently composed of the output of
@@ -12,9 +14,11 @@ The website is currently composed of the output of
 [WARNING]
 .https://issues.apache.org/jira/browse/JAMES-3187[Documentation migration]
 ====
-We are migrating the content of the maven site to use antora documentation instead.
+We are migrating the content of the maven site to use xref:_building_the_next_gen_documentation[antora documentation] instead.
 
-Most of the useful content has been migrated but the new documentation is not yet published to the main site. It can be found on the https://james.staged.apache.org[staging version] of the website.
+Most of the useful content has been migrated but the new documentation is not
+yet published to the main site. It can be found on the
+https://james.staged.apache.org[staging version] of the website.
 ====
 
 == Building the homepage
@@ -25,7 +29,8 @@ You can use jekyll to build the website. Go into `{path}` and run the following
 $ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jekyll/jekyll:$JEKYLL_VERSION  jekyll build
 ----
 
-The resulting deployable content will be available in the `{path}/_site/` directory.
+The resulting deployable content will be available in the `{path}/_site/`
+directory.
 
 In order to test the homepage, you can use this command:
 [,shell]
@@ -35,7 +40,8 @@ $ docker run --rm -v $PWD/site:/srv/jekyll  -p 4000:4000 -it jekyll/jekyll jekyl
 The site will be available at http://localhost:4000/
 
 
-If you need to update the current site, checkout the branch asf-site from Apache git:
+If you need to update the current site, checkout the branch asf-site from
+Apache git:
 [,shell]
 ----
 $ git clone https://git-wip-us.apache.org/repos/asf/james-site.git
@@ -43,7 +49,8 @@ $ cd james-site
 $ git checkout origin/asf-site -b asf-site
 ----
 
-And replace in the previous commands `$PWD/site` by `<james-site-clone-directory>/content`, for example:
+And replace in the previous commands `$PWD/site` by
+`<james-site-clone-directory>/content`, for example:
 
 [,shell]
 ----
@@ -58,22 +65,27 @@ $ cd ../james-site
 $ git push origin asf-site
 ----
 
-## Maven site
+== Maven site
 
-The maven site deploy phase uses and requires locally configuring credentials to enable ssh access. See
+The maven site deploy phase uses and requires locally configuring credentials to
+enable ssh access. See
 http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html[maven-deploy-plugin's documentation] for more details on achieving this.
 
-### Manually
+WARNING: Generating the full maven site with all reports takes a long time
+(as in hours)
+
+=== Manually
 
 1. Install Apache Maven 3.0.2+ and make its binary 'mvn' available on your PATH.
 See http://maven.apache.org/download.html#Installation.
-2. run `mvn clean site`
+2. run `mvn clean package site -Djib.skip`
 3. Test the built site in your browser from the `{path}/target/site` folder
 4. If everything looks OK, deploy the site using `mvn clean site-deploy`.
-5. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
-a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+5. Wait for the changes to replicate to the Apache web server or setup
+140.211.11.10:80 as a proxy to review the changes (described here:
+http://www.apache.org/dev/project-site.html)
 
-### Docker
+=== Docker
 
 Can be used only to build the site locally
 
@@ -94,18 +106,34 @@ $ docker build -t james/site src/site-docker
 $ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination james/site master
 ----
 
-### nix development shell
+=== Nix development shell
 
-Enter the xref:contributing.adoc#_experimental_nix_support[james experimental development shell]
+Enter the xref:contributing.adoc#_experimental_nix_support[james experimental
+development shell]
 
-1. run `mvn clean site`
+1. run `mvn clean package site -Djib.skip`
 2. Test the built site in your browser from the `{path}/target/site` folder
 3. If everything looks OK, deploy the site using `mvn clean site-deploy`.
-4. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
-a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+4. Wait for the changes to replicate to the Apache web server or setup
+140.211.11.10:80 as a proxy to review the changes
+(see: http://www.apache.org/dev/project-site.html)
+
+=== Technical reports
+
+To deploy the technical reports use any of the 3 ways above adding the
+`-Psite-reports` profile.
+
+== Building the next gen documentation
 
-### Technical reports
+The old maven site is quite painful to maintain and doesn't allow for
+versionning of the content per releases which motivated the
+https://issues.apache.org/jira/browse/JAMES-3187[migration effort].
 
-To deploy the technical reports use any of the 3 ways above adding the `-Psite-reports` profile.
+Most of the maven site content has been migrated to asciidoc files assembled by
+antora. You can preview the content at https://james.staged.apache.org, this
+documentation is published automatically by the james CI.
 
+This new documentation root is located in the `docs` directory and includes
+these build instructions.
 
+include::partial$antora.adoc[]
diff --git a/docs/modules/community/partials/antora.adoc b/docs/modules/community/partials/antora.adoc
new file mode 100644
index 0000000000..fedaff768d
--- /dev/null
+++ b/docs/modules/community/partials/antora.adoc
@@ -0,0 +1,60 @@
+== Building the next gen documentation
+:page-partial:
+
+The old maven site is quite painful to maintain and doesn't allow for
+versionning of the content per releases which motivated the
+https://issues.apache.org/jira/browse/JAMES-3187[migration effort].
+
+Most of the maven site content has been migrated to asciidoc files assembled by
+antora. You can preview the content at https://james.staged.apache.org, this
+documentation is published automatically by the james CI.
+
+This new documentation root is located in the `docs` directory and includes
+these build instructions.
+
+=== Executing within source code
+
+(Clone `https://github.com/apache/james-project` locally, go into `docs` folder)
+
+. https://docs.antora.org/antora/latest/install-and-run-quickstart/[Install Antora]
+
+. Build the Antora content locally
++
+[,shell]
+----
+ $ antora antora-playbook-local.yml
+----
++
+. Open `build/site/index.html` in your browser.
+
+=== Building with Dockerfile
+
+To build the document from apache-james repository, you can use the Dockerfile provided in this folder.
+
+Build the Docker image:
+
+----
+docker build --build-arg JAMES_CHECKOUT=master -f Dockerfile -t james-site-antora .
+----
+
+Then run the Docker image:
+
+----
+docker run -p 80:80 james-site-antora
+----
+
+Go to `http://localhost` in your browser.
+
+=== Build with the nix enviroment
+
+Enter the xref:contributing.adoc#_experimental_nix_support[james experimental
+development shell]
+
+. Build the Antora content locally
++
+[,shell]
+----
+ $ antora antora-playbook-local.yml
+----
++
+. Open `build/site/index.html` in your browser.
\ No newline at end of file


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org


(james-project) 02/03: [JAMES-4175] fix maven site build

Posted by jh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

jhelou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit 2dee790b0afc36d7c3974a813f1f47198c6a96a5
Author: Jean Helou <je...@xn--gml-cma.com>
AuthorDate: Thu Feb 26 07:19:26 2026 +0100

    [JAMES-4175] fix maven site build
    
    The current process removes all modules from the root POM resulting in no reports being generated.
    
    This commit improves the situation by restoring a full maven site generation and disabling only problematic reports :
    
    javadoc triggers unresolved symbols in mpt/mavenplugin
    
    findbugs is not compatible with our current jdk and requires a migration to spotbugs
---
 pom.xml           | 119 ++++++++++++++++++++++++++++++++++++++++--------------
 src/site/site.xml |  21 ++++------
 2 files changed, 97 insertions(+), 43 deletions(-)

diff --git a/pom.xml b/pom.xml
index 7af94808aa..226b996296 100644
--- a/pom.xml
+++ b/pom.xml
@@ -609,6 +609,7 @@
             otherwise the set values are used by default.
         -->
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
+        <project.build.outputTimestamp>1980-01-01T00:00:02Z</project.build.outputTimestamp>
         <target.jdk>21</target.jdk>
         <maven.compiler.source>${target.jdk}</maven.compiler.source>
         <maven.compiler.target>${target.jdk}</maven.compiler.target>
@@ -3657,7 +3658,7 @@
                 <plugin>
                     <groupId>org.apache.maven.plugins</groupId>
                     <artifactId>maven-javadoc-plugin</artifactId>
-                    <version>3.11.2</version>
+                    <version>3.12.0</version>
                     <configuration>
                         <!-- The javadoc plugin only runs in the javadoc modules. But with the default configuration it tries
                               to run a new maven instance in every dependency, in order to generate the apidocs there as well.
@@ -3814,33 +3815,7 @@
                 <plugin>
                     <groupId>org.apache.rat</groupId>
                     <artifactId>apache-rat-plugin</artifactId>
-                    <version>0.16.1</version>
-                    <configuration>
-                        <excludes>
-                            <exclude>BUILDING.*</exclude>
-                            <exclude>HOWTO.*</exclude>
-                            <exclude>HOWTO_*</exclude>
-                            <exclude>LICENSE.*</exclude>
-                            <exclude>NOTICE.*</exclude>
-                            <!-- site resources -->
-                            <exclude>src/site/resources/download*.cgi</exclude>
-                            <exclude>src/site/resources/downloads/formatting.xml</exclude>
-                            <exclude>src/site/resources/js/galleria/**</exclude>
-                            <exclude>src/site/resources/model-eclipse-modeler/*</exclude>
-                            <exclude>src/site/resources/robots.txt</exclude>
-                            <!-- Generated by Maven -->
-                            <exclude>release.properties</exclude>
-                            <exclude>dist/**/*</exclude>
-                            <exclude>**/derby.log</exclude>
-                            <exclude>**/h2.log</exclude>
-                            <!-- Eclipse -->
-                            <exclude>**/.*</exclude>
-                            <exclude>.*/**/*</exclude>
-                            <!-- Schemas for offline use -->
-                            <exclude>**/META-INF/XSD/activemq-core-*.xsd</exclude>
-                            <exclude>**/META-INF/XSD/spring-beans-*.xsd</exclude>
-                        </excludes>
-                    </configuration>
+                    <version>0.17</version>
                 </plugin>
                 <plugin>
                     <groupId>org.codehaus.mojo</groupId>
@@ -3872,7 +3847,7 @@
                 <plugin>
                     <groupId>org.codehaus.mojo</groupId>
                     <artifactId>versions-maven-plugin</artifactId>
-                    <version>2.18.0</version>
+                    <version>2.21.0</version>
                 </plugin>
                 <plugin>
                     <groupId>org.eclipse.m2e</groupId>
@@ -4081,7 +4056,8 @@
                     <dotGitDirectory>${project.basedir}/.git</dotGitDirectory>
                     <injectAllReactorProjects>true</injectAllReactorProjects>
                     <generateGitPropertiesFile>true</generateGitPropertiesFile>
-                    <generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties</generateGitPropertiesFilename>
+                    <generateGitPropertiesFilename>${project.build.outputDirectory}/git.properties
+                    </generateGitPropertiesFilename>
                     <failOnNoGitDirectory>false</failOnNoGitDirectory>
                     <format>json</format>
                     <gitDescribe>
@@ -4138,31 +4114,114 @@
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-project-info-reports-plugin</artifactId>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>ci-management</report>
+                            <report>dependencies</report>
+                            <report>dependency-info</report>
+                            <report>dependency-management</report>
+                            <report>distribution-management</report>
+                            <report>index</report>
+                            <report>issue-management</report>
+                            <report>licenses</report>
+                            <report>mailing-lists</report>
+                            <!--
+                            disabled to avoid slowly failing but non blocking  resolution
+                            https://issues.apache.org/jira/browse/JAMES-4180
+                            -->
+                            <!--<report>plugin-management</report>-->
+                            <report>plugins</report>
+                            <report>scm</report>
+                            <report>summary</report>
+                            <report>team</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
             </plugin>
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-jxr-plugin</artifactId>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>jxr-no-fork</report>
+                            <report>test-jxr-no-fork</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
             </plugin>
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-dependency-plugin</artifactId>
             </plugin>
+
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-surefire-report-plugin</artifactId>
             </plugin>
+
             <plugin>
                 <groupId>org.apache.rat</groupId>
                 <artifactId>apache-rat-plugin</artifactId>
+                <configuration>
+                    <inputExcludes>
+                        <inputExclude>BUILDING.*</inputExclude>
+                        <inputExclude>HOWTO.*</inputExclude>
+                        <inputExclude>HOWTO_*</inputExclude>
+                        <inputExclude>LICENSE.*</inputExclude>
+                        <inputExclude>NOTICE.*</inputExclude>
+                        <!-- site resources -->
+                        <inputExclude>src/site/resources/download*.cgi</inputExclude>
+                        <inputExclude>src/site/resources/downloads/formatting.xml</inputExclude>
+                        <inputExclude>src/site/resources/js/galleria/**</inputExclude>
+                        <inputExclude>src/site/resources/model-eclipse-modeler/*</inputExclude>
+                        <inputExclude>src/site/resources/robots.txt</inputExclude>
+                        <!-- Generated by Maven -->
+                        <inputExclude>release.properties</inputExclude>
+                        <inputExclude>dist/**/*</inputExclude>
+                        <inputExclude>**/derby.log</inputExclude>
+                        <inputExclude>**/h2.log</inputExclude>
+                        <!-- Eclipse -->
+                        <inputExclude>**/.*</inputExclude>
+                        <inputExclude>.*/**/*</inputExclude>
+                        <!-- Schemas for offline use -->
+                        <inputExclude>**/META-INF/XSD/activemq-core-*.xsd</inputExclude>
+                        <inputExclude>**/META-INF/XSD/spring-beans-*.xsd</inputExclude>
+                    </inputExcludes>
+                </configuration>
             </plugin>
+<!--
+            Even using the -no-fork variant of hte tasks, generating this reports
+            triggers unresolved symbols errors which need to be further investigated
+            trakced in https://issues.apache.org/jira/browse/JAMES-4178
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
                 <artifactId>maven-javadoc-plugin</artifactId>
+                <reportSets>
+                    <reportSet>
+                        <reports>
+                            <report>javadoc-no-fork</report>
+                            <report>test-javadoc-no-fork</report>
+                        </reports>
+                    </reportSet>
+                </reportSets>
             </plugin>
+-->
+
+<!--
+            This plugin is not compatible with jdk21, so I disabled it
+            temporarily.
+            it appears the successor is spotbugs but we should do this migration
+            in a separate effort https://issues.apache.org/jira/browse/JAMES-4179
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>findbugs-maven-plugin</artifactId>
             </plugin>
+
+-->
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>versions-maven-plugin</artifactId>
diff --git a/src/site/site.xml b/src/site/site.xml
index 4fa2d2f21a..23d6cf4c5f 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -17,10 +17,10 @@
     specific language governing permissions and limitations
     under the License.
 -->
-<project
-    xmlns="http://maven.apache.org/DECORATION/1.0.0"
+<site
+    xmlns="http://maven.apache.org/SITE/2.0.0"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-    xsi:schemaLocation="http://maven.apache.org/DECORATION/1.0.0 http://maven.apache.org/xsd/decoration-1.0.0.xsd"
+    xsi:schemaLocation="http://maven.apache.org/SITE/2.0.0 https://maven.apache.org/xsd/site-2.0.0.xsd"
     name="Apache James Project">
 
     <skin>
@@ -29,17 +29,12 @@
         <version>${james-skin.version}</version>
     </skin>
 
-    <bannerLeft>
-        <name>James Project</name>
-        <src>images/logos/james-logo.png</src>
-        <href>https://james.apache.org/index.html</href>
-        <alt>james-logo.png</alt>
+    <bannerLeft name="James Project" href="https://james.apache.org/index.html" >
+        <image src="images/logos/james-logo.png"  alt="james-logo.png"/>
     </bannerLeft>
 
-    <bannerRight>
-        <name>The Apache Software Foundation</name>
-        <src>images/logos/asf_logo_small.png</src>
-        <href>https://www.apache.org/index.html</href>
+    <bannerRight name="The Apache Software Foundation" href="https://www.apache.org/index.html">
+        <image src="images/logos/asf_logo_small.png"/>
     </bannerRight>
 
     <version position="none" />
@@ -230,4 +225,4 @@
 
     </body>
 
-</project>
+</site>


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org


(james-project) 01/03: [JAMES-4175] improves documentation build repeatability

Posted by jh...@apache.org.
This is an automated email from the ASF dual-hosted git repository.

jhelou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/james-project.git

commit d252250cc3c06f4ec6d0a4ea178975f8f867f8b2
Author: Jean Helou <je...@xn--gml-cma.com>
AuthorDate: Fri Feb 20 13:01:12 2026 +0100

    [JAMES-4175] improves documentation build repeatability
    
    - Adds missing `bundler` command.
    - Adds Gemfile.lock so `bundle install` downloads the same artifacts.
    - gitignore jekyll output directory
    - update website build instructions
---
 docs/modules/community/pages/website.adoc | 117 ++++++++++++++++++++++--------
 flake.nix                                 |   1 +
 src/homepage/.gitignore                   |   3 +
 src/homepage/Gemfile                      |   1 +
 src/homepage/Gemfile.lock                 |  81 +++++++++++++++++++++
 5 files changed, 174 insertions(+), 29 deletions(-)

diff --git a/docs/modules/community/pages/website.adoc b/docs/modules/community/pages/website.adoc
index 2e831784ff..69bff57cc2 100644
--- a/docs/modules/community/pages/website.adoc
+++ b/docs/modules/community/pages/website.adoc
@@ -4,49 +4,108 @@
 The source code of website https://james.apache.org[james.apache.org] is located in {path}.
 Here are the instructions how to publish new changes to the website.
 
-1. Install Apache Maven 3.0.2+ and make its binary 'mvn' available on your PATH.
-See http://maven.apache.org/download.html#Installation.
-2. run "mvn clean site"
-3. Test the built site in your browser from the {path}/target/site folder
-4. If everything looks OK, deploy the site using "mvn clean site-deploy".
-5. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
-a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+The website is currently composed of the output of
 
-To deploy the technical reports use the "-Psite-reports" profile.
+- The homepage build
+- The maven site
 
-For wagon-ssh-external configuration see
-http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html
+[WARNING]
+.https://issues.apache.org/jira/browse/JAMES-3187[Documentation migration]
+====
+We are migrating the content of the maven site to use antora documentation instead.
 
-You can alternatively use a docker container to build the website :
+Most of the useful content has been migrated but the new documentation is not yet published to the main site. It can be found on the https://james.staged.apache.org[staging version] of the website.
+====
 
-You need to build the homepage by:
+== Building the homepage
+You can use jekyll to build the website. Go into `{path}` and run the following command
 
-    $ docker build -t james/homepage src/homepage-docker
-    $ docker run -v $PWD:/origin -v $PWD/site:/destination james/homepage master
+[,shell]
+----
+$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jekyll/jekyll:$JEKYLL_VERSION  jekyll build
+----
+
+The resulting deployable content will be available in the `{path}/_site/` directory.
 
 In order to test the homepage, you can use this command:
+[,shell]
+----
+$ docker run --rm -v $PWD/site:/srv/jekyll  -p 4000:4000 -it jekyll/jekyll jekyll serve
+----
+The site will be available at http://localhost:4000/
 
-    $ docker run --rm -v $PWD/site:/srv/jekyll  -p 4000:4000 -it jekyll/minimal:3.8.3 jekyll serve
 
-the site will be available at http://localhost:4000/
+If you need to update the current site, checkout the branch asf-site from Apache git:
+[,shell]
+----
+$ git clone https://git-wip-us.apache.org/repos/asf/james-site.git
+$ cd james-site
+$ git checkout origin/asf-site -b asf-site
+----
 
-Then you build the other pages by:
+And replace in the previous commands `$PWD/site` by `<james-site-clone-directory>/content`, for example:
 
-    $ docker build -t james/site src/site-docker
-    $ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination james/site master
+[,shell]
+----
+$ docker run -v $PWD:/origin -v $PWD/../james-site/content:/destination james/homepage master
+$ docker run -v $PWD/.m2:/root/.m2 -v $PWD/../james-site/content:/origin -v $PWD/site:/destination james/site master
+----
 
-If you need to update the current site, checkout the branch asf-site from Apache git:
+Then just push the new site:
+[,shell]
+----
+$ cd ../james-site
+$ git push origin asf-site
+----
 
-    $ git clone https://git-wip-us.apache.org/repos/asf/james-site.git
-    $ cd james-site
-    $ git checkout origin/asf-site -b asf-site
+## Maven site
 
-And replace in the previous commands `$PWD/site` by `<james-site-clone-directory>/content`, for example:
+The maven site deploy phase uses and requires locally configuring credentials to enable ssh access. See
+http://maven.apache.org/plugins/maven-deploy-plugin/examples/deploy-ssh-external.html[maven-deploy-plugin's documentation] for more details on achieving this.
 
-    $ docker run -v $PWD:/origin -v $PWD/../james-site/content:/destination james/homepage master
-    $ docker run -v $PWD/.m2:/root/.m2 -v $PWD/../james-site/content:/origin -v $PWD/site:/destination james/site master
+### Manually
+
+1. Install Apache Maven 3.0.2+ and make its binary 'mvn' available on your PATH.
+See http://maven.apache.org/download.html#Installation.
+2. run `mvn clean site`
+3. Test the built site in your browser from the `{path}/target/site` folder
+4. If everything looks OK, deploy the site using `mvn clean site-deploy`.
+5. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
+a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+
+### Docker
+
+Can be used only to build the site locally
+
+[WARNING]
+.Contribution welcome
+====
+The docker file in `src/site-docker` is currently broken:
+
+- outdated JDK (11 instead of 21)
+- "manual" download of maven from a link which doesn't resolve anymore
+
+prepare for some tinkering before building using this method.
+====
+
+[,shell]
+----
+$ docker build -t james/site src/site-docker
+$ docker run -v $PWD/.m2:/root/.m2 -v $PWD:/origin -v $PWD/site:/destination james/site master
+----
+
+### nix development shell
+
+Enter the xref:contributing.adoc#_experimental_nix_support[james experimental development shell]
+
+1. run `mvn clean site`
+2. Test the built site in your browser from the `{path}/target/site` folder
+3. If everything looks OK, deploy the site using `mvn clean site-deploy`.
+4. Wait for the changes to replicate to the Apache web server or setup 140.211.11.10:80 as
+a proxy to review the changes (described here: http://www.apache.org/dev/project-site.html)
+
+### Technical reports
+
+To deploy the technical reports use any of the 3 ways above adding the `-Psite-reports` profile.
 
-Then just push the new site:
 
-    $ cd ../james-site
-    $ git push origin asf-site
diff --git a/flake.nix b/flake.nix
index cc9b2638f1..fb7d562565 100644
--- a/flake.nix
+++ b/flake.nix
@@ -28,6 +28,7 @@
         default = pkgs.mkShell {
           packages = with pkgs; [
             antora  # build documentation
+            bundler # homepage and blog
             cacert  # ssl certificate management
             dive    # explore generated docker images
             git     # version control
diff --git a/src/homepage/.gitignore b/src/homepage/.gitignore
new file mode 100644
index 0000000000..d317b536b9
--- /dev/null
+++ b/src/homepage/.gitignore
@@ -0,0 +1,3 @@
+_site/
+.run
+.jekyll-cache/
\ No newline at end of file
diff --git a/src/homepage/Gemfile b/src/homepage/Gemfile
index 1f0d3cd0d0..f984cef319 100644
--- a/src/homepage/Gemfile
+++ b/src/homepage/Gemfile
@@ -21,6 +21,7 @@ source 'https://rubygems.org'
 ruby RUBY_VERSION
 
 gem 'jekyll'
+gem 'webrick'
 
 #source "https://rubygems.org"
 
diff --git a/src/homepage/Gemfile.lock b/src/homepage/Gemfile.lock
new file mode 100644
index 0000000000..c2acc28395
--- /dev/null
+++ b/src/homepage/Gemfile.lock
@@ -0,0 +1,81 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.1)
+      public_suffix (>= 2.0.2, < 6.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.1.10)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.15.5)
+    forwardable-extended (2.6.0)
+    http_parser.rb (0.8.0)
+    i18n (1.12.0)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.2.2)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (~> 2.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (~> 0.4.0)
+      pathutil (~> 0.9)
+      rouge (~> 3.0)
+      safe_yaml (~> 1.0)
+      terminal-table (~> 2.0)
+    jekyll-feed (0.17.0)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (2.2.0)
+      sassc (> 2.0.1, < 3.0)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.3)
+    listen (3.7.1)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    minima (2.5.1)
+      jekyll (>= 3.5, < 5.0)
+      jekyll-feed (~> 0.9)
+      jekyll-seo-tag (~> 2.1)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (5.0.0)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.5)
+    rouge (3.30.0)
+    safe_yaml (1.0.5)
+    sassc (2.4.0)
+      ffi (~> 1.9)
+    terminal-table (2.0.0)
+      unicode-display_width (~> 1.1, >= 1.1.1)
+    unicode-display_width (1.8.0)
+    webrick (1.9.2)
+
+PLATFORMS
+  x86_64-linux-musl
+
+DEPENDENCIES
+  jekyll
+  minima
+  webrick
+
+RUBY VERSION
+   ruby 3.1.1p18
+
+BUNDLED WITH
+   2.3.25


---------------------------------------------------------------------
To unsubscribe, e-mail: notifications-unsubscribe@james.apache.org
For additional commands, e-mail: notifications-help@james.apache.org