Contribute!

Configuration

The Mercure 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.

ParameterDescription
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: 0.0.0.0:8080), default to :http.
addrthe address to listen on (example: 127.0.0.1:3000, default to :http or :https depending if HTTPS is enabled or not). Note that Let's Encrypt only supports the default port: to use Let's Encrypt, do not set this parameter.
allow_anonymousset to 1 to allow subscribers with no valid JWT to connect
cert_filea cert file (to use a custom certificate)
key_filea key file (to use a custom certificate)
compressset to 0 to disable HTTP compression support (default to enabled)
cors_allowed_originsa list of allowed CORS origins, can be * for all
debugset to 1 to enable the debug mode, dangerous, don't enable in production (logs updates' content, why an update is not send to a specific subscriber and recovery stack traces)
demoset to 1 to enable the demo mode (automatically enabled when debug=1)
heartbeat_intervalinterval between heartbeats (useful with some proxies, and old browsers, default to 15s, set to 0s to disable)
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=10). (default to bolt://updates.db)
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 RS512. Defaults to HS256.
log_formatthe log format, can be JSON, FLUENTD or TEXT (default)
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 RS512. Defaults to HS256.
read_timeoutmaximum duration for reading the entire request, including the body, set to 0s to disable (default), example: 2m
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 RS512. Defaults to HS256.
write_timeoutmaximum duration before timing out writes of the response, set to 0s to disable (default), example: 2m
use_forwarded_headersset to 1 to use 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 risk.

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.

-----BEGIN PUBLIC KEY-----
MIGeMA0GCSqGSIb3DQEBAQUAA4GMADCBiAKBgHVwuJsFmzsFnOkGj+OgAp4lTNqR
CF0RZSmjY+ECWOJ3sSEzQ8qtkJe61uSjr/PKmqvBxxex0YtUL7waSS4jvq3ws8Bm
WIxK2GqoAVjLjK8HzThSPQpgv2AjiEXD6iAERHeySLGjYAUgfMrVJ01J5fNSL+O+
bCd7nPuNAyYHCOOHAgMBAAE=
-----END PUBLIC KEY-----

Unix

JWT_KEY=`cat jwt_key.pub` ./mercure

PowerShell

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

Bolt Adapter

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

ParameterDescription
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`
transport_url="bolt:///var/run/database.db"

# path to `updates.db` in the current directory
transport_url="bolt://database.db"

# custom options
transport_url="bolt://database.db?bucket_name=demo&size=1000&cleanup_frequency=0.5"