config.md

Configuration

The Mercure.rocks hub is a custom build of the Caddy web server including the Mercure.rocks module.

Read Caddy web server's getting started guide to learn the basics.

While all supported way to configure Caddy are also supported by the Mercure.rocks Hub, the easiest one is to use a Caddyfile. A default Caddyfile is provided in the archive containing the Mercure.rocks Hub.

A minimal Caddyfile for the Mercure hub looks like this:

# The address of your server
localhost

route {
    mercure {
        # Publisher JWT key
        publisher_jwt !ChangeMe!
        # Subscriber JWT key
        subscriber_jwt !ChangeMe!
    }

    respond "Not Found" 404
}

Caddy will automatically generate a Let's Encrypt TLS certificate automatically for you! So you can use HTTPS.

Directives

The following Mercure-specific directives are available:

Directive	Description	Default
publisher_jwt <key> [<algorithm>]	the JWT key and algorithm to use for publishers, can contain placeholders
subscriber_jwt <key> [<algorithm>]	the JWT key and algorithm to use for subscribers, can contain placeholders
anonymous	allow subscribers with no valid JWT to connect	false
publish_origins <origins...>	a list of origins allowed publishing, can be * for all (only applicable when using cookie-based auth)
cors_origins <origin...>	a list of allowed CORS origins, can be * for all
subscriptions	expose 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}
heartbeat	interval between heartbeats (useful with some proxies, and old browsers), set to 0s disable	40s
transport_url <url>	URL representation of the transport to use. Use local://local to disabled history, (example bolt:///var/run/mercure.db?size=100&cleanup_frequency=0.4), see also the cluster mode	bolt://mercure.db
dispatch_timeout <duration>	maximum duration of the dispatch of a single update, set to 0s disable	5s
write_timeout <duration>	maximum duration before closing the connection, set to 0s disable	600s
demo [<assets-path>]	enable the demo mode and the UI
cache <num-counters> <max-cost>	cache configuration (see Ristretto's docs), set to -1 to disable the cache	6e7 1e8 (100MB)

See also the list of built-in Caddyfile directives.

Environment Variables

The provided Caddyfile and the Docker image provide convenient environment variables:

Environment variable	Description	Default value
DEBUG=debug	enable the debug mode
SERVER_NAME	the server name or address	localhost
MERCURE_TRANSPORT_URL	the value passed to the transport_url directive	bolt://mercure.db
MERCURE_PUBLISHER_JWT_KEY	the JWT key to use for publishers	!ChangeMe!
MERCURE_PUBLISHER_JWT_ALG	the JWT algorithm to use for publishers	HS256
MERCURE_SUBSCRIBER_JWT_KEY	the JWT key to use for subscribers	!ChangeMe!
MERCURE_SUBSCRIBER_JWT_ALG	the JWT algorithm to use for subscribers	HS256
MERCURE_EXTRA_DIRECTIVES	a list of extra Mercure directives to pass, one per line
MERCURE_LICENSE	the license to use (only applicable for the HA version

JWT Verification

When using RSA public keys for verification make sure the key is properly formatted and make sure to set the correct algorithm as second parameter of the publisher_jwt or subscriber_jwt directives (for example RS256).

Here is an example of how to use environments variables with a RSA public key.

Generate keys (if you don't already have them):

ssh-keygen -t rsa -b 4096 -m PEM -f publisher.key
openssl rsa -in publisher.key -pubout -outform PEM -out publisher.key.pub

ssh-keygen -t rsa -b 4096 -m PEM -f subscriber.key
openssl rsa -in subscriber.key -pubout -outform PEM -out subscriber.key.pub

Start the hub:

MERCURE_PUBLISHER_JWT_KEY=$(cat publisher.key.pub) \
MERCURE_PUBLISHER_JWT_ALG=RS256 \
MERCURE_SUBSCRIBER_JWT_KEY=$(cat subscriber.key.pub) \
MERCURE_SUBSCRIBER_JWT_ALG=RS256 \
./mercure run

Bolt Adapter

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

Parameter	Description
bucket_name	name of the bolt bucket to store events. default to updates
cleanup_frequency	chances 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.
size	size 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

You can visualize and edit the content of the database using boltdbweb.

Legacy Server

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

Parameter	Description	Default
acme_cert_dir	the directory where to store Let's Encrypt certificates
acme_hosts	a list of hosts for which Let's Encrypt certificates must be issued
acme_http01_addr	the address used by the acme server to listen on (example: 0.0.0.0:8080)	:http
addr	the address to listen on (example: 127.0.0.1:3000. 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_anonymous	allow subscribers with no valid JWT to connect	false
cert_file	a cert file (to use a custom certificate)
key_file	a key file (to use a custom certificate)
compress	Use HTTP compression	false
cors_allowed_origins	a space-separated list of allowed CORS origins, can be * for all
debug	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)	false
demo	demo mode (automatically enabled when debug is true)	false
dispatch_timeout	maximum duration of the dispatch of a single update, set to 0s to disable	5s
subscriptions	expose 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_interval	interval between heartbeats (useful with some proxies, and old browsers), set to 0s to disable	40s
jwt_key	the JWT key to use for both publishers and subscribers
jwt_algorithm	the JWT verification algorithm to use for both publishers and subscribers, e.g. HS256 or RS512	HS256
metrics_enabled	Enable the /metrics HTTP endpoint. Provide metrics for Hub monitoring in the OpenMetrics (Prometheus) format	false
metrics_addr	the address to listen on	127.0.0.1:9764
publish_allowed_origins	a list of origins allowed to publish (only applicable when using cookie-based auth)
publisher_jwt_key	must contain the secret key to valid publishers' JWT, can be omitted if jwt_key is set
publisher_jwt_algorithm	the JWT verification algorithm to use for publishers, e.g. HS256 or RS512	HS256
read_timeout	maximum duration for reading the entire request, including the body, set to 0s to disable	5s
subscriber_jwt_key	must contain the secret key to valid subscribers' JWT, can be omitted if jwt_key is set
subscriber_jwt_algorithm	the JWT verification algorithm to use for subscribers, e.g. HS256 or RS512	HS256
transport_url	URL 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_headers	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	false
write_timeout	maximum duration before closing the connection, set to 0s to disable	600s

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).