coop/SETUP.md

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

git clone <repository>
cd coop-credits
npm run install:all

2. Environment Configuration

# 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

# 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

# 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

# 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

# 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