156 lines
5.2 KiB
Markdown
156 lines
5.2 KiB
Markdown
# CoopCredits Setup Guide
|
|
|
|
This guide walks you through setting up the complete CoopCredits ecosystem.
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js 20+
|
|
- Docker & Docker Compose
|
|
- Access to Plex, Tautulli, and Overseer instances
|
|
- Domain name (for production)
|
|
|
|
## Quick Start
|
|
|
|
### 1. Clone and Install
|
|
|
|
```bash
|
|
git clone <repository>
|
|
cd coop-credits
|
|
npm run install:all
|
|
```
|
|
|
|
### 2. Environment Configuration
|
|
|
|
```bash
|
|
# Copy example environment file
|
|
cp .env.example .env
|
|
|
|
# Edit with your values
|
|
nano .env
|
|
```
|
|
|
|
Required environment variables:
|
|
- `DATABASE_URL` - PostgreSQL connection string
|
|
- `JWT_SECRET` - Random string for JWT signing (openssl rand -hex 32)
|
|
- `PLEX_CLIENT_ID` & `PLEX_CLIENT_SECRET` - From Plex.tv
|
|
- `TAUTULLI_API_KEY` - From Tautulli settings
|
|
- `OVERSEER_API_KEY` - From Overseer settings
|
|
- `ENCRYPTION_KEY` - For encrypting session data (openssl rand -base64 32)
|
|
- `KOFI_VERIFICATION_TOKEN` - From Ko-fi settings (optional)
|
|
|
|
### 3. Database Setup
|
|
|
|
```bash
|
|
# Start PostgreSQL and Redis
|
|
docker-compose up -d postgres redis
|
|
|
|
# Push schema to database
|
|
cd backend
|
|
npx prisma db push
|
|
|
|
# Generate Prisma client
|
|
npx prisma generate
|
|
```
|
|
|
|
### 4. Start Development
|
|
|
|
```bash
|
|
# Start all services
|
|
npm run dev
|
|
|
|
# Or individually:
|
|
npm run dev:backend # API on port 3002
|
|
npm run dev:frontend # Next.js on port 3000
|
|
```
|
|
|
|
### 5. Production Deployment
|
|
|
|
```bash
|
|
# Create public directory (required for build)
|
|
mkdir -p frontend/public
|
|
|
|
# Deploy
|
|
docker-compose up -d --build
|
|
```
|
|
|
|
**Note:** This runs HTTP internally. Place behind Caddy or another reverse proxy for SSL termination. Backend runs on port 3002.
|
|
|
|
## Architecture Overview
|
|
|
|
```
|
|
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
|
|
│ User Browser │────▶│ Next.js (3000) │────▶│ Express (3002) │
|
|
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
|
│
|
|
┌─────────────────┐ │
|
|
│ PostgreSQL │◀──────────┘
|
|
│ (Database) │
|
|
└─────────────────┘
|
|
▲
|
|
┌─────────────────┐
|
|
│ Ko-fi │
|
|
│ (Purchases) │
|
|
└─────────────────┘
|
|
▲
|
|
┌───────────────────────┴───────────────────────┐
|
|
│ │
|
|
┌───────▼───────┐ ┌────────▼──────┐
|
|
│ Tautulli │ │ Overseer │
|
|
│ (Watch Events)│ │ (Requests) │
|
|
└───────────────┘ └───────────────┘
|
|
```
|
|
|
|
## User Flow
|
|
|
|
1. **Login**: User authenticates with Plex OAuth
|
|
2. **Backfill**: First login triggers 30-day Tautulli history import
|
|
3. **Watch**: Viewing on Plex → Tautulli triggers webhook → $COOP credited to DB
|
|
4. **Earn**: Real-time balance updates on dashboard via Socket.io
|
|
5. **Spend**: Request content on Overseer → $COOP deducted from DB balance
|
|
6. **Buy**: Ko-fi purchase → Webhook → $COOP added to DB balance
|
|
|
|
## Admin Features
|
|
|
|
Access `/admin` with an admin account to:
|
|
- **The Flock** — User list with search, bonuses, backfill, promote/demote
|
|
- **Barn Rules** — Edit credits per minute, watch thresholds, request costs
|
|
- **Donations** — View Ko-fi payment history
|
|
- **The Feed Queue** — All content requests with Overseer sync button
|
|
- **Egg Stats** — Analytics cards (users, total credits, requests, pending)
|
|
|
|
## Troubleshooting
|
|
|
|
### Database Connection Issues
|
|
```bash
|
|
# Reset database
|
|
docker-compose down -v
|
|
docker-compose up -d postgres
|
|
cd backend && npx prisma db push
|
|
```
|
|
|
|
### Tautulli Webhook Not Working
|
|
1. Check webhook URL is accessible
|
|
2. Verify `TAUTULLI_WEBHOOK_SECRET` matches (optional)
|
|
3. Check backend logs: `docker-compose logs backend`
|
|
|
|
### Request Stuck on PENDING
|
|
1. Check Overseer webhook is configured
|
|
2. Use admin dashboard **The Feed Queue** → **SYNC** button
|
|
3. Or use dashboard **Requests** tab → refresh button
|
|
|
|
## Security Considerations
|
|
|
|
1. **Never commit `.env` files**
|
|
2. **JWT Secret**: Use a strong random string (32+ chars)
|
|
3. **Encryption Key**: Use `openssl rand -base64 32`
|
|
4. **SSL**: Always use HTTPS in production (Caddy handles this)
|
|
5. **Rate Limiting**: 1000 req/15min per IP
|
|
|
|
## Support
|
|
|
|
For issues or questions:
|
|
1. Check logs: `docker-compose logs -f`
|
|
2. Review environment variables
|
|
3. Verify all services are running: `docker-compose ps`
|
|
4. Check `docs/TROUBLESHOOTING.md`
|