docs: update all documentation to reflect current project state
This commit is contained in:
@@ -1,13 +1,13 @@
|
||||
# CoopCredits Setup Guide
|
||||
|
||||
This guide will walk you through setting up the complete CoopCredits ecosystem.
|
||||
This guide walks 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)
|
||||
- Access to Plex, Tautulli, and Overseer instances
|
||||
- Domain name (for production)
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -31,48 +31,20 @@ nano .env
|
||||
|
||||
Required environment variables:
|
||||
- `DATABASE_URL` - PostgreSQL connection string
|
||||
- `JWT_SECRET` - Random string for JWT signing
|
||||
- `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
|
||||
- `SOLANA_MINT_AUTHORITY_KEYPAIR` - Will be generated in step 3
|
||||
- `ENCRYPTION_KEY` - For encrypting session data (openssl rand -base64 32)
|
||||
- `KOFI_VERIFICATION_TOKEN` - From Ko-fi settings (optional)
|
||||
|
||||
### 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
|
||||
### 3. Database Setup
|
||||
|
||||
```bash
|
||||
# Start PostgreSQL and Redis
|
||||
docker-compose up -d postgres redis
|
||||
|
||||
# Push schema to database (no migrations needed for fresh setup)
|
||||
# Push schema to database
|
||||
cd backend
|
||||
npx prisma db push
|
||||
|
||||
@@ -80,44 +52,34 @@ npx prisma db push
|
||||
npx prisma generate
|
||||
```
|
||||
|
||||
### 6. Start Development
|
||||
### 4. 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
|
||||
npm run dev:backend # API on port 3002
|
||||
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
|
||||
### 5. Production Deployment
|
||||
|
||||
```bash
|
||||
# Create public directory (required for build)
|
||||
mkdir -p frontend/public
|
||||
|
||||
# Deploy (Caddy handles SSL termination)
|
||||
# Deploy
|
||||
docker-compose up -d --build
|
||||
```
|
||||
|
||||
**Note:** This setup runs HTTP only on port 80. Place behind Caddy or another reverse proxy for SSL termination.
|
||||
**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 (3001) │
|
||||
│ User Browser │────▶│ Next.js (3000) │────▶│ Express (3002) │
|
||||
└─────────────────┘ └─────────────────┘ └─────────────────┘
|
||||
│
|
||||
┌─────────────────┐ │
|
||||
@@ -126,8 +88,8 @@ docker-compose up -d --build
|
||||
└─────────────────┘
|
||||
▲
|
||||
┌─────────────────┐
|
||||
│ Solana Devnet │
|
||||
│ ($COOP Token) │
|
||||
│ Ko-fi │
|
||||
│ (Purchases) │
|
||||
└─────────────────┘
|
||||
▲
|
||||
┌───────────────────────┴───────────────────────┐
|
||||
@@ -141,19 +103,20 @@ docker-compose up -d --build
|
||||
## 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
|
||||
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:
|
||||
- View system analytics
|
||||
- Manage users and grant bonuses
|
||||
- Configure minting rates
|
||||
- Pause/resume minting
|
||||
- Monitor transactions
|
||||
- **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
|
||||
|
||||
@@ -162,30 +125,26 @@ Access `/admin` with an admin account to:
|
||||
# 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>
|
||||
cd backend && npx prisma db push
|
||||
```
|
||||
|
||||
### Tautulli Webhook Not Working
|
||||
1. Check webhook URL is accessible
|
||||
2. Verify `TAUTULLI_WEBHOOK_SECRET` matches
|
||||
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. **Private Keys**: Never commit `.env` files
|
||||
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
|
||||
5. **Rate Limiting**: Nginx config includes rate limits
|
||||
4. **SSL**: Always use HTTPS in production (Caddy handles this)
|
||||
5. **Rate Limiting**: 1000 req/15min per IP
|
||||
|
||||
## Support
|
||||
|
||||
@@ -193,3 +152,4 @@ 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`
|
||||
|
||||
Reference in New Issue
Block a user