Adding a Package

Relevant source files

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

• README.md
• catalog/packages.yaml
• agents.md
• builder/builder/main.py
• builder/builder/sources/adapters.py
• builder/builder/opsi.py
• builder/builder/download.py

Adding a package involves defining a new software product in the central catalog, allowing the system to discover, download, and bundle it into an OPSI archive. The process uses the catalog/packages.yaml file to map upstream release metadata to OPSI-compatible installer logic.

The system uses these definitions to automate the lifecycle of a software package, from detecting new versions on vendor sites to generating the .opsi files served by the repo-web service.

Sources: README.md:129-144, agents.md:43-48

Package Definition Workflow

The following diagram illustrates the sequence of actions the repo-builder performs when a new package is identified in the catalog.

The workflow ensures that only validated, allowlisted installers are packaged for distribution.
Sources: builder/builder/main.py:46-125, builder/builder/opsi.py:73-81

Catalog Configuration

All package definitions reside in catalog/packages.yaml. Each entry must include metadata, source resolution settings, and installation/uninstallation logic.

Required Core Fields

Field	Description	Constraints
id	Internal catalog identifier	Unique string
opsi_product_id	The product ID used by OPSI	Unique, lowercase, max 32 chars
name	Human-readable application name	Descriptive string
enabled	Toggles processing of the package	Boolean (true/false)
package_revision	Internal OPSI package version	Positive integer
architecture	Target CPU architecture	[x64] supported
redistribution	Licensing classification	allowed, internal_only, or unknown

Sources: README.md:129-158, catalog/packages.yaml:1-20

Source Adapter Types

The source block defines how to find the installer. Different type values require different configuration fields.

Type	Description	Key Parameters
github_release	Fetches from GitHub API	repo, asset_regex, release_type
direct_url	Parses a vendor version feed	version_url, version_regex, download_url_template
winget_manifest	Uses Microsoft WinGet manifests	package_identifier, installer_types
mozilla	Specific to Firefox/Thunderbird	product, channel, version_url
adoptium	Fetches Temurin JDKs	java_version, api_url

Sources: README.md:173-195, builder/builder/sources/adapters.py:64-162

Security and Validation

Every added package must satisfy strict security requirements. The builder enforces hostname pinning and integrity checks before packaging.

1. Allowed Hosts: You must list every domain the installer might be downloaded from or redirected to in allowed_hosts.
2. Checksums: The system compares the downloaded file against a SHA256 hash provided by the source. If ALLOW_CHANGED_CHECKSUM is false, the build fails if a known version's hash changes.
3. Path Traversal: ZIP installers are extracted using safety checks to prevent directory traversal or unsafe symlinks.

Detection and Installation Logic

You must specify how the OPSI client detects if the software is already installed.

• Registry Detection: Uses display_name_regex to match the Windows Uninstall registry.
• MSI Detection: Uses the product_code.
• Custom Detection: Executes a specific OPSI script provided in the overrides/ directory.

Registry Detection Example

detection:
  method: registry
  display_name_regex: '^Example Application$'
installer:
  type: exe
  silent_args: [/S]

Sources: catalog/packages.yaml:14-25, README.md:313-330

Procedures for Adding a Package

1. Modify Catalog: Add the YAML entry to catalog/packages.yaml following the schema requirements.
2. Verify Hosts: Ensure all vendor CDN and API hosts are present in the allowed_hosts list.
3. Run Dry Run: Use docker compose run --rm repo-builder --dry-run --product <your-id> to verify metadata resolution without downloading.
4. Perform Real Build: Execute docker compose run --rm repo-builder --once --product <your-id> to perform the actual download and OPSI build.
5. Acceptance Test: Install the resulting .opsi file on a representative Windows VM to confirm the silent arguments and detection work correctly.

Sources: agents.md:43-48, README.md:129-140, builder/builder/main.py:205-220

Conclusion

Adding a package requires precise configuration of the source metadata and installer behavior. By defining products in the catalog, you enable the system to maintain a private, secure repository of software that stays updated without manual intervention or internet access for client machines.

Sources: README.md:10-25