# id-configurator

`id-configurator` is a CLI tool by [InterDiode](https://interdiode.fr/) 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+.

```bash
uv sync
```

## Usage

```bash
# 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:

```yaml
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: <GPG key>
  apk:
    repositories:
      - url: <string>
        key: <RSA public key>
  yum:
    repositories:
      - name: <string>
        index-url: <string>
        gpg-url: <string>
    keys:
      - name: <string>
        content: <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, nuget, ruby/gem, rust/crates, go, packagist/composer, ...) are planned; see `CLAUDE.md` for the full roadmap.

## Development

```bash
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](LICENSE). Copyright InterDiode SA.