Skip to content

Commit 6c2d07d

Browse files
dunglasdunglas
authored
docs: updated docs for Mercure On Premise (#1002)
* docs: updated docs for Mercure On Premise * linter
1 parent 1b58398 commit 6c2d07d

File tree

2 files changed

+57
-32
lines changed

2 files changed

+57
-32
lines changed

‎docs/hub/cluster.md‎

Lines changed: 51 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -70,23 +70,31 @@ The Redis transport should fit most use cases.
7070
To install Redis, [read the documentation](https://redis.io/topics/quickstart).
7171
Most Cloud Computing platforms also provide managed versions of Redis.
7272

73+
<!-- markdownlint-disable MD009 -->
74+
7375
| Feature | Supported |
7476
|-----------------|-----------|
7577
| History | ✅ |
7678
| Presence API | ✅ |
7779
| Custom event ID | ✅ |
7880

79-
##### Configuration
81+
##### Redis Configuration
82+
83+
The following options can be passed to the `transport` directive:
84+
85+
| Option | Description |
86+
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
87+
| `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) |
88+
| `stream` | the name of the Redis stream to use (required) |
89+
| `password` | the Redis password |
90+
| `tls` | enable TLS support |
91+
| `max_length` | the approximate maximum number of messages to store in the history, set to `0` to store all messages |
8092

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

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

85-
MERCURE_TRANSPORT_URL=redis://127.0.0.1:6379/mercure-ha \
86-
MERCURE_LICENSE=snip \
87-
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
88-
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
89-
./mercure run
97+
**This feature is deprecated: use the new `transport` directive instead**.
9098

9199
The following options can be passed as query parameters of the URL set in `transport_url`:
92100

@@ -100,6 +108,8 @@ The following options can be passed as query parameters of the URL set in `trans
100108
The PostgreSQL Transport allows to store permanently the event and to query them using the full power of SQL.
101109
It is mostly useful when using the Mercure.rocks Hub as an event store, or as a primary data store.
102110

111+
This feature uses PostgreSQL `LISTEN`/`NOTIFY`.
112+
103113
To install PostgreSQL, [read the documentation](https://www.postgresql.org/docs/12/tutorial-install.html).
104114
Most Cloud Computing platforms also provide managed versions of PostgreSQL.
105115

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

112122
##### PostgreSQL Configuration
113123

124+
The following options can be passed to the `transport` directive:
125+
126+
| Option | Description |
127+
|--------|-------------------------------------------------------------------------------------------------------------|
128+
| `url` | The URL (DSN) to use to connect to Postgres (ex: `postgres://user:password@127.0.0.1/mercure-ha`, required) |
129+
130+
[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`.
131+
114132
All [the configuration parameters and formats](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.
115133

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

118-
MERCURE_TRANSPORT_URL=postgres://user:password@127.0.0.1/mercure-ha \
119-
MERCURE_LICENSE=snip \
120-
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
121-
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
122-
./mercure run
136+
**This feature is deprecated: use the new `transport` directive instead**.
123137

124138
[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`.
125139

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

146160
##### Kafka Configuration
147161

162+
The following options can be passed to the `transport` directive:
163+
164+
| Option | Description |
165+
|--------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------|
166+
| `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) |
167+
| `topic` | the name of the Kafka topic to use, **all Mercure.rocks hub instances must use the same topic** (required) |
168+
| `consumer_group` | the consumer group of this node, **must be different for every instance of the Mercure.rocks hub** |
169+
| `user` | the Kafka SASL user (optional) |
170+
| `password` | the Kafka SASL password (optional) |
171+
| `tls` | enable TLS support |
172+
148173
All [the configuration parameters and formats](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.
149174

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

152-
MERCURE_TRANSPORT_URL=kafka://kafka/?addr=localhost:9092&topic=mercure-ha \
153-
MERCURE_LICENSE=snip \
154-
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
155-
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
156-
./mercure run
177+
**This feature is deprecated: use the new `transport` directive instead**.
157178

158179
The following options can be passed as query parameters of the URL set in `transport_url`:
159180

160181
| Parameter | Description |
161182
|------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
162183
| `addr` | addresses of the Kafka servers, you can pass several `addr` parameters to use several Kafka servers (ex: `addr=host1:9092&addr=host2:9092`) |
163184
| `topic` | the name of the Kafka topic to use (ex: `topic=mercure-ha`), **all Mercure.rocks hub instances must use the same topic** |
164-
| `consumer_group` | consumer group, **must be different for every instance of the Mercure.rocks hub** (ex: `consumer_group=<random-string>`) |
185+
| `consumer_group` | the consumer group of this node, **must be different for every instance of the Mercure.rocks hub** (ex: `consumer_group=<random-string>`) |
165186
| `user` | Kafka SASL user (optional, ex: `user=kevin`) |
166187
| `password` | Kafka SASL password (optional, ex: `password=maman`) |
167188
| `tls` | Set to `1` to enable TLS (ex: `tls=1`) |
@@ -180,15 +201,19 @@ To install Apache Pulsar, [read the documentation](https://pulsar.apache.org/doc
180201

181202
##### Pulsar Configuration
182203

204+
The following options can be passed to the `transport` directive:
205+
206+
| Option | Description |
207+
|---------------------|-------------------------------------------------------------------------------------------------------------|
208+
| `url` | the address of the Pulsar server (required) |
209+
| `topic` | the name of the Pulsar topic to use, **all Mercure.rocks hub instances must use the same topic** (required) |
210+
| `subscription_name` | the subscription name for this node, **must be different for every instance of the Mercure.rocks hub** |
211+
183212
All [the configuration parameters and formats](https://mercure.rocks/docs/hub/config) supported by the free Mercure.rocks Hub are also available.
184213

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

187-
MERCURE_TRANSPORT_URL=pulsar://localhost:6650?topic=mercure-ha&subscription_name=the-node-id \
188-
MERCURE_LICENSE=snip \
189-
MERCURE_PUBLISHER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
190-
MERCURE_SUBSCRIBER_JWT_KEY='!ChangeThisMercureHubJWTSecretKey!' \
191-
./mercure run
216+
**This feature is deprecated: use the new `transport` directive instead**.
192217

193218
The following options can be passed as query parameters of the URL set in `transport_url`:
194219

‎docs/hub/config.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -127,12 +127,12 @@ MERCURE_SUBSCRIBER_JWT_ALG=RS256 \
127127

128128
## Bolt Adapter
129129

130-
| Option | Description |
131-
|---------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
132-
| `path` | path of the database file (default: `mercure.db`) |
133-
| `bucket_name` | name of the bolt bucket to store events. default to `updates` |
134-
| `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`. |
135-
| `size` | size of the history (to retrieve lost messages using the `Last-Event-ID` header), set to `0` to never remove old events (default) |
130+
| Option | Description |
131+
|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
132+
| `path` | path of the database file (default: `mercure.db`) |
133+
| `bucket_name` | name of the bolt bucket to store events (default: `updates`) |
134+
| `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`) |
135+
| `size` | size of the history (to retrieve lost messages using the `Last-Event-ID` header), set to `0` to never remove old events (default) |
136136

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

0 commit comments

Comments
 (0)