AeThex-OS/RAILWAY_DEPLOYMENT.md

Railway Deployment Guide - AeThex OS Kernel

Architecture Overview

• aethex.tech/api - Auth service (Passport endpoints)
• aethex.cloud/api - Services (Sentinel & others)
• THIS REPO - OS Kernel (Identity linking, Entitlements, Subjects)

Pre-Deployment Checklist

1. Environment Variables (Required)

# Core Config
NODE_ENV=production
PORT=3000  # Railway auto-assigns

# Security
SESSION_SECRET=<generate-strong-secret>

# Supabase (OS Database)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=<service-role-key>

# Stripe (for payments)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_PRICE_ID=price_...  # Optional
STRIPE_SUCCESS_URL=https://aethex.tech/upgrade/success
STRIPE_CANCEL_URL=https://aethex.tech/upgrade/cancel

# OpenAI (if using AI features)
OPENAI_API_KEY=sk-proj-...

2. Database Setup

Run migrations before deploying:

npm install
npm run db:push

3. Railway Project Setup

Option A: New Railway Project

# Install Railway CLI
npm i -g @railway/cli

# Login
railway login

# Initialize project
railway init

# Link to this repo
railway link

# Set environment variables
railway variables set SESSION_SECRET=<secret>
railway variables set SUPABASE_URL=<url>
railway variables set SUPABASE_SERVICE_KEY=<key>

# Deploy
railway up

Option B: Deploy from GitHub

1. Go to railway.app
2. Select "Deploy from GitHub repo"
3. Choose AeThex-Corporation/AeThex-OS
4. Railway auto-detects railway.json and nixpacks.toml
5. Set environment variables in Railway dashboard
6. Deploy automatically triggers

4. Custom Domain Setup

For aethex.tech/api/os/* (Auth domain)

1. In Railway dashboard → Settings → Domains
2. Add custom domain: aethex.tech
3. Update DNS:

   CNAME api railway.app (or provided value)
   

4. Configure path routing in Railway or reverse proxy

For aethex.cloud/api/os/* (Services domain)

1. Same process with aethex.cloud
2. Use Railway's path-based routing or Cloudflare Workers

Deployment Commands

Build locally

npm run build

Test production build

NODE_ENV=production npm start

Deploy to Railway

railway up
# or
git push  # if GitHub integration enabled

Post-Deployment Verification

1. Health Check

curl https://your-app.railway.app
# Expected: {"status":"AeThex OS Kernel: ONLINE"}

2. Test OS Kernel Endpoints

# Link Start
curl -X POST https://your-app.railway.app/api/os/link/start \
  -H 'Content-Type: application/json' \
  -H 'x-user-id: test-user' \
  -d '{"provider":"studio"}'

# Resolve Entitlements
curl 'https://your-app.railway.app/api/os/entitlements/resolve?platform=discord&id=12345'

3. Check Logs

railway logs

Troubleshooting

Build Fails

• Verify npm run build succeeds locally
• Check Railway build logs for missing dependencies

Database Connection Issues

• Ensure Supabase service key has correct permissions
• Check Supabase project isn't paused
• Verify database tables exist (run npm run db:push)

Session/Cookie Issues

• Set SESSION_SECRET in Railway
• Verify trust proxy is enabled (it is)

CORS Issues

• Check if frontend domain is whitelisted
• Railway auto-adds CORS headers for Railway subdomains

Migration Strategy

From Replit → Railway

1. Export Data (if needed)

   # Backup Supabase tables
   npx supabase db dump --db-url "$SUPABASE_URL"
   

2. Update DNS

   • Keep Replit running
   • Point Railway custom domain
   • Test Railway deployment
   • Switch DNS to Railway
   • Decommission Replit

3. Zero-Downtime Migration

   • Use Railway preview deploys first
   • Test all endpoints
   • Switch production traffic gradually

Monitoring

Railway Dashboard

• View metrics: CPU, Memory, Network
• Check deployment status
• Review logs in real-time

External Monitoring

# Setup health check cron (every 5 min)
*/5 * * * * curl -f https://your-app.railway.app/health || echo "OS Kernel down"

Cost Optimization

• Railway Hobby: $5/month (500h compute)
• Railway Pro: $20/month + usage
• Optimize by:
  • Using Railway sleep feature for non-prod
  • Caching Supabase queries
  • CDN for static assets (if serving frontend)

Security Notes

• Railway auto-provisions TLS certificates
• Use Railway secrets for sensitive env vars
• Rotate SESSION_SECRET periodically
• Monitor Supabase auth logs
• Review audit logs (aethex_audit_log table)

Support

• Railway Docs: https://docs.railway.app
• Railway Discord: https://discord.gg/railway
• AeThex Kernel Issues: Create GitHub issue in this repo