coop/SETUP.md

CoopCredits Setup Guide

This guide will walk you through setting up the complete CoopCredits ecosystem.

Prerequisites

• Node.js 20+
• Docker & Docker Compose
• Solana CLI (for blockchain development)
• Anchor Framework (for Solana program deployment)

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
• PLEX_CLIENT_ID & PLEX_CLIENT_SECRET - From Plex.tv
• TAUTULLI_API_KEY - From Tautulli settings
• OVERSEER_API_KEY - From Overseer settings
• SOLANA_MINT_AUTHORITY_KEYPAIR - Will be generated in step 3

3. Solana Setup

# Run the Solana setup script
npm run setup:solana

# This will:
# - Install Solana CLI if needed
# - Create a devnet keypair
# - Request airdrop (2 SOL)
# - Output the private key for your .env file

Copy the SOLANA_MINT_AUTHORITY_KEYPAIR value into your .env file.

4. Deploy Solana Program

cd anchor-program

# Build the program
anchor build

# Deploy to devnet
anchor deploy

# Note the Program ID and update .env SOLANA_PROGRAM_ID

5. Database Setup

# Start PostgreSQL
docker-compose up -d postgres

# Run migrations
cd backend
npx prisma migrate dev

# Generate Prisma client
npx prisma generate

6. Start Development

# Start all services
npm run dev

# Or individually:
npm run dev:backend  # API on port 3001
npm run dev:frontend # Next.js on port 3000

7. Configure Tautulli Webhook

1. Open Tautulli Settings
2. Go to Notification Agents → Add Agent → Webhook
3. Configure:
   • Webhook URL: http://your-server:3001/webhooks/tautulli
   • Webhook Method: POST
   • JSON Payload: See webhook template in Admin Dashboard
4. Enable "Notify on Watched"

8. Production Deployment

# Setup SSL certificates
mkdir -p docker/nginx/ssl
cp your-cert.pem docker/nginx/ssl/cert.pem
cp your-key.pem docker/nginx/ssl/key.pem

# Deploy
npm run deploy

Architecture Overview

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   User Browser  │────▶│  Next.js (3000) │────▶│  Express (3001) │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                         ┌─────────────────┐           │
                         │  PostgreSQL     │◀──────────┘
                         │  (Database)     │
                         └─────────────────┘
                                ▲
                         ┌─────────────────┐
                         │  Solana Devnet  │
                         │  ($COOP Token)  │
                         └─────────────────┘
                                ▲
        ┌───────────────────────┴───────────────────────┐
        │                                               │
┌───────▼───────┐                             ┌────────▼──────┐
│  Tautulli     │                             │   Overseer    │
│ (Watch Events)│                             │  (Requests)   │
└───────────────┘                             └───────────────┘

User Flow

1. Login: User authenticates with Plex OAuth
2. Wallet: Auto-created Solana wallet (or connect existing)
3. Watch: Viewing on Plex → Tautulli triggers webhook
4. Earn: Backend validates → Mints $COOP tokens
5. Spend: Request content on Overseer → Deducts $COOP

Admin Features

Access /admin with an admin account to:

• View system analytics
• Manage users and grant bonuses
• Configure minting rates
• Pause/resume minting
• Monitor transactions

Troubleshooting

Database Connection Issues

# Reset database
docker-compose down -v
docker-compose up -d postgres
npx prisma migrate dev

Solana Transaction Failures

# Check balance
solana balance <pubkey>

# Request airdrop
solana airdrop 2 <pubkey>

Tautulli Webhook Not Working

1. Check webhook URL is accessible
2. Verify TAUTULLI_WEBHOOK_SECRET matches
3. Check backend logs: docker-compose logs backend

Security Considerations

1. Private Keys: 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
5. Rate Limiting: Nginx config includes rate limits

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