Build and Delivery

Audience: Technical administration

Overview

oPBWeb consists of three images of its own: backend (for api and worker), frontend (nginx with user interface and manual) and garage-init. You either build them locally with ./start.sh --build or let GitLab CI build them and push them to the project registry. The CI also generates the manual as PDF. This chapter describes the images, the pipeline and how to build the manual locally.

Images

All Dockerfiles use the project directory as build context. Among other things, .dockerignore keeps secrets/, certs/, .env, node_modules/ as well as the Hugo output and manual/.doc-state/ out of the context.

Backend

backend/Dockerfile, one image for api and worker:

Locally, this produces opbweb-backend:latest (production) or opbweb-backend:dev (dev stack).

Frontend

frontend/Dockerfile:

The manual is therefore an integral part of the frontend image. A change to the manual appears in the web interface only with a newly built frontend image.

garage-init

garage/Dockerfile.garage-init: alpine:3.21 with bash, jq and curl plus the script garage/init-garage.sh. Locally, the image is called opbweb-garage-init:1.0.0. The version is fixed and only changes when the Dockerfile or the script changes.

Network access during the build

For a build, the host needs access to Docker Hub (base images), GitHub (python-opsi, Hugo modules), PyPI, the npm registry and the Go module proxy proxy.golang.org (Docsy). The launcher needs no third-party Go modules.

GitLab CI pipeline

The pipeline is defined in .gitlab-ci.yml. The jobs run on runners with the tag dind and build with Docker-in-Docker.

Stages and jobs

The pipeline reads the versions from backend/src/core/version.py and frontend/package.json. The images end up in the project registry under <registry>/<project path>/backend, …/frontend and …/garage-init (path in lowercase). The registry address is set as CI_REGISTRY in .gitlab-ci.yml.

Stack ZIP

The job stack-release packs everything a Docker host needs to set up and start with the registry images into oPBWeb-Stack-<pipeline no>.zip, without sources:

docker-compose.dev.yml is left out on purpose: the development stack mounts the sources. Without sources, setup-opbweb.sh offers no local build and start.sh --dev stops with a message. The ZIP is stored in the generic package stack/<pipeline no> of the project registry and linked from the release oPBWeb Stack (tag stack-latest), which every run recreates.

Using the images from the registry

The target host then does not need to build the images. In ./setup-opbweb.sh, choose r at the images question and enter the registry prefix (default: the registry of this CI, a different one via OPBWEB_REGISTRY) and the versions you want. The script writes BACKEND_IMAGE, FRONTEND_IMAGE and GARAGE_INIT_IMAGE to .env. Then pull the images (sign in with docker login first if the registry requires it) with docker compose pull and start with ./start.sh without --build. Details are in Installation and Configuration .

When each job runs

On the default branch of the project (set in GitLab under Settings → Repository, e.g. master or main), the jobs start automatically when their triggers change:

A new backend or frontend image is therefore typically created by setting a new version with set-version.sh, see Operation and Updates . A change to the manual alone produces new PDFs but no new frontend image; for that you need a new frontend version or a manual run of build-frontend.

Starting the pipeline manually

When you start a pipeline manually in GitLab, you choose what should run with the input run_job:

The scans check the image with the current version number from the registry. It must therefore have been built and pushed beforehand.

Container scanning

The scan jobs use the GitLab template Jobs/Container-Scanning.gitlab-ci.yml with the threshold HIGH. The reports are available as job artifacts (gl-container-scanning-report-backend.json, gl-container-scanning-report-frontend.json) and appear in GitLab’s security reports.

Manual PDFs

The job build-manuals runs in the image python:3, installs WeasyPrint, Hugo extended version 0.154.5 (variable HUGO_VERSION), Go, Node.js and the GitLab release-cli, and then calls manual/build-pdf.sh output. It produces one PDF file per part and language:

<Version> is the frontend version. The job uploads the PDFs to the generic package manuals/latest in the project registry; it deletes files with the same name first. It then recreates the release manuals-latest („oPBWeb Handbücher“ – oPBWeb manuals) with one link per PDF („DE: Installation“, „EN: User Guide“ and so on) and the build date, pipeline number and frontend version in the description. In addition, the PDFs are kept as job artifacts for 30 days.

Building the manual locally

The sources are in manual/ (Hugo with the Docsy theme as a Hugo module). German texts are in manual/content/de/, English texts in manual/content/en/, images under manual/static/images/<language>/. You do not need to install anything on the host; all methods run in containers.

Preview in the dev stack

The development stack starts the service manual-dev (hugo server in the image hugomods/hugo:exts-0.154.5). You reach the preview via the Vite proxy:

http://localhost:3100/manual/

Live reload is disabled; reload the page after a change. If there are problems, docker logs opbweb-manual-dev helps. The dev stack is described in Operation and Updates .

Building the website as in the image

The frontend image builds the manual itself. To check it without building an image, you can run the same command in a container (example):

docker run --rm -v "$PWD/manual":/src -w /src hugomods/hugo:exts-0.154.5 \
  sh -c 'npm ci --no-audit --no-fund && hugo --minify --baseURL /manual/'

The result is in manual/public/. The directory is excluded from Git and from the Docker build.

Building the PDFs

manual/build-pdf.sh needs Hugo extended, Go, npm and Python with WeasyPrint. Run it in a container, as the CI does. The script reads the versions from backend/ and frontend/, so mount the whole project directory. Example for an x86-64 host, based on the CI job:

docker run --rm -v "$PWD":/work -w /work python:3 bash -c '
  pip install --quiet weasyprint &&
  apt-get update -qq && apt-get install -y -qq wget git golang nodejs npm > /dev/null &&
  wget -q https://github.com/gohugoio/hugo/releases/download/v0.154.5/hugo_extended_0.154.5_linux-amd64.deb &&
  dpkg -i hugo_extended_0.154.5_linux-amd64.deb > /dev/null &&
  manual/build-pdf.sh output'

The PDFs are then in output/. On an ARM machine, use the matching Hugo package (linux-arm64) or start the container with --platform linux/amd64. The files created in the container are owned by root.

For PDF printing, Hugo also generates Docsy’s print output; manual/scripts/combine_print_html.py combines it into one HTML file with a title page per part and language, which WeasyPrint converts into a PDF.

Hugo and Docsy versions

Docsy is pinned to v0.15.0 in manual/go.mod, matching Hugo 0.154.5, which the CI uses for the PDFs. Update Docsy only together with a matching Hugo version, and check the website and PDFs afterwards.