11notes/docker-netbird: A Rootless, Distroless Single-Image NetBird

What this image actually changes

NetBird itself is a WireGuard-based overlay network with Zero Trust Network Access. The official distribution splits the components across several images, each running as root. 11notes/docker-netbird compresses the whole stack into one image that runs as UID/GID 1000, has no shell, is read-only, and is distroless. The README claims a size of 73MB on disk against 337MB for the netbirdio images. That size difference is the concrete payoff. The trade-off is that you lose armv7 support, which the official images still offer. If you run on Raspberry Pi-class hardware, this image is not for you.

The single-image architecture and its init binary

Unlike the official multi-image setup, this container runs NetBird from a single image. The dashboard component needs a custom command entry in the compose file because the image supports all NetBird images as one. The init binary performs two jobs. First, it replaces environment variables in the default.yml config file, accepting either ${VAR} or $VAR syntax. Second, it generates random values for unset keys and hashes from the default config. That means you do not have to pre-generate secrets for authSecret or sessionCookieEncryptionKey. The default config uses the embedded IdP, so you can start without an external identity provider. The README warns that post tag 0.70.5 the image runs the embedded IdP by default and uses the unified management binary. If you were on an external IdP, you must follow NetBird's migration guide.

Getting it running: compose and config keys

The compose example pins the image to 11notes/netbird:0.77.1 and applies a lockdown anchor that sets read_only: true and no-new-privileges: true. The server service depends on a postgres service with a healthcheck. Environment variables include TZ, NETBIRD_FQDN, and POSTGRES_PASSWORD. The config file lives in /netbird/etc and dynamic data in /netbird/var. The default.yml snippet shows server.listenAddress :8080, metricsPort 9090, healthcheckAddress :9000, and exposedAddress https://${NETBIRD_FQDN}:443. You can override the whole config with your own file or an inline config. The README points to a separate RTFM document for changing the default UID/GID, so that is not covered in the repository itself.

The no-latest tag policy and update model

There is no :latest tag. The maintainer deliberately avoids it because breaking changes would propagate to everyone using :latest. Instead you use short semver tags like :0 or :0.77, which update to the latest minor or major version within that range. The README argues this is identical to :latest but fixed to a version boundary. There is also a :rolling tag for the bleeding edge, with a warning that you will get the newest release and potentially breaking changes. For a security-focused image, this is a sensible update policy, but it means you must actively decide which tag to track. If you want reproducible deployments, pin a full version like :0.77.1. If you want automatic patch updates, :0.77 gives you that within the same minor.

Security posture and its limits

The image is rootless, distroless, read-only, and has a health check. It is automatically scanned for CVEs before and after publishing. The CI/CD process is pinned and secure, according to the README. These are strong guarantees for a container image. But distroless means no shell, so debugging inside the container is harder. If something breaks, you cannot exec into a shell to inspect the filesystem. You must rely on logs and the health check. Also, read-only mode means all writable state must go to the named volumes /netbird/etc and /netbird/var. The compose example mounts a volume for server.etc. If you forget a writable path, the container may fail at runtime. That is a real operational constraint.

A genuine limitation: the config format shift

The most disruptive change is the switch from management.json to yml config. The README issues a caution that post tag 0.70.5 the image uses the yml config and not the management.json anymore. Any existing setup that relied on the old JSON format will break. You must convert your configuration. The default config embeds the IdP, so if you were using an external IdP like Keycloak, you need to follow NetBird's migration guide. This is not a trivial update. It is a breaking change that the maintainer flags clearly, but it means you cannot treat this image as a drop-in replacement for an older NetBird deployment. Verify your IdP setup before upgrading.

Alternative: official netbirdio images

The direct alternative is the official netbirdio images, which the README compares against. Those images run as root (init default 0:0), are not distroless, and are larger at 337MB. They support amd64, arm64, and armv7, whereas this image only supports amd64 and arm64. The official images also use the standard NetBird distribution, which may follow a different config evolution. If you need armv7 or prefer to stay close to the upstream packaging, the official images are the safer choice. If you value the security hardening and smaller footprint, this image is the trade. The choice hinges on whether you can accept the config migration and the loss of armv7.

Maintenance and license implications

The repository is under the MIT license, which is permissive for reuse. The image is auto-updated via CI/CD to the latest NetBird version, so you do not have to manually rebuild. Releases are frequent, with v1.36.1 pushed on 2026-08-22, about a week after v1.36.0. That cadence means you need to track updates if you want security patches. The no-latest policy forces you to choose a tag, which is good for stability but requires you to bump the tag manually when you want a new major or minor. The README mentions Terraform deployment scripts and Helm charts in the repository, but the details are not in the provided material. For licensing, the MIT license applies to the container image project itself, not to NetBird, which is under its own license. You should check NetBird's license separately if that matters to your use case.

Editorial conclusion

Adopt 11notes/docker-netbird if you run NetBird self-hosted and want a single container that is rootless, distroless, read-only, and small (73MB vs 337MB for official images). Avoid it if you need armv7 support, which the official images provide but this image does not. Before adopting, verify your current NetBird config against the post-0.70.5 switch to the yml format and embedded IdP, and confirm your external IdP migration path with the linked NetBird guide. Also pin a minor tag like :0.77 rather than :rolling to avoid unexpected breaking changes.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes