Introduction
Relevant source files
The following files were used as context for generating this wiki page:
The auto-opsi-repo project provides an automated, self-hosted Docker stack for managing a private OPSI 4.3 software repository. It discovers upstream Windows software releases, downloads official installers, packages them into .opsi archives, and serves them over HTTP. This system allows OPSI clients to install vendor software without requiring WinGet or direct internet access on the client side.
The architecture runs alongside an existing OPSI server without modifying the server's configuration or scheduling deployments automatically. It functions through a cyclic builder process that monitors a central package catalog, handles version tracking via persistent state, and performs atomic updates to the repository metadata.
Sources: README.md:1-12, agents.md:6-10
System Architecture
The project consists of two primary Docker services: a Python-based builder and an Nginx-based web server.
- repo-builder: A Python application utilizing official OPSI 4.3 CLI tools. It runs on a configurable six-hour interval to check for updates, download installers to a private
work/directory, and generate packages. - repo-web: An Nginx server that provides a read-only mount of the repository. It serves
.opsifiles and generated metadata via HTTP (default port 8088).
The following diagram illustrates the high-level data flow and component interaction:
Core Components
Package Catalog
The catalog/packages.yaml file defines all products. Each entry specifies source settings, installer arguments, detection methods, and uninstallation configurations. No application logic is embedded in the Python source; the builder consumes this YAML to determine its actions.
Sources: catalog/packages.yaml:1-50, README.md:19-21
Repository Builder (repo-builder)
The builder manages the lifecycle of a package. It performs version resolution, verifies checksums, generates OPSI control files, and invokes the OPSI CLI for packaging.
| Feature | Description |
|---|---|
| Cycle Interval | Default 21,600 seconds (6 hours). |
| Atomic Updates | Files are renamed into the repository atomically to prevent partial reads. |
| Locking | Uses builder.lock to ensure only one writer process runs at a time. |
| Retention | Maintains a configurable number of older versions (default 2). |
Sources: builder/builder/main.py:21-45, README.md:38-50, docker-compose.yml:21-22
Source Adapters
The system uses specialized adapters in builder/builder/sources/adapters.py to interact with various upstream metadata protocols. Supported types include github_release, direct_url, mozilla, microsoft, adoptium, and winget_manifest.
Data Flow and Packaging Logic
The builder follows a strict sequence to ensure repository integrity:
- Resolution: The builder resolves the latest version using the configured adapter.
- Comparison: It compares the upstream version against the local
state/packages.jsonand existing files inrepository/. - Download: If a new version is found, it downloads the installer to the
work/directory. - Validation: It validates the installer using SHA256 checksums and file magic (EXE/MSI).
- Generation: It renders OPSI scripts (setup/uninstall) using Jinja2 templates.
- Packaging: It calls
opsi-cli package maketo create the.opsiarchive. - Publication: It moves the new archive and its sidecars (.md5, .zsync, .provenance.json) into the repository and regenerates the repository metadata.
Sources: builder/builder/main.py:53-150, builder/builder/opsi.py:18-80, README.md:23-35
Configuration and Environment
The system is configured via environment variables, typically stored in a .env file.
| Variable | Default | Function |
|---|---|---|
UPDATE_INTERVAL_SECONDS | 21600 | Delay between build cycles. |
KEEP_VERSIONS | 2 | Number of versions to retain per product. |
HTTP_PORT | 8088 | The host port for the web server. |
BUILDER_UID/GID | 1000 | User ID/Group ID for file ownership in volumes. |
ALLOW_CHANGED_CHECKSUM | false | Permits hash changes for an existing version. |
Sources: README.md:65-76, docker-compose.yml:21-27
Summary
The auto-opsi-repo project automates the complex task of maintaining a local software mirror for OPSI. By decoupling package definitions into a catalog and using a robust Python builder, it ensures that Windows installers are consistently packaged, verified, and served. The use of atomic operations and persistent state management provides a reliable foundation for enterprise software distribution.
Sources: README.md:1-12, agents.md:6-10