coop/docs/SETUP-INFRASTRUCTURE.md

CoopCredits Setup for 172.20.1.0/24 Infrastructure

This guide covers setting up CoopCredits with your existing Plex/Tautulli/Overseer infrastructure.

Prerequisites

• Server running Docker and Docker Compose
• Access to 172.20.1.0/24 network
• API keys from Tautulli and Overseer
• Domain name (coop.hobokenchicken.com) pointing to your server
• Ko-fi account with store items set up (optional, for credit purchases)

Network Overview

┌─────────────────────────────────────────────────────────────────┐
│                     CoopCredits Server                           │
│                    (Your Server IP)                              │
│                         :443                                     │
└─────────────────────────────────┬───────────────────────────────┘
                                  │ HTTPS
        ┌─────────────────────────┼──────────────────────────┐
        │                         │                          │
        ▼                         ▼                          ▼
┌──────────────┐         ┌──────────────┐          ┌──────────────┐
│     Plex     │         │   Tautulli   │          │   Overseer   │
│172.20.1.220  │         │172.20.1.255  │          │172.20.1.225  │
│   :32400     │         │   :8181      │          │   :5055      │
└──────────────┘         └──────────────┘          └──────────────┘

Quick Start

1. Clone Repository

cd /opt
git clone <repository> coop-credits
cd coop-credits

2. Configure Environment

cp .env.example .env
nano .env

Required environment variables:

# Database
DATABASE_URL="postgresql://coop:coop_password@localhost:5432/coop_credits?schema=public"

# Server
PORT=3002
API_URL=https://coop.hobokenchicken.com
FRONTEND_URL=https://coop.hobokenchicken.com

# JWT Secret (generate: openssl rand -hex 32)
JWT_SECRET=your-random-secret

# Plex OAuth
PLEX_CLIENT_ID=your-plex-client-id
PLEX_CLIENT_SECRET=your-plex-client-secret
PLEX_REDIRECT_URI=https://coop.hobokenchicken.com/auth/callback

# Tautulli
TAUTULLI_URL=http://172.20.1.255:8181
TAUTULLI_API_KEY=your-tautulli-api-key

# Overseer
OVERSEER_URL=http://172.20.1.225:5055
OVERSEER_API_KEY=your-overseer-api-key

# Ko-fi (optional — for credit purchases)
KOFI_VERIFICATION_TOKEN=your-kofi-verification-token

# Security
ENCRYPTION_KEY=$(openssl rand -base64 32)

3. Deploy

docker-compose up -d --build

# Initialize database (first time only)
docker exec coop-backend npx prisma db push --accept-data-loss

4. Configure Caddy

See docs/CADDY-CONFIG.md. Key points:

• Backend runs on port 3002
• Use handle (not handle_path) for /api/*
• Proxy /webhooks/* to backend

5. Configure Tautulli Webhook

1. Open Tautulli: http://172.20.1.255:8181
2. Go to Settings > Notification Agents
3. Click Add a new notification agent > Webhook

Configuration:

• Webhook URL: https://coop.hobokenchicken.com/webhooks/tautulli
• Webhook Method: POST
• Content Type: application/json

JSON Payload:

{
  "action": "watched",
  "user_id": "{user_id}",
  "username": "{username}",
  "rating_key": "{rating_key}",
  "session_key": "{session_key}",
  "media_type": "{media_type}",
  "title": "{title}",
  "grandparent_title": "{grandparent_title}",
  "started": "{started}",
  "stopped": "{stopped}",
  "percent_complete": "{percent_complete}",
  "is_new": "{is_new}"
}

Triggers: Enable Watched

6. Configure Overseer Webhook

1. Open Overseer: http://172.20.1.225:5055
2. Go to Settings > Notifications
3. Enable Webhook

Configuration:

• Webhook URL: https://coop.hobokenchicken.com/webhooks/overseer
• Content Type: application/json

JSON Payload:

{
  "request_id": "{{request.id}}",
  "status": "{{request.status}}",
  "media_type": "{{media.media_type}}",
  "title": "{{media.title}}"
}

Events: Enable Request Approved and Request Declined

7. Configure Ko-fi Webhook (Optional)

1. Go to ko-fi.com → Settings > Webhooks
2. Set Webhook URL to: https://coop.hobokenchicken.com/webhooks/kofi
3. Save

Create store items:

• $5 item → link: https://ko-fi.com/s/YOUR_ITEM_ID
• $10 item → link: https://ko-fi.com/s/YOUR_ITEM_ID

Update frontend preset links in frontend/src/app/dashboard/components/BuyCreditsModal.tsx

8. Set Admin User

docker exec coop-postgres psql -U coop -d coop_credits -c "UPDATE users SET is_admin = true WHERE plex_username = 'YOUR_USERNAME';"

Verification

Test Connectivity

# Backend health
curl https://coop.hobokenchicken.com/health

# Test Tautulli webhook manually
curl -X POST https://coop.hobokenchicken.com/webhooks/tautulli \
  -H "Content-Type: application/json" \
  -d '{
    "action": "watched",
    "user_id": "12345",
    "username": "testuser",
    "rating_key": "1234",
    "session_key": "abc123",
    "media_type": "movie",
    "title": "Test Movie",
    "started": "'$(date +%s)'",
    "stopped": "'$(($(date +%s) + 3600))'",
    "percent_complete": "90"
  }'

Maintenance

Update Application

cd /opt/coop-credits
git pull
docker-compose up -d --build

Backup Database

docker exec -T coop-postgres pg_dump -U coop coop_credits > backup_$(date +%Y%m%d).sql

View Logs

# All services
docker-compose logs -f

# Specific service
docker-compose logs -f backend

Restart Services

docker-compose restart backend
docker-compose restart frontend

Security Checklist

• Changed default PostgreSQL password
• External reverse proxy (Caddy) configured for SSL
• Firewall rules configured
• JWT secret is random and secure
• Database not exposed externally
• Encryption key is random and backed up
• Ko-fi verification token set (if using purchases)

Support

For issues:

1. Check logs: docker-compose logs -f
2. Review environment variables
3. Verify all services are running: docker ps