Suggest Edits

Advanced Configuration

Talk requires configuration in order to customize the installation. The default behavior is to load it’s configuration from the environment, following the 12 Factor App Manifesto. In development, you can specify configuration in a file named .env and it will be loaded into the environment when you run yarn dev-start.

The following variables have defaults, and are optional to start your instance of Talk:

If this is your first time configuring Talk, ensure you’ve also added the Required Configuration as well, otherwise the application will fail to start.


Configure the duration for which comment counts are cached for, parsed by ms. (Default 1hr)


This is a Build Variable and must be consumed during build. If using the Docker-onbuild image you can specify it with --build-arg TALK_DEFAULT_LANG=en.

Specify the default translation language. (Default en)


This is a Build Variable and must be consumed during build. If using the Docker-onbuild image you can specify it with --build-arg TALK_DEFAULT_STREAM_TAB=all.

Specify the default stream tab in the admin. (Default all)


When TRUE, disables flagging of comments that match the suspect word filter. (Default FALSE)


When set to TRUE, the build process will not include the babel-polyfill in the embed.js target that is loaded on the page that loads the embed. (Default FALSE)


When TRUE, it will not mount the static asset serving routes on the router. This is used primarily in conjunction with TALK_STATIC_URI when the static assets are being hosted on an external domain. (Default FALSE)


A JSON string representing the configuration passed to the helmet middleware. It can be used to disable features like HSTS and others by simply providing the configuration as detailed on the helmet docs. (Default {})

For sites that do not have SSL enabled on all their pages across their domain, it is critical that you specify the following to disable the HSTS headers from being sent:


To disable these headers from being sent.


When TRUE, disables the dynamic setup endpoint /admin/install from even loading. This prevents hits to the database with enabled. This should always be set to TRUE after you’ve deployed Talk. (Default FALSE)


The algorithm used to sign/verify JWT’s used for session management. Read up about alternative algorithms on the jsonwebtoken package. (Default HS256)

Shared Secret

You would use a shared secret when you have no need to share the tokens with other applications in your organization.

Supported signing algorithms:

  • HS256
  • HS384
  • HS512

These must be provided in the form:

  "secret": "<my secret key>"

Asymmetric Secret

You would use a asymmetric secret when you want to share the token in your organization, and would like to pass an existing auth token to Talk in order to authenticate your users.

Supported signing algorithms:

  • RS256
  • RS384
  • RS512
  • ES256
  • ES384
  • ES512

These must be provided in the form:

  "public": "<the PEM encoded public key>",
  "private": "<the PEM encoded private key>"

Note that when using the asymmetric keys as discussed above, the certificates must have their newlines replaced with \\n, this is to ensure that the newlines are preserved after JSON decoding. Not doing so will result in parsing errors.

To assist with this process, we have developed a tool that can generate new certificates that match our required format: coralcert. This tool can generate RSA and ECDSA certificates, check it’s README for more details.


The audience aud claim for login JWT tokens. (Default talk)

When FALSE, Talk will not clear the cookie with name TALK_JWT_SIGNING_COOKIE_NAME when logging out but will still blacklist the token. (Default TRUE)

The default cookie name to check for a valid JWT token to use for verifying a user. (Default authorization)

The different cookie names to check for a JWT token in, separated by a ,. By default, we always use the value of TALK_JWT_COOKIE_NAME and TALK_JWT_SIGNING_COOKIE_NAME for this value. Any additional cookie names specified here will be appended to the list of cookie names to inspect.

For example, the value of:


Would mean we would check the following cookies (in order) for a valid token:

  1. talk
  3. coralproject.auth


When TRUE, Talk will not verify or sign JWT’s with an audience aud claim, even if TALK_JWT_AUDIENCE is set. (Default FALSE)


When TRUE, Talk will not verify or sign JWT’s with an issuer iss claim, even if TALK_JWT_ISSUER is set. (Default FALSE)


The expiry duration exp for the tokens issued for logged in sessions, parsed by ms. (Default 1 day)

If the user logs out, then an entry is created in the token blacklist of it’s jti for set to be automatically removed at it’s expiry time. It is important for this reason to create reasonable expiry lengths as to minimize the storage overhead.


The issuer iss claim for login JWT tokens. (Defaults to value of TALK_ROOT_URL)


Used to specify the application signing secret. You can specify this using a simple string, we recommend using a password generator and pasting it’s output. An example for TALK_JWT_SECRET could be:


You can also express this secret in the JSON syntax:

TALK_JWT_SECRET={"secret": "jX9y8G2ApcVLwyL{$6s3"}

Refer to the documentation for TALK_JWT_ALG for other signing methods and other forms of the TALK_JWT_SECRET. If you are interested in using multiple keys, then refer to TALK_JWT_SECRETS.


Used when specifying multiple secrets used for key rotations. This is a JSON encoded array, where each element matches the JWT Secret pattern. When this is used, you do not need to specify a TALK_JWT_SECRET as this will take precedence. The first secret in TALK_JWT_SECRETS will be used for signing, and must contain a private key if used with an asymmetric algorithm.

All secrets should specify a kid field which uniquely identifies a given key and will sign all tokens with that kid for later identification.

When the value of TALK_JWT_ALG is a HS* value, then the value of the TALK_JWT_SECRETS should take the form:

TALK_JWT_SECRETS=[{"kid": "1", "secret": "my-super-secret"}, {"kid": "2", "secret": "my-other-super-secret"}]

Note that the secret is stored in a JSON object, keyed by secret. This is only needed when specifying in the multiple secrets for TALK_JWT_SECRETS, but may be used to specify the single TALK_JWT_SECRET.

When the value of TALK_JWT_ALG is not a HS* value, then the value of the TALK_JWT_SECRETS should take the form:

TALK_JWT_SECRETS=[{"kid": "1", "private": "<my private key>", "public": "<my public key>"}, ...]

Refer to the documentation on the TALK_JWT_ALG for more information on what to store in these parameters.

The default cookie name that is use to set a cookie containing a JWT that was issued by Talk. (Defaults to value of TALK_JWT_COOKIE_NAME)


Specify the claim using dot notation for where the user id should be stored/read to/from. (Default sub)

If for example, the JWT’s claims looks something like this:

  "user": {
    "id": "123123"

Then we would set TALK_JWT_USER_ID_CLAIM to:


The keepalive timeout that should be used to send keep alive messages through the websocket to keep the socket alive, parsed by ms. (Default 30s)


Client secret used for enabling reCAPTCHA powered logins. If TALK_RECAPTCHA_SECRET and TALK_RECAPTCHA_PUBLIC are not provided it will instead default to providing only a time based lockout. Refer to reCAPTCHA for information on getting an account setup.


Server secret used for enabling reCAPTCHA powered logins. If TALK_RECAPTCHA_SECRET and TALK_RECAPTCHA_PUBLIC are not provided it will instead default to providing only a time based lockout. Refer to reCAPTCHA for information on getting an account setup.


Configuration overrides for the redis client configuration in a JSON encoded string. Configuration is overridden as the second parameter to the redis client constructor, and is merged with default configuration. Refer to the ioredis docs on the available options. (Default {})


The JSON encoded form of the cluster nodes. Only required when TALK_REDIS_CLUSTER_MODE is CLUSTER. See for configuration details. (Default [])


The cluster mode of the redis client. Can be either NONE or CLUSTER. (Default NONE)


The time factor that will be multiplied against the current attempt count between attempts to connect to redis, parsed by ms. (Default 500 ms)


The minimum time used to delay before attempting to reconnect to redis, parsed by ms. (Default 1 sec)


When set to TRUE, the routes will be mounted onto the <PATHNAME> component of the TALK_ROOT_URL. You would use this when your upstream proxy cannot strip the prefix from the url. (Default FALSE)

If for example, you had the following configuration:


Then all the routes for the API will be expecting to be hit on /talk/, such as /talk/api/v1/graph/ql instead of /api/v1/graph/ql. Most modern webservers can perform the path stripping when serving an upstream proxy, but some CDN’s cannot. You would use this option in the latter situation.


The email address to send emails from using the SMTP provider in the format:

TALK_SMTP_FROM_ADDRESS="The Coral Project" <>

Including the name and email address.


The domain for the SMTP provider that you are using.


The password for the SMTP provider you are using.


The port for the SMTP provider that you are using.


The username of the SMTP provider you are using.


Used to set the uri where the static assets should be served from. This is used when you want to upload the static assets through your build process to a service like Google Cloud Storage or Amazon S3 and you would then specify the CDN/Storage url. (Defaults to value of TALK_ROOT_URL)


This is a Build Variable and must be consumed during build. If using the Docker-onbuild image you can specify it with --build-arg TALK_THREADING_LEVEL=3.

Specify the maximum depth of the comment thread. (Default 3)

Note that a high value for TALK_THREADING_LEVEL will result in large performance impacts.


Used to override the location to connect to the websocket endpoint to potentially another host. This should be used when you need to route websocket requests out of your CDN in order to serve traffic more efficiently.

If the value of TALK_ROOT_URL is a https url, then this defaults to wss://${}${MOUNT_PATH}api/v1/live. Otherwise, it defaults to ws://${}${MOUNT_PATH}api/v1/live.

Where MOUNT_PATH is either / if TALK_ROOT_URL_MOUNT_PATH is FALSE, or the path component of TALK_ROOT_URL if it’s TRUE.

Warning: if used without managing the auth state manually, auth cannot be persisted due to browser restrictions.


Configure the reliability thresholds for flagging and commenting. (Default comment:2,-1;flag:2,-1)

The form of the environment variable:


The default value of:


Could be read as:

  • When a commenter has one comment rejected, their next comment must be pre-moderated once in order to post freely again. If they instead get rejected again, then they must have two of their comments approved in order to get added back to the queue.
  • At the moment of writing, behavior is not attached to the flagging reliability, but it is recorded.