DiscoverVulcain | Server Push Web APIs



The Hub is configurable using environment variables (recommended in production, twelve-factor app methodology), command line flags and configuration files (JSON, TOML, YAML, HCL, envfile and Java properties files are supported).

Environment variables must be the name of the configuration parameter in uppercase. Run ./mercure -h to see all available command line flags.

Configuration files must be named mercure.<format> (ex: mercure.yaml) and stored in one of the following directories:

  • the current directory ($PWD)
  • ~/.config/mercure/ (or any other XDG configuration directory set with the XDG_CONFIG_HOME environment variable)
  • /etc/mercure

Most configuration parameters are hot reloaded: changes made to environment variables or configuration files are immediately taken into account, without having to restart the hub.

When using environment variables, list must be space separated. As flags parameters, they must be comma separated.

acme_cert_dirthe directory where to store Let's Encrypt certificates
acme_hostsa list of hosts for which Let's Encrypt certificates must be issued
acme_http01_addrthe address used by the acme server to listen on (example:
addrthe address to listen on (example: Note that Let's Encrypt only supports the default port: to use Let's Encrypt, do not set this parameter.:http or :https depending if HTTPS is enabled or not
allow_anonymousallow subscribers with no valid JWT to connectfalse
cert_filea cert file (to use a custom certificate)
key_filea key file (to use a custom certificate)
compressUse HTTP compressionfalse
cors_allowed_originsa list of allowed CORS origins, can be * for all
debugdebug mode, dangerous, don't enable in production (logs updates' content, why an update is not send to a specific subscriber and recovery stack traces)false
demodemo mode (automatically enabled when debug is true)false
dispatch_timeoutmaximum duration of the dispatch of a single update, set to 0s to disable5s
subscriptionsexpose the subscription web API and dispatch private updates when a subscription between the Hub and a subscriber is established or closed. The topic follows the template /.well-known/mercure/subscriptions/{topicSelector}/{subscriberID}false
heartbeat_intervalinterval between heartbeats (useful with some proxies, and old browsers), set to 0s to disable5s
jwt_keythe JWT key to use for both publishers and subscribers
jwt_algorithmthe JWT verification algorithm to use for both publishers and subscribers, e.g. HS256 or RS512HS256
log_formatthe log format, can be JSON, FLUENTD or TEXTTEXT
metrics_enabledEnable the /metrics HTTP endpoint. Provide metrics for Hub monitoring in the OpenMetrics (Prometheus) formatfalse
metrics_addrthe address to listen on127.0.0.1:3002
publish_allowed_originsa list of origins allowed to publish (only applicable when using cookie-based auth)
publisher_jwt_keymust contain the secret key to valid publishers' JWT, can be omitted if jwt_key is set
publisher_jwt_algorithmthe JWT verification algorithm to use for publishers, e.g. HS256 or RS512HS256
read_timeoutmaximum duration for reading the entire request, including the body, set to 0s to disable5s
subscriber_jwt_keymust contain the secret key to valid subscribers' JWT, can be omitted if jwt_key is set
subscriber_jwt_algorithmthe JWT verification algorithm to use for subscribers, e.g. HS256 or RS512HS256
transport_urlURL representation of the history database. Provided database are null to disabled history, bolt to use bbolt (example bolt:///var/run/mercure.db?size=100&cleanup_frequency=0.4)bolt://updates.db
use_forwarded_headersuse the X-Forwarded-For, and X-Real-IP for the remote (client) IP address, X-Forwarded-Proto or X-Forwarded-Scheme for the scheme (http or https), X-Forwarded-Host for the host and the RFC 7239 Forwarded header, which may include both client IPs and schemes. If this option is enabled, the reverse proxy must override or remove these headers or you will be at riskfalse
write_timeoutmaximum duration before timing out writes of the response, set to 0s to disable60s

If acme_hosts or both cert_file and key_file are provided, an HTTPS server supporting HTTP/2 connection will be started. If not, an HTTP server will be started (not secure).

When using RSA public keys for verification make sure the key is properly formatted.

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


JWT_KEY=`cat` ./mercure


$env:JWT_KEY = [IO.File]::ReadAllText(".\")

Bolt Adapter

The Data Source Name (DSN) specifies the path to the bolt database as well as options

bucket_namename of the bolt bucket to store events. default to updates
cleanup_frequencychances to trigger history cleanup when an update occurs, must be a number between 0 (never cleanup) and 1 (cleanup after every publication), default to 0.3.
sizesize of the history (to retrieve lost messages using the Last-Event-ID header), set to 0 to never remove old events (default)

Below are common examples of valid DSNs showing a combination of available values:

# absolute path to `updates.db`

# path to `updates.db` in the current directory

# custom options