feat: add CoopCredits Solana media rewards ecosystem

Add complete token system with Plex/Tautulli/Overseer integration: - Anchor program for SPL token mint/burn/transfer - Express backend with OAuth, webhooks, Solana integration - Next.js frontend with dashboard, admin panel, wallet management - Docker deployment for 172.20.1.0/24 infrastructure - Production configs with SSL, Nginx, health monitoring Tautulli webhooks auto-mint on watch events. Overseer integration burns for content requests.
2026-04-14 11:09:50 -04:00
parent f106328f6a
commit e8d9b1fd42
69 changed files with 11382 additions and 0 deletions
@@ -0,0 +1,195 @@
+# 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
+
+```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
+- `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
+
+```bash
+# 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
+
+```bash
+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
+
+```bash
+# Start PostgreSQL
+docker-compose up -d postgres
+
+# Run migrations
+cd backend
+npx prisma migrate dev
+
+# Generate Prisma client
+npx prisma generate
+```
+
+### 6. Start Development
+
+```bash
+# 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
+
+```bash
+# 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
+```bash
+# Reset database
+docker-compose down -v
+docker-compose up -d postgres
+npx prisma migrate dev
+```
+
+### Solana Transaction Failures
+```bash
+# 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`