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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
