Building Your First Image: A Complete Workflow

This guide walks through the full lifecycle of creating a new daemonless container image, from initialization to GitHub Actions CI/CD.

Why use dbuild?

If you're building FreeBSD container images, dbuild provides a standardized, high-trust workflow that bridges the gap between local development and CI/CD:

• Jinja2 Power: Use templates (.j2) to keep your Containerfile DRY across multiple variants (e.g., :latest vs :pkg).
• Integrated Testing (CIT): Automatically verify that your container actually works (port checks, health endpoints, even screenshots) before pushing.
• GitHub-First: Seamlessly integrates with GitHub Actions and GHCR.io with zero-config reusable workflows.
• Local/CI Parity: The exact same dbuild build and dbuild test commands run on your laptop and in the cloud.

1. Prerequisites

• FreeBSD 14+ or 15+
• dbuild and Podman installed:

1

pkg install sysutils/py-dbuild

2. Initialize the Project

Create an empty directory for your image and run dbuild init. We'll use Traefik as our example:

1
2
3
4
5
6

mkdir traefik && cd traefik
dbuild init \
  --freebsd-port net/traefik \
  --port 8080 \
  --variants latest,pkg,pkg-latest \
  --github

What just happened?

dbuild scaffolded a complete project structure for you:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

traefik/
├── .daemonless/
│   └── config.yaml             # Build variants and CIT test config
├── .github/workflows/build.yaml # GitHub Actions CI pipeline
├── compose.yaml                # Image metadata + deployment example
├── Containerfile.j2            # Template for :latest (upstream binary)
├── Containerfile.pkg.j2        # Template for :pkg and :pkg-latest
└── root/
    ├── etc/services.d/traefik/run # s6 service supervisor script
    └── healthz                 # Optional health check script

3. The "Single Source of Truth": compose.yaml

In the daemonless ecosystem, compose.yaml isn't just for deployment—it's the source of truth for your image's metadata and documentation.

Open compose.yaml and refine the x-daemonless section:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

name: traefik

x-daemonless:
  title: "Traefik"
  icon: ":material-server-network:"        # Browse icons at pictogrammers.com
  category: "Infrastructure"               # See config reference for categories
  description: "Modern HTTP reverse proxy and load balancer for FreeBSD."
  upstream_url: "https://github.com/traefik/traefik" # Must be the SOURCE repo
  web_url: "https://traefik.io/"
  freshports_url: "https://www.freshports.org/net/traefik/"
  upstream_binary: true                    # Tells dbuild :latest uses binaries
  user: "bsd"

  docs:
    env:
      PUID: "User ID for the application process"
      PGID: "Group ID for the application process"
    volumes:
      /config: "Traefik configuration directory"
    ports:
      80: "HTTP"
      443: "HTTPS"
      8080: "Dashboard / API"

services:
  traefik:
    image: ghcr.io/daemonless/traefik:latest
    # ... rest of deployment config ...

4. Crafting the Templates (.j2)

dbuild uses Jinja2 templates to generate standard Containerfiles. This allows you to inject dynamic labels and reuse logic.

Edit Containerfile.j2 (:latest variant)

Replace the placeholder download logic with Traefik's real GitHub releases:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

ARG BASE_VERSION=15
FROM ghcr.io/daemonless/base:${BASE_VERSION}

ARG UPSTREAM_URL="https://api.github.com/repos/traefik/traefik/releases/latest"
ARG UPSTREAM_JQ=".tag_name"

# [dbuild] labels will be automatically injected here

RUN pkg update && pkg install -y ca_root_nss jq && pkg clean -ay

# Fetch version and binary using 'fetch' (FreeBSD native)
RUN TRAEFIK_VERSION=$(fetch -qo - "${UPSTREAM_URL}" | jq -r "${UPSTREAM_JQ}") && \
    fetch -qo /tmp/traefik.tar.gz \
      "https://github.com/traefik/traefik/releases/download/${TRAEFIK_VERSION}/traefik_${TRAEFIK_VERSION}_freebsd_amd64.tar.gz" && \
    tar xzf /tmp/traefik.tar.gz -C /usr/local/bin traefik && \
    chmod +x /usr/local/bin/traefik && \
    mkdir -p /app && echo "${TRAEFIK_VERSION}" > /app/version && \
    rm /tmp/traefik.tar.gz

RUN mkdir -p /config && chown -R bsd:bsd /config

COPY root/ /

5. Generate and Build

The core dbuild loop is Generate → Build → Test.

flowchart TD
    Init["$ dbuild init\nScaffold a new project"] --> Compose
    Init --> Template
    Init --> Config

    Compose["📝 compose.yaml\nTitle, description, ports, env vars, docs"]
    Template["📝 Containerfile.j2\nHow the image is built"]
    Config["📝 .daemonless/config.yaml\nBuild variants and CIT settings"]

    Compose --> Generate
    Template --> Generate
    Config --> Generate

    Generate["$ dbuild generate\nRenders templates → Containerfile + README"]
    Generate --> Build

    Build["$ dbuild build\nBuilds OCI image with podman"]
    Build --> Test

    Test["$ dbuild test\nRuns CIT: shell → port → health → screenshot"]
    Test --> CIT{Pass?}

    CIT -- "✅ yes" --> Push["$ dbuild push\nPushes to ghcr.io/daemonless/app:latest"]
    CIT -- "❌ no" --> Fix["📝 Fix Containerfile.j2\nor .daemonless/config.yaml"]
    Fix --> Build

    style Init fill:#2563eb,color:#fff,stroke:none
    style Generate fill:#2563eb,color:#fff,stroke:none
    style Build fill:#2563eb,color:#fff,stroke:none
    style Test fill:#2563eb,color:#fff,stroke:none
    style Push fill:#2563eb,color:#fff,stroke:none

    style Compose fill:#7c3aed,color:#fff,stroke:none
    style Template fill:#7c3aed,color:#fff,stroke:none
    style Config fill:#7c3aed,color:#fff,stroke:none
    style Fix fill:#7c3aed,color:#fff,stroke:none

Step A: Generate

Turn your templates and compose.yaml into real files:

1

dbuild generate

Step B: Build Locally

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# Build the default variant
dbuild build

# Build all variants defined in .daemonless/config.yaml
dbuild build --variant latest --variant pkg --variant pkg-latest

# Build all variants in parallel
dbuild build -p

# Limit to 2 concurrent builds
dbuild build -p 2

6. Test with CIT (Container Integration Test)

Don't just assume it works. dbuild test spins up the container and runs the checks defined in .daemonless/config.yaml:

1
2
3
4
5

cit:
  mode: health
  port: 8080
  health: /ping
  ready: "Configuration loaded" # Watch logs for this string

Run the test:

1

dbuild test

7. GitHub Integration: dbuild + github

This is where dbuild shines. The .github/workflows/build.yaml file generated by dbuild init --github uses a reusable workflow.

The Workflow File

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

name: Build FreeBSD Container

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  build:
    # This delegates EVERYTHING to the shared daemonless engine
    uses: daemonless/dbuild/.github/workflows/daemonless-build.yaml@main
    with:
      image_name: traefik
    secrets: inherit

Why use the Reusable Workflow?

1. Managed FreeBSD Runners: It automatically handles spinning up FreeBSD VMs on GitHub Actions.
2. Automatic Matrix: It calls dbuild detect to build all your variants in parallel.
3. GHCR.io Auth: It uses your GITHUB_TOKEN to automatically push to ghcr.io/your-user/traefik.
4. SBOM Generation: Automatically generates and attaches CycloneDX Software Bill of Materials.

GitHub "Pro Tips"

• Registry: By default, it pushes to ghcr.io/{github_actor}/{image_name}.
• Commit Directives: Control CI behavior directly from your commit messages:
  • [skip test] — Skip CIT (useful for docs-only changes).
  • [skip push] — Build and test, but don't push to the registry.

8. Summary of Commands

Next Steps

• Learn more about Quality Gates (CIT).
• Explore Multi-Arch Builds for amd64 and aarch64.
• Check the Config Reference for advanced .daemonless/config.yaml options.