mirror of
https://github.com/kikootwo/ReadMeABook.git
synced 2026-06-02 20:30:10 +00:00
Initial commit
This commit is contained in:
kikootwo
@@ -0,0 +1,339 @@
|
||||
# 📚 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:**
|
||||
```bash
|
||||
curl -O https://raw.githubusercontent.com/kikootwo/ReadMeABook/main/docker-compose.yml
|
||||
```
|
||||
|
||||
2. **Start the container:**
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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](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:**
|
||||
```bash
|
||||
openssl rand -base64 32
|
||||
```
|
||||
|
||||
### Reverse Proxy Setup
|
||||
|
||||
Example Nginx configuration:
|
||||
|
||||
```nginx
|
||||
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:
|
||||
```yaml
|
||||
environment:
|
||||
PUBLIC_URL: "https://readmeabook.example.com"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Updating
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Check logs for errors
|
||||
docker logs readmeabook
|
||||
|
||||
# Check container status
|
||||
docker ps -a | grep readmeabook
|
||||
```
|
||||
|
||||
### Database issues
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
# Test Redis connection
|
||||
docker exec readmeabook redis-cli ping
|
||||
# Should return: PONG
|
||||
```
|
||||
|
||||
### Reset everything (⚠️ Warning: Deletes all data)
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
docker exec readmeabook su - postgres -c \
|
||||
"pg_dump -h 127.0.0.1 -U readmeabook readmeabook" > backup.sql
|
||||
```
|
||||
|
||||
### Restore Database
|
||||
```bash
|
||||
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](docker-compose.local.yml)
|
||||
- **Debug Mode:** [docker-compose.debug.yml](docker-compose.debug.yml) (separate PostgreSQL/Redis containers)
|
||||
- **Documentation:** [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/](documentation/)
|
||||
- **Table of Contents:** [documentation/TABLEOFCONTENTS.md](documentation/TABLEOFCONTENTS.md)
|
||||
- **Agent Guidelines:** [AGENTS.md](AGENTS.md)
|
||||
- **Claude Guidelines:** [CLAUDE.md](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](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](https://github.com/kikootwo/ReadMeABook/issues)
|
||||
- **Discussions:** [GitHub Discussions](https://github.com/kikootwo/ReadMeABook/discussions)
|
||||
|
||||
---
|
||||
|
||||
**Made with ❤️ for audiobook enthusiasts**
|
||||
Reference in New Issue
Block a user