Getting Started

Relevant source files

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

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

The auto-opsi-repo project provides an automated Docker-based stack that manages a private OPSI 4.3 software repository. It discovers upstream Windows software releases, downloads official installers, packages them into .opsi archives, and serves them via HTTP for use with existing OPSI servers.

Sources: README.md:1-10, agents.md:7-11

System Architecture

The project consists of two primary services running in a Docker Compose environment. The system automates the lifecycle of OPSI packages without modifying the configuration of your main OPSI server.

Sources: README.md:12-25, docker-compose.yml:2-55

Core Components

Component	Technology	Function
repo-builder	Python / OPSI CLI	Discovers releases, downloads installers, builds packages, and manages metadata.
repo-web	Nginx	Serves the repository via HTTP as a read-only mount.
Catalog	YAML	Defines product metadata, source URLs, and installation arguments.
Storage	Local Bind Mounts	Persists repository data, state, and temporary work files.

Sources: README.md:13-25, agents.md:12-16, docker-compose.yml:2-55

The following diagram illustrates the data flow from upstream discovery to client availability:

The diagram shows the transition of software from external vendors through the automated build process to the local web server.
Sources: README.md:13-25, docker-compose.yml:1-55

Installation and Setup

Prerequisites

• A Linux host with Docker Engine and Docker Compose.
• Outbound HTTPS access to official software vendor hosts.
• 15–25 GB of disk space for initial catalog and retention versions.

Sources: README.md:38-42

Deployment Steps

1. Clone the repository and enter the directory.
2. Copy the example environment file: cp -n .env.example .env.
3. Create the necessary persistent directories: mkdir -p repository state work.
4. Identify your current user and group IDs using id -u and id -g.
5. Update BUILDER_UID and BUILDER_GID in the .env file to match these IDs.
6. Launch the stack: docker compose up -d --build.

Sources: README.md:44-55, agents.md:65-70

Configuration

The system uses environment variables in the .env file to control builder behavior and network settings.

Variable	Default	Description
UPDATE_INTERVAL_SECONDS	21600	The delay between build cycles (default 6 hours).
KEEP_VERSIONS	2	Number of previous product versions to retain.
HTTP_PORT	8088	The host port for the web repository.
GITHUB_TOKEN	(None)	Optional token to increase GitHub API rate limits.
LOG_LEVEL	INFO	Logging verbosity (DEBUG, INFO, WARNING, ERROR).

Sources: README.md:65-77, docker-compose.yml:14-20

Security Constraints

• Unprivileged Execution: The builder service drops all capabilities and runs with a non-root user ID.
• Read-Only Access: The web server mounts the repository directory as read-only and denies all non-GET/HEAD requests.
• TLS Verification: Verification is mandatory; the builder does not support an insecure bypass.

Sources: README.md:82-90, docker-compose.yml:10-12, nginx/default.conf:10-13

Operational Management

Manual Build Commands

The builder service supports manual triggers for specific products or diagnostic runs.

# Perform a dry run (checks versions without downloading)
docker compose run --rm repo-builder --dry-run

# Run a single cycle for all packages and exit
docker compose run --rm repo-builder --once

# Build one specific product immediately
docker compose run --rm repo-builder --once --product auto-firefox

Sources: README.md:95-99, agents.md:73-75

Build Logic Flow

The builder follows a strict sequence to ensure package integrity:

The sequence diagram details the decision-making process for updating a package.
Sources: builder/builder/main.py:32-150, builder/builder/opsi.py:16-90

Package Management

Software products are defined in catalog/packages.yaml. Each entry specifies the source adapter, installer arguments, and detection methods.

Key Catalog Attributes

• opsi_product_id: Unique lowercase ID (max 32 chars).
• source: Configuration for github_release, mozilla, winget_manifest, or direct_url.
• installer: Specifies the installer type (exe, msi, zip) and silent arguments.
• detection: Methods to verify installation (usually registry or file_version).

Sources: README.md:120-140, catalog/packages.yaml:1-20

Summary: This "Getting Started" guide establishes the foundation for deploying and configuring the auto-opsi-repo stack. By following the environment setup and using the documented CLI commands, administrators can automate software packaging for their OPSI infrastructure.