From 9516f5d5707cd5aba2213e1be7e2d798a98ec8a1 Mon Sep 17 00:00:00 2001
From: hobokenchicken <dustin@dustin.coffee>
Date: Wed, 15 Apr 2026 14:21:37 -0400
Subject: [PATCH] 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               | 27 ++++++++++-----
 SETUP.md                | 21 +++++++-----
 docs/TROUBLESHOOTING.md | 74 ++++++++++++++++++++++++++++++++++++++++-
 3 files changed, 105 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index d3cf676..91bc88c 100644
--- a/README.md
+++ b/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
-# Edit backend/.env with your values
+cp .env.example .env
+# Edit .env with your values (see docs/SETUP-INFRASTRUCTURE.md)
 
-# 3. Start with Docker Compose
-docker-compose up -d
+# 3. Create required directories
+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
diff --git a/SETUP.md b/SETUP.md
index 746d0c5..c1cd7be 100644
--- a/SETUP.md
+++ b/SETUP.md
@@ -69,12 +69,12 @@ anchor deploy
 ### 5. Database Setup
 
 ```bash
-# Start PostgreSQL
-docker-compose up -d postgres
+# Start PostgreSQL and Redis
+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
-cp your-key.pem docker/nginx/ssl/key.pem
+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"
+
+# Create public directory (required for build)
+mkdir -p frontend/public
 
 # Deploy
-npm run deploy
+docker-compose up -d --build
 ```
 
 ## Architecture Overview
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 8afe811..487414d 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/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
    ```