Brainforge Knowledge

files-brainforge-railway-migration

3 min read

files.brainforge.ai → Railway migration

Status: Migration checklist. Use this when moving files.brainforge.ai from Heroku to Railway.

Context

  • Domain: files.brainforge.ai — serves static assets (PDFs, etc.) from the brainforge-ai/brainforge-files GitHub repo at paths like /sales/ai/brainforge_ai_capabilities_deck.pdf.
  • Previous host: Heroku app brainforge-files-analytics (dashboard). DNS currently points to Heroku; the app returns 404 “No such app” and TLS fails (tlsv1 unrecognized name), so all links on files.brainforge.ai are broken.
  • Target host: Railway — same URL scheme, no link changes in platform/marketing.

Root cause (summary)

DNS for files.brainforge.ai still points at Heroku (*.herokudns.com). The Heroku app no longer exists or lost custom domain/cert. Fix: host the file proxy on Railway and point DNS at Railway.

Migration steps (do this now)

1. Deploy the files-proxy service on Railway

The repo includes a minimal proxy app at apps/files-proxy/ that serves paths from brainforge-ai/brainforge-files (GitHub raw).

From repo root, with Railway CLI installed and logged in (railway whoami):

cd apps/files-proxy
railway link    # select workspace, project (e.g. brainforge-platform), environment (e.g. production)
railway add     # add new service; name it e.g. "files-proxy"
railway service # switch to the files-proxy service

  • Root directory (required): In Railway dashboard → files-proxy service → Settings → General → set Root Directory to apps/files-proxy. If this is not set, the build runs from the repo root and the deployment will fail (build may not start or “Deployment failed during network process”).

  • Variables (optional): If brainforge-files is private, set GITHUB_TOKEN (or GITHUB_RAW_TOKEN) on the service so the proxy can fetch files. If the repo is public, no token is required for raw.githubusercontent.com.

  • Deploy:

    railway up --path-as-root

    Or from repo root: railway up apps/files-proxy --path-as-root

  • Verify: Open the Railway-generated URL (e.g. https://files-proxy-production-xxxx.up.railway.app/health) and a test path (e.g. /sales/ai/brainforge_ai_capabilities_deck.pdf). Confirm 200 and correct Content-Type.

2. Add custom domain in Railway

In the Railway dashboard (or via CLI):

  • Open the files-proxy service → Settings → Networking → Custom Domains.
  • Add domain: files.brainforge.ai.
  • Railway will show the CNAME target (e.g. xxxx.up.railway.app). Note it.

CLI alternative:

railway domain files.brainforge.ai --service files-proxy --json

Use the returned DNS instructions (CNAME record).

3. Update DNS

At your DNS provider (where brainforge.ai is managed):

  1. Remove or replace the existing CNAME for files.brainforge.ai that points to Heroku (e.g. metric-bat-....herokudns.com).

  2. Add a CNAME record:

    • Name/host: files (or files.brainforge.ai depending on provider).
    • Value/target: The Railway CNAME target from step 2 (e.g. xxxx.up.railway.app).
    • TTL: 300–3600 as preferred.

  3. Save and wait for propagation (often 5–30 minutes; can be up to 48 hours).

4. Verify

  • https://files.brainforge.ai/health → 200.
  • https://files.brainforge.ai/sales/ai/brainforge_ai_capabilities_deck.pdf → 200, PDF loads.
  • Platform Marketing Assets page and any hardcoded files.brainforge.ai links should work without code changes.

5. Optional: retire Heroku

After DNS has been pointing at Railway for at least 24–48 hours and all links are verified:

  • In Heroku dashboard, remove the custom domain files.brainforge.ai from the old app (if the app still exists).
  • Consider deleting the Heroku app brainforge-files-analytics if it is no longer used.

Troubleshooting

  • “Deployment failed during network process” or Build not started: Usually (1) Root Directory is not set to apps/files-proxy in the Railway service settings, or (2) the app crashed on startup (e.g. ensure the app uses ESM import not require when package.json has "type": "module"). Check View logs in Railway for the failing deployment.
  • Health check timeout: The service must respond with 200 at /health within 30s. If the process exits before that (e.g. uncaught exception), Railway reports a network/deploy failure.

References

  • Railway: Custom domains, CLI domain.
  • Playbook: Railway CLI setup, Paperclip setup (same pattern: custom domain + CNAME).
  • Platform: apps/platform/src/app/(main)/internal/marketing-assets/page.tsx builds URLs as https://files.brainforge.ai/${path}; repo brainforge-ai/brainforge-files.

Graph View

Backlinks