Audiobookshelf with a Cloudflare Tunnel: setup, 502 errors and app sign-in

Run cloudflared in Docker on the same network as Audiobookshelf, and point the tunnel at http://audiobookshelf:80, the container’s name and its inside port. A 502 error from the tunnel means cloudflared can’t reach the address you gave it.

A Cloudflare Tunnel gives your server a public HTTPS address without opening any ports on your router. cloudflared makes an outgoing connection to Cloudflare, and visitors reach your server through it. It also works when your internet provider shares one public IP between many homes (called CGNAT). If you’re still choosing between a tunnel, Tailscale and a reverse proxy, start with listening away from home.

You need a domain whose DNS is managed by Cloudflare.

How do I set up a Cloudflare Tunnel for Audiobookshelf?

1. In the Cloudflare Zero Trust dashboard, create a tunnel. Pick Docker as the environment and copy the tunnel token from the command it shows you.

2. Add cloudflared to the same Docker Compose file as Audiobookshelf, so both containers share a network:

   services:
     audiobookshelf:
       image: ghcr.io/advplyr/audiobookshelf:latest
       container_name: audiobookshelf
       ports:
         - 13378:80
       volumes:
         - /path/to/audiobooks:/audiobooks
         - /path/to/podcasts:/podcasts
         - /path/to/config:/config
         - /path/to/metadata:/metadata
       restart: unless-stopped
   
     cloudflared:
       image: cloudflare/cloudflared:latest
       command: tunnel --no-autoupdate run
       environment:
         - TUNNEL_TOKEN=your-tunnel-token
       restart: unless-stopped
   

3. Start it with docker compose up -d. The tunnel shows as connected in the dashboard.

4. In the tunnel’s settings, add a public hostname (Cloudflare now calls it a published application). Pick a subdomain, like books, and your domain.

5. Set the service to http://audiobookshelf:80. Use http, not https: the tunnel already adds HTTPS on Cloudflare’s side.

6. Save, then open https://books.example.com in a browser and sign in.

The 13378:80 line still lets you use the server at home on http://your-server-ip:13378. The tunnel doesn’t need it.

Why do I get a 502 Bad Gateway error?

When the 502 page says “Unable to reach the origin service”, the tunnel is connected to Cloudflare but cloudflared can’t reach Audiobookshelf. Things to check:

• The service points at the wrong place. Inside the cloudflared container, localhost means the cloudflared container itself. And port 13378 is the port on the host. On a shared Docker network, containers talk to each other by name and inside port: http://audiobookshelf:80. That’s the fix that worked in issue #4128.
• The containers aren’t on the same network. Put them in one Compose file, or attach both to the same Docker network.
• The name doesn’t match. audiobookshelf has to be the service or container name you used. If you named it abs, the service is http://abs:80.
• https on the service. Audiobookshelf answers plain http inside Docker. An https:// service URL fails.

If cloudflared runs directly on the host instead of in Docker, http://localhost:13378 is the right service.

Why do I get a 522 error?

A 522 means Cloudflare timed out trying to connect to your server. With a tunnel, check the DNS record for your hostname first. If it’s an A record you made by hand, pointing at your home IP, Cloudflare tries to reach your home directly instead of using the tunnel. With no open ports, nothing answers.

If that’s what you find, delete the manual record and let the tunnel make its own. When you add a public hostname in the dashboard, Cloudflare creates a DNS record that points the name at the tunnel (a CNAME ending in cfargotunnel.com).

Do I need to turn on WebSockets?

Audiobookshelf’s apps keep a live connection open for updates, called a WebSocket. Cloudflare supports WebSockets on every plan with no extra setup in the tunnel. If live updates don’t work, check that the WebSockets switch on your domain’s Network page in the Cloudflare dashboard is on.

Cloudflare may close a WebSocket that sends nothing for a while, and closes them when it restarts its own servers. Audiobookshelf reconnects by itself. If you see “Socket failed to connect” all the time, this troubleshooting guide goes through the causes.

How do I sign in from an app with Cloudflare Access?

Cloudflare Access puts a Cloudflare sign-in page (email code, Google and so on) in front of your server. A browser can show it. An app’s requests to the server can’t fill it in, so they’re stopped before they ever reach Audiobookshelf.

The fix is a service token: a client ID and secret that the app sends with every request. You need two things in Cloudflare:

1. A service token, made under Zero Trust > Access controls > Service credentials > Service Tokens.
2. A policy on your Audiobookshelf application whose action is Service Auth, not Allow, that includes that token. Without it, Access still asks for a sign-in.

Then in SoundLeaf, on the sign-in screen, open Connection settings and add two headers: CF-Access-Client-Id and CF-Access-Client-Secret, with your token’s values. SoundLeaf sends them with every request, including audio and the live connection.

The token only gets you past Cloudflare. You still sign in with your Audiobookshelf username and password, or OpenID if your server uses it. SoundLeaf has no API key login. The step by step is in Cloudflare Access setup.

If you don’t need Access, you can skip it and rely on Audiobookshelf’s own sign-in. Securing your server covers what to do then.

Why are downloads slow through a Cloudflare Tunnel?

Some things to check:

• HTTP/2 to the origin. The tunnel has an option to talk to your server over HTTP/2 instead of HTTP/1.1. It’s off by default and needs a server that answers over HTTPS. With the http://audiobookshelf:80 service in this guide, leave it off.
• Your home upload speed. Every byte goes from your home connection to Cloudflare first, so your upload speed is the ceiling. Slow downloads away from home goes through this.
• Inside the house. At home there’s no reason to go out to Cloudflare and back. SoundLeaf can use the local address on your home Wi-Fi and the tunnel everywhere else; see home and away addresses.

Can I upload audiobooks through a Cloudflare Tunnel?

Small ones. On Cloudflare’s Free and Pro plans, one request can send at most 100 MB (200 MB on Business). A bigger upload fails with a 413 error. A single-file M4B audiobook is often bigger than that.

The limit is only on what you send to the server. Cloudflare doesn’t limit response size, so streaming and downloading books through the tunnel aren’t capped this way.

To add big books, upload them at home using the local address, or copy the files straight into your library folder and let Audiobookshelf scan them.

Is streaming audiobooks through Cloudflare allowed?

Cloudflare’s terms speak to this. In the service-specific terms, the section on the Free, Pro and Business CDN says that using it “to serve video or a disproportionate percentage of pictures, audio files, or other large files” without one of Cloudflare’s paid media services can lead Cloudflare to limit or turn off your access.

Read the terms and decide for yourself. If it worries you, Tailscale keeps the audio off Cloudflare entirely. So does your own reverse proxy, as long as its DNS record is set to DNS only (grey cloud) rather than proxied through Cloudflare.