DockNS

Appearance

Name Server Configuration ​

Basics ​

Name servers can be configured in the configuration file (config.toml), via environment variables, or a combination of both.

Each name server is given a unique ID (often referred to as the Server ID) which is how records are matched to the correct server. For example, to define 2 name servers, one internal and one external, we can give them the IDs internaldns1 and externaldns1:

toml
[name_servers.internaldns1]
service = "technitium"
#...

[name_servers.externaldns1]
service = "cloudflare"
# ...
bash
DOCKNS_NS_INTERNALDNS1_SERVICE=technitium
# ...

DOCKNS_NS_EXTERNALDNS1_SERVICE=cloudflare
# ...

Server ID Case Sensitivity

The <SERVER ID> portion of environment variables is automatically converted to lowercase. For example, DOCKNS_NS_INTERNALDNS1_SERVICE maps to server ID internaldns1, which must match your Docker labels (e.g., dockns.internaldns1.record).

Then, when creating records with labels, we refer to each ID to set the correct IP addresses:

yaml
labels:
  dockns.internaldns1.record: A
  dockns.internaldns1.ip: 192.168.1.50 # Internal IP for internal name server
  # ...

  dockns.externaldns1.record: A
  dockns.externaldns1.ip: 1.2.3.4 # External IP for external name server
  # ...

Hybrid Configuration ​

You can also combine both approaches: define server structure in a config file and inject secrets via environment variables. Environment variable values take precedence over config file values for the same server and field.

toml
# config.toml - safe to commit to version control
[name_servers.externaldns1]
service = "cloudflare"
bash
# Secrets injected at runtime
DOCKNS_NS_EXTERNALDNS1_API_KEY=token_from_secret_manager
DOCKNS_NS_EXTERNALDNS1_ACCOUNT_ID=account_id_from_secret_manager
DOCKNS_NS_EXTERNALDNS1_ZONE_IDS=example.com=zone_id_from_secret_manager

Full Setup ​

Each supported name server has a slightly different way of authenticating to the API. Enterprise-grade solutions like Cloudflare may need special keys, IDs, and setup, where hobbyist/consumer grade servers may only need an API key. This means that the configuration for each server will look slightly different.

In order to keep some semblance of regularity, fields with similar purposes and/or names are combined. For example, if one server needs an API key and another needs an app password, those fields are condensed into the singular api_key field. To get specific instructions for your name server, select from the list of supported name servers below.

Supported Name Servers ​

A Note on Additional Servers ​

At this time, we do not plan on supporting servers which don't have an API to configure records (unbound, bind9, etc.). We don't have the bandwidth to identify ways to transfer files and restart servers.

However, if you know of tools which expose the file configs as APIs we would happily take contributions to support those solutions.