Directory and Workspace Layout
Relevant source files
The following files were used as context for generating this wiki page:
The auto-opsi-repo project organizes its workspace into distinct directories that separate static configuration, persistent state, active build data, and published repository files. This structure allows the repo-builder to process installers in isolation while the repo-web service provides read-only access to the final archives and metadata.
Sources: README.md:14-25, agents.md:46-53, docker-compose.yml:25-28
Core Directory Structure
The project uses five primary directories to manage the lifecycle of an OPSI package.
| Directory | Purpose | Persistency |
|---|---|---|
catalog/ | Contains product definitions and Jinja2 template overrides. | Static / Config |
builder/ | Python source code for the repo-builder application. | Static / Source |
repository/ | Published .opsi archives and repository metadata. | Persistent |
state/ | JSON state tracking, historical checksums, and file locks. | Persistent |
work/ | Temporary download and build workspace. | Ephemeral |
Sources: agents.md:46-53, docker-compose.yml:25-28
Persistent Storage and Volume Mounting
The system mounts three local directories into the Docker containers as volumes. The repo-builder requires write access to all three to update archives, track versions, and perform packaging. The repo-web service mounts the repository/ directory as read-only to serve files via Nginx.
This diagram shows the relationship between host directories and their mount points within the Docker services.
The Work Directory (Ephemeral)
The work/ directory acts as a scratchpad for the builder. During a cycle, the builder creates unique subdirectories for each product to prevent interference.
- Download Isolation: Installers download to a private subdirectory inside
work/. - Packaging Space: The OPSI CLI extracts and stages files here before creating the final
.opsiarchive. - Cleanup Policy: The builder removes product-specific subdirectories after a successful build or at the start of a new cycle if a previous run crashed.
Sources: builder/builder/main.py:126-128, builder/builder/main.py:166-174, agents.md:53
The State Directory (Persistent)
The state/ directory maintains the integrity of the repository across builder cycles. It stores metadata that is not part of the OPSI package itself.
packages.json: Tracks normalized OPSI versions, upstream versions, and successful download timestamps.builder.lock: A file used withflockto ensure only one builder instance writes to the repository at a time.last-run.json: Stores the summary of the most recent cycle, including lists of updated, failed, and disabled products.
Sources: builder/builder/main.py:34-36, builder/builder/main.py:141-142, builder/builder/main.py:159-160
The Repository Directory (Publication)
The repository/ directory is the final destination for all OPSI-compatible files. The builder uses atomic renames to move completed files into this directory.
Repository Content
For every published product version, the directory contains:
- The
.opsiarchive. - Sidecar files for OPSI compatibility:
.opsi.md5and.opsi.zsync. - Provenance data:
.opsi.provenance.jsoncontaining vendor source URLs and original installer hashes. - Metadata files:
packages.jsonandpackages.msgpack.zstdgenerated by the OPSI CLI.
Sources: README.md:20-25, builder/builder/opsi.py:108-111, builder/builder/repository.py:65-72
The sequence of directory interactions during a standard product update cycle.
Sources: builder/builder/main.py:106-140, builder/builder/repository.py:65-72
Catalog and Overrides
The catalog/ directory contains the logic governing what is built. It is mounted as read-only to the builder.
packages.yaml: The authoritative list of all supported applications and their source adapters.overrides/: Subdirectories named after anopsi_product_idcontaining custom Jinja2 templates (e.g.,setup.opsiscript.j2) or OPSI script snippets.
Sources: README.md:18-19, builder/builder/opsi.py:37-45, agents.md:46