Development
This guide covers the internal architecture, conventions, and patterns for building and contributing to daemonless containers.
Architecture Overview
Image Hierarchy
graph TD
A[daemonless/base-core:15.1] --> B[daemonless/base-exec:15.1]
A --> R[daemonless/base-rcd:15.1]
B --> C[daemonless/arr-base:15.1]
B --> E[Single-process apps]
R --> D[daemonless/nginx-base:15.1]
R --> M[Multi-service appliances]
C --> F[radarr, sonarr, lidarr, prowlarr]
D --> G[nextcloud, vaultwarden, organizr]
E --> H[navidrome, traefik, redis, jellyfin, etc.]
M --> N[gitea, paperless-ngx, readmeabook, unifi]
Pick the base by how many processes the image runs:
- base-exec (most images): one process.
/initruns the setup scripts, thenexecs the app asbsd. The app's exit is the container's exit, so podman, AppJail or Kubernetes restart, stop and log it. There's no supervisor inside. - base-rcd: several services in one container (an app behind nginx, an app with its own database or workers). rcd(8) runs as the container's main process and restarts any service that exits.
Both handle PUID/PGID the same way. Specialized bases add runtime dependencies:
- arr-base (on base-exec) - .NET runtime and libraries for *arr applications
- nginx-base (on base-rcd) - nginx pre-installed, run as an rcd unit next to your app
The old s6 base image still exists for images built outside daemonless. Don't
start new images on it. See Architecture for the full tree.
Repository Structure
Each image is a standalone git repo:
Labels Reference
dbuild generate writes these labels into the generated Containerfile* from your compose.yaml metadata — don't add them by hand (see Service Anatomy). This section is a reference for what each one means.
io.daemonless.* Labels
| Label | Required | Purpose | Example |
|---|---|---|---|
io.daemonless.port |
Conditional | Primary listening port(s) | "7878", "80,443,8080" |
io.daemonless.category |
Yes | Service classification | "Media Management" |
io.daemonless.packages |
Yes | FreeBSD packages to install | "${PACKAGES}" |
io.daemonless.volumes |
No | Suggested volume mounts | "/movies,/downloads" |
io.daemonless.upstream-url |
No | Version-check API endpoint | "https://api.github.com/repos/Radarr/Radarr/releases/latest" |
io.daemonless.upstream-jq |
No | jq filter to extract the version from that endpoint | ".tag_name" |
io.daemonless.arch |
No | Supported architecture | "amd64" (default) |
io.daemonless.type |
No | Image type (base images only) | "base" |
io.daemonless.wip |
No | Work-in-progress flag | "true" |
io.daemonless.pkg-name |
No | Package name for :pkg builds | "radarr" |
io.daemonless.base |
No | Base image type | "nginx" |
Upstream Version Tracking
For upstream-binary images, version status is tracked from two labels, both rendered from Containerfile*.j2 ARGs:
| Label | Purpose | Example |
|---|---|---|
io.daemonless.upstream-url |
HTTP endpoint returning version info (usually a GitHub releases API URL) | "https://api.github.com/repos/Radarr/Radarr/releases/latest" |
io.daemonless.upstream-jq |
jq filter applied to that response to get the version string |
".tag_name" |
The version pipeline fetches upstream-url and applies upstream-jq. Package-based images skip these and read the version from pkg via io.daemonless.pkg-name instead. (The older upstream-mode/-repo/-package/-branch/-sed labels are obsolete and no longer read.)
Category Values
Media Management- radarr, sonarr, lidarr, prowlarr, overseerrMedia Servers- jellyfin, plex, tautulliDownloaders- sabnzbd, transmissionInfrastructure- traefik, gitea, woodpecker, tailscaleDatabases- redis, immich-postgresPhotos & Media- immich-server, immich-mlUtilities- nextcloud, vaultwarden, mealie, n8n, smokeping
Special Annotations
For .NET applications (arr-base derivatives):
The Source of Truth: compose.yaml
Daemonless uses a standardized compose.yaml file located in the root of each repository to define the image's metadata, dependencies, and configuration. Do not manually add io.daemonless.* labels to your Containerfile.
Instead, define your app in compose.yaml under the x-daemonless block:
Then, run dbuild generate to automatically inject the required io.daemonless.* labels into your Containerfiles and regenerate the README.md.
For a quick map of what belongs in compose.yaml, .daemonless/config.yaml, and Containerfile*.j2, see Service Anatomy.
Containerfile Patterns
Standard Pattern (:latest)
Downloads binaries from upstream for bleeding-edge versions:
This is Containerfile.j2; dbuild generate substitutes the {{ ... }} values from compose.yaml:
Package Pattern (:pkg)
Uses FreeBSD packages for stable, tested versions:
Multi-stage Pattern
For Node.js or compiled applications:
Init and Services
Every image's entrypoint is /init. It is a short shell script, and it does
the same setup on base-exec and base-rcd:
- Networking: brings up the loopback interface (
lo0) for health checks. - Setup scripts: runs each executable in
/daemonless/init.d/, in name order.10-usermodcomes from the base and remaps thebsduser toPUID/PGID. Your image adds its own, such as20-<app>. - Custom scripts: runs each executable in
/daemonless/custom.d/(yours to mount, see below). - Start: on base-exec,
execs the image'sCMDasbsd. On base-rcd,execs rcd, which starts the units.
/init runs under set -e, so a setup script that fails stops the container,
and the error is the last thing in podman logs. Make a script fail when the
app can't work without it (a database migration, say), and don't let it fail
for something that doesn't matter.
Started as another user (podman run --user, Kubernetes runAsUser), /init
skips the root-only steps (lo0, the PUID/PGID remap) and runs the app as that
user. Setup scripts that chown or write outside /config should cope with
not being root.
Custom Scripts
Mount your own setup scripts at /daemonless/custom.d. They run as root after
the image's own, before the app starts:
Setup Script
root/daemonless/init.d/20-<app> runs as root before the app:
Only exports made in the launcher reach the app; the ones made here don't.
Launcher (base-exec)
root/daemonless/libexec/<app> is the image's CMD. /init has already
dropped to bsd with dsu when it runs:
Always use exec
exec replaces the shell with the app, so the app gets the runtime's
signals and its exit status is the container's.
There's no supervisor in a base-exec container: when the app exits, the
container exits, and the runtime's restart policy brings it back
(--restart always with podman, restart: always in compose). Images that must
run as root set ENV DAEMONLESS_USER=root.
Units (base-rcd)
A base-rcd image runs each service as an rcd unit,
root/usr/local/etc/rcd.d/<service>.ucl:
- rcd starts units as root, so the unit's launcher drops privileges itself:
exec dsu bsd /app/bin/app. - rcd starts units with an empty environment.
/initsaves the container's environment to/run/rcd.env, andenv_filehands it to the unit. max_retries = 0means restart forever. With rcd's default of 5, a unit that crashes for the fifth time stays down while the container keeps running.sig_stopsets the signal that stops a unit, for apps that want something other thanTERM(nginx:QUIT, PostgreSQL:INT).- rcd stops units one at a time, and
/etc/rcd.confkeeps the total under podman's 10 second stop timeout.
Unit output goes to the container's stdout, so podman logs shows every
service.
cd after dsu does nothing
dsu bsd cd /app cmd runs /usr/bin/cd, which exits without running
cmd. Change directory first: cd /app && exec dsu bsd cmd.
Readiness
Neither base has a readiness protocol. Give the image a health check instead
(HEALTHCHECK_URL and /healthz): podman, fjord and dbuild's tests poll it.
Environment Variables
Base Container
| Variable | Default | Purpose |
|---|---|---|
PUID |
1000 |
User ID for bsd user |
PGID |
1000 |
Group ID for bsd group |
TZ |
UTC |
Timezone |
Logs
Everything an image prints goes to the container's stdout and stderr: the
[init] lines, the setup scripts, the app, and on base-rcd every unit.
The images don't write their own log files. Rotation and retention are the
runtime's job (podman's --log-opt max-size, for example).
.NET Applications
| Variable | Default | Purpose |
|---|---|---|
CLR_OPENSSL_VERSION_OVERRIDE |
35 |
OpenSSL version hint |
DOTNET_SYSTEM_NET_DISABLEIPV6 |
1 |
Disable IPv6 in .NET |
HOME |
/config |
.NET home directory |
Build System
The Daemonless project uses dbuild as its primary build engine. dbuild handles the full lifecycle of an image, from initial build to integration testing and publishing.
Local Building
To build an image locally, navigate to the image repository and use dbuild:
CI/CD Pipeline
Standard .github/workflows/build.yaml for a new image repository:
Legacy CI (Woodpecker as Plan-B)
We previously used Woodpecker CI before migrating to GitHub Actions. Woodpecker serves as our "Plan B" if GHA ever goes down. We still maintain the configuration capability, but we don't currently use it for active builds.
The dbuild ci-run command handles environment preparation, multi-variant building, CIT testing, pushing to the registry, and SBOM generation.
Adding a New Image
1. Create Repository
2. Initialize with dbuild
This creates a starter compose.yaml, Containerfile, .daemonless/config.yaml, and .github/workflows/build.yaml (use --woodpecker instead if you need to scaffold the fallback pipeline).
Initializing from a FreeBSD Port
If the app you're packaging already has a FreeBSD port, point dbuild init at it instead of starting from a blank template. It queries the port's Makefile (title, description, license, category, runtime deps) and pre-fills .daemonless/config.yaml and compose.yaml for you:
Requires a local ports tree checkout ($PORTSDIR, default /usr/ports).
FLAVORS
Some ports build multiple package variants via FreeBSD's FLAVORS mechanism (e.g. editors/joe's tiny/x11 flavors). Pass --flavors to scaffold one pkg-type variant tag per flavor, each pointing at that flavor's own resolved package name:
This generates pkg-tiny, pkg-x11, pkg-latest-tiny, and pkg-latest-x11 variant tags (each with its own pkg_name: in .daemonless/config.yaml) — flavors only apply to pkg-type (Containerfile.pkg) variants, since FLAVORS is a FreeBSD packaging concept with no equivalent for upstream-source builds. --flavors requires --freebsd-port, and dbuild init aborts without scaffolding anything if a requested flavor doesn't exist on that port.
3. Configure Metadata & Assets
Edit compose.yaml to set your app's title, ports, and category. Then, fetch the visual assets and generate the documentation:
This automatically injects the required io.daemonless.* labels into your Containerfiles and builds a rich README.md using your fetched assets.
4. Create Service Files
5. Test Locally
6. Push to Registry
Conventions Checklist
- Use
fetchinstead ofcurl(included in FreeBSD base) - Clean pkg cache:
pkg clean -ay && rm -rf /var/cache/pkg/* - Set ownership:
chown -R bsd:bsd /config /app - Make scripts executable:
chmod +x /daemonless/libexec/* /daemonless/init.d/* - base-exec:
CMDis the launcher, whichexecs the app - base-rcd: each unit's launcher drops to
bsdwithexec dsu bsd ... - Create /config directory and set as VOLUME
- Run
dbuild generateto synccompose.yamlmetadata to Containerfiles - Use ARG for BASE_VERSION, PACKAGES, VERSION
- Include
upstream_urlincompose.yamlfor version detection - Add
io.daemonless.wip="true"for incomplete images
Troubleshooting
.NET Apps Won't Start
Ensure ocijail 0.5.0+ is installed and the annotation is set:
See ocijail Native Support for details.
Permission Denied
Check PUID/PGID match host user:
Service Not Starting
Check the init output and the app's last words:
A setup script that fails stops the container before the app starts; its error
is the last thing in the log. On base-rcd, rcctl status lists the units:
Build Fails on pkg install
Check package name exists: