DNS over HTTPS

Running an own DNS over HTTPS (DoH) server seems to be not so common. Even when the technology gets more and more traction. Chromium/-e as well as Firefox have implemented it in their browser and run requests to major DNS providers like Google or Cloudflare.

In order to liberate and democratize the usage of DoH this container image provides the base to run a setup along with any recursive DNS server you like.

The example docker-compose runs along with secns' unbound that provides DNSSec validation.

The project itself is based on m13253's work providing a DoH-proxy in golang.

Usage

The current example requires you to have a HTTPS reverse-proxy running.

git clone https://git.shivering-isles.com/container-library/dns-over-https.git
cd dns-over-https
docker-compose up -d

This will download and setup the mentioned unbound DNS server along with the proxy, which will be exposed on 127.0.0.1:8053.

To test that it's working run: curl 'http://127.0.0.1:8053/dns-query?name=shivering-isles.com&type=A'

Or curl 'http://127.0.0.1:8053/dns-query?name=shivering-isles.com&type=A' | jq when you prefer a beautified output.

Setup a reverse proxy that takes care of HTTPS and you can set it up on your browser 🎉

As alternative for enterprise setups, you can provide a policy.json looking like this:

{
  "policies": {
    "DNSOverHTTPS": {
      "Enabled": true,
      "ProviderURL": "https://<your dns host>/dns-query"
    }
  }
}

Don't forget to replace <your dns host> with an appropriated value. For example: dns.shivering-isles.com

Healthcheck

The image contains a health check to make sure no defect container is running. This health check points by default to ci-test.dns.shivering-isles.com which is also used for CI in this repository. The domain returns the IP address 127.0.0.123 as A record.

You can configure an own domain using the DOH_HEALTHCHECK_DOMAIN environment variable. But make sure this domain returns the mentioned 127.0.0.123 as A record.