Backend Docs API Deployment Guide

Complete guide for deploying backend-docs-api to Railway

Backend Docs API Deployment Guide

Complete guide for deploying the backend-docs-api to Railway with MongoDB integration.

Prerequisites

Railway account with CLI installed
MongoDB Atlas test-modules cluster
Railway project created for backend-docs-api
.env.local configured with tokens

Step 1: Configure Environment Variables

Add to .env.local:

# Railway Docs API Token
RAILWAY_DOCS_TOKEN=<your-railway-project-token>
RAILWAY_PROJECTID_DOCS=<your-railway-project-id>

# MongoDB Test Modules Cluster
MONGODB_CONNECTION_STRING_TEST_MODULES=mongodb+srv://username:[email protected]/

# Shared Authentication (MUST match other APIs)
JWT_SECRET=<YOUR_JWT_SECRET_FROM_ENV_LOCAL>
SYSTEM_TOKEN=<your-system-token>

# Docs API Port (local only)
DOCS_API_PORT=3002

Step 2: Create Railway Project

Go to Railway Dashboard
Create new project: "backend-docs-api"
Create project token: Settings → Tokens → Create Token
Copy token to .env.local as RAILWAY_DOCS_TOKEN
Copy project ID to .env.local as RAILWAY_PROJECTID_DOCS

Step 3: Configure Railway Environment

In Railway dashboard, add these environment variables:

NODE_ENV=production
PORT=8080  # Railway sets this automatically
RAILWAY_ENVIRONMENT=true

# MongoDB (test-modules cluster)
MONGODB_CONNECTION_STRING_TEST_MODULES=mongodb+srv://...

# Authentication (MUST match other APIs)
JWT_SECRET=<same as backend-api>
SYSTEM_TOKEN=<same as other APIs>

# CORS
ALLOWED_ORIGINS=https://gograb.space,http://localhost:5010

# Network timeouts
NPM_CONFIG_FETCH_RETRIES=5
NPM_CONFIG_FETCH_TIMEOUT=300000
YARN_NETWORK_TIMEOUT=600000

Step 4: ⚠️ Verify Railway Dashboard Settings (CRITICAL!)

Before deploying, manually verify these settings in the Railway Dashboard:

Go to Railway Dashboard → backend-docs-api service → Settings

Build Settings

Setting	Must Be
Builder	`Dockerfile`
Dockerfile Path	`deployment/Dockerfile.railway.docs-api`

Deploy Settings

Setting	Must Be
Start Command	`node dist/apis/backend-docs-api/main.js`
Health Check Path	`/docs-api/health`

⚠️ WARNING: If the Dockerfile Path is wrong (e.g., pointing to backend-ai), you will deploy the WRONG API!

Step 5: Deploy

# Deploy to Railway
./deployment/deploy-docs-api.sh

Step 6: Verify Deployment

⚠️ Check Logs First (CRITICAL!)

In Railway Dashboard, check the logs for your backend-docs-api service:

# ✅ CORRECT - You should see:
[DOCS-API] 1  - 12/22/2025, 3:55:09 PM ...
📚 GoGrab Backend Docs API READY on port 8080

# ❌ WRONG - If you see:
[AI-API] 1  - 12/22/2025, 3:55:09 PM ...
🤖 GoGrab Backend AI API READY on port 8080  ← WRONG API!

If logs show [AI-API] instead of [DOCS-API], the Dockerfile Path is wrong! Go back to Step 4.

Health Check

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"
}

Test Endpoints

# Get manifest
curl https://backend-docs-api-production.up.railway.app/docs-api/sync/manifest

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

Step 7: Initial Bulk Sync

After deployment, sync all local docs to MongoDB:

# Option 1: Use the prod sync script (recommended)
yarn docs:sync:prod

# Option 2: Manual with environment variables
export DOCS_API_URL=https://backend-docs-api-production.up.railway.app/docs-api
export SYSTEM_TOKEN=<your-system-token>
yarn docs:sync

Step 8: Update Frontend

Update docs-angular production environment:

// 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,
};

✅ This file has already been updated with the production URL.

Architecture

flowchart LR
    Local["/docs folder"] -->|watch| Watcher["File Watcher"]
    Watcher -->|POST| DocsAPI["backend-docs-api<br/>Railway"]
    DocsAPI -->|write| MongoDB["MongoDB<br/>test-modules"]
    MongoDB -->|Change Streams| DocsAPI
    DocsAPI -->|WebSocket| Frontend["docs-angular<br/>gograb.space/docs"]

Monitoring

Railway Dashboard

Monitor your deployment:

Logs: View real-time logs in Railway dashboard
Metrics: CPU, memory, network usage
Deployments: Track deployment history

Health Checks

Railway automatically monitors /docs-api/health endpoint:

Interval: 30 seconds
Timeout: 30 seconds
Retries: 3 attempts before restart

MongoDB Monitoring

Check MongoDB Atlas dashboard for:

Connection count
Query performance
Storage usage
Change stream activity

Troubleshooting

Deployment Fails

Check Railway logs for build errors
Verify all environment variables are set
Ensure MongoDB connection string is correct
Check Dockerfile syntax

API Not Responding

Check Railway service status
Verify health check endpoint
Review application logs
Check MongoDB connection

Sync Not Working

Verify SYSTEM_TOKEN matches in all environments
Check file watcher is running locally
Review API logs for sync errors
Test manual sync: yarn docs:sync

Authentication Issues

Ensure JWT_SECRET is identical across all APIs
Verify token is being sent in Authorization header
Check token expiration (7 days default)
Test with curl: curl -H "Authorization: Bearer <token>" ...

Performance

Expected Performance

Health Check: <100ms
File Read: <200ms
File Write: <500ms
Bulk Sync: ~1s per 50 files
WebSocket Latency: <50ms

Optimization Tips

Use pagination for large file lists
Enable MongoDB compression
Use Change Streams for real-time updates (not polling)
Cache manifest on frontend

Security

Authentication

JWT tokens expire after 7 days
System token for internal service communication
All admin endpoints require JWT authentication
Public endpoints for reading documentation

MongoDB Security

Connection uses TLS/SSL
Credentials stored in Railway environment variables
Write concern: majority with journal
Read preference: primaryPreferred

Related APIs

Backend API (:3000) - Main platform API
Backend AI API (:3001) - AI/MCP API
Backend Docs API (:3002) - Documentation API

All three APIs share the same JWT authentication system.

Next Steps

Deploy to Railway
Run initial bulk sync
Update frontend environment
Build and deploy docs-angular static site
Test end-to-end flow

Support

For issues or questions:

Check Railway logs
Review MongoDB Atlas logs
Test locally first
Verify all environment variables