Legacy Guide

Documentation for Deployment

Railway Deployment Guide

Date: November 1, 2025
Status: ✅ Complete
Purpose: Complete guide for deploying frontend and backend to Railway

📋 Table of Contents

  1. Overview
  2. Architecture
  3. Prerequisites
  4. Frontend Deployment
  5. Backend Deployment
  6. Troubleshooting
  7. Key Findings

Overview

This monorepo contains two separate Railway projects:

Project Apps Railway Project Service Name
Frontend gograb-space, docs-angular GoGrab-Unified GoGrab
Backend backend-api GoGrab API backend-api

Architecture

editor/ (monorepo)
├── apps/
│   ├── gograb-space/          → Frontend (GoGrab-Unified)
│   ├── docs-angular/           → Frontend (GoGrab-Unified)
│   └── backend-api/            → Backend (GoGrab API)
├── deployment/
│   ├── Dockerfile.railway.simple       (Frontend)
│   └── Dockerfile.railway.backend      (Backend)
└── scripts/
    ├── deploy-frontend.sh              ✅ Automated frontend deploy
    └── deploy-backend-fixed.sh         ✅ Automated backend deploy

Prerequisites

1. Railway CLI Installation

npm install -g @railway/cli

2. Railway Authentication

railway login

Verify:

railway whoami
# Should show: Logged in as GoGrab ([email protected]) 👋

3. Project IDs

Frontend (GoGrab-Unified):

Backend (GoGrab API):

Frontend Deployment

Quick Deploy

cd /Users/fguijarro/developer/repos/editor
./scripts/deploy-frontend.sh

Manual Steps

# 1. Link to frontend project
railway link --project 9fea5118-7c3c-45d9-845a-9cc7c22b2da6

# Select:
# - Workspace: GoGrab Projects
# - Project: GoGrab-Unified
# - Environment: production

# 2. Deploy
railway up -d

# 3. Monitor
# https://railway.app/project/9fea5118-7c3c-45d9-845a-9cc7c22b2da6

What Gets Deployed

Backend Deployment

Quick Deploy ✅

cd /Users/fguijarro/developer/repos/editor
./scripts/deploy-backend-fixed.sh

Manual Steps

# 1. Link to backend project
railway link --project 926d1c6f-0fad-41cd-a8ef-778289c79985

# Select:
# - Workspace: GoGrab Projects
# - Project: GoGrab API
# - Environment: production

# 2. Deploy with --service flag (CRITICAL!)
railway up -d --service backend-api

# 3. Monitor
# https://railway.app/project/926d1c6f-0fad-41cd-a8ef-778289c79985

What Gets Deployed

Troubleshooting

Issue 1: "No linked project found"

Problem: Running railway up returns "No linked project found"

Cause: The .railway/project.json file exists but Railway CLI hasn't established the link properly.

Solution:

# Re-link to the project
railway link --project <PROJECT_ID>

# Then deploy
railway up -d

Issue 2: "Multiple services found"

Problem: Running railway up returns "Multiple services found. Please specify a service via the --service flag."

Cause: The backend project has multiple services, and Railway needs to know which one to deploy.

Solution:

# Always use --service flag for backend
railway up -d --service backend-api

Issue 3: "404 on new endpoints after deployment"

Problem: New API endpoints return 404 even after deploying

Causes:

  1. Railway deployed before code was pushed to GitHub
  2. Railway is set to manual deploy (not auto-deploy)
  3. Wrong project was deployed

Solution:

# 1. Ensure code is in main branch
git checkout main
git log --oneline -5  # Verify latest changes are there

# 2. Push to GitHub
git push origin main

# 3. Link to correct project
railway link --project 926d1c6f-0fad-41cd-a8ef-778289c79985

# 4. Deploy with service flag
railway up -d --service backend-api

# 5. Wait 2-3 minutes for build

# 6. Test
curl https://backend-api-production-97c0.up.railway.app/api/health

Issue 4: Wrong project deployed

Problem: Deployed to frontend when trying to deploy backend

Cause: Railway CLI uses the link stored in .railway/project.json. If you previously linked to frontend, it stays linked.

Solution:

# Check current link
railway status

# If it shows wrong project, re-link
railway link --project <CORRECT_PROJECT_ID>

# Then deploy
railway up -d --service <SERVICE_NAME>

Key Findings

1. Railway Link Persistence

Finding: The .railway/project.json file stores the linked project, but this file can become stale or incorrect.

Implication: Always verify the link with railway status before deploying.

Best Practice: Use automated scripts that re-link before each deployment.

2. Service Flag Requirement

Finding: Backend project has multiple services, requiring the --service flag.

Why: The GoGrab API project may have multiple services (backend-api, database, etc.), so Railway needs explicit instruction on which service to deploy.

Solution: Always use --service backend-api when deploying backend.

3. Interactive Linking

Finding: railway link command is interactive and requires user input (workspace, project, environment selection).

Problem: This makes automation difficult in CI/CD pipelines.

Solution: Use the --project flag to pre-select the project:

railway link --project <PROJECT_ID>
# Then answer prompts: workspace → project → environment

4. Auto-Deploy vs Manual Deploy

Finding: Railway can auto-deploy on git push, but manual deploys via CLI are more reliable for monorepos.

Why: Monorepos have multiple apps, and auto-deploy might not trigger for the right app/service.

Best Practice: Use CLI deploy scripts for monorepos to ensure correct service is deployed.

5. Build Context

Finding: Railway builds from the repository root, not from the app directory.

Implication: Dockerfiles must reference files relative to repo root:

# ✅ Correct
COPY apis/backend-api/ ./apis/backend-api/

# ❌ Wrong (if Dockerfile expects to be in apis/backend-api/)
COPY ./ ./

Our Setup: All Dockerfiles in deployment/ folder, built from repo root.

Deployment Checklist

Before Deploying

Frontend Deployment

Backend Deployment

After Deployment

Quick Reference Commands

# Check Railway status
railway status

# View services in current project
railway service

# View logs
railway logs

# Open Railway dashboard
railway open

# Unlink current project
railway unlink

# Frontend Deploy
./scripts/deploy-frontend.sh

# Backend Deploy
./scripts/deploy-backend-fixed.sh

# Test Backend Health
curl https://backend-api-production-97c0.up.railway.app/api/health

# Test Backend Spaces Endpoint
curl -X POST https://backend-api-production-97c0.up.railway.app/api/spaces/initialize \
  -H "Content-Type: application/json" \
  -d '{}'

Future Improvements

1. CI/CD Pipeline

Create GitHub Actions workflow to auto-deploy on push to main:

# .github/workflows/deploy.yml
name: Deploy to Railway
on:
  push:
    branches: [main]
jobs:
  deploy-backend:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install -g @railway/cli
      - run: railway up -d --service backend-api
        env:
          RAILWAY_TOKEN: ${{ secrets.RAILWAY_TOKEN }}

2. Environment-Specific Configs

Create separate deploy scripts for staging/production:

3. Deployment Notifications

Add Slack/Discord notifications on successful/failed deployments.

4. Rollback Script

Create a quick rollback script that deploys the previous version:

./scripts/rollback-backend.sh

Related Documentation

Last Updated: November 1, 2025
Maintained By: GoGrab Space Team
Railway Account: GoGrab ([email protected])