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, system package manager sources (APT, YUM/DNF, APK) and language-specific package manager settings (pip/uv/poetry, Maven/Gradle/Ivy/SBT/Leiningen, Composer, npm, cargo, Go modules, RubyGems, NuGet). 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 from a file (--config), from a base64-encoded string, typically an environment variable (--config-env / $ID_CONFIGURATOR_CONFIG), or downloaded over HTTP(S) from a URL (--config-url). --config-url-cacert-content optionally gives the PEM content of the CA certificate to trust for that one download, for an internal endpoint signed by a private CA the running system doesn't otherwise trust yet (e.g. before the certificates module has ever run) - it defaults to the system's own trust store otherwise. --config-url-insecure disables certificate (and hostname) verification entirely instead, overriding --config-url-cacert-content - insecure, only meant for a first bootstrap against a server whose certificate isn't trustable, or trusted, yet by any other means.
• 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. For example, the configured Alpine repositories are only written if --src can be identified as an Alpine filesystem (i.e. it has an /etc/apk directory); and a source cloning Debian's official repository is only configured if that official repository is actually present in the filesystem given via --src (via uri-to-replace, see "Replacing an existing repository" below).

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

# Download the configuration from an internal HTTPS server instead of a local file
uv run id-configurator apply \
  --config-url https://config.internal.example/device.yaml \
  --config-url-cacert-content "$(cat internal-ca.pem)" \
  --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. Every configurations.* block is optional - a module that finds nothing to do for it simply does not run. version is the configuration format's own schema version (currently "1.0", and the default if omitted) - independent of the id-configurator package version - so a future, incompatible format change can be told apart from this one:

version: "1.0"
uuid: <UUID>
organisation: <string>
description: <string>
configurations:
  certificates:
    - name: <string>
      content: <PEM>
  apt:
    sources:
      - name: <string>
        uris: [<string>]
        suites: [<string>]
        components: [<string>]
        signed-by: <ASCII-armored GPG public key>       # or signed-by-file: <path already on the target>
        uri-to-replace: <fnmatch pattern, optional>      # see "Replacing an existing repository" below
  apk:
    repositories:
      - name: <string>
        url: <string>
        key: <RSA public key, optional>
        url_to_replace: <fnmatch pattern, optional>
  yum:
    repositories:
      - name: <string>
        index-url: <string>
        gpg-url: <string, optional>
        index-url-to-replace: <fnmatch pattern, optional>
    keys:
      - name: <string>
        content: <GPG key>
  python:
    repositories:
      - name: <string>
        index-url: <string>
  java:
    repositories:
      - name: <string>
        url: <string>
  php:
    repositories:
      - name: <string>
        url: <string>
  npm:
    repositories:
      - name: <string>
        url: <string>
  rust:
    repositories:
      - name: <string>
        url: <string>
  go:
    repositories:
      - name: <string>
        url: <string>
  ruby:
    repositories:
      - name: <string>
        url: <string>
  nuget:
    repositories:
      - name: <string>
        url: <string>

Replacing an existing repository

apt.sources[].uri-to-replace, apk.repositories[].url_to_replace and yum.repositories[].index-url-to-replace are optional fnmatch patterns. When set, the configured repository is only written if the pattern matches at least one URI/URL already present in --src's existing configuration - and only the matching existing entries are disabled, the rest are left untouched. This lets a configuration safely target "whatever machine this is applied to": e.g. uri-to-replace: "http://deb.debian.org/*" replaces Debian's default mirror if (and only if) it's actually there, without disturbing any other source a given machine might already have. Leaving the field unset never disables anything - the configured repository is simply added alongside whatever is already present.

Modules

This tool's own modular structure is meant to be extended: see CLAUDE.md for the module interface and how to add one.

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

CeCILL v2.1 (GPL-compatible free software license). See LICENSE. Copyright InterDiode SA.