id-configurator

id-configurator is a CLI tool by InterDiode that configures a device (typically a Docker image) in an air-gapped environment: no network access is required or ever used.

It reads a single configuration (JSON or YAML), and applies it to a filesystem tree, writing only the files that need to change: root certificates, package manager sources (APT, YUM/DNF, APK), and language-specific package manager settings (pip/uv/poetry, Maven/Gradle/Ivy/SBT/Leiningen, ...). The result can then be used to build a Docker image or otherwise deployed to the target device.

How it works

• --dst points to the destination directory that receives every modified or created file. id-configurator never writes anywhere else.
• --src (optional) points to an existing filesystem, used to detect the current configuration (existing APT sources, existing Java keystores, etc.) so it can be extended or disabled instead of blindly overwritten.
• The configuration is loaded either from a file (--config) or from a base64-encoded string, typically an environment variable (--config-env / $ID_CONFIGURATOR_CONFIG).
• Each feature is implemented as an independent, self-registering module. On apply, every module inspects the configuration and the source filesystem and decides for itself whether it has something to do; only relevant modules touch the destination directory.

Installation

Requires Python 3.13+.

uv sync

Usage

# Apply a configuration file to a destination directory
uv run id-configurator apply --config config.yaml --dst ./output

# Take an existing filesystem into account (e.g. to extend its APT sources)
uv run id-configurator apply --config config.yaml --src /path/to/rootfs --dst ./output

# Use a base64-encoded configuration from the environment instead of a file
export ID_CONFIGURATOR_CONFIG=$(base64 -w0 config.yaml)
uv run id-configurator apply --dst ./output

# Validate a configuration without applying it
uv run id-configurator validate --config config.yaml

# List the available modules
uv run id-configurator list-modules

The tool can also be invoked as python -m id_configurator.

Configuration format

The configuration is a JSON or YAML object:

uuid: <UUID>
organisation: <string>
description: <string>
configurations:
  certificates:
    - name: <string>
      content: <PEM>
  apt:
    sources:
      - name: <string>
        uris: [<string>]
        suites: [<string>]
        components: [<string>]
    keys:
      - name: <string>
        content: <base64-encoded GPG key>
  apk:
    repositories:
      - url: <string>
        key: <base64-encoded RSA public key>
  yum:
    repositories:
      - name: <string>
        index-url: <string>
        gpg-url: <string>
    keys:
      - name: <string>
        content: <base64-encoded GPG key>
  python:
    repositories:
      - name: <string>
        index-url: <string>
  java:
    repositories:
      - name: <string>
        url: <string>

Modules

Module	Applies to
certificates	Installs root certificates into the system's CA store (update-ca-certificates).
apt	Disables existing APT sources and adds the configured ones, in DEB822 format.
apk	Disables existing Alpine /etc/apk/repositories entries and adds the configured ones, plus their keys.
yum	Disables existing YUM/DNF .repo files, adds the configured ones, and imports their GPG keys.
python	Points pip, uv, poetry and easy_install to the configured Python package indexes.
java	Adds root certificates to every detected JKS/PKCS12 keystore, and configures Maven, Gradle, Ivy, SBT and Leiningen repositories.

More modules (npm, gem, go, composer, ...) are planned; see CLAUDE.md for the full roadmap.

Development

uv sync                            # install dependencies
uv run pytest                      # run the test suite
uv run ruff check --fix .          # lint
uv run ruff format .               # format
uv run pre-commit run --all-files  # run all pre-commit hooks

License

Proprietary. See LICENSE. Copyright InterDiode SA.