Deployment Steps

Step-by-step deployment instructions for production

Backend Docs API - Deployment Steps

Follow these exact steps to deploy to production.

Prerequisites Checklist

Before starting:

Railway CLI installed: npm install -g @railway/cli
Railway account created
MongoDB Atlas test-modules cluster accessible
.env.local configured with local tokens
Local testing completed successfully

Part 1: Deploy Backend API to Railway

Step 1: Create Railway Project (5 minutes)

Open https://railway.app/dashboard
Click "New Project"
Click "Empty Project"
Name it: "backend-docs-api"
Click the project to open it

Step 2: Generate Project Token (2 minutes)

In Railway project, click "Settings"
Scroll to "Tokens"
Click "Create Token"
Name it: "backend-docs-api-deploy"
Copy the token

Step 3: Update .env.local (1 minute)

Add these lines to .env.local:

# Railway Docs API
RAILWAY_DOCS_TOKEN=<paste-token-here>
RAILWAY_PROJECTID_DOCS=<copy-from-railway-url>

To get project ID:

Look at Railway URL: https://railway.app/project/abc123...
The part after /project/ is your project ID

Step 4: Configure Railway Environment (5 minutes)

In Railway dashboard:

Click "Variables" tab
Add these variables (click "+ New Variable" for each):

NODE_ENV=production
JWT_SECRET=<copy from .env.local - MUST match backend-api>
SYSTEM_TOKEN=<copy from .env.local>
MONGODB_CONNECTION_STRING_TEST_MODULES=<copy from .env.local>
ALLOWED_ORIGINS=https://gograb.space,http://localhost:5010

Click "Deploy" (or wait for auto-deploy)

Step 5: Deploy to Railway (3-5 minutes)

Run the deployment script:

cd /Users/fguijarro/developer/repos/editor
./deployment/deploy-docs-api.sh

Expected output:

📚 Backend Docs API Railway Deployment
⏳ Deploying backend-docs-api...
✅ Backend Docs API Deployment Triggered!

Step 6: Wait for Build (2-3 minutes)

Go to Railway dashboard
Click "Deployments" tab
Watch build progress
Wait for "Success" status

Step 7: Get Railway URL (1 minute)

In Railway dashboard, click "Settings"
Scroll to "Networking"
Click "Generate Domain"
Copy the URL (e.g., backend-docs-api-production.up.railway.app)

Step 8: Test Deployment (1 minute)

# Replace with your Railway URL
curl https://backend-docs-api-production.up.railway.app/docs-api/health

Expected response:

{
  "status": "ok",
  "timestamp": "2025-12-21T...",
  "service": "backend-docs-api",
  "database": "docs-database"
}

✅ Backend API Deployed Successfully!

Part 2: Initial Data Sync

Step 9: Configure Sync Environment (1 minute)

# Set production API URL (use your Railway URL)
export DOCS_API_URL=https://backend-docs-api-production.up.railway.app/docs-api
export SYSTEM_TOKEN=<copy-from-env-local>

Step 10: Run Bulk Sync (10-15 minutes)

yarn docs:sync

Expected output:

☁️  Starting bulk sync to cloud...
📁 Docs path: /Users/.../editor/docs
🌐 API URL: https://backend-docs-api-production.up.railway.app/docs-api

🔍 Scanning documentation files...
📊 Found 450 markdown files

📤 Uploading batch 1/9 (50 files)...
✅ Batch 1 uploaded: 50 created, 0 updated
...

╔════════════════════════════════════════╗
║     ☁️  Bulk Sync Complete           ║
╚════════════════════════════════════════╝

✅ Uploaded: 450 files
❌ Failed:   0 files
⏱️  Duration: 12.5s

Step 11: Verify Data in MongoDB (2 minutes)

Go to MongoDB Atlas dashboard
Click "Browse Collections"
Select docs-database
Verify collections:
- doc-files - Should have ~450 documents
- doc-projects - Should have project configs
- page-views - Empty initially
- search-events - Empty initially

✅ Data Synced Successfully!

Part 3: Deploy Frontend

Step 12: Update Production Environment (1 minute)

Edit apps/docs-angular/src/environments/environment.prod.ts:

export const environment = {
  production: true,
  docsApiUrl: 'https://backend-docs-api-production.up.railway.app/docs-api',
  wsUrl: 'wss://backend-docs-api-production.up.railway.app',
  enableCloudSync: true,
  enableAnalytics: true,
};

Replace backend-docs-api-production.up.railway.app with your actual Railway URL.

Step 13: Build Frontend (2-3 minutes)

nx build docs-angular --configuration=production

Expected output:

✔ Browser application bundle generation complete.
✔ Copying assets complete.
✔ Index html generation complete.

Output location: dist/apps/docs-angular/browser

Step 14: Test Build Locally (2 minutes)

nx serve-static docs-angular

Navigate to http://localhost:5010 and verify:

App loads
Documentation renders
Search works
API calls go to Railway (check Network tab)

Step 15: Deploy Frontend (5-10 minutes)

Option A: Copy to gograb.space/docs

If you have server access:

scp -r dist/apps/docs-angular/browser/* [email protected]:/var/www/gograb.space/docs/

Option B: Deploy to Railway Static

Create new Railway service: "docs-angular-static"
Connect to GitHub repo
Build command: nx build docs-angular --configuration=production
Start command: npx serve dist/apps/docs-angular/browser -p $PORT
Generate domain

Option C: Deploy to Vercel

cd dist/apps/docs-angular/browser
vercel --prod

Step 16: Verify Production Frontend (2 minutes)

Navigate to: https://gograb.space/docs (or your deployment URL)

Test:

Homepage loads
Documentation pages render
Search works (⌘K / Ctrl+K)
Navigation sidebar works
Language switching works
Admin panel loads (if authenticated)
No console errors
API calls succeed (check Network tab)

✅ Frontend Deployed Successfully!

Part 4: Post-Deployment Verification

Step 17: End-to-End Test (5 minutes)

Test Public Access:
- Navigate to https://gograb.space/docs
- Browse documentation
- Perform searches
- Check different projects
Test Admin Access:
- Go to https://gograb.space/docs/admin
- Login with admin password
- Check analytics dashboard
- Verify cloud file manager
Test Real-Time Sync (if applicable):
- Edit a file locally
- Run yarn docs:watch (with production URL)
- Verify change appears online

Step 18: Monitor for 24 Hours

Railway Dashboard:
- Monitor resource usage
- Check for errors in logs
- Verify health checks passing
MongoDB Atlas:
- Monitor connection count
- Check query performance
- Verify storage usage
Frontend:
- Check for JavaScript errors
- Monitor page load times
- Verify analytics tracking

Troubleshooting

API Deployment Failed

Check:

Railway build logs for errors
Environment variables are all set
MongoDB connection string is correct
Dockerfile syntax is valid

Fix:

# Redeploy
./deployment/deploy-docs-api.sh

Initial Sync Failed

Check:

DOCS_API_URL is correct
SYSTEM_TOKEN matches Railway
API is responding to health checks
MongoDB is accessible

Fix:

# Verify API
curl https://your-api.railway.app/docs-api/health

# Retry sync
yarn docs:sync

Frontend Build Failed

Check:

TypeScript errors: nx lint docs-angular
Environment file is correct
All imports are valid
Bundle size within limits

Fix:

# Clear cache and rebuild
nx reset
nx build docs-angular --configuration=production

Frontend Can't Connect to API

Check:

environment.prod.ts has correct Railway URL
CORS is configured in Railway environment
API is deployed and healthy
Browser console for CORS errors

Fix:

Update ALLOWED_ORIGINS in Railway
Redeploy API
Rebuild frontend

Success Criteria

Deployment is complete when:

✅ API health check responds
✅ All docs synced to MongoDB (450+ files)
✅ Frontend loads at gograb.space/docs
✅ Documentation pages render
✅ Search works
✅ Admin panel accessible
✅ Analytics tracking active
✅ No critical errors

Timeline Summary

Step	Time	Status
Create Railway project	5 min	⏳ User action
Configure environment	5 min	⏳ User action
Deploy API	3-5 min	⏳ User action
Initial sync	10-15 min	⏳ User action
Build frontend	2-3 min	⏳ User action
Deploy frontend	5-10 min	⏳ User action
Total	30-45 min	Ready

Quick Command Reference

# Deploy API
./deployment/deploy-docs-api.sh

# Sync data
export DOCS_API_URL=https://your-api.railway.app/docs-api
yarn docs:sync

# Build frontend
nx build docs-angular --configuration=production

# Test locally
yarn serve:backend-docs
yarn docs:sync
yarn serve:docs

Support

Congratulations! 🎉

You're ready to deploy! Follow these steps and your documentation will be live at gograb.space/docs.

Implementation Status: ✅ Complete
Deployment Status: ⏳ Awaiting user action
Documentation Status: ✅ Complete