Backup, Restore, and Updates
Relevant source files
The following files were used as context for generating this wiki page:
The backup, restore, and update processes for the auto-opsi-repo project ensure data persistence, integrity, and system longevity. These operations manage the state of the OPSI repository, historical checksums, and Docker stack configurations.
The system relies on a central builder (repo-builder) that manages a persistent state file and a directory-based repository. Accurate backups of these components prevent the loss of historical installer evidence and permit recovery from repository corruption or host failures.
Backup Procedures
Backup operations must capture four critical directories and configuration files to ensure a complete recovery point. You should perform backups while the repo-builder service is stopped or by using a consistent filesystem snapshot.
Required Backup Targets
| Path | Purpose | Significance |
|---|---|---|
catalog/ | Product definitions and overrides | Contains all custom Jinja templates and package logic. |
repository/ | OPSI archives and metadata | Stores .opsi files, sidecars, and provenance data. |
state/ | Persistent state and checksums | Stores packages.json and the global builder lock. |
.env | Environment configuration | Stores credentials, UIDs, and operational variables. |
Sources: README.md:468-472, builder/builder/main.py:27-33
Consistency and Integrity
The system uses a lock file (state/builder.lock) to prevent concurrent write operations. During a backup, you must preserve file ownership (UID/GID) to match the BUILDER_UID and BUILDER_GID settings in .env.
The diagram shows the recommended sequence to ensure a consistent state during data archival.
Sources: README.md:470-473, builder/builder/main.py:157-164
Recovery and Restore
Restoring the repository requires re-establishing the directory structure and verifying the integrity of the state against the existing physical archives.
Restoration Steps
- Restore the
catalog/,repository/,state/, and.envdirectories to the target host. - Match the local UID/GID to the values defined in the
.envfile. - Perform a dry run using
docker compose run --rm repo-builder --dry-runto verify the state. - Restart the periodic builder.
Sources: README.md:475-477, agents.md:65-70
Provenance Recovery
If the state/packages.json file is lost but the repository/ remains intact, the builder can reconstruct historical checksum evidence using .opsi.provenance.json sidecar files. The builder scans the repository for these files on startup to populate its internal checksum database.
This sequence illustrates how the builder automatically recovers immutable version evidence from repository sidecars when the primary state file is missing.
Sources: builder/builder/main.py:40-49, README.md:477-479
Software and Stack Updates
Updating the auto-opsi-repo involves pulling new container images and applying changes to the catalog or environment configuration.
Update Workflow
- Back up current configuration and state.
- Stop the current
repo-builderservice. - Pull the latest images using
docker compose build --pull repo-builderanddocker compose pull repo-web. - Review any changes in
catalog/packages.yaml. - Execute a dry run to validate the update.
- Bring the stack up with
docker compose up -d.
Sources: README.md:483-492
Version and Revision Management
When changing packaging logic without an upstream update, you must increment the package_revision in the catalog. This ensures the builder generates a new OPSI archive version (e.g., auto-firefox_143.0-1.opsi to auto-firefox_143.0-2.opsi).
| Component | Change Scenario | Action |
|---|---|---|
| Upstream Version | New vendor release detected | Automatic; revision resets to 1. |
| Package Revision | Deployment script change | Manual; increment package_revision in catalog. |
| Stack Images | Project code/nginx update | Manual; pull/build Docker images. |
Sources: README.md:275-285, builder/builder/main.py:80-85
Checksum Integrity and Force Rebuilds
The builder enforces checksum immutability. If an installer's SHA256 changes for an existing version, the builder fails the update to prevent potential compromise.
Handling Checksum Mismatches
If an installer genuinely changed upstream and you have verified the change:
- Preserve the old artifact and state.
- Increment the
package_revision. - Set the environment variable
ALLOW_CHANGED_CHECKSUM=truefor a one-off run to accept the new hash.
Sources: README.md:298-310, builder/builder/download.py:108-112
Rebuilding Packages
You can force a rebuild of existing archives using the --force or --force-all flags. This re-downloads the installer and re-packages the OPSI archive even if it already exists in the repository. Note that --force does not bypass the immutable checksum guard unless ALLOW_CHANGED_CHECKSUM is also enabled.
# Force rebuild a specific product
docker compose run --rm repo-builder --once --product auto-firefox --force auto-firefox
# Force rebuild all enabled products
docker compose run --rm repo-builder --once --force-all
Sources: README.md:300-305, builder/builder/main.py:99-105
Summary
Backup, restore, and update operations prioritize the preservation of the OPSI repository's integrity. By backing up the catalog, repository, and state directories together, administrators ensure that the builder's historical checksum evidence remains intact. The system provides built-in recovery mechanisms through provenance sidecars and strict versioning via package revisions to handle both software updates and infrastructure recovery.