keystonejs/keystone-6-railway-example

A simple example project showing how you might deploy Keystone 6 to Railway

Summary

The keystonejs/keystone-6-railway-example repository is an archived TypeScript example that demonstrates deploying a Keystone 6 headless CMS backend to Railway with PostgreSQL. It walks through Railway's service-injection model, where local code connects to remote Railway-hosted services so developers can work against a near-production environment without installing Postgres locally.

What it is useful for

This project is useful when an engineer wants to try Keystone 6 quickly with minimal infrastructure friction. It shows a one-click Railway deployment that provisions a Postgres plugin, applies Prisma migrations automatically, and wires up authentication scaffolding.

The codebase is intentionally minimal. Most of the Keystone logic lives in two files:

• schema.ts defines the lists, fields, and relationships.
• keystone.ts configures the system: database connection, authentication, and sessions.

Because the example deliberately omits advanced Keystone features such as hooks, the document field, and access control, it reads as a clear starting point rather than a production template. Teams needing those features will have to layer them in. The repository is archived, so it is best treated as historical reference for the workflow it documents rather than a maintained scaffold.

How engineers can use it

The README outlines a six-step workflow:

1. Deploy via the button. Click "Deploy on Railway" (Cmd-click to keep the guide open), authenticate with GitHub, and the button forks the repo into your account, deploys it with a Postgres plugin, and prompts for a SESSION_SECRET. The README notes this variable is optional, but leaving it unset regenerates a random value on each app start, which resets existing sessions.

2. Install prerequisites. NodeJS v14.13+, Yarn (or npm), git, and the Railway CLI. On macOS: brew install git node yarn railwayapp/railway/railway.

3. Get the code locally. Clone the repo Railway created in your GitHub account (not the original keystonejs org copy, since it lacks the deploy hooks), then run yarn.

4. Link to Railway. Run railway login followed by railway link <your-project-id>.

5. Start the app. Run railway run yarn dev to execute local code against the Railway-hosted database. The Admin UI appears at localhost:3000.

6. Iterate. Edit schema.ts or keystone.ts, then restart with Ctrl+C and re-run railway run yarn dev. Schema changes prompt a Prisma migration; the README documents adding a phone field as a worked example. Pushing to GitHub triggers redeployment via configured hooks.

The README also recommends creating a separate Railway environment (railway environment development) rather than developing against the live database, since resource usage is duplicated per environment. Because Railway's build script runs keystone-next prisma migrate deploy before rolling out the new app version, migrations need to be backwards-compatible with the previous release to avoid runtime errors during deployment. The README also warns against running railway run yarn build casually, as it applies outstanding migrations to whichever Railway environment is currently selected.