Docker Services Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• docker-compose.yml
• README.md
• agents.md
• nginx/default.conf
• builder/builder/main.py

The Docker Services Configuration defines a self-hosted stack that automates the creation and distribution of OPSI 4.3 software packages. The system consists of two primary services: repo-builder for package construction and repo-web for serving the repository over HTTP.

This configuration allows administrators to maintain a private repository of Windows applications without requiring internet access for clients. The stack operates on a periodic cycle to synchronize upstream releases with the local OPSI repository.

Sources: README.md:1-12, agents.md:11-16, docker-compose.yml:3-46

Architecture Overview

The project architecture separates the build logic from the web delivery layer. Both services run as unprivileged users with restricted capabilities to enhance security.

The diagram shows how the repo-builder manages the lifecycle of packages while repo-web provides read-only access to the final repository.
Sources: README.md:14-25, docker-compose.yml:23-26, docker-compose.yml:43-45

repo-builder Service

The repo-builder service is a Python application that uses official OPSI 4.3 package CLI tools. It executes a build cycle immediately upon startup and then repeats at a configurable interval.

Security and Runtime Configuration

The service implements several security measures to minimize the attack surface:

• Runs as a non-root user defined by BUILDER_UID and BUILDER_GID.
• Drops all capabilities and prevents new privileges.
• Mounts the root filesystem as read-only, using tmpfs for /tmp.
• Uses a file lock (state/builder.lock) to ensure only one writer process runs at a time.

Sources: docker-compose.yml:3-28, builder/builder/main.py:157-170, README.md:162-167

Environment Variables

Variable	Default	Description
UPDATE_INTERVAL_SECONDS	21600	Delay between cycles (minimum 60s).
KEEP_VERSIONS	2	Number of product versions to retain.
MAX_DOWNLOAD_BYTES	2147483648	Max size of one installer (2 GiB).
GITHUB_TOKEN	(empty)	Optional token for higher API rate limits.
ALLOW_CHANGED_CHECKSUM	false	Permits hash changes for known versions.

Sources: docker-compose.yml:14-20, README.md:92-105

repo-web Service

The repo-web service uses Nginx to serve the generated OPSI repository to clients. It is configured for high availability and strict read-only access.

Web Server Configuration

The Nginx configuration ensures the repository is served securely:

• Root Directory: /usr/share/nginx/html, mapped to the local ./repository volume.
• Access Control: Only GET and HEAD requests are permitted.
• Directory Listing: autoindex is enabled to allow clients to browse the repository.
• Healthchecks: Uses wget to verify service availability every 30 seconds.

Sources: nginx/default.conf:1-15, docker-compose.yml:42-53

The sequence diagram illustrates the atomic publishing process where the builder updates the repository, which is then served by Nginx to OPSI clients.
Sources: README.md:23-31, nginx/default.conf:8-13

Storage and Volume Mapping

The Docker stack requires specific local directories to maintain state and provide data persistence across restarts.

Container Path	Host Path	Description
/app/catalog	./catalog	Read-only. Contains packages.yaml and script overrides.
/data/repository	./repository	The served OPSI repository containing .opsi and metadata files.
/data/state	./state	Persistent state including packages.json and the builder lock.
/data/work	./work	Temporary workspace for downloads and archive extraction.

Sources: docker-compose.yml:23-26, agents.md:57-62, README.md:19-25

Lifecycle and Maintenance

The builder manages the repository lifecycle through specific phases:

1. Discovery: Resolves upstream versions via source adapters (GitHub, WinGet, Adoptium, etc.).
2. Download: Retrieves installers to the work/ directory and validates SHA256 hashes.
3. Packaging: Generates control.toml and OPSI scripts, then builds the .opsi archive.
4. Publication: Atomically renames the completed archive into the repository/ directory.
5. Retention: Deletes versions older than the KEEP_VERSIONS limit.

Sources: README.md:21-25, builder/builder/main.py:44-142, agents.md:15-16

Manual Execution

You can bypass the scheduled cycle by using docker compose run to perform specific tasks:

# Perform a single run for all products
docker compose run --rm repo-builder --once

# Force a rebuild of a specific product
docker compose run --rm repo-builder --once --product auto-firefox --force auto-firefox

# Perform a dry run to check for updates without downloading
docker compose run --rm repo-builder --dry-run

Sources: README.md:118-122, builder/builder/main.py:149-156

Conclusion

The Docker Services Configuration provides a robust, isolated environment for OPSI repository management. By utilizing read-only mounts, capability dropping, and atomic file operations, the stack ensures that package building does not interfere with the availability of the web service while maintaining strict security standards.