From b47d8233ede207f521401fc8c9fd20b0515557d2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C3=ABl=20Demeyer?= Date: Thu, 5 Oct 2023 16:02:55 +0200 Subject: [PATCH] docs: fix ui and demo directive descriptions (#816) * docs: fix ui and demo directive descriptions * docs: Allow longer line in markdown files for table --- .github/linters/.markdown-lint.yml | 36 +++++++++ docs/hub/config.md | 114 +++++++++++++++-------------- 2 files changed, 96 insertions(+), 54 deletions(-) create mode 100644 .github/linters/.markdown-lint.yml diff --git a/.github/linters/.markdown-lint.yml b/.github/linters/.markdown-lint.yml new file mode 100644 index 00000000..ab381c0c --- /dev/null +++ b/.github/linters/.markdown-lint.yml @@ -0,0 +1,36 @@ +--- +########################### +########################### +## Markdown Linter rules ## +########################### +########################### + +# Linter rules doc: +# - https://github.com/DavidAnson/markdownlint +# +# Note: +# To comment out a single error: +# +# any violations you want +# +# + +############### +# Rules by id # +############### +MD004: false # Unordered list style +MD007: + indent: 2 # Unordered list indentation +MD013: + line_length: 400 # Line length 80 is far too short + tables: false +MD026: + punctuation: ".,;:!。，；:" # List of not allowed +MD029: false # Ordered list item prefix +MD033: false # Allow inline HTML +MD036: false # Emphasis used instead of a heading + +################# +# Rules by tags # +################# +blank_lines: false # Error on blank lines diff --git a/docs/hub/config.md b/docs/hub/config.md index a934f563..3da36127 100644 --- a/docs/hub/config.md +++ b/docs/hub/config.md @@ -60,8 +60,8 @@ The following Mercure-specific directives are available: | `dispatch_timeout ` | maximum duration of the dispatch of a single update, set to `0s` disable | `5s` | | `write_timeout ` | maximum duration before closing the connection, set to `0s` disable | `600s` | | `protocol_version_compatibility` | version of the protocol to be backward compatible with (only version 7 is supported) | disabled | -| `ui` | enable the UI and expose demo endpoints | | -| `demo` | enable the UI but do not expose demo endpoints | | +| `demo` | enable the UI and expose demo endpoints | | +| `ui` | enable the UI but do not expose demo endpoints | | | `cache ` | cache configuration (see [Ristretto's docs](https://github.com/dgraph-io/ristretto)), set to -1 to disable the cache | `6e7` `1e8` (100MB) | See also [the list of built-in Caddyfile directives](https://caddyserver.com/docs/caddyfile/directives). @@ -91,40 +91,46 @@ 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 +```console +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 +```console +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)](https://en.wikipedia.org/wiki/Data_source_name) specifies the path to the [bolt](https://github.com/etcd-io/bbolt) database as well as options -| Parameter | Description -|---------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `bucket_name` | name of the bolt bucket to store events. default to `updates` | +| 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) | +| `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 +```Caddyfile +# 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 +# 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 +# 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](https://github.com/evnix/boltdbweb). @@ -132,10 +138,10 @@ You can visualize and edit the content of the database using [boltdbweb](https:/ **The legacy server is deprecated and will be removed in the next version. Consider upgrading to the Caddy-based build.** -The legacy Mercure.rocks Hub is configurable using [environment variables](https://en.wikipedia.org/wiki/Environment_variable) (recommended in production, [twelve-factor app methodology](https://12factor.net/)), command line flags and configuration files (JSON, TOML, YAML, HCL, envfile and Java properties files are supported). +The legacy Mercure.rocks Hub is configurable using [environment variables](https://en.wikipedia.org/wiki/Environment_variable) (recommended in production, [twelve-factor app methodology](https://12factor.net/)), 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. +Run `./mercure -h` to see all available command-line flags. Configuration files must be named `mercure.` (ex: `mercure.yaml`) and stored in one of the following directories: @@ -147,36 +153,36 @@ Most configuration parameters are hot reloaded: changes made to environment vari 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`) and enables ui at `https://example.com/.well-known/mercure/ui/` | `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` | -| `read__header_timeout` | the amount of time allowed to read request headers, 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 disable history, `bolt` to use [bbolt](https://github.com/etcd-io/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` | +| 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`) and enables ui at `https://example.com/.well-known/mercure/ui/` | `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` | +| `read__header_timeout` | the amount of time allowed to read request headers, 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 disable history, `bolt` to use [bbolt](https://github.com/etcd-io/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**).