Deploying Audiobookshelf

Audiobookshelf is a powerful, open-source, self-hosted audiobook and podcast server that puts you in complete control of your audio library. With native mobile apps for Android and iOS, multi-user support, and seamless progress synchronization across all your devices, Audiobookshelf delivers a premium listening experience without subscription fees.

Built with Node.js and featuring a beautiful Vue.js web interface, Audiobookshelf can stream any audio format on-the-fly, automatically fetch metadata and cover art, and even manage podcasts with auto-download capabilities. With over 10,000 GitHub stars, it’s become the go-to solution for self-hosted audiobook enthusiasts.

Stream Any Format

Play all audio formats directly in your browser or mobile app

Mobile Apps

Native Android and iOS apps with offline listening support

Multi-User

Separate progress tracking and permissions per user

Podcast Support

Subscribe to podcasts with automatic episode downloads

Key Features

Audiobookshelf provides a comprehensive audiobook and podcast management solution:

Feature	Description
Chromecast Support	Cast to Chromecast devices from web and Android apps
Progress Sync	Automatic sync across all devices per user
Metadata Fetching	Automatically fetch book info and covers from multiple sources
Chapter Editor	Edit chapters with lookup via Audnexus API
Audio Merge	Combine multiple audio files into a single m4b
Embed Metadata	Write metadata and covers into your audio files
Ebook Support	Read ePub, PDF, CBR, CBZ with send-to-device (Kindle)
RSS Feeds	Generate RSS feeds for podcasts and audiobooks
Auto-Detection	Library auto-updates without manual rescanning

Supported Formats

Audio	Ebooks
MP3, M4A, M4B	ePub
FLAC, OGG, OPUS	PDF
WAV, WMA	CBR, CBZ
AAC, AIFF

Prerequisites

Before deploying Audiobookshelf on Klutch.sh, ensure you have:

• A Klutch.sh account with an active project
• A GitHub repository for your deployment configuration
• Your audiobook/podcast library ready to upload

Project Structure

Set up your Audiobookshelf deployment:

• Directoryaudiobookshelf/

  • Dockerfile
  • docker-compose.yml (local development)
  • README.md

Deployment Configuration

Dockerfile

Create a Dockerfile for your Audiobookshelf deployment:

Dockerfile

FROM ghcr.io/advplyr/audiobookshelf:latest

# Set timezone (adjust to your timezone)
ENV TZ=America/New_York

# Expose the internal port (container listens on port 80)
EXPOSE 80

# Create necessary directories
RUN mkdir -p /audiobooks /podcasts /config /metadata

# Default command is already set in base image

Custom Dockerfile with Additional Configuration

For more control over your deployment:

Dockerfile

FROM ghcr.io/advplyr/audiobookshelf:latest

# Environment configuration
ENV TZ=America/New_York
ENV NODE_ENV=production

# Create directory structure
RUN mkdir -p /audiobooks /podcasts /ebooks /config /metadata

# Set permissions
RUN chmod -R 755 /audiobooks /podcasts /ebooks /config /metadata

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1

EXPOSE 80

Environment Variables

Audiobookshelf supports extensive configuration through environment variables:

Variable	Default	Description
TZ	UTC	Server timezone
CONFIG_PATH	/config	Path to configuration directory
METADATA_PATH	/metadata	Path to metadata directory
PORT	80	Internal listening port
HOST	0.0.0.0	Host to bind to
ACCESS_TOKEN_EXPIRY	43200	Access token expiry in seconds (12 hours)
REFRESH_TOKEN_EXPIRY	604800	Refresh token expiry in seconds (7 days)
ALLOW_CORS	0	Enable CORS (set to 1)

Local Development with Docker Compose

Test your Audiobookshelf setup locally:

docker-compose.yml

services:
  audiobookshelf:
    image: ghcr.io/advplyr/audiobookshelf:latest
    container_name: audiobookshelf
    ports:
      - "13378:80"
    volumes:
      - ./audiobooks:/audiobooks
      - ./podcasts:/podcasts
      - ./ebooks:/ebooks
      - audiobookshelf-config:/config
      - audiobookshelf-metadata:/metadata
    environment:
      - TZ=America/New_York
    restart: unless-stopped

volumes:
  audiobookshelf-config:
  audiobookshelf-metadata:

Tip

Run docker compose up -d to start Audiobookshelf locally. Access it at http://localhost:13378 to create your initial admin account.

Deploying to Klutch.sh

1. Push your repository to GitHub

   1. Initialize your Git repository and commit the Dockerfile

   git init
   git add .
   git commit -m "Initial Audiobookshelf configuration"
   git remote add origin https://github.com/yourusername/audiobookshelf.git
   git push -u origin main

2. Create a new app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project or create a new one
   3. Click Create App and connect your GitHub repository
   4. Klutch.sh will automatically detect your Dockerfile

3. Configure environment variables

   1. In your app settings, add the following environment variables

   Variable	Value
   TZ	Your timezone (e.g., America/New_York)

4. Configure the internal port

   1. Set the internal port to 80 (Audiobookshelf’s default container port)
   2. Select HTTP as the traffic type

5. Set up persistent storage

   1. Add persistent volumes for your audiobook library and server data

   Mount Path	Size	Purpose
   /audiobooks	100 GB+	Your audiobook library (adjust based on collection)
   /podcasts	50 GB	Podcast episodes
   /ebooks	10 GB	Ebook files
   /config	1 GB	Database and user settings
   /metadata	10 GB	Covers, cache, backups, and logs

   Note

   The /config directory contains your SQLite database and must be on local storage, not network-mounted. Adjust volume sizes based on your library size.

6. Deploy your application

   1. Click Deploy to build and launch your Audiobookshelf server
   2. Monitor the build logs for any issues
   3. Once deployed, your server will be available at https://your-app.klutch.sh

7. Create your admin account

   1. Visit your deployed server URL
   2. Create your initial admin account on first access
   3. Set up your first library by pointing to your mounted directories

WebSocket Support

Audiobookshelf requires WebSocket connections for real-time features. Klutch.sh handles this automatically through its HTTPS proxy.

Initial Server Setup

Creating Your First Library

After your first login:

1. Click Settings (gear icon) → Libraries
2. Click Add Library
3. Choose library type: Audiobooks or Podcasts
4. Set the library name and folders:
   • Audiobooks: /audiobooks
   • Podcasts: /podcasts
   • Ebooks: Add /ebooks to an audiobook library
5. Click Create and let the scanner index your library

Recommended Directory Structure

Organize your audiobooks for optimal metadata detection:

/audiobooks/
├── Terry Goodkind/                          # Author folder
│   └── Sword of Truth/                      # Series folder
│       ├── Vol 1 - 1994 - Wizards First Rule/
│       │   ├── Audio Track 1.mp3
│       │   ├── Audio Track 2.mp3
│       │   └── cover.jpg
│       └── Vol 2 - 1995 - Stone of Tears/
│           └── Audiobook.m4b
└── Steven Levy/
    └── Hackers - Heroes of the Computer Revolution/
        └── Audiobook.m4a

Title Folder Naming Patterns

Audiobookshelf parses folder names for metadata:

Pattern	Example
Title only	Wizards First Rule
With narrator	Wizards First Rule {'{'}Sam Tsoutsouvas{'}'}
With year	1994 - Wizards First Rule
With series	Vol 1 - 1994 - Wizards First Rule
Full format	Vol. 1 - 1994 - Wizards First Rule - Subtitle {'{'}Narrator{'}'}

Mobile App Setup

Android App

1. Download from Google Play Store
2. Open the app and tap Add Server
3. Enter your server URL: https://your-app.klutch.sh
4. Log in with your credentials
5. Download books for offline listening

iOS App

1. Join the TestFlight beta
2. Install the app through TestFlight
3. Configure your server connection
4. Enjoy offline listening on your iOS device

Managing Podcasts

Adding a Podcast

1. Navigate to your Podcasts library
2. Click Add Podcast
3. Search by name or paste an RSS feed URL
4. Configure auto-download settings
5. Click Subscribe

Auto-Download Settings

Setting	Description
Auto Download	Enable automatic episode downloads
Max Episodes	Limit downloaded episodes to save space
Schedule	Set check interval (hourly, daily, etc.)

User Management

Creating Additional Users

1. Go to Settings → Users
2. Click Create User
3. Set username, password, and user type
4. Configure library access permissions

User Types

Type	Description
Admin	Full server access and configuration
User	Can access assigned libraries and features
Guest	Limited access, view-only

API Integration

Audiobookshelf provides a comprehensive REST API for integrations:

# Get all libraries
curl "https://your-app.klutch.sh/api/libraries" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get library items
curl "https://your-app.klutch.sh/api/libraries/{library-id}/items" \
  -H "Authorization: Bearer YOUR_TOKEN"

# Get listening progress
curl "https://your-app.klutch.sh/api/me/listening-sessions" \
  -H "Authorization: Bearer YOUR_TOKEN"

Full API documentation: api.audiobookshelf.org

Metadata Management

Fetching Metadata

1. Select a book in your library
2. Click Match to search providers
3. Choose from results: Audnexus, Google Books, Open Library, iTunes
4. Apply metadata and cover art

Embedding Metadata

Write metadata directly into your audio files:

1. Select books to update
2. Click Tools → Embed Metadata
3. Choose options (metadata, chapters, cover)
4. Process files

Backups and Restoration

Automatic Backups

Audiobookshelf creates automatic daily backups:

• Stored in /metadata/backups
• Contains database and metadata
• Configure retention in Settings → Backups

Manual Backup

1. Go to Settings → Backups
2. Click Create Backup
3. Download the backup file for off-site storage

Restoring from Backup

1. Go to Settings → Backups
2. Upload your backup file
3. Click Restore
4. Restart the server if prompted

Security Configuration

Strong Passwords

Use complex passwords for all user accounts

HTTPS Enabled

Klutch.sh provides automatic SSL certificates

Rate Limiting

Built-in protection against brute force attacks

Token Security

Secure JWT tokens with configurable expiry

Security Environment Variables

# Add to your Dockerfile for additional security
ENV ACCESS_TOKEN_EXPIRY=43200
ENV REFRESH_TOKEN_EXPIRY=604800
ENV RATE_LIMIT_AUTH_MAX=40
ENV RATE_LIMIT_AUTH_WINDOW=600000

Troubleshooting

Common issues and solutions:

Issue	Cause	Solution
Library not scanning	Wrong folder permissions	Ensure proper permissions on mounted volumes
No cover art	Metadata not fetched	Use Match feature to fetch from providers
Mobile app can’t connect	WebSocket issues	Verify HTTPS is working correctly
Progress not syncing	Token expired	Log out and back in on the mobile app
Audio not playing	Codec not supported	Convert to a supported format like M4B

Viewing Logs

Access logs in /metadata/logs or through the web interface:

1. Go to Settings → Logs
2. Filter by level (Error, Warning, Info, Debug)
3. Download logs for support requests

Performance Optimization

For Large Libraries

# Add SQLite optimizations for large libraries
ENV SQLITE_MMAP_SIZE=268435456
ENV SQLITE_CACHE_SIZE=10000

Transcoding Settings

Audiobookshelf transcodes audio on-the-fly. For better performance:

1. Go to Settings → General
2. Adjust Max Transcode Workers based on server CPU
3. Consider pre-converting to M4B for direct playback

Additional Resources

• Audiobookshelf Official Website
• Official Documentation
• GitHub Repository
• API Documentation
• Discord Community
• User Guides
• FAQ