Skip to content

website.adoc

Latest commit

 

History

History
182 lines (135 loc) · 5.29 KB

website.adoc

File metadata and controls

182 lines (135 loc) · 5.29 KB

Building and publishing the website

The source code of website james.apache.org is located in src/homepage.

Here are the instructions how to publish new changes to the website.

The website is currently composed of the output of

  • The homepage build

  • The maven site

Warning

We are migrating the content of the maven site to use 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 staging version of the website.

Building the homepage

You can use jekyll to build the website. Go into src/homepage and run the following command

Docker

Warning

The official docker image jekyll/jekyll is unmaintained and is not compatible with jekyll version beyond 4.2.2. In this documentation we suggest a replacement jvconseil/jekyll-docker but note that this is not an official image. Use at your own risks.

 
$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jvconseil/jekyll-docker:4 jekyll build

The resulting deployable content will be available in the src/homepage/_site/ directory.

In order to test the homepage, you can use this command:

$ docker run --rm -v $PWD/site:/srv/jekyll -p 4000:4000 -it jvconseil/jekyll-docker:4 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:

$ git clone https://git-wip-us.apache.org/repos/asf/james-site.git
$ cd james-site
$ git checkout origin/asf-site -b asf-site

make sure to build the site then copy the output to

$ docker run --rm -v="$PWD:/srv/jekyll:Z" -it jvconseil/jekyll-docker:4 jekyll build
$ cp  ../james-site/content

Then just push the new site:

$ cd ../james-site
$ git push origin asf-site

Experimental nix environment

From the root of the repository checkout, you can use the flake’s devshell

$ cd src/homepage
$ nix develop

Then use jekyll directly

$ jekyll serve
# or
$ jekyll build

Gemset update for nix

Updating the gemset to track the gemfile updates is a bit involved :

  1. ensure you are out of all nix devshell (check using echo $SHLVL it should be 1)

  2. create a temporary shell for gem manipulation nix-shell -p ruby -p bundix

  3. update the gemfile then run

    BUNDLE_FORCE_RUBY_PLATFORM="true" bundle lock --update
bundix -l

  4. exit the temporary shell and enter the devShell again nix develop

Maven site

The maven site deploy phase uses and requires locally configuring credentials to enable ssh access. See maven-deploy-plugin’s documentation for more details on achieving this.

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 package site -Djib.skip

  3. Test the built site in your browser from the src/homepage/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.

 
$ 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 james experimental development shell with nix develop.

  1. run mvn clean package site -Djib.skip

  2. Test the built site in your browser from the src/homepage/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 (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

The old maven site is quite painful to maintain and doesn’t allow for versionning of the content per releases which motivated the 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.