Skip to main content

​
Nestr Production Deployment Guide

Complete guide for deploying Nestr to production using Railway (backend) and Vercel (frontend).

​
Quick Start

# 1. Deploy backend to Railway
cd engine
./scripts/deploy-railway.sh

# 2. Deploy frontend to Vercel
cd ../web
./scripts/deploy-vercel.sh

# 3. Run smoke tests
cd ..
./scripts/smoke-test-production.sh

​
Table of Contents

  1. Prerequisites
  2. Backend Deployment (Railway)
  3. Frontend Deployment (Vercel)
  4. Production Configuration
  5. Smoke Testing
  6. Post-Deployment
  7. Troubleshooting
  8. Rollback Procedures

​
Prerequisites

​
Required Tools

# Railway CLI
npm install -g @railway/cli
# or
brew install railway

# Vercel CLI
npm install -g vercel

# Verify installations
railway --version
vercel --version

​
Accounts Required

​
Authentication

# Login to Railway
railway login

# Login to Vercel
vercel login

# Verify authentication
railway whoami
vercel whoami

​
Backend Deployment (Railway)

​
Step 1: Prepare Backend

cd engine

# Verify Dockerfile exists
ls -la Dockerfile

# Verify railway.json exists
ls -la railway.json

# Optional: Build locally to verify
go build -o nestr .
./nestr serve  # Test locally

​
Step 2: Deploy to Railway

./scripts/deploy-railway.sh
The script will:
  • ✅ Check Railway CLI installation
  • ✅ Verify authentication
  • ✅ Link or create Railway project
  • ✅ Set environment variables
  • ✅ Run pre-deployment checks
  • ✅ Deploy using Dockerfile
  • ✅ Verify deployment health

​
Option B: Manual Deployment

# Create/link project
railway init
# or
railway link

# Set environment variables
railway variables set ENVIRONMENT=production
railway variables set PORT=8080
railway variables set LOG_LEVEL=info
railway variables set CORS_ALLOWED_ORIGINS="https://your-frontend.vercel.app"
railway variables set DB_PATH=/app/data/nestr.db
railway variables set ENABLE_METRICS=true
railway variables set RATE_LIMIT_ENABLED=true

# Deploy
railway up

# Generate domain
railway domain

# Check deployment
railway logs

​
Step 3: Get Backend URL

# Get your Railway domain
railway domain

# Example output: nestr-engine.up.railway.app
# Full URL: https://nestr-engine.up.railway.app

​
Step 4: Verify Backend Deployment

# Test health endpoint
curl https://your-railway-domain.up.railway.app/health

# Expected response:
# {"status":"healthy","service":"nestr-engine","version":"0.1.0"}

# Test readiness
curl https://your-railway-domain.up.railway.app/ready

# Test API
curl https://your-railway-domain.up.railway.app/api/workspace

​
Frontend Deployment (Vercel)

​
Step 1: Prepare Frontend

cd web

# Install dependencies
yarn install

# Verify build works locally
VITE_API_URL=https://your-railway-domain.up.railway.app yarn build

# Test build output
ls -la dist/

​
Step 2: Deploy to Vercel

./scripts/deploy-vercel.sh
The script will:
  • ✅ Check Vercel CLI installation
  • ✅ Verify authentication
  • ✅ Link or create Vercel project
  • ✅ Set VITE_API_URL environment variable
  • ✅ Verify backend connectivity
  • ✅ Build and deploy
  • ✅ Test deployment

​
Option B: Manual Deployment

# Link project
vercel link

# Set environment variable
vercel env add VITE_API_URL production
# Enter: https://your-railway-domain.up.railway.app

# Deploy to production
vercel --prod

# Or deploy to preview
vercel

​
Step 3: Get Frontend URL

After deployment, Vercel will output your deployment URL: 
https://nestr.vercel.app
# or
https://nestr-web.vercel.app

​
Step 4: Update Backend CORS

Critical: Update Railway backend to allow requests from frontend: 
cd ../engine

railway variables set CORS_ALLOWED_ORIGINS="https://your-vercel-app.vercel.app"

# Or multiple origins:
railway variables set CORS_ALLOWED_ORIGINS="https://app1.vercel.app,https://app2.vercel.app"

# Redeploy backend to apply CORS changes
railway up

​
Production Configuration

​
Backend Environment Variables (Railway)

​
Required

VariableValueDescription
ENVIRONMENTproductionEnvironment name
PORT8080Server port (Railway provides PORT automatically)
LOG_LEVELinfoLogging level
CORS_ALLOWED_ORIGINShttps://your-frontend.vercel.appAllowed origins for CORS
VariableValueDescription
DB_PATH/app/data/nestr.dbSQLite database path
ENABLE_METRICStrueEnable Prometheus metrics
ENABLE_TRACINGfalseDistributed tracing (optional)
RATE_LIMIT_ENABLEDtrueEnable rate limiting
RATE_LIMIT_REQUESTS_PER_MINUTE100Rate limit threshold

​
Optional

VariableValueDescription
MAX_REQUEST_SIZE_MB10Max request body size
REQUEST_TIMEOUT_SECONDS30Request timeout
WORKSPACE_ROOT/app/workspaceWorkspace directory

​
Setting Variables in Railway

# Via CLI
railway variables set KEY=value

# Via Railway Dashboard
# 1. Open project at railway.app
# 2. Navigate to Variables tab
# 3. Add/edit variables
# 4. Redeploy to apply

​
Frontend Environment Variables (Vercel)

​
Required

VariableValueDescription
VITE_API_URLhttps://your-backend.up.railway.appBackend API base URL

​
Setting Variables in Vercel

# Via CLI - Production
vercel env add VITE_API_URL production
# Paste value: https://your-backend.up.railway.app

# Via CLI - Preview
vercel env add VITE_API_URL preview

# Via Vercel Dashboard
# 1. Open project at vercel.com
# 2. Settings → Environment Variables
# 3. Add VITE_API_URL
# 4. Select environments (Production, Preview, Development)
# 5. Save

​
Smoke Testing

​
Automated Smoke Tests

Run comprehensive smoke tests against production: 
./scripts/smoke-test-production.sh \
  https://your-backend.up.railway.app \
  https://your-frontend.vercel.app
Tests include:
  • ✅ Backend health endpoints
  • ✅ API endpoints (workspace, services)
  • ✅ CORS configuration
  • ✅ Frontend deployment
  • ✅ Security headers
  • ✅ Response times
  • ✅ Integration connectivity

​
Manual Testing Checklist

​
Backend

  • Health check: curl https://backend/health
  • Readiness: curl https://backend/ready
  • Metrics: curl https://backend/metrics
  • Workspace API: curl https://backend/api/workspace
  • Services API: curl https://backend/api/services

​
Frontend

  • Homepage loads: Visit https://frontend
  • No console errors (check browser DevTools)
  • API calls succeed (check Network tab)
  • Data displays correctly
  • Responsive on mobile

​
Integration

  • Frontend can fetch data from backend
  • CORS headers present
  • No authentication/permission errors

​
Post-Deployment

​
Monitoring

​
Railway Monitoring

# View logs
railway logs

# Follow logs in real-time
railway logs --follow

# Check service status
railway status

# Open Railway dashboard
railway open

​
Vercel Monitoring

# View logs
vercel logs

# Follow logs
vercel logs --follow

# View specific deployment
vercel inspect <deployment-url>

# Open Vercel dashboard
vercel open

​
Custom Domains (Optional)

​
Railway Custom Domain

# Add custom domain
railway domain add api.yourdomain.com

# Follow Railway instructions to:
# 1. Add CNAME record: api.yourdomain.com → your-app.up.railway.app
# 2. Wait for DNS propagation
# 3. SSL certificate auto-generated

​
Vercel Custom Domain

# Add custom domain
vercel domains add yourdomain.com

# Follow Vercel instructions to:
# 1. Add DNS records (A, CNAME, or ALIAS)
# 2. Wait for DNS propagation
# 3. SSL certificate auto-generated

# Or use Vercel nameservers for automatic configuration
After adding custom domains, update environment variables: 
# Update Railway CORS
railway variables set CORS_ALLOWED_ORIGINS="https://yourdomain.com"

# Update Vercel API URL
vercel env add VITE_API_URL production
# Enter: https://api.yourdomain.com

​
Metrics and Analytics

​
Backend Metrics

Access Prometheus metrics: 
https://your-backend.up.railway.app/metrics
Key metrics:
  • http_requests_total - Total requests
  • http_request_duration_seconds - Request latency
  • http_requests_in_flight - Active requests

​
Frontend Analytics

Consider adding:
  • Vercel Analytics (built-in)
  • Google Analytics
  • Sentry for error tracking
  • LogRocket for session replay

​
Security

​
SSL/TLS

  • ✅ Railway provides automatic SSL
  • ✅ Vercel provides automatic SSL
  • ✅ All connections encrypted (HTTPS)

​
Secrets Management

  • ✅ Environment variables encrypted at rest
  • ✅ Never commit .env files
  • ✅ Rotate secrets periodically

​
Security Headers

Vercel automatically adds (via vercel.json):
  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block

​
Backups

​
Database Backup

# Railway persistent volumes are backed up automatically
# To manually backup:

# 1. SSH into Railway container (if available)
railway run bash

# 2. Copy database
cp /app/data/nestr.db /tmp/backup.db

# 3. Download locally
railway connect
# Follow instructions to access files

​
Configuration Backup

# Export Railway variables
railway variables > railway-vars-backup.txt

# Export Vercel variables (via dashboard)
# Settings → Environment Variables → Export

​
Troubleshooting

​
Backend Issues

​
”Service Not Starting"

# Check logs
railway logs

# Common causes:
# 1. Port mismatch (Railway sets PORT env var)
# 2. Missing environment variables
# 3. Database path not writable

# Verify PORT is read from environment:
railway variables get PORT

​
"Health Check Failing"

# Test health endpoint
curl https://your-app.up.railway.app/health

# Check if service is listening on correct port
railway logs | grep "listening on"

# Verify HEALTHCHECK in Dockerfile
cat Dockerfile | grep HEALTHCHECK

​
"Database Errors”

# Ensure database directory exists and is writable
railway run bash
mkdir -p /app/data
chmod 755 /app/data

# Check DB_PATH variable
railway variables get DB_PATH

​
Frontend Issues

​
”Failed to Fetch” Errors

# 1. Verify API URL is set
vercel env ls

# 2. Check backend is accessible
curl https://your-backend.up.railway.app/health

# 3. Verify CORS is configured
curl -I -H "Origin: https://your-frontend.vercel.app" \
  https://your-backend.up.railway.app/api/workspace

# Should include: Access-Control-Allow-Origin

​
”Blank Page"

# Check build logs
vercel inspect <deployment-url>

# Common causes:
# 1. Build errors (check logs)
# 2. Runtime errors (check browser console)
# 3. Missing environment variables

# Rebuild with logs
vercel --prod --debug

​
"CORS Errors”

# Update backend CORS settings
cd engine
railway variables set CORS_ALLOWED_ORIGINS="https://your-frontend.vercel.app"
railway up  # Redeploy

# Verify CORS headers
curl -I -H "Origin: https://your-frontend.vercel.app" \
  https://your-backend.up.railway.app/health

​
Integration Issues

​
”API Calls Failing”

  1. Check browser console for specific errors
  2. Verify environment variable: VITE_API_URL in Vercel
  3. Test backend directly: curl https://backend/api/workspace
  4. Check CORS: Origin must match frontend URL exactly
  5. Verify network tab: Look for 4xx/5xx responses

​
”Slow Performance”

# Test response times
time curl https://your-backend.up.railway.app/health

# If slow:
# 1. Check Railway region (close to users?)
# 2. Check database queries (add indexes)
# 3. Enable caching
# 4. Scale Railway service (paid plans)

​
Rollback Procedures

​
Railway Rollback

# View recent deployments
railway status

# Rollback to previous deployment
# Via dashboard:
# 1. Open Railway project
# 2. Go to Deployments tab
# 3. Find previous successful deployment
# 4. Click "Redeploy"

# Via CLI (redeploy from local)
git checkout <previous-commit>
railway up

​
Vercel Rollback

# List recent deployments
vercel ls

# Promote previous deployment to production
vercel promote <deployment-url>

# Or rollback via dashboard:
# 1. Open Vercel project
# 2. Go to Deployments tab
# 3. Find previous deployment
# 4. Click "..." → "Promote to Production"

​
Emergency Rollback

If both services have issues:
  1. Immediately rollback frontend (fastest) 
    vercel promote <last-known-good-deployment>
  2. Then rollback backend 
    # Via Railway dashboard: redeploy previous version
  3. Verify rollback 
    ./scripts/smoke-test-production.sh
  4. Investigate issues in logs before redeploying

​
Production Checklist

​
Pre-Deployment

  • All tests passing locally
  • E2E tests passing: yarn test:e2e
  • Backend builds successfully: go build
  • Frontend builds successfully: yarn build
  • Environment variables documented
  • Secrets rotated (if applicable)
  • Database migrations tested
  • CORS origins configured
  • Monitoring set up

​
Deployment

  • Backend deployed to Railway
  • Backend health check passing
  • Frontend deployed to Vercel
  • Frontend loads correctly
  • CORS updated for frontend URL
  • Smoke tests passing
  • Integration verified

​
Post-Deployment

  • Monitor logs for errors
  • Check metrics for anomalies
  • Verify user-facing functionality
  • Update documentation
  • Notify team of deployment
  • Create backup of current state

​
Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                         Production                           │
└─────────────────────────────────────────────────────────────┘

┌────────────────────┐                    ┌──────────────────┐
│   Vercel (CDN)     │                    │  Railway (PaaS)  │
│                    │                    │                  │
│  ┌──────────────┐  │                    │  ┌────────────┐  │
│  │   React App  │  │  HTTPS requests    │  │ Go Backend │  │
│  │   (Vite)     │  │◄──────────────────►│  │  (Fiber)   │  │
│  └──────────────┘  │  with CORS         │  └────────────┘  │
│         │          │                    │        │         │
│    Static Files    │                    │   SQLite DB      │
│    (HTML/JS/CSS)   │                    │   /app/data/     │
└────────────────────┘                    └──────────────────┘
         │                                         │
         │                                         │
         └─────────── TLS/SSL ────────────────────┘
                  (Auto-generated)
Traffic Flow:
  1. User visits https://nestr.vercel.app
  2. Vercel serves static React app
  3. React app makes API calls to https://nestr-engine.up.railway.app
  4. Railway backend processes requests
  5. CORS headers allow cross-origin requests
  6. Responses returned to frontend
  7. Frontend renders data

​
Support and Resources

​
Documentation

​
Deployment Scripts

  • Railway Deployment: engine/scripts/deploy-railway.sh
  • Vercel Deployment: web/scripts/deploy-vercel.sh
  • Smoke Tests: scripts/smoke-test-production.sh

​
Monitoring Commands

# Railway
railway logs --follow
railway status
railway open

# Vercel
vercel logs --follow
vercel ls
vercel open

​
Getting Help

  • Review logs first: railway logs and vercel logs
  • Check smoke test output
  • Review this troubleshooting section
  • Check platform status pages:

​
Summary

✅ Backend: Deployed to Railway with Dockerfile ✅ Frontend: Deployed to Vercel with Vite ✅ CORS: Configured for cross-origin requests ✅ SSL: Automatic HTTPS on both platforms ✅ Monitoring: Logs and metrics available ✅ Testing: Automated smoke tests included Production URLs:
  • Backend: https://<your-project>.up.railway.app
  • Frontend: https://<your-project>.vercel.app
Next Steps:
  1. Run smoke tests regularly
  2. Set up monitoring alerts
  3. Configure custom domains (optional)
  4. Plan scaling strategy
  5. Document runbooks for common operations