Running the Docker Relay

Article author
Minetta Gould
  • Updated


In order to run the Docker relay, you will first need to install Docker and Docker Compose on your machine. Docker is the container hypervisor and Docker Compose allows you to describe the environment for the relay container and easily bring it online.

Docker Versions

Docker Desktop versions can be found below:

Note: Docker Desktop includes Docker Compose, Docker Engine and Docker CLI.

Setup Steps

  1. After you have everything installed, create a new folder and put the following 2 files inside:


    #level = "error"
    level = "debug"
    verbose = true
    name = "Skynet"
    # Local DNS servers to forward domain specific requests
    addresses = [ "" ]
    local_domains = [ "lan", "" ]

    Make sure to specify your secret key in the value above for your network. You can also specify local DNS servers and domains which should be sent to those servers. Whenever the relay received a query for these domains, it will send the query to the specified servers.


    version: '3'
        image: dnsfilter/relay:latest
        network_mode: host
          - ./relay.conf:/go/bin/relay.conf
          - ./relay.reg:/go/bin/relay.reg
        restart: unless-stopped

    This file defines that Docker should download the dnsfilter/relay:latest image from Docker Hub, should bind to the networks of the host machine, and use the relay.conf file in the folder, and restart if stopped.

  2. Create an empty file with the name below
    The file above can be empty, it just needs to exist. Once the container runs, it will populate this file with the registration information for the relay, so that it persists. Without this file, every time you start and stop the relay, it would create a new copy in the DNSFilter dashboard.

  3. Next, open a terminal window and make sure you are in the same folder as the files. Start the relay container with this command:

    docker-compose up -d && docker-compose logs -f

    The container will start up and you will see log output.

  4. At this point, you can set the IP address of the machine running this container as the DNS for another machine on your network. The queries from that machine should immediately be visible in the log output.

  5. Go to the DNSFilter dashboard and start to see in the Query Log that DNS queries associated with this relay have started to come in.

  6. To shut down the container, run:

    docker-compose down

Was this article helpful?

0 out of 2 found this helpful

Have more questions? Submit a request



Please sign in to leave a comment.