From e488e878d06ecd45ca9767479d5bb4d690b03238 Mon Sep 17 00:00:00 2001 From: Wyatt Johnson Date: Thu, 25 Jun 2020 09:21:24 -0600 Subject: [PATCH] feat: updated docs (#2998) --- docs/source/01-02-configuration.md | 178 +++++++++++++++++++---------- docs/source/02-04-css.md | 40 +++++-- 2 files changed, 150 insertions(+), 68 deletions(-) diff --git a/docs/source/01-02-configuration.md b/docs/source/01-02-configuration.md index eff541fdf..829524f79 100644 --- a/docs/source/01-02-configuration.md +++ b/docs/source/01-02-configuration.md @@ -1,5 +1,5 @@ --- -title: Configuring Version 5 +title: Configuring Version 5+ permalink: /v5/configuration/ toc: true --- @@ -9,60 +9,82 @@ can expose them in your shell via `export NODE_ENV=development` or by placing the variables in a `.env` file in the root of the project in a simple `NODE_ENV=development` format delimited by newlines. -## `NODE_ENV` +## Required Configuration Variables -Can be one of `production` or `development`. All production deployments should use `production`. Defaults to `production` when ran with -`npm run start` and `development` when run with `npm run start:development`. - -## `PORT` +### `PORT` The port to listen for HTTP and Websocket requests. (Default `3000`) -## `DEV_PORT` - -The port where the Webpack Development server is running on. (Default `8080`) - -## `MONGODB_URI` +### `MONGODB_URI` The MongoDB database URI to connect to. (Default `mongodb://127.0.0.1:27017/coral`) -## `REDIS_URI` +### `REDIS_URI` The Redis database URI to connect to. (Default `redis://127.0.0.1:6379`) -## `REDIS_OPTIONS` +### `SIGNING_SECRET` -A JSON string with optional configuration options to be used when connecting to Redis as specified in the [ioredis](https://github.com/luin/ioredis/blob/1dac50a63753c2afc969315cfe38faf0edc50bc5/API.md#new_Redis_new) documentation. (Default: `{}`) +The shared secret to use to sign JSON Web Tokens (JWT) with the selected signing +algorithm. (Default: `keyboard cat`) -## `SIGNING_SECRET` +Note: While there is a default for this so development can be simplified, Coral +will throw a runtime error in the event it's started with `NODE_ENV=production` +and the `SIGNING_SECRET="keyboard cat"` to prevent insecure installations. This +_must_ be set in production to something long and secure. You can use `openssl` +to help with that: -The shared secret to use to sign JSON Web Tokens (JWT) with the selected signing algorithm. (Default: `keyboard cat`) -🚨 **Don't forget to set this variable!** 🚨 +```sh +openssl rand -base64 45 +``` -## `SIGNING_ALGORITHM` +## Advanced Configuration Variables -The signing algorithm to use for signing JWT's. (Default `HS256`). +### `NODE_ENV` -## `LOCALE` +Can be one of `production` or `development`. All production deployments should +use `production`. Defaults to `production` when ran with `npm run start`, or +with Docker deployments. Defaults to `development` when run with +`npm run start:development`. + +### `REDIS_OPTIONS` + +A JSON string with optional configuration options to be used when connecting to +Redis as specified in the [ioredis](https://github.com/luin/ioredis/blob/1dac50a63753c2afc969315cfe38faf0edc50bc5/API.md#new_Redis_new) documentation. (Default: `{}`) + +### `SIGNING_ALGORITHM` + +The signing algorithm to use for signing tokens. (Default `HS256`). + +Supported algorithms are: + +- `HS256` +- `HS384` +- `HS512` +- `RS256` +- `RS384` +- `RS512` +- `ES256` +- `ES384` +- `ES512` + +### `LOCALE` Specify the default locale to use for all requests without a locale specified. (Default `en-US`) -## `LOGGING_LEVEL` +### `LOGGING_LEVEL` The logging level that can be set to one of `fatal`, `error`, `warn`, `info`, `debug`, or `trace`. (Default `info`) -## `DISABLE_CLIENT_ROUTES` - -Disables mounting of client routes for developing with Webpack Dev Server (Default `false`) - -## `FORCE_SSL` +### `FORCE_SSL` Forces SSL in production by redirecting all HTTP requests to HTTPS, and sending -HSTS headers. (Default `false`) +[HSTS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security) headers. (Default `false`) -By default, Coral does not use HTTPS. If you want to enable HTTPS, you must -configure a proxy in front of Coral such as [Caddy](https://caddyserver.com/). +Coral does not provide or manage HTTPS certificates. If you want to enable +HTTPS, you must configure a proxy in front of Coral such as +[Caddy](https://caddyserver.com/). **Troubleshooting**: If you are seeing redirect loops when trying to access pages like the admin, you may need to configure [`TRUST_PROXY`](#trust-proxy) to @@ -73,65 +95,99 @@ headers that will force web browsers to connect via HTTPS for the next 60 days. By forcing SSL use you'll need to provide a secure connection to your Coral instance for at least the next 60 days. -## `DISABLE_LIVE_UPDATES` +### `DISABLE_LIVE_UPDATES` -When `true`, disables subscriptions for the comment stream for all stories across all tenants (Default `false`) +When `true`, the comment stream will not create a websocket connection to get +live comment updates. This applies across all tenants on the installation, and +cannot be turned back on via the interface. (Default `false`) -## `DISABLE_LIVE_UPDATES_TIMEOUT` +### `DISABLE_LIVE_UPDATES_TIMEOUT` Stories that have not received a comment within this time frame will pause live -live updates automatically. Once a single comment is received on these stories, -live updates will be re-enabled until the story sits idle for the timeout value. +updates automatically. Once a single comment is received on these stories, live +updates will be re-enabled until the story sits idle for the timeout value, +parsed by [ms](https://www.npmjs.com/package/ms). (Default `2 weeks`) -## `DISABLE_RATE_LIMITERS` - -Disables the rate limiters in development. This will only work when also set to a development environment (Default `false`) - -## `DISABLE_TENANT_CACHING` +### `DISABLE_TENANT_CACHING` When `true`, all tenants will be loaded from the database when needed rather than keeping a in-memory copy in sync via published events on Redis. (Default `false`) -## `ENABLE_GRAPHIQL` +### `ENABLE_GRAPHIQL` -When `true`, it will enable the `/graphiql` even in production, **use with care**. (Default `false`) +When `true`, it will enable the interactive GraphQL developer environment at the +`/graphiql` route. This will also disable persisted (Default `false`) -## `METRICS_USERNAME` +Note: We do not recommend using this in production environments as it disables +many safety features used by the application to provide it. -The username for _Basic Authentication_ at the `/metrics` endpoint. If not +### `METRICS_USERNAME` + +The username for _Basic Authentication_ at the `/metrics` route. If not provided with `METRICS_PASSWORD`, no authentication will be added to this route. -## `METRICS_PASSWORD` +### `METRICS_PASSWORD` -The password for _Basic Authentication_ at the `/metrics` endpoint. If not +The password for _Basic Authentication_ at the `/metrics` route. If not provided with `METRICS_USERNAME`, no authentication will be added to this route. -## `METRICS_PORT` +### `METRICS_PORT` -Metrics are provided at this port under `/metrics`. (Default `9000`) +[Prometheus](https://prometheus.io/docs/introduction/overview/) metrics are +provided at this port under `/metrics` route. (Default `9000`) -## `SCRAPE_TIMEOUT` +### `SCRAPE_TIMEOUT` -The request timeout (in ms) for scraping operations. (Default `10 seconds`) +The request timeout for scraping operations, parsed by [ms](https://www.npmjs.com/package/ms). +(Default `10 seconds`) -## `SCRAPE_MAX_RESPONSE_SIZE` +### `SCRAPE_MAX_RESPONSE_SIZE` The maximum size (in bytes) to allow for scraping responses. (Default `10e6`) -## `STATIC_URI` +### `STATIC_URI` -The URI that static assets can be accessed from. This URI can be to a proxy that uses this Coral server on `PORT` as the upstream. Disabled by default. +The URI that static assets can be accessed from. This URI can be to a proxy that +uses this Coral server on `PORT` as the upstream. Disabled by default. -## `TRUST_PROXY` +### `TRUST_PROXY` -When provided, it configures the "trust proxy" settings for Express. If you are encountering issues where urls in the administration are showing with a `http` instead of `https`, you may need to set the `TRUST_PROXY` setting. -Refer to https://expressjs.com/en/guide/behind-proxies.html for possible values -of this configuration variable as it pertains to your setup. +When provided, it configures the "trust proxy" settings for Express. If you are +encountering issues where urls in the administration are showing with a `http` +instead of `https`, you may need to set the `TRUST_PROXY` setting. Refer to +https://expressjs.com/en/guide/behind-proxies.html for possible values of this +configuration variable as it pertains to your setup. -## `WEBSOCKET_KEEP_ALIVE_TIMEOUT` +### `WEBSOCKET_KEEP_ALIVE_TIMEOUT` -A duration in a parsable format (e.g. `30 seconds`, `1 minute`) that should be used to send keep alive messages through the websocket to keep the socket alive. (Default `30 seconds`) +The interval that should be used to send keep alive messages over websocket to +keep the socket open, parsed by [ms](https://www.npmjs.com/package/ms). +(Default `30s`) -## `WORD_LIST_TIMEOUT` +### `WORD_LIST_TIMEOUT` -The word list timeout (in ms) that should be used to limit the amount of time -the process is frozen processing a word list comparison. (Default `100`) +The length of time that a given request to test a comment against a given word +list, parsed by [ms](https://www.npmjs.com/package/ms). (Default `100ms`) + +### `PERSPECTIVE_TIMEOUT` + +The length of time that a given request should wait for a response when +interacting with the Perspective API, parsed by [ms](https://www.npmjs.com/package/ms). +(Default `800ms`) + +## Development Configuration Variables + +The following configuration variables are only enabled when the server has been +started in development mode (where `NODE_ENV=development`). + +### `DEV_PORT` + +The port where the Webpack Development server is running on. (Default `8080`) + +### `DISABLE_CLIENT_ROUTES` + +Disables mounting of client routes for developing with Webpack Dev Server. +(Default `false`) + +### `DISABLE_RATE_LIMITERS` + +Used to disable the rate limiters used in Coral. (Default `false`) diff --git a/docs/source/02-04-css.md b/docs/source/02-04-css.md index 0a1f2bc57..12d6c3fed 100644 --- a/docs/source/02-04-css.md +++ b/docs/source/02-04-css.md @@ -5,7 +5,7 @@ permalink: /v5/css/ You can add your own stylesheet in **Admin** > **Configure** > **Advanced** > **Custom CSS**. -If you would like to change the styling of any elements of the comment embed, we provide global classnames. Most elements will be tagged with either `.coral` or `.coral-stream`. +If you would like to change the styling of any elements of the comment embed, we provide global classnames. Most elements will be tagged with either `.coral` or `.coral-stream`. The easiest way to find the classname for the element you're looking for is to use the web inspector, and then update your stylesheet accordingly. @@ -16,15 +16,41 @@ You can also navigate to https://github.com/coralproject/talk/blob/master/src/co You can set the class name of the `` tag inside the embed by using the `bodyClassName` parameter when calling `Coral.createStreamEmbed`: ```js - Coral.createStreamEmbed({ - bodyClassName: "pink", - }); +Coral.createStreamEmbed({ + bodyClassName: "pink" +}); ``` This will allow your styles to include variations: ```css - .pink button.coral { - background: pink; - } +.pink button.coral { + background: pink; +} +``` + +### Reaction styling + +As of Coral 6.3.0, Coral has support for styling based on the number of +reactions that a given comment has received. It does so via the: + +```sh +.coral-reacted-{{ n }} +``` + +Where `{{ n }}` is the number of reactions the comment has received. You can +invert this when creating CSS to allow you to highlight comments that have at +least `{{ n }}` reactions. For example, if you wanted to add a coral color to +comments with at least 3 reactions, you could write: + +```css +.coral-comment .coral-indent { + background-color: coral; +} + +.coral-reacted-0 .coral-indent, +.coral-reacted-1 .coral-indent, +.coral-reacted-2 .coral-indent { + background-color: transparent; +} ```