Railway Deployment Guide

Date: November 1, 2025
Status: 🚀 In Progress
Purpose: Complete guide for deploying latest lambo-plan-2 changes to Railway

✅ Completed Steps

1. Git Operations:

   • ✅ Merged lambo-plan-2 into main branch
   • ✅ Pushed main to GitHub (commit: 507f66a6f)
   • ✅ All session changes now in main branch

2. Railway CLI Setup:

   • ✅ Installed Railway CLI v4.11.0
   • ✅ Verified login (GoGrab / [email protected])
   • ✅ CLI Path: /Users/fguijarro/.nvm/versions/node/v22.15.0/lib/node_modules/@railway/cli/bin/railway

3. Frontend Deployment:

   • ✅ Triggered deployment for GoGrab-Unified project
   • ✅ Build logs: https://railway.com/project/9fea5118-7c3c-45d9-845a-9cc7c22b2da6/service/45b32dc2-c650-440e-98dd-accf2ba9294a

🚧 Next Steps: Backend API Deployment

Your Railway setup has two separate projects:

Project 1: GoGrab-Unified (Frontend) ✅ DEPLOYED

• Project ID: 9fea5118-7c3c-45d9-845a-9cc7c22b2da6
• Service: GoGrab
• Status: Deployment in progress
• Config: railway.frontend.toml

Project 2: GoGrab API (Backend) ⏳ PENDING

• Project ID: 926d1c6f-0fad-41cd-a8ef-778289c79985
• Environment ID: 64e937b1-841e-437f-9a8f-f1b8db8c4137
• Config: railway.backend.toml
• Dockerfile: deployment/Dockerfile.railway.backend

📋 Manual Backend Deployment Options

Option 1: Railway Dashboard (Easiest)

1. Go to: https://railway.app/dashboard
2. Select project: "GoGrab API"
3. Go to the service/environment
4. Click "Deploy" or "Redeploy" button
5. Railway will pull latest from main and deploy

Option 2: Railway CLI (Command Line)

# Navigate to project directory
cd /Users/fguijarro/developer/repos/editor

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

# Deploy
railway up -d

Option 3: Auto-Deploy Setup

If you want automatic deployments on every push to main:

1. Go to Railway dashboard
2. Select "GoGrab API" project
3. Go to Settings → Source
4. Enable "Auto-deploy" for main branch
5. Future pushes will trigger automatic deploys

🔍 Deployment Verification

After both deployments complete, verify:

Frontend (gograb-space):

• ✅ App loads at your Railway frontend URL
• ✅ No console errors
• ✅ Space slug works correctly (uses user's space, not URL)
• ✅ Editable slug component saves properly

Backend API:

• ✅ Health check: https://your-backend-url/api/health
• ✅ Space initialization: POST /api/spaces/initialize
• ✅ Space updates: PUT /api/spaces/:id
• ✅ No 404 errors in frontend console

📦 What Was Deployed

All changes from the lambo-plan-2 session:

Core Fixes:

• ✅ Space slug management (always from user context in dev mode)
• ✅ Fixed circular dependency (API_BASE_URL injection token)
• ✅ Deployment mode system (development vs subdomain)
• ✅ Editable slug component (proper async handling)
• ✅ SpaceService offline-first with sync queue
• ✅ Enhanced console logging (LoggerService integration)

New Features:

• ✅ Space Sync Queue (offline → online auto-sync)
• ✅ API fallback (graceful 404 handling)
• ✅ Production-safe logging with enhanced styling

Documentation:

• ✅ SYNC-QUEUE-IMPLEMENTATION.md
• ✅ STORAGE-SYSTEM-IN-USE.md
• ✅ SYNC-MECHANISMS-AUDIT.md
• ✅ BACKEND-404-EXPLAINED.md

🎯 Expected Behavior After Deployment

Development Mode (Local):

• Space slug ALWAYS comes from user's profile
• URL slug is ignored
• Perfect for testing with one space

Production Mode (Railway):

• Space slug from subdomain/URL
• Multi-tenant support
• Correct space isolation

Offline-First:

• Works without backend (local storage fallback)
• Queues changes when offline
• Auto-syncs when online
• No data loss

🆘 Troubleshooting

If Backend Deployment Fails:

Check Dockerfile:

# Verify backend Dockerfile exists and is valid
cat deployment/Dockerfile.railway.backend

Check Build Logs:

• Go to Railway dashboard
• Click on the deployment
• View detailed error logs

Common Issues:

• Missing environment variables (DATABASE_URL, JWT_SECRET, etc.)
• Build timeout (increase in Railway settings)
• Dockerfile path incorrect

If Frontend Works But Backend 404s:

This is expected if backend isn't deployed yet! The app is designed to work offline-first:

• ✅ Frontend continues to work
• ✅ Uses local storage (GgStorage)
• ✅ Queues changes for later sync
• ⚠️ Backend sync will work once backend is deployed

📞 Quick Command Reference

# Railway CLI path (add to PATH or use full path)
export PATH="/Users/fguijarro/.nvm/versions/node/v22.15.0/lib/node_modules/@railway/cli/bin:$PATH"

# Check status
railway status

# List projects
railway list

# Deploy current linked project
railway up -d

# View logs
railway logs

# Open dashboard
railway open

✅ Deployment Checklist

• Merge lambo-plan-2 to main
• Push main to GitHub
• Install Railway CLI
• Deploy frontend (GoGrab-Unified)
• Deploy backend (GoGrab API) ← YOU ARE HERE
• Verify frontend loads
• Verify backend health check
• Test space slug functionality
• Test editable slug component
• Confirm offline-first works
• Confirm sync queue works

Last Updated: November 1, 2025
Next Action: Deploy backend API via Railway dashboard or CLI