Railway Deployment Guide – Node.js / TypeScript (GFAVIP Wallet)

Overview

This guide covers the Node.js-based deployment process for the GFAVIP Wallet application on Railway.app. The stack includes Node.js v20+, TypeScript, Express, and PostgreSQL (managed via Drizzle ORM).

Last updated: March 2026

Critical Gotchas to Understand First

Railway deployments can fail silently due to two main issues with database migrations:

• Interactive Migration Trap: Commands like drizzle-kit push can pause for user input in ambiguous cases (column renames, etc.). Railway has no terminal, so it hangs or skips — leading to "column does not exist" crashes.
• Start Command Timing: The app must run migrations BEFORE starting the Express server. Default npm start behavior often starts the server too early.

Solution: Use a custom, non-interactive migration script in pure Node.js + pg, and chain it before the server start in package.json.

Recommended Configuration

Key settings include:

• Custom start script that runs migration first, then launches the app
• Idempotent raw SQL migrations in a standalone JS script (avoids tsx/ts-node issues in prod)
• Essential environment variables: DATABASE_URL, NODE_ENV=production, PORT, SESSION_SECRET, COOKIE_DOMAIN=.gfavip.com

Deployment Workflow Summary

1. Make schema changes (if any) in shared/schema.ts
2. Update the manual migration script with raw SQL for new/changed columns
3. Commit and push to main
4. Railway auto-deploys (build: npm install && npm run build, start: npm run start)
5. Watch logs for migration success messages

Debug & Verification Tool

After deployment, always check the health of the database connection and schema using this debug endpoint:

https://wallet.gfavip.com/debug/db-check

It shows connection status and basic schema validation — very useful for quick post-deploy checks.

Full Detailed Guide (Download)

For the complete step-by-step SOP including exact script examples, troubleshooting steps, emergency manual fixes via Railway CLI, and more — download the markdown version here:

Download Full Guide: railwaydeploy3.md

Quick Visual References

Railway provides a clean dashboard for monitoring deployments, logs, and database health.