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.

Getting Started

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

This chapter shows you how to sign in, how the oPBWeb interface is laid out and how to use the search to jump quickly to packages, files and commands. At the end you find a short overview of the roles and the package lifecycle.

Signing in

Open oPBWeb in your browser. Without a valid session, you land on the sign-in page.
Enter your User name and Password.
Click Sign in.

After signing in, the package list opens, or the page you originally wanted to open. On the sign-in page you can already switch the language (DE/EN) and light/dark mode in the top corner.

Requirements

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

Audience: Technical administration

Overview

This chapter lists everything that must be in place before the installation: a Docker host, free ports, a network connection to the opsi configserver and a technical opsi user. Check the items in order before you start the Installation .

Host

oPBWeb runs on any Linux host with Docker. You can run the stack directly on the opsi configserver or on a separate host that reaches the configserver via HTTPS.

Users and Roles

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

Role: Administrator

Overview

Under Users and roles, you manage all accounts that can sign in to oPBWeb. Each account has exactly one role, which defines what it may do in the UI. Besides local accounts that you create yourself, there are directory accounts from LDAP whose role is derived from their groups in the directory.

Open the area with the Users and roles icon at the bottom of the activity bar. It has two tabs: Users (with the number of accounts) and Audit log. The audit log is described in the Audit log chapter.

Audit Log

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

Role: Administrator

Overview

The audit log records who triggered which important action in oPBWeb and when: sign-ins and changes to accounts, packages, depots and settings. You find it under Users and roles on the Audit log tab. Only administrators can read it.

Entries can be neither changed nor deleted in the UI. Even if you delete a user account, its entries are kept with the user name.

Reading the audit log

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.

Installation

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

Audience: Technical administration

Overview

The installation takes only a few steps: get the sources, run ./setup-opbweb.sh (it writes the configuration file .env and generates the secrets), optionally add a TLS certificate, and start the stack. You either build the images locally with ./start.sh --build or pull prebuilt images from a registry. Then check that all services are running and continue with the Initial Setup in the interface.

Run all commands in the project directory on the Docker host. Check the Requirements first.

Packages

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

The Packages area is the start page of oPBWeb. Here you see all packages with their latest version, check in the package details on which depots they are installed, and create new packages. As a viewer you can see the list and the details; creating, importing and all changing actions require at least the Packager role.

The package list

Config Servers

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

Role: Administrator

Overview

oPBWeb works with any number of opsi config servers, for example a test, a staging and a production system. Through each config server, oPBWeb reads its depots, installs packages and accesses /repository, /workbench and /depot. Each depot belongs to exactly one config server.

You manage the config servers in the Depots view in the activity bar. As long as no config server is configured, depots, installing and the workbench do not work, and the status bar shows “No config server configured”.

Initial Setup

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

Role: Administrator

Overview

After the Installation , oPBWeb is reachable but does not know any opsi server yet and has only one account: the first administrator. During the initial setup you sign in with this account, change its password, connect oPBWeb to one or more opsi configservers, define the depot stages and set up the first users.

For this you need the admin password from secrets/admin_password.txt, the credentials of the technical opsi user and shell access to the configserver to verify the fingerprint of the CA certificate.

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.

Package Editor

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

In the package editor you edit a package version: the control data (product information, scripts, dependencies, properties), the changelog and the files of the package. This chapter describes the control tab. Working with files and scripts is described in Package Files and Script Editor .

You can only edit drafts, and only with at least the Packager role. As a viewer and for released versions, all fields are locked; you can still view everything.

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 .

Package Files

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

Role: Packager

Overview

Every package version consists of the three areas OPSI/, CLIENT_DATA/ and SERVER_DATA/. In the package editor you see them on the left under the Files tab. There you create files and folders, upload installers, rename, move and delete. The Structure tab next to it shows which scripts include which other scripts.

You can only change files in a version with the status Draft and with at least the Packager role. In released versions and with the Viewer role, the file tree is read-only: opening and downloading still work, all changing entries in the context menu are grayed out.

Settings for New Packages

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

Role: Administrator

Overview

Under Settings, you define the values new packages and meta packages start with, and which mail address changelog entries get when the user has no email. The values apply to all users. Only administrators may change them.

The defaults only take effect when a package is created. Existing packages and imported packages (.opsi or workbench) keep their own values, and every Packager can override the defaults in the package editor.

Test Environment

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

Audience: Technical administration, anyone who wants to try oPBWeb

Overview

The test environment starts oPBWeb together with two simulated opsi servers (opsiconfd mocks). With them you try the editor and the whole workflow, from the import from the workbench through building to promoting from Test to Production, without a real opsi server.

Config server in oPBWeb	Stage	Depots	Mock container
`opsi-test`	Test	`opsi-test.mock` (config server), `depot-test.mock`	`opbweb-opsi-mock-test`
`opsi-prod`	Production	`opsi-prod.mock` (config server), `depot-prod.mock`	`opbweb-opsi-mock-prod`

The mocks run with the oPBWeb backend image, their code comes from tools/opsi-mock/opsi_mock.py. Both are part of the repository clone and of the stack ZIP . The short version of this guide is next to them as START-TEST-ENVIRONMENT_en.md.

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.

Depot Management

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

Role: Administrator

Overview

oPBWeb reads the list of depots from the configured opsi config servers. Each depot belongs to exactly one config server. As an administrator, you define for each depot which Stage it runs in, which Service URL oPBWeb uses to reach it and whether it is used at all (Enabled). The stage determines which role may install on the depot.

You find these settings under Depots. The list on the left is grouped by config server: each config server is shown as a bold row, with its depots indented below it, each with a stage badge and the number of products; for the config server’s own depot, for example, “config server · 120 products”. Additions such as “disabled” or “no longer present” also appear in the second line. How to add and maintain config servers is described in Config servers .

Script Editor

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

Role: Packager

Overview

To open a text file of the package, click it in the file tree (see Package files ). It opens as a separate tab next to the control tab in the script editor. For opsi scripts, the editor offers completion, error checking, command help and snippets. All other text formats get syntax highlighting. You set the highlighting colors per file type under My account .

You can only edit files in a version with the status Draft and with at least the Packager role. Otherwise the editor is read-only; reading, searching, help and copying text still work.

Build and Deploy

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

Roles: Packager, Releaser

Overview

This chapter describes the path of a package version from draft to the depots: Build creates the .opsi file, Install … transfers it to one or more depots and releases the version in the process, Promote … takes a tested version unchanged to the depots of the next stage. You find all actions in the toolbar of the control tab in the package editor and in the ⋯ menu (More actions).

System Status

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

Role: Administrator

Overview

The System status area shows whether all oPBWeb services are running and gives administrators insight into how the database and object storage are used. Open it with the System status icon at the bottom of the activity bar.

All roles see the services table. Only administrators see the Database, Object storage (with Clean up …) and Bucket contents sections.

Checking services

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.

Snippets

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

Snippets are text blocks for opsi-script that you insert in the script editor by double-click, autocompletion or the context menu. The Snippets view in the activity bar is where you manage them: create categories, write and test snippets, import and export files.

Viewers see all snippets but cannot change anything. From the Packager role on, you create your own snippets and maintain the shared categories.

Depots

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

The Depots view shows all opsi config servers set up in oPBWeb and their depots as oPBWeb last read them. You see which products are installed in which version, clean up the repository, edit files directly on the server and compare the depots with each other.

Viewers see everything but cannot change anything. What Packagers and Releasers may change on a depot depends on its stage (see Stages and roles ). Only administrators can add, edit and remove config servers, see opsi server .

Jobs

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

Everything that takes longer or talks to an opsi server runs in oPBWeb as a background job. You start the action, keep working and follow the progress in the status bar, in the package editor or in the Jobs view.

All users see all jobs, including those of their colleagues, together with their logs. This lets you trace who built or deployed what and when.

Account and Language

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

Roles: Viewer, Packager, Releaser, Administrator

Overview

You reach the settings of your own account via the avatar icon with your initials at the far right of the top bar. Next to it in the top bar you find the switches for language and light/dark appearance, as well as access to this manual.

These functions are available to all users, regardless of their role.

Click the avatar icon to open the user menu.

oPBWeb Manual

Architecture

Overview

Services

Getting Started

Overview

Signing in

Requirements

Overview

Host

Users and Roles

Overview

Audit Log

Overview

Reading the audit log

Configuration

Overview

Installation

Overview

Packages

Overview

The package list

Config Servers

Overview

Initial Setup

Overview

LDAP Sign-in

Overview

How sign-in works

Package Editor

Overview

Operation and Updates

Overview

Starting and stopping the stack

start.sh

Package Files

Overview

Settings for New Packages

Overview

Test Environment

Overview

Backup and Restore

Overview

Depot Management

Overview

Script Editor

Overview

Build and Deploy

Overview

System Status

Overview

Checking services

Troubleshooting

Overview

First places to look

Stack does not start

Sign-in

Build and Delivery

Overview

Images

Snippets

Overview

Depots

Overview

Jobs

Overview

Account and Language

Overview

The user menu