Setting up Audiobookshelf for SoundLeaf

To use SoundLeaf you need an Audiobookshelf server somewhere. The official docs cover every option in detail, but they’re long. This is the short version, organized by how much fiddling you actually want to do.

I run my own ABS on a small home server. Most people I talk to either want the easiest possible deploy, want to use a machine they already own, or want a proper VPS. Pick the path that matches.

Path 1: I just want it running

If you don’t have a home server and don’t want one, deploy through a hosted Docker provider.

Easypanel

1. Sign up at easypanel.io. The free tier is enough to start.
2. Create a new project.
3. Click “Create Service” then “From Template”.
4. Search for “Audiobookshelf” and click it.
5. Deploy.

Your server lands at https://your-project.easypanel.host.

The free tier is fine for poking around. Storage is tight, so this isn’t where you put a 500GB library long-term, but it’s the fastest way to see if you actually like Audiobookshelf before committing to anything.

Path 2: I have a computer at home

This is what I do. The recurring cost is zero and you keep your library on hardware you control.

On a Synology NAS

1. Open Container Manager (Docker on older DSM).
2. Search the registry for “audiobookshelf”.
3. Download ghcr.io/advplyr/audiobookshelf:latest.
4. In File Station, create:

   /docker/audiobookshelf/config
   /docker/audiobookshelf/metadata
   /audiobooks
   /podcasts
   

5. Launch with port 13378:13378 and the four folders above mounted.

Full Synology walkthrough is in the NAS setup guide.

On an old laptop or mini PC

Anything that can run Docker works. I’ve seen people happily run Audiobookshelf on a 7-year-old NUC. If you’re shopping for hardware, this mini PC list is decent.

Install Docker:

curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh

Then run Audiobookshelf:

docker run -d \
  -p 13378:80 \
  -v ~/audiobooks:/audiobooks \
  -v ~/podcasts:/podcasts \
  -v ~/config:/config \
  -v ~/metadata:/metadata \
  --name audiobookshelf \
  ghcr.io/advplyr/audiobookshelf

Getting to it from outside your home

You probably want SoundLeaf to work on cellular too, not just on your home WiFi. Two ways.

Cloudflare Tunnel is the easier option. No port forwarding, no static IP needed.

1. Install cloudflared on your server.
2. Run cloudflared tunnel --url http://localhost:13378.
3. Cloudflare hands you a public HTTPS URL.

If you go this route and want SSO in front of the login page too, the Cloudflare Access setup guide walks through it.

Port forwarding is the older route. Forward port 13378 on your router to your server, set up dynamic DNS if your IP changes, and put a real cert in front with Let’s Encrypt. The reverse proxy guide covers Nginx, Caddy, and Traefik configs.

Path 3: I want a proper VPS

DigitalOcean, Linode, and Vultr all have basic plans around $5-6/month that will run Audiobookshelf comfortably. Always-on, no power bill at home, accessible from anywhere.

1. Spin up an Ubuntu server.
2. SSH in and install Docker (same script as above).
3. Run the same docker run command from Path 2.
4. Put Nginx in front for SSL:

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost: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;
    }
}

5. Add a cert with Certbot:

sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d your-domain.com

The one thing to get right is WebSocket support (Upgrade and Connection headers above). Audiobookshelf uses WebSockets for real-time updates and breaks without them.

Folder structure (this part actually matters)

Audiobookshelf is picky about how books are organized. Each book needs its own folder:

/audiobooks/
  Brandon Sanderson - The Way of Kings/
    01 - Prelude.mp3
    02 - Chapter 1.mp3
    cover.jpg
  Andy Weir - The Martian/
    The Martian.m4b

Things that will bite you:

• All files dumped into one folder. Won’t work.
• Weird characters in filenames. Causes parser issues.
• OPUS format. iOS doesn’t decode it well.
• No cover image. The book still works, you just stare at a blank rectangle.

Format-wise, MP3 and M4B are the safe defaults. M4A and AAC work fine. FLAC is supported but the files are big, which matters if you download to your phone. Avoid OPUS.

Connecting SoundLeaf

Once the server is up:

1. Open SoundLeaf.
2. Type the server URL. The app tries https:// and http:// automatically, so you don’t need the prefix.
3. Add :13378 if you didn’t change the port.
4. Username and password.
5. Connect.

If the connection fails, the usual suspects:

• Server isn’t actually running. docker ps should list it.
• Web UI works in a browser but the app doesn’t. Almost always WebSockets aren’t proxied through.
• Connection refused. Wrong port or firewall.
• Connects on home WiFi but not on cellular. The server isn’t reachable from outside. Cloudflare Tunnel or port forwarding.

A note on the official iOS app

The official Audiobookshelf iOS app is open source and fine. If TestFlight is full when you check (it caps at 10,000 users), SoundLeaf is the alternative I’ve been building. Both apps talk to the same server, your progress syncs through Audiobookshelf, and you can switch between them whenever.

I built SoundLeaf because I wanted a polished native iOS app for my own listening, and the official one wasn’t yet what I wanted. That’s it. There’s no rivalry; the official app and ABS itself are why any of this exists.

Resources

• Audiobookshelf on GitHub
• Audiobookshelf docs
• Audiobookshelf API reference
• SoundLeaf on the App Store
• SoundLeaf on GitHub

Happy listening, Hemant