Skip to content

Run Stubby without losing the performance benefits of having a local caching DNS resolver.


Notifications You must be signed in to change notification settings


Folders and files

Last commit message
Last commit date

Latest commit



81 Commits

Repository files navigation

Unbound and Stubby Docker Images

What does this do?

This allows you to run Stubby without losing the performance benefits of having a local caching DNS resolver. Historically, Stubby had better DNS over TLS support than Unbound.

To achieve this, this setup uses two containers, one running Stubby and another running Unbound. Unbound exposes DNS over port 53 and forwards requests not in its cache to the Stubby container on port 8053 (not publically exposed). Stubby then performs DNS resolution over TLS. By default, this is configured to use Cloudflare DNS.

How to use


sudo docker build -t mvance/stubby:latest .

sudo docker build -t mvance/unbound:1.13.1-stubby .

Standard usage

Run these containers with the following command:

docker-compose up -d

Next, point your DNS to the IP of your Docker host running the Unbound container.

Serve Custom DNS Records for Local Network

While Unbound is not a full authoritative name server, it supports resolving custom entries on a small, private LAN. In other words, you can use Unbound to resolve fake names such as your-computer.local within your LAN.

To support such custom entries using this image, you need to update the provided a-records.conf file. This conf file is where you will define your custom entries for forward and reverse resolution.

The a-records.conf file should use the following format:

# A Record
  #local-data: "somecomputer.local. A"
  local-data: “laptop.local. A”

# PTR Record
  #local-data-ptr: " somecomputer.local."
  local-data-ptr: " laptop.local."

Use a customized Unbound configuration

Instead of using this image's default Unbound configuration, you may supply your own unbound.conf. See my unbound-docker README for further details. Note, you will likely want to apply the concepts from those directions via docker-compose.yml.


If you have any problems with or questions about this image, please contact me through a GitHub issue.


You are invited to contribute new features, fixes, or updates, large or small. I imagine the upstream projects would be equally pleased to receive your contributions.

Please familiarize yourself with the repository's file before attempting a pull request.

Before you start to code, I recommend discussing your plans through a GitHub issue, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing.


These deserve credit for making this all possible.



Unless otherwise specified, all code is released under the MIT License (MIT). See the repository's LICENSE file for details.

Licenses for other components


Run Stubby without losing the performance benefits of having a local caching DNS resolver.








No releases published