Deployment Readiness

Expert skill for verifying deployment configuration, environment variables, database migrations, and health check endpoints for production readiness.

When to Use This Skill

Use this skill when:

• Preparing for deployment to Replit, Railway, or other platforms
• Verifying environment variables match .env.example
• Checking database migrations are applied
• Validating health check endpoints
• Reviewing build artifacts and configuration

Expertise

• Deployment platform configuration (Replit, Railway, Netlify)
• Environment variable management
• Database migration validation
• Health check endpoint implementation
• Build artifact verification
• Docker and containerization

Environment Variables Validation

Required Variables

# Core
DATABASE_URL          # PostgreSQL connection string
INTERNAL_API_KEY      # Python ↔ TypeScript authentication

# Optional (search providers)
TAVILY_API_KEY        # Tavily search ($0.01/query)
PERPLEXITY_API_KEY    # Perplexity search ($0.005/query)
GOOGLE_API_KEY        # Google search
GOOGLE_SEARCH_ENGINE_ID

# Development
QIG_LOG_LEVEL         # DEBUG (dev), INFO (prod)
QIG_LOG_TRUNCATE      # false (dev), true (prod)
QIG_ENV               # development/production

Validation Steps

1. Check all vars from .env.example present in deployment
2. Verify secrets are not hardcoded in code
3. Confirm DATABASE_URL points to correct environment
4. Validate API keys have correct format/permissions

Database Readiness

Migration Checklist

• All Drizzle migrations applied (npx drizzle-kit push)
• pgvector extension installed
• HNSW indexes created for similarity search
• No pending schema changes
• Correct database for environment (dev/staging/prod)

Database Architecture

Health Check Endpoints

Required Endpoints

// Must return 200 OK
GET /health          // Basic liveness check
GET /health/ready    // Full readiness (DB connected, services up)
GET /api/health      // API health check

Health Response Format

{
  "status": "healthy",
  "timestamp": "2026-01-29T12:00:00Z",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "python_backend": "connected",
    "redis": "connected"
  }
}

Build Configuration

Railway (railpack.json)

{
  "build": {
    "builder": "nixpacks"
  },
  "deploy": {
    "startCommand": "npm start",
    "healthcheckPath": "/api/health",
    "healthcheckInterval": 30
  }
}

Port Configuration

• Bind servers to 0.0.0.0
• Read port from process.env.PORT
• Never hardcode ports
• Frontend: 3000 (dev), Backend: 5000, Python: 5001

Pre-Deployment Checklist

Build Artifacts

• npm run build succeeds
• No TypeScript errors (npm run check)
• Lint passes (npm run lint)
• Tests pass (npm test)
• Frontend assets in dist/

Configuration

• railpack.json present (Railway)
• No competing configs (Dockerfile vs railpack)
• .gitignore excludes sensitive files
• .env not committed

Database

• Migrations up to date
• Seed data applied if needed
• Backup exists before deployment

Monitoring

• Health check configured
• Error tracking enabled
• Logging configured for production

Common Issues

Port Already in Use

# Check what's using the port
lsof -i :5000

# Kill process if needed
kill -9 <PID>

Database Connection Failed

# Test connection
psql $DATABASE_URL -c "SELECT 1"

# Check pgvector
psql $DATABASE_URL -c "SELECT * FROM pg_extension WHERE extname = 'vector'"

Build Fails

# Clean install
rm -rf node_modules package-lock.json
npm install

# Check TypeScript
npm run check

Validation Commands

# Full pre-deployment check
bash scripts/pre_deployment_check.sh

# Environment validation
python scripts/validate_env.py

# Database status
npx drizzle-kit check

# Health check test
curl http://localhost:5000/health

Response Format

# Deployment Readiness Report

## Environment Variables
- ✅ DATABASE_URL: Set
- ❌ INTERNAL_API_KEY: Missing
- ⚠️ TAVILY_API_KEY: Optional, not set

## Database Status
- ✅ Connection: OK
- ✅ pgvector: Installed
- ❌ Migrations: 2 pending

## Health Checks
- ✅ /health: 200 OK
- ❌ /health/ready: 503 (DB not connected)

## Build Status
- ✅ TypeScript: No errors
- ✅ Lint: Passed
- ⚠️ Tests: 2 skipped

## Priority Actions
1. [CRITICAL] Set INTERNAL_API_KEY
2. [HIGH] Run pending migrations
3. [MEDIUM] Fix skipped tests