Audiobookshelf — Self-Hosted Audiobook and Podcast Server on VPS

Audiobook platforms impose their catalogues, their DRM and their monthly fees. With Audiobookshelf you import your own M4B, MP3 or FLAC files — bought, borrowed or produced yourself — and reach them from any device through the open-source mobile apps. The library grows at your pace, not theirs.

Audiobookshelf plays the common formats, including MP3, M4A, M4B (with chapters), AAC, OGG, FLAC, WAV and OPUS. M4B chapters appear in the player with their title and duration. DRM-protected Audible files do not play as they are: only import files you have the right to use, in an open format.

The server itself is modest: an Ubuntu 24.04 VPS with Docker is enough for a family. What weighs is disk, because the library (above all podcast episodes, downloaded over time) keeps growing, and CPU only when a client asks for transcoding through ffmpeg instead of direct playback. Size your data volume on your collection, and leave room for metadata, covers and backups, which live by default in the same /metadata volume.

The server's SQLite database must stay on the VPS's local disk. The Audiobookshelf documentation is explicit: the /config folder must not be mounted on a network share, or you risk slowdowns and then corruption. The audio files themselves can live elsewhere.

Audiobookshelf does not need a domain name to run. With the ServOrbit template, the container listens only on the VPS loopback, port 13780. Open an SSH tunnel from your machine: ssh -L 13378:127.0.0.1:13780 root@<vps-ip>, then browse to http://localhost:13378. For permanent use from the mobile app, attach a domain from your ServOrbit client area — nginx proxies the container over HTTPS — or use the free subdomain {app}.{dns_slug}.servorbit-dns.com included with every VPS.

Four volumes, four roles. /config holds the SQLite database and the migration scripts. /metadata holds metadata, covers, author images, logs, the cache and, by default, backups. /audiobooks and /podcasts give access to the media files. The server must be able to write to /config and /metadata; on /audiobooks, writing is only needed if you want it to write metadata next to the files, and on /podcasts it is essential since episodes are downloaded there.

By default, the official example sets no user. To harden, add the user: directive: the container then no longer has root rights on the mounts, and that is precisely where permission errors appear. The rule is simple: the owner of the host folders must be the UID:GID of the user: directive. Test before loading the library: docker compose exec audiobookshelf touch /config/test /metadata/test, then delete both files.

On a filesystem with ACLs (ZFS with NFSv4 ACLs, for example), a chown is not always enough: the incident described below illustrates it, with a container running as user 568, all capabilities dropped, on a ZFS dataset.

Audiobookshelf can create its own backups from the interface (schedule, number of backups kept, maximum size). Each archive contains the database and the cover images from the metadata folder; the media files stored with library items are not in it. By default, archives are written to /metadata/backups, that is on the same disk as the data: a VPS failure takes both. Copy them off the server regularly.

A backup only protects if it is consistent. The database is a live SQLite file: copying /config with cp or rsync while the server writes (listening progress, scans) can produce an inconsistent file. Two safe methods: use the server's built-in backup, then copy the archive it produced; or stop the container for the duration of the copy. Audio files are backed up separately, with rsync or a deduplicating backup tool.

A restore is done on the same kind of system: the documentation warns that a Linux backup is restored on Linux, and that switching from one installation method to another can lose progress and metadata.

The ServOrbit template pulls the latest image. It is convenient, but it exposes you to regressions from one version to the next. The documented update is simple: docker compose pull, docker compose down, docker compose up --detach. Before each update, take a backup (built-in or cold) and read the release notes on the GitHub repository's releases page.

A recent case justifies this. Version 2.37.0 moved the server to Node.js 24, and 2.37.1 was hit by a restart loop on some installations (see below). The fix is published in 2.37.2, which is, at the time of writing, the latest stable version listed by the project. A pinned tag and a prior backup let you roll back without improvising.

Symptom: the container restarts in a loop after an upgrade to 2.37.1, and the logs show "Failed to copy migrations to the config directory", then "EPERM: operation not permitted, copyfile" from the /app/dist-server/server/migrations/ folder to /config/migrations/, followed by "Database migration failed".

Actual state of the incident (issue no. 5637 of the advplyr/audiobookshelf repository, opened in October 2026): it is closed. The reporter used TrueNAS SCALE, a container running as user 568, all capabilities dropped and no-new-privileges, with /config on a ZFS dataset as a bind mount. Several TrueNAS users reported the same thing. No root cause is formally established in the discussion; a test showed copyFileSync failing with EPERM on that mount while writing a file directly worked with the same user, and a regression in the copy path linked to Node.js 24 is suspected. The fix (PR no. 5668) adds a fallback when the copy fails; it ships in 2.37.2.

Remedy: upgrade to 2.37.2 or later. If you cannot update right away, the workaround mentioned in the issue is to go back to 2.36.1 with a backup taken before the update. If the same message persists after the update, check the owner of the configuration folder and the dataset ACLs: it is no longer that bug.

Symptom: the server stops at the scheduled backup time, with "FATAL: [Server] Uncaught exception" and SQLITE_BUSY: database is locked. With restart: unless-stopped, Docker restarts the container: you only see a brief outage, revealed by a non-zero restart counter (docker inspect --format '{{.RestartCount}}' <container>; replace the name with your container's).

Actual state (issue no. 4572, opened in August 2025): it is still open. A contributor explains the cause: the SQLite backup emits the "database busy" error as an event with no listener, which Node.js treats as an uncaught exception, and no retry is made. The crash happens when another write, for example a client saving listening progress, holds the lock for more than a second during the copy. PR no. 5660 (batched backup that retries on lock, and session errors logged instead of crashing) is open and not merged to date: no published version contains it. An earlier competing PR was closed in favour of this one.

In the meantime, three workarounds reported in the issue: move the backup away from listening hours (dawn rather than evening); keep restart: unless-stopped so the container comes back on its own; or replace the built-in backup with a scheduled cold backup on the host, which stops the container for a few moments. Reminder from the documentation: the database must be on a local disk, never on a network share.

Once the server is stable, add a second layer of protection: an encrypted backup of the configuration folders to remote storage, and an alert if the container restarts more than once a day. Keep following the issues cited here: the backup crash will need checking again as soon as PR no. 5660 is merged and released.