deploy-railway

name	deploy-railway
description	Deploy the Hyperindex frontend and backend to Railway. Use this skill when the user asks to deploy, redeploy, or update the production services on Railway.

Deploy Hyperindex to Railway

Project Layout

Hyperindex is a monorepo with two Railway services:

Service	Source	Dockerfile	Railway Name
Backend (Go)	repo root /	Dockerfile	backend
Frontend (Next.js)	client/	client/Dockerfile	frontend

Custom Domains

Service	Domain
Backend	https://api.hi.gainforest.app
Frontend	https://hi.gainforest.app

Legacy domains (still active): backend-production-95a22.up.railway.app, frontend-production-dcce.up.railway.app

Prerequisites

• Railway CLI v4+ installed and logged in (railway whoami)
• Linked to project: railway status should show project hyperindex
• On the correct git branch (typically tap-feature)

Deploy Backend

The backend deploys from the repo root using the root Dockerfile:

railway up -s backend -d

This uploads the entire repo, builds the Go binary in Docker, and deploys it. Takes ~3-5 minutes.

Verify backend:

curl -s https://api.hi.gainforest.app/
# Should return: {"name":"Hyperindex","version":"0.1.0-dev",...}

Deploy Frontend

CRITICAL: The frontend MUST use --path-as-root to avoid Railway picking up the root Go Dockerfile:

railway up --path-as-root client/ -s frontend -d

This makes client/ the archive root so Railway only sees client/Dockerfile (the Next.js build). Takes ~3-5 minutes.

Why --path-as-root?

Without it, railway up uploads the entire monorepo and Railway finds the root Dockerfile (Go backend) instead of client/Dockerfile (Next.js frontend). This causes the frontend service to run the Go binary instead of the Next.js app.

Verify frontend:

curl -s -o /dev/null -w "%{http_code}" https://hi.gainforest.app/
# Should return: 200

# Verify it's actually Next.js (not the Go server):
curl -s https://hi.gainforest.app/ | grep -o '<title>[^<]*</title>'
# Should return: <title>Hyperindex</title>

Deploy Both Services

# Backend (from repo root)
railway up -s backend -d

# Frontend (with path-as-root)
railway up --path-as-root client/ -s frontend -d

Environment Variables

Backend (backend service)

Variable	Value
HOST	0.0.0.0
PORT	8080
DATABASE_URL	sqlite:/app/data/hyperindex.db
EXTERNAL_BASE_URL	https://api.hi.gainforest.app
ADMIN_API_KEY	(must match frontend HYPERINDEX_ADMIN_API_KEY for proxied admin requests)
ADMIN_DIDS	did:plc:qc42fmqqlsmdq7jiypiiigww (daviddao.org)
OAUTH_LOOPBACK_MODE	true
SECRET_KEY_BASE	(set on Railway, do not change)

Frontend (frontend service)

Variable	Value
PORT	3000
NEXT_PUBLIC_CLIENT_URL	https://hi.gainforest.app
NEXT_PUBLIC_HYPERINDEX_URL	https://api.hi.gainforest.app
HYPERINDEX_URL	https://api.hi.gainforest.app
HYPERINDEX_ADMIN_API_KEY	(must match backend ADMIN_API_KEY; used by the Next.js admin proxy only)
COOKIE_SECRET	(set on Railway, do not change)
ATPROTO_JWK_PRIVATE	(ES256 JWK, set on Railway, do not change)

Note: NEXT_PUBLIC_HYPERINDEX_URL is a build-time variable (inlined by Next.js during npm run build). HYPERINDEX_ADMIN_API_KEY is server-side only and must be set as a runtime variable on the frontend service.

Troubleshooting

Frontend shows Go JSON response instead of HTML

You forgot --path-as-root client/. Redeploy with:

railway up --path-as-root client/ -s frontend -d

"Application not found" on custom domain

SSL certificate is still provisioning. Wait 5-15 minutes after adding DNS records.

GraphiQL returns 500 through frontend

GraphiQL is served directly by the backend. The frontend has a /graphiql server-side redirect route that redirects to https://api.hi.gainforest.app/graphiql.

OAuth login fails

Check that ATPROTO_JWK_PRIVATE and NEXT_PUBLIC_CLIENT_URL are set on the frontend service. Generate a new JWK with:

node scripts/generate-jwk.js  # (in hyperscan repo, or client/scripts/ if copied)

"admin privileges required" after login

Ensure the frontend HYPERINDEX_ADMIN_API_KEY matches the backend ADMIN_API_KEY. Without matching keys, the backend ignores the X-User-DID header from the Next.js proxy.

Setting Environment Variables

# Set a variable on a service
railway variables set 'KEY=value' -s backend
railway variables set 'KEY=value' -s frontend

# View all variables for a service
railway variables -s backend
railway variables -s frontend

After changing env vars, redeploy the affected service.