Applications Azure

Audiobookshelf on Ubuntu 24.04 on Azure User Guide

| Product: Audiobookshelf on Ubuntu 24.04 LTS on Azure

Overview

Audiobookshelf is a popular open source, self hosted audiobook and podcast media server. Stream your own audiobook and podcast collection from anywhere through a fast web player or the native iOS and Android apps, with listening progress sync across every device. This cloudimg image runs Audiobookshelf 2.35.1 behind nginx on a hardened, fully patched Ubuntu 24.04 LTS base, so a private audiobook server is running within minutes of launch.

The Audiobookshelf server is a single self contained binary with an embedded SQLite datastore and a bundled web player. It runs under systemd, listening on the loopback interface, with nginx in front on port 80 (and 443 once you add TLS). nginx also proxies the WebSocket traffic the player relies on. Transcoding and audio tagging use ffmpeg. The binary, config, metadata and media library all live on a dedicated, independently resizable Azure data disk mounted at /usr/share/audiobookshelf, separate from the operating system disk.

What is included:

  • Audiobookshelf 2.35.1 served through nginx, managed by systemd
  • ffmpeg and ffprobe from the distribution, wired into the service environment for transcoding
  • A dedicated Azure data disk at /usr/share/audiobookshelf holding the SQLite database, cached metadata and your library
  • Secure by default: the image ships with no administrator, so only you set the admin password on first visit
  • The REST backend for the native iOS and Android apps, plus an OPDS feed
  • 24/7 cloudimg support

Secure by default, you create the admin account

Audiobookshelf has no default administrator, and this image does not bake one in. The image ships at Audiobookshelf's built in first visit Initial Server Setup / Create Root User screen. The very first time you browse to your instance you create your own admin account with your own username and password. No shared credentials, no database rows and no media files ship in the image, every instance starts as a clean slate that only you secure.

Audiobookshelf first visit Initial Server Setup screen where you create the root administrator account and the config and metadata paths are prefilled to the dedicated data disk

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus subnet in the target region. Standard_B2s (2 vCPU / 4 GiB RAM) is a sensible starting point for a personal library; size up for multi user libraries exceeding a thousand titles. Network security group inbound: allow 22/tcp from your management network and 80/tcp (and 443/tcp once you add TLS) from the networks that will reach the web player. The Azure CLI is required only if you deploy from the command line.

Step 1: Launch from the Azure Marketplace

Sign in to the Azure portal, select Create a resource, and search the Marketplace for Audiobookshelf on Ubuntu 24.04 LTS by cloudimg. Select the offer, choose the plan, and select Create.

On the Basics tab pick your subscription and resource group, a region, and a VM size of Standard_B2s or larger. Set the authentication type to SSH public key, the username to azureuser, and provide your public key. On the Networking tab select your VNet and subnet and a network security group that allows inbound 22/tcp and 80/tcp. Review and create. First boot initialisation completes about a minute after the VM reaches the Running state.

Step 2: Launch from the Azure CLI

az vm create \
  --resource-group my-resource-group \
  --name audiobookshelf \
  --image cloudimg:audiobookshelf-ubuntu-24-04:default:latest \
  --size Standard_B2s \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

# Open the required inbound ports on the VM's network security group
az vm open-port --resource-group my-resource-group --name audiobookshelf --port 22 --priority 1001
az vm open-port --resource-group my-resource-group --name audiobookshelf --port 80 --priority 1002

Step 3: Connect over SSH

Connect over SSH on port 22 as azureuser with the key pair you launched with:

ssh azureuser@<public-ip>

Replace <public-ip> with your VM's public IP address (or its private address if you reach it over a VPN or ExpressRoute).

Step 4: First visit, create your admin account

Open Audiobookshelf in your browser:

http://<public-ip>/

You are taken to the Initial Server Setup screen shown above. Enter a username (the default is root), choose a strong password and confirm it. The config and metadata paths are prefilled to the dedicated data disk (/usr/share/audiobookshelf/config and /usr/share/audiobookshelf/metadata), leave them as they are. Select Submit.

Because the database is empty, this first account is the administrator. That single step secures your instance; you are then taken to the sign in page to log in, and the setup screen never appears again for this instance.

Enable HTTPS before exposing the instance to the public internet (see the TLS section below). Until then, treat the password you set here as you would any credential sent over plain HTTP.

Verifying the deployment

The commands below confirm the server is healthy and shipped in the secure, no admin state. Run them over SSH on the VM.

Confirm both services are active and that the server is bound to the loopback interface only, with nginx fronting it on port 80:

systemctl is-active audiobookshelf nginx
ss -tlnp 2>/dev/null | grep -E ':80 |:13378'

The audiobookshelf and nginx services both active, with nginx listening on port 80 and the Audiobookshelf server bound to 127.0.0.1:13378

Confirm the health endpoint returns HTTP 200, the installed version, and that ffmpeg is wired into the service environment:

curl -s -o /dev/null -w 'healthcheck HTTP %{http_code}\n' http://127.0.0.1/healthcheck
dpkg-query -W -f='audiobookshelf ${Version}\n' audiobookshelf
grep -E '^FFMPEG_PATH|^HOST|^PORT' /etc/default/audiobookshelf

The Audiobookshelf health endpoint returning HTTP 200, the installed version 2.35.1, and the service environment showing the loopback host binding and the ffmpeg path

Confirm the server reports it has not been initialised yet, no admin user exists until you create one on first visit:

curl -s http://127.0.0.1/status | grep -o '"isInit":[a-z]*'

The Audiobookshelf status endpoint reporting the app name, server version 2.35.1, isInit false meaning no administrator is baked in, and the local authentication method

Confirm the dedicated Azure data disk is mounted at /usr/share/audiobookshelf, keyed by UUID in fstab so it survives reboots and re provisioning:

findmnt /usr/share/audiobookshelf
grep audiobookshelf /etc/fstab
df -h /usr/share/audiobookshelf | tail -1

The dedicated ext4 Azure data disk mounted at /usr/share/audiobookshelf, with its UUID keyed fstab entry and available capacity

Adding your library

After you log in, Audiobookshelf prompts you to add your first library. Copy your audiobooks or podcasts onto the dedicated data disk first, then point a library folder at them.

Copy your collection in over SSH from your workstation, for example with rsync (replace the placeholders with your own paths and address):

rsync -av /path/to/your/audiobooks/ azureuser@<public-ip>:/tmp/abs-upload/

Then move it into the library area and hand ownership to the service account:

sudo rsync -a --chown=audiobookshelf:audiobookshelf /tmp/abs-upload/ /usr/share/audiobookshelf/audiobooks/ && rm -rf /tmp/abs-upload

In the web UI, go to Settings, then Libraries, then Add Library, give it a name, choose the Books (or Podcasts) media type, and add the folder /usr/share/audiobookshelf/audiobooks. Organise audiobooks as Author/Title/files for the cleanest results, Audiobookshelf reads embedded tags and folder structure for author, title, series, cover art and chapters. It scans the folder automatically when you create the library and watches for new files thereafter; you can also trigger a rescan from the library's overflow menu.

The web player

Once a library is scanned, the home view shows your collection with cover art, organised into shelves such as Recently Added and Discover, with a sidebar for Library, Series, Collections, Authors, Narrators and listening Stats.

The Audiobookshelf web player home view showing a scanned library of audiobooks with cover art, organised into Recently Added and Discover shelves, with the navigation sidebar

Open any title to see its detail page, cover, author, narrator, duration, chapters, audio tracks and library files, and select Play to start listening.

An Audiobookshelf item detail page showing the cover, author, genre, duration and file size, with the Play button and the audio tracks and library files sections

The persistent player bar gives you play and pause, chapter and track navigation, a seek bar, variable playback speed, a sleep timer and bookmarks. Your listening position syncs automatically, so you can pick up on another device or in the mobile apps exactly where you left off.

The Audiobookshelf web player streaming an audiobook, with the persistent player bar showing the cover, title, playback controls, seek bar, playback speed and sleep timer

The same server backs the native iOS and Android apps, sign in with your instance URL and the admin credentials you created, and your libraries, progress and bookmarks are all there.

Multiple users

Audiobookshelf is multi user. As the admin, go to Settings, then Users, then Add User to create accounts for family members or a team, each with their own login, independent listening progress and per library access. An OPDS feed is also available for compatible reader and player apps.

Managing the services

Audiobookshelf and nginx are managed with systemd:

sudo systemctl status audiobookshelf
sudo systemctl restart audiobookshelf
sudo systemctl status nginx
sudo journalctl -u audiobookshelf -f

The service environment lives in /etc/default/audiobookshelf (port, host binding, config and metadata paths and the ffmpeg and ffprobe locations). The server binds to 127.0.0.1:13378; nginx terminates client connections on port 80.

Enabling HTTPS

Before exposing the instance to the public internet, terminate TLS at nginx. Point a DNS A record at your VM, open port 443 in the network security group, and use Certbot to obtain and install a Let's Encrypt certificate (replace the host with your own domain):

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d audiobooks.your-domain.example

Certbot edits the nginx site to serve HTTPS and sets up automatic renewal. After it completes, browse to https://audiobooks.your-domain.example/.

Backups

Audiobookshelf has a built in backup feature under Settings, then Backups that snapshots the database and server settings into the metadata folder on the data disk. For disaster recovery, also take periodic Azure snapshots of the /usr/share/audiobookshelf data disk, that single disk holds the database, cached metadata and your media library.

Support

This image is commercially supported by cloudimg. We provide 24/7 technical support by email and chat for deployment, upgrades, library migration, transcoding configuration and TLS termination.

Audiobookshelf is a trademark of its respective owner. All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.