Portainer Templates logo

Portainer Templates

Audiobookshelf Audiobookshelf

Stack

MultimediaAudio

Self hosted audiobook and podcast server

Image details

Architecture: amd64, arm64
Image size: 110 MB
User: advplyr

Source details

Repo: advplyr/audiobookshelf
Stars: 14.0k
Forks: 1k
Language: JavaScript
License: GPL-3.0
Latest: v2.36.0 · 19 days ago
Updated: 12 days ago
Website: audiobookshelf.org/

Configuration

Type
Compose
Platform
linux
Image
ghcr.io/advplyr/audiobookshelf
Ports
13378:80
Volumes
/audiobooks : /portainer/Files/AppData/Config/audiobookshelf/audiobooks/podcasts : /portainer/Files/AppData/Config/audiobookshelf/podcasts/metadata : /portainer/Files/AppData/Config/audiobookshelf/metadata/config : /portainer/Files/AppData/Config/audiobookshelf
Env vars
PUID=1000PGID=1000PORT=''
Source
Repo

Template by xneo1·Source

Standalone Install

Select an install method, to see config/commands for deploying Audiobookshelf

Installation method

Install on Portainer

Import all app templates into your Portainer instance, for easy 1-click deploys

  1. Ensure both Docker and Portainer are installed, and up-to-date
  2. Log into your Portainer web UI
  3. Under Settings → App Templates, paste the below URL
  4. Head to Home → App Templates, and the list of apps will show up
  5. Select Audiobookshelf, fill in any config options, and hit Deploy

Template Import URL

https://raw.githubusercontent.com/Lissy93/portainer-templates/main/templates.json
Show Me demo
Original stackfile

The compose file this template deploys, straight from its repo:

services:
  audiobookshelf:
    container_name: audiobookshelf
    image: ghcr.io/advplyr/audiobookshelf
    ports:
      - 13378:80
    volumes:
      - /portainer/Files/AppData/Config/audiobookshelf/audiobooks:/audiobooks
      - /portainer/Files/AppData/Config/audiobookshelf/podcasts:/podcasts
      - /portainer/Files/AppData/Config/audiobookshelf/metadata:/metadata
      - /portainer/Files/AppData/Config/audiobookshelf:/config

Or deploy it directly from the source:

git clone https://github.com/xneo1/portainer_templates
cd portainer_templates
docker compose -f Template/Stack/audiobookshelf.yml up -d

More install options in our documentation, or see advplyr/audiobookshelf for app-specific guidance.


<img alt="Audiobookshelf Banner" src="https://github.com/advplyr/audiobookshelf/raw/master/images/banner.svg" width="600">

<br />
<a href="https://audiobookshelf.org/docs">Documentation</a>
·
<a href="https://audiobookshelf.org/support">Support</a>
·
<a href="https://audiobooks.dev/">Demo</a>

⚠️ Frontend pull requests are not being reviewed or merged for the existing Vue frontend. The frontend is currently being rewritten and migrated to React and should be available soon.

About

Audiobookshelf is a self-hosted audiobook and podcast server.

Features

  • Fully open-source, including the android & iOS app (in beta)
  • Stream all audio formats on the fly
  • Search and add podcasts to download episodes w/ auto-download
  • Multi-user support w/ custom permissions
  • Keeps progress per user and syncs across devices
  • Auto-detects library updates, no need to re-scan
  • Upload books and podcasts w/ bulk upload drag and drop folders
  • Backup your metadata + automated daily backups
  • Progressive Web App (PWA)
  • Chromecast support on the web app and android app
  • Fetch metadata and cover art from several sources
  • Chapter editor and chapter lookup (using Audnexus API)
  • Merge your audio files into a single m4b
  • Embed metadata and cover image into your audio files
  • Basic ebook support and ereader
- Epub, pdf, cbr, cbz - Send ebook to device (i.e. Kindle)
  • Open RSS feeds for podcasts and audiobooks

Is there a feature you are looking for? Suggest it
Join us on Discord

Demo

Check out the web client demo: https://audiobooks.dev/ (thanks for hosting @Vito0912!)
Username/password: demo/demo (user account)

Android App (beta)

Try it out on the Google Play Store

iOS App (beta)

Beta is currently full. Apple has a hard limit of 10k beta testers. Updates will be posted in Discord.
Using Test Flight: https://testflight.apple.com/join/wiic7QIW (beta is full)


Library Screenshot

Organizing your media

Directory structure and folder names are important to Audiobookshelf!

See library docs for supported directory structures, folder naming conventions, and audio file metadata usage.

Installation

See install docs

Reverse Proxy Set Up

Important! Audiobookshelf requires a websocket connection.

Note: Using a subfolder is supported with no additional changes but the path must be /audiobookshelf (this is not changeable). See discussion

See reverse proxy docs

Contributing

See contributing docs

Localization

Thank you to Weblate for hosting our localization infrastructure pro-bono. If you want to see Audiobookshelf in your language, please help us localize. Additional information on helping with the translations here. Translation status

Run from source

This application is built using NodeJs.

Dev Container Setup

The easiest way to begin developing this project is to use a dev container. An introduction to dev containers in VSCode can be found here.
Required Software:

Note, it is possible to use other container software than Docker and IDEs other than VSCode. However, this setup is more complicated and not covered here.
Install the required software on Windows with winget

Note: This requires a PowerShell prompt with winget installed. You should be able to copy and paste the code block to install. If you use an elevated PowerShell prompt, UAC will not pop up during the installs.

winget install -e --id Docker.DockerDesktop; `
winget install -e --id Microsoft.VisualStudioCode


Install the required software on MacOS with homebrew


brew install --cask docker visual-studio-code


Install the required software on Linux with snap


sudo snap install docker; \
sudo snap install code --classic


After installing these packages, you can now install the Remote Development extension for VSCode. After installing this extension open the command pallet (ctrl+shift+p or cmd+shift+p) and select the command >Dev Containers: Rebuild and Reopen in Container. This will cause the development environment container to be built and launched.
You are now ready to start development!

Manual Environment Setup

If you don't want to use the dev container, you can still develop this project. First, you will need to install NodeJs (version 20) and FFmpeg.
Next you will need to create a dev.js file in the project's root directory. This contains configuration information and paths unique to your development environment. You can find an example of this file in .devcontainer/dev.js.
You are now ready to build the client:
npm ci
cd client
npm ci
npm run generate
cd ..

Development Commands

After setting up your development environment, either using the dev container or using your own custom environment, the following commands will help you run the server and client.
To run the server, you can use the command npm run dev. This will use the client that was built when you ran npm run generate in the client directory or when you started the dev container. If you make changes to the server, you will need to restart the server. If you make changes to the client, you will need to run the command (cd client; npm run generate) and then restart the server. By default the client runs at localhost:3333, though the port can be configured in dev.js.
You can also build a version of the client that supports live reloading. To do this, start the server, then run the command (cd client; npm run dev). This will run a separate instance of the client at localhost:3000 that will be automatically updated as you make changes to the client.
If you are using VSCode, this project includes a couple of pre-defined targets to speed up this process. First, if you build the project (ctrl+shift+b or cmd+shift+b) it will automatically generate the client. Next, there are debug commands for running the server and client. You can view these targets using the debug panel (bring it up with (ctrl+shift+d or cmd+shift+d):
  • Debug server—Run the server.
  • Debug client (nuxt)—Run the client with live reload.
  • Debug server and client (nuxt)—Runs both the preceding two debug targets.

Serve Audiobookshelf on your own domain behind Caddy, Nginx or Traefik. Fill in your domain and copy the result. It's a starting point, some apps need their own base URL or extra headers set too.

Proxying audiobookshelf.example.com to http://audiobookshelf:80

Add this to your Caddyfile

audiobookshelf.example.com {
	reverse_proxy http://audiobookshelf:80
}

Check the logs first

Nine times out of ten the logs tell you exactly what went wrong.

  • In Portainer, go to Containers, click the container, then Logs. Or run docker logs <container>
  • Exit codes help too: 137 means killed, usually out of memory. 126 or 127 means the command inside the image is broken.

Port already in use

If deployment fails with "Bind for 0.0.0.0:13378 failed: port is already allocated", something else on your server is using that port.

  • Find what's using it: sudo ss -tlnp | grep :13378
  • Stop the other service, or pick a different host port. In 13378:80 only the left number is yours to change, the right one belongs to the app.

Running but the page won't load

The container is up but nothing appears in your browser.

  • Use your server's real IP: http://your-server-ip:13378. The 0.0.0.0 link Portainer shows isn't a real address.
  • Give it a minute after first deploy, audiobookshelf can take a while to initialise.
  • Make sure your firewall allows the port, e.g. sudo ufw allow 13378

Permission denied on volumes

If the logs show "permission denied", the app can't write to its data folder on the host.

  • Fix the ownership: sudo chown -R 1000:1000 /portainer/Files/AppData/Config/audiobookshelf/audiobooks (and the same for the other mapped folders)
  • Or set the PUID and PGID variables (defaults 1000:1000) to match your own user, found with id $USER

Image won't pull

Test the pull directly on the host: docker pull ghcr.io/advplyr/audiobookshelf

  • "manifest unknown" means the tag no longer exists. This template uses latest, so try pinning a specific version instead.
  • "toomanyrequests" is the Docker Hub rate limit. Log in with docker login to raise it.
  • "no space left on device" means a full disk. Reclaim space with docker system prune

"exec format error"

This means the image was built for a different CPU architecture than your server.

  • This image supports: amd64, arm64
  • Check yours with uname -m: x86_64 is amd64, aarch64 is arm64. Raspberry Pi and other ARM boards are the usual culprits.

Required settings are blank

PORT has no default value, and audiobookshelf may crash or misbehave if left empty.

  • Fill it in on the deploy screen before hitting deploy.

Stack won't deploy

Compose stacks fail fast on small mistakes, and Portainer shows the reason just above the editor.

  • YAML only accepts spaces for indentation, a single tab breaks the whole file.

Raise an issue

Found something which isn't working as it should? Here's how to report it.

A Compose stack

Audiobookshelf is a Compose stack, a set of containers defined in one file and brought up together by Portainer, then started and stopped as a single app.

The app image

An image is the app packed up ready to go, everything Audiobookshelf needs bundled into one download. This template pulls ghcr.io/advplyr/audiobookshelf, which Docker fetches once (about 110 MB) and then starts your own copy from.

Where the image comes from

Docker pulls its images from registries, public libraries of ready-built apps. Audiobookshelf's comes from the GitHub Container Registry, published by advplyr.

Version tags

The bit after the colon in the image name is the version tag. Here it's latest, which always points at the newest build, so a redeploy can bump you to a newer release without you asking. Pin a specific tag if you would rather stay on one version.

Which machines it runs on

Every image is built for particular CPU types. This one ships for amd64, arm64, so it runs on both regular x86 servers and ARM boards like a Raspberry Pi.

Ports

A port is the door the app answers on. A mapping like 13378:80 means it's reachable on port 13378 of your server, where the left number is yours to change and the right one belongs to the app. Once it's running, open http://your-server-ip:13378 in a browser. It opens:

  • 13378:80, likely the web interface

Volumes

A volume is where Audiobookshelf keeps its files so they survive an update or a restart. Without one, anything it saves would sit inside the container and vanish the moment it's recreated. This template mounts:

  • /audiobooks from /portainer/Files/AppData/Config/audiobookshelf/audiobooks on the host
  • /podcasts from /portainer/Files/AppData/Config/audiobookshelf/podcasts on the host
  • /metadata from /portainer/Files/AppData/Config/audiobookshelf/metadata on the host
  • /config from /portainer/Files/AppData/Config/audiobookshelf on the host

Environment variables

Environment variables are the settings you hand over when you deploy, things like a password or a timezone. Audiobookshelf takes 3 of them, and one needs a value before it'll start properly:

  • PUID, defaults to 1000
  • PGID, defaults to 1000
  • PORT, needs a value

Users and permissions

The PUID and PGID settings tell it which user and group to act as on your host. Point them at your own account (find yours with id $USER) so the files it writes into your mounted folders come out owned by you rather than root.

Networking

Nothing custom is set, so Audiobookshelf sits on Docker's default bridge network: its own private space that reaches the outside world only through the ports it publishes.

Container name

Once it's deployed, Portainer names the container audiobookshelf. That's what you'll spot in the containers list and use in commands like docker logs audiobookshelf.

Platform

The platform is linux, the kind of system the container is built to run on. Docker and Portainer handle this on a normal Linux server.

Open source license

Audiobookshelf is open source, released under the GPL-3.0 license. In plain terms the code is out in the open, so you're free to run it and change it to fit what you need.

Portainer app templates

Zooming out, this whole page comes from a Portainer app template: a short recipe telling Portainer how to set Audiobookshelf up. Add the template list to Portainer once, then deploying Audiobookshelf is a click rather than a wall of config.