OPSI Server Integration Guide
Relevant source files
The following files were used as context for generating this wiki page:
The OPSI Server Integration Guide describes how to connect the auto-opsi-repo stack to an existing OPSI 4.3 infrastructure. This system functions as an automated private repository that discovers, downloads, and packages Windows software into .opsi archives without modifying the core OPSI server configuration.
The integration architecture uses a Docker-based builder to generate official OPSI archives and an Nginx-based web server to serve these archives over HTTP. Administrators integrate this repository by pointing their OPSI server to the repo-web service, allowing for automated depot imports and version tracking.
Sources: README.md:1-12, agents.md:9-14
System Architecture
The integration consists of two primary services and a persistent storage structure. The repo-builder handles the logic of package creation, while repo-web provides the delivery mechanism.
Component Breakdown
| Component | Technology | Role |
|---|---|---|
| repo-builder | Python / OPSI CLI | Discovers upstream releases and builds .opsi packages. |
| repo-web | Nginx | Serves the repository/ directory over HTTP (default port 8088). |
| Catalog | YAML | Defines product metadata, source URLs, and installer arguments. |
| State | JSON | Tracks checksums and package provenance to prevent duplicates. |
Sources: README.md:16-25, docker-compose.yml:3-55, agents.md:13-17
Data Flow Diagram
The following diagram illustrates the lifecycle of a package from discovery to availability for the OPSI server.
Package Generation and Validation
The repo-builder utilizes the official opsi-cli to ensure all generated archives are compatible with OPSI 4.3 standards.
Generation Logic
The builder performs the following steps for each enabled package in the catalog:
- Resolution: The builder identifies the latest version using source adapters (e.g.,
github_release,mozilla,winget_manifest). - Download: It retrieves the installer and validates the SHA256 checksum against upstream records.
- Templating: It generates
control.toml,setup.opsiscript, anduninstall.opsiscriptusing Jinja2 templates. - Packaging: It calls
opsi-cli package maketo create the.opsifile. - Validation: It performs a round-trip extraction to verify the archive integrity and metadata matches.
Sources: builder/builder/opsi.py:22-108, builder/builder/main.py:65-115
Provenance Tracking
Every package includes a provenance.json file inside the CLIENT_DATA directory and as a sidecar in the repository. This file contains metadata used to verify the installer's origin and integrity.
{
"product_id": "auto-firefox",
"vendor": "Mozilla Firefox",
"upstream_version": "143.0",
"sha256": "...",
"signature_status": "SIGNED",
"download_timestamp": "2023-..."
}
Sources: builder/builder/main.py:100-112, README.md:120-130
Repository Publication and Maintenance
Packages are published atomically to the repository/ directory. The repo-web service serves this directory as a read-only OPSI repository.
Nginx Configuration
The web server is configured to permit only GET and HEAD requests. It provides a directory listing (autoindex) to allow the OPSI server to discover new files.
server {
listen 80;
root /usr/share/nginx/html;
autoindex on;
location / {
limit_except GET HEAD { deny all; }
try_files $uri $uri/ =404;
}
}
Sources: nginx/default.conf:1-15, docker-compose.yml:43-55
Retention Policy
The builder maintains a configurable number of versions (default KEEP_VERSIONS=2). When a new version is successfully published, the builder identifies obsolete packages and unlinks them, along with their .md5, .zsync, and .provenance.json sidecars.
Sources: builder/builder/repository.py:25-50, README.md:200-205
Integration Procedures
To integrate the repository with an existing OPSI server, you must ensure network reachability between the OPSI container and the repo-web host IP.
Repository Setup
- Configure
.env: SetHTTP_PORT(default 8088) andBUILDER_UID/BUILDER_GIDto match the owner of the local repository directories. - Start Services: Run
docker compose up -d. - Verify Access: Ensure
http://<HOST-IP>:8088/is reachable from the OPSI server and displays a file listing. - Register Repository: On the OPSI server, add the repository as a new source for package imports.
Sources: README.md:46-65, docker-compose.yml:10-50
Manual Package Operations
You can trigger manual builds or repackaging for specific products to test integration:
- Manual Build:
docker compose run --rm repo-builder --once --product <opsi_product_id> - Offline Repackaging: If only the OPSI scripts changed but the installer is the same, use
python -m builder.repackage <opsi_product_id>to generate a new revision without re-downloading.
Sources: builder/builder/main.py:165-180, builder/builder/repackage.py:15-80
Summary
The OPSI Server Integration Guide provides a modular way to extend OPSI 4.3 with automated package management. By separating the builder (logic) from the web server (delivery), the system ensures that failed builds do not interrupt the availability of existing packages. The use of official OPSI tooling and atomic file operations ensures that the resulting repository is stable and compatible with standard OPSI depot management workflows.
Sources: README.md:16-35, agents.md:9-14