Deploying Next.js on Railway: Lessons Learned
Lessons from moving a Next.js and Payload CMS site to Railway: builds, databases, migrations and the variables that break at 2 a.m.
Deploying a modern Next.js application looks simple: connect a repository, push, done. The reality involves a build system, a database, migrations and environment variables that all have to agree. Here is what running a Next.js and Payload CMS site on Railway taught me.
The build is where dependency problems surface. A clean install fails on peer dependency conflicts that a local machine with cached modules never noticed, so keep the lockfile committed and the framework versions within the ranges your CMS supports. Keep build artifacts and local files out of the repository; a stray build cache or database file in the build context causes confusing errors.
Use a real Postgres database from day one, even in development. SQLite is convenient locally, but a production container has an ephemeral filesystem, and a schema that was pushed automatically in development will not exist in production. Migrations, committed to the repository and applied at startup, are the only reliable path.
Environment variables are the most common cause of a deploy that "worked locally." Set them on the correct service and environment, apply staged changes, and make the application fail with a clear message when a required variable is missing. A generic 500 error is much harder to diagnose than "DATABASE_URL is not set."
Finally, check the deployed site, not just the deploy log. A container that starts successfully can still fail on the first request. Probe a page that touches the database and a page that does not; the difference tells you where to look.
