📚 ReadMeABook

An automated audiobook request and acquisition system that integrates with your Plex library.

ReadMeABook bridges the gap between your Plex audiobook library and automation tools like qBittorrent and Prowlarr. Request audiobooks through a web interface, and let ReadMeABook handle finding, downloading, and organizing them into your Plex library.

---

✨ Features

• 🔐 Plex Authentication - Seamless login with your existing Plex account
• 📖 Library Sync - Automatically scans and tracks your Plex audiobook library
• 🤖 AI-Powered Recommendations - BookDate: Get personalized audiobook suggestions based on your library and preferences
• 🔍 Smart Search - Finds audiobooks via Audible metadata and Prowlarr indexers
• ⚡ Automated Downloads - Integrates with qBittorrent for automatic acquisition
• 📊 Request Management - Track request status from search to library import
• 👥 Multi-User Support - Role-based access control (user/admin)
• 🎯 Intelligent Matching - Matches downloaded files to requested books
• 🔄 Background Jobs - Automated library scans, status checks, and cleanup

---

🚀 Quick Start

Prerequisites

• Docker (recommended) or Docker Compose
• Plex Media Server with an audiobook library
• qBittorrent - Download client for torrent management
• Prowlarr - Indexer aggregator for searching torrents

Option 1: Docker Compose (Recommended)

1. Download the compose file:

   curl -O https://raw.githubusercontent.com/kikootwo/ReadMeABook/main/docker-compose.yml
   

2. Start the container:

   docker compose up -d
   

3. Access the application: Open http://localhost:3030 in your browser

Note: The application automatically creates all required directories on first run.

Option 2: Docker Run

docker run -d \
  --name readmeabook \
  -p 3030:3030 \
  -v ./config:/app/config \
  -v ./cache:/app/cache \
  -v ./downloads:/downloads \
  -v ./media:/media \
  -v readmeabook-pgdata:/var/lib/postgresql/data \
  -v readmeabook-redis:/var/lib/redis \
  ghcr.io/kikootwo/readmeabook:latest

Note: Directories are automatically created on first run.

---

📁 Volume Mounts

Path	Description	Required
/app/config	Application configuration and logs	Yes
/app/cache	Temporary file cache	Yes
/downloads	qBittorrent download directory	Yes
/media	Plex audiobook library path	Yes
/var/lib/postgresql/data	PostgreSQL database	Yes
/var/lib/redis	Redis cache data	Yes

💡 Tip: The unified Docker image includes PostgreSQL and Redis built-in. For separate containers, see docker-compose.debug.yml.

---

⚙️ Initial Setup

After starting ReadMeABook for the first time:

1. Navigate to http://localhost:3030
2. Log in with Plex - First user automatically becomes admin
3. Configure Settings (Settings → Configuration):
   • Plex Server URL - Your Plex server address
   • Audiobook Library - Select your audiobook library
   • Prowlarr API - API URL and key for torrent searching
   • qBittorrent - Web UI URL and credentials for downloads
4. Scan Library - Click "Scan Library" to import existing audiobooks
5. Explore BookDate - Get AI-powered audiobook recommendations
6. Start Requesting - Search for audiobooks and submit requests

---

🔧 Configuration

Environment Variables (Optional)

Most variables have secure defaults generated automatically. Configure these only if needed:

Security (Auto-generated on first run)

• JWT_SECRET - JWT token signing secret
• JWT_REFRESH_SECRET - Refresh token signing secret
• CONFIG_ENCRYPTION_KEY - Database encryption key
• POSTGRES_PASSWORD - PostgreSQL password

Application

• PUBLIC_URL - Your public URL (e.g., https://readmeabook.example.com)
• LOG_LEVEL - Logging level: debug, info, warn, error (default: info)
• PLEX_CLIENT_IDENTIFIER - Custom Plex client ID (auto-generated if not set)

Database

• POSTGRES_USER - Database user (default: readmeabook)
• POSTGRES_DB - Database name (default: readmeabook)

Generate secure secrets:

openssl rand -base64 32

Reverse Proxy Setup

Example Nginx configuration:

server {
    listen 80;
    server_name readmeabook.example.com;

    location / {
        proxy_pass http://localhost:3030;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Don't forget to set the PUBLIC_URL environment variable in your docker-compose.yml:

environment:
  PUBLIC_URL: "https://readmeabook.example.com"

---

🔄 Updating

# Pull latest image
docker compose pull

# Restart with new image
docker compose up -d

# View logs
docker compose logs -f

Database migrations run automatically on startup.

---

📊 Resource Usage

The unified container typically uses:

• Memory: ~500MB-1GB (depending on usage)
• CPU: Low (spikes during library scans and downloads)
• Disk: Varies based on database size and Redis cache
• Image Size: ~3GB (includes PostgreSQL 16 + Redis + App)

---

🐛 Troubleshooting

Container won't start

# Check logs for errors
docker logs readmeabook

# Check container status
docker ps -a | grep readmeabook

Database issues

# Access PostgreSQL directly
docker exec -it readmeabook su - postgres -c "psql -h 127.0.0.1 -U readmeabook"

# Check database status
docker exec readmeabook su - postgres -c "pg_isready -h 127.0.0.1"

Redis issues

# Test Redis connection
docker exec readmeabook redis-cli ping
# Should return: PONG

Reset everything (⚠️ Warning: Deletes all data)

# Stop and remove container
docker compose down

# Remove volumes
docker volume rm readmeabook-pgdata readmeabook-redis

# Start fresh
docker compose up -d

---

📦 Backup & Restore

Backup Database

docker exec readmeabook su - postgres -c \
  "pg_dump -h 127.0.0.1 -U readmeabook readmeabook" > backup.sql

Restore Database

cat backup.sql | docker exec -i readmeabook su - postgres -c \
  "psql -h 127.0.0.1 -U readmeabook readmeabook"

---

🏗️ Development

For local development and debugging, see:

• Local Build: docker-compose.local.yml
• Debug Mode: docker-compose.debug.yml (separate PostgreSQL/Redis containers)
• Documentation: documentation/

Project Structure

readmeabook/
├── src/
│   ├── app/              # Next.js app router pages
│   ├── components/       # React components
│   ├── lib/              # Utilities and helpers
│   ├── services/         # Backend services (auth, jobs, config)
│   └── generated/        # Prisma client
├── prisma/
│   └── schema.prisma     # Database schema
├── documentation/        # Project documentation
├── docker/               # Docker configuration
└── public/               # Static assets

---

🆚 Deployment Options

Unified Container (Default - docker-compose.yml)

✅ Best for: Simple deployment, single-host, minimal configuration

• All services in one container (PostgreSQL + Redis + App)
• Easiest to deploy and manage
• Single container to update
• ~3GB image size

Multi-Container (docker-compose.debug.yml)

✅ Best for: Development, debugging, separate service scaling

• PostgreSQL, Redis, and App as separate containers
• Independent service management
• Better for development and testing
• More flexible but requires more configuration

---

🔐 Security Best Practices

1. Change default secrets in production (set environment variables)
2. Use HTTPS via reverse proxy (Nginx, Caddy, Traefik)
3. Restrict port access - only expose port 3030 to trusted networks
4. Keep container updated - pull latest images regularly
5. Backup database - regularly backup PostgreSQL data
6. Review user access - Manage user roles appropriately

---

📚 Documentation

• Full Documentation: documentation/
• Table of Contents: documentation/TABLEOFCONTENTS.md
• Agent Guidelines: AGENTS.md
• Claude Guidelines: CLAUDE.md

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues, feature requests, or pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📝 License

MIT License - see LICENSE for details

---

🙏 Acknowledgments

• Plex - Media server platform
• Prowlarr - Indexer manager
• qBittorrent - BitTorrent client
• Next.js - React framework
• Prisma - Database ORM
• PostgreSQL - Database
• Redis - Cache and job queue

---

📧 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

---

Made with ❤️ for audiobook enthusiasts