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:33 UTC
(james-project) 01/03: [JAMES-4175] improves documentation build repeatability
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