Skip to content

daemonless

Configuration

daemonless/daemonless

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.
`/usr/local/etc/daemonless.yaml`	Global templates for shared build variants.

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:`)
`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.

`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):

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:

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 for version extraction across all 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`	Override the top-level `build.pkg_name` for this variant
`tag_desc`	`None`	Override the auto-generated tag description in the README version table

CIT Config (`cit:`)

See the CIT reference for full details. Quick summary:

Field	Default	Description
`mode`	`(auto)`	Test mode: `shell`, `port`, `health`, or `screenshot`. Auto-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)
`https`	`false`	Use HTTPS for health and screenshot checks
`compose`	`false`	Start the service via `compose.yaml` instead of `podman run`