Mercure documentation

Mercure is an open protocol for real-time updates over HTTP and Server-Sent Events (SSE). These guides cover the protocol and its open-source reference implementation, the Mercure.rocks Hub.

Looking for an alternative to Pusher / Ably / Firebase / Supabase Realtime? Mercure works with your existing backend and the browser's native APIs. Start with managed Mercure Cloud, or deploy Mercure Enterprise on your own infrastructure.

This documentation covers the protocol and the Mercure.rocks Hub for the 1.0 release. If you're upgrading from 0.x, start with the upgrade guide.

#Get started with Mercure

• Introduction: what Mercure is and when to use it
• Quickstart: run a hub, subscribe, and publish an update
• Installation: binary, Docker, Compose, Kubernetes, AUR

#Mercure core concepts

• Topics and matchers: select topics with exact matches and URL Patterns
• Subscribing: receive updates over SSE
• Publishing: send updates over HTTP
• Update payloads: envelopes for the data field, ActivityStreams 2.0
• Authorization: OAuth 2.0 access tokens, authorization_details, cookies
• Authorization servers: issuing tokens from Keycloak or another OAuth 2.0 server
• Discovery: finding the hub and its protected resource metadata
• Reconnection and history: Last-Event-ID, replay
• Active subscriptions: presence and the subscription API
• Encryption: JWE end-to-end

#Mercure use cases

• Use cases overview
• LLM token streaming
• AI agent progress
• Live data and dashboards
• Collaborative editing
• Async jobs and progress
• Notifications
• Hotwire / Turbo Streams
• GraphQL subscriptions
• Laravel Broadcasting

#Mercure hub deployment

• Configuration: Caddyfile directives and environment variables
• Docker
• Kubernetes
• Reverse proxies: NGINX and Traefik
• GitHub Actions

#Running Mercure in production

• High availability: scaling beyond one node
• Rolling updates: graceful shutdown for SSE
• Health checks and monitoring
• Tracing: OpenTelemetry spans
• Load testing
• Debugging
• Troubleshooting

#Mercure protocol reference

• Protocol: the IETF specification
• FAQ
• License
• Upgrade guide

#Mercure ecosystem

• Awesome Mercure: libraries, integrations, demos
• Conformance tests

#Mercure support and community

• GitHub Discussions for community questions
• Stack Overflow mercure tag
• #mercure on the Symfony Slack
• Cloud and Enterprise support: contact@mercure.rocks