TrafegoDNS

<div align="center"> <img src="https://raw.githubusercontent.com/elmerfds/TrafegoDNS/main/logo/logo.png" alt="TrafegoDNS Logo" width="200" height="200"> </div>

A service that automatically manages DNS records based on container configuration. Supports both Traefik integration and direct Docker container label mode, making it compatible with any web server or reverse proxy solution.

Table of Contents

• Features
• Operation Modes
• Supported DNS Providers
• Supported Architectures
• Container Registries
• Quick Start
• DNS Provider Configuration
  • Cloudflare
  • DigitalOcean
  • Route53
• User/Group Permissions
• Service Labels
  • Basic Labels
  • Provider-Specific Labels
  • Type-Specific Labels
• Label Precedence
• Provider-Specific TTL Requirements
• Usage Examples
• Environment Variables
• Automated Cleanup of Orphaned Records
  • Preserving Specific DNS Records
• Manual Hostname Management
• DNS Record Tracking
• Configuration Storage
• DNS Management Modes
• Logging System
• Performance Optimisation
• Automatic Apex Domain Handling
• Using Docker Secrets
• Building from Source
• Development
• Licence

Features

• 🔄 Automatic DNS record management based on container configuration
• 🔀 Support for both Traefik integration and direct container label mode (works with NGINX, Apache, etc.)
• 👀 Real-time monitoring of Docker container events
• 🏷️ Support for multiple DNS record types (A, AAAA, CNAME, MX, TXT, SRV, CAA)
• 🌐 Automatic public IP detection for apex domains
• 🎛️ Fine-grained control with service-specific labels
• 💪 Fault-tolerant design with retry mechanisms
• 🧹 Optional cleanup of orphaned DNS records with preservation capabilities
• 📊 Optimised performance with DNS caching and batch processing
• 🖨️ Configurable logging levels for better troubleshooting
• 🔌 Multi-provider support with provider-agnostic label system
• 🔒 Preserves manually created DNS records using smart tracking system
• 🛡️ Support for explicitly preserving specific hostnames from cleanup
• 📝 Manual creation and management of hostnames independent of containers
• 🔐 PUID/PGID support for proper file permissions
• 💾 Persistent configuration storage in mounted volumes

Operation Modes

TrafegoDNS supports two operation modes:

Traefik Mode (Default)

In this mode, TrafegoDNS monitors the Traefik API to detect hostnames from router rules.

environment:
  - OPERATION_MODE=traefik
  - TRAEFIK_API_URL=http://traefik:8080/api

With Traefik mode, you define hostnames using standard Traefik Host rules:

services:
  my-app:
    image: my-image
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.my-app.rule=Host(`app.example.com`)"
      - "dns.proxied=false"  # Configure DNS settings

Direct Mode

In this mode, TrafegoDNS operates independently of Traefik, directly reading hostnames from container labels. This allows it to run completely independently of any web server or reverse proxy, making it compatible with NGINX, Apache, HAProxy, or any other solution - or even with containers that don't use a reverse proxy at all. The only requirement is that services are deployed as Docker containers.

environment:
  - OPERATION_MODE=direct

When using direct mode, you can specify hostnames using any of the following label formats:

1. Comma-separated hostnames:

   services:
     my-app:
       image: my-image
       labels:
         - "dns.hostname=app.example.com,api.example.com"
         - "dns.proxied=false"  # Configure DNS settings
   

2. Domain and subdomain combination:

   services:
     my-app:
       image: my-image
       labels:
         - "dns.domain=example.com"
         - "dns.subdomain=app,api,admin"
         - "dns.proxied=false"  # Configure DNS settings
   

3. Use apex domain:

   services:
     my-app:
       image: my-image
       labels:
         - "dns.domain=example.com"
         - "dns.use_apex=true"
         - "dns.proxied=false"  # Configure DNS settings
   

4. Individual host labels:

   services:
     my-app:
       image: my-image
       labels:
         - "dns.host.1=app.example.com"
         - "dns.host.2=api.example.com"
         - "dns.proxied=false"  # Configure DNS settings
   

All other DNS configuration labels work the same way as in Traefik mode.

Supported DNS Providers

| Provider | Status | Implementation Details | |:--------:|:------:|:----------------------:| | | | Full support for all record types and features | | | | Full support for all record types and features | | | | Full support for all record types and features |

Supported Architectures

TrafegoDNS supports multiple architectures with multi-arch Docker images:

• amd64: Standard 64-bit PCs and servers
• arm64: 64-bit ARM devices (Raspberry Pi 4/5, newer ARM servers)
• armv7: 32-bit ARM devices (Raspberry Pi 3 and older)

Docker will automatically select the appropriate architecture when you pull the image.

Container Registries

TrafegoDNS images are available from both Docker Hub and GitHub Container Registry.

Both registries receive simultaneous updates and are functionally identical. The GitHub Container Registry offers an alternative if you experience rate limiting or availability issues with Docker Hub.

Docker Hub

image: eafxx/trafegodns:latest

GitHub Container Registry

image: ghcr.io/elmerfds/trafegodns:latest

Quick Start

Docker Compose

version: '3'

services:
  trafegodns:
    image: eafxx/trafegodns:latest
    container_name: trafegodns
    restart: unless-stopped
    environment:
      # User/Group Permissions (optional)
      - PUID=1000                # User ID to run as
      - PGID=1000                # Group ID to run as
      
      # Operation mode
      - OPERATION_MODE=traefik  # Options: traefik, direct
      
      # DNS Provider (choose one)
      - DNS_PROVIDER=cloudflare  # Options: cloudflare, digitalocean, route53
      
      # Cloudflare settings (if using Cloudflare)
      - CLOUDFLARE_TOKEN=your_cloudflare_api_token
      - CLOUDFLARE_ZONE=example.com
      
      # DigitalOcean settings (if using DigitalOcean)
      - DO_TOKEN=your_digitalocean_api_token
      - DO_DOMAIN=example.com
      
      # Route53 settings (if using Route53)
      - ROUTE53_ACCESS_KEY=your_aws_access_key
      - ROUTE53_SECRET_KEY=your_aws_secret_key
      - ROUTE53_ZONE=example.com
      # - ROUTE53_ZONE_ID=Z1234567890ABC  # Alternative to ROUTE53_ZONE
      # - ROUTE53_REGION=eu-west-2  # Optional, defaults to eu-west-2 (London)
      
      # Traefik API settings (for traefik mode)
      - TRAEFIK_API_URL=http://traefik:8080/api
      - LOG_LEVEL=INFO
      
      # DNS record management
      - CLEANUP_ORPHANED=true  # Set to true to automatically remove DNS records when containers are removed
      - PRESERVED_HOSTNAMES=static.example.com,api.example.com,*.admin.example.com  # Hostnames to preserve (even when orphaned)
      - MANAGED_HOSTNAMES=blog.example.com:A:192.168.1.10:3600:false,mail.example.com:MX:mail.example.com:3600:false  # Manually managed hostnames
      
      # API and network timeout settings
      - API_TIMEOUT=60000  # API request timeout in milliseconds (60 seconds)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./config:/config   # Persistent configuration storage
    networks:
      - traefik-network

Using Direct Mode Example

version: '3'

services:
  trafegodns:
    image: eafxx/trafegodns:latest
    container_name: trafegodns
    restart: unless-stopped
    environment:
      # User/Group Permissions (optional)
      - PUID=1000                # User ID to run as
      - PGID=1000                # Group ID to run as
      
      # Operation mode - direct doesn't need Traefik
      - OPERATION_MODE=direct
      
      # DNS Provider
      - DNS_PROVIDER=cloudflare
      - CLOUDFLARE_TOKEN=your_cloudflare_api_token
      - CLOUDFLARE_ZONE=example.com
      
      # Application settings
      - LOG_LEVEL=INFO
      - CLEANUP_ORPHANED=true
      
      # API and network timeout settings
      - API_TIMEOUT=60000  # API request timeout in milliseconds (60 seconds)
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./config:/config   # Persistent configuration storage

  example-app:
    image: nginx
    labels:
      # Direct mode hostname definition
      - "dns.hostname=app.example.com"
      # DNS configuration
      - "dns.type=A"  # A record instead of default CNAME
      - "dns.proxied=false"  # Disable Cloudflare proxy

DNS P