# Configuration

Set default options, choose a configuration file, and use profiles for different builds.

Source: https://debark.dev/docs/reference/configuration

---
Configuration is optional. Use it for settings you reuse, such as a signing key, verification keys, or container backend. Command-line flags can override these defaults.

## Create and inspect the config

```bash
debark config init
debark config path
debark config show
```

`init` creates a starter YAML file. It refuses to overwrite an existing file unless you pass `--force`. `path` prints the chosen location, and `show` prints the loaded settings.

A small builder configuration might look like this. Replace the key path with your own:

```yaml
schema_version: debark.config/v1
backend: auto
sign_key: /home/builder/keys/operator.key
```

When signing must succeed, also pass an explicit `--sign` to the build command.

## File location

The path is selected in this order:

1. `--config PATH`, if supplied.
2. `DEBARK_CONFIG`, if set.
3. `$XDG_CONFIG_HOME/debark/config.yaml`, if `XDG_CONFIG_HOME` is set.
4. `%APPDATA%\debark\config.yaml` on Windows, if `APPDATA` is set.
5. `~/.config/debark/config.yaml` otherwise.

This selects one path; it does not search successive locations for an existing file. A missing file allows the defaults to apply, unless you requested a profile from it.

## Settings

| Key                   | Default                      | Purpose                                                        |
| --------------------- | ---------------------------- | -------------------------------------------------------------- |
| `schema_version`      | —                            | Use `debark.config/v1`.                                      |
| `backend`             | `auto`                       | `auto`, `local`, or `container` for build and base resolution. |
| `image`               | Selected for the target      | Container image override.                                      |
| `container_runtime`   | Auto-detected                | Choose `docker` or `podman`.                                   |
| `self_binary`         | Auto-detected where possible | Linux Debark binary to run inside the build container.         |
| `store_dir`           | Platform cache path          | Directory used for cached package downloads.                   |
| `sign_key`            | Unset                        | Private key file, `gpg:KEY_ID`, or `plugin:NAME`.              |
| `policy_file`         | Unset                        | YAML or JSON policy file used by builds.                       |
| `approved_keys_file`  | Unset                        | File of allowed archive key fingerprints.                      |
| `verify_keys`         | Empty list                   | Public key files used by verify and install.                   |
| `verify_keyring_dirs` | Empty list                   | Directories of trusted public keys.                            |
| `profiles`            | Empty map                    | Named groups of settings.                                      |

Use absolute paths for settings shared across working directories.

## Profiles

A profile overrides selected settings from the top level of the file. For example:

```yaml
schema_version: debark.config/v1
backend: auto

profiles:
  ubuntu-build:
    backend: container
    image: ubuntu:24.04
  offline-target:
    verify_keys:
      - /etc/debark/operator.pub
```

Choose it with `--profile`:

```bash
debark config show --profile ubuntu-build
debark build --profile ubuntu-build \
  --snapshot target.snapshot.tar.zst --out ./bundle --sign operator.key jq
```

You can also set `DEBARK_PROFILE`. An unknown profile name is an error.

## Which value wins?

For settings mapped to environment variables, the order is:

1. An explicit command-line option.
2. A nonempty environment variable.
3. The selected profile.
4. The top-level configuration.
5. The built-in default.

Empty environment variables do not clear configured values. For example, an empty `DEBARK_SIGN` leaves `sign_key` in effect. Use `--no-sign` for an unsigned build.

The download cache is an exception: `store_dir` in the configuration takes precedence over `DEBARK_STORE`. The store commands also accept `--store` to override both. The build command uses the configuration or environment; it has no `--store` flag.

## Environment variables

| Variable                     | Setting or effect                                                               |
| ---------------------------- | ------------------------------------------------------------------------------- |
| `DEBARK_CONFIG`            | Configuration file path.                                                        |
| `DEBARK_PROFILE`           | Selected profile.                                                               |
| `DEBARK_BACKEND`           | `backend`.                                                                      |
| `DEBARK_IMAGE`             | `image`.                                                                        |
| `DEBARK_CONTAINER_RUNTIME` | `container_runtime`.                                                            |
| `DEBARK_SELF_BINARY`       | `self_binary`.                                                                  |
| `DEBARK_SIGN`              | `sign_key`.                                                                     |
| `DEBARK_POLICY`            | `policy_file`.                                                                  |
| `DEBARK_APPROVED_KEYS`     | `approved_keys_file`.                                                           |
| `DEBARK_KEYS`              | `verify_keys`, as a path list.                                                  |
| `DEBARK_KEYRING_DIRS`      | `verify_keyring_dirs`, as a path list.                                          |
| `DEBARK_STORE`             | Cache path when `store_dir` is unset.                                           |
| `DEBARK_STATE_DIR`         | Directory for the installation event log.                                       |
| `SOURCE_DATE_EPOCH`          | Fixed build timestamp; see [Repeatable builds](/docs/concepts/reproducibility). |
| `NO_COLOR`                   | A nonempty value disables color.                                                |
| `TERM=dumb`                  | Disables color and terminal progress rendering.                                 |
| `XDG_CONFIG_HOME`            | Base directory for configuration.                                               |
| `XDG_DATA_HOME`              | Base directory for cached package data.                                         |
| `XDG_STATE_HOME`             | Base directory for installation state.                                          |

Path lists use `:` on Linux/macOS and `;` on Windows.

## When a setting does not take effect

Run `debark config show --json` and check the selected file, profile, and environment. Malformed YAML fails with exit code 1. Unknown configuration keys are ignored, so check spelling if a value stays at its default.

Policy files are separate from the main configuration and reject unknown keys. See [Policy and package checks](/docs/guides/policy-and-doctor) for their format.

<NextSteps
  items={[
    {
      title: 'Build backends',
      href: '/docs/concepts/backends',
      description: 'Set up apt or a container for the builder.',
    },
    {
      title: 'CLI reference',
      href: '/docs/reference/cli',
      description: 'Look up command-line overrides.',
    },
  ]}
/>