hobokenchicken
e8d9b1fd42
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.
196 lines
5.3 KiB
Markdown
196 lines
5.3 KiB
Markdown
# 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`
|