NAME

dbuild - FreeBSD OCI container image build tool

SYNOPSIS

dbuild [OPTIONS] COMMAND [ARGS...]

DESCRIPTION

dbuild provides a streamlined interface for creating and managing OCI-compliant containers that run natively in FreeBSD Jails. It eliminates the friction of configuring ocijail, networking, and jail templates by using a 'Registry-First' approach. Configuration is automatically derived from Git remotes and standard Compose files, allowing for reproducible builds across local and CI environments.

COMMANDS

build: Build container images from Containerfiles.

-h, --help: show this help message and exit
--variant: filter to a single variant by tag (e.g. latest, pkg)
--arch: override target architecture (e.g. amd64, aarch64)
-p, --parallel: build variants in parallel; optionally limit to N concurrent builds

ci-prepare: Set up a FreeBSD CI runner with all build dependencies.

-h, --help: show this help message and exit
--arch: override target architecture (e.g. amd64, aarch64)
--compose: also install podman-compose

ci-run: Run the complete CI/CD pipeline for all (or selected) variants.

-h, --help: show this help message and exit
--variant: filter to a single variant by tag (e.g. latest, pkg)
--arch: override target architecture (e.g. amd64, aarch64)
--prepare: run ci-prepare before the pipeline

ci-test-env: Run read-only checks to verify the CI environment is ready.

-h, --help: show this help message and exit

detect: Auto-detect variants and output the build matrix.

-h, --help: show this help message and exit
--format, -f: output format (default: json)

generate: Render documentation and build files using Jinja2 templates.

-h, --help: show this help message and exit
--community: override community help link (e.g. Discord:https://...)

info: Display detected configuration in a human-readable format.

-h, --help: show this help message and exit

init: Generate starter files for a new dbuild project.

-h, --help: show this help message and exit
--freebsd-port: initialize from a FreeBSD port (e.g. net-p2p/bazarr)
--name: application name (e.g. radarr)
--title: human-readable title (e.g. Radarr)
--category: application category (default: Apps)
--type: application type (default: generic)
--port: default application port (default: 8080)
--variants: comma-separated list of variants to scaffold (default: latest)
--community: override community help link (e.g. Discord:https://...)
--dry-run: show what would be created without writing to disk
--github: generate GitHub Actions workflow (.github/workflows/build.yaml)
--woodpecker: generate Woodpecker CI pipeline (.woodpecker.yaml)

lint: Check compose.yaml and .daemonless/config.yaml for correctness. Lints the current repo if run from an image directory, or all subdirectories if run from a workspace root.

-h, --help: show this help message and exit

manifest: Create and push multi-architecture manifest lists.

-h, --help: show this help message and exit

push: Tag and push built images to the configured registry.

-h, --help: show this help message and exit
--variant: filter to a single variant by tag (e.g. latest, pkg)
--arch: override target architecture (e.g. amd64, aarch64)

sbom: Generate a CycloneDX SBOM via trivy and pkg query.

-h, --help: show this help message and exit
--variant: filter to a single variant by tag (e.g. latest, pkg)
--arch: override target architecture (e.g. amd64, aarch64)

screenshot: Start a container, wait for it to be ready, and capture a screenshot.

-h, --help: show this help message and exit
--variant: filter to a single variant by tag (e.g. latest, pkg)
-o, --output: save screenshot to FILE (default: .daemonless/baseline.png)

test: Run container integration tests against built images.

-h, --help: show this help message and exit
--variant: filter to a single variant by tag (e.g. latest, pkg)
--json: write test result JSON to FILE
--backend: which backend(s) to test with: podman, appjail, or all (default: all)

ENVIRONMENT

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.

FILES

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.

EXAMPLES

Build and push all variants:

: dbuild build --push Initialize from a FreeBSD Port:
: dbuild init --freebsd-port net-p2p/transmission Run specific tests:
: dbuild test --variant pkg

EXIT STATUS

0: Success.
1: Build, test, or system failure.
2: Command-line usage error (invalid flags or arguments).