Backend Docs API - Ready to Deploy

The backend-docs-api is fully implemented and ready for Railway deployment. Follow this checklist to go live.

Pre-Deployment Checklist

1. Environment Configuration

• .env.local contains all required variables
• MONGODB_CONNECTION_STRING_TEST_MODULES is valid
• JWT_SECRET matches other APIs
• SYSTEM_TOKEN is set

2. Local Testing

• API starts successfully: yarn serve:backend-docs
• Health check responds: curl http://localhost:3002/docs-api/health
• Bulk sync works: yarn docs:sync
• File watcher works: yarn docs:watch
• Frontend connects: yarn serve:docs

3. Railway Project Setup

• Railway project created
• Project token generated and added to .env.local
• Project ID added to .env.local
• Environment variables configured in Railway dashboard

4. MongoDB Configuration

• Test-modules cluster is accessible
• Database user has read/write permissions
• Network access configured (0.0.0.0/0 or specific IPs)
• Connection string tested with MongoDB Compass

Deployment Steps

Step 1: Create Railway Project

# 1. Go to https://railway.app/dashboard
# 2. Click "New Project"
# 3. Name it "backend-docs-api"
# 4. Go to Settings → Tokens → Create Token
# 5. Copy token to .env.local

Step 2: Configure Railway Environment

In Railway dashboard, add these variables:

NODE_ENV=production
JWT_SECRET=<same as backend-api>
SYSTEM_TOKEN=<same as other APIs>
MONGODB_CONNECTION_STRING_TEST_MODULES=<MongoDB URI>
ALLOWED_ORIGINS=https://gograb.space,http://localhost:5010

Step 3: Deploy to Railway

./deployment/deploy-docs-api.sh

Wait 2-3 minutes for build to complete.

Step 4: Verify Deployment

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

Expected response:

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

Step 5: Initial Data Sync

# Set production API URL
export DOCS_API_URL=https://your-docs-api.railway.app/docs-api
export SYSTEM_TOKEN=<your-system-token>

# Sync all docs
yarn docs:sync

Expected output:

☁️  Bulk Sync Complete
✅ Uploaded: 450 files
❌ Failed:   0 files
⏱️  Duration: 12.5s

Step 6: Verify Data in MongoDB

Check MongoDB Atlas:

1. Go to Collections
2. Select docs-database
3. Verify collections exist:
   • doc-files (should have ~450 documents)
   • doc-projects (should have project configs)
   • page-views (empty initially)
   • search-events (empty initially)

Step 7: Test API Endpoints

# Get manifest
curl https://your-docs-api.railway.app/docs-api/sync/manifest

# Get files
curl https://your-docs-api.railway.app/docs-api/sync/files?page=1&limit=10

# Get projects
curl https://your-docs-api.railway.app/docs-api/sync/projects

Step 8: Update Frontend Environment

// apps/docs-angular/src/environments/environment.prod.ts
export const environment = {
  production: true,
  docsApiUrl: 'https://your-docs-api.railway.app/docs-api',
  wsUrl: 'wss://your-docs-api.railway.app',
  enableCloudSync: true,
  enableAnalytics: true,
};

Step 9: Build Frontend

nx build docs-angular --configuration=production

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

Step 10: Deploy Frontend

Option A: Copy to gograb.space/docs

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

Option B: Deploy to Railway Static

1. Create new Railway service
2. Connect to repo
3. Build command: nx build docs-angular --configuration=production
4. Start command: npx serve dist/apps/docs-angular/browser -p $PORT

Option C: Deploy to Vercel/Cloudflare

Follow their respective deployment guides.

Post-Deployment Verification

1. Test Production API

# Health check
curl https://your-docs-api.railway.app/docs-api/health

# Get manifest
curl https://your-docs-api.railway.app/docs-api/sync/manifest

# Test analytics (should work without auth)
curl -X POST https://your-docs-api.railway.app/docs-api/analytics/page-views \
  -H "Content-Type: application/json" \
  -d '{"path":"/test","project":"test","language":"en"}'

2. Test Production Frontend

Navigate to: https://gograb.space/docs

Verify:

• Homepage loads
• Documentation pages render
• Search works
• Navigation works
• Language switching works
• No console errors
• API calls succeed (check Network tab)

3. Test Admin Features

Navigate to: https://gograb.space/docs/admin

• Admin login works
• Dashboard loads
• Analytics display correctly
• Cloud file manager works

4. Test Real-Time Sync

1. Edit a file locally in /docs
2. Run yarn docs:watch (with production API URL)
3. Verify change appears in MongoDB
4. Check frontend updates (if WebSocket connected)

Monitoring Setup

Railway Monitoring

1. Enable health checks (already configured)
2. Set up alerts for downtime
3. Monitor resource usage

MongoDB Monitoring

1. Enable MongoDB Atlas monitoring
2. Set up alerts for:
   • High connection count
   • Slow queries
   • Storage usage

Application Monitoring

Consider adding:

• Sentry for error tracking
• LogRocket for session replay
• Google Analytics for usage tracking

Rollback Plan

If deployment fails:

1. API Rollback: Redeploy previous version in Railway
2. Frontend Rollback: Restore previous static files
3. Database Rollback: MongoDB has automatic backups (restore if needed)

Success Criteria

Deployment is successful when:

• ✅ API health check responds
• ✅ All docs synced to MongoDB
• ✅ Frontend loads at gograb.space/docs
• ✅ Documentation pages render correctly
• ✅ Search functionality works
• ✅ Admin panel accessible
• ✅ Analytics tracking active
• ✅ No critical errors in logs

Support

If you encounter issues:

1. Check Railway logs
2. Review MongoDB Atlas logs
3. Test locally first
4. Verify all environment variables
5. Check CORS configuration
6. Review Troubleshooting Guide

Next Steps After Deployment

1. Monitor Performance: Watch Railway metrics for first 24 hours
2. Test End-to-End: Verify complete user flow
3. Enable Analytics: Start tracking usage patterns
4. Set Up Alerts: Configure monitoring alerts
5. Document URL: Share https://gograb.space/docs with team

Deployment Timeline

Expected timeline:

• Railway Project Setup: 10 minutes
• Initial Deployment: 3-5 minutes (build time)
• Initial Sync: 10-15 minutes (450 files)
• Frontend Build: 2-3 minutes
• Frontend Deployment: 5-10 minutes

Total: ~30-45 minutes for complete deployment

Congratulations! 🎉

You now have a fully functional documentation system with:

• Real-time MongoDB synchronization
• Shared authentication across all APIs
• Admin panel for management
• Analytics tracking and reporting
• Production-ready Railway deployment
• Static frontend at gograb.space/docs

The documentation is now accessible online! 📚