interdiode/id-configurator repository overview

⁠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).

⁠As a Docker image

docker run --rm -v "$(pwd)/config.yaml:/config.yaml:ro" -v "$(pwd)/output:/dst" -v "/:/src" \
  interdiode/id-configurator:latest \
  id-configurator apply --config /config.yaml --dst /dst --src /src

More typically, as a builder stage of the target image's own Dockerfile - <src> here is the target image itself, taken as of its target stage, before id-configurator's own changes are copied back on top of it:

FROM debian:trixie-slim AS target
FROM interdiode/id-configurator:latest AS configuration
COPY --from=target / /src/
COPY config.yaml /config.yaml
RUN id-configurator apply --config /config.yaml --src /src --dst /dst
FROM target
COPY --from=configuration /dst/ /

⁠Configuration format

The simplest way to generate a new configuration is InterDiode⁠ itself, through its simple interface - it also handles duplicating application mirrors onto disconnected networks.