a month ago
Hi Community,
I'm deploying a Medusa v2 monorepo (npm workspaces + Turborepo) and
hitting Railway's internal heartbeat timeout during build.
Railway's own diagnosis confirms:
"This deployment failed due to an internal platform timeout
during the build snapshot phase. The Medusa v2 monorepo installs
1,366 npm packages, causing the build to take 28-31 minutes and
exceed Railway's internal activity heartbeat limit. The build
itself actually completes successfully, but the deployment is
marked as failed before it finishes."
Setup:
- Builder: Railpack v0.25.0
- Project structure: apps/backend (Medusa v2.15.3)
- Build command: npm run build (turbo build under the hood)
- Pre-deploy: cd apps/backend && npm run predeploy
- Start: cd apps/backend && npm run start
Has anyone successfully deployed Medusa v2 monorepos on Railway?
Did you switch to Dockerfile? Are there best practices to avoid
this timeout?
Thanks!
Pinned Solution
a month ago
Hey nestorfloresv,
The build itself succeeds - Railway's heartbeat just kills it before it finishes. Two practical fixes:
- Switch to a Dockerfile. This bypasses Railpack's heartbeat-monitored build phase entirely. Multi-stage build with a cached node_modules layer cuts your 28-31 min install down dramatically on subsequent deploys.
- Trim the install scope. In your Railway build, you only need apps/backend deps, not the full monorepo. Scope your install:
cd apps/backend && npm install --workspace=apps/backend
Fewer packages = faster install = under the timeout.
- .npmrc cache hint. Add prefer-offline=true to .npmrc so Railway's layer cache gets used aggressively for the 1,366 packages.
Dockerfile is the most reliable path for heavy monorepos on Railway. Others have confirmed it works for Medusa v2 specifically. Worth the switch.
2 Replies
a month ago
This thread has been opened as a bounty so the community can help solve it.
Status changed to Open Railway • about 1 month ago
a month ago
Hey nestorfloresv,
The build itself succeeds - Railway's heartbeat just kills it before it finishes. Two practical fixes:
- Switch to a Dockerfile. This bypasses Railpack's heartbeat-monitored build phase entirely. Multi-stage build with a cached node_modules layer cuts your 28-31 min install down dramatically on subsequent deploys.
- Trim the install scope. In your Railway build, you only need apps/backend deps, not the full monorepo. Scope your install:
cd apps/backend && npm install --workspace=apps/backend
Fewer packages = faster install = under the timeout.
- .npmrc cache hint. Add prefer-offline=true to .npmrc so Railway's layer cache gets used aggressively for the 1,366 packages.
Dockerfile is the most reliable path for heavy monorepos on Railway. Others have confirmed it works for Medusa v2 specifically. Worth the switch.
a month ago
Update: Successfully deployed Medusa v2 monorepo on Railway! 🎉
Following the Dockerfile approach (recommendation #1) was indeed the key.
However, I want to share additional findings for future readers:
KEY INSIGHT: Don't prune devDependencies in the runtime image.
Medusa v2 needs TypeScript available at runtime to load:
- medusa-config.ts
- instrumentation.ts
- src/api/*.ts route handlers
- Even .ts files inside node_modules/@medusajs/*
I initially tried optimizing image size with npm prune --omit=dev and
copy steps for compiled files. This led to a cascade of "Cannot find module"
errors as Medusa's route scanner kept finding .ts files in different places.
The robust solution: keep node_modules complete (including devDeps).
Trade-off: ~600MB image vs ~400MB. For most use cases, this is acceptable.
My working Dockerfile structure:
- Builder stage: npm install --workspace=apps/backend + npm run build
- Runtime stage: COPY full node_modules + apps/backend, no prune
Additional gotchas I hit:
- Watch Paths must include Dockerfile + root config files for monorepos
- DISABLE_MEDUSA_ADMIN=true if you don't need admin in production
- Region of service must match Postgres/Redis region for latency
Hope this helps the next person! 🚂
Status changed to Solved passos • about 1 month ago