docker-Edirom-Online

A Docker image running on eXist-db with a predeployed Edirom Online, and options for deploying additional XAR archives on-build or on-run.

Two Dockerfiles are provided:

• Dockerfile — fetches Edirom XARs from GitHub: downloads release assets when EDIROM_REF is a tag, or clones and builds from source when it is a branch. Requires a GitHub API token.
• Dockerfile.local — builds backend and frontend XARs from local source repositories. No GitHub token required. Use this for local development.

Both Dockerfiles share a common final stage (edirom-online) described below.

Dockerfile stages

• STAGE 1: xar-fetcher

  The xar-fetcher stage is based on bwbohl/sencha-cmd:2.1.1 and uses multiple strategies to retrieve the EXPath Packages (XAR archives) to be deployed to STAGE 2. One option is to inject local XAR archives (cf. Building the Docker Image).

• STAGE 2: edirom-online

  The edirom-online stage is based on stadlerpeter/existdb:6.4.0, which runs an eXist database. STAGE 2 copies XAR archives fetched by STAGE 1 and places them into the autodeploy directory of the eXist database. Moreover, it provides a method for deploying additional XAR archives to the eXist database when running the Docker image for the first time (cf. Running the Docker Image).

Dockerfile.local stages

• STAGE 1a: local-backend-builder — builds the backend XAR from local source using ant.
• STAGE 1b: local-frontend-builder — builds the frontend XAR from local source using Sencha Cmd.
• STAGE 1c: local-config-deployer-builder — builds a XAR tath automatically deploys a config.json to the installed Edirom Online Frontend.
• STAGE 2: edirom-online — identical to the final stage of Dockerfile.

Pulling the Docker Image

If you want to pull the latest version of a pre-built Docker image run:

docker pull ghcr.io/baz-ga/docker-edirom-online:latest

For available tags please visit: https://github.com/baz-ga/docker-edirom-online/pkgs/container/docker-edirom-online

Running the Docker Image

Note

docker run -p 8080:8080 -v `pwd`/add-xars:/var/add-xars ghcr.io/baz-ga/docker-edirom-online

If you want to run the Docker image and start using eXist-db with an installed Edirom Online, e.g., run:

docker run -p 8080:8080 ghcr.io/baz-ga/docker-edirom-online

Suppose you want to deploy additional XAR archives to the eXist database when running the Docker image for the first time. In that case, you can use the Docker -v flag to mount a local directory to the Docker image’s /var/add-xars directory, e.g. by running:

docker run -p 8080:8080 -v `pwd`/add-xars:/var/add-xars ghcr.io/baz-ga/docker-edirom-online

The final image (i.e., STAGE 2) will copy any XAR archive in your local directory to the autodeploy directory of the eXist database and thus deploy it on first run.

Important

Deploying additional XAR archives to eXist-db will only work when starting the database for the first time!

Environment Variables

As the final stage of the Docker image is based on stadlerpeter/existdb:6.4.0, all environment variables defined for it are valid run arguments for the Docker image.

For an overview, please visit the corresponding documentation

This Docker image overrides the following environment variables if not set to other values in the docker run command:

• EXIST_DEFAULT_APP_PATH

  Set to xmldb:exist:///db/apps/Edirom-Online (for EDIROM_VERSION_STRATEGY < 2.0.0) or xmldb:exist:///db/apps/Edirom-Online-Frontend (for >= 2.0.0) to make Edirom Online the default app.

• EXIST_CONTEXT_PATH

  Set to / to make Edirom Online available at the root of the configured host and port.

• EXIST_ENV

  Set to development.

• BACKEND_URL

  The URL written to config.json as backendURL for the Edirom Online Frontend. Defaults to the backend's installation path as resolved from the eXist-db package registry, falling back to /apps/Edirom-Online-Backend/. This absolute path is correct when EXIST_CONTEXT_PATH=/ (the default). Override this when the backend is served at a different URL. Override this when the backend is served at a different URL, e.g.:

  docker run -e BACKEND_URL="https://edirom.example.com/exist/apps/Edirom-Online-Backend/" ...

Building the Docker Image

[!WARNING] This repository uses gitmodules. This requires a recursive checkout or fetching the submodules after cloning.

For a recursive clone do:

git clone --recurse-submodules https://github.com/baz-ga/docker-edirom-online.git

For activating the submodules after cloning this repository do:

git submodule update --init --recursive

Building from Local Source (Dockerfile.local)

To build from local source repositories without a GitHub token, use Dockerfile.local with named build contexts pointing at your local checkouts:

docker build -f Dockerfile.local \
  --build-context backend=/path/to/Edirom-Online-Backend \
  --build-context frontend=/path/to/Edirom-Online-Frontend \
  -t edirom-online:local \
  .

?Important build arguments:

• BE_PORT — backend port injected into the frontend build (default: 8080)
• BE_HOST — backend host injected into the frontend build (default: localhost)
• BUILD_DATE – =$(date -u +"%Y-%m-%dT%H:%M:%SZ")
• EXIST_DEFAULT_APP_PATH
• SENCHA_BUILD_ENVIRONMENT – [production|testing|native|package] defaults to production

Building from GitHub (Dockerfile)

[!WARNING] Building this Docker image requires a GitHub API Token for fetching the Edirom XAR archives. There are several ways to provide your GitHub API Token securely (cf. Docker build secrets documentation).

For illustrative purposes, let's consider you save it in a simple text file, e.g., called MY_GITHUB_API_TOKEN. The file should contain a variable assignment in one of the following formats:

Option 1: Variable assignment (without export)

GITHUB_API_TOKEN="ghp_************************"

Option 2: Variable assignment (with export)

export GITHUB_API_TOKEN="ghp_************************"

Both formats are supported and will be sourced by the build script.

When issuing the build, you should provide this file using the --secret option, as in the following example:

--secret type=file,id=GITHUB_API_TOKEN,src=/PATH/TO/MY/SECRET/MY_GITHUB_API_TOKEN

Alternatively you can set the variable in your build environment’s shell, e.g.:

docker build -t ghcr.io/baz-ga/docker-edirom-online:mytag --secret type=file,id=GITHUB_API_TOKEN,src=/PATH/TO/MY/SECRET/MY_GITHUB_API_TOKEN .

Important

This repo provides a build.sh to ensure proper building of the Dockerimage. This mostly is connected to a proper extraction of the versions of the contained Edirom packages. Using build.sh is just as using docker build, just call ./build.sh instead and submit all the build arguments you would when building using docker build (except for the Dockerfile reference, e.g., .). The build.sh performs a two-step build, first building STAGE 1, then extracting the Edirom package versions, and finally building STAGE 1 and STAGE 2 for the final image (with set version numbers for the Dockerimage metadata). For example run:

./build.sh --secret type=file,id=GITHUB_API_TOKEN,src=/PATH/TO/MY/SECRET/MY_GITHUB_API_TOKEN -t ghcr.io/baz-ga/docker-edirom-online:mytag

Important

If you want to include additional XAR archives when building the image, place them in the add-xars directory next to the Dockerfile. These files will get copied by the xar-fetcher stage and handed to the edirom-online stage, which will place them in the eXist-db autodeploy directory!

Note

The config-deployer/ directory contains a minimal XAR package whose post-install.xql writes config.json to the Edirom Online Frontend collection after eXist-db deploys the application. This XAR is built and added to autodeploy automatically during the Docker image build — no manual action is required.

Controlling the Deployed Edirom Online Version

The xar-fetcher stage uses the xar-fetcher-entrypoint.sh to determine how to obtain the Edirom Online XAR archives, this depends on several build arguments:

• EDIROM_VERSION_STRATEGY

  The version strategy for fetching the Edirom Online XAR archives. (default: 1.0.0).

  The build differentiates between values greater than or equal to 2.0.0 and values less than 2.0.0 and applies different strategies:

  • < 2.0.0: download a monolithic Edirom Online including both the frontend and the backend. The assumed repository name is Edirom-Online.

  • >= 2.0.0: download separate Edirom Online Frontend and Edirom Online Backend. The assumed repository names are Edirom-Online-Frontend and Edirom-Online-Backend.

• EDIROM_OWNER

  The owner (organisation or user) of the Edirom-Online or Edirom-Online-Frontend and Edirom-Online-Backend repositories on GitHub (default: Edirom).

• EDIROM_REF

  The git reference (branch or tag) to use for fetching the Edirom Online XAR archives (default: v${EDIROM_VERSION_STRATEGY}).

  If the reference is a tag, the build assumes a tagged release and downloads any XAR archive (.xar) from the release assets.

  If the reference is a branch, the build will check out the branch and try to run build.sh in the branch’s root to create an XAR archive.

Other Build Arguments (ARGs)

• EDIROM_COMMIT

  The git SHA of the Edirom Online version (default: unknown). Will be used in the metadata of the final Docker image. When you build the image using build.sh from this repository, the git SHA of the installed Edirom XAR will be automatically determined.

• BUILD_DATE

  The date when the Docker image was built (default: 1970-01-01T00:00:00Z).

eXist-db Build Arguments

As the final stage of the Docker image is based on stadlerpeter/existdb:6.4.0, all build arguments defined for it are valid additional build arguments for the Docker image. For an overview, please visit the corresponding documentation.

Licences

This software is published under the terms of the GNU General Public License 3 (GPL-3.0-only).

Code required for execution of this software is published under the terms of the GNU General Public License 3 (GPL-3.0-only) licence, corresponding documentation is published under the terms of the Creative Commons Attribution-ShareAlike 4.0 International licence (CC-BY-SA 4.0). For a detailed clarification, please consult the individual licence and SPDX-License-Identifier statements in the preamble of each file.

Component Licences

Stage 1 (xar-fetcher)

• Base image: bwbohl/sencha-cmd - GPLv3
• baz-ga/gh-asset-downloader - GPLv3

Stage 2 (edirom-online)

• Base image: stadlerpeter/existdb - MIT License
  • Based on: eclipse-temurin:17-jre - Apache License 2.0
  • Includes: OpenJDK - GPLv2 with Classpath Exception
    • See DockerHub for additional licence information
• eXist-db - LGPL-2.1
• Edirom Online - GPLv3

Additional Software

The referenced Docker images may contain additional software under various licences.

User Responsibility

It is the responsibility of the user of any pre-built image to ensure that any use complies with all relevant licences for all software contained within.

Acknowledgements

This Docker image was developed in the context of the Bernd Alois Zimmermann-Gesamtausgabe project (BAZ-GA).

The Bernd Alois Zimmermann-Gesamtausgabe. Historisch-kritische Ausgabe seiner Werke, Schriften und Briefe (Bernd Alois Zimmermann Complete Edition. Historical-Critical Edition of his Works, Writings, and Letters) are promoted by the Union of the German Academies of Sciences and Humanities, represented by the Academy of Sciences and Humanities Berlin-Brandenburg and the Academy of Sciences and Literature | Mainz, funded by the Federal Ministry of Education and Research, Bonn and Berlin, the Berlin Senate Department for Higher Education and Research, Health and Long-Term Care and the Hessian Ministry of Science and the Arts, Wiesbaden.

For more information, please visit: https://www.zimmermann-gesamtausgabe.de.