Skip to content

Configuration Reference

dbuild uses compose.yaml as the primary source of truth for metadata.

Environment Variables

Variable Description
DBUILD_REGISTRY Override the target container registry (e.g., ghcr.io/myorg).
GITHUB_TOKEN Authentication token for GitHub Packages and build secrets.
GITHUB_ACTOR The username associated with GITHUB_TOKEN.
DOCKERHUB_USERNAME Enable mirroring by providing a Docker Hub username.
DOCKERHUB_TOKEN Personal access token for Docker Hub mirroring.
CHROME_BIN Path to the Chrome/Chromium binary for screenshot testing.

Config File Locations

File Description
compose.yaml The primary source of truth for metadata and documentation.
.daemonless/config.yaml Project-specific build and test overrides.

Local pkg cache (pkg_cache_url)

/usr/local/etc/daemonless.yaml is host-local builder configuration. Use it for settings that depend on the machine running dbuild, not for per-image project configuration.

To route package installs through a local pkg-cache appliance, set:

1
pkg_cache_url: pkg-cache.example.lan:8080

During dbuild build, dbuild passes that value as the PKG_CACHE_URL build argument. Containerfiles that opt in can use it to point FreeBSD pkg at the local cache during the build. If the file or key is missing, or the Containerfile does not declare/use PKG_CACHE_URL, nothing changes.

Metadata (x-daemonless)

The x-daemonless section in compose.yaml defines discovery metadata used for documentation generation and the images index.

Field Default Description
title (dir name) Human-readable application title
description "" Short description of the application
category "Apps" Application category. Valid values: Base, Databases, Development, Downloaders, Infrastructure, Media Management, Media Servers, Monitoring, Network, Photos & Media, Productivity, Security, Utilities
upstream_url "" URL to the upstream source repository
web_url "" URL to the official project website
freshports_url "" URL to the FreeBSD port on freshports.org (pkg-based images)
user "bsd" Internal container user (docs only)
upstream_binary true true if :latest is built from an upstream release binary; false if built from FreeBSD ports/packages. Controls the tag description in generated READMEs.
icon ":material-docker:" Material or SimpleIcon identifier (e.g. :simple-postgresql:)
logo "" Custom logo filename (SVG or PNG) vendored under docs/images/logos/
logo_dark "" Custom dark mode logo filename (SVG or PNG) vendored under docs/images/logos/
notes "" Free-form Markdown shown in the generated README as a Notes section. Useful for documenting jail requirements like allow.sysvipc.
community "" Help link in Name:URL format (e.g. Discord:https://...)
appjail None Enable AppJail documentation. Bare key or true uses defaults; pass a dict for custom config.
healthcheck None Docker-style healthcheck definition, used as the CIT health URL if cit.health is not set.
docs {} Structured env/volumes/ports documentation. Used to generate README reference tables (see docs: sub-keys below).
image_class "service" Image class controlling README layout. Valid values: service, cli, base. service (default): persistent daemon with compose/CLI/ansible docs. cli: run-and-exit tool, deployment section replaced with usage example. base: base image for FROM, no deployment docs.
deprecated None Mark this image as deprecated. Bare key disables builds; pass a dict with reason, replacement, sunset_date, and/or migration_guide for structured messaging.
readme None Custom Markdown blocks to inject into specific sections of the README.

deprecated: sub-keys

Images can be marked as deprecated with a bare key (generic notice) or a structured dict (with context for users migrating away):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
x-daemonless:
  # Generic — disables CI builds and shows a notice
  deprecated:

  # Structured — adds context and points to a replacement
  deprecated:
    reason: "Superseded by seerr"
    replacement: "seerr"
    sunset_date: "2026-06-01"
    migration_guide: "Stop overseerr, copy /containers/overseerr to /containers/seerr."
Field Default Description
reason "" Human-readable explanation of why the image is deprecated
replacement "" Name of the image that replaces this one (e.g. seerr). Used to generate a prominent migration callout.
sunset_date "" Date after which the image will no longer be available (e.g. 2026-06-01)
migration_guide "" Free-form Markdown with migration steps shown alongside the deprecation notice
successor "" Full URL of the successor image (e.g. https://daemonless.io/images/grimmory). Used to generate a migration callout.

docs: sub-keys

The docs: field accepts three optional sub-keys used to generate README reference tables:

1
2
3
4
5
6
7
docs:
  env:
    ENV_VAR: "Description of this variable"
  volumes:
    /data/path: "Description of this mount"
  ports:
    8080: "Description of this port"

Build Config (.daemonless/config.yaml)

Top-level build: keys

Field Default Description
pkg_name None Default FreeBSD package name (auto-injected as --build-arg PKG_NAME and used for version extraction across variants)
architectures ["amd64"] List of architectures to build (e.g. ["amd64", "arm64"])

Variant fields (build.variants[])

Field Default Description
tag (required) Image tag to push (e.g. latest, 18, pkg)
containerfile "Containerfile" Containerfile to build
args {} Build arguments passed as --build-arg to the Containerfile
aliases [] Additional tags to push alongside this variant (e.g. ["18-pkg", "pkg", "latest"])
default false Mark as the default variant for dbuild test when no --variant is given
pkg_name None FreeBSD package name override for this variant (auto-injected as --build-arg PKG_NAME)
tag_desc None Override the auto-generated tag description in the README version table
puid None Override the per-image cit: puid: re-chown check for this variant (e.g. false for a root image with no PUID/PGID remapping)
cache_prefix "/var/cache/dbuild" Root prefix of cache directories when they are specified as relative path names.
cache_dirs [] Mount a host directory into containers when executing RUN instructions during the build (passed as --volume)

Package Name Injection (pkg_name)

When pkg_name is defined (either at the top level under build.pkg_name or per variant under build.variants[].pkg_name), dbuild automates several workflow steps:

  1. Automatic Build Argument Injection: dbuild passes the specified package name to podman build as --build-arg PKG_NAME=<pkg_name>. This allows your Containerfile to simply declare ARG PKG_NAME and install ${PKG_NAME} without explicitly specifying args: { PKG_NAME: ... }.
  2. Linter Redundancy Check: If both pkg_name and args.PKG_NAME are defined on a variant, dbuild lint emits a warning that args.PKG_NAME is redundant.
  3. Version Extraction: CI and documentation scripts use pkg_name to query FreeBSD package repositories and populate multi-version comparison tables in generated project READMEs.
  4. OCI Image Labeling: The package name is recorded on published images under the io.daemonless.pkg-name label.

CIT Config (cit:)

See the CIT reference for full details. Quick summary:

Field Default Description
mode (auto) Test mode: shell, port, health, screenshot, or commandAuto-detected if omitted.
port None TCP port the service listens on
health None HTTP path for the health check endpoint (e.g. /ping, /api/health)
wait 120 Max seconds to wait for the container to be ready
ready None String to watch for in container logs before starting tests — avoids fixed sleep delays
screenshot_wait None Extra seconds to wait after health passes before capturing the screenshot
ssim_threshold None Override the SSIM similarity threshold for screenshot comparison (0.0-1.0)
edge_threshold None Override the edge-ratio threshold for the UI-element check (default 0.005; lower for sparse/dark UIs)
https false Use HTTPS for health and screenshot checks
compose false Start the service via compose.yaml instead of podman run
puid true Run the PUID/PGID re-chown check (two deploys on a persistent volume) during dbuild test. Set false to opt out for images that don't follow the bsd-owned /config convention.
puid_ignore (required) Paths under /config (find -path globs) allowed to stay non-PUID-owned, e.g. root-owned sshd host keys. The PUID ownership check prunes these.
command [] For command mode: args appended to the image entrypoint (empty = the image's default CMD).
expect_exit 0 For command mode: the exit code that counts as success.
expect_output None For command mode: a regex that must match the container's combined stdout/stderr (e.g. a version string).