Railway Service Setup for Backend Docs API

You have the Railway project created ("Docs Api"), now let's add the service.

Current Status

✅ Railway project exists: "Docs Api"
⏳ Need to add service: "backend-docs-api"

Step-by-Step Service Creation

Step 1: Add Service in Railway Dashboard

1. Open your Railway project: https://railway.com/project/3990549d-4313-47e4-9682-d17b382bdba2
2. Click the "+ New" button or "Add a Service" button
3. Select "GitHub Repo"
4. Select your repository (the one containing this code)
5. Click "Add Service"

Step 2: Configure Service Settings

Once the service is created:

1. Name the service: Click on the service name and rename to "backend-docs-api"

2. Configure Build Settings:

   • Build Command: yarn install && nx build backend-docs-api --configuration=production
   • Start Command: node dist/apis/backend-docs-api/main.js

3. Set Root Directory (if asked):

   • Leave blank (root of monorepo)

Step 3: Add Environment Variables

Click "Variables" tab and add these:

NODE_ENV=production
PORT=${{PORT}}
RAILWAY_ENVIRONMENT=true

# MongoDB (test-modules cluster)
MONGODB_CONNECTION_STRING_TEST_MODULES=<your-mongodb-uri>

# Shared Authentication (MUST match backend-api)
JWT_SECRET=<copy-from-backend-api-railway-vars>
SYSTEM_TOKEN=<copy-from-backend-api-railway-vars>

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

# Build optimization
NPM_CONFIG_FETCH_RETRIES=5
NPM_CONFIG_FETCH_TIMEOUT=300000
NPM_CONFIG_NETWORK_TIMEOUT=600000
YARN_NETWORK_TIMEOUT=600000

Important: Copy JWT_SECRET and SYSTEM_TOKEN from your backend-api Railway variables to ensure shared authentication works.

Step 4: Configure Health Check

1. Click "Settings" tab
2. Scroll to "Health Check"
3. Set Health Check Path: /docs-api/health
4. Set Health Check Timeout: 30 seconds
5. Click "Save"

Step 5: Deploy

Railway will automatically start deploying. Watch the build logs:

1. Click "Deployments" tab
2. Click on the active deployment
3. Watch the logs

Expected logs:

Building...
Installing dependencies...
Building backend-docs-api...
✅ Build complete
Starting application...
📚 GoGrab Backend Docs API READY on port 8080

Step 6: Generate Domain

1. Go to "Settings" tab
2. Scroll to "Networking"
3. Click "Generate Domain"
4. Copy the generated URL (e.g., backend-docs-api-production.up.railway.app)

Step 7: Test Deployment

# Replace with your Railway domain
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"
}

✅ Service deployed successfully!

Alternative: Deploy via CLI

If you prefer using Railway CLI:

Step 1: Login to Railway

railway login

Step 2: Link to Project

# Use your project token
export RAILWAY_TOKEN=<your-RAILWAY_DOCS_TOKEN>

# Or link interactively
railway link
# Select: "Docs Api" project

Step 3: Deploy

cd /Users/fguijarro/developer/repos/editor
railway up --service backend-docs-api

Railway will:

1. Detect your code
2. Build using Nixpacks or Dockerfile
3. Start the service
4. Generate a URL

Using Our Deployment Script

Once the service exists, you can use our script:

./deployment/deploy-docs-api.sh

Note: The script requires:

• RAILWAY_DOCS_TOKEN in .env.local
• Service already created in Railway project

Troubleshooting

"No services found" Error

Solution: Create the service manually in Railway dashboard first (Step 1 above).

Build Fails

Check:

1. Build command is correct
2. All environment variables are set
3. MongoDB connection string is valid

Logs: View in Railway dashboard → Deployments → Click deployment → View logs

Health Check Fails

Check:

1. Health check path is /docs-api/health
2. App is actually starting (check logs)
3. Port is correct (Railway sets PORT env var)

Fix: Make sure main.ts uses process.env.PORT in Railway environment.

Can't Connect to MongoDB

Check:

1. MONGODB_CONNECTION_STRING_TEST_MODULES is correct
2. MongoDB Atlas network access allows Railway IPs (use 0.0.0.0/0)
3. Database user has read/write permissions

Next Steps After Service is Running

1. Get Railway URL: Copy from Settings → Networking

2. Update .env.local:

   RAILWAY_DOCS_API_URL=https://your-domain.railway.app
   

3. Run Initial Sync:

   export DOCS_API_URL=https://your-domain.railway.app/docs-api
   yarn docs:sync
   

4. Update Frontend Environment:

   // apps/docs-angular/src/environments/environment.prod.ts
   docsApiUrl: 'https://your-domain.railway.app/docs-api'
   

5. Build Frontend:

   nx build docs-angular --configuration=production
   

6. Deploy Frontend to gograb.space/docs

Railway Project Structure

Your project should look like:

Docs Api (Railway Project)
└── backend-docs-api (Service)
    ├── Variables (environment vars)
    ├── Settings (health check, networking)
    └── Deployments (build history)

Quick Reference

Railway Dashboard Tabs

• Architecture: Visual view of services
• Observability: Metrics and monitoring
• Logs: Real-time application logs
• Settings: Service configuration

Important URLs

• Dashboard: https://railway.com/project/
• Deployment Logs: Dashboard → Deployments → Click deployment
• Environment Variables: Dashboard → Variables
• Health Check Config: Dashboard → Settings

Support

If you encounter issues:

1. Check Railway documentation: https://docs.railway.app
2. View deployment logs in Railway dashboard
3. Test locally first: yarn serve:backend-docs
4. Verify all environment variables are set

Ready to create the service? Follow Step 1 above to add the backend-docs-api service to your Railway project!