EZ-Homelab/docs/service-docs/duckdns.md

DuckDNS - Dynamic DNS Service

Table of Contents

• Overview
• What is DuckDNS?
• Why Use DuckDNS?
• How It Works
• Configuration in AI-Homelab
• Official Resources
• Educational Resources
• Docker Configuration
• Troubleshooting

Overview

Category: Core Infrastructure
Docker Image: linuxserver/duckdns
Default Stack: core (deployed on core server only)
Web UI: No web interface (runs silently)
Authentication: Not applicable

Multi-Server Note: DuckDNS runs only on the core server where Traefik generates the wildcard SSL certificate. This single certificate is used for all services across all servers in your homelab.

What is DuckDNS?

DuckDNS is a free dynamic DNS (DDNS) service that provides you with a memorable subdomain under duckdns.org and keeps it updated with your current IP address. It's perfect for homelabs where your ISP provides a dynamic IP address that changes periodically.

Key Features

• Free subdomain under duckdns.org
• Automatic IP updates every 5 minutes
• No account required - simple token-based authentication
• IPv4 and IPv6 support
• No ads or tracking
• Works with Let's Encrypt for SSL certificates

Why Use DuckDNS?

1. Access Your Homelab Remotely: Use a memorable domain name instead of remembering IP addresses
2. SSL Certificates: Required for Let's Encrypt to issue SSL certificates for your domain
3. Dynamic IP Handling: Automatically updates when your ISP changes your IP
4. Free and Simple: No credit card, no complex setup
5. Homelab Standard: One of the most popular DDNS services in the homelab community

How It Works

Your Home Network → Router (Dynamic IP) → Internet
                         ↓
                    DuckDNS Updates
                         ↓
                yourdomain.duckdns.org → Current IP

1. You create a subdomain at DuckDNS.org (e.g., myhomelab.duckdns.org)
2. DuckDNS gives you a token
3. The Docker container periodically sends updates to DuckDNS with your current public IP
4. When someone visits myhomelab.duckdns.org, they're directed to your current IP
5. Traefik uses this domain to request SSL certificates from Let's Encrypt

Configuration in AI-Homelab

Environment Variables

DOMAIN=yourdomain.duckdns.org
DUCKDNS_TOKEN=your-token-from-duckdns
DUCKDNS_SUBDOMAINS=yourdomain  # Without .duckdns.org

Setup Steps

1. Sign up at DuckDNS.org:

   • Visit https://www.duckdns.org
   • Sign in with GitHub, Google, Reddit, or Twitter
   • No registration form needed

2. Create your subdomain:

   • Enter desired name (e.g., myhomelab)
   • Click "Add domain"
   • Copy your token (shown at top of page)

3. Configure in .env file:

   DOMAIN=myhomelab.duckdns.org
   DUCKDNS_TOKEN=paste-your-token-here
   DUCKDNS_SUBDOMAINS=myhomelab
   

4. Deploy with core stack:

   cd /opt/stacks/core
   docker compose up -d duckdns
   

Verification

Check if DuckDNS is updating correctly:

# Check container logs
docker logs duckdns

# Verify your domain resolves
nslookup yourdomain.duckdns.org

# Check current IP
curl https://www.duckdns.org/update?domains=yourdomain&token=your-token&verbose=true

Official Resources

• Website: https://www.duckdns.org
• Install Page: https://www.duckdns.org/install.jsp
• FAQ: https://www.duckdns.org/faqs.jsp
• Docker Hub: https://hub.docker.com/r/linuxserver/duckdns
• LinuxServer.io Docs: https://docs.linuxserver.io/images/docker-duckdns

Educational Resources

Videos

• What is Dynamic DNS? (NetworkChuck) - Great overview of DDNS concepts
• DuckDNS Setup Tutorial (Techno Tim) - Practical setup guide
• Home Lab Beginners Guide - DuckDNS

Articles & Guides

• DuckDNS Official Documentation
• Self-Hosting Guide: Dynamic DNS
• LinuxServer.io DuckDNS Documentation

Related Concepts

• Dynamic DNS (DDNS): A service that maps a domain name to a changing IP address
• Public IP vs Private IP: Your router's public-facing IP vs internal network IPs
• DNS Propagation: Time it takes for DNS changes to spread across the internet
• A Record: DNS record type that maps domain to IPv4 address
• AAAA Record: DNS record type that maps domain to IPv6 address

Docker Configuration

Container Details

duckdns:
  image: lscr.io/linuxserver/duckdns:latest
  container_name: duckdns
  restart: unless-stopped
  environment:
    - PUID=${PUID:-1000}
    - PGID=${PGID:-1000}
    - TZ=${TZ}
    - SUBDOMAINS=${DUCKDNS_SUBDOMAINS}
    - TOKEN=${DUCKDNS_TOKEN}
    - UPDATE_IP=ipv4
  volumes:
    - /opt/stacks/core/duckdns:/config

Update Frequency

The DuckDNS container updates your IP every 5 minutes by default. This is frequent enough for most use cases.

Resource Usage

• CPU: Minimal (~0.1%)
• RAM: ~10MB
• Disk: Negligible
• Network: Tiny API calls every 5 minutes

Troubleshooting

Domain Not Resolving

# Check if DuckDNS is updating
docker logs duckdns

# Manually check current status
curl "https://www.duckdns.org/update?domains=yourdomain&token=your-token&verbose=true"

# Expected response: OK or KO (with details)

Wrong IP Being Updated

# Check what IP DuckDNS sees
curl https://www.duckdns.org/update?domains=yourdomain&token=your-token&ip=&verbose=true

# Check your actual public IP
curl ifconfig.me

# If different, check router port forwarding

Token Issues

• Invalid Token: Regenerate token at DuckDNS.org
• Token Not Working: Check for extra spaces in .env file
• Multiple Domains: Separate with commas: domain1,domain2

Let's Encrypt Issues

If SSL certificates fail:

1. Verify DuckDNS is updating correctly
2. Check domain propagation: nslookup yourdomain.duckdns.org
3. Ensure ports 80 and 443 are forwarded to your server
4. Wait 10-15 minutes for DNS propagation

Integration with Other Services

Traefik

Traefik uses your DuckDNS domain for:

• Generating SSL certificates via Let's Encrypt
• Routing incoming HTTPS traffic to services
• Creating service-specific subdomains (e.g., plex.yourdomain.duckdns.org)

Let's Encrypt

Let's Encrypt requires:

1. A publicly accessible domain (provided by DuckDNS)
2. DNS validation or HTTP challenge
3. Ports 80/443 accessible from the internet

Port Forwarding

On your router, forward these ports to your server:

• Port 80 (HTTP) → Your Server IP
• Port 443 (HTTPS) → Your Server IP

Alternatives to DuckDNS

• No-IP: Similar free DDNS service (requires monthly confirmation)
• FreeDNS: Another free option
• Cloudflare: Requires owning a domain, but adds CDN benefits
• Custom Domain + Cloudflare: More professional but requires purchasing domain

Best Practices

1. Keep Your Token Secret: Don't share or commit to public repositories
2. Use One Domain: Multiple domains complicate SSL certificates
3. Monitor Logs: Occasionally check logs to ensure updates are working
4. Router Backup: Save your router config in case you need to reconfigure port forwarding
5. Alternative DDNS: Consider having a backup DDNS service

Summary

DuckDNS is the foundational service that makes your homelab accessible from the internet. It provides:

• A memorable domain name for your homelab
• Automatic IP updates when your ISP changes your address
• Integration with Let's Encrypt for SSL certificates
• Simple, free, and reliable service

Without DuckDNS (or similar DDNS), you would need to use your IP address directly and manually update SSL certificates - making remote access and HTTPS much more difficult.