Deployment Guide
How to deploy the application
Production Stack
| Service | Provider | Purpose |
|---|---|---|
| Hosting | Coolify | Container build, deploy, and runtime orchestration |
| CI/CD | Coolify auto-deploy | Production build and deploy trigger from deploy/coolify-live |
| Database | Neon | PostgreSQL with branching |
| Storage | Cloudflare R2 | File uploads |
| Auth | Custom JWT | User authentication |
| Payments | Stripe | Subscriptions and billing |
| Queue | BullMQ / Redis | Background jobs |
| Cache | Fleet Redis or Upstash Redis | Distributed cache and rate limiting |
| Monitoring | Sentry | Error and performance monitoring |
Deployment Process
Standard Deployment
-
Push to the Coolify deploy branch
git push origin deploy/coolify-live -
Coolify deploys
- Coolify watches
deploy/coolify-livethrough the GitHub app/deploy key. - Each push pulls the branch, builds the Dockerfile, and deploys on the app server.
- No GitHub workflow is part of the production path.
- Coolify watches
Manual Deployment
Use the Coolify dashboard to trigger a manual rebuild/deploy for the application.
Pre-Deployment Checklist
Code Quality
- All tests passing (
npm run test:run) - No TypeScript errors (
npm run type-check) - Linting passes (
npm run lint) - Build succeeds locally (
npm run build) - Production Docker image builds in Coolify
Database
- Migrations are up to date
- No pending schema changes
- Backup verified
Environment
- Coolify environment variables are configured
- Coolify builder has enough memory for the production Docker build
- API keys rotated if needed
- Feature flags set correctly
Database Migrations
Create Migration (Development)
npx prisma migrate dev --name <descriptive_name>
Deploy Migration (Production)
npx prisma migrate deploy
The production container includes Prisma CLI support so migrations can run from the Coolify release command or a one-off container command.
Rollback Procedures
Coolify Rollback
- Open the Coolify project deployment history.
- Select the last known-good deployment.
- Redeploy or roll back to that image/revision.
- Verify
/api/healthand the top customer workflows.
Database Rollback
- Identify issue via Sentry/logs.
- If migration issue: rollback or resolve the migration.
- If data issue: restore from Neon point-in-time backup.
Emergency Contacts
- Platform issues: On-call engineer
- Database: Neon support
- Payments: Stripe support
Monitoring
Health Checks
/api/health- Basic health/api/ready- Database, cache, and required environment readiness- Coolify deployment status
- Neon connection status
Key Metrics
- Response times (p50, p95, p99)
- Error rates by route
- Database query times
- AI API latency
- Docker image build duration and memory pressure
Alerts
- Error rate > 1%
- Response time > 5s
- Database connection failures
- AI provider errors
- Failed Coolify Docker build
Environment Variables
Required for Production
DATABASE_URL
JWT_SECRET
ENCRYPTION_KEY
NEXT_PUBLIC_APP_URL
NEXT_PUBLIC_MARKETING_URL
STRIPE_SECRET_KEY
STRIPE_WEBHOOK_SECRET
ANTHROPIC_API_KEY
OPENAI_API_KEY
R2_ACCESS_KEY_ID
R2_SECRET_ACCESS_KEY
RESEND_API_KEY
Optional/Feature-Specific
ENABLE_REDIS_CACHE
CACHE_REDIS_URL
REDIS_URL
ENABLE_UPSTASH_CACHE
UPSTASH_REDIS_REST_URL
UPSTASH_REDIS_REST_TOKEN
GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET
MICROSOFT_CLIENT_ID
MICROSOFT_CLIENT_SECRET
APPLE_CLIENT_ID
APPLE_CLIENT_SECRET
SENTRY_DSN