Skip to content

Commit

Permalink
docs: updated docs for Mercure On Premise (#1002)
Browse files Browse the repository at this point in the history 
* docs: updated docs for Mercure On Premise

* linter
  • Loading branch information
@dunglas
dunglas authored Jan 30, 2025
1 parent 1b58398 commit 6c2d07d
Show file tree
Hide file tree
Showing 2 changed files with 57 additions and 32 deletions.
77 changes: 51 additions & 26 deletions docs/hub/cluster.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -70,23 +70,31 @@ The Redis transport should fit most use cases.
To install Redis, [read the documentation](https://redis.io/topics/quickstart).
Most Cloud Computing platforms also provide managed versions of Redis.

<!-- markdownlint-disable MD009 -->

| Feature | Supported |
|-----------------|-----------|
| History | ✅ |
| Presence API | ✅ |
| Custom event ID | ✅ |

##### Configuration
##### Redis Configuration

The following options can be passed to the `transport` directive:

| Option | Description |
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
| `address` or `addresses` | the address(es) of the Redis server(s), you can pass several addresses to use several Redis servers (ex: `addresses host1:6379 host2:6379`, required) |
| `stream` | the name of the Redis stream to use (required) |
| `password` | the Redis password |
| `tls` | enable TLS support |
| `max_length` | the approximate maximum number of messages to store in the history, set to `0` to store all messages |

All [the configuration parameters and formats](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.

To use Redis, the `MERCURE_TRANSPORT_URL` environment variable must be set like in this example:
###### Legacy Redis URL

MERCURE_TRANSPORT_URL=redis://127.0.0.1:6379/mercure-ha \
MERCURE_LICENSE=snip \
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
./mercure run
**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`:

Expand All @@ -100,6 +108,8 @@ The following options can be passed as query parameters of the URL set in `trans
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](https://www.postgresql.org/docs/12/tutorial-install.html).
Most Cloud Computing platforms also provide managed versions of PostgreSQL.

Expand All @@ -111,15 +121,19 @@ Most Cloud Computing platforms also provide managed versions of PostgreSQL.

##### PostgreSQL Configuration

The following options can be passed to the `transport` directive:

| Option | Description |
|--------|-------------------------------------------------------------------------------------------------------------|
| `url` | The URL (DSN) to use to connect to Postgres (ex: `postgres://user:[email protected]/mercure-ha`, required) |

[Options supported by `libpq`](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) can be passed as query parameters of the URL set in `_url`.

All [the configuration parameters and formats](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.

To use PostgreSQL `LISTEN`/`NOTIFY`, the `MERCURE_TRANSPORT_URL` environment variable must be set like in this example:
###### Legacy PostgreSQL URL

MERCURE_TRANSPORT_URL=postgres://user:[email protected]/mercure-ha \
MERCURE_LICENSE=snip \
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
./mercure run
**This feature is deprecated: use the new `transport` directive instead**.

[Options supported by `libpq`](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) can be passed as query parameters of the URL set in `transport_url`.

Expand All @@ -145,23 +159,30 @@ The Mercure.rocks hub has been tested with:

##### 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 (ex: `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](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.

To use Kafka, the `MERCURE_TRANSPORT_URL` environment variable must be set like in this example:
###### Legacy Kafka URL

MERCURE_TRANSPORT_URL=kafka://kafka/?addr=localhost:9092&topic=mercure-ha \
MERCURE_LICENSE=snip \
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
./mercure run
**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 (ex: `addr=host1:9092&addr=host2:9092`) |
| `topic` | the name of the Kafka topic to use (ex: `topic=mercure-ha`), **all Mercure.rocks hub instances must use the same topic** |
| `consumer_group` | consumer group, **must be different for every instance of the Mercure.rocks hub** (ex: `consumer_group=<random-string>`) |
| `consumer_group` | the consumer group of this node, **must be different for every instance of the Mercure.rocks hub** (ex: `consumer_group=<random-string>`) |
| `user` | Kafka SASL user (optional, ex: `user=kevin`) |
| `password` | Kafka SASL password (optional, ex: `password=maman`) |
| `tls` | Set to `1` to enable TLS (ex: `tls=1`) |
Expand All @@ -180,15 +201,19 @@ To install Apache Pulsar, [read the documentation](https://pulsar.apache.org/doc

##### 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](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.

To use Pulsar, the `MERCURE_TRANSPORT_URL` environment variable must be set like in this example:
###### Legacy Pulsar URL

MERCURE_TRANSPORT_URL=pulsar://localhost:6650?topic=mercure-ha&subscription_name=the-node-id \
MERCURE_LICENSE=snip \
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
./mercure run
**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`:

Expand Down
12 changes: 6 additions & 6 deletions docs/hub/config.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,12 +127,12 @@ MERCURE_SUBSCRIBER_JWT_ALG=RS256 \

## Bolt Adapter

| Option | Description |
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `path` | path of the database file (default: `mercure.db`) |
| `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) |
| Option | Description |
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `path` | path of the database file (default: `mercure.db`) |
| `bucket_name` | name of the bolt bucket to store events (default: `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) |

You can visualize and edit the content of the database using [boltdbweb](https://github.com/evnix/boltdbweb).

Expand Down

0 comments on commit 6c2d07d

Please sign in to comment.