Awesome Open Source
Awesome Open Source


Alpine Linux Based Unbound Hyperlocal & DNSSEC Validating DNS Server Multiarch Docker Image



Docker Logo

Docker Image Version Docker Image Size Docker Pulls Docker Stars

Github Logo

Maintenance GitHub version Release date Latest commit main branch License

Commit Activity Forks Stars Issues Pull Requests

Build Multiarch Unbound Docker Image Build Multiarch OpenSSL BuildEnv Docker Image Build Multiarch Libevent BuildEnv Docker Image

Image Components Versions

Current Unbound release Current OpenSSL release Current Libevent release

Available Docker Tags



You can view the changelogs in the Releases section.

Table of Contents

What is Unbound

Unbound is a validating, recursive, caching DNS resolver. It is designed to be fast and lean and incorporates modern features based on open standards. Late 2019, Unbound has been rigorously audited, which means that the code base is more resilient than ever.


About this Image

This container image is based on Alpine Linux with focus on security, performance and a small image size. The unbound process runs in the context of a non-root user, is sealed with chroot and makes use of unprivileged ports (5335 tcp/udp).

Unbound is configured as an DNSSEC validating DNS resolver, which directly queries DNS root servers utilizing zone transfers holding a local copy of the root zone (see IETF RFC 8806) to build a "hyperlocal" setup as an upstream DNS server in combination with Pi-hole for adblocking in mind, but works also as a standalone server. However, even though the image is intended to run a "hyperlocal" setup, it does not necessarily mean that it has to be used that way. You are absolutely free to edit the unbound.conf file according to your own needs and requirements, especially if you'd rather like to use an upstream DNS server which provides DoT or DoH features instead of using the "hyperlocal" feature.

To provide always the latest versions, the following software components are self compiled in the build process using separated workflows and are not just installed:

The image is completely built online via a GitHub Action with hardened runners and not locally on my systems. All components as well as the Internic files (root.hints and are verified with their corresponding PGP keys and signature files if available to guarantee maximum security and trust.

Unbound itself is compiled from source with hardening security features such as PIE (Position Independent Executables), which randomizes the application's position in memory which makes attacks more difficult and RELRO (Relocation Read-Only) which also can mitigate exploitations by preventing memory corruption.

Feature Supported
Unprivileged user
Draft-0x20 (caps-for-id: yes)
DNS over TLS
QName Minimization
Auth. zones with local copy of root zone
Aggressive use of DNSSEC-Validated Cache
Response Policy Zones
EDNS Client Subnet

I hope you enjoy the image.


Current multiarch-builds of the image are available on Docker Hub and is the recommended source of installation on any Linux-based 386, arm, arm64 or amd64 platform.

How to use this Image

You should adapt the /usr/local/unbound/unbound.conf file and my example docker-compose.yaml files to your needs. The compose files also deploys Pi-hole for blocking ads and to prevent tracking as well as Watchtower for keeping your images up to date.

To provide a better structuring of the unbound.conf file, directories for optionally storing zone and other configuration files as well as for your certificates and the unbound.log file have been created and can be mounted as volumes:

The config files in the conf.d and zones.d folders must be named with the suffix .conf to prevent issues with specific host configurations.

The splitted configuration files located in unbound/examples/usr/local/unbound are only meant to give you an impression on how to separating and structuring the configs. Please mind that those files are examples which also needs to be edited to make them work for your environment if you intend to use them. It might be necessary to fix permissions and ownership of the files put in the persistent volumes if unbound refuses to start. You can access the running image by executing the following command in your shell: sudo docker exec -ti madnuttah-unbound /bin/sh. If you have assigned a different name for the image than madnuttah-unbound, this must be adjusted of course.

Other than that, splitting ain't really necessary as your standard unbound.conf will perfectly do the job.

Folder Structure



Port Description
5335 Listening Port (TCP/UDP)

If you want to use this image as a standalone DNS resolver without Pi-hole, the given ports must be changed to 53 (TCP/UDP) in your unbound.conf and docker-compose.yaml.

Standard Usage

The best way to get started is using docker-compose. I have provided combined Pi-hole/Unbound/Watchtower docker-compose.yaml samples which I'm using in slightly modified form that makes use of a MACVLAN or Bridge network which must be adapted to your network environment and to suit your needs for development or production use. Especially all entries in angle brackets (<>) needs your very attention!

I prefer using a MACVLAN network configuration instead of a bridged or rather unsafe host network, but other network configurations will run as well.

Anyway, you can also spin up the container with the following command:

docker run --name madnuttah-unbound -d \
-p 5335:5335/udp \
-p 5335:5335/tcp \
--restart=unless-stopped \

Documentation and Feedback


In-depth documentation for NLnetLabs Unbound is available on the Unbound project's website and here goes a direct link to the documentation of the default unbound.conf file.

There's also a dedicated Unbound documentation website which can be accessed using this link.


Feel free to contact me through a GitHub Issue if you have any questions, requests for new features or encounter problems with the image.


If you like to contribute to this repository, take a look at the Contributing Guidelines.




Unless otherwise specified, all code is released under the MIT license. See the LICENSE for details.

Licenses for other components


Please note that this is a work of a private contributor and I'm neither affiliated with NLnetLabs or Pi-hole nor is NLnetLabs or Pi-hole involved in the development of the image. The marks and properties, 'Unbound' and 'Pi-hole' are properties of NLnetLabs and Pi-hole respectively. All rights in the source codes, including logos relating to said marks and properties belong to their respective owners.


Stay up-to-date with the development by following my social media accounts:

Follow me on Mastodon
Follow me on Twitter

Alternative Project Comparisons
Related Awesome Lists
Top Programming Languages
Top Projects

Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Docker (97,273
Dockerfile (26,599
Dns (10,196
Arm (8,404
Arm64 (789
Dnssec (371
Dnscrypt (198
Amd64 (173
Dns Over Https (152
Unbound (94
Dns Over Tls (85
Multiarch (75
Dns Resolver (44
Hyperlocal (13
Dnstap (11
Dns Forwarder (10
Dns Privacy (9
386 (6
Small Size (4