Troubleshooting Guide

Relevant source files

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

• README.md
• builder/builder/main.py
• builder/builder/download.py
• builder/builder/sources/adapters.py
• builder/builder/opsi.py
• builder/builder/repository.py
• agents.md

This guide provides technical instructions for diagnosing and resolving failures within the auto-opsi-repo system. The system consists of the repo-builder Python application and the repo-web nginx service. Troubleshooting covers infrastructure issues, source resolution errors, and package integrity failures.

System Execution Flow

The repo-builder operates in a cycle. It processes the catalog, downloads installers, and packages them using OPSI tooling. If a single product fails, the builder continues to the next product in the catalog.

Common Runtime Errors

Process Locks and Permissions

The builder uses a file-based lock to prevent concurrent modifications to the repository and state.

• Builder already active: If you see "Another builder is active", a scheduled or manual build is already holding the lock at state/builder.lock. You must wait for it to complete or stop the repo-builder service before running manual commands.
• Permission denied: This occurs when the BUILDER_UID and BUILDER_GID in the .env file do not match the owners of the bind-mounted directories (repository/, state/, work/). Match these IDs to your host user to ensure the container can write data.

Sources: builder/builder/main.py:183-190, README.md:225-231

Infrastructure and Networking

• Port already allocated: The host port (default 8088) is in use by another service. Change HTTP_PORT in the .env file and update your OPSI depot configurations to match.
• OPSI sees no packages: Verify the container reachability via IP and port. Check if nginx is serving the directory by running curl -f http://HOST-IP:PORT/.

Sources: README.md:222-224, README.md:238-241

Source and Download Failures

Upstream Rate Limiting

The system monitors rate limits for external APIs, particularly GitHub.

Error Case	Behavior	Resolution
GitHub 403/429	The builder caches the X-RateLimit-Reset time and skips the host for that cycle.	Configure a read-only GITHUB_TOKEN in .env to increase limits.
Untrusted Host	The builder rejects URLs that are not in the package's allowed_hosts list.	Verify the new URL via official vendor docs and update the catalog allowlist.

Sources: builder/builder/download.py:65-98, builder/builder/sources/adapters.py:70-75, README.md:232-237

Version and Checksum Conflicts

The system enforces strict immutability for known versions to prevent supply chain attacks or accidental corruption.

• Checksum changed/mismatch: If a vendor replaces an installer at a previously seen URL, the builder will fail with an "IMMUTABLE VERSION CHECKSUM CHANGED" error.
• Resolution:
  1. Investigate if the change is legitimate.
  2. If legitimate, increment the package_revision in the catalog.
  3. If you must accept the change for the same version, use ALLOW_CHANGED_CHECKSUM=true as a one-off environment variable.

Sources: builder/builder/download.py:121-127, builder/builder/main.py:91-105, README.md:238-240

Package Building and Metadata

OPSI Tooling Failures

Packaging requires the opsi-cli to succeed within the builder container.

• Package created but metadata failed: If repository: ... shows a failure in the log summary, the .opsi files were created, but the global repository metadata (packages.json) was not updated. The system will attempt to regenerate metadata in the next successful cycle before performing retention.
• Ambiguous assets: Occurs when a GitHub asset_regex matches multiple files in one release. You must refine the regex in catalog/packages.yaml.

Sources: builder/builder/main.py:150-155, builder/builder/sources/adapters.py:32-35, README.md:241-242

Recovery Procedures

Repackaging Existing Installers

If packaging logic changes but the upstream installer is still valid, you can use the repackage tool to avoid re-downloading.

1. Stop the repo-builder container.
2. Run the manual repackage command:

   docker compose run --rm --entrypoint python repo-builder -m builder.repackage <opsi-product-id>
   

3. Restart the repo-builder.

Sources: README.md:200-205

Cleaning Temporary Data

The builder automatically cleans the work/ directory at the start of each cycle. If the builder crashes, you may manually delete subdirectories in work/ starting with auto- or metadata- while the builder is stopped.

Sources: builder/builder/main.py:192-200

This guide ensures that administrators can maintain repository integrity and resolve connectivity or configuration issues effectively. Success is measured by the absence of "Failed" items in the state/last-run.json summary.