Skip to content

DEPLOY.md

Latest commit

 

History

History
252 lines (191 loc) · 7.34 KB

DEPLOY.md

File metadata and controls

252 lines (191 loc) · 7.34 KB

Prism Deployment Guide

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│   Vercel     │────▶│   Railway    │────▶│   Supabase      │
│  (Next.js)   │ WS  │  (Go API)    │     │  (PostgreSQL +  │
│  prism-web/  │◀────│  prism/      │     │   pgvector)     │
└─────────────┘     └──────┬───────┘     └─────────────────┘
                           │
                    ┌──────┴───────┐
                    │  External    │
                    │  APIs        │
                    ├──────────────┤
                    │ OpenAI       │ TTS, GPT-4o analysis, embeddings
                    │ Deepgram     │ Speech-to-text
                    └──────────────┘

Frontend (Vercel): Next.js 15 + React 19 + Tailwind v4 + Framer Motion Backend (Railway): Go HTTP/WebSocket server, eino LLM orchestration Database (Supabase): PostgreSQL 15+ with pgvector for semantic search

Prerequisites

Tool Purpose Install
railway Backend deploy npm i -g @railway/cli
vercel Frontend deploy npm i -g vercel
supabase Database setup brew install supabase/tap/supabase
jq JSON parsing brew install jq / apt install jq
go >= 1.21 Backend build golang.org/dl
node >= 18 Frontend build nodejs.org
pnpm Package manager npm i -g pnpm

API Keys

Key Required Purpose
OPENAI_API_KEY Recommended TTS voice output, GPT-4o post-session analysis, pgvector embeddings
DEEPGRAM_API_KEY Optional Voice input (speech-to-text). Without it, text-only mode

The server starts in degraded mode without API keys — all features degrade gracefully.

Quick Start (Automated)

./scripts/setup.sh

This interactive script walks through:

  1. Prerequisites check
  2. API key collection with format validation
  3. Supabase project creation + pgvector
  4. Railway backend deployment with env vars
  5. Vercel frontend deployment with env vars
  6. Health endpoint verification
  7. Summary with all URLs

Manual Deploy

1. Database (Supabase)

# Create project
supabase projects create prism --region us-east-1

# Get connection string from Dashboard → Settings → Database
# Format: postgres://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres

# Enable pgvector (run in SQL Editor)
CREATE EXTENSION IF NOT EXISTS vector;

Migrations run automatically on server startup.

2. Backend (Railway)

cd prism

# Initialize and link
railway login
railway init --name prism-backend

# Set environment variables
railway variables set \
  DATABASE_URL="postgres://..." \
  OPENAI_API_KEY="sk-..." \
  DEEPGRAM_API_KEY="..." \
  PORT=8080

# Deploy
railway up

# Get the public URL
railway domain

The Go server auto-runs migrations on startup and initializes all available services.

3. Frontend (Vercel)

cd prism-web

# Install dependencies
pnpm install

# Link and configure
vercel link
vercel env add BACKEND_URL production   # Railway URL (https://...)
vercel env add NEXT_PUBLIC_API_URL production  # Same Railway URL

# Deploy
vercel --prod

The Next.js app proxies /api/* and /ws/* to the backend via rewrites in next.config.ts.

4. Verify

# Health check (should show all services)
curl https://your-railway-url.up.railway.app/api/health | jq

# Expected response:
# {
#   "status": "ok",
#   "service": "prism",
#   "services": {
#     "database": true,
#     "tts": true,
#     "stt": true,
#     "embeddings": true,
#     "analyzer": true
#   }
# }

Terraform (IaC)

For reproducible infrastructure provisioning:

cd infra/terraform

# Copy and fill in variables
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values

terraform init
terraform plan
terraform apply

This provisions Supabase and Vercel. Railway is deployed via CLI (community Terraform provider is immature).

See infra/terraform/ for full configuration.

Local Kubernetes (Mac Mini)

For self-hosting on a Mac Mini with minikube + Cloudflare Tunnels:

cd infra/k8s

# Automated setup
./scripts/local-setup.sh

# Or manual:
minikube start --driver=docker --cpus=4 --memory=8g
minikube addons enable ingress

# Create .env file with your secrets
cat > .env << 'EOF'
DATABASE_URL=postgres://postgres:password@postgres.prism.svc.cluster.local:5432/prism?sslmode=disable
OPENAI_API_KEY=sk-...
DEEPGRAM_API_KEY=...
POSTGRES_PASSWORD=your-secure-password
EOF

kubectl create namespace prism
kubectl create secret generic prism-secrets --from-env-file=.env -n prism
kubectl apply -k .

See infra/k8s/ for full manifests and Cloudflare Tunnel configuration.

Environment Variable Reference

Variable Service Required Description
DATABASE_URL Backend Yes PostgreSQL connection string
OPENAI_API_KEY Backend Recommended Enables TTS, analysis, embeddings
DEEPGRAM_API_KEY Backend Optional Enables voice input (STT)
PORT Backend No HTTP port (default: 8080)
BACKEND_URL Frontend Yes Backend URL for Next.js rewrites
NEXT_PUBLIC_API_URL Frontend Production Direct backend URL (bypasses rewrites)
NEXT_PUBLIC_BASE_URL Frontend No Frontend URL for OpenGraph tags

Verification Checklist

  • curl $BACKEND/api/health returns {"status":"ok"}
  • services.database is true
  • Frontend loads at Vercel URL
  • Can start an interview session (WebSocket connects)
  • Voice input works (if Deepgram key set)
  • TTS audio plays (if OpenAI key set)
  • Dashboard shows sessions
  • Topics page shows mastery heatmap

Troubleshooting

WebSocket connection fails

  • Ensure NEXT_PUBLIC_API_URL is set in Vercel env vars
  • Railway must have a public domain assigned (railway domain)
  • Check CORS: backend allows all origins by default

Database connection fails

  • Verify DATABASE_URL format includes ?sslmode=require for Supabase
  • Check Railway logs: railway logs
  • Ensure pgvector extension is enabled: SELECT * FROM pg_extension WHERE extname = 'vector';

Voice features not working

  • TTS requires OPENAI_API_KEY — check for "TTS client initialized" in logs
  • STT requires DEEPGRAM_API_KEY — check for "Deepgram STT configured" in logs
  • Browser must grant microphone permission
  • Mobile Safari requires user gesture to unlock AudioContext

Health endpoint shows "degraded"

  • Check which services are false
  • Missing API keys cause graceful degradation, not failure
  • Only database: false indicates a real problem

Frontend build fails

  • Must run from prism-web/ directory
  • Requires pnpm install first
  • Next.js 15 requires Node.js >= 18

Local development

# Start PostgreSQL
docker compose up -d

# Start backend (auto-runs migrations)
cd prism && go run ./cmd/server

# Start frontend (proxies to localhost:8080)
cd prism-web && pnpm dev