81 lines
3.9 KiB
Markdown
81 lines
3.9 KiB
Markdown
# 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:
|
|
```bash
|
|
docker network create web_traffic
|
|
```
|
|
2. Deploy the stack:
|
|
```bash
|
|
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.
|