Audiobookshelf sur VPS : audiolivres et podcasts self-hosted

Les plateformes d'audiolivres imposent leurs catalogues, leurs DRM et leurs prix mensuels. Avec Audiobookshelf, vous importez vos propres fichiers M4B, MP3 ou FLAC — que vous les ayez achetés, empruntés ou produits vous-même — et vous y accédez depuis n'importe quel appareil via les apps mobiles open source. La bibliothèque grandit à votre rythme, pas au leur.

Audiobookshelf lit les formats courants, notamment MP3, M4A, M4B (avec chapitres), AAC, OGG, FLAC, WAV et OPUS. Les chapitres M4B sont affichés dans le lecteur avec leur titre et leur durée. Les fichiers Audible protégés par DRM ne se lisent pas tels quels : n'importez que des fichiers dont vous avez le droit de disposer, dans un format ouvert.

Le serveur lui-même est modeste : un VPS Ubuntu 24.04 avec Docker suffit pour une famille. Ce qui pèse est le disque, car la bibliothèque (surtout les épisodes de podcasts, téléchargés au fil du temps) grossit en continu, et le processeur uniquement quand un client demande un transcodage via ffmpeg plutôt qu'une lecture directe. Prévoyez donc un volume de données dimensionné sur votre collection, plus de la marge pour les métadonnées, les couvertures et les sauvegardes, qui vivent par défaut dans le même volume /metadata.

La base SQLite du serveur doit rester sur le disque local du VPS. La documentation d'Audiobookshelf est explicite : le dossier /config ne doit pas être monté sur un partage réseau, sous peine de lenteurs puis de corruption. Les fichiers audio, eux, peuvent vivre ailleurs.

Audiobookshelf ne nécessite pas de nom de domaine pour fonctionner. Avec le template ServOrbit, le conteneur n'écoute que sur le loopback du VPS, port 13780. Ouvrez un tunnel SSH depuis votre machine : ssh -L 13378:127.0.0.1:13780 root@<ip-vps>, puis allez sur http://localhost:13378. Pour une utilisation permanente depuis l'app mobile, rattachez un domaine depuis votre espace client ServOrbit — nginx proxifie le conteneur en HTTPS — ou utilisez le sous-domaine gratuit {app}.{dns_slug}.servorbit-dns.com inclus avec chaque VPS.

Quatre volumes, quatre rôles. /config contient la base SQLite et les scripts de migration. /metadata contient les métadonnées, les couvertures, les images d'auteurs, les journaux, le cache et, par défaut, les sauvegardes. /audiobooks et /podcasts donnent accès aux fichiers médias. Le serveur doit pouvoir écrire dans /config et /metadata ; sur /audiobooks, l'écriture n'est nécessaire que si vous voulez qu'il écrive des métadonnées à côté des fichiers, et sur /podcasts elle est indispensable puisque les épisodes y sont téléchargés.

Par défaut, l'exemple officiel ne fixe pas d'utilisateur. Pour durcir, ajoutez la directive user: : le conteneur n'a alors plus les droits de root sur les montages, et c'est précisément là que les erreurs de permissions apparaissent. La règle est simple : le propriétaire des dossiers hôtes doit être l'UID:GID de la directive user:. Testez avant de charger la bibliothèque : docker compose exec audiobookshelf touch /config/test /metadata/test, puis supprimez les deux fichiers.

Sur un système de fichiers à ACL (ZFS avec ACL NFSv4, par exemple), un chown ne suffit pas toujours : l'incident décrit plus bas en est l'illustration, avec un conteneur en utilisateur 568, toutes capacités retirées, sur un dataset ZFS.

Audiobookshelf sait créer ses propres sauvegardes depuis l'interface (planification, nombre de sauvegardes conservées, taille maximale). Chaque archive contient la base de données et les images de couverture du dossier de métadonnées ; les fichiers médias stockés avec les éléments de bibliothèque n'y sont pas. Par défaut, les archives sont écrites dans /metadata/backups, c'est-à-dire sur le même disque que les données : une panne du VPS emporte les deux. Copiez-les donc régulièrement hors du serveur.

Une sauvegarde ne protège que si elle est cohérente. La base est un fichier SQLite vivant : copier /config avec cp ou rsync pendant que le serveur écrit (progression d'écoute, scan) peut produire un fichier incohérent. Deux méthodes sûres : utiliser la sauvegarde intégrée du serveur, puis copier l'archive produite ; ou arrêter le conteneur le temps de la copie. Les fichiers audio, eux, se sauvegardent à part, avec rsync ou un outil de sauvegarde par déduplication.

Une restauration se fait sur le même type de système : la documentation avertit qu'une sauvegarde Linux se restaure sur Linux, et qu'un passage d'une méthode d'installation à une autre peut faire perdre progression et métadonnées.

Le template ServOrbit tire l'image latest. C'est pratique, mais cela vous expose aux régressions d'une version à l'autre. La mise à jour documentée est simple : docker compose pull, docker compose down, docker compose up --detach. Avant chaque mise à jour, faites une sauvegarde (intégrée ou à froid) et lisez les notes de version sur la page des releases du dépôt GitHub.

Un cas récent le justifie. La version 2.37.0 a fait passer le serveur à Node.js 24, et la 2.37.1 a été touchée par une boucle de redémarrage sur certaines installations (voir ci-dessous). La correction est publiée dans la 2.37.2, qui est, à la date de rédaction, la dernière version stable listée par le projet. Un tag épinglé et une sauvegarde préalable permettent de revenir en arrière sans improviser.

Symptôme : le conteneur redémarre en boucle après une mise à jour vers la 2.37.1, et les journaux affichent « Failed to copy migrations to the config directory », puis « EPERM: operation not permitted, copyfile » du dossier /app/dist-server/server/migrations/ vers /config/migrations/, suivi de « Database migration failed ».

État réel de l'incident (issue n° 5637 du dépôt advplyr/audiobookshelf, ouverte en octobre 2026) : elle est fermée. Le rapporteur utilisait TrueNAS SCALE, un conteneur en utilisateur 568, toutes capacités retirées et no-new-privileges, avec /config sur un dataset ZFS en bind mount. Plusieurs utilisateurs de TrueNAS ont signalé la même chose. Aucune cause racine n'est formellement établie dans la discussion ; un test a montré que copyFileSync échouait avec EPERM sur ce montage alors que l'écriture directe d'un fichier fonctionnait avec le même utilisateur, et une régression de la copie liée à Node.js 24 est soupçonnée. La correction (PR n° 5668) ajoute un repli quand la copie échoue ; elle est livrée dans la 2.37.2.

Remède : passez à la 2.37.2 ou plus récente. Si vous ne pouvez pas mettre à jour tout de suite, la solution de contournement évoquée dans l'issue est de revenir à la 2.36.1 avec une sauvegarde faite avant la mise à jour. Si le même message persiste après la mise à jour, vérifiez le propriétaire du dossier de configuration et les ACL du dataset : ce n'est plus ce bogue-là.

Symptôme : le serveur s'arrête à l'heure de la sauvegarde planifiée, avec « FATAL: [Server] Uncaught exception » et SQLITE_BUSY: database is locked. Avec restart: unless-stopped, Docker relance le conteneur : on ne voit qu'une brève coupure, que révèle un compteur de redémarrages non nul (docker inspect --format '{{.RestartCount}}' <conteneur> ; remplacez le nom par celui de votre conteneur).

État réel (issue n° 4572, ouverte en août 2025) : elle est toujours ouverte. Un contributeur explique la cause : la sauvegarde SQLite émet l'erreur « base occupée » comme un événement sans écouteur, que Node.js traite comme une exception non rattrapée, et aucune nouvelle tentative n'est faite. Le plantage survient quand une autre écriture, par exemple l'enregistrement de la progression d'écoute par un client, tient le verrou plus d'une seconde pendant la copie. La PR n° 5660 (sauvegarde par lots avec reprise sur verrou, et erreurs de session journalisées au lieu de planter) est à ce jour ouverte et non fusionnée : aucune version publiée ne la contient. Une première PR concurrente a été fermée au profit de celle-ci.

En attendant, trois palliatifs rapportés dans l'issue : décaler la sauvegarde loin des heures d'écoute (plutôt l'aube que la soirée) ; garder restart: unless-stopped pour que le conteneur reparte seul ; ou remplacer la sauvegarde intégrée par une sauvegarde à froid planifiée côté hôte, qui arrête le conteneur quelques instants. Rappel de la documentation : la base doit être sur le disque local, jamais sur un partage réseau.

Une fois le serveur stable, ajoutez une seconde couche de protection : une sauvegarde chiffrée des dossiers de configuration vers un stockage distant, et une alerte si le conteneur redémarre plus d'une fois par jour. Suivez les issues citées ici : le plantage de sauvegarde sera à nouveau à vérifier dès que la PR n° 5660 sera fusionnée et publiée.