docs: Update setup and troubleshooting guides

- Add Docker build troubleshooting section
- Update Quick Start with SSL cert and public dir steps
- Add prisma db push instruction for database setup
- Document common build errors and solutions

README.md

@@ -28,22 +28,33 @@ A complete Solana-based rewards system integrated with Plex, Tautulli, and Overs
 
 ```bash
 # 1. Clone and install dependencies
+git clone <repository> coop-credits
 cd coop-credits
 npm install
 
 # 2. Set up environment
-cp backend/.env.example backend/.env
+cp .env.example .env
-# Edit backend/.env with your values
+# Edit .env with your values (see docs/SETUP-INFRASTRUCTURE.md)
 
-# 3. Start with Docker Compose
+# 3. Create required directories
-docker-compose up -d
+mkdir -p docker/nginx/ssl
+mkdir -p frontend/public
 
-# 4. Deploy Solana program
+# 4. Generate SSL certificates (self-signed for local dev)
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout docker/nginx/ssl/key.pem \
+  -out docker/nginx/ssl/cert.pem \
+  -subj "/CN=localhost"
+
+# 5. Start with Docker Compose
+docker-compose up -d --build
+
+# 6. Initialize database (first time only)
+docker-compose exec backend npx prisma db push
+
+# 7. Deploy Solana program (optional, for token features)
 cd anchor-program
 anchor deploy
-
-# 5. Seed initial data
-npm run db:seed
 ```
 
 ## Project Structure

SETUP.md

@@ -69,12 +69,12 @@ anchor deploy
 ### 5. Database Setup
 
 ```bash
-# Start PostgreSQL
+# Start PostgreSQL and Redis
-docker-compose up -d postgres
+docker-compose up -d postgres redis
 
-# Run migrations
+# Push schema to database (no migrations needed for fresh setup)
 cd backend
-npx prisma migrate dev
+npx prisma db push
 
 # Generate Prisma client
 npx prisma generate
@@ -104,13 +104,18 @@ npm run dev:frontend # Next.js on port 3000
 ### 8. Production Deployment
 
 ```bash
-# Setup SSL certificates
+# Setup SSL certificates (self-signed for local dev, or use real certs)
 mkdir -p docker/nginx/ssl
-cp your-cert.pem docker/nginx/ssl/cert.pem
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
-cp your-key.pem docker/nginx/ssl/key.pem
+  -keyout docker/nginx/ssl/key.pem \
+  -out docker/nginx/ssl/cert.pem \
+  -subj "/CN=coop.hobokenchicken.com"
+
+# Create public directory (required for build)
+mkdir -p frontend/public
 
 # Deploy
-npm run deploy
+docker-compose up -d --build
 ```
 
 ## Architecture Overview

docs/TROUBLESHOOTING.md

@@ -170,6 +170,78 @@ sudo mkswap /swapfile
 sudo swapon /swapfile
 ```
 
+## Docker Build Issues
+
+### Backend Build Fails: Cannot redeclare block-scoped variable
+
+**Error:** `error TS2451: Cannot redeclare block-scoped variable 'signature'`
+
+**Solution:** Fixed in source. If you see this, pull the latest code.
+
+### Backend: Prisma Client could not locate Query Engine
+
+**Error:** `PrismaClientInitializationError: Prisma Client could not locate the Query Engine`
+
+**Solution:**
+```bash
+# Regenerate Prisma client with correct binary target
+cd backend
+npx prisma generate
+
+# Rebuild backend container
+docker-compose up -d --build backend
+```
+
+### Frontend Build Fails: Module not found
+
+**Error:** `Module not found: Can't resolve '@/components/ui/...'`
+
+**Solution:** Ensure `tsconfig.json` has correct paths:
+```json
+"paths": {
+  "@/*": ["./src/*"]
+}
+```
+
+### Frontend: Prerender Error on /login
+
+**Error:** `Error occurred prerendering page "/login"`
+
+**Solution:** This was caused by zustand persist middleware accessing localStorage during SSR. Fixed by wrapping providers with dynamic import `ssr: false`.
+
+### Frontend: Cannot find module 'next-themes'
+
+**Error:** `Module not found: Can't resolve 'next-themes'`
+
+**Solution:** 
+```bash
+cd frontend
+npm install next-themes
+```
+
+### Nginx: SSL Certificate Error
+
+**Error:** `cannot load certificate "/etc/nginx/ssl/cert.pem"`
+
+**Solution:**
+```bash
+mkdir -p docker/nginx/ssl
+openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
+  -keyout docker/nginx/ssl/key.pem \
+  -out docker/nginx/ssl/cert.pem \
+  -subj "/CN=coop.hobokenchicken.com"
+```
+
+### Docker Compose: Public Directory Not Found
+
+**Error:** `failed to calculate checksum: "/app/frontend/public": not found`
+
+**Solution:**
+```bash
+mkdir -p frontend/public
+touch frontend/public/.gitkeep
+```
+
 ## Getting Help
 
 1. Check health status:
@@ -190,5 +262,5 @@ sudo swapon /swapfile
 4. Verify environment:
    ```bash
    # Check all required env vars are set
-grep -E '^\w+=' .env | wc -l
+   grep -E '^\w+=' .env | wc -l
    ```