Installation

Docker

A Docker image is available on Docker Hub (brenekh/dockns).

Docker CLI

docker run \
  -v /var/run/docker.sock/var/run/docker.sock \
  -v ./config.toml:/config.toml:ro \
  -v ./data:/data \
  docker.io/brenekh/dockns:0.5.0

Docker Compose

services:
  dockns:
    image: docker.io/brenekh/dockns:0.5.0
    environment:
      # Setting DOCKER_HOST allows for Docker daemons on other socket files
      # or TCP connections to be used by DockNS.
      # DOCKER_HOST: /var/run/docker.sock
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock # Mount Docker socket to read labels
      - /docker-mounts/dockns/config.toml:/config.toml:ro # Name server configuration
      - /docker-mounts/dockns/data:/data # Data folder to save status between restarts
    restart: unless-stopped

NixOS

This repository contains a flake which provides both a package and module. Channel-based Nix is not currently supported.

Release Process Note

The latest stable release of DockNS is available in the nixos-release branch. Omitting ?ref=nixos-release from the examples below will cause Nix to use the latest development version, which may have breaking behavior not yet documented.

It is therefore highly recommended to use the nixos-release branch instead of the master branch when using DockNS via Nix.

Package

If you just want to run the binary, you can use nix shell or nix run with git+https://codeberg.org/BrenekH/DockNS.git?ref=nixos-release as the argument (i.e. nix run git+https://codeberg.org/BrenekH/DockNS.git?ref=nixos-release).

Nix Module

The provided Nix module offers Nix-native configuration and a hardened SystemD service.

To use the Nix Module add the following to your flake inputs:

inputs = {
  # ...
  dockns.url = "git+https://codeberg.org/BrenekH/DockNS.git?ref=nixos-release";
  #dockns.inputs.nixpkgs.follows = "nixpkgs"; # Uncomment to reduce the number of nixpkgs definitions in the Nix store.
  # ...
};

Then you can add inputs.dockns.nixosModules.<system>.dockns as an import to your system configuration and enable DockNS with services.dockns.enable = true;.

Example:

imports = [
  # Other module imports here

  # Import for specifically amd64 linux systems.
  # i686-linux, aarch64-linux, and armv6l-linux are also available.
  inputs.dockns.nixosModules.x86_64-linux.dockns
];

# ...

services.dockns = {
  enable = true;
  record_defaults.ttl = 3600; # Set default time to live to 1 hour

  # Sample name server config
  name_servers = {
    internaldns = {
      service = "technitium";
      host = "http://<ip>:5380";
      api_key = "<api key>";
      record_defaults = {
        A.ip = "<system ip address>";
        CNAME.target_domain = "ingress.domain.tld";
      };
    };
  };
};

Manual Installation

To install on systems which don't have a native package, you can compile the project on your own.

Requirements

• Rust v1.88.0+
• OpenSSL

Compilation Steps

1. Obtain a copy of the source code. Either clone via Git (git clone https://codeberg.org/BrenekH/DockNS.git) or download the source code zip file and extract it to a location of your choosing.

2. Open a terminal in the source code folder.

3. Run cargo build --release.

4. The binary will be located within the source code folder as target/release/dockns.