Day 36: mercure – Open-Source protocol for pushing data updates via SSE – 7 Days of Docker

29. August 2025

.SHARE

Mercure is an open-source protocol for pushing data updates to web browsers and other HTTP clients in real-time. It’s built on top of Server-Sent Events (SSE) and provides a fast, reliable, and battery-efficient way to implement real-time communications. The Mercure hub is distributed as a custom build of the Caddy web server with the Mercure module included.

In this guide, we’ll walk through setting up Mercure on your own server using Docker Compose, covering all the essential configuration options and environment variables you need to get started.

Basic Docker Compose Setup

Here’s a minimal Docker Compose configuration to get Mercure running:


# compose.yaml
services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      SERVER_NAME: "localhost"
      MERCURE_PUBLISHER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"
      MERCURE_SUBSCRIBER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - mercure_data:/data
      - mercure_config:/config

volumes:
  mercure_data:
  mercure_config:

# compose.yaml

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

environment:

SERVER_NAME: "localhost"

MERCURE_PUBLISHER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"

MERCURE_SUBSCRIBER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"

ports:

- "80:80"

- "443:443"

volumes:

- mercure_data:/data

- mercure_config:/config

volumes:

mercure_data:

mercure_config:

Development Configuration

For development purposes, you can enable the debug UI and allow anonymous subscribers:


# compose.yaml
services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      SERVER_NAME: "localhost"
      MERCURE_PUBLISHER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"
      MERCURE_SUBSCRIBER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"
      MERCURE_EXTRA_DIRECTIVES: |
        anonymous
        ui
        demo
    command: /usr/bin/caddy run --config /etc/caddy/dev.Caddyfile
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - mercure_data:/data
      - mercure_config:/config

volumes:
  mercure_data:
  mercure_config:

# compose.yaml

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

environment:

SERVER_NAME: "localhost"

MERCURE_PUBLISHER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"

MERCURE_SUBSCRIBER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"

MERCURE_EXTRA_DIRECTIVES: |

anonymous

demo

command: /usr/bin/caddy run --config /etc/caddy/dev.Caddyfile

ports:

- "80:80"

- "443:443"

volumes:

- mercure_data:/data

- mercure_config:/config

volumes:

mercure_data:

mercure_config:

Production Configuration with Health Checks

For production deployments, include health checks and proper security settings:


# compose.yaml
services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      # Server configuration
      SERVER_NAME: "mercure.yourdomain.com"
      
      # JWT Keys - CHANGE THESE IN PRODUCTION
      MERCURE_PUBLISHER_JWT_KEY: "your-strong-publisher-jwt-secret-key-here"
      MERCURE_SUBSCRIBER_JWT_KEY: "your-strong-subscriber-jwt-secret-key-here"
      MERCURE_PUBLISHER_JWT_ALG: "HS256"
      MERCURE_SUBSCRIBER_JWT_ALG: "HS256"
      
      # CORS configuration
      MERCURE_EXTRA_DIRECTIVES: |
        cors_origins https://yourdomain.com https://www.yourdomain.com
        publish_origins https://yourdomain.com https://www.yourdomain.com
        
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - mercure_data:/data
      - mercure_config:/config
    healthcheck:
      test: ["CMD", "wget", "-q", "--spider", "https://localhost/healthz"]
      timeout: 5s
      retries: 5
      start_period: 60s

volumes:
  mercure_data:
  mercure_config:

# compose.yaml

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

environment:

# Server configuration

SERVER_NAME: "mercure.yourdomain.com"

# JWT Keys - CHANGE THESE IN PRODUCTION

MERCURE_PUBLISHER_JWT_KEY: "your-strong-publisher-jwt-secret-key-here"

MERCURE_SUBSCRIBER_JWT_KEY: "your-strong-subscriber-jwt-secret-key-here"

MERCURE_PUBLISHER_JWT_ALG: "HS256"

MERCURE_SUBSCRIBER_JWT_ALG: "HS256"

# CORS configuration

MERCURE_EXTRA_DIRECTIVES: |

cors_origins https://yourdomain.com https://www.yourdomain.com

publish_origins https://yourdomain.com https://www.yourdomain.com

ports:

- "80:80"

- "443:443"

volumes:

- mercure_data:/data

- mercure_config:/config

healthcheck:

test: ["CMD", "wget", "-q", "--spider", "https://localhost/healthz"]

timeout: 5s

retries: 5

start_period: 60s

volumes:

mercure_data:

mercure_config:

HTTP-Only Setup (Behind Reverse Proxy)

If you’re running Mercure behind a reverse proxy and want to disable HTTPS:


# compose.yaml
services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      SERVER_NAME: ":80"  # Disable HTTPS
      MERCURE_PUBLISHER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"
      MERCURE_SUBSCRIBER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"
    ports:
      - "80:80"
    volumes:
      - mercure_data:/data
      - mercure_config:/config

volumes:
  mercure_data:
  mercure_config:

# compose.yaml

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

environment:

SERVER_NAME: ":80" # Disable HTTPS

MERCURE_PUBLISHER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"

MERCURE_SUBSCRIBER_JWT_KEY: "!ChangeThisMercureHubJWTSecretKey!"

ports:

- "80:80"

volumes:

- mercure_data:/data

- mercure_config:/config

volumes:

mercure_data:

mercure_config:

Environment Variables Reference

Core Configuration

SERVER_NAME: The server name or address (default: localhost)
- Examples: localhost, mercure.example.com, :3000, :80
MERCURE_PUBLISHER_JWT_KEY: JWT key for publishers (required)
MERCURE_SUBSCRIBER_JWT_KEY: JWT key for subscribers (required)
MERCURE_PUBLISHER_JWT_ALG: JWT algorithm for publishers (default: HS256)
MERCURE_SUBSCRIBER_JWT_ALG: JWT algorithm for subscribers (default: HS256)

Advanced Configuration

MERCURE_EXTRA_DIRECTIVES: Additional Mercure directives (multiline)


MERCURE_EXTRA_DIRECTIVES: |
  anonymous
  ui
  demo
  heartbeat 30s
  cors_origins https://example.com
  publish_origins https://example.com

MERCURE_EXTRA_DIRECTIVES: |

anonymous

demo

heartbeat 30s

cors_origins https://example.com

publish_origins https://example.com

CADDY_EXTRA_CONFIG: Additional Caddy configuration
CADDY_SERVER_EXTRA_DIRECTIVES: Additional Caddy server directives
GLOBAL_OPTIONS: Global Caddy options block

JWT Configuration Options

You can use different JWT algorithms:


# HMAC (symmetric key)
environment:
  MERCURE_PUBLISHER_JWT_KEY: "your-secret-key"
  MERCURE_PUBLISHER_JWT_ALG: "HS256"

# RSA (asymmetric key)
environment:
  MERCURE_PUBLISHER_JWT_KEY: |
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
    -----END PUBLIC KEY-----
  MERCURE_PUBLISHER_JWT_ALG: "RS256"

# HMAC (symmetric key)

environment:

MERCURE_PUBLISHER_JWT_KEY: "your-secret-key"

MERCURE_PUBLISHER_JWT_ALG: "HS256"

# RSA (asymmetric key)

environment:

MERCURE_PUBLISHER_JWT_KEY: |

-----BEGIN PUBLIC KEY-----

MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...

-----END PUBLIC KEY-----

MERCURE_PUBLISHER_JWT_ALG: "RS256"

Complete Production Example

Here’s a comprehensive production setup with all common options:


# compose.yaml
services:
  mercure:
    image: dunglas/mercure:latest
    restart: unless-stopped
    environment:
      # Server configuration
      SERVER_NAME: "mercure.yourdomain.com"
      
      # JWT Configuration
      MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_PUBLISHER_JWT_KEY}"
      MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_SUBSCRIBER_JWT_KEY}"
      MERCURE_PUBLISHER_JWT_ALG: "HS256"
      MERCURE_SUBSCRIBER_JWT_ALG: "HS256"
      
      # Mercure-specific directives
      MERCURE_EXTRA_DIRECTIVES: |
        cors_origins https://yourdomain.com https://api.yourdomain.com
        publish_origins https://yourdomain.com https://api.yourdomain.com
        heartbeat 40s
        dispatch_timeout 5s
        write_timeout 600s
        transport bolt://mercure.db?size=1000&cleanup_frequency=0.3
        
      # Additional Caddy configuration
      CADDY_EXTRA_CONFIG: |
        handle /health* {
          respond "OK" 200
        }
        
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - mercure_data:/data
      - mercure_config:/config
      - ./mercure.db:/data/mercure.db
    healthcheck:
      test: ["CMD", "wget", "-O-", "https://localhost/healthz"]
      timeout: 5s
      retries: 5
      start_period: 60s
    networks:
      - mercure_network

networks:
  mercure_network:
    driver: bridge

volumes:
  mercure_data:
  mercure_config:

# compose.yaml

services:

mercure:

image: dunglas/mercure:latest

restart: unless-stopped

environment:

# Server configuration

SERVER_NAME: "mercure.yourdomain.com"

# JWT Configuration

MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_PUBLISHER_JWT_KEY}"

MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_SUBSCRIBER_JWT_KEY}"

MERCURE_PUBLISHER_JWT_ALG: "HS256"

MERCURE_SUBSCRIBER_JWT_ALG: "HS256"

# Mercure-specific directives

MERCURE_EXTRA_DIRECTIVES: |

cors_origins https://yourdomain.com https://api.yourdomain.com

publish_origins https://yourdomain.com https://api.yourdomain.com

heartbeat 40s

dispatch_timeout 5s

write_timeout 600s

transport bolt://mercure.db?size=1000&cleanup_frequency=0.3

# Additional Caddy configuration

CADDY_EXTRA_CONFIG: |

handle /health* {

respond "OK" 200

}

ports:

- "80:80"

- "443:443"

volumes:

- mercure_data:/data

- mercure_config:/config

- ./mercure.db:/data/mercure.db

healthcheck:

test: ["CMD", "wget", "-O-", "https://localhost/healthz"]

timeout: 5s

retries: 5

start_period: 60s

networks:

- mercure_network

networks:

mercure_network:

driver: bridge

volumes:

mercure_data:

mercure_config:

Environment File Setup

Create a .env file for your secrets:


# .env file
MERCURE_PUBLISHER_JWT_KEY=your-super-secret-publisher-jwt-key-change-this-in-production
MERCURE_SUBSCRIBER_JWT_KEY=your-super-secret-subscriber-jwt-key-change-this-in-production

# .env file

MERCURE_PUBLISHER_JWT_KEY=your-super-secret-publisher-jwt-key-change-this-in-production

MERCURE_SUBSCRIBER_JWT_KEY=your-super-secret-subscriber-jwt-key-change-this-in-production

Mercure Directives Explained

Security Directives

anonymous: Allow subscribers without JWT tokens
cors_origins <origins>: Allowed CORS origins
publish_origins <origins>: Origins allowed to publish (cookie auth only)

Performance Directives

heartbeat <duration>: Interval between heartbeats (default: 40s)
dispatch_timeout <duration>: Max dispatch time per update (default: 5s)
write_timeout <duration>: Max connection duration (default: 600s)
transport <config>: Storage backend configuration

Feature Directives

ui: Enable the debug UI
demo: Enable demo endpoints
subscriptions: Enable subscription API

Accessing Your Mercure Hub

Once running, your Mercure hub will be available at:

Subscribe endpoint: GET https://your-domain/.well-known/mercure
Publish endpoint: POST https://your-domain/.well-known/mercure
Health check: GET https://your-domain/healthz
Debug UI (if enabled): GET https://your-domain/.well-known/mercure/ui/

Starting Your Setup

Save your Docker Compose configuration to compose.yaml
Create your .env file with secure JWT keys
Generate strong JWT keys (JWT Encoder / Decoder):


# Generate a random 256-bit key
openssl rand -hex 32

# Generate a random 256-bit key

openssl rand -hex 32

Start the service:


docker compose up -d

docker compose up -d

Check the logs:


docker compose logs -f mercure

docker compose logs -f mercure

Generating JWT Tokens

To publish updates, you’ll need to generate JWT tokens. Here’s a simple example in multiple languages:

PHP


use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$key = 'your-publisher-jwt-key';
$payload = [
    'mercure' =--> [
        'publish' => ['*'], // Allow publishing to all topics
         'subscribe'=> ["*"]          // Topics the token can subscribe to

    ]
];

$token = JWT::encode($payload, $key, 'HS256');

use Firebase\JWT\JWT;

use Firebase\JWT\Key;

$key = 'your-publisher-jwt-key';

$payload = [

'mercure' =--> [

'publish' => ['*'], // Allow publishing to all topics

'subscribe'=> ["*"] // Topics the token can subscribe to

]

];

$token = JWT::encode($payload, $key, 'HS256');

JavaScript/Node.js


const jwt = require('jsonwebtoken');

const key = 'your-publisher-jwt-key';
const payload = {
  mercure: {
    publish: ['*'] // Allow publishing to all topics
  }
};

const token = jwt.sign(payload, key, { algorithm: 'HS256' });

const jwt = require('jsonwebtoken');

const key = 'your-publisher-jwt-key';

const payload = {

mercure: {

publish: ['*'] // Allow publishing to all topics

}

};

const token = jwt.sign(payload, key, { algorithm: 'HS256' });

Python


import jwt

key = 'your-publisher-jwt-key'
payload = {
    'mercure': {
        'publish': ['*']  # Allow publishing to all topics
    }
}

token = jwt.encode(payload, key, algorithm='HS256')

import jwt

key = 'your-publisher-jwt-key'

payload = {

'mercure': {

'publish': ['*'] # Allow publishing to all topics

}

token = jwt.encode(payload, key, algorithm='HS256')

Publishing Updates

Once you have a JWT token, you can publish updates using a simple HTTP POST request:


curl -X POST https://your-domain/.well-known/mercure \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "topic=https://example.com/books/1" \
  -d "data={\"message\": \"Book updated!\"}"

curl -X POST https://your-domain/.well-known/mercure \

-H "Authorization: Bearer YOUR_JWT_TOKEN" \

-H "Content-Type: application/x-www-form-urlencoded" \

-d "topic=https://example.com/books/1" \

-d "data={\"message\": \"Book updated!\"}"

Subscribing to Updates

Clients can subscribe to updates using Server-Sent Events:


const eventSource = new EventSource('https://your-domain/.well-known/mercure?topic=https://example.com/books/1');

eventSource.onmessage = function(event) {
    console.log('Received update:', event.data);
};

eventSource.onerror = function(event) {
    console.error('Connection error:', event);
};

const eventSource = new EventSource('https://your-domain/.well-known/mercure?topic=https://example.com/books/1');

eventSource.onmessage = function(event) {

console.log('Received update:', event.data);

};

eventSource.onerror = function(event) {

console.error('Connection error:', event);

};

Advanced Configuration Examples

Multiple Topics and Private Updates


services:
  mercure:
    image: dunglas/mercure
    environment:
      SERVER_NAME: "mercure.example.com"
      MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_PUBLISHER_JWT_KEY}"
      MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_SUBSCRIBER_JWT_KEY}"
      MERCURE_EXTRA_DIRECTIVES: |
        # Enable subscriptions API for monitoring
        subscriptions
        # Custom heartbeat interval
        heartbeat 30s
        # Configure transport with history
        transport bolt://mercure.db?size=5000&cleanup_frequency=0.2
        # CORS for multiple domains
        cors_origins https://app.example.com https://admin.example.com
        publish_origins https://app.example.com https://admin.example.com

services:

mercure:

image: dunglas/mercure

environment:

SERVER_NAME: "mercure.example.com"

MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_PUBLISHER_JWT_KEY}"

MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_SUBSCRIBER_JWT_KEY}"

MERCURE_EXTRA_DIRECTIVES: |

# Enable subscriptions API for monitoring

subscriptions

# Custom heartbeat interval

heartbeat 30s

# Configure transport with history

transport bolt://mercure.db?size=5000&cleanup_frequency=0.2

# CORS for multiple domains

cors_origins https://app.example.com https://admin.example.com

publish_origins https://app.example.com https://admin.example.com

High Availability Setup


services:
  mercure:
    image: dunglas/mercure
    deploy:
      replicas: 3
    environment:
      SERVER_NAME: "mercure.example.com"
      MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_PUBLISHER_JWT_KEY}"
      MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_SUBSCRIBER_JWT_KEY}"
      MERCURE_EXTRA_DIRECTIVES: |
        # Use Redis for clustering
        transport redis://redis:6379
        # Optimized timeouts for HA
        dispatch_timeout 3s
        write_timeout 300s
        heartbeat 20s
    depends_on:
      - redis
    networks:
      - mercure_network

  redis:
    image: redis:alpine
    networks:
      - mercure_network

services:

mercure:

image: dunglas/mercure

deploy:

replicas: 3

environment:

SERVER_NAME: "mercure.example.com"

MERCURE_PUBLISHER_JWT_KEY: "${MERCURE_PUBLISHER_JWT_KEY}"

MERCURE_SUBSCRIBER_JWT_KEY: "${MERCURE_SUBSCRIBER_JWT_KEY}"

MERCURE_EXTRA_DIRECTIVES: |

# Use Redis for clustering

transport redis://redis:6379

# Optimized timeouts for HA

dispatch_timeout 3s

write_timeout 300s

heartbeat 20s

depends_on:

- redis

networks:

- mercure_network

redis:

image: redis:alpine

networks:

- mercure_network

Troubleshooting Common Issues

CORS Issues

If you’re experiencing CORS problems, make sure to configure the cors_origins directive properly:


MERCURE_EXTRA_DIRECTIVES: |
  cors_origins https://your-frontend-domain.com https://another-domain.com
  # Or allow all origins (NOT recommended for production)
  cors_origins *

MERCURE_EXTRA_DIRECTIVES: |

cors_origins https://your-frontend-domain.com https://another-domain.com

# Or allow all origins (NOT recommended for production)

cors_origins *

JWT Token Issues

Ensure your JWT tokens have the correct structure:


{
  "mercure": {
    "publish": ["*"],           // Topics the token can publish to
    "subscribe": ["*"]          // Topics the token can subscribe to
  }
}

{

"mercure": {

"publish": ["*"], // Topics the token can publish to

"subscribe": ["*"] // Topics the token can subscribe to

}

Connection Issues

Check if the Mercure hub is accessible:


# Test health endpoint
curl -k https://localhost/healthz

# Check if Mercure endpoint responds
curl -k https://localhost/.well-known/mercure

# Test health endpoint

curl -k https://localhost/healthz

# Check if Mercure endpoint responds

curl -k https://localhost/.well-known/mercure

Security Best Practices

Use strong JWT keys: Generate random, long keys for production
Restrict CORS origins: Only allow trusted domains
Use HTTPS: Always enable TLS in production
Limit topic access: Use specific topic patterns in JWT tokens
Regular key rotation: Rotate JWT keys periodically
Monitor access logs: Keep track of connections and publications

Performance Optimization

Transport Configuration

Optimize the Bolt database settings for your use case:


MERCURE_EXTRA_DIRECTIVES: |
  # Large history for high-traffic apps
  transport bolt://mercure.db?size=10000&cleanup_frequency=0.1
  
  # Smaller history for memory-constrained environments
  transport bolt://mercure.db?size=100&cleanup_frequency=0.5
  
  # No history (fastest, but no recovery for disconnected clients)
  transport local://local

MERCURE_EXTRA_DIRECTIVES: |

# Large history for high-traffic apps

transport bolt://mercure.db?size=10000&cleanup_frequency=0.1

# Smaller history for memory-constrained environments

transport bolt://mercure.db?size=100&cleanup_frequency=0.5

# No history (fastest, but no recovery for disconnected clients)

transport local://local

Timeout Configuration


MERCURE_EXTRA_DIRECTIVES: |
  # Faster dispatch for real-time apps
  dispatch_timeout 1s
  # Longer connection timeout for stable connections
  write_timeout 1200s
  # More frequent heartbeats for mobile clients
  heartbeat 15s

MERCURE_EXTRA_DIRECTIVES: |

# Faster dispatch for real-time apps

dispatch_timeout 1s

# Longer connection timeout for stable connections

write_timeout 1200s

# More frequent heartbeats for mobile clients

heartbeat 15s

Important Links

Official Website: https://mercure.rocks
GitHub Repository: https://github.com/dunglas/mercure
Docker Hub: https://hub.docker.com/r/dunglas/mercure
Documentation: https://mercure.rocks/docs/hub/install
Configuration Reference: https://mercure.rocks/docs/hub/config
Symfony Integration: https://symfony.com/doc/current/mercure.html

Your Mercure hub is now ready to handle real-time communications for your applications!

EXTRA: Setting Up Mercure with Caddy and NGINX Proxy Manager

1. Mercure Configuration with Caddy

First, let’s configure Mercure with its built-in Caddy server. Create a Caddyfile:


# Caddyfile for Mercure
{
    auto_https off  # If NGINX Proxy Manager handles SSL
}

:3000 {
    log {
        output stdout
        format console
        level INFO
    }

    mercure {
        # JWT key for publishers
        publisher_jwt !ChangeThisSecretKey!
        # JWT key for subscribers (optional)
        subscriber_jwt !ChangeThisSubscriberKey!
        
        # CORS configuration
        cors_origins "https://yourdomain.com" "https://app.yourdomain.com"
        publish_origins "*"
        
        # Allow anonymous subscribers (optional)
        anonymous
        
        # UI for debugging
        demo
    }

    respond /healthz 200
}

# Caddyfile for Mercure

{

auto_https off # If NGINX Proxy Manager handles SSL

}

:3000 {

log {

output stdout

format console

level INFO

}

mercure {

# JWT key for publishers

publisher_jwt !ChangeThisSecretKey!

# JWT key for subscribers (optional)

subscriber_jwt !ChangeThisSubscriberKey!

# CORS configuration

cors_origins "https://yourdomain.com" "https://app.yourdomain.com"

publish_origins "*"

# Allow anonymous subscribers (optional)

anonymous

# UI for debugging

demo

}

respond /healthz 200

}

Or using environment variables in docker-compose.yml:


version: '3.8'

services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      # Mercure configuration
      MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisSecretKey!'
      MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisSubscriberKey!'
      
      # CORS settings
      MERCURE_CORS_ALLOWED_ORIGINS: "https://yourdomain.com https://app.yourdomain.com"
      MERCURE_PUBLISH_ALLOWED_ORIGINS: '*'
      
      # Optional: Allow anonymous subscribers
      MERCURE_ANONYMOUS: "1"
      
      # Optional: Enable debug UI
      MERCURE_DEMO: "1"
      
      # Server configuration
      SERVER_NAME: ':3000'
      MERCURE_TRANSPORT_URL: "bolt://mercure.db"
      
      # Disable Caddy's auto HTTPS since NGINX will handle it
      CADDY_AUTO_HTTPS: "off"
    ports:
      - "3000:3000"
    volumes:
      - mercure_data:/data
      - mercure_config:/config

volumes:
  mercure_data:
  mercure_config:

version: '3.8'

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

environment:

# Mercure configuration

MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisSecretKey!'

MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisSubscriberKey!'

# CORS settings

MERCURE_CORS_ALLOWED_ORIGINS: "https://yourdomain.com https://app.yourdomain.com"

MERCURE_PUBLISH_ALLOWED_ORIGINS: '*'

# Optional: Allow anonymous subscribers

MERCURE_ANONYMOUS: "1"

# Optional: Enable debug UI

MERCURE_DEMO: "1"

# Server configuration

SERVER_NAME: ':3000'

MERCURE_TRANSPORT_URL: "bolt://mercure.db"

# Disable Caddy's auto HTTPS since NGINX will handle it

CADDY_AUTO_HTTPS: "off"

ports:

- "3000:3000"

volumes:

- mercure_data:/data

- mercure_config:/config

volumes:

mercure_data:

mercure_config:

2. NGINX Proxy Manager Configuration

In NGINX Proxy Manager, create a proxy host with these settings:

Details Tab:

Domain Names: mercure.yourdomain.com
Scheme: http
Forward Hostname/IP: mercure (or the container name/IP)
Forward Port: 3000
Enable “Websockets Support” ✓ (Important!)
Enable “Block Common Exploits” ✓
Enable “HTTP/2 Support” ✓

SSL Tab:

Request SSL Certificate with Let’s Encrypt
Force SSL ✓

Advanced Tab – Custom Nginx Configuration:


# Proxy headers for Mercure
proxy_read_timeout 24h;
proxy_http_version 1.1;
proxy_set_header Connection "";

# Important for SSE (Server-Sent Events)
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding off;

# Keep connections alive
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;

# CORS headers (if Mercure's CORS isn't sufficient)
add_header 'Access-Control-Allow-Origin' $http_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Mercure' always;

# Handle preflight requests
if ($request_method = 'OPTIONS') {
    add_header 'Access-Control-Allow-Origin' $http_origin always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Mercure' always;
    add_header 'Access-Control-Max-Age' 1728000;
    add_header 'Content-Type' 'text/plain; charset=utf-8';
    add_header 'Content-Length' 0;
    return 204;
}

# SSE specific headers
add_header 'Cache-Control' 'no-cache';
add_header 'X-Accel-Buffering' 'no';

# Proxy headers for Mercure

proxy_read_timeout 24h;

proxy_http_version 1.1;

proxy_set_header Connection "";

# Important for SSE (Server-Sent Events)

proxy_buffering off;

proxy_cache off;

chunked_transfer_encoding off;

# Keep connections alive

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Proto $scheme;

# CORS headers (if Mercure's CORS isn't sufficient)

add_header 'Access-Control-Allow-Origin' $http_origin always;

add_header 'Access-Control-Allow-Credentials' 'true' always;

add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;

add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Mercure' always;

# Handle preflight requests

if ($request_method = 'OPTIONS') {

add_header 'Access-Control-Allow-Origin' $http_origin always;

add_header 'Access-Control-Allow-Credentials' 'true' always;

add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;

add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Mercure' always;

add_header 'Access-Control-Max-Age' 1728000;

add_header 'Content-Type' 'text/plain; charset=utf-8';

add_header 'Content-Length' 0;

return 204;

}

# SSE specific headers

add_header 'Cache-Control' 'no-cache';

add_header 'X-Accel-Buffering' 'no';

3. Working CORS Configuration for NGINX Proxy Manager

Option 1: Simple CORS Configuration (Recommended)

In the Advanced Tab of your proxy host, add this configuration that works within NPM’s limitations:


# Proxy settings for Mercure/SSE
proxy_read_timeout 24h;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding off;

# SSE specific
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;

# CORS headers - always append
add_header 'Access-Control-Allow-Origin' $http_origin always;
add_header 'Access-Control-Allow-Credentials' 'true' always;
add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Mercure' always;
add_header 'Access-Control-Max-Age' '86400' always;

# SSE headers
add_header 'Cache-Control' 'no-cache' always;
add_header 'X-Accel-Buffering' 'no' always;

# Proxy settings for Mercure/SSE

proxy_read_timeout 24h;

proxy_http_version 1.1;

proxy_set_header Connection "";

proxy_buffering off;

proxy_cache off;

chunked_transfer_encoding off;

# SSE specific

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Proto $scheme;

# CORS headers - always append

add_header 'Access-Control-Allow-Origin' $http_origin always;

add_header 'Access-Control-Allow-Credentials' 'true' always;

add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;

add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range,Authorization,Mercure' always;

add_header 'Access-Control-Max-Age' '86400' always;

# SSE headers

add_header 'Cache-Control' 'no-cache' always;

add_header 'X-Accel-Buffering' 'no' always;

Option 2: Let Mercure Handle CORS (Cleaner Approach)

Since Mercure has built-in CORS support, you can configure CORS entirely in Mercure and just focus on proxy settings in NPM:

NGINX Proxy Manager Advanced Config:


# Minimal proxy configuration
proxy_read_timeout 24h;
proxy_http_version 1.1;
proxy_set_header Connection "";

# Critical for SSE
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding off;
add_header 'X-Accel-Buffering' 'no' always;

# Forward headers
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Real-IP $remote_addr;

# Minimal proxy configuration

proxy_read_timeout 24h;

proxy_http_version 1.1;

proxy_set_header Connection "";

# Critical for SSE

proxy_buffering off;

proxy_cache off;

chunked_transfer_encoding off;

add_header 'X-Accel-Buffering' 'no' always;

# Forward headers

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Proto $scheme;

proxy_set_header X-Real-IP $remote_addr;

Mercure Docker Configuration:


version: '3.8'

services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    environment:
      # JWT keys
      MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisSecretKey32Characters!'
      MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisSubscriberKey32Characters!'
      
      # Let Mercure handle ALL CORS
      MERCURE_CORS_ALLOWED_ORIGINS: "*"  # Or specific origins
      MERCURE_PUBLISH_ALLOWED_ORIGINS: "*"
      
      # Allow OPTIONS preflight
      MERCURE_CORS_ALLOW_CREDENTIALS: "true"
      
      # Other settings
      MERCURE_ANONYMOUS: "1"
      MERCURE_DEMO: "1"
      SERVER_NAME: ':3000'
      CADDY_AUTO_HTTPS: "off"
    ports:
      - "3000:3000"

version: '3.8'

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

environment:

# JWT keys

MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisSecretKey32Characters!'

MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisSubscriberKey32Characters!'

# Let Mercure handle ALL CORS

MERCURE_CORS_ALLOWED_ORIGINS: "*" # Or specific origins

MERCURE_PUBLISH_ALLOWED_ORIGINS: "*"

# Allow OPTIONS preflight

MERCURE_CORS_ALLOW_CREDENTIALS: "true"

# Other settings

MERCURE_ANONYMOUS: "1"

MERCURE_DEMO: "1"

SERVER_NAME: ':3000'

CADDY_AUTO_HTTPS: "off"

ports:

- "3000:3000"

Option 3: Using Custom Location Block

Some versions of NPM allow custom location blocks. Try this in the Advanced tab:


location /.well-known/mercure {
    proxy_pass http://mercure:3000/.well-known/mercure;
    proxy_read_timeout 24h;
    proxy_http_version 1.1;
    
    # SSE requirements
    proxy_set_header Connection "";
    proxy_buffering off;
    proxy_cache off;
    
    # Headers
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    # CORS
    add_header 'Access-Control-Allow-Origin' $http_origin always;
    add_header 'Access-Control-Allow-Credentials' 'true' always;
    add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;
    add_header 'Access-Control-Allow-Headers' 'Authorization,Mercure,Content-Type' always;
    add_header 'X-Accel-Buffering' 'no' always;
}

location /.well-known/mercure {

proxy_pass http://mercure:3000/.well-known/mercure;

proxy_read_timeout 24h;

proxy_http_version 1.1;

# SSE requirements

proxy_set_header Connection "";

proxy_buffering off;

proxy_cache off;

# Headers

proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

proxy_set_header X-Forwarded-Host $host;

proxy_set_header X-Forwarded-Proto $scheme;

# CORS

add_header 'Access-Control-Allow-Origin' $http_origin always;

add_header 'Access-Control-Allow-Credentials' 'true' always;

add_header 'Access-Control-Allow-Methods' 'GET, POST, OPTIONS' always;

add_header 'Access-Control-Allow-Headers' 'Authorization,Mercure,Content-Type' always;

add_header 'X-Accel-Buffering' 'no' always;

}

4. Complete Docker Compose Setup

Here’s a complete setup with both services:


version: '3.8'

networks:
  web:
    external: true
  internal:
    external: false

services:
  mercure:
    image: dunglas/mercure
    restart: unless-stopped
    networks:
      - internal
      - web
    environment:
      MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisSecretKey32Characters!'
      MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisSubscriberKey32Characters!'
      MERCURE_CORS_ALLOWED_ORIGINS: "https://yourdomain.com https://app.yourdomain.com http://localhost:3000"
      MERCURE_PUBLISH_ALLOWED_ORIGINS: '*'
      MERCURE_ANONYMOUS: "1"
      MERCURE_DEMO: "1"
      SERVER_NAME: ':3000'
      CADDY_AUTO_HTTPS: "off"
    volumes:
      - mercure_data:/data
      - mercure_config:/config
    labels:
      - "traefik.enable=false"  # If using Traefik alongside

  nginx-proxy-manager:
    image: 'jc21/nginx-proxy-manager:latest'
    restart: unless-stopped
    ports:
      - '80:80'
      - '443:443'
      - '81:81'  # Admin GUI
    networks:
      - web
      - internal
    volumes:
      - npm_data:/data
      - npm_letsencrypt:/etc/letsencrypt

volumes:
  mercure_data:
  mercure_config:
  npm_data:
  npm_letsencrypt:

version: '3.8'

networks:

web:

external: true

internal:

external: false

services:

mercure:

image: dunglas/mercure

restart: unless-stopped

networks:

- internal

- web

environment:

MERCURE_PUBLISHER_JWT_KEY: '!ChangeThisSecretKey32Characters!'

MERCURE_SUBSCRIBER_JWT_KEY: '!ChangeThisSubscriberKey32Characters!'

MERCURE_CORS_ALLOWED_ORIGINS: "https://yourdomain.com https://app.yourdomain.com http://localhost:3000"

MERCURE_PUBLISH_ALLOWED_ORIGINS: '*'

MERCURE_ANONYMOUS: "1"

MERCURE_DEMO: "1"

SERVER_NAME: ':3000'

CADDY_AUTO_HTTPS: "off"

volumes:

- mercure_data:/data

- mercure_config:/config

labels:

- "traefik.enable=false" # If using Traefik alongside

nginx-proxy-manager:

image: 'jc21/nginx-proxy-manager:latest'

restart: unless-stopped

ports:

- '80:80'

- '443:443'

- '81:81' # Admin GUI

networks:

- web

- internal

volumes:

- npm_data:/data

- npm_letsencrypt:/etc/letsencrypt

volumes:

mercure_data:

mercure_config:

npm_data:

npm_letsencrypt:

5. Testing Your Configuration

Test Mercure directly:


# Test health endpoint
curl http://localhost:3000/healthz

# Test through NGINX Proxy Manager
curl https://mercure.yourdomain.com/.well-known/mercure

# Test health endpoint

curl http://localhost:3000/healthz

# Test through NGINX Proxy Manager

curl https://mercure.yourdomain.com/.well-known/mercure

Test CORS:


# Test CORS preflight
curl -I -X OPTIONS https://mercure.yourdomain.com/.well-known/mercure \
  -H "Origin: https://yourdomain.com" \
  -H "Access-Control-Request-Method: GET"

# Test CORS preflight

curl -I -X OPTIONS https://mercure.yourdomain.com/.well-known/mercure \

-H "Origin: https://yourdomain.com" \

-H "Access-Control-Request-Method: GET"

Check if Mercure is accessible:


curl -I https://mercure.yourdomain.com/.well-known/mercure

curl -I https://mercure.yourdomain.com/.well-known/mercure

Test CORS headers are present:


curl -I https://mercure.yourdomain.com/.well-known/mercure \
  -H "Origin: https://yourdomain.com"

curl -I https://mercure.yourdomain.com/.well-known/mercure \

-H "Origin: https://yourdomain.com"

You should see headers like:


Access-Control-Allow-Origin: https://yourdomain.com
Access-Control-Allow-Credentials: true
Access-Control-Allow-Methods: GET, POST, OPTIONS

Access-Control-Allow-Origin: https://yourdomain.com

Access-Control-Allow-Credentials: true

Access-Control-Allow-Methods: GET, POST, OPTIONS

JavaScript client example:


// Subscribe to updates
const url = new URL('https://mercure.yourdomain.com/.well-known/mercure');
url.searchParams.append('topic', 'https://example.com/my-topic');

const eventSource = new EventSource(url, {
    withCredentials: true  // If using cookies for auth
});

eventSource.onmessage = (event) => {
    console.log('New message:', JSON.parse(event.data));
};

// Publish updates (requires JWT)
fetch('https://mercure.yourdomain.com/.well-known/mercure', {
    method: 'POST',
    headers: {
        'Authorization': 'Bearer YOUR_JWT_TOKEN',
        'Content-Type': 'application/x-www-form-urlencoded',
    },
    body: new URLSearchParams({
        'topic': 'https://example.com/my-topic',
        'data': JSON.stringify({ message: 'Hello!' })
    })
});

// Subscribe to updates

const url = new URL('https://mercure.yourdomain.com/.well-known/mercure');

url.searchParams.append('topic', 'https://example.com/my-topic');

const eventSource = new EventSource(url, {

withCredentials: true // If using cookies for auth

});

eventSource.onmessage = (event) => {

console.log('New message:', JSON.parse(event.data));

};

// Publish updates (requires JWT)

fetch('https://mercure.yourdomain.com/.well-known/mercure', {

method: 'POST',

headers: {

'Authorization': 'Bearer YOUR_JWT_TOKEN',

'Content-Type': 'application/x-www-form-urlencoded',

body: new URLSearchParams({

'topic': 'https://example.com/my-topic',

'data': JSON.stringify({ message: 'Hello!' })

})

});

Test with a simple HTML client:


<!DOCTYPE html>
<html>
<head>
    <title>Mercure Test</title>
</head>
<body>
    <div id="messages"></div>
    <script>
        const url = new URL('https://mercure.yourdomain.com/.well-known/mercure');
        url.searchParams.append('topic', 'test');
        
        const eventSource = new EventSource(url, {
            withCredentials: true
        });
        
        eventSource.onopen = () => {
            console.log('Connected to Mercure');
            document.getElementById('messages').innerHTML += '<p>Connected!</p>';
        };
        
        eventSource.onmessage = (e) => {
            console.log('Message:', e.data);
            document.getElementById('messages').innerHTML += `<p>${e.data}</p>`;
        };
        
        eventSource.onerror = (error) => {
            console.error('EventSource error:', error);
        };
    </script>
</body>
</html>

<!DOCTYPE html>

<html>

<head>

<title>Mercure Test</title>

</head>

<body>

const url = new URL('https://mercure.yourdomain.com/.well-known/mercure');

url.searchParams.append('topic', 'test');

const eventSource = new EventSource(url, {

withCredentials: true

});

eventSource.onopen = () => {

console.log('Connected to Mercure');

document.getElementById('messages').innerHTML += '<p>Connected!</p>';

};

eventSource.onmessage = (e) => {

console.log('Message:', e.data);

document.getElementById('messages').innerHTML += `<p>${e.data}</p>`;

};

eventSource.onerror = (error) => {

console.error('EventSource error:', error);

};

</script>

</body>

</html>

6. Important Settings Summary

Must-have in NPM Advanced Config:

proxy_buffering off – Critical for SSE
proxy_read_timeout 24h – Prevents timeout
add_header 'X-Accel-Buffering' 'no' – Disables NGINX buffering

In NPM Details Tab:

Enable “Websockets Support”
Use HTTP scheme (not HTTPS) if Mercure is on same network
Set correct port (3000 by default)

7. Troubleshooting Common Issues

SSE Connection Drops:

Ensure proxy_buffering off is set
Check proxy_read_timeout is set to a high value (24h)
Verify WebSockets support is enabled in NGINX Proxy Manager

CORS Errors:

Check origins match exactly (including protocol)
Verify credentials setting matches on both client and server
Check browser console for specific CORS error messages

Authentication Issues:

Verify JWT keys match between publisher and Mercure config
Check JWT token expiration
Ensure JWT has correct claims for publishing/subscribing

The key is that NPM’s GUI is limited, so it’s often better to let Mercure handle CORS entirely and just ensure NPM properly proxies the SSE connections without buffering.

FAQ SSE

What are Server-Sent Events (SSE)?

Server-Sent Events (SSE) is a web technology that enables a server to push data to a client over HTTP. It allows servers to maintain data transmission to clients after an initial connection has been established, providing real-time updates like stock prices, news feeds, or live notifications without requiring the client to poll the server.

How do SSE differ from WebSockets?

SSE provides unidirectional communication (server-to-client only), while WebSockets support full bidirectional communication. SSE uses standard HTTP/HTTPS protocols and is simpler to implement, whereas WebSockets use their own protocol (ws:// or wss://) and require more complex setup. SSE has automatic reconnection built-in, while WebSockets require manual reconnection handling.

What is the connection limit for SSE?

When using HTTP/1.1, browsers limit SSE connections to 6 concurrent connections per domain per browser. This limit applies across all tabs. However, with HTTP/2, the limit increases to around 100 simultaneous streams (negotiated between client and server), effectively solving the connection limitation problem.

How do I implement SSE on the client side?

Use the EventSource API in JavaScript:


const eventSource = new EventSource('/api/events');

eventSource.onmessage = function(event) {
    console.log('Received:', event.data);
};

eventSource.onerror = function(event) {
    console.error('SSE error:', event);
};

// Close connection
eventSource.close();

const eventSource = new EventSource('/api/events');

eventSource.onmessage = function(event) {

console.log('Received:', event.data);

};

eventSource.onerror = function(event) {

console.error('SSE error:', event);

};

// Close connection

eventSource.close();

How do I implement SSE on the server side?

Set the proper headers and send event-formatted data:


// Node.js/Express example
app.get('/api/events', (req, res) => {
    res.writeHead(200, {
        'Content-Type': 'text/event-stream',
        'Cache-Control': 'no-cache',
        'Connection': 'keep-alive',
        'Access-Control-Allow-Origin': '*'
    });

    // Send data
    res.write('data: Hello from server\n\n');
    
    // Send with event type
    res.write('event: update\n');
    res.write('data: {"message": "Update received"}\n\n');
});

// Node.js/Express example

app.get('/api/events', (req, res) => {

res.writeHead(200, {

'Content-Type': 'text/event-stream',

'Cache-Control': 'no-cache',

'Connection': 'keep-alive',

'Access-Control-Allow-Origin': '*'

});

// Send data

res.write('data: Hello from server\n\n');

// Send with event type

res.write('event: update\n');

res.write('data: {"message": "Update received"}\n\n');

});

Why do SSE connections keep disconnecting?

Common causes include: network timeouts, proxy/firewall interference, server-side timeouts, or antivirus software (like Sophos) blocking the connection. Solutions include implementing keep-alive messages (sending comments like “: keep-alive\n\n” every 15-30 seconds), configuring proxy settings, or adjusting server timeout settings.

What browsers support SSE?

SSE is supported by all modern browsers including Chrome, Firefox, Safari, Edge, and Opera. Internet Explorer does not support SSE natively, but polyfills are available. Browser support has been stable since around 2011 for most major browsers.

When should I use SSE instead of WebSockets?

Use SSE when you need:

One-way server-to-client communication only
Simple implementation with existing HTTP infrastructure
Automatic reconnection handling
Real-time updates like news feeds, stock prices, or notifications
Better compatibility with firewalls and proxies

Choose WebSockets for bidirectional communication, gaming, chat applications, or when you need to send data from client to server frequently.

Can SSE send binary data?

No, SSE can only transmit UTF-8 text data. Binary data must be encoded (e.g., using Base64) before transmission, which increases overhead. If you need to send binary data efficiently, WebSockets would be a better choice.

How do I handle SSE reconnection?

SSE automatically attempts to reconnect when the connection is lost. You can control this behavior:


// Server-side: Set retry delay (in milliseconds)
res.write('retry: 5000\n\n');

// Client-side: Handle reconnection
eventSource.addEventListener('open', function(event) {
    console.log('Connection opened');
});

eventSource.addEventListener('error', function(event) {
    if (event.target.readyState === EventSource.CLOSED) {
        console.log('Connection closed');
    } else if (event.target.readyState === EventSource.CONNECTING) {
        console.log('Reconnecting...');
    }
});

// Server-side: Set retry delay (in milliseconds)

res.write('retry: 5000\n\n');

// Client-side: Handle reconnection

eventSource.addEventListener('open', function(event) {

console.log('Connection opened');

});

eventSource.addEventListener('error', function(event) {

if (event.target.readyState === EventSource.CLOSED) {

console.log('Connection closed');

} else if (event.target.readyState === EventSource.CONNECTING) {

console.log('Reconnecting...');

}

});

What are common SSE use cases?

Popular SSE use cases include:

Real-time news feeds and social media updates
Stock price tickers and financial data
Live sports scores and updates
System monitoring dashboards
Chat applications (receive messages only)
Progress indicators for long-running tasks
Live notifications and alerts
IoT sensor data streaming

How do I send different event types with SSE?

Use the ‘event:’ field to specify event types:


// Server-side
res.write('event: notification\n');
res.write('data: {"type": "info", "message": "Hello"}\n\n');

res.write('event: update\n');
res.write('data: {"status": "completed"}\n\n');

// Client-side
eventSource.addEventListener('notification', function(event) {
    console.log('Notification:', event.data);
});

eventSource.addEventListener('update', function(event) {
    console.log('Update:', event.data);
});

// Server-side

res.write('event: notification\n');

res.write('data: {"type": "info", "message": "Hello"}\n\n');

res.write('event: update\n');

res.write('data: {"status": "completed"}\n\n');

// Client-side

eventSource.addEventListener('notification', function(event) {

console.log('Notification:', event.data);

});

eventSource.addEventListener('update', function(event) {

console.log('Update:', event.data);

});

What are the performance limitations of SSE?

SSE limitations include:

6 concurrent connections per domain on HTTP/1.1
Higher latency compared to WebSockets for frequent updates
Text-only data transmission (UTF-8)
One-way communication only
HTTP overhead for each message
Potential issues with corporate firewalls or proxies

Most limitations are resolved by using HTTP/2 or choosing WebSockets when appropriate.

How do I implement authentication with SSE?

Since SSE uses standard HTTP, you can use regular authentication methods:


// Using URL parameters
const eventSource = new EventSource('/api/events?token=YOUR_AUTH_TOKEN');

// Using cookies (automatically sent)
const eventSource = new EventSource('/api/events');

// Server-side validation
app.get('/api/events', (req, res) => {
    const token = req.query.token || req.headers.authorization;
    
    if (!isValidToken(token)) {
        return res.status(401).send('Unauthorized');
    }
    
    // Continue with SSE setup
});

// Using URL parameters

const eventSource = new EventSource('/api/events?token=YOUR_AUTH_TOKEN');

// Using cookies (automatically sent)

const eventSource = new EventSource('/api/events');

// Server-side validation

app.get('/api/events', (req, res) => {

const token = req.query.token || req.headers.authorization;

if (!isValidToken(token)) {

return res.status(401).send('Unauthorized');

}

// Continue with SSE setup

});

How do I debug SSE connections?

You can debug SSE using:

Browser Developer Tools (Network tab shows EventSource connections)
curl command: curl -N -H "Accept: text/event-stream" http://your-server/events
Console logging in JavaScript event handlers
Server-side logging of connection states
Monitoring connection counts and error rates

The text-based format makes SSE easy to troubleshoot compared to binary protocols.

Let’s Talk!

Looking for a reliable partner to bring your project to the next level? Whether it’s development, design, security, or ongoing support—I’d love to chat and see how I can help.

Get in touch,
and let’s create something amazing together!

Semantic Editors in JavaScript – Lets keep that Code Clean!

Development / Content Creation / Content Managment / HTML5 / Javascript

If you’ve ever tried to style text in a WYSIWYG editor and ended up with HTML that looked like a spaghetti disaster, you’ve already met the reason why semantic editors meaning, structure, and sanity. In other words: they keep your content clean, organized, and machine-friendly. This article walks you through the most important semantic and […]

Meet the Isolated Block Editor – Gutenberg, Untethered – Integrated into Elementor

Design / Content Creation / Content Managment / Development / WordPress

If you’ve ever worked with text editors on the web, you know the routine: dependencies everywhere, fragile integrations, and editors that only behave when the stars align. The Isolated Block Editor (IBE) solves this by taking the core of Gutenberg and making it work anywhere — no WordPress environment required. It gives you the power […]

Best WordPress Table Plugins: Global Plugins vs Elementor Tools

Design / Content Creation / CSS / Development / HTML5 / Plugins / SEO / WordPress

Let’s be real—WordPress’s default table block is kind of… meh. It gets the job done for super basic tables, but the moment you need sorting, filtering, or something that doesn’t look like it’s stuck in 2010, you’re out of luck. That’s where table plugins come in, and trust me, there’s a whole world of options […]

Alexander

I am a full-stack developer. My expertise include:

Server, Network and Hosting Environments
Data Modeling / Import / Export
Business Logic
API Layer / Action layer / MVC
User Interfaces
User Experience
Understand what the customer and the business needs

I have a deep passion for programming, design, and server architecture—each of these fuels my creativity, and I wouldn’t feel complete without them.

With a broad range of interests, I’m always exploring new technologies and expanding my knowledge wherever needed. The tech world evolves rapidly, and I love staying ahead by embracing the latest innovations.

Beyond technology, I value peace and surround myself with like-minded individuals.

I firmly believe in the principle: Help others, and help will find its way back to you when you need it.

Day 36: mercure – Open-Source protocol for pushing data updates via SSE – 7 Days of Docker

Table of Contents

Basic Docker Compose Setup

Development Configuration

Production Configuration with Health Checks

HTTP-Only Setup (Behind Reverse Proxy)

Environment Variables Reference

Core Configuration

Advanced Configuration

JWT Configuration Options

Complete Production Example

Environment File Setup

Mercure Directives Explained

Security Directives

Performance Directives

Feature Directives

Accessing Your Mercure Hub

Starting Your Setup

Generating JWT Tokens

PHP

JavaScript/Node.js

Python

Publishing Updates

Subscribing to Updates

Advanced Configuration Examples

Multiple Topics and Private Updates

High Availability Setup

Troubleshooting Common Issues

CORS Issues

JWT Token Issues

Connection Issues

Security Best Practices

Performance Optimization

Transport Configuration

Timeout Configuration

Important Links

EXTRA: Setting Up Mercure with Caddy and NGINX Proxy Manager

1. Mercure Configuration with Caddy

2. NGINX Proxy Manager Configuration

Details Tab:

SSL Tab:

Advanced Tab – Custom Nginx Configuration:

3. Working CORS Configuration for NGINX Proxy Manager

Option 1: Simple CORS Configuration (Recommended)

Option 2: Let Mercure Handle CORS (Cleaner Approach)

Option 3: Using Custom Location Block

4. Complete Docker Compose Setup

5. Testing Your Configuration

6. Important Settings Summary

7. Troubleshooting Common Issues

FAQ SSE

What are Server-Sent Events (SSE)?

How do SSE differ from WebSockets?

What is the connection limit for SSE?

How do I implement SSE on the client side?

How do I implement SSE on the server side?

Why do SSE connections keep disconnecting?

What browsers support SSE?

When should I use SSE instead of WebSockets?

Can SSE send binary data?

How do I handle SSE reconnection?

What are common SSE use cases?

How do I send different event types with SSE?

What are the performance limitations of SSE?

How do I implement authentication with SSE?

How do I debug SSE connections?

RELATED POSTS

Semantic Editors in JavaScript – Lets keep that Code Clean!

Meet the Isolated Block Editor – Gutenberg, Untethered – Integrated into Elementor

Best WordPress Table Plugins: Global Plugins vs Elementor Tools

Alexander

.highlights