pulse-railway

name	pulse-railway
description	Railway deployment utilities for Pulse applications. Use this skill when deploying Pulse apps with pulse-railway, configuring RailwayPlugin or RailwaySessionStore, running pulse-railway scaffold/ensure/deploy/redeploy/remove, migrating from pulse-aws to Railway, or debugging Railway router/session/deployment affinity behavior.

Pulse Railway

Deploys Pulse applications to Railway with one stable public router service and one backend Railway service per deployment. The router keeps old deployments alive and routes HTTP + websocket traffic by deployment affinity.

Quick Reference

import pulse as ps
from pulse_railway import RailwayPlugin, RailwaySessionStore

app = ps.App(
    routes=[...],
    plugins=[RailwayPlugin(dockerfile="Dockerfile")],
    session_store=RailwaySessionStore(),  # optional Redis-backed server sessions
)

uv run pulse-railway ensure \
  apps/my-app/main.py \
  --project my-railway-project \
  --environment production

uv run pulse-railway deploy \
  apps/my-app/main.py \
  --project my-railway-project \
  --environment production

uv run pulse-railway redeploy

When To Use

• deploying a Pulse app to Railway
• setting up or reconciling the stable pulse-router, pulse-env, pulse-redis, and pulse-janitor baseline
• rolling out new versions with deployment affinity
• preserving server-backed sessions through Railway Redis
• migrating a Pulse app from pulse-aws / AWSECSPlugin
• debugging /_pulse/meta, websocket routing, stale deployment affinity, or drained deployments

App Integration

Add RailwayPlugin(...) to the app. It injects pulse_deployment into prerender and Socket.IO directives and exposes /_pulse/meta. Set dockerfile=... there.

import os
import pulse as ps
from pulse_railway import RailwayPlugin, RailwaySessionStore

app = ps.App(
    routes=[...],
    plugins=[
        RailwayPlugin(
            dockerfile="Dockerfile",
            project="my-railway-project",
            environment="production",
            deployment_name="prod",
            # Optional: default image deploy repo.
            # image_repository="ghcr.io/acme/my-app",
        )
    ],
    session_store=RailwaySessionStore(),
    server_address=os.environ.get("PULSE_SERVER_ADDRESS"),
)

Use RailwaySessionStore() when the app needs server-backed sessions that survive redeploys. Do not read REDIS_URL directly for app sessions and do not hand-roll a Railway fallback. pulse-railway deploy injects PULSE_RAILWAY_REDIS_URL when it detects RailwaySessionStore().

CLI Workflow

Use RAILWAY_API_TOKEN for local user/workspace tokens. Reserve RAILWAY_TOKEN for Railway project tokens, especially in CI. If neither is set, pulse-railway falls back to the local Railway CLI login session from ~/.railway/config*.json. CLI login tokens are allowed for local API calls, but scaffold and ensure will not write them into the long-lived router or janitor services; set RAILWAY_TOKEN or RAILWAY_API_TOKEN when initializing or repairing runtime credentials.

First-time setup:

set -a; source .env; set +a

uv run pulse-railway ensure \
  apps/my-app/main.py

Deploy with Railway source builds by default:

uv run pulse-railway deploy \
  apps/my-app/main.py

Deploy by building and pushing an image locally:

uv run pulse-railway deploy \
  apps/my-app/main.py \
  --image-repository ghcr.io/acme/my-app

Redeploy the active backend service:

uv run pulse-railway redeploy \
  --project my-railway-project \
  --environment production

Redeploy a specific Pulse deployment id:

uv run pulse-railway redeploy \
  --deployment-id prod-260402-120000 \
  --project my-railway-project \
  --environment production

scaffold <app-file> and ensure <app-file> load the app and resolve project, environment, stable service names, and service prefix from RailwayPlugin. If project or environment is omitted from the plugin, the token must provide enough scope to infer them.

Use scaffold for fresh-only template setup. Use ensure for CI and repeated setup; it creates or reconciles the baseline with the official router and janitor images for the installed package version. If the router is in a Railway canvas group, ensure also moves Pulse baseline and deployment services into that group.

Target flags are shared by local commands:

• workspace: --workspace or --workspace-id; only needed to disambiguate project lookup by name
• project: --project-id, then --project, then RailwayPlugin(project=...); absent means infer from a project token
• environment: --environment-id, then --environment, then RailwayPlugin(environment=...), then the project token environment, then production

Use either the name or ID form for each target, not both.

deploy precedence:

• deployment name: --deployment-name, then RailwayPlugin(deployment_name=...), then prod
• image repository: --image-repository, then RailwayPlugin(image_repository=...); absent means source deploy
• server address: --server-address, then App(server_address=...), then the initialized router service address
• Dockerfile: RailwayPlugin(dockerfile=...); one is required for deploy
• web root: --web-root, then App(..., codegen=CodegenConfig(web_dir=...))

Path Rules

• scaffold/ensure app file is positional: pulse-railway ensure path/to/app.py
• deploy app file is positional: pulse-railway deploy path/to/app.py
• --context resolves from the shell invocation directory
• --web-root for deploy overrides must be relative to the deploy context
• source deploys use railway up, so the Railway CLI must be available
• image deploys use docker buildx build --push

Railway Model

pulse-railway scaffold creates, and pulse-railway ensure creates only on an empty project or reconciles mutable config on a complete baseline:

• stable public router service, default pulse-router
• stable env service, default pulse-env, for user-managed app variables
• stable Redis service, default pulse-redis, unless --redis-url is supplied
• janitor cron service, default pulse-janitor
• latest published official router/janitor GHCR image tags

The router resolves deployments from Redis only. Deploy registers a new backend deployment in Redis before checking it through the router with pulse_deployment=<id>, then promotes it active after the affinity check passes. Railway API calls belong to the deploy CLI/control plane, not the router request path.

scaffold is fresh-only. ensure fails on partial baselines instead of repairing missing services; delete partial leftovers and rerun scaffold. deploy is strict and will not repair missing baseline services.

If the router has no Railway canvas group, grouping reconciliation is skipped.

User-managed variables belong on pulse-env. New backend deployments reference every non-Pulse-managed variable from that service.

Migration From pulse-aws

Typical app migration:

• replace AWSECSPlugin() with RailwayPlugin(...)
• remove pulse-aws dependency and add pulse-railway
• replace AWS deploy wrapper with pulse-railway ensure / pulse-railway deploy
• if using custom Redis sessions, switch to RailwaySessionStore()
• set custom domains in the Railway UI and point them at the router service

Verification

After deploy:

curl https://<router-domain>/_pulse/meta

Check:

• /_pulse/meta returns the active deployment id
• app loads through the Railway router URL or custom domain
• session data survives a redeploy when using RailwaySessionStore()
• websocket navigation and actions still work after a redeploy
• old deployment services are deleted once they have no render sessions, or after the drain TTL

For a local repo example, inspect examples/railway/ and packages/pulse-railway/README.md.

Operational Gotchas

• Keep backend replicas at 1 unless sessions are safe across replicas; Railway does not provide replica-level sticky routing.
• The router can run multiple replicas because routing state lives in request affinity plus Redis.
• pulse-railway janitor run is for the deployed janitor service only and fails outside Railway.
• ensure rewrites janitor runtime env with PULSE_RAILWAY_SERVICE, PULSE_RAILWAY_JANITOR_SERVICE, and PULSE_RAILWAY_REDIS_SERVICE; rerun it after changing baseline service names.
• The janitor should run every 5 minutes or slower; Railway cron does not run more frequently.
• pulse-railway redeploy defaults to the active deployment in Redis; use --deployment-id for a specific Pulse deployment.
• If a deployment name matches multiple generated ids, pulse-railway remove fails and prints matches; retry with pulse-railway delete --deployment-id ....