First Config

DockNS can be configured using a TOML file, environment variables, or a combination of both.

By default, the config file is located at /etc/dockns/config.toml, but the location can be specified using the DOCKNS_CONFIG_FILE environment variable or the --config-file <filepath> command-line argument.

Simple Starter Configuration

The most basic configuration is just name server configuration, all other parameters use defaults which can be overwritten either in config.toml, environment variables, or CLI arguments.

config.toml

[name_servers.server1] # Create a new name server with an id of server1
service = "technitium" # Selects the type of name server
host = "http://<ip>:5380" # Since Technitium is self-hosted, the host of the API must be specified
api_key = "<api key>" # Technitium API key to authorize DockNS to add and remove records

docker-compose.yaml (env vars only)

services:
  dockns:
    image: brenekh/dockns:latest
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      DOCKNS_NS_SERVER1_SERVICE: technitium
      DOCKNS_NS_SERVER1_HOST: "http://<ip>:5380"
      DOCKNS_NS_SERVER1_API_KEY: "<api key>"

Environment variables use the pattern DOCKNS_NS_<SERVER ID>_<FIELD>, where <SERVER ID> matches the ID used in Docker labels. This approach keeps secrets out of config files, making it ideal for deployments where configuration is managed externally (e.g., via secret managers or CI/CD variables).

Server ID Case Sensitivity

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

For more details on name server configuration, visit the Name Server docs.

Other Relevant Options

• Docker Host - Control where to find the Docker daemon socket. Follows the same syntax as the Docker CLI.

  Env Var: DOCKER_HOST

  Up to 99 additional daemons can be configured with the same syntax using the DOCKER_HOST_<1-99> environment variables. The env var numbers must be contiguous, DockNS will try number 1 and continue increasing the number until it can't a variable. Example: DOCKER_HOST_1=unix:///var/run/docker.sock

• Dry Run - Evaluate container labels without modifying the records on the name server(s).

  TOML: dry_run

  CLI: --dry-run

  Env Var: DOCKNS_DRY_RUN

• Log Level - Set the level of logging from the application to stdout.

  TOML: log_level

  CLI: --log-level

  Env Var: DOCKNS_LOG_LEVEL

• Include Stopped - Whether or not to include stopped containers' labels when looking for records.

  TOML: include_stopped

  CLI: --include-stopped

  Env Var: DOCKNS_INCLUDE_STOPPED

A full list of options can be found in the config reference.