# 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.