Technical Administration on oPBWeb Manual

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Audience: Technical administration

Overview

oPBWeb runs as a single Docker Compose project named opbweb. The file docker-compose.yml describes production operation; docker-compose.dev.yml extends it for development. This chapter shows which services exist, how they are connected and where each kind of data is stored.

Services

Service	Container	Image	Purpose
frontend	`opbweb-frontend`	`opbweb-frontend:latest` (nginx:stable-alpine)	serves the web interface and the manual, forwards `/api` to the API; the only service with published ports
api	`opbweb-api`	`opbweb-backend:latest` (python:3.13-slim)	REST API and WebSocket (FastAPI/uvicorn on port 8000), sign-in, database migrations at startup, first administrator account
worker	`opbweb-worker`	`opbweb-backend:latest`	runs all jobs (arq on Redis); the only service that talks to the opsi config servers and decrypts their passwords
db	`opbweb-db`	`mariadb:11.4`	all application data (packages, versions, users, jobs, audit log, settings)
redis	`opbweb-redis`	`redis:7-alpine`	job queue, worker heartbeat, opsi connection status, revocation list of signed-out tokens, depot locks
garage	`opbweb-garage`	`dxflrs/garage:v2.2.0`	S3-compatible object storage (single node, replication factor 1) for file contents and built packages
garage-init	`opbweb-garage-init`	`opbweb-garage-init:1.0.0` (alpine:3.21)	sets up the layout, the access key `opbweb` and the bucket `packages` on every start, then exits

API and worker use the same image; the worker just starts with a different command (./start-worker.sh). The garage-init image carries the :dev tag in production as well.

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Audience: Technical administration

Overview

oPBWeb splits its configuration into three levels:

.env in the project directory: non-secret settings such as ports, LDAP server, time limits. Docker Compose reads the file and inserts the values into docker-compose.yml.
secrets/: all passwords and keys as individual files. They reach the containers as Docker secrets and are never stored in .env.
User interface: the connections to the opsi config servers (URL, technical user, password, stage, CA certificate; in the Depots view) and the defaults for new packages. These settings are stored in the database, see Config servers and Settings for new packages .

./setup-opbweb.sh creates .env and the missing secrets, see Installation . Afterwards you can edit .env directly or run the script again; the existing values are then the defaults. Changes to .env take effect with the next ./start.sh; Docker Compose then recreates the affected containers.

LDAP Sign-in

Mon, 01 Jan 0001 00:00:00 +0000

Audience: Technical administration

Overview

In addition to local accounts, oPBWeb can sign users in against an LDAP directory or Active Directory. The role in oPBWeb is then derived from the group memberships in the directory. You configure the connection with LDAP_* variables in .env and the password of the service account in secrets/ldap_bind_password.txt. There are no settings for this in the user interface.

If oPBWeb has a local account with the entered user name, oPBWeb signs in locally only. The directory is not queried, even if the password is wrong.
Otherwise, with LDAP_ENABLED=true, oPBWeb connects with the service account (LDAP_BIND_DN), or anonymously if no bind DN is set.
oPBWeb searches with LDAP_USER_FILTER below LDAP_USER_SEARCH_BASE (empty: LDAP_BASE_DN). The search must return exactly one entry.
oPBWeb binds as the user with the DN it found and the entered password, which verifies the password.
oPBWeb determines the role from the memberOf attribute (see below). Without a matching group, there is no access.
On the first successful sign-in, oPBWeb creates the account with the source Directory (LDAP). Display name (displayName), email (mail) and role are taken from the directory again on every sign-in.

Local accounts therefore always stay local, including the first administrator account. This way you can still get into oPBWeb if the directory is down.

Operation and Updates

Mon, 01 Jan 0001 00:00:00 +0000

Audience: Technical administration

Overview

For day-to-day operation you need two scripts in the project directory: start.sh and stop.sh. This chapter also describes where to find logs and service status, how to update oPBWeb and what to keep in mind on the opsi side. Run all commands in the project directory.

Starting and stopping the stack

start.sh

./start.sh [--build] [--logs] [--dev | --test] [--lang de|en]

Option	Effect
(none)	starts the production stack (`docker-compose.yml`) with the existing images
`--build`	rebuilds your own images before starting
`--logs`	follows the logs of all containers after starting (`logs -f --tail=50`); Ctrl+C only ends the output
`--dev`	adds `docker-compose.dev.yml` (development stack, see below); only in a clone with the sources
`--test`	adds `docker-compose.test.yml`: two opsi mocks as config servers Test and Production, see Test Environment
`--lang de` or `--lang en`	language of the messages for this run (otherwise `OPBWEB_LANG` from `.env`)
`-h`, `--help`	shows the help

Sequence: the script aborts if .env is missing („.env fehlt – bitte ./setup-opbweb.sh ausführen (im Entwickler-Checkout: ./setup-opbweb.sh –dev).“ – .env is missing, please run ./setup-opbweb.sh, in a developer checkout ./setup-opbweb.sh –dev), calls scripts/init-secrets.sh, runs docker compose up -d and shows the status with docker compose ps. Running containers whose configuration has not changed are left untouched. start.sh does not pull new third-party images; for that, see Updating .

Backup and Restore

Mon, 01 Jan 0001 00:00:00 +0000

Audience: Technical administration

Overview

oPBWeb’s data lives in two places that belong together: the database holds all metadata, the object storage holds the file contents. The database refers to objects in the storage via SHA-256 checksums and keys (blobs/…, artifacts/…). A backup is only usable if both parts come from the same point in time and the matching secrets are included.

Note

The commands in this chapter are examples. Backing up the database with mariadb-dump and backing up the Garage volumes while the stack is stopped is the intended approach; the specific commands for volumes and restore are derived from it. Adapt paths and names to your environment and test the restore before you rely on it.

Troubleshooting

Mon, 01 Jan 0001 00:00:00 +0000

Audience: Technical administration

Overview

This chapter sorts typical problems by symptom. For each symptom you find the likely cause and the fix. At the end there is a table of important error messages. Messages of the server follow the interface language; this chapter quotes them as shown in the English interface. Messages of the shell scripts and container logs are German and are quoted with an English translation.

First places to look

Source	Content
System status page	status of database, Redis, object storage, worker and opsi server, see System status
Jobs page	complete log of every job with error message, see Jobs
`docker compose ps -a`	which containers are running and which have exited (with exit code)
`docker logs opbweb-api`	startup, migrations, sign-in, LDAP
`docker logs opbweb-worker`	jobs, opsi connection
`docker logs opbweb-garage-init`	object storage setup
Status bar of the user interface	“Backend not connected” if the API does not respond; orange notice for problems with the opsi server

Stack does not start

Symptom	Cause	Fix
`start.sh` reports „.env fehlt – bitte ./setup-opbweb.sh ausführen (im Entwickler-Checkout: ./setup-opbweb.sh –dev).“ (.env is missing, run the setup script)	no `.env`	`./setup-opbweb.sh` (or `cp .env.example .env`)
API does not start, log: “Secret file not found: …”	secret file missing, for example because the stack was started with `docker compose` instead of `./start.sh`	use `./start.sh` or run `./scripts/init-secrets.sh`
API exits after about 60 seconds, log: “Database not reachable: …”	MariaDB not ready, or the password does not match the volume	check `docker logs opbweb-db`; if `db_password.txt` was changed, see Configuration
api, worker and frontend do not start, garage-init has a non-zero exit code	object storage setup failed	`docker logs opbweb-garage-init`; “ERROR: No admin token found” means `secrets/garage_admin_token.txt` is missing
garage-init keeps reporting “Not ready yet, retrying in 2s…”	Garage does not start or the admin token does not match	`docker logs opbweb-garage`; do not change the token in `secrets/` afterwards
API log: “No users and no ADMIN_PASSWORD configured - no initial admin created”	`secrets/admin_password.txt` is empty or missing while the user table is empty	fill the file or let `init-secrets.sh` create it, restart the stack

Sign-in

“Wrong user name or password.” For local accounts, every failed attempt counts. After 5 failed attempts from the same address the account is locked for that address for 15 minutes: “Account locked until HH:MM.” The user can still sign in from other addresses; the account is locked for everyone only after 50 failed attempts. After 20 failed attempts from one address (across all accounts) oPBWeb answers “Too many failed sign-ins from this address.” An administrator removes the lock under Users and roles with Unlock; Set password also unlocks the account. See Users and roles .

Build and Delivery

Mon, 01 Jan 0001 00:00:00 +0000

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.

Technical Administration on oPBWeb Manual

Architecture

Overview

Services

Configuration

Overview

LDAP Sign-in

Overview

How sign-in works

Operation and Updates

Overview

Starting and stopping the stack

start.sh

Backup and Restore

Overview

Troubleshooting

Overview

First places to look

Stack does not start

Sign-in

Build and Delivery

Overview

Images