Railway

How it works

The template deploys from the erpc/railway-deployment (opens in a new tab) repository and creates two Railway services:

• erpc — the proxy, listening on port 4000. Railway assigns a public URL automatically.
• monitoring — the same combined Prometheus v3.9.1 + Grafana 12.3.3 container as the repo's monitoring/Dockerfile. Grafana is accessible on port 3000.

The default erpc.yaml in the template uses public free RPC endpoints across all supported chains, so traffic flows immediately without any credentials.

Private networking. Services within the same Railway project communicate via .railway.internal hostnames without leaving Railway's network and without incurring egress costs. Services outside the project (or local clients) use the public URL.

Config customization. Railway deploys from a connected Git repository. To change erpc.yaml, fork erpc/railway-deployment (opens in a new tab), edit the config in your fork, and connect Railway to your fork under Settings → Source. Pushing to the connected branch triggers an automatic redeploy.

Monitoring. After deploying, open the monitoring service in Railway, find the Grafana URL under Settings → Networking → Public Networking, and log in with admin/admin. The Grafana dashboard loads automatically with 80+ panels covering request rates, latency, failover events, and cache metrics.

// Calling eRPC from another Railway service (private network)
const result = await fetch("https://my-erpc.railway.internal/main/evm/1", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    method: "eth_getBlockByNumber",
    params: ["0x1203319", false],
    id: 1,
    jsonrpc: "2.0",
  }),
});

Use the public URL (found under Settings → Networking → Public Networking in the eRPC service) for clients outside the same Railway project.

Config schema

Railway deployment has no eRPC-specific config fields. Configuration is entirely through erpc.yaml in the connected repository. Railway injects standard env vars (PORT, RAILWAY_ENVIRONMENT, etc.) which eRPC does not use directly.

The relevant eRPC env vars that operators may set via Railway's environment variable UI:

Worked examples

1. One-click deploy from the template. Click the Railway button above, sign in or create a Railway account, click Deploy. Done — both services start in under a minute.

2. Adding premium upstreams. Fork erpc/railway-deployment (opens in a new tab) and edit erpc.yaml to add your Alchemy or QuickNode keys. In Railway, go to your eRPC service → Settings → Source and connect your fork. Subsequent pushes to main auto-deploy:

# erpc.yaml in your fork
projects:
  - id: main
    networks:
      - architecture: evm
        evm:
          chainId: 1
        upstreams:
          - id: alchemy-mainnet
            endpoint: https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_KEY}

Set ALCHEMY_KEY as a Railway environment variable so it's not committed to the repo.

3. Enabling CORS for browser usage. If you call eRPC directly from a frontend, add a CORS block to erpc.yaml. See CORS for full options:

projects:
  - id: main
    cors:
      allowedOrigins:
        - "https://your-app.com"

4. Securing the public endpoint. The default config proxies all chains to anyone with the public URL. Add authentication before going to production:

projects:
  - id: main
    auth:
      strategies:
        - type: secret
          secret:
            value: ${AUTH_SECRET}

Set AUTH_SECRET in Railway's environment variable UI.

Best practices

• Change the Grafana password immediately. The monitoring service ships with admin/admin. Set a strong password via Railway environment variables before sharing the public Grafana URL.
• Set GOMEMLIMIT to ~90% of your Railway service's memory allocation. Without it, Go's GC may allow the heap to reach the hard memory limit and trigger a service restart.
• Use CORS before exposing to browsers. eRPC's default config has no CORS headers. Add a cors block under your project in erpc.yaml before consuming from a frontend. See CORS.
• Use authentication before going public. The default config proxies all supported chains without access control. Add authentication or rate limiters before exposing the public URL to untrusted clients.
• Keep secrets out of erpc.yaml. Use Railway environment variables for API keys and reference them as ${VAR_NAME} in your config file.
• Do not rely on the monitoring service for production observability. Prometheus and Grafana share one container — a crash in either is not independently restarted. For production monitoring, use separate Railway services or an external observability stack.

Edge cases & gotchas

1. Default credentials: Grafana ships with admin/admin. Set a strong password via Railway env vars before exposing the public URL.
2. CORS for browser usage: eRPC's default config has no CORS headers. Add a cors block under your project in erpc.yaml before consuming from a frontend. See CORS.
3. Config changes require a connected repo: Editing erpc.yaml triggers an automatic redeploy only if you connected your fork to Railway. Manual deploys are needed otherwise.
4. Monitoring container is single-process: Prometheus and Grafana share one container. A crash in either is not independently restarted. Not suitable for production monitoring.
5. Public URL exposes all chains: The default config proxies public endpoints for all supported chains. Add authentication or rate limiters before exposing the public URL to untrusted clients.
6. Private networking is project-scoped: The .railway.internal hostname is only reachable from services within the same Railway project. External clients must use the public URL.

Source code entry points

• railway-deployment repository (opens in a new tab) — template source with default erpc.yaml
• monitoring/Dockerfile (opens in a new tab) — combined Prometheus v3.9.1 + Grafana 12.3.3 image
• monitoring/scripts/entrypoint.sh (opens in a new tab) — dual-process startup and SERVICE_ENDPOINT substitution
• cmd/erpc/main.go:L354-L363 (opens in a new tab) — LOG_LEVEL env var handling
• cmd/erpc/main.go:L72-L74 (opens in a new tab) — SIGTERM graceful shutdown via signal.NotifyContext

Related pages

• Docker — self-hosted container deploy with local compose stack.
• Kubernetes — production-grade orchestration with resource sizing and drain tuning.
• Monitoring & metrics — full metrics reference for dashboards and alerting.
• Authentication — lock down the public endpoint before production traffic.
• Rate limiters — cap per-client or per-upstream traffic.
• CORS — required for browser-side usage.