Deploy Mercure

Deploy and Host Mercure on Railway

Mercure is an open protocol and hub for pushing real-time updates from servers to browsers and apps over Server-Sent Events. Your backend publishes an update to a topic with a signed token, and subscribed clients receive it instantly, with automatic reconnection, history replay and authorization built into the protocol.

About Hosting Mercure

This template deploys the Mercure.rocks hub v1.0.0, the first stable release, on Caddy with the bolt transport stored on a Railway volume so history survives restarts. Publishers and subscribers authenticate with OAuth 2.0-style access tokens signed with the two generated keys. The token issuer and audience are pinned to your Railway domain, which avoids the http versus https mismatch behind Railway's proxy. The safe debugger UI is enabled; the insecure playground is not. Add your frontend origin to cors_origins before subscribing from another domain. Everything runs in one small service that fits the Hobby plan.

Common Use Cases

• Live updates for dashboards, notifications and collaborative apps without WebSocket servers
• Pushing API resource changes to clients (API Platform, Symfony, Laravel and any backend)
• Streaming job progress or AI responses to the browser over SSE

Dependencies for Mercure Hosting

• dunglas/mercure:v1.0.0 (official image, Caddy based)
• A Railway volume at /data for the bolt history database

Deployment Dependencies

• Mercure documentation
• Mercure v1.0.0 release notes
• Upgrade guide to 1.0
• Railway volumes

Implementation Details

Tokens are JWTs (HS256) with typ: at+jwt, iss equal to MERCURE_TRUSTED_ISSUERS, aud equal to https:///.well-known/mercure, an exp, and an authorization_details array:

{"authorization_details": [{"type": "https://mercure.rocks/authorization-detail",
  "actions": ["publish"], "topics": [{"match": "https://example.com/books/1"}]}]}

Sign publisher tokens with MERCURE_PUBLISHER_JWT_KEY and subscriber tokens with MERCURE_SUBSCRIBER_JWT_KEY, then publish:

curl -X POST "$MERCURE_HUB_URL" -H "Authorization: Bearer " \
  -d "topic=https://example.com/books/1" -d 'data={"status":"shipped"}'

Notes:

• The 0.x mercure JWT claim is no longer accepted; mint tokens in the 1.0 format above.
• cors_origins * is not allowed together with authenticated subscribers; list your origins explicitly.
• Anonymous subscribers are off. Add anonymous to the extra directives only for topics you want public.

This is a community-maintained deployment package and does not imply affiliation with or endorsement by the Mercure project or its maintainers.

Why Deploy Mercure on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Mercure on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.