docker-ddns-server/README.md

Dynamic DNS Server for Docker with Web UI written in Go

With docker-ddns-server you can set up your own dynamic DNS server. This project is inspired by https://github.com/dprandzioch/docker-ddns. In addition to the original version, you can setup and maintain your dyndns entries via a simple web UI with comprehensive security features, modern authentication, and threat monitoring.

✨ Key Features

• Web-Based Management - Easy-to-use web interface for managing DNS entries
• Security & IP Blocking - Automatic protection against brute-force attacks
• Modern Authentication - Session-based admin login with HTTPS support
• Security Dashboard - Real-time monitoring of threats and blocked IPs
• Multi-Platform Support - Runs on amd64, arm64, arm (Raspberry Pi compatible)
• Automatic Migration - Handles legacy data with automatic normalization
• Reverse Proxy Ready - Works seamlessly with nginx, Caddy, Traefik
• Threat Intelligence - Comprehensive logging for attack pattern analysis

---

📦 Installation

You can either use the pre-built Docker image or build it yourself.

Using the Docker Image

Docker Hub: https://hub.docker.com/r/w3kllc/ddns

Quick Start:

docker run -it -d \
    -p 8080:8080 \
    -p 53:53 \
    -p 53:53/udp \
    -v /somefolder:/var/cache/bind \
    -v /someotherfolder:/root/database \
    -e DDNS_ADMIN_LOGIN=admin:$$2y$$05$$... \
    -e DDNS_DOMAINS=dyndns.example.com \
    -e DDNS_PARENT_NS=ns.example.com \
    -e DDNS_DEFAULT_TTL=3600 \
    -e DDNS_SESSION_SECRET=your-random-32-char-secret \
    --name=dyndns \
    w3kllc/ddns:latest

Using docker-compose (Recommended)

For a complete setup example, see: docker-compose.yml

Example docker-compose.yml:

version: '3.8'

services:
  ddns:
    image: w3kllc/ddns:latest
    container_name: dyndns
    ports:
      - "8080:8080"
      - "53:53"
      - "53:53/udp"
    volumes:
      - ./bind:/var/cache/bind
      - ./database:/root/database
      - ./static:/app/static  # Optional: for custom logo
    environment:
      # Required
      - DDNS_ADMIN_LOGIN=admin:$$2y$$05$$hashed_password_here
      - DDNS_DOMAINS=dyndns.example.com
      - DDNS_PARENT_NS=ns.example.com
      - DDNS_DEFAULT_TTL=3600
      
      # Security (Recommended)
      - DDNS_SESSION_SECRET=your-random-32-character-secret-key
      
      # Optional
      - DDNS_TITLE=My DynDNS Server
      - DDNS_CLEAR_LOG_INTERVAL=30
      - DDNS_ALLOW_WILDCARD=true
      - DDNS_LOGOUT_URL=https://example.com
      - DDNS_POWERED_BY=ACME Inc
      - DDNS_POWERED_BY_URL=https://acme.inc
    restart: unless-stopped

---

⚙️ Configuration

Environment Variables

Required Variables

DDNS_ADMIN_LOGIN
Admin credentials in htpasswd format for web UI access.

Generate with:

htpasswd -nb username password

For docker-compose.yml (escape dollar signs):

echo $(htpasswd -nb username password) | sed -e s/\\$/\\$\\$/g

If not set, all /@/ routes are accessible without authentication (useful with auth proxy).

DDNS_DOMAINS
Comma-separated list of domains managed by the server.
Example: dyndns.example.com,dyndns.example.org

DDNS_PARENT_NS
Parent nameserver of your domain.
Example: ns.example.com

DDNS_DEFAULT_TTL
Default TTL (Time To Live) for DNS records in seconds.
Example: 3600 (1 hour)

Security Variables (Recommended)

DDNS_SESSION_SECRET
Secret key for session encryption. Should be 32+ random characters.

Generate with:

# Linux/Mac
openssl rand -base64 32

# Or using Python
python3 -c "import secrets; print(secrets.token_urlsafe(32))"

⚠️ Important: Without this variable, sessions won't persist across container restarts.

Optional Variables

DDNS_TITLE
Custom site title displayed in the web UI.
Default: "w3K DynDNS"

DDNS_CLEAR_LOG_INTERVAL
Automatically clear log entries older than specified days.
Example: 30 (keep 30 days of logs)

DDNS_ALLOW_WILDCARD
Enable wildcard DNS resolution (e.g., *.subdomain.dyndns.example.com).
Values: true or false

DDNS_LOGOUT_URL
Redirect to this URL after logout.
Example: https://example.com

DDNS_POWERED_BY
Show this in the footer credits.
Example: ACME Inc

DDNS_POWERED_BY_URL
The URL to ACME Inc.
Example: https:/acme.inc

---

🌐 DNS Setup

If your parent domain is example.com and you want your DynDNS domain to be dyndns.example.com, your DynDNS hosts would be like blog.dyndns.example.com.

Add these entries to your parent DNS server:

dyndns                   IN NS      ns
ns                       IN A       <IPv4 address of your DynDNS server>
ns                       IN AAAA    <IPv6 address of your DynDNS server> (optional)

Example:

dyndns                   IN NS      ns
ns                       IN A       203.0.113.10
ns                       IN AAAA    2001:db8::10

---

🔐 Security Features

IP Blocking & Threat Protection

• Automatic IP Blocking: IPs are blocked after 3 failed authentication attempts within 72 hours
• 7-Day Block Duration: Blocked IPs are automatically unblocked after 7 days
• Failed Authentication Logging: Comprehensive logs including IP, timestamp, username, and password
• Threat Intelligence: Analyze attack patterns and password attempts
• Manual Unblock: Security dashboard allows manual IP unblocking
• Automatic Cleanup: Expired blocks and old logs are cleaned up automatically

Session-Based Authentication

• Modern Login Page: No browser popup dialogs
• Secure Sessions: HttpOnly, Secure, and SameSite cookie attributes
• Remember Me: Optional 30-day session duration
• Proper Logout: Destroys sessions completely
• HTTPS Enforcement: Automatic redirect to HTTPS when available
• Reverse Proxy Support: Detects SSL via X-Forwarded-Proto headers

Security Dashboard

Access the security dashboard at /@/security to:

• Monitor blocked IPs and active threats
• Review failed authentication attempts
• Analyze password patterns in attack attempts
• Manually unblock IP addresses
• View statistics and historical data

Password Logging Rationale:
This is a single-user system where the admin is the only legitimate user. All other login attempts are malicious by definition. Password logging enables threat intelligence analysis to determine if attackers are getting close to your actual password. Ensure your database volume is properly secured.

---

🖥️ Admin Panel Access

The admin panel is accessible at /@/ (not /admin/ - more unique, less common).

Main Features

• 🏠 Dashboard (/@/) - Overview and quick access
• 📝 Hosts (/@/hosts) - Manage DNS hosts with automatic lowercase migration
• 🔗 CNAMEs (/@/cnames) - Manage CNAME records
• 📊 Logs (/@/logs) - View update history
• 🔒 Security (/@/security) - Monitor threats and blocked IPs
• ⏏️ Logout (/@/logout) - End session securely

Authentication Flow

1. Navigate to /@/ (or any admin route)
2. Redirected to /@/login if not authenticated
3. Enter admin credentials
4. Optionally check "Remember Me" for 30-day session
5. Access admin panel
6. Click logout icon (⏏️) when done

HTTPS Detection:
If running behind a reverse proxy with SSL, the system automatically detects HTTPS and enforces it for the admin panel while keeping API endpoints accessible via HTTP for device compatibility.

---

🔄 Updating DNS Entries

After adding a host via the web UI, configure your router or device to update its IP address.

Update URLs

The server accepts updates on multiple endpoints:

• /update
• /nic/update
• /v2/update
• /v3/update

With IP Address Specified

http://dyndns.example.com:8080/update?hostname=blog.dyndns.example.com&myip=1.2.3.4

Or with authentication in URL:

http://username:password@dyndns.example.com:8080/update?hostname=blog.dyndns.example.com&myip=1.2.3.4

Without IP Address (Auto-detect)

If your router/device doesn't support sending the IP address (e.g., OpenWRT), omit the myip parameter:

http://dyndns.example.com:8080/update?hostname=blog.dyndns.example.com

Or with authentication:

http://username:password@dyndns.example.com:8080/update?hostname=blog.dyndns.example.com

The server will automatically use the client's IP address from the request.

Authentication

API endpoints use HTTP Basic Authentication with the username and password you set for each host in the web UI (not the admin credentials).

Important:

• Admin credentials (DDNS_ADMIN_LOGIN) - For web UI access at /@/
• Host credentials - For API updates, set per-host in the web UI

---

🎨 UI/UX Features

Automatic Logo Detection

Place a logo file in the static directory to automatically display it:

Supported formats:

• static/icons/logo.png
• static/icons/logo.webp
• static/icons/logo.svg

If no logo is found, the system displays the text title (DDNS_TITLE).

Docker volume mount for custom logo:

volumes:
  - ./static:/app/static

Then place your logo at: ./static/icons/logo.png

Visual Improvements

• Sticky Header: Navigation remains visible while scrolling
• Unicode Icons: 🏠 Dashboard, 🔒 Security, ⏏️ Logout (with tooltips)
• Modern Design: Clean, professional interface
• HTTPS Indicator: Visual confirmation of secure connection on login page
• Password Controls: Hide/reveal functionality with confirmation prompts
• Responsive Layout: Works on desktop, tablet, and mobile

---

🔧 Data Management

Automatic Hostname Normalization

All usernames and hostnames are automatically converted to lowercase to prevent case-sensitivity issues:

• Database storage is always lowercase
• Lookups are case-insensitive
• Prevents duplicate entries with different cases

Legacy Data Migration

When accessing /@/hosts for the first time, the system automatically migrates any uppercase entries:

• Converts hostnames to lowercase
• Handles conflicts by appending numbers (e.g., host-1, host-2)
• Displays migration report in the UI
• One-time process, status persisted in database
• Non-destructive, preserves all host data

Username Flexibility

• Non-Unique Usernames: Multiple hosts can share the same username
• Enables flexible credential management strategies
• Each host can have the same or different password

Validation Rules

• Hostnames: Minimum 1 character (allows single-letter subdomains)
• Usernames: Minimum 1 character
• Passwords: Minimum 6 characters

---

🔀 Reverse Proxy Configuration

The application intelligently detects HTTPS availability and adjusts behavior accordingly.

HTTPS Detection Methods

1. Direct TLS connection (request.TLS)
2. X-Forwarded-Proto header
3. X-Forwarded-Ssl header
4. X-Url-Scheme header

Behavior

Admin Panel (/@/*):

• Auto-redirects to HTTPS when available
• Graceful HTTP fallback if HTTPS unavailable
• Session cookies use Secure flag with HTTPS

API Endpoints (/update, /nic/update, etc.):

• Always accept HTTP connections
• No forced HTTPS redirect (device compatibility)
• Works with devices that don't support HTTPS

Example Nginx Configuration

server {
    listen 443 ssl;
    server_name dyndns.example.com;

    ssl_certificate /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # Recommended SSL settings
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    ssl_prefer_server_ciphers on;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

# Optional: HTTP to HTTPS redirect
server {
    listen 80;
    server_name dyndns.example.com;
    return 301 https://$server_name$request_uri;
}

Example Caddy Configuration

dyndns.example.com {
    reverse_proxy localhost:8080
}

Caddy automatically handles SSL certificates and sets appropriate headers.

---

🐳 Multi-Platform Docker Support

Automated Builds

Docker images are automatically built via GitHub Actions for multiple platforms:

Supported Platforms:

• linux/amd64 - Intel/AMD 64-bit (standard servers, PCs)
• linux/386 - Intel/AMD 32-bit (older systems)
• linux/arm/v7 - ARM 32-bit (Raspberry Pi 2/3, older ARM devices)
• linux/arm64 - ARM 64-bit (Raspberry Pi 4+, modern ARM servers)

Version Tags

Docker images are tagged using semantic versioning:

:latest - Always points to the most recent stable build

:vX.Y.Z - Semantic version tags (e.g., :v1.2.3)

• Version from commit message (if commit starts with vX.Y.Z)
• OR auto-incremented from last git tag
• OR date-based tag if no version tags exist

Example:

# Pull latest version
docker pull w3kllc/ddns:latest

# Pull specific version
docker pull w3kllc/ddns:v1.2.3

# Pull specific platform
docker pull --platform linux/arm64 w3kllc/ddns:latest

Versioning Strategy

The build system automatically determines version tags using this priority order:

1. Commit Message Version (Highest Priority): If your commit message title starts with vX.Y.Z (e.g., v1.2.3), that exact version is used
2. Auto-Increment from Last Tag: If no version in commit message, finds the latest git tag and increments the patch version (e.g., v1.2.3 → v1.2.4)
3. Date-Based Fallback: If no git tags exist at all, uses timestamp format vYY.MM.DD-HHMM (e.g., v25.10.11-1430)

Example commit messages:

# Explicit version (workflow extracts "v1.3.0" from start of commit message)
git commit -m "v1.3.0 Add new security features"

# Auto-increment (no version found, so increments last tag: v1.2.3 → v1.2.4)
git commit -m "Fix bug in authentication"

# Date-based (no tags exist yet, uses timestamp: v25.10.11-1430)
git commit -m "Initial release"

How version extraction works:

• Workflow searches for pattern vX.Y.Z or vX.Y at the start of commit message
• Must begin with v followed by numbers and dots
• Examples that work: v1.0.0, v2.1.3, v1.2
• Examples that won't work: version 1.0.0 (missing v), Release v1.0.0 (doesn't start with v)

GitHub Releases

Each build automatically creates a GitHub release with:

• Version tag
• Docker image reference
• Commit message as release notes
• Source code archives (zip and tar.gz)

---

🚀 Migration from Original Project

If migrating from dprandzioch/docker-ddns or older versions of this fork:

Before Migration

1. Backup your data:

   docker cp dyndns:/root/database ./backup-database
   docker cp dyndns:/var/cache/bind ./backup-bind
   

2. Note your current configuration (environment variables)

Breaking Changes

1. Admin Panel URL: Changed from /admin to /@/

   • Update bookmarks and links
   • Use /@/login for login page

2. Authentication Method: Admin panel now uses sessions

   • Add DDNS_SESSION_SECRET environment variable
   • Login via web form instead of browser popup

3. New Recommended Variable: DDNS_SESSION_SECRET

   • Required for session persistence
   • Generate: openssl rand -base64 32

Migration Steps

1. Update docker-compose.yml or docker command with new variables
2. Add DDNS_SESSION_SECRET to environment
3. Update bookmarks from /admin to /@/
4. Restart container with new configuration
5. Visit /@/hosts to trigger automatic data migration
6. Review security dashboard for any blocked IPs

Backward Compatibility

✅ Fully Compatible:

• DynDNS API endpoints unchanged
• HTTP Basic Auth still works for device updates
• Existing host configurations work without changes
• Database schema additions are non-breaking
• All original functionality preserved

⚠️ Manual Update Required:

• Bookmark/link updates for admin panel
• Addition of session secret (recommended)

---

🔍 Troubleshooting

Login Issues

Problem: Login redirects back to login page
Solution: Ensure DDNS_SESSION_SECRET is set. Without it, sessions won't persist.

Problem: Can't remember admin password
Solution: Regenerate password with htpasswd -nb username newpassword and update DDNS_ADMIN_LOGIN

HTTPS Issues

Problem: HTTPS redirect loop
Solution: Verify reverse proxy sends X-Forwarded-Proto: https header

Problem: "Not Secure" warning
Solution: Check SSL certificate configuration in your reverse proxy

IP Blocking

Problem: Locked out after failed login attempts
Solution:

• Wait 7 days for automatic unblock
• OR manually remove from blocked_ips table in database
• OR access database with SQLite: DELETE FROM blocked_ips WHERE ip_address='YOUR_IP';

API Updates

Problem: Device updates not working
Solution:

• API uses host credentials (from web UI), not admin credentials
• Check username/password for specific host in /@/hosts
• Verify device is sending correct Basic Auth headers

Problem: "nochg" response from server
Solution: IP address hasn't changed, this is normal behavior

Build Issues

Problem: missing go.sum entry for gorilla/sessions
Solution:

go get github.com/gorilla/sessions@v1.2.2
go mod tidy

Database Issues

Problem: Database locked errors
Solution: Ensure only one container instance is running

Problem: Lost all data after update
Solution: Check volume mounts are correct in docker-compose.yml

---

🛡️ Security Best Practices

1. Always Set Session Secret
   Generate a strong random secret: openssl rand -base64 32

2. Use HTTPS with Reverse Proxy
   Never expose the admin panel over plain HTTP in production

3. Secure Database Volume
   Set appropriate file permissions:

   chmod 700 /path/to/database
   

4. Regular Updates
   Keep Docker image updated: docker pull w3kllc/ddns:latest

5. Monitor Security Dashboard
   Check /@/security regularly for attack patterns

6. Strong Admin Password
   Use a password manager to generate and store strong credentials

7. Separate Credentials
   Use different passwords for admin and each host

8. Firewall Configuration
   Limit access to web UI (port 8080) to trusted networks if possible

9. Database Backups
   Regularly backup the database volume

10. Password Logging Awareness
    Remember that failed auth logs include passwords - secure your database

---

📚 API Reference

Update Endpoints

All endpoints accept the same parameters:

Endpoints:

• GET /update
• GET /nic/update
• GET /v2/update
• GET /v3/update

Parameters:

• hostname (required) - Fully qualified domain name to update
• myip (optional) - IP address to set (auto-detected if omitted)

Authentication:

• HTTP Basic Auth using host credentials (username/password from web UI)

Response Codes:

• good <IP> - Update successful
• nochg <IP> - IP address hasn't changed
• badauth - Authentication failed
• notfqdn - Hostname is not a valid FQDN
• nohost - Hostname doesn't exist
• abuse - IP address has been blocked

Example:

curl -u username:password \
  "http://dyndns.example.com:8080/update?hostname=test.dyndns.example.com&myip=1.2.3.4"

---

🤝 Contributing

Contributions are welcome! Whether it's bug fixes, new features, documentation improvements, or reporting issues.

How to Contribute

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Test thoroughly
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to your fork (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Setup

# Clone the repository
git clone https://github.com/w3K-one/docker-ddns-server.git
cd docker-ddns-server

# Build the application
cd dyndns
go build

# Run tests (if available)
go test ./...

# Build Docker image locally
cd ..
docker build -t ddns:dev -f deployment/Dockerfile .

Code Style

• Follow Go conventions and best practices
• Use gofmt for code formatting
• Add comments for complex logic
• Write meaningful commit messages

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🙏 Credits

Original Project:
dprandzioch/docker-ddns - Original DynDNS server implementation

Web UI Fork:
benjaminbear/docker-ddns-server - Added web UI for management

Enhanced Fork:
w3K-one/docker-ddns-server - Security features, modern auth, multi-platform support

Major Enhancements in This Fork

• 🔒 IP blocking and threat protection system
• 🔐 Session-based authentication with modern login
• 📊 Security dashboard for monitoring attacks
• 🌐 HTTPS enforcement with reverse proxy support
• 🎨 Enhanced UI/UX with logo support and sticky header
• 📦 Multi-platform Docker builds (amd64, arm64, arm, 386)
• 🔄 Automatic data migration and normalization
• 📝 Comprehensive documentation
• 🤖 Automated CI/CD with GitHub Actions
• 🏷️ Semantic versioning with automatic releases

---

💬 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Docker Hub: w3kllc/ddns

---

🗺️ Roadmap

Potential future enhancements:

• Email notifications for security events
• Two-factor authentication (2FA)
• API rate limiting
• Web-based configuration wizard
• DNS over HTTPS (DoH) support
• Prometheus metrics export
• Docker Swarm / Kubernetes support
• Advanced search and filtering in logs
• Bulk host management

Have an idea? Open an issue or start a discussion!

---

Made with ❤️ by the community