📚 ShelfLife

A feature-rich companion dashboard for Audiobookshelf.

Key Features • Quick Start (Local) • Docker Deployment • Mobile Deployment • Security Considerations

---

ShelfLife is a companion dashboard and mobile app designed for Audiobookshelf, a self-hosted audiobook and podcast server.

ShelfLife delivers real-time listening logs, advanced stats, library audits, ASIN matching tools, and deep active-session tracking. Think of Tautulli for Audiobookshelf.

Note

Disclaimer: ShelfLife is an independent, community-developed companion application. It is not affiliated with, endorsed by, or officially connected to the Audiobookshelf project.

📸 Click to view Dashboard Previews

🖥️ Desktop

📱 Mobile

🌟 Key Features

• 📊 Real-Time Listener Dashboard: Monitor system-wide listening statistics, server status, library sizes, and active listener sessions at a glance.
• 📈 Deep Listener Analytics: Visualize patterns with GitHub-style activity heatmaps, daily listening averages, completion rates, top genres, and device usage logs.
• 📚 Interactive Library Audits: Search and inspect your audiobooks across different libraries with responsive cover previews, duration info, and detail modals showing listening history and chapter listings.
• 🔍 Audnex Book Matching: Integrated ASIN (Audible) lookups that fetch metadata, descriptions, and chapters automatically to help you clean up and match your library's books.
• 📱 Native Android Integration: Built with Capacitor.

Note

🤖 Fully AI-Generated Project This project was 100 % generated by AI agents (vibe-coded).

⚙️ Quick Start (Local Run, as development server only)

Prerequisites

• Node.js (v18 or higher recommended)
• An active Audiobookshelf server instance

Step 1: Install Dependencies

Clone this repository to your system and install the required packages:

npm install

Step 2: Configure Environment Variables

Create a .env file in the root of the project using the template provided in .env.example:

cp .env.example .env

Open the .env file and configure it with your Audiobookshelf server details:

# Port where the ShelfLife server will run (default is 3000)
PORT=3000

# The URL of your Audiobookshelf instance
ABS_URL="https://audiobookshelf.example.com"

# Your Audiobookshelf API Token (admin dashboard or user token)
ABS_TOKEN="your_private_api_token"

# Optional: Custom headers in JSON format (e.g. for Cloudflare Access bypass)
# ABS_EXTRA_HEADERS='{"CF-Access-Client-Id": "xyz", "CF-Access-Client-Secret": "abc"}'

Step 3: Run the Development Server

Start both the backend proxy and the Vite development server simultaneously:

npm run dev

Visit the app in your browser at http://localhost:3000.

---

🐳 Docker Deployment

ShelfLife is fully containerized and can be easily deployed using Docker or Docker Compose. This is the recommended method for hosting ShelfLife on a home server or NAS.

Caution

Security Notice: The ShelfLife container runs an unauthenticated server proxy with administrative API tokens to your Audiobookshelf instance. Do not expose the ShelfLife container port directly to the internet without a secure authentication layer (like basic auth, Authelia, or Cloudflare Access) or VPN. See the Security Considerations section for best practices.

Option 1: Docker Compose (Recommended)

You can configure your environment variables in one of two ways:

• Via .env file (Recommended): Create a .env file in the same directory as docker-compose.yml and populate it (see Configure Environment Variables). Docker Compose will automatically read it.
• Directly in docker-compose.yml: Open docker-compose.yml and replace the ${VARIABLE} placeholders with your actual values under the environment: block (e.g., ABS_URL=https://audiobookshelf.example.com).

Once configured, run:

1. Start the container in detached mode:

   docker compose up -d

2. The dashboard will be accessible at http://localhost:3000 (or your configured PORT).

Option 2: Docker CLI

1. Build the production Docker image locally:

   docker build -t shelflife .

2. Start the container, loading your environmental configuration:

   docker run -d \
     -p 3000:3000 \
     --env-file .env \
     --name shelflife \
     --restart unless-stopped \
     shelflife

---

📱 Mobile Deployment (Android Native)

ShelfLife includes native mobile support via Capacitor.

Build and Install Automatically (via Bash Script)

If you have an Android device or emulator connected via USB and adb installed in your path, run the automated compile-and-install script:

chmod +x build-android.sh
./build-android.sh

---

Compile Manually

If you prefer to compile manually, follow these steps:

1. Build the static assets:

   npm run build

2. Sync the code to your native Capacitor Android project:

   npx cap sync android

3. Compile and launch: Open the /android folder in Android Studio to run, debug, or build a signed release APK of the app.

---

🔒 Security Considerations

Warning

Best Practices for Secure Deployment: The ShelfLife web server does not implement its own user authentication or management. To secure your setup against critical proxy risks—including open-proxy SSRF scans, unencrypted HTTP credential exposure, browser local storage leaks, and environmental token escalation:

1. Deploy behind an Authentication Layer: Always place the ShelfLife web server behind a secure reverse proxy (e.g., Caddy, Nginx, or a Cloudflare Tunnel) that terminates TLS/HTTPS and enforces access control (such as Basic Auth, Authelia, or Cloudflare Access).
2. Limit Network Access: Alternatively, restrict hosting to a private local network (LAN) or access the dashboard remotely via a secure VPN (WireGuard, Tailscale).

---

⚖️ License & Disclaimer

ShelfLife is an independent, community-developed companion application. It is not affiliated with, endorsed by, or officially connected to the Audiobookshelf project.

This project is licensed under the MIT License. See the LICENSE file for the full text.

Important

Liability and Warranty Disclaimer: The software is provided "AS IS", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software. Under no circumstances should this companion tool be deployed without appropriate network safety protections in place.