Self-Hosted Service + nginx Reverse Proxy + DuckDNS + Let's Encrypt

Full pattern for exposing a self-hosted Docker service to the internet with SSL when your ISP blocks ports 80/443.

When to use

Setting up any self-hosted service behind nginx with SSL
ISP blocks ports 80/443 (residential connection)
Need HTTPS for mobile app connectivity (Audiobookshelf, Immich, Paperless-ngx, etc.)

Pattern Overview

Internet → Router (port forward) → nginx (SSL) → Docker service (internal port)
                 ↑
          DuckDNS (IP updater)
          Let's Encrypt (DNS challenge, no port 80 needed)

Step 1: DuckDNS Setup

# Create updater script
sudo mkdir -p /opt/duckdns
sudo tee /opt/duckdns/update.sh << 'EOF' > /dev/null
#!/bin/bash
echo url="https://www.duckdns.org/update?domains=<SUBDOMAIN>&token=<TOKEN>&ip=" | curl -k -s -o /opt/duckdns/duck.log -K -
EOF
sudo chmod +x /opt/duckdns/update.sh

# Run once to verify (should return "OK")
sudo /opt/duckdns/update.sh && cat /opt/duckdns/duck.log

# Add cron (every 5 min)
(sudo crontab -l 2>/dev/null | grep -v duckdns; echo "*/5 * * * * /opt/duckdns/update.sh") | sudo crontab -

Verify: dig +short <domain>.duckdns.org should return your public IP.

Step 2: Docker Service Setup

The service must run on a port that doesn't conflict with nginx (which will take 80 and the SSL port). Common pattern: use PORT=<high-port> env var or map -p <external>:<internal>.

Audiobookshelf example:

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    network_mode: host
    environment:
      - PORT=13378
      - TZ=America/New_York
    volumes:
      - ./config:/config
      - ./metadata:/metadata
      - /path/to/audiobooks:/audiobooks:ro

Immich example: Already runs on 2283. Add IMMICH_EXTERNAL_DOMAIN=<domain>:<port> to .env so shared links use the correct URL.

Paperless-ngx example: Map 8010:8000 and set PAPERLESS_URL=https://<domain>:<port>.

Step 3: Let's Encrypt via DNS Challenge

When ports 80/443 are blocked, use DNS-01 challenge:

# Install DuckDNS plugin
sudo pip3 install --break-system-packages certbot-dns-duckdns

# Create credentials file
sudo mkdir -p /etc/letsencrypt
sudo tee /etc/letsencrypt/duckdns.ini << 'EOF' > /dev/null
dns_duckdns_token=<YOUR_DUCK_DNS_TOKEN>
EOF
sudo chmod 600 /etc/letsencrypt/duckdns.ini

# Get certificate
sudo certbot certonly \
  --authenticator dns-duckdns \
  --dns-duckdns-credentials /etc/letsencrypt/duckdns.ini \
  --dns-duckdns-propagation-seconds 30 \
  -d <domain>.duckdns.org \
  --non-interactive --agree-tos --email <your-email>

Cert auto-renews via certbot's systemd timer.

Step 4: nginx Configuration

server {
    listen <PORT> ssl;
    server_name <domain>.duckdns.org;

    ssl_certificate /etc/letsencrypt/live/<domain>.duckdns.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/<domain>.duckdns.org/privkey.pem;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    client_max_body_size 500M;

    location / {
        proxy_pass http://127.0.0.1:<SERVICE_PORT>;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
        proxy_read_timeout 86400;
    }
}

# Optional: redirect HTTP → HTTPS on same port
server {
    listen 80;
    server_name <domain>.duckdns.org;
    return 301 https://$host:<PORT>$request_uri;
}

Deploy:

sudo cp /tmp/<service>-nginx.conf /etc/nginx/sites-available/<service>
sudo ln -sf /etc/nginx/sites-available/<service> /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx

Step 5: Router Port Forwarding (ASUS RT-AX82U)

http://192.168.50.1 → log in
WAN → Port Forwarding tab
Add Profile:
- Service Name: <service>
- Protocol: TCP
- External Port: <PORT>
- Internal IP: 192.168.50.98
- Internal Port: <PORT>
OK → Apply

Port assignments for this server:

Service	External Port	Internal
Audiobookshelf	3443	13378
Immich	3444	2283
Paperless-ngx	3446	8010

Pitfalls

network_mode: host + port conflicts: Audiobookshelf defaults to port 80 internally. Set PORT=<alt> env var to avoid nginx conflict.
Shell token mangling: Plex/Audiobookshelf tokens containing special chars get garbled by bash. Use Python to make HTTP calls instead: urllib.request.urlopen(f"http://localhost:32400/library/sections?X-Plex-Token={token}").
Hairpin NAT: Testing https://<domain>:<port> from within the LAN may fail. Test from cellular data to confirm external access works.
Heimdall uses 8443: If Heimdall runs on the same machine, port 8443 is taken. Use 3443+ range.
Port 8000 is Portainer: Paperless-ngx defaults to 8000 — map to 8010 instead.
Immich needs IMMICH_EXTERNAL_DOMAIN: Without it, shared links use localhost:2283. Set in .env and restart with docker compose up -d (NOT restart).
Paperless-ngx needs PAPERLESS_URL: Same issue — set the full https://<domain>:<port> URL.
Cert name must match domain: The cert is issued for the full DuckDNS domain. All nginx server blocks for different ports on the same domain reuse the same cert files.

5.4 KiB Raw Permalink Blame History