fix: update railway docs to include graceful shutdown

[MasterPtato]

Description

Please include a summary of the changes and the related issue. Please also include relevant motivation and context.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

How Has This Been Tested?

Please describe the tests that you ran to verify your changes.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[MasterPtato]

• fix(pb-outbound): add back serverless token #4817
• fix(pb-envoy): hard abort ws to tunnel on ping error #4776
• fix(outbound): implement drain grace period #4775
• fix(pb): fix pool config defaults #4774
• fix(pb): remove actor sleep ts when allocated #4772
• refactor(gateway): clean up and fix lost tunnel msgs #4771
• refactor(pb): fix actor overdue alarm handling #4770
• fix: update railway docs to include graceful shutdown #4715 👈 (View in Graphite)
• fix: add wf registry command #4714
• chore: move code #4713
• fix(gas): add large txn retries for pulling signals, tighten commit interval for actors #4712
• fix: improve epoxy propose errors, add gcp logging fmt #4698
• fix: autogenerate bare protocol versions #4696
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[claude]

PR #4715 Review: fix: update railway docs to include graceful shutdown

Summary: This PR adds ~16 lines to website/src/content/docs/self-hosting/railway.mdx, documenting Railway's graceful shutdown configuration for Rivet Engine. It adds a new ## Graceful Shutdown section and a cross-reference to it from Step 2 of the manual deployment instructions.

---

Overall Assessment

The change addresses a real operational gap — Railway's default 0-second drain window can silently affect in-flight state on every deploy. The content is accurate in its high-level guidance, but there are several correctness, completeness, and style issues worth addressing before merge.

---

Issues

1. Incorrect environment variable name (potential bug)

The PR references RAILWAY_DEPLOYMENT_DRAINING_SECONDS and drainingSeconds in config-as-code. Railway's actual environment variable is RAILWAY_DEPLOYMENT_OVERLAP_SECONDS and the railway.toml key is overlapSeconds. The dashboard UI labels it "Draining Seconds" but the programmatic names differ. A wrong variable name will silently have no effect. Please verify against Railway's current docs before publishing.

2. PID 1 / signal-forwarding guidance is scoped to the wrong service

The npm start / yarn start examples make sense for user application containers (Step 3 of the guide), but this section is attached to deploying Rivet Engine (rivetdev/engine:latest). The engine image has its own entrypoint — users don't start it with npm start. The guidance should be explicitly scoped to the user's own application service, or it should verify and document whether rivetdev/engine:latest already handles signals correctly (similar to how the Render doc uses exec /usr/bin/rivet-engine start). Mixing the two concerns without clear scoping will cause confusion.

3. Step 2 cross-reference wording is misleading

Listing "Configure graceful shutdown" as a numbered deploy step implies it is required engine container configuration. But the graceful shutdown section documents a Railway service-level setting (drain window), not a container env var. Suggested wording: "Configure the Railway draining window for this service (see Graceful Shutdown below)."

4. Quick Deploy path skips graceful shutdown guidance entirely

Users who use the Quick Deploy buttons (Railway template / Rivet Starter) never reach the manual deployment section and never see this guidance. Consider adding a <Note> or <Warning> near the Quick Deploy section noting whether the Rivet Railway template already configures an appropriate drain window (or that users need to set it manually).

5. Trailing whitespace

There are trailing spaces at the end of the dumb-init / tini bullet line that should be removed.

6. Config-as-code example is missing

The sentence mentions three mechanisms (dashboard, config-as-code, env var) but only the variable name is code-formatted. A concrete railway.toml snippet would help users on the config-as-code path:

[deploy]
overlapSeconds = 60  # verify key name against Railway docs

---

Minor Suggestions

• Rationale for 60 seconds. Noting what drives that number (e.g. typical actor state flush time, max in-flight request timeout) helps operators tune it for their workloads.
• Audit Railway docs links. The linked anchors (#singleton-deploys, /deployment-teardown) should be verified as live — Railway has a history of restructuring their docs.
• Production checklist gap. Since an unconfigured drain window can cause data loss on every deploy, this belongs as a bullet in the production checklist (/docs/self-hosting/production-checklist) alongside health checks and resource limits.

---

What the PR Gets Right

• The core observation — Railway's 0-second default drain window can affect in-flight state — is accurate and important to document.
• Cross-referencing the new section from Step 2 of the manual flow is the right structural choice.
• The dumb-init/tini guidance is correct general advice for containerized workloads.