Nestr Deployment Guide

Production-ready deployment guide for Nestr engine (Railway) and web (Vercel).

📚 Documentation Quick Links

PRODUCTION_DEPLOYMENT - Complete production deployment guide with automated scripts
DEPLOYMENT_QUICK_REFERENCE - Quick command reference cheatsheet
This document - Detailed manual deployment steps

🚀 Quick Deploy (Recommended)

For automated deployment with pre-deployment checks:

# 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

See PRODUCTION_DEPLOYMENT for complete guide.

Prerequisites

Railway CLI installed: npm install -g @railway/cli
Vercel CLI installed: npm install -g vercel
Docker installed (for local testing)
Node.js 18+ and Yarn
Go 1.25+

Architecture Overview

┌─────────────────┐         ┌──────────────────┐
│  Vercel (Web)   │  HTTPS  │ Railway (Engine) │
│  React + Vite   ├────────→│   Go + SQLite    │
│  Static Hosting │         │   Docker Container│
└─────────────────┘         └──────────────────┘

Production URLs:

Web: https://nestr.vercel.app (or custom domain)
API: https://nestr-engine.up.railway.app (or custom domain)

Part 1: Railway Deployment (Engine - Backend)

Step 1: Initialize Railway Project

cd lab/nestr/engine

# Login to Railway
railway login

# Initialize new project
railway init

# Link to existing project (if you created one in the web dashboard)
# railway link [project-id]

Step 2: Configure Environment Variables

In Railway dashboard or via CLI:

# Required variables
railway variables set ENVIRONMENT=production
railway variables set LOG_LEVEL=info
railway variables set PORT=8080
railway variables set DB_PATH=/app/data/nestr.db

# Optional: Custom domain
railway variables set CORS_ALLOWED_ORIGINS=https://your-domain.vercel.app

# Security (generate strong secrets)
railway variables set API_KEY=$(openssl rand -hex 32)

# Observability
railway variables set ENABLE_METRICS=true
railway variables set METRICS_PORT=9090

Step 3: Deploy

# Deploy using Dockerfile
railway up

# Check deployment status
railway status

# View logs
railway logs

Step 4: Verify Health

# Get your Railway URL
RAILWAY_URL=$(railway status --json | jq -r '.url')

# Test health endpoints
curl $RAILWAY_URL/health
curl $RAILWAY_URL/ready
curl $RAILWAY_URL/metrics

Expected responses:

// /health
{
  "status": "healthy",
  "service": "nestr-engine",
  "version": "0.1.0"
}

// /ready
{
  "status": "ready",
  "service": "nestr-engine",
  "database": "connected"
}

Step 5: Configure Custom Domain (Optional)

# Add custom domain in Railway dashboard
railway domain

# Update DNS records:
# CNAME: api.your-domain.com → your-app.up.railway.app

Part 2: Vercel Deployment (Web - Frontend)

Step 1: Prepare Environment

cd lab/nestr/web

# Copy environment template
cp .env.example .env.production

# Edit .env.production with your Railway URL
# VITE_API_URL=https://nestr-engine.up.railway.app

Step 2: Initialize Vercel Project

# Login to Vercel
vercel login

# Initialize project (follow prompts)
vercel

# Link to existing project
# vercel link

Step 3: Configure Environment Variables

In Vercel dashboard (Settings → Environment Variables) or via CLI:

# Production environment
vercel env add VITE_API_URL production
# Enter: https://nestr-engine.up.railway.app

vercel env add VITE_ENVIRONMENT production
# Enter: production

vercel env add VITE_APP_VERSION production
# Enter: 0.1.0

Step 4: Deploy to Production

# Deploy to production
vercel --prod

# Or deploy via Git push (if linked to GitHub)
git push origin main

Step 5: Verify Deployment

Visit your Vercel URL and test:

Homepage loads
API connection works
WebSocket connections establish (if applicable)
Graph visualization renders

# Get deployment URL
vercel inspect [deployment-url]

Step 6: Configure Custom Domain (Optional)

# Add domain in Vercel dashboard
vercel domains add your-domain.com

# Update DNS records:
# CNAME: www → cname.vercel-dns.com
# A: @ → 76.76.21.21

Part 3: CORS Configuration

Update Railway Environment

cd lab/nestr/engine

# Set allowed origins (your Vercel URL)
railway variables set CORS_ALLOWED_ORIGINS=https://your-app.vercel.app,https://your-domain.com

Update REST Server (if needed)

The engine automatically reads CORS_ALLOWED_ORIGINS from environment. Verify in internal/server/rest.go that CORS middleware is properly configured.

Part 4: Database & Persistence

Railway Volume Configuration

SQLite database is stored at /app/data/nestr.db in the container. To persist data across deployments:

Go to Railway dashboard → Your service → Settings
Scroll to “Volumes”
Click “Add Volume”
- Mount Path: /app/data
- Size: 1GB (or as needed)
Redeploy service

Backup Strategy:

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

# Export database
sqlite3 /app/data/nestr.db .dump > backup.sql

# Or use Railway's built-in backups

Part 5: Monitoring & Observability

Health Check Endpoints

Monitor these endpoints for service health:

# Engine health
curl https://nestr-engine.up.railway.app/health

# Readiness (database connectivity)
curl https://nestr-engine.up.railway.app/ready

# Prometheus metrics
curl https://nestr-engine.up.railway.app/metrics

Railway Logs

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

# Filter by service
railway logs --service nestr-engine

# Export logs
railway logs > logs.txt

Vercel Analytics

Enable in Vercel dashboard:

Settings → Analytics → Enable Web Analytics
Provides insights on performance, visitors, and errors

Part 6: CI/CD Pipeline (Optional)

GitHub Actions for Automated Deployment

Create .github/workflows/deploy.yml:

name: Deploy Nestr

on:
  push:
    branches: [main]

jobs:
  deploy-engine:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to Railway
        run: |
          npm install -g @railway/cli
          railway link ${{ secrets.RAILWAY_PROJECT_ID }}
          railway up --service engine
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

  deploy-web:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Deploy to Vercel
        run: |
          npm install -g vercel
          vercel --prod --token=${{ secrets.VERCEL_TOKEN }}
        env:
          VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
          VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
          VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}

Add secrets to GitHub:

RAILWAY_TOKEN
RAILWAY_PROJECT_ID
VERCEL_TOKEN
VERCEL_ORG_ID
VERCEL_PROJECT_ID

Part 7: Rollback Procedures

Railway Rollback

# List deployments
railway deployments

# Rollback to specific deployment
railway rollback [deployment-id]

# Or rollback to previous
railway rollback --previous

Vercel Rollback

# List deployments
vercel ls

# Promote a previous deployment
vercel promote [deployment-url] --scope [team-name]

# Or via dashboard: Deployments → Select deployment → Promote to Production

Part 8: Troubleshooting

Engine Not Starting

Check logs:

railway logs --service engine --tail 100

Common issues:

Missing environment variables → Check railway variables
Port binding → Ensure PORT matches Dockerfile EXPOSE
Database path → Verify volume is mounted

Frontend API Connection Failed

Check CORS:

# Test from browser console
fetch('https://nestr-engine.up.railway.app/health')
  .then(r => r.json())
  .then(console.log)

Verify environment variables:

# Check Vercel env vars
vercel env ls

Database Locked

SQLite can lock under high concurrency:

Consider migrating to PostgreSQL for production
Enable WAL mode (already enabled in code)
Add connection pooling

Part 9: Performance Optimization

Railway

Enable caching headers
Use Railway’s built-in CDN
Consider upgrading plan for more resources

Vercel

Enable Edge Functions (if needed)
Configure caching policies in vercel.json
Use ISR (Incremental Static Regeneration) for dynamic content

Part 10: Security Checklist

Environment variables secured (not in code)
HTTPS enforced on both services
CORS properly configured
Rate limiting enabled in engine
API keys rotated regularly
Database backups scheduled
Health checks monitored
Logs reviewed for suspicious activity
Dependencies up to date (yarn upgrade, go get -u)

Quick Reference

# Railway commands
railway login
railway init
railway up
railway logs
railway variables set KEY=value
railway status

# Vercel commands
vercel login
vercel
vercel --prod
vercel logs
vercel env add KEY
vercel domains add domain.com

# Health checks
curl $API_URL/health
curl $API_URL/ready
curl $API_URL/metrics

Support

Railway docs: https://docs.railway.app
Vercel docs: https://vercel.com/docs
Nestr issues: https://github.com/Dev4rno/nestr/issues

Overview

Architecture

Deployment

Taskset Reports

Verification

Strategy & Branding

​Nestr Deployment Guide

​📚 Documentation Quick Links

​🚀 Quick Deploy (Recommended)

​Prerequisites

​Architecture Overview

​Part 1: Railway Deployment (Engine - Backend)

​Step 1: Initialize Railway Project

​Step 2: Configure Environment Variables

​Step 3: Deploy

​Step 4: Verify Health

​Step 5: Configure Custom Domain (Optional)

​Part 2: Vercel Deployment (Web - Frontend)

​Step 1: Prepare Environment

​Step 2: Initialize Vercel Project

​Step 3: Configure Environment Variables

​Step 4: Deploy to Production

​Step 5: Verify Deployment

​Step 6: Configure Custom Domain (Optional)

​Part 3: CORS Configuration

​Update Railway Environment

​Update REST Server (if needed)

​Part 4: Database & Persistence

​Railway Volume Configuration

​Part 5: Monitoring & Observability

​Health Check Endpoints

​Railway Logs

​Vercel Analytics

​Part 6: CI/CD Pipeline (Optional)

​GitHub Actions for Automated Deployment

​Part 7: Rollback Procedures

​Railway Rollback

​Vercel Rollback

​Part 8: Troubleshooting

​Engine Not Starting

​Frontend API Connection Failed

​Database Locked

​Part 9: Performance Optimization

​Railway

​Vercel

​Part 10: Security Checklist

​Quick Reference

​Support