marcuoli/codexdns repository overview

⁠CodexDNS — DNS Server with Web Management

A comprehensive DNS server solution with an intuitive web interface, designed for network administrators and self-hosters.

📚 Full documentation: https://docs.codexs.com.br/codexdns/⁠

⁠Quick Start

⁠Basic Setup (HTTP only)

docker run -d \
  --name codexdns \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 53:53/udp \
  -p 53:53/tcp \
  -v codexdns-data:/app/data \
  -v codexdns-config:/app/config \
  -v codexdns-logs:/app/logs \
  -v codexdns-certs:/app/certs \
  marcuoli/codexdns:latest

Access the web UI at: http://localhost:8080⁠

⁠Production Setup (HTTPS + DNS/DHCP/NTP)

docker run -d \
  --name codexdns \
  --restart unless-stopped \
  -p 8080:8080 \
  -p 8443:8443 \
  -p 53:53/udp \
  -p 53:53/tcp \
  -p 853:853/tcp \
  -p 123:123/udp \
  -v codexdns-data:/app/data \
  -v codexdns-config:/app/config \
  -v codexdns-logs:/app/logs \
  -v codexdns-certs:/app/certs \
  -e TZ=America/New_York \
  -e CODEXDNS_ADMIN_PASSWORD=your-strong-admin-password \
  -e CODEXDNS_SESSION_SECRET=$(openssl rand -hex 32) \
  marcuoli/codexdns:latest

⁠Docker Compose

services:
  codexdns:
    image: marcuoli/codexdns:latest
    container_name: codexdns
    restart: unless-stopped
    ports:
      - "8080:8080"    # HTTP Web UI
      - "8443:8443"    # HTTPS Web UI
      - "53:53/udp"    # DNS
      - "53:53/tcp"    # DNS
      - "853:853/tcp"  # DNS-over-TLS
      - "123:123/udp"  # NTP
    volumes:
      - codexdns-data:/app/data
      - codexdns-config:/app/config
      - codexdns-logs:/app/logs
      - codexdns-certs:/app/certs
    environment:
      - TZ=America/New_York
      - CODEXDNS_ADMIN_PASSWORD=your-strong-admin-password
      - CODEXDNS_SESSION_SECRET=replace-with-output-of-openssl-rand-hex-32

volumes:
  codexdns-data:
  codexdns-config:
  codexdns-logs:
  codexdns-certs:

⁠First Login

• Username: admin
• Password: Set via the CODEXDNS_ADMIN_PASSWORD environment variable

⁠Setting the admin password

Option A — provide a password at startup (recommended):

docker run -d \
  --name codexdns \
  -e CODEXDNS_ADMIN_PASSWORD=your-strong-password \
  ...

The password must be at least 12 characters. The admin account is created with this password on first boot; if the account already exists the seed step is skipped.

Option B — auto-generated password (if CODEXDNS_ADMIN_PASSWORD is not set):

CodexDNS generates a strong random 24-character password and prints it once to the startup logs. Retrieve it before the first login:

docker logs codexdns | grep -A1 'CODEXDNS ADMIN PASSWORD'

You will also be prompted to change this password on your first login.

⁠Port Mapping

⁠Volume Mapping

⁠Environment Variables

All CODEXDNS_* variables map directly to config file fields via the CODEXDNS_ prefix (e.g. CODEXDNS_HTTP_PORT overrides http_port). Environment variables always take precedence over values in config.json.

⁠Features

⁠✨ DNS Server

• Authoritative zones (forward & reverse)
• DNS forwarding with per-domain rules
• DNS-over-HTTPS (DoH), DNS-over-TLS (DoT), DNS-over-QUIC (DoQ)
• EDNS0 support
• Per-upstream concurrency caps and circuit breakers

⁠🛡️ Security & Filtering

• Ad blocking and malware protection
• Custom blocklists/whitelists
• Per-client DNS policies
• Safe search enforcement (Google, YouTube, Bing, DuckDuckGo, and more)
• TLS certificate management

⁠🖥️ Web Management

• Modern responsive UI (mobile-friendly)
• Real-time DNS query monitoring
• Statistics and analytics dashboards
• Zone and record management (A, AAAA, CNAME, MX, TXT, PTR, NS, SRV)
• Role-based access control

⁠🔧 Advanced Features

• DHCP integration with dynamic DNS (RFC 2136)
• NTP server with time synchronization
• Client discovery (reverse DNS, NetBIOS, mDNS, LLMNR)
• MAC vendor lookup (OUI database)
• Redis caching support
• Multi-database support (SQLite, PostgreSQL, MySQL)
• Prometheus metrics endpoint
• Structured, per-subsystem log files (HTTP, DNS, DHCP, NTP)
• Goroutine-per-query DNS handling with configurable concurrency caps and singleflight deduplication

⁠⚡ Performance & Concurrency

CodexDNS is built on Go's native concurrency model — lightweight goroutines scheduled by the Go runtime across all available CPU cores. There is no thread pool to size; the runtime automatically parallelises work across every core the container is given.

⁠Independent service goroutines

Each protocol server and background service runs in its own independent goroutine, so a restart of the DNS server (via the web UI or API) never pauses the HTTP/HTTPS interface, and vice versa.

⁠Per-query concurrency

Each incoming DNS query is dispatched to its own goroutine. Two mechanisms prevent overload:

• dns_max_concurrent_queries — configurable hard cap; queries that exceed the limit are dropped gracefully with a counter exposed in the dashboard and Prometheus metrics.
• singleflight deduplication — identical upstream forwarding requests that arrive simultaneously are collapsed into a single round-trip, reducing upstream load and latency spikes under burst traffic.

⁠CPU resource limits and GOMAXPROCS

Go 1.25 is fully cgroup-aware: when you set --cpus (or a cgroup CPU quota) on a container, the runtime reads the quota and automatically caps GOMAXPROCS to match — no extra configuration needed.

# Give CodexDNS 2 vCPUs; GOMAXPROCS will be set to 2 automatically
docker run -d --cpus="2" --name codexdns ...

For single-core environments (e.g. a small home Raspberry Pi) CodexDNS works fine — goroutines that are waiting on I/O (network, disk) yield the CPU automatically, so even one vCPU handles typical home DNS load with headroom to spare.

⁠Sizing recommendations

⁠Configuration

On first start, CodexDNS copies its built-in default configuration to /app/config/config.json if no config file exists. You can then edit it via the web UI or by mounting your own file. For a full list of configuration parameters see the Configuration Reference⁠.

⁠Mount a custom config

docker run -d \
  --name codexdns \
  -v /path/to/config.json:/app/config/config.json \
  -v codexdns-data:/app/data \
  -v codexdns-logs:/app/logs \
  -v codexdns-certs:/app/certs \
  -p 8080:8080 -p 53:53/udp -p 53:53/tcp \
  marcuoli/codexdns:latest

A minimal config.json to get started:

{
  "http_port": "8080",
  "dns_host": "0.0.0.0",
  "dns_port": "53",
  "db_driver": "sqlite",
  "db_dsn": "/app/data/codexdns.db",
  "cache_backend": "memory",
  "log_level": "info",
  "upstream_servers": ["8.8.8.8:53", "1.1.1.1:53"],
  "upstream_strategy": "round-robin"
}

⁠Logs & Troubleshooting

# View logs
docker logs codexdns

# Follow logs in real-time
docker logs -f codexdns

# View container status
docker ps -a | grep codexdns

# Check health endpoint
docker exec codexdns wget -qO- http://localhost:8080/health

# Access logs directory (if mounted)
docker exec codexdns ls -la /app/logs

⁠Documentation

Full documentation is available at https://docs.codexs.com.br/codexdns/⁠

⁠Security Notes

• Set CODEXDNS_ADMIN_PASSWORD to a strong password before first boot; if omitted, a random 24-character password is auto-generated and printed once to the startup log
• Set CODEXDNS_SESSION_SECRET to a unique random string of at least 32 characters; startup will abort in release (production) mode if this is missing, too short, or left as a placeholder — generate one with openssl rand -hex 32
• Use HTTPS in production (mount TLS certificates to /app/certs)
• Restrict network access using firewall rules or Docker networks
• Keep the image updated for security patches

⁠License

MIT License — see https://github.com/marcuoli/codexdns/blob/main/LICENSE⁠

Built with: Go, Gin, GORM, Templ, TailwindCSS, Alpine.js, HTMX
Base image: Alpine Linux 3.19
Architecture: Multi-stage optimized build (~50 MB)