Audiobookshelf Deployment

This repository contains the deployment configuration for Audiobookshelf, a self-hosted audiobook and podcast server. It leverages a CI/CD pipeline via Woodpecker CI and integrates with a cloud-backed storage solution for long-term archiving.

🏗️ Architecture Overview

The deployment is designed with a "separation of concerns" approach:

• Containerization: Managed via Docker Compose.
• Networking: Integrated into a web_traffic external network, designed to sit behind a reverse proxy (e.g., Caddy) for SSL termination.
• Storage: A hybrid approach using local SSDs for active metadata/config and an Rclone-mounted Google Drive for the main library.
• CI/CD: Automated deployment via Woodpecker CI on every push to the main branch.

📂 Repository Structure

• docker-compose.yaml: Defines the application service, volumes, and network bridge.
• .woodpecker.yaml: Automation script for deployment to the host server.

📚 Cloud Storage Setup

This server uses Rclone and FUSE to bridge Google Drive with Audiobookshelf, allowing for a massive library with a minimal local storage footprint.

☁️ Cloud Integration (Rclone)

The system mounts a Google Drive subdirectory as a local filesystem. It utilizes a VFS (Virtual File System) Cache to make remote files behave like local ones, which is critical for smooth metadata scanning.

Mount Details

• Source: gdrive:audiobooks
• Local Destination: /home/george/google-drive
• Cache Mode: full (Allows the app to interact with files before they are fully downloaded)
• Optimization: Includes --dir-cache-time 1000h to ensure the folder structure remains snappy and reduces API calls to Google.

Fail-Safe Mechanism

To prevent Audiobookshelf from wiping its database if the connection drops, the service includes Forceful Cleanup logic. Before starting, it attempts to unmount any "zombie" connections to ensure the mount point is clean and ready.

---

🛠️ Management & Maintenance

The mount is managed by a systemd service (rclone-gdrive.service) to ensure high availability and automatic recovery.

Task	Command
Check Health	sudo systemctl status rclone-gdrive
Restart Mount	sudo systemctl restart rclone-gdrive
Apply Config Changes	sudo systemctl daemon-reload && sudo systemctl restart rclone-gdrive
Emergency Unmount	sudo fusermount -uz ~/google-drive
Refresh API Token	rclone config reconnect gdrive:
Test Cloud Link	rclone lsd gdrive:

---

⚠️ Troubleshooting: The "Missing Library" Issue

If Audiobookshelf shows 0 books, the Google Drive API token has likely expired (a common occurrence with Google's Oauth security).

1. Check Logs: Run journalctl -u rclone-gdrive.service -n 50. Look for invalid_grant or token expired.
2. Re-authenticate: Run rclone config reconnect gdrive: and follow the headless authentication prompts.
3. Verify Mount: Ensure files are visible on the host via ls ~/google-drive.
4. Sync ABS: Trigger a Library Scan in the Audiobookshelf Web UI to re-link the database.

Note on Moving Books: To move a book from the local SSD to the Cloud Archive, use: mv ~/audiobookshelf/audiobooks/AuthorName ~/google-drive/ The --vfs-cache-mode full flag will handle the upload to Google Drive in the background.

🚀 Deployment

Manual Setup

1. Ensure the web_traffic network exists:

   docker network create web_traffic
   

2. Deploy the stack:

   docker compose up -d
   

CI/CD Workflow

The Woodpecker pipeline automates the following on every push:

1. Copies the repository files to the deployment directory on the host.
2. Triggers a docker compose up -d --pull always --force-recreate to ensure the latest image and configuration are live.