Mercure Hub

beginner

Real-time push notifications using Server-Sent Events.

Overview

Mercure is a modern protocol built on top of Server-Sent Events (SSE) that enables real-time web applications through efficient push notifications. Created by Kévin Dunglas, the founder of API Platform, Mercure addresses the complexity of WebSocket implementations by leveraging native browser APIs and HTTP/2 push capabilities. Unlike traditional polling or complex WebSocket setups, Mercure uses standard HTTP infrastructure and works transparently with CDNs, proxies, and firewalls. The Mercure Hub acts as a central message broker that receives updates from publishers and broadcasts them to authorized subscribers in real-time. Publishers send POST requests with JWT tokens to authenticate and specify topics, while subscribers connect using the browser's EventSource API to receive live updates. This architecture eliminates the need for custom WebSocket servers or complex message queuing systems, making real-time features accessible through standard web technologies. This configuration is ideal for developers building live applications who want the simplicity of HTTP with the power of real-time updates. Mercure excels in scenarios where you need to push live data to web browsers, mobile apps, or server-side consumers without the overhead of maintaining persistent WebSocket connections. The protocol's built-in features like automatic reconnection, message history, and topic-based subscriptions make it particularly valuable for teams transitioning from polling-based systems to true real-time architectures.

Key Features

JWT-based authentication for both publishers and subscribers with configurable keys
Topic-based message routing with wildcard subscription support
Automatic client reconnection with missed message recovery
Built-in CORS handling for cross-origin browser requests
Server-Sent Events protocol leveraging native browser EventSource API
HTTP/2 push support for enhanced performance with modern browsers
Link header discovery for automatic hub endpoint detection
Message history replay for subscribers joining after publication

Common Use Cases

1Live chat applications requiring real-time message delivery to multiple users
2E-commerce sites displaying live inventory updates and price changes
3Dashboard applications showing real-time metrics, analytics, and system status
4Collaborative editing tools with live document synchronization
5Trading platforms broadcasting live market data and price feeds
6IoT device monitoring with live sensor data streaming to web interfaces
7Social media feeds pushing live updates, likes, and comments to users

Prerequisites

Generate secure JWT keys for PUBLISHER_KEY and SUBSCRIBER_KEY environment variables
Basic understanding of Server-Sent Events and the EventSource JavaScript API
Port 80 available on the host system for the Mercure Hub endpoint
Minimum 512MB RAM for handling concurrent SSE connections
Knowledge of JWT token structure and claims for proper authentication setup

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  mercure: 
3    image: dunglas/mercure:latest
4    container_name: mercure
5    restart: unless-stopped
6    environment: 
7      SERVER_NAME: ':80'
8      MERCURE_PUBLISHER_JWT_KEY: ${PUBLISHER_KEY}
9      MERCURE_SUBSCRIBER_JWT_KEY: ${SUBSCRIBER_KEY}
10    ports: 
11      - "80:80"

.env Template

.env

1PUBLISHER_KEY=your-publisher-key
2SUBSCRIBER_KEY=your-subscriber-key

Usage Notes

1Docs: https://mercure.rocks/docs/
2Hub at http://localhost/.well-known/mercure
3Server-Sent Events - works natively in browsers (EventSource API)
4Publish: POST to hub with JWT token and topic/data
5Built by Symfony/API Platform creator - integrates well with PHP
6Discovery via Link header, auto-reconnection built-in

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  mercure:
5    image: dunglas/mercure:latest
6    container_name: mercure
7    restart: unless-stopped
8    environment:
9      SERVER_NAME: ':80'
10      MERCURE_PUBLISHER_JWT_KEY: ${PUBLISHER_KEY}
11      MERCURE_SUBSCRIBER_JWT_KEY: ${SUBSCRIBER_KEY}
12    ports:
13      - "80:80"
14EOF
15
16# 2. Create the .env file
17cat > .env << 'EOF'
18PUBLISHER_KEY=your-publisher-key
19SUBSCRIBER_KEY=your-subscriber-key
20EOF
21
22# 3. Start the services
23docker compose up -d
24
25# 4. View logs
26docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/mercure/run | bash

Troubleshooting

EventSource connection fails with CORS errors: Verify the hub allows your origin domain and check MERCURE_CORS_ALLOWED_ORIGINS if set
Publisher receives 401 Unauthorized when posting updates: Ensure JWT token includes valid 'mercure' claim with publish topics in the payload
Subscribers don't receive messages: Check that subscriber JWT token authorizes the subscribed topics in the 'mercure' claim
Hub responds with 'invalid JWT' errors: Verify PUBLISHER_KEY and SUBSCRIBER_KEY match the keys used to sign your tokens
Browser EventSource immediately disconnects: Check that SERVER_NAME environment variable matches your access domain or use ':80' for any domain

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

mercure

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download