Complete guide to configure Windows 11 to use DNS-over-HTTPS (DoH) with token-based authentication using Docker Desktop.
🪟 Windows 11 • 22H2+ 🐳 Docker Desktop ✅ Verified • Working 🔒 DoH • Token AuthOur DNSaaS service uses DNS-over-HTTPS (DoH) with token-based authentication for maximum privacy and security. This guide will help you configure Windows 11 using Docker Desktop to run the DNS proxy.
| Service | Endpoint | Authentication |
|---|---|---|
| Primary DNS | https://dns1.oss.co.za/xxxxx |
Token in URL path |
| Protocol | DNS-over-HTTPS (DoH) • Port 443 • TLS 1.3 | |
| Container | bwmoran/https-dns-proxy listening on 0.0.0.0:5053 |
|
| Fallback | ✅ 1.1.1.1 • ✅ 8.8.8.8 (if service unreachable) | |
token_xxxxxxxxxx (provided by DNSaaS administrator)token_xxxxxxxxxx. Keep it secure!
If you don't have Docker Desktop installed, follow these steps.
Visit https://www.docker.com/products/docker-desktop and download Docker Desktop for Windows.
Run the installer and follow the prompts. Make sure to enable WSL 2 when prompted for better performance.
Launch Docker Desktop from the Start menu. Wait for the status to show "Running" in the bottom-left corner.
The quickest way to get started. Copy and paste this command in PowerShell to run the DNS proxy in a Docker container.
bwmoran/https-dns-proxy Docker imageRight-click the Start menu → select Terminal (Admin) or PowerShell (Admin).
Replace token_testclient123 with your actual token:
token_testclient123 with your actual token-e RESOLVER_URL and -e DNS_SERVERS) - this image does NOT support -r or -b command-line arguments-vvv flag enables verbose logging (optional)nslookup google.com returns IP addressesnslookup adult.filterdns.net returns Non-existent domaindocker ps shows the container as UpNow configure Windows to use the DNS proxy running in Docker.
The DNS proxy runs in a Docker container and is accessible at 127.0.0.1 (localhost).
Right-click the Network icon in the system tray → select Network and Internet settings.
Alternatively, go to Settings → Network & internet.
Click Ethernet (for wired) or Wi-Fi (for wireless), then click the name of your active network connection.
Scroll to the DNS server assignment section → click Edit.
Change from Automatic (DHCP) to Manual → toggle IPv4 to ON.
In the Preferred DNS field, enter 127.0.0.1.
In the Alternate DNS field, enter 1.1.1.1 as a fallback.
127.0.0.1 (Docker container)1.1.1.1 (fallback)Click Save to apply the changes.
Open PowerShell and run:
Check that the server field shows localhost or 127.0.0.1.
Easily start, stop, or check the status of your DNS proxy in Docker.
| Action | Command |
|---|---|
| Start | docker start https-dns-proxy |
| Stop | docker stop https-dns-proxy |
| Restart | docker restart https-dns-proxy |
| Check status | docker ps --filter name=https-dns-proxy |
| View logs | docker logs https-dns-proxy -f |
| Remove container | docker rm -f https-dns-proxy |
Use these commands to verify your Windows configuration is working correctly.
| Test | Command | Expected Result |
|---|---|---|
| Basic Resolution | nslookup google.com |
Returns IP address(es) |
| Blocking | nslookup adult.filterdns.net |
Returns Non-existent domain |
| MX Record | nslookup -type=MX gmail.com |
Returns mail servers |
| DNS Server Check | ipconfig /all | findstr DNS |
Shows 127.0.0.1 as DNS server |
| Test Domain | Expected Result |
|---|---|
https://example.com |
✅ Should load normally |
http://zycdjz.com |
❌ Should show "This site can't be reached" |
http://adult.filterdns.net |
❌ Should show "This site can't be reached" |
docker logs https-dns-proxy-e RESOLVER_URL=... not -r ...netstat -ano | findstr :53docker pscurl -sk https://dns1.oss.co.za/testclient123docker logs https-dns-proxy127.0.0.1--restart unless-stopped which should restart itdocker versionTo revert to your previous DNS settings:
Go to Settings → Network & internet → select your network → Edit DNS assignment.
Change from Manual back to Automatic (DHCP).
Open PowerShell as Administrator and run:
https://dns1.oss.co.za/xxxxx127.0.0.1:53 (mapped from container port 5053)