--- name: audiobookshelf-setup description: Deploy Audiobookshelf on a self-hosted Linux server — Docker setup, reverse proxy with nginx + Let's Encrypt, DuckDNS for dynamic DNS, and DNS challenge for SSL when ISP blocks ports 80/443. version: 1.0.0 author: Hermes Agent license: MIT platforms: [linux] metadata: hermes: tags: [audiobookshelf, docker, nginx, lets-encrypt, duckdns, reverse-proxy, self-hosted] category: self-hosting related_skills: [plex-setup, selfhosted-migration] --- # Audiobookshelf Setup Deploy Audiobookshelf via Docker with secure HTTPS access — including reverse proxy, dynamic DNS, and SSL via Let's Encrypt DNS challenge (for residential ISPs that block ports 80/443). ## When to Use - User asks to install Audiobookshelf - User wants a self-hosted audiobook/podcast server - User needs HTTPS access to a self-hosted service behind a residential ISP - User needs a reverse proxy pattern for any Docker-hosted web service ## Prerequisites - Docker + docker-compose-v2 installed - A domain or DuckDNS subdomain (for SSL) - Port forwarding in router (for external access) ## Setup Steps ### 1. Create directory structure ```bash mkdir -p ~/docker/audiobookshelf/{config,metadata} ``` ### 2. Create docker-compose.yml ```yaml services: audiobookshelf: image: ghcr.io/advplyr/audiobookshelf:latest container_name: audiobookshelf network_mode: host environment: - TZ=America/New_York - PORT=13378 volumes: - /home/ray/docker/audiobookshelf/config:/config - /home/ray/docker/audiobookshelf/metadata:/metadata - /path/to/audiobooks:/audiobooks:ro restart: unless-stopped ``` **Key points:** - **`network_mode: host`** — Audiobookshelf defaults to port 80 internally. Set `PORT=13378` to move it off port 80 (needed for nginx later). With host networking, the port binds directly on the host. - **Audiobook mount** — Use `:ro` (read-only). Audiobookshelf only reads files; no write access needed. - The container needs ~5-10 seconds on first run to initialize its SQLite database and generate a JWT secret. ### 3. Start and verify ```bash cd ~/docker/audiobookshelf && docker compose pull && docker compose up -d sleep 10 curl -s -o /dev/null -w "HTTP %{http_code}" http://localhost:13378/ # Should return 200 ``` ### 4. Set up DuckDNS (free dynamic DNS) If using a residential ISP without a static IP: 1. Go to https://duckdns.org → sign in with GitHub/Google 2. Create a subdomain (e.g., `mybooks`) 3. Copy the token from the top of the page Install the updater script and cron job: ```bash sudo mkdir -p /opt/duckdns sudo tee /opt/duckdns/update.sh << 'EOF' > /dev/null #!/bin/bash echo url="https://www.duckdns.org/update?domains=&token=&ip=" | curl -k -s -o /opt/duckdns/duck.log -K - EOF sudo chmod +x /opt/duckdns/update.sh # Run once to register sudo /opt/duckdns/update.sh && cat /opt/duckdns/duck.log # Should output "OK" # Auto-update every 5 minutes (sudo crontab -l 2>/dev/null | grep -v duckdns; echo "*/5 * * * * /opt/duckdns/update.sh") | sudo crontab - ``` Verify the domain resolves: `dig +short .duckdns.org` ### 5. Install nginx + certbot ```bash sudo apt-get update && sudo apt-get install -y nginx certbot python3-certbot-nginx # Install DuckDNS plugin for Let's Encrypt DNS challenge sudo pip3 install --break-system-packages certbot-dns-duckdns ``` ### 6. Get SSL certificate via DNS challenge **Why DNS challenge:** Residential ISPs often block incoming ports 80/443. Let's Encrypt HTTP challenge requires port 80. DNS challenge works without any open ports — it adds a TXT record to the domain. ```bash # Create credentials file sudo mkdir -p /etc/letsencrypt sudo tee /etc/letsencrypt/duckdns.ini << 'EOF' > /dev/null dns_duckdns_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 .duckdns.org \ --non-interactive --agree-tos --email ``` Cert will auto-renew via certbot's built-in systemd timer. No cron needed. ### 7. Configure nginx reverse proxy with SSL Pick an **available high port** (since 80/443 are blocked by ISP). Check what's free: ```bash sudo ss -tlnp | grep -E "3443|4443|5443" ``` Create the nginx config: ```nginx server { listen 3443 ssl; server_name .duckdns.org; ssl_certificate /etc/letsencrypt/live/.duckdns.org/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/.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:13378; 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 server { listen 80; server_name .duckdns.org; return 301 https://$host:3443$request_uri; } ``` Enable and reload: ```bash sudo cp audiobookshelf.conf /etc/nginx/sites-available/audiobookshelf sudo ln -sf /etc/nginx/sites-available/audiobookshelf /etc/nginx/sites-enabled/ sudo rm -f /etc/nginx/sites-enabled/default sudo nginx -t && sudo systemctl reload nginx ``` ### 8. Port forwarding Forward the chosen high port (e.g., 3443 TCP) in your router to the server's LAN IP. ### 9. Access and create library 1. Visit `https://.duckdns.org:3443` 2. Create an admin account on first visit 3. Add a library → point it to `/audiobooks` (the container's internal mount path) 4. Audiobookshelf will scan and populate automatically ### 10. Client apps - **Web player** — built-in, at the same URL - **iOS** — [Audiobookshelf App](https://apps.apple.com/us/app/audiobookshelf/id6446379655) - **Android** — [Audiobookshelf on Google Play](https://play.google.com/store/apps/details?id=com.audiobookshelf.app) Connect the app to `https://.duckdns.org:3443` with your account. Supports offline downloads, sleep timer, and playback speed controls. ## Pitfalls - **Port 80 conflicts with host networking** — Audiobookshelf defaults to port 80 internally. With `network_mode: host`, this binds directly on the host, conflicting with nginx. Set `PORT=13378` in the environment to move it before nginx setup. - **Docker port conflicts** — Other containers may already use ports you want for nginx (e.g., Heimdall on 8443). Check with `docker ps --format '{{.Names}} {{.Ports}}'` before picking an nginx port. - **Shell mangling of tokens** — If API tokens or Docker env vars contain special chars (underscores, dashes), bash may mangle them in variable expansion. Use Python for HTTP calls with tokens: `urllib.request.Request(url)` with `headers` works reliably. See `plex-setup` for the same pattern. - **Hairpin NAT** — Testing the public URL from inside the LAN often fails (connection refused) even when the setup is correct. Always test from a mobile device on cellular data, not Wi‑Fi. - **`certbot-dns-duckdns` not in apt** — On Ubuntu 26.04, this package isn't in apt. Use `pip3 install --break-system-packages certbot-dns-duckdns` instead. - **Audiobookshelf first-run delay** — The container needs ~10 seconds to initialize its SQLite database, generate a JWT secret, and start listening. Don't assume it's broken if port 13378 isn't immediately available. - **`docker compose restart` vs `up -d`** — `restart` reuses the old container config (doesn't pick up new env vars like `PORT`). Use `up -d` when changing environment variables, then `restart` for simple process cycling. ## Verification Checklist - [ ] `curl http://localhost:13378/` returns 200 - [ ] DuckDNS updater returns "OK" on manual run - [ ] `dig +short .duckdns.org` returns the correct public IP - [ ] SSL cert obtained (`sudo certbot certificates`) - [ ] nginx config passes `sudo nginx -t` - [ ] `curl -sk https://localhost:3443/` returns 200 (SSL working locally) - [ ] Port forwarding rule added in router - [ ] External access confirmed from cellular data ## Support Files - `templates/docker-compose.yml` — Starter Docker Compose file - `templates/nginx-audiobookshelf.conf` — nginx reverse proxy config with SSL - `scripts/duckdns-update.sh` — DuckDNS IP update script (set DOMAIN and TOKEN) - `references/heimdall-dashboard.md` — Add the service to Heimdall dashboard via SQLite