batman

docs/production.md

@@ -0,0 +1,122 @@
+# KoolTab Production Deployment
+
+## Option A: Docker (recommended)
+
+The production setup uses PostgreSQL and configurable secrets.
+
+### 1. Set environment variables
+
+Create `.env` in the project root:
+
+```env
+# Database
+DB_PASSWORD=<generate-a-strong-password>
+
+# JWT secrets — generate with: openssl rand -hex 64
+JWT_SECRET=<64-char-hex-string>
+JWT_REFRESH_SECRET=<64-char-hex-string>
+
+# URLs — set your actual domain/port
+DASHBOARD_URL=https://dashboard.yourdomain.com
+API_URL=https://api.yourdomain.com
+DASHBOARD_PORT=3000
+API_PORT=3001
+```
+
+### 2. Build and start
+
+```bash
+docker compose -f docker-compose.prod.yml up --build -d
+```
+
+### 3. Seed the database (first time only)
+
+```bash
+# Generate Prisma client and run migrations
+docker compose -f docker-compose.prod.yml exec api npx prisma migrate deploy
+
+# Seed demo data (or create your own venue/users)
+docker compose -f docker-compose.prod.yml exec api npx ts-node prisma/seed.ts
+```
+
+### 4. Set up a reverse proxy (nginx/Caddy)
+
+Example Caddyfile:
+```
+dashboard.yourdomain.com {
+    reverse_proxy dashboard:3000
+}
+
+api.yourdomain.com {
+    reverse_proxy api:3001
+}
+```
+
+---
+
+## Option B: Manual (Node.js + PostgreSQL)
+
+### 1. Install PostgreSQL
+
+Create database and user:
+```sql
+CREATE DATABASE kooltab;
+CREATE USER kooltab WITH PASSWORD 'your-password';
+GRANT ALL PRIVILEGES ON DATABASE kooltab TO kooltab;
+```
+
+### 2. Configure environment
+
+```env
+DATABASE_URL="postgresql://kooltab:your-password@localhost:5432/kooltab"
+JWT_SECRET="<random-64-char-string>"
+JWT_REFRESH_SECRET="<random-64-char-string>"
+PORT=3001
+CORS_ORIGIN="https://dashboard.yourdomain.com"
+```
+
+### 3. Update Prisma schema for PostgreSQL
+
+In `apps/api/prisma/schema.prisma`, change:
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+```
+
+### 4. Build and run
+
+```bash
+cd apps/api
+pnpm install
+npx prisma generate
+npx prisma migrate deploy
+pnpm build
+node dist/main
+```
+
+---
+
+## Migration Steps: SQLite → PostgreSQL
+
+1. Update `schema.prisma` to use `postgresql` provider
+2. Update `DATABASE_URL` environment variable
+3. Run `prisma migrate dev` to create initial PostgreSQL migration
+4. Export SQLite data and import to PostgreSQL (using `prisma db pull` + manual script, or insert via seed)
+5. Run `prisma migrate deploy` on production
+
+Key differences to handle:
+- SQLite uses `Int` for booleans → use `Boolean` in PostgreSQL
+- SQLite uses `String` for JSON → use `Json` type in PostgreSQL
+- UUID generation is handled by Prisma on both
+
+## Security Checklist
+
+- [ ] JWT secrets are 64+ random hex characters
+- [ ] DB_PASSWORD is strong and unique
+- [ ] HTTPS is terminated at reverse proxy
+- [ ] CORS_ORIGIN is set to the exact dashboard URL (no wildcard)
+- [ ] API is not exposed directly to the internet (reverse proxy only)
+- [ ] Rate limiting is configured
+- [ ] Audit logs are monitored