Environment Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Environment Configuration manages the operational parameters of the auto-opsi-repo Docker stack. This system defines how the builder interacts with upstream sources, manages local storage, and serves the OPSI repository over HTTP. The configuration relies on environment variables, typically defined in a .env file, and structured YAML definitions in the product catalog.
Sources: README.md:88-105, agents.md:52-56, docker-compose.yml:14-25
Core Service Configuration
The system uses docker-compose.yml to orchestrate two primary services: repo-builder and repo-web. You define the behavior of these services through environment variables passed into the Docker containers.
Service Architecture and Data Flow
The following diagram illustrates how environment variables and volume mounts configure the relationship between the host and the Docker services.
This diagram shows the flow of configuration data from the host into the Docker services and the shared volumes used for persistence.
Sources: docker-compose.yml:2-55, README.md:65-79
Standard Environment Variables
The table below lists the primary variables used to configure the builder and web server behavior.
| Variable | Default | Description |
|---|---|---|
UPDATE_INTERVAL_SECONDS | 21600 | Delay between repository update cycles (minimum 60s). |
KEEP_VERSIONS | 2 | Number of product versions to retain in the repository. |
GITHUB_TOKEN | (empty) | Read-only token to avoid GitHub API rate limits. |
ALLOW_CHANGED_CHECKSUM | false | Permits updating a version if the upstream hash changes. |
MAX_DOWNLOAD_BYTES | 2147483648 | Size limit for a single installer download (2 GiB). |
HTTP_PORT | 8088 | Host port for the Nginx repository server. |
HTTP_BIND_ADDRESS | 0.0.0.0 | IP address for the web server to bind to. |
LOG_LEVEL | INFO | Logging verbosity (DEBUG, INFO, WARNING, ERROR). |
BUILDER_UID/BUILDER_GID | 1000 | User/Group ID that owns the mounted directories. |
Sources: README.md:88-105, docker-compose.yml:14-25
Storage and Volume Mapping
The configuration requires four main directories on the host to be mounted into the containers. You must ensure these directories exist and have correct ownership matching the BUILDER_UID and BUILDER_GID.
catalog/: Containspackages.yamland optional script overrides. Mounted read-only.repository/: Stores the final.opsipackages and repository metadata.state/: Holdspackages.json(version tracking) andbuilder.lock.work/: Acts as a temporary workspace for downloads and packaging.
Sources: docker-compose.yml:26-30, agents.md:58-64, builder/builder/main.py:192-195
User and Group Permissions
The builder runs as a non-privileged user. To prevent permission errors, you must set the ownership of host directories to match the environment variables:
# Get current user IDs
id -u # Set as BUILDER_UID
id -g # Set as BUILDER_GID
# Apply ownership
chown -R 1000:1000 repository state work
Sources: README.md:73-77, docker-compose.yml:10
Security Configuration
The stack implements several security layers through Docker and environment settings.
TLS and CA Certificates
The system enables TLS verification by default. If you use a private CA, you must mount the PEM bundle and set the REQUESTS_CA_BUNDLE variable.
services:
repo-builder:
environment:
REQUESTS_CA_BUNDLE: /certs/ca-bundle.pem
volumes:
- ./certs/ca-bundle.pem:/certs/ca-bundle.pem:ro
Sources: README.md:112-120
Container Hardening
The docker-compose.yml file applies the following security constraints to both services:
read_only: true: The container root filesystem is immutable.cap_drop: [ALL]: All Linux capabilities are dropped.no-new-privileges:true: Prevents processes from gaining new privileges viasetuidorsetgidbinaries.
Sources: docker-compose.yml:11-13, docker-compose.yml:42-45
Catalog Configuration
While environment variables control the system, catalog/packages.yaml controls individual product behavior. This file defines the source types, installer arguments, and detection methods.
Product Definition Structure
Each package in the catalog follows a structured schema that determines its environment requirements:
id: firefox
opsi_product_id: auto-firefox
enabled: true
source:
type: mozilla
allowed_hosts:
- product-details.mozilla.org
- archive.mozilla.org
installer:
type: exe
silent_args: [-ms]
detection:
method: registry
display_name_regex: ^Mozilla Firefox
Sources: catalog/packages.yaml:2-25, builder/builder/opsi.py:73-82
Host Validation
To protect against unauthorized redirects, the configuration requires an allowed_hosts list for each package. The builder validates every URL against this list unless disable_host_validation: true is explicitly set for a package.
Sources: README.md:154-159, builder/builder/opsi.py:100-101
Execution Environment
The repo-builder service uses a file lock at state/builder.lock to ensure only one instance of the builder logic runs at a time.
Execution Cycle Sequence
This diagram demonstrates the locking mechanism that prevents concurrent repository modifications.
Sources: builder/builder/main.py:209-216
Summary
Environment configuration in auto-opsi-repo is a hybrid of global system settings defined via Docker environment variables and per-product operational parameters defined in the YAML catalog. This structure allows administrators to control system-wide resource usage (disk, network, interval) while maintaining granular control over how specific Windows applications are sourced and packaged.