Using Multiple Nodes
The community version of Mercure.rocks is shipped with transports (BoltDB and local) that can only run on a single node.
On the other hand, the Cloud and the Enterprise versions of Mercure.rocks Hub have been designed from the ground up to support clusters. These natively run on multiple nodes, are designed for fault tolerance and can support very high loads.
Both versions work by providing extra transports supporting synchronization of several nodes. They support all features of the community Hub.
If you don't want to purchase a Cloud or an Enterprise version of the Mercure.rocks Hub, you can also create your custom build of Mercure.rocks using a custom transport.
Cloud
The Cloud version is hosted on our own High Availability infrastructure (built on top of Kubernetes). This service is 100% hosted and managed: you have nothing to do!
The Cloud version of the Mercure.rocks Hub can be purchased directly online. After the purchase, a production-ready Hub is instantly deployed.
To use it, just configure your custom domain name (if any) and your secret JWT key from the administration panel; that's all!
Self-Hosted Enterprise
Mercure.rocks Enterprise provides a drop-in replacement for the community Hub, allowing you to spread the load across as many servers as you want. It is designed to run on your own servers and is fault-tolerant by default.
The Enterprise version is shipped with transports having node synchronization capabilities. These transports can rely on:
Redis or Valkey
Postgres
LISTEN/NOTIFYApache Kafka
Apache Pulsar
Mercure.rocks Enterprise also provides:
advanced rate limiting
drop-in replacements builds for FrankenPHP including High Availability transports
We can help you decide which synchronization mechanism is best suited for your needs, and assist you in installing and configuring it on your infrastructure.
The Mercure.rocks Enterprise Hub is provided as binaries and as a Docker image. We also maintain a Helm chart that allows for installation on any Kubernetes cluster.
For more details (and a benchmark), read the case studies section.
Purchasing
To purchase Mercure.rocks Enterprise, send us an email: contact@mercure.rocks
Setting the License
A license key is provided when you purchase Mercure.rocks Enterprise.
This key must be set in an environment variable named MERCURE_LICENSE.
Ex:
MERCURE_LICENSE=snip \ MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \ MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \ ./mercure run
If you use the Helm chart, set the license value and change the Docker image to use the one provided.
Transports
The clustered mode of the Mercure.rocks Hub requires transport to work. Supported transports are Apache Pulsar, Apache Kafka, and PostgreSQL.
Redis/Valkey Transport
This is the recommended transport when the Hub isn't the main storage system and low latency is needed. The Redis transport should fit most use cases.
To install Redis, read the documentation. Valkey is also supported. Most Cloud Computing platforms also provide managed versions of Redis or Valkey.
| Feature | Supported |
|---|---|
| History | ✅ |
| Presence API | ✅ |
| Custom event ID | ✅ |
Here is a basic example of a Redis transport configuration using environment variables:
MERCURE_EXTRA_DIRECTIVES="transport redis { url rediss://default:p@ssw0rd123@redis.example.com:6379 stream mercure }"
Redis Configuration
The following options can be passed to the transport directive:
| Option | Description |
|---|---|
url | The Redis URI to use to connect to Redis. If set, address, addresses, username, password, and tls options are ignored. |
stream | the name of the Redis stream to use (default to mercure) |
max_length | the approximate maximum number of messages to store in the history, set to 0 to store all messages |
gob | use the Go gob encoding instead of JSON (faster but not compatible with third-party systems querying the Redis instance directly) |
address or addresses | the address(es) of the Redis server(s), you can pass several addresses to use several Redis servers (e.g., addresses host1:6379 host2:6379). Prefer using url except if you use Redis Cluster. |
username | the Redis username |
password | the Redis password |
tls | enable TLS support |
All the configuration parameters and formats supported by Mercure.rocks Community are also available.
Reusing an Existing Caddy Storage Redis Instance
The Redis storage module for Caddy is shipped with the Enterprise build of Mercure.rocks.
If you use it (for instance, as the storage for the Caddy ratelimit module that is also included),
you can reuse the same Redis instance for Mercure.rocks by using the special caddy-storage-redis.alt value as address in your Caddyfile:
Here is an example using the built-in environment variables:
MERCURE_EXTRA_DIRECTIVES="transport redis { address caddy-storage-redis.alt stream mercure # ... }" GLOBAL_OPTIONS="storage redis"
Legacy Redis URL
This feature is deprecated: use the new transport directive instead.
The following options can be passed as query parameters of the URL set in transport_url:
| Parameter | Description | Default |
|---|---|---|
tls | set to 1 to enable TLS support | 0 |
max_len_approx | the approximate maximum number of messages to store in the history, set to 0 to store all messages | 0 |
PostgreSQL Transport
The PostgreSQL Transport allows to store permanently the event and to query them using the full power of SQL. It is mostly useful when using the Mercure.rocks Hub as an event store, or as a primary data store.
This feature uses PostgreSQL LISTEN/NOTIFY.
To install PostgreSQL, read the documentation. Most Cloud Computing platforms also provide managed versions of PostgreSQL.
| Feature | Supported |
|---|---|
| History | ✅ |
| Presence API | ❌ (planned) |
| Custom event ID | ✅ |
PostgreSQL Configuration
The following options can be passed to the transport directive:
| Option | Description |
|---|---|
url | The URL (DSN) to use to connect to Postgres (e.g., postgres://user:password@127.0.0.1/mercure-ha, required) |
Options supported by libpq can be passed as query parameters of the URL set in _url.
All the configuration parameters and formats supported by Mercure.rocks Community are also available.
Legacy PostgreSQL URL
This feature is deprecated: use the new transport directive instead.
Options supported by libpq can be passed as query parameters of the URL set in transport_url.
Kafka Transport
The Kafka transport should only be used when Kafka is already part of your stack.
To install Apache Kafka, read the quickstart guide.
Most Cloud Computing platforms also provide managed versions of Kafka. The Mercure.rocks hub has been tested with:
Bitnami's Kafka Docker images (Kubernetes and the like)
Amazon Managed Streaming for Apache Kafka (Amazon MSK)
IBM Event Streams for IBM Cloud
Heroku Kafka
| Feature | Supported |
|---|---|
| History | ✅ |
| Presence API | ❌ |
| Custom event ID | ✅ |
Kafka Configuration
The following options can be passed to the transport directive:
| Option | Description |
|---|---|
address or addresses | the address(es) of the Kafka server(s), you can pass several addresses to use several Kafka servers (e.g., addresses host1:9092 host2:9092, required) |
topic | the name of the Kafka topic to use, all Mercure.rocks hub instances must use the same topic (required) |
consumer_group | the consumer group of this node, must be different for every instance of the Mercure.rocks hub |
user | the Kafka SASL user (optional) |
password | the Kafka SASL password (optional) |
tls | enable TLS support |
All the configuration parameters and formats supported by Mercure.rocks Community are also available.
Legacy Kafka URL
This feature is deprecated: use the new transport directive instead.
The following options can be passed as query parameters of the URL set in transport_url:
| Parameter | Description |
|---|---|
addr | addresses of the Kafka servers, you can pass several addr parameters to use several Kafka servers (e.g., addr=host1:9092&addr=host2:9092) |
topic | the name of the Kafka topic to use (e.g., topic=mercure-ha), all Mercure.rocks hub instances must use the same topic |
consumer_group | the consumer group of this node, must be different for every instance of the Mercure.rocks hub (e.g., consumer_group=<random-string>) |
user | Kafka SASL user (optional, e.g., user=kevin) |
password | Kafka SASL password (optional, e.g., password=maman) |
tls | Set to 1 to enable TLS (e.g., tls=1) |
Pulsar Transport
The Pulsar transport should only be used when Pulsar is already part of your stack.
To install Apache Pulsar, read the documentation.
| Feature | Supported |
|---|---|
| History | ✅ |
| Presence API | ❌ |
| Custom event ID | ❌ (planned) |
Pulsar Configuration
The following options can be passed to the transport directive:
| Option | Description |
|---|---|
url | the address of the Pulsar server (required) |
topic | the name of the Pulsar topic to use, all Mercure.rocks hub instances must use the same topic (required) |
subscription_name | the subscription name for this node, must be different for every instance of the Mercure.rocks hub |
All the configuration parameters and formats supported by Mercure.rocks Community are also available.
Legacy Pulsar URL
This feature is deprecated: use the new transport directive instead.
The following options can be passed as query parameters of the URL set in transport_url:
| Parameters | Description | |
|---|---|---|
topic | the name of the Pulsar topic to use (e.g., topic=mercure), all Mercure.rocks hub instances must use the same topic | |
subscription_name | the subscription name for this node, must be different for every instance of the Mercure.rocks hub (e.g., subscription_name=<random-string>) |
Docker Images and Kubernetes Chart
An official Docker image and a Kubernetes Chart are available. Contact us if you need help using them.
Updates
New releases of Mercure.rocks Enterprise are automatically available in the Amazon S3 bucket containing the binary and on the Docker registry.
Support
For support requests related to the Mercure.rocks Cloud and Enterprise, send a mail to contact@mercure.rocks.
For Mercure.rocks Community support, please use GitHub discussions.