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

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:

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:

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:

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.
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 for their format.