diff --git a/docs/hub/config.md b/docs/hub/config.md index 6c55919b..1966e986 100644 --- a/docs/hub/config.md +++ b/docs/hub/config.md @@ -1,36 +1,48 @@ # Configuration -The Mercure Hub follows [the twelve-factor app methodology](https://12factor.net/) and is configurable using [environment variables](https://en.wikipedia.org/wiki/Environment_variable): - - -| Variable | Description | -|-----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `ACME_CERT_DIR` | the directory where to store Let's Encrypt certificates | -| `ACME_HOSTS` | a comma separated 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`), default to `:http`. | -| `ADDR` | the address to listen on (example: `127.0.0.1:3000`, default to `:http` or `:https` depending if HTTPS is enabled or not). Note that Let's Encrypt only supports the default port: to use Let's Encrypt, **do not set this variable**. | -| `ALLOW_ANONYMOUS` | set to `1` to allow subscribers with no valid JWT to connect | -| `CERT_FILE` | a cert file (to use a custom certificate) | -| `KEY_FILE` | a key file (to use a custom certificate) | -| `COMPRESS` | set to `0` to disable HTTP compression support (default to enabled) | -| `CORS_ALLOWED_ORIGINS` | a comma separated list of allowed CORS origins, can be `*` for all | -| `DEBUG` | set to `1` to enable the 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) | -| `DEMO` | set to `1` to enable the demo mode (automatically enabled when `DEBUG=1`) | -| `HEARTBEAT_INTERVAL` | interval between heartbeats (useful with some proxies, and old browsers, default to `15s`, set to `0s` to disable) | -| `TRANSPORT_URL` | URL representation of the history database. Provided database are `null` to disabled history, `bolt` to use [bbolt](https://github.com/etcd-io/bbolt) (example `bolt:///var/run/mercure.db?size=100&cleanup_frequency=10`). (default to `bolt://updates.db`) | -| `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. Defaults to HS256. | -| `LOG_FORMAT` | the log format, can be `JSON`, `FLUENTD` or `TEXT` (default) | -| `PUBLISH_ALLOWED_ORIGINS` | a comma separated 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. Defaults to HS256. | -| `READ_TIMEOUT` | maximum duration for reading the entire request, including the body, set to `0s` to disable (default), example: `2m` | -| `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. Defaults to HS256. | -| `WRITE_TIMEOUT` | maximum duration before timing out writes of the response, set to `0s` to disable (default), example: `2m` | -| `USE_FORWARDED_HEADERS` | set to `1` to 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. | - -If `ACME_HOSTS` or both `CERT_FILE` and `KEY_FILE` are provided, an HTTPS server supporting HTTP/2 connection will be started. +The Mercure 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. + +Configuration files must be named `mercure.` (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 | +|----------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `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`), default to `:http`. | +| `addr` | the address to listen on (example: `127.0.0.1:3000`, default to `:http` or `:https` depending if HTTPS is enabled or not). Note that Let's Encrypt only supports the default port: to use Let's Encrypt, **do not set this parameter**. | +| `allow_anonymous` | set to `1` to allow subscribers with no valid JWT to connect | +| `cert_file` | a cert file (to use a custom certificate) | +| `key_file` | a key file (to use a custom certificate) | +| `compress` | set to `0` to disable HTTP compression support (default to enabled) | +| `cors_allowed_origins` | a list of allowed CORS origins, can be `*` for all | +| `debug` | set to `1` to enable the 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) | +| `demo` | set to `1` to enable the demo mode (automatically enabled when `debug=1`) | +| `heartbeat_interval` | interval between heartbeats (useful with some proxies, and old browsers, default to `15s`, set to `0s` to disable) | +| `transport_url` | URL representation of the history database. Provided database are `null` to disabled history, `bolt` to use [bbolt](https://github.com/etcd-io/bbolt) (example `bolt:///var/run/mercure.db?size=100&cleanup_frequency=10`). (default to `bolt://updates.db`) | +| `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. Defaults to HS256. | +| `log_format` | the log format, can be `JSON`, `FLUENTD` or `TEXT` (default) | +| `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. Defaults to HS256. | +| `read_timeout` | maximum duration for reading the entire request, including the body, set to `0s` to disable (default), example: `2m` | +| `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. Defaults to HS256. | +| `write_timeout` | maximum duration before timing out writes of the response, set to `0s` to disable (default), example: `2m` | +| `use_forwarded_headers` | set to `1` to 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. | + +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**). When using RSA public keys for verification make sure the key is properly formatted. @@ -44,12 +56,14 @@ bCd7nPuNAyYHCOOHAgMBAAE= -----END PUBLIC KEY----- ``` -Bash +Unix + ``` JWT_KEY=`cat jwt_key.pub` ./mercure ``` PowerShell + ``` $env:JWT_KEY = [IO.File]::ReadAllText(".\jwt_key.pub") ``` @@ -66,13 +80,11 @@ The [Data Source Name (DSN)](https://en.wikipedia.org/wiki/Data_source_name) spe Below are common examples of valid DSNs showing a combination of available values: -```bash -# absolute path to `updates.db` -TRANSPORT_URL="bolt:///var/run/database.db" + # 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" diff --git a/docs/hub/install.md b/docs/hub/install.md index a1609b26..e7cb3082 100644 --- a/docs/hub/install.md +++ b/docs/hub/install.md @@ -11,15 +11,12 @@ First, download the archive corresponding to your operating system and architect Note: Mac OS users must use the `Darwin` binary. -Then, on UNIX, run: +Then run: - JWT_KEY='!ChangeMe!' ADDR=':3000' DEMO=1 ALLOW_ANONYMOUS=1 CORS_ALLOWED_ORIGINS=* PUBLISH_ALLOWED_ORIGINS='http://localhost:3000' ./mercure + ./mercure --jwt-key='!ChangeMe!' --addr=':3000' --debug --allow-anonymous --cors-allowed-origins='*' --publish-allowed-origins='http://localhost:3000' -On Windows, start [PowerShell](https://docs.microsoft.com/en-us/powershell/), go into the extracted directory and run: - - $env:JWT_KEY='!ChangeMe!'; $env:ADDR='localhost:3000'; $env:DEMO='1'; $env:ALLOW_ANONYMOUS='1'; $env:CORS_ALLOWED_ORIGINS='*'; $env:PUBLISH_ALLOWED_ORIGINS='http://localhost:3000'; .\mercure.exe - -The Windows Defender Firewall will ask you if you want to allow `mercure.exe` to communicate through it. Allow it for both public and private networks. If you use an antivirus, or another firewall software, be sure to whitelist `mercure.exe`. +On Windows, the Windows Defender Firewall will ask you if you want to allow `mercure.exe` to communicate through it. +Allow it for both public and private networks. If you use an antivirus, or another firewall software, be sure to whitelist `mercure.exe`. The server is now available on `http://localhost:3000`, with the demo mode enabled. Because `ALLOW_ANONYMOUS` is set to `1`, anonymous subscribers are allowed.