satishweb / docker-doh

DNS Over HTTP Container Image

DNS Over HTTP Service Docker Image (Compatible with Raspberry Pi)

Overview

This Docker image provides a DNS Over HTTP (DOH) service, designed to enhance privacy and security by encrypting DNS queries. It supports custom upstream DNS servers and execution of custom scripts. The image is compatible with various architectures including linux/amd64, linux/arm64, and linux/arm/v7. It offers both Alpine and Ubuntu based images for flexibility.

Upcoming Features

• Helm chart for Kubernetes deployments (current chart is usable but not tied to the latest version of DOH)
• Automated CI/CD using Github Actions
• Kubernetes deployment examples

Features

• DNS Over HTTP support
• Custom upstream DNS server option
• Support for custom script execution (/app-config)
• Compatible with below architectures:
  • Alpine: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6,linux/ppc64le,linux/s390x,linux/386
  • Ubuntu: linux/amd64,linux/arm/v7,linux/ppc64le,linux/s390x
• Alpine based tiny images; Ubuntu based image also available
• Comprehensive DOH Server setup example using Docker Compose

Why Use DNS Over HTTP?

Using DNS Over HTTP offers several advantages:

• Protects against ISP monitoring
• Avoids reliance on DOH providers, preserving privacy
• Learn more: Pros & Cons of DNS Over HTTPS
• Additional resource: DNS over HTTPS - Wikipedia

How to Use

docker run -itd --name doh-server \
    -p 8053:8053 \
    -e UPSTREAM_DNS_SERVER=udp:208.67.222.222:53 \
    satishweb/doh-server

Docker Configuration

version: '2.2'
networks:
  default:

services:
  doh-server:
    image: satishweb/doh-server
    hostname: doh-server
    networks:
      - default
    environment:
      DEBUG: "0"
      # Upstream DNS server: proto:host:port
      # We are using OpenDNS DNS servers as default,
      # Here is the list of addresses: https://use.opendns.com/
      UPSTREAM_DNS_SERVER: "udp:208.67.222.222:53"
      DOH_HTTP_PREFIX: "/getnsrecord"
      DOH_SERVER_LISTEN: ":8053"
      DOH_SERVER_TIMEOUT: "10"
      DOH_SERVER_TRIES: "3"
      DOH_SERVER_VERBOSE: "true"
      # You can add more variables here or as docker secret and entrypoint
      # script will replace them inside doh-server.conf file
    volumes:
      # - ./doh-server.conf:/server/doh-server.conf
      # Mount app-config script with your customizations
      # - ./app-config:/app-config
    deploy:
      replicas: 1
      # placement:
      #   constraints:
      #     - node.labels.type == worker

Docker Buildx Setup

Setup: Mac M1/x86

brew install colima
colima start --cpu 8 --memory 16 --disk 150
docker context use colima

Setup: Mac M1 (buildx)

brew install colima
colima start --arch x86_64 --cpu 8 --memory 16 --disk 150 -p buildx
docker context use colima-buildx

Setup: Linux

• Install Docker CLI + Containerd
• Install docker-compose

Start Buildx instance

docker run --rm --privileged multiarch/qemu-user-static --reset -p yes
docker buildx create --use
docker buildx inspect --bootstrap

Build Docker Image

docker build . --no-cache -t satishweb/doh-server -f Dockerfile.alpine

Pull Docker Hub Image

docker pull satishweb/doh-server

Quick Setup Guide

Follow these steps to set up DOH Server on Linux, Mac, or Raspberry Pi in minutes using Docker Compose.

Requirements

• Raspberry Pi/Linux/Mac with Docker preinstalled (Required)
• DNS Server Setup on AWS R53 (Other providers supported)
• AWS Access Key, Secret key, and R53 DNS Hosted Zone ID (for LetsEncrypt based auto installation of SSL Certs) (Optional)

Steps

1. Download the latest release from GitHub to your server:

wget https://github.com/satishweb/docker-doh/archive/v2.3.5.zip
unzip v2.3.5.zip
cp -rf docker-doh-2.3.5/examples/docker-compose-doh-server doh-server
rm -rf v2.3.5.zip docker-doh-2.3.5
cd doh-server

2. Copy env.sample.conf to env.conf and update environment variables:

[email protected]
DOMAIN=example.com
SUBDOMAIN=dns
AWS_ACCESS_KEY_ID=AKIKJ_CHANGE_ME_FKGAFVA
AWS_SECRET_ACCESS_KEY=Nx3yKjujG8kjj_CHANGE_ME_Z/FnMjhfJHFvEMRY3
AWS_REGION=us-east-1
AWS_HOSTED_ZONE_ID=Z268_CHANGE_ME_IQT2CE6

3. Launch services:

./launch.sh

4. Add your custom hosts to override DNS records if needed:

mkdir -p data/unbound/custom
vi data/unbound/custom/custom.hosts

5. Determine your DOH address:

https://dns.example.com/getnsrecord

6. Test the DOH Server:

curl -w '\n' 'https://dns.example.com/getnsrecord?name=google.com&type=A'

Common Issues and Debugging

• If a proxy is still running with a self-signed certificate:

  • Check data/proxy/certs/acme.json contents.
  • Enable debug mode for the proxy by editing the proxy service in docker-compose.yml.
  • Check proxy container logs for errors.

• If unable to bind port 53 for unbound service:

  • Stop systemd-resolved service: sudo service systemd-resolved stop; sudo apt-get -y purge systemd-resolved
  • Retry.

• If unable to bind ports 80 and 443 for proxy service:

  • Another program on the Docker host or one of the Docker containers may be using the same ports.
  • Stop those programs or change the proxy service ports to unused ports.

IPV6 Support

Docker-compose configuration with IPV6 support will be added in the future.

How to Use DOH Server?

Setup Your Router (Recommended)

Configure your router's DHCP settings to point to your DOH server's IP address.

Linux, Mac, Windows Clients

Install Cloudflared for Linux, Mac, or Windows. Set your DOH server as upstream for Cloudflared as follows:

• Linux: /usr/local/etc/cloudflared/config.yml
• Mac: /usr/local/etc/cloudflared/config.yaml
• Windows: Location varies

proxy-dns: true

docker-doh's Issues

doh-server container turns unhealthy when loopback address is used as upstream DNS server

I use your image to setup a doh front end, compose as follow:

  doh-server:
    restart: unless-stopped
    logging:
      options:
        tag: "{{.Name}}"
    image: satishweb/doh-server
    container_name: doh-server
    hostname: doh-server
    network_mode: host
    environment:
      DEBUG: "0"
      UPSTREAM_DNS_SERVER: "udp:127.0.0.53:53"
      DOH_HTTP_PREFIX: "/resolve"
      DOH_SERVER_LISTEN: "[::1]:8053"
      DOH_SERVER_TIMEOUT: "10"
      DOH_SERVER_TRIES: "3"
      DOH_SERVER_VERBOSE: "false"

However I notice it will turn unhealthy in a few minutes(no traffic/load required):

$ docker ps
CONTAINER ID        IMAGE                  COMMAND                  CREATED             STATUS                      PORTS                                       NAMES
adbab228d04b        satishweb/doh-server   "/docker-entrypoint …"   17 minutes ago      Up 17 minutes (unhealthy)                                               doh-server

I tried DOH_SERVER_VERBOSE: "ture" but there is no extra message at all. Tried on 2 different linux box.

[Feature Request] How to manually set the certs?

I don't have any domain names for now, so I want to run this doh-server with my own self-signed certs for testing, but I can't find anything like --cert /path/to/mycert.cert --key /path/to/myprivkey.key.

Support for DNSSEC

Anyway to add DNSSEC support to unbound for this repo?

Helm Chart Enhancements

• Add unbound DNS server helm chart dependency
• Add security features
• Enhance ingress configuration
• TBA

Create new container image automatically upon new release

Container image creation is manual right now, it should be automatic

1. Setup GitHub workflow for container image creation on creation of the new tag
2. Publish the image to docker.io
3. Publish the image to GHCR

ENV Variable to disable logging

I'd like to be able to disable logging. Is their way to do that currently?

Update to 2.3.5

Hi,

any chance to get an update to the latest version (v2.3.5)? Please!

https://github.com/m13253/dns-over-https/releases/tag/v2.3.5

Thank you.

Peter

Near line 10 (last key parsed 'listen'): expected a comma or array terminator ']', but got ':' instead

For some reason the environment variables are not applied correctly. This is my compose:

version: "3"

services:
  doh-server:
    image: satishweb/doh-server
    environment:
      - UPSTREAM_DNS_SERVER="udp:pihole:53"
      - DOH_HTTP_PREFIX="/dns-query"
      - DOH_SERVER_LISTEN=":8053"

log reports this:

|---------------------------------------------------------------------------------------------
| Starting DNS Over HTTP Service 
| ENTRYPOINT: Loading docker secrets if found...
| ENTRYPOINT: app-config was not available, running given parameters or default CMD...
2022/03/04 16:35:43 Near line 10 (last key parsed 'listen'): expected a comma or array terminator ']', but got ':' instead

and

2022/03/04 16:40:19 Near line 28 (last key parsed ''): expected a top-level item to end with a newline, comment, or EOF, but got '/' instead