Book Services

​

Overview

​

Audiobookshelf

• Internal: https://audiobooks.giohosted.com
• External: https://audiobooks.giohosted.com (via Cloudflare Tunnel)

​

Features

• Web and mobile apps (iOS/Android)
• Progress tracking across devices
• Playback speed control and sleep timer
• Podcast support
• User management with individual libraries
• Chapter navigation
• OIDC authentication via Authentik

​

Library Configuration

/data/media/books/audiobooks/
├── Author Name/
│   └── Book Title/
│       ├── cover.jpg
│       └── Book Title.m4b
└── Another Author/
    └── Another Book/
        ├── cover.jpg
        └── Chapter 01.mp3
        └── Chapter 02.mp3

• M4B (preferred - single file with chapters)
• MP3
• M4A
• FLAC
• OGG

​

SSO Configuration

• Audiobookshelf may create duplicate users if sub claim changes
• Documented fix available in Authentik configuration

​

External Access

• Cloudflare Access with Authentik OIDC
• Access restricted to users and admins groups
• Valid authentication required for streaming

• iOS: Audiobookshelf app
• Android: Audiobookshelf app
• Configure server URL: https://audiobooks.giohosted.com

​

Calibre-Web-Automated (CWA)

​

Features

• Web-based ebook reader
• Metadata management via Calibre backend
• Automatic metadata fetching from multiple sources
• Format conversion (EPUB, MOBI, AZW3, PDF)
• User libraries with individual bookshelves
• Send to Kindle integration
• OAuth2 authentication via Authentik

​

Library Configuration

1. Organized by author and title
2. Metadata fetched and applied
3. Stored in Calibre database structure

/data/media/books/ebooks/
├── Author Name/
│   └── Book Title (ID)/
│       ├── cover.jpg
│       ├── metadata.opf
│       └── Book Title.epub
└── metadata.db  # Calibre database

​

Automated Workflow

1. Shelfmark hardlinks downloaded ebook to /data/downloads/books/ebooks/ingest/
2. CWA detects new file in ingest directory
3. Fetches metadata from configured sources
4. Imports to Calibre library at /data/media/books/ebooks/
5. Deletes hardlink from ingest directory
6. Original file in /data/downloads/books/ebooks/downloads/ continues seeding

​

SSO Configuration

• Users must link their Authentik account on first login
• Admin can pre-create accounts and users link during SSO

​

Shelfmark

• Internal: https://books.giohosted.com
• External: https://books.giohosted.com (via Cloudflare Tunnel)

​

Features

• Search interface for ebooks and audiobooks
• User requests sent to configured sources
• Status tracking for requests
• Integration with private trackers (MAM)
• Automatic download via qBittorrent
• Hardlink creation for library import

​

Integration

• qBittorrent (via Gluetun VPN)
• Calibre-Web-Automated (ebook import)
• Audiobookshelf (audiobook import)

1. User requests ebook via Shelfmark
2. Shelfmark searches indexers (e.g., MAM)
3. Best match sent to qBittorrent
4. qBittorrent downloads to /data/downloads/books/ebooks/downloads/
5. Shelfmark creates hardlink to /data/downloads/books/ebooks/ingest/
6. CWA imports from ingest directory
7. CWA deletes hardlink after import
8. Original file continues seeding in downloads directory

1. User requests audiobook via Shelfmark
2. Shelfmark searches indexers
3. Download sent to qBittorrent
4. qBittorrent downloads to /data/downloads/books/audiobooks/downloads/
5. Shelfmark creates hardlink to /data/media/books/audiobooks/
6. Audiobookshelf scans and adds to library
7. Original file continues seeding in downloads directory

​

External Access

• Cloudflare Access with Authentik OIDC
• Access restricted to authorized users
• Request submissions logged and tracked

​

Storage Architecture

​

Directory Structure

/data/
├── media/books/
│   ├── ebooks/              # CWA Calibre library (canonical)
│   │   ├── Author/Book/
│   │   └── metadata.db
│   └── audiobooks/          # Audiobookshelf library
│       └── Author/Book/
└── downloads/books/
    ├── ebooks/
    │   ├── downloads/       # qBit seeds from here (permanent)
    │   └── ingest/          # CWA imports from here (temporary)
    └── audiobooks/
        └── downloads/       # qBit seeds from here (permanent)

​

Hardlink Workflow Explained

• Hardlink = same file with two directory entries
• Deleting one directory entry doesn’t delete the file
• File only deleted when all hardlinks removed
• qBit sees original download path unchanged

# Check hardlink status
stat /data/downloads/books/ebooks/downloads/book.epub
stat /data/downloads/books/ebooks/ingest/book.epub
# Matching inode = hardlinked
# Different inode = copied (WRONG - breaks seeding)

​

MAM Seeding Requirements

seeding:
  categories:
    books-ebooks: 14d
    books-audiobooks: 14d

• qBitrr automatically stops seeding
• Torrent removed from qBittorrent
• File remains in downloads directory (manual cleanup or automated script)

​

SSO and External Access

​

Audiobookshelf

• Users authenticate with Authentik credentials
• Accounts automatically created on first login
• Access controlled via Cloudflare Access policies

1. Open Audiobookshelf app
2. Enter server URL: https://audiobooks.giohosted.com
3. Tap “Login with SSO”
4. Authenticate via Authentik
5. Mobile app receives session token

​

Calibre-Web-Automated

• Manual user linking required
• Admin creates user accounts in CWA
• Users link Authentik account on first OAuth login

​

Shelfmark

• Protected via Cloudflare Access policies
• Authentik OIDC for user authentication
• Access restricted to users and admins groups

​

Backup Strategy

• /opt/appdata/audiobookshelf/
• /opt/appdata/calibre-web-automated/
• /opt/appdata/shelfmark/
• Backed up nightly to NAS /backups via rsync script

• Calibre library: /data/media/books/ebooks/ (on NAS parity array)
• Audiobook library: /data/media/books/audiobooks/ (on NAS parity array)
• Protected by Unraid dual parity
• Included in nightly Synology ABB cold copy