Installation
This guide covers the essentials. Read the full upstream guide on GitHub → For a specific release, select its tag in the repository.
Choose an installation format
Get artifacts from BoronDNS releases or the website's downloads page. Check the chosen tag's asset list for availability.
| Format | Intended use |
|---|---|
| Linux x86_64 MUSL installer archive | Static binaries and an installer for a native service. |
| Debian/Ubuntu amd64 package | Native package and systemd lifecycle. |
| Fedora/RHEL-compatible x86_64 RPM | Native package and systemd lifecycle. |
| Docker image archive | A verified image loaded locally with Docker. |
| Source checkout | Development or a custom build. |
The Docker release is an image archive, not a registry image to pull.
Verify the downloaded release
Download your artifact, release-handoff.sha256, and release-handoff.sha256.sigstore.json from the same tag. Authenticate the manifest with Cosign using the exact release workflow identity and tag, then check the artifact against the authenticated manifest.
Follow the upstream verification and installation procedure. It keeps verification, extraction, and installation in a protected directory. Stop if either signature verification or the artifact checksum fails.
Native service
Packages install the binaries under /usr/bin, create the service account and state directories, and enable the systemd unit. The service waits for /etc/borondns-secondary/config.toml; create and validate it using the quick start.
The runtime user needs readable configuration and credentials, plus write access to the zone cache. A manual standalone-binary installation needs its own account, state directory, and service setup; use the upstream systemd unit.
Containers
The image runs as UID/GID 53053. Mount readable configuration and secrets, retain zone state in a named volume, and publish both UDP and TCP DNS ports. For bridge networking, bind management to 0.0.0.0:8080 inside the container and publish it only on host loopback.
Use the complete Docker deployment example for image loading, volume ownership, capabilities, and mounts.
Builds and upgrades
For source builds, follow developer setup, including the checkout's pinned Rust toolchain and locked dependencies.
Before upgrading, verify the artifact and back up configuration, credentials, and service overrides. Validate with the candidate binary, upgrade one secondary, and verify all zone serials and both query transports before continuing through the fleet. Migrating an archive installation to native packages requires handling the existing local systemd unit; follow the package lifecycle guide.