mirror of
https://github.com/wassname/talk.git
synced 2026-07-19 11:28:50 +08:00
initial rewrite
This commit is contained in:
Wyatt Johnson
@@ -0,0 +1,181 @@
|
||||
---
|
||||
title: Talk Quickstart
|
||||
permalink: /
|
||||
---
|
||||
|
||||
Online comments are broken. Our open-source Talk tool rethinks how moderation,
|
||||
comment display, and conversation function, creating the opportunity for safer,
|
||||
smarter discussions around your work. Read more about our product features and
|
||||
goals [here](https://coralproject.net/products/talk.html). The
|
||||
documentation available here is pertaining to the technical details for
|
||||
installing, configuring, and deploying Talk.
|
||||
|
||||
Talk is a [Node](https://nodejs.org/) application with
|
||||
dependencies managed by
|
||||
[Yarn](https://yarnpkg.com/en/docs/install) that connects to
|
||||
[MongoDB](https://docs.mongodb.com/manual/installation/) and
|
||||
[Redis](https://redis.io/topics/quickstart) databases in order
|
||||
to persist data. The following versions are supported:
|
||||
|
||||
- Node {{ config.versions.node }}
|
||||
- Yarn {{ config.versions.yarn }}
|
||||
- MongoDB {{ config.versions.mongodb }}
|
||||
- Redis {{ config.versions.redis }}
|
||||
|
||||
An optional dependency for Talk is
|
||||
[Docker](https://www.docker.com/community-edition#/download).
|
||||
It is used during [development](#development) to set up the database and can be
|
||||
used to [install via Docker](#installation-from-docker). We have tested Talk
|
||||
and this documentation with versions {{ config.versions.docker }}.
|
||||
|
||||
Another optional dependency for Talk is
|
||||
[Docker Compose](https://docs.docker.com/compose/install/). It
|
||||
can be used to setup your environment easily for testing. We have tested Talk
|
||||
and this documentation with versions {{ config.versions.docker_compose }}.
|
||||
|
||||
## Installation
|
||||
|
||||
### Installation from Docker
|
||||
|
||||
To use Talk without major customization you can run the application using our
|
||||
provided docker image. The following is a `docker-compose.yml` file that can
|
||||
be used to setup Talk:
|
||||
|
||||
```yml
|
||||
|
||||
```
|
||||
|
||||
This is the bare minimum needed to run the demo, for more configuration
|
||||
variables, check out the [Configuration](./configuration/) section.
|
||||
|
||||
|
||||
And you can then start it with:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
This process will take a minute or two, it has to download docker images for the
|
||||
required databases and Talk as well as setup the environments.
|
||||
|
||||
Now that you've started the services started using compose, you should see
|
||||
output that resembles the following:
|
||||
|
||||
```
|
||||
Creating mongo_1 ...
|
||||
Creating redis_1 ...
|
||||
Creating mongo_1 ... done
|
||||
Creating redis_1 ... done
|
||||
Creating talk_1 ...
|
||||
Creating talk_1 ... done
|
||||
```
|
||||
|
||||
|
||||
And when you run `docker-compose ps`, you should see something like:
|
||||
|
||||
```
|
||||
Name Command State Ports
|
||||
-------------------------------------------------------------------------------
|
||||
mongo_1 docker-entrypoint.sh mongod Up 27017/tcp
|
||||
redis_1 docker-entrypoint.sh redis ... Up 6379/tcp
|
||||
talk_1 yarn start Up 0.0.0.0:3000->3000/tcp
|
||||
```
|
||||
|
||||
|
||||
Continue onto the [Running](#running) section for details on how to complete the
|
||||
installation and get started using Talk.
|
||||
|
||||
### Installation from Source
|
||||
|
||||
To install Talk from Source, ensure that you have the version of Node as
|
||||
specified above. First we will download and extract the latest codebase of Talk:
|
||||
|
||||
```bash
|
||||
curl -sLo talk.tar.gz https://github.com/coralproject/talk/archive/master.tar.gz
|
||||
mkdir -p talk
|
||||
tar xzf talk.tar.gz -C talk --strip-components 1
|
||||
cd talk
|
||||
```
|
||||
|
||||
From here we need to fetch the dependencies and build the static assets using
|
||||
Yarn:
|
||||
|
||||
```bash
|
||||
yarn
|
||||
yarn build
|
||||
```
|
||||
|
||||
You can either setup the required databases by visiting the docs for [MongoDB](https://docs.mongodb.com/manual/installation/) and
|
||||
[Redis](https://redis.io/topics/quickstart), or using the following commands which will leverage Docker:
|
||||
|
||||
```bash
|
||||
docker run -p 127.0.0.1:6379:6379 -d redis
|
||||
docker run -p 127.0.0.1:27017:27017 -d mongo
|
||||
```
|
||||
|
||||
Didn't work? Sometimes you may already have a container running on these ports,
|
||||
run `docker ps` to see what other containers you have running and running
|
||||
`docker stop <id>` on those containers to stop them.
|
||||
|
||||
|
||||
_This documentation assumes that you will be running MongoDB on
|
||||
`127.0.0.1:27017` and Redis on `127.0.0.1:6379`. The above Docker commands bind
|
||||
MongoDB and Redis on these interfaces for you._
|
||||
|
||||
We should then specify the configuration variables that can be used to run the
|
||||
application locally in a file named `.env`. This will be read by the application
|
||||
when running in development mode:
|
||||
|
||||
```bash
|
||||
NODE_ENV=development
|
||||
TALK_MONGO_URL=mongodb://127.0.0.1:27017/talk
|
||||
TALK_REDIS_URL=redis://127.0.0.1:6379
|
||||
TALK_ROOT_URL=http://127.0.0.1:3000
|
||||
TALK_PORT=3000
|
||||
TALK_JWT_SECRET=password
|
||||
TALK_FACEBOOK_APP_ID=A-Facebook-App-ID
|
||||
TALK_FACEBOOK_APP_SECRET=A-Facebook-App-Secret
|
||||
```
|
||||
|
||||
This is only the bare minimum needed to run the demo, for more configuration
|
||||
variables, check out the [Configuration](./configuration/) section. Facebook login above
|
||||
will definitely not work unless you change those values as well.
|
||||
|
||||
|
||||
You can now start the application by running:
|
||||
|
||||
```bash
|
||||
yarn watch:server
|
||||
```
|
||||
|
||||
Continue onto the [Running](#running) section for details on how to complete the
|
||||
installation and get started using Talk.
|
||||
|
||||
## Running
|
||||
|
||||
You can now navigate to
|
||||
[http://127.0.0.1:3000/admin/install](http://127.0.0.1:3000/admin/install)
|
||||
and go through the admin installation. There you will be prompted to create your
|
||||
first admin account, and specify the domain whitelist for domains that are
|
||||
allowed to have the comment box on.
|
||||
|
||||
_During development, ensure you whitelist 127.0.0.1:3000 otherwise the
|
||||
[http://127.0.0.1:3000/](http://127.0.0.1:3000/) page will not
|
||||
load._
|
||||
|
||||
Once you've completed the installation, you can visit
|
||||
[http://127.0.0.1:3000/](http://127.0.0.1:3000/) where you can
|
||||
view our development area where we test out features in Talk where you can write
|
||||
comments and see them in the admin interface where you can do moderation and
|
||||
reconfigure the user experience.
|
||||
|
||||
## Demo
|
||||
|
||||
If you've followed the documentation above, you'll now have a running copy of
|
||||
Talk. To demonstrate what your own self-hosted copy of Talk can do, below
|
||||
you'll find a demo that can be used to test the copy that is running now on your
|
||||
machine.
|
||||
|
||||
At this point you've successfully installed, configured, and ran your very own
|
||||
instance of Talk! Continue through this documentation on this site to learn more
|
||||
on how to configure, develop with, and contribute to Talk!
|
||||
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Installation from Docker
|
||||
permalink: /installation-from-docker/
|
||||
---
|
||||
|
||||
[Docker](https://www.docker.com/community-edition#/download) {{ site.versions.docker }} and
|
||||
[Docker Compose](https://docs.docker.com/compose/install/) {{ site.versions.docker_compose }} are required
|
||||
to perform installation via Docker. This is the recommended way to deploy the
|
||||
application when used in production.
|
||||
|
||||
Available as [coralproject/talk](https://hub.docker.com/r/coralproject/talk/) on
|
||||
Docker Hub. [(latest/Dockerfile)](https://github.com/coralproject/talk/blob/master/Dockerfile)
|
||||
|
||||
Images are tagged using the following notation:
|
||||
|
||||
- `x` (where `x` is the major version number): any minor or patch updates will
|
||||
be included in this. If you're ok getting new features occasionally and all
|
||||
the bug fixes, this is the tag for you. Any changes to this image tag will not
|
||||
require a database migration.
|
||||
- `x.y` (where `y` is the minor version number): any patch updates will be
|
||||
included with this tag. If you like getting fixes and having features change
|
||||
only when you want, this is the tag for you. **(recommended)**
|
||||
- `x.y.z` (where `z` is the patch version): this tag never gets updated, and
|
||||
essentially freezes your version, this should only be used when you are either
|
||||
extending Talk or are sure of a specific version you want to freeze.
|
||||
|
||||
We provide tags with `*-onbuild`
|
||||
[(onbuild/Dockerfile)](https://github.com/coralproject/talk/blob/master/Dockerfile.onbuild)
|
||||
that can be used for easy plugin integration and acts as a customization
|
||||
endpoint. To use this image tag, refer to the
|
||||
[onbuild](#onbuild) section.
|
||||
|
||||
## Installing
|
||||
|
||||
To use Talk without major customization you can run the application using our
|
||||
provided docker image. The following is a `docker-compose.yml` file that can
|
||||
be used to setup Talk:
|
||||
|
||||
```yml
|
||||
```
|
||||
|
||||
This is the bare minimum needed to start Talk, for more configuration
|
||||
variables, check out the [Configuration](./configuration/) section.
|
||||
|
||||
|
||||
And you can then start it with:
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
This process will take a minute or two, it has to download docker images for the
|
||||
required databases and Talk as well as setup the environments.
|
||||
|
||||
Now that you've started the services started using compose, you should see
|
||||
output that resembles the following:
|
||||
|
||||
```
|
||||
Creating mongo_1 ...
|
||||
Creating redis_1 ...
|
||||
Creating mongo_1 ... done
|
||||
Creating redis_1 ... done
|
||||
Creating talk_1 ...
|
||||
Creating talk_1 ... done
|
||||
```
|
||||
|
||||
|
||||
And when you run `docker-compose ps`, you should see something like:
|
||||
|
||||
```
|
||||
Name Command State Ports
|
||||
-------------------------------------------------------------------------------
|
||||
mongo_1 docker-entrypoint.sh mongod Up 27017/tcp
|
||||
redis_1 docker-entrypoint.sh redis ... Up 6379/tcp
|
||||
talk_1 yarn start Up 0.0.0.0:3000->3000/tcp
|
||||
```
|
||||
|
||||
|
||||
At this stage, you should refer to the [configuration](./configuration/) for
|
||||
configuration variables that are specific to your installation.
|
||||
|
||||
## Onbuild
|
||||
|
||||
We provide `*-onbuild` images to assist and automate the customization of our
|
||||
base installation with additional custom plugins. Images can be created with the
|
||||
most basic of `Dockerfile`'s:
|
||||
|
||||
```docker
|
||||
FROM coralproject/talk:latest-onbuild
|
||||
```
|
||||
|
||||
And running the following to build the docker image:
|
||||
|
||||
```bash
|
||||
docker build -t my-awesome-talk-image --build-arg TALK_DEFAULT_LANG=es .
|
||||
```
|
||||
|
||||
Don't forget to replace `my-awesome-talk-image` with your own image name, and
|
||||
specify your build variables with the `--build-arg`. Refer to [Dockerfile.onbuild](https://github.com/coralproject/talk/blob/master/Dockerfile.onbuild) for the
|
||||
available build variables.
|
||||
|
||||
|
||||
This accomplishes a lot:
|
||||
|
||||
1. Copies all the files alongside the `Dockerfile` into the application
|
||||
directory in the Docker image.
|
||||
2. Installs any new dependencies that were required by any new plugins.
|
||||
3. Builds the new static bundles so that they are ready to serve when the image
|
||||
is running.
|
||||
4. Specifies a build time variable [TALK_DEFAULT_LANG](./advanced-configuration/#talk_default_lang). Refer
|
||||
to [Dockerfile.onbuild](https://github.com/coralproject/talk/blob/master/Dockerfile.onbuild) for the
|
||||
available build variables.
|
||||
|
||||
This means that you can create a repository for your organization that simply
|
||||
includes the above `Dockerfile`, a directory of `plugins`, and a `plugins.json`
|
||||
file which specifies the activated plugins, and you can deploy Talk easily to
|
||||
your containerized infrastructure. The versioning of our Docker tags as well
|
||||
lets you do something like:
|
||||
|
||||
```docker
|
||||
FROM coralproject/talk:4.0-onbuild
|
||||
```
|
||||
|
||||
Which would pin your image to `4.0` release's.
|
||||
@@ -0,0 +1,78 @@
|
||||
---
|
||||
title: Installation from Source
|
||||
permalink: /installation-from-source/
|
||||
---
|
||||
|
||||
To install Talk from Source, ensure that you have Node version
|
||||
{{ site.versions.node }}. Installing via source is the recommended method when
|
||||
developing as it give you the best tooling. We release versions using semantic
|
||||
versioning, and do so to our
|
||||
[Github Releases](https://github.com/coralproject/talk/releases)
|
||||
page. There you can download archives of older versions or the latest release.
|
||||
The examples following will download the latest code on our master branch.
|
||||
|
||||
## Installing
|
||||
|
||||
First we will download and extract the latest codebase of Talk:
|
||||
|
||||
```bash
|
||||
curl -sLo talk.tar.gz https://github.com/coralproject/talk/archive/master.tar.gz
|
||||
mkdir -p talk
|
||||
tar xzf talk.tar.gz -C talk --strip-components 1
|
||||
cd talk
|
||||
```
|
||||
|
||||
From here we need to fetch the dependencies and build the static assets using
|
||||
Yarn:
|
||||
|
||||
```bash
|
||||
yarn
|
||||
yarn build
|
||||
```
|
||||
|
||||
You can either setup the required databases by visiting the docs for [MongoDB](https://docs.mongodb.com/manual/installation/) and
|
||||
[Redis](https://redis.io/topics/quickstart), or using the following commands which will leverage Docker:
|
||||
|
||||
```bash
|
||||
docker run -p 127.0.0.1:6379:6379 -d redis
|
||||
docker run -p 127.0.0.1:27017:27017 -d mongo
|
||||
```
|
||||
|
||||
Didn't work? Sometimes you may already have a container running on these ports,
|
||||
run `docker ps` to see what other containers you have running and running
|
||||
`docker stop <id>` on those containers to stop them.
|
||||
|
||||
|
||||
_This documentation assumes that you will be running MongoDB on
|
||||
`127.0.0.1:27017` and Redis on `127.0.0.1:6379`. The above Docker commands bind
|
||||
MongoDB and Redis on these interfaces for you._
|
||||
|
||||
We should then specify the configuration variables that can be used to run the
|
||||
application locally in a file named `.env`. This will be read by the application
|
||||
when running in development mode:
|
||||
|
||||
```bash
|
||||
NODE_ENV=development
|
||||
TALK_MONGO_URL=mongodb://127.0.0.1:27017/talk
|
||||
TALK_REDIS_URL=redis://127.0.0.1:6379
|
||||
TALK_ROOT_URL=http://127.0.0.1:3000
|
||||
TALK_PORT=3000
|
||||
TALK_JWT_SECRET=password
|
||||
TALK_FACEBOOK_APP_ID=A-Facebook-App-ID
|
||||
TALK_FACEBOOK_APP_SECRET=A-Facebook-App-Secret
|
||||
```
|
||||
|
||||
This is the bare minimum needed to start Talk, for more configuration
|
||||
variables, check out the [Configuration](./configuration/)
|
||||
section. Facebook login above will definitely not work unless you change those
|
||||
values as well.
|
||||
|
||||
|
||||
You can now start the application by running:
|
||||
|
||||
```bash
|
||||
yarn watch:server
|
||||
```
|
||||
|
||||
At this stage, you should refer to the [configuration](./configuration/) for
|
||||
configuration variables that are specific to your installation.
|
||||
@@ -0,0 +1,83 @@
|
||||
---
|
||||
title: Required Configuration
|
||||
permalink: /configuration/
|
||||
class: 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](https://12factor.net/).
|
||||
In development, you can specify configuration in a file named `.env` and it will
|
||||
be loaded into the environment when you run `yarn watch:server`.
|
||||
|
||||
The following variables do not have defaults, and are **required** to start your
|
||||
instance of Talk:
|
||||
|
||||
If you've already configured your application with the required configuration,
|
||||
you can further customize it's behavior by applying
|
||||
[Advanced Configuration](./advanced-configuration/).
|
||||
|
||||
## TALK_MONGO_URL
|
||||
|
||||
The database connection string for the MongoDB database. This usually takes the
|
||||
form of:
|
||||
|
||||
```plain
|
||||
TALK_MONGO_URL=mongodb://<DATABASE USER>:<DATABASE PASSWORD>@<DATABASE HOST>:<DATABASE PORT>/<DATABASE NAME>
|
||||
```
|
||||
|
||||
Refer to [connection string uri format](https://docs.mongodb.com/manual/reference/connection-string/)
|
||||
for the detailed url scheme of the MongoDB url.
|
||||
|
||||
## TALK_REDIS_URL
|
||||
|
||||
The database connection string for the Redis database. This usually takes the
|
||||
form of:
|
||||
|
||||
```plain
|
||||
TALK_REDIS_URL=redis://user:<DATABASE PASSWORD>@<DATABASE HOST>:<DATABASE PORT>/<DATABASE NUMBER>
|
||||
```
|
||||
|
||||
If we for example, had Redis running on our local machine without a password,
|
||||
where I want to use database #2, I could set the `TALK_REDIS_URL` to:
|
||||
|
||||
```plain
|
||||
TALK_REDIS_URL=redis://127.0.0.1:6379/2
|
||||
```
|
||||
|
||||
Refer to [uri scheme](http://www.iana.org/assignments/uri-schemes/prov/redis)
|
||||
for the detailed url scheme of the Redis url.
|
||||
|
||||
## TALK_ROOT_URL
|
||||
|
||||
The root url of the installed application externally available in the format:
|
||||
|
||||
```plain
|
||||
TALK_ROOT_URL=<SCHEME>://<HOST>:<PORT?>/<PATHNAME>
|
||||
```
|
||||
|
||||
For example, if we installed our application onto the `talk.coralproject.net`
|
||||
domain, where we used a proxy like [Caddy](https://caddyserver.com)
|
||||
or [Nginx](https://nginx.org) to perform SSL termination, then
|
||||
`TALK_ROOT_URL` would be:
|
||||
|
||||
```plain
|
||||
TALK_ROOT_URL=https://talk.coralproject.net/
|
||||
```
|
||||
|
||||
_Note that we omitted the `PORT`, as it was implied by setting the `SCHEME` to
|
||||
`https`._
|
||||
|
||||
## TALK_JWT_SECRET
|
||||
|
||||
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:
|
||||
|
||||
```plain
|
||||
TALK_JWT_SECRET=jX9y8G2ApcVLwyL{$6s3
|
||||
```
|
||||
|
||||
Be default, we sign our tokens with HMAC using a SHA-256 hash algorithm. If you
|
||||
want to change the signing algorithm, or use multiple signing/verifying keys,
|
||||
refer to our [Advanced Configuration](./advanced-configuration/) documentation.
|
||||
@@ -0,0 +1,502 @@
|
||||
---
|
||||
title: Advanced Configuration
|
||||
permalink: /advanced-configuration/
|
||||
class: configuration
|
||||
---
|
||||
|
||||
Talk requires configuration in order to customize the installation. The default
|
||||
behavior is to load its configuration from the environment, following the
|
||||
[12 Factor App Manifesto](https://12factor.net/).
|
||||
In development, you can specify configuration in a file named `.env` and it will
|
||||
be loaded into the environment when you run `yarn watch:server`.
|
||||
|
||||
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](./configuration) as well,
|
||||
otherwise the application will fail to start.
|
||||
|
||||
## TALK_CACHE_EXPIRY_COMMENT_COUNT
|
||||
|
||||
Configure the duration for which comment counts are cached for, parsed by
|
||||
[ms](https://www.npmjs.com/package/ms). (Default `1hr`)
|
||||
|
||||
## TALK_DEFAULT_LANG
|
||||
|
||||
This is a **Build Variable** and must be consumed during build. If using the
|
||||
[Docker-onbuild](./installation-from-docker/#onbuild)
|
||||
image you can specify it with `--build-arg TALK_DEFAULT_LANG=en`.
|
||||
|
||||
Specify the default translation language. (Default `en`)
|
||||
|
||||
## TALK_DEFAULT_STREAM_TAB
|
||||
|
||||
This is a **Build Variable** and must be consumed during build. If using the
|
||||
[Docker-onbuild](./installation-from-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`)
|
||||
|
||||
## TALK_DISABLE_AUTOFLAG_SUSPECT_WORDS
|
||||
|
||||
When `TRUE`, disables flagging of comments that match the suspect word filter. (Default `FALSE`)
|
||||
|
||||
## TALK_DISABLE_EMBED_POLYFILL
|
||||
|
||||
When set to `TRUE`, the build process will not include the
|
||||
[babel-polyfill](https://babeljs.io/docs/usage/polyfill/)
|
||||
in the embed.js target that is loaded on the page that loads the embed. (Default
|
||||
`FALSE`)
|
||||
|
||||
## TALK_DISABLE_STATIC_SERVER
|
||||
|
||||
When `TRUE`, it will not mount the static asset serving routes on the router.
|
||||
This is used primarily in conjunction with [TALK_STATIC_URI](#talk_static_uri)
|
||||
when the static assets are being hosted on an external domain. (Default `FALSE`)
|
||||
|
||||
## TALK_FACEBOOK_APP_ID
|
||||
|
||||
The Facebook App ID for your Facebook Login enabled app. You can learn more
|
||||
about getting a Facebook App ID at the
|
||||
[Facebook Developers Portal](https://developers.facebook.com)
|
||||
or by visiting the
|
||||
[Creating an App ID](https://developers.facebook.com/docs/apps/register)
|
||||
guide. This is only required while the `talk-plugin-facebook-auth` plugin is
|
||||
enabled.
|
||||
|
||||
## TALK_FACEBOOK_APP_SECRET
|
||||
|
||||
The Facebook App Secret for your Facebook Login enabled app. You can learn more
|
||||
about getting a Facebook App Secret at the
|
||||
[Facebook Developers Portal](https://developers.facebook.com)
|
||||
or by visiting the
|
||||
[Creating an App ID](https://developers.facebook.com/docs/apps/register)
|
||||
guide. This is only required while the `talk-plugin-facebook-auth` plugin is
|
||||
enabled.
|
||||
|
||||
## TALK_HELMET_CONFIGURATION
|
||||
|
||||
A JSON string representing the configuration passed to the
|
||||
[helmet](https://github.com/helmetjs/helmet) middleware. It
|
||||
can be used to disable features like [HSTS](https://helmetjs.github.io/docs/hsts/)
|
||||
and others by simply providing the configuration as detailed on the
|
||||
[helmet docs](https://helmetjs.github.io/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](https://helmetjs.github.io/docs/hsts/) headers from
|
||||
being sent:
|
||||
|
||||
```plain
|
||||
TALK_HELMET_CONFIGURATION={"hsts": false}
|
||||
```
|
||||
|
||||
To disable these headers from being sent.
|
||||
|
||||
## TALK_INSTALL_LOCK
|
||||
|
||||
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`)
|
||||
|
||||
## TALK_JWT_ALG
|
||||
|
||||
The algorithm used to sign/verify JWTs used for session management. Read up
|
||||
about alternative algorithms on the
|
||||
[jsonwebtoken](https://www.npmjs.com/package/jsonwebtoken#algorithms-supported)
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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](https://github.com/coralproject/coralcert).
|
||||
This tool can generate RSA and ECDSA certificates, check it's [README](https://github.com/coralproject/coralcert)
|
||||
for more details.
|
||||
|
||||
## TALK_JWT_AUDIENCE
|
||||
|
||||
The audience [aud](https://tools.ietf.org/html/rfc7519#section-4.1.3)
|
||||
claim for login JWT tokens. (Default `talk`)
|
||||
|
||||
## TALK_JWT_CLEAR_COOKIE_LOGOUT
|
||||
|
||||
When `FALSE`, Talk will not clear the cookie with name
|
||||
[TALK_JWT_SIGNING_COOKIE_NAME](#talk_jwt_signing_cookie_name) when logging out
|
||||
but will still blacklist the token. (Default `TRUE`)
|
||||
|
||||
## TALK_JWT_COOKIE_NAME
|
||||
|
||||
The default cookie name to check for a valid JWT token to use for verifying a
|
||||
user. (Default `authorization`)
|
||||
|
||||
## TALK_JWT_COOKIE_NAMES
|
||||
|
||||
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](#talk_jwt_cookie_name)
|
||||
and [TALK_JWT_SIGNING_COOKIE_NAME](#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:
|
||||
|
||||
```plain
|
||||
TALK_JWT_COOKIE_NAME=talk
|
||||
TALK_JWT_SIGNING_COOKIE_NAME=talk
|
||||
TALK_JWT_COOKIE_NAMES=coralproject.talk,coralproject.auth
|
||||
```
|
||||
|
||||
Would mean we would check the following cookies (in order) for a valid token:
|
||||
|
||||
1. `talk`
|
||||
2. `coralproject.talk`
|
||||
3. `coralproject.auth`
|
||||
|
||||
## TALK_JWT_DISABLE_AUDIENCE
|
||||
|
||||
When `TRUE`, Talk will not verify or sign JWT’s with an audience
|
||||
[aud](https://tools.ietf.org/html/rfc7519#section-4.1.3)
|
||||
claim, even if [TALK_JWT_AUDIENCE](#talk_jwt_audience) is set. (Default `FALSE`)
|
||||
|
||||
## TALK_JWT_DISABLE_ISSUER
|
||||
|
||||
When `TRUE`, Talk will not verify or sign JWT’s with an issuer
|
||||
[iss](https://tools.ietf.org/html/rfc7519#section-4.1.1)
|
||||
claim, even if [TALK_JWT_ISSUER](#talk_jwt_issuer) is set. (Default `FALSE`)
|
||||
|
||||
## TALK_JWT_EXPIRY
|
||||
|
||||
The expiry duration [exp](https://tools.ietf.org/html/rfc7519#section-4.1.4)
|
||||
for the tokens issued for logged in sessions, parsed by
|
||||
[ms](https://www.npmjs.com/package/ms). (Default `1 day`)
|
||||
|
||||
If the user logs out, then an entry is created in the token blacklist of it's
|
||||
[jti](https://tools.ietf.org/html/rfc7519#section-4.1.7) 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.
|
||||
|
||||
## TALK_JWT_ISSUER
|
||||
|
||||
The issuer [iss](https://tools.ietf.org/html/rfc7519#section-4.1.1)
|
||||
claim for login JWT tokens. (Defaults to value of [TALK_ROOT_URL](./configuration/#talk_root_url))
|
||||
|
||||
## TALK_JWT_SECRET
|
||||
|
||||
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:
|
||||
|
||||
```plain
|
||||
TALK_JWT_SECRET=jX9y8G2ApcVLwyL{$6s3
|
||||
```
|
||||
|
||||
You can also express this secret in the JSON syntax:
|
||||
|
||||
```plain
|
||||
TALK_JWT_SECRET={"secret": "jX9y8G2ApcVLwyL{$6s3"}
|
||||
```
|
||||
|
||||
Refer to the documentation for [TALK_JWT_ALG](#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](#talk_jwt_secrets).
|
||||
|
||||
## 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](#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](#talk_jwt_alg) is a `HS*` value, then the value
|
||||
of the `TALK_JWT_SECRETS` should take the form:
|
||||
|
||||
```plain
|
||||
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](#talk_jwt_secret).
|
||||
|
||||
|
||||
When the value of [TALK_JWT_ALG](#talk_jwt_alg) is **not** a `HS*` value, then
|
||||
the value of the `TALK_JWT_SECRETS` should take the form:
|
||||
|
||||
```plain
|
||||
TALK_JWT_SECRETS=[{"kid": "1", "private": "<my private key>", "public": "<my public key>"}, ...]
|
||||
```
|
||||
|
||||
Refer to the documentation on the [TALK_JWT_ALG](#talk_jwt_alg) for more
|
||||
information on what to store in these parameters.
|
||||
|
||||
|
||||
## TALK_JWT_SIGNING_COOKIE_NAME
|
||||
|
||||
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](#talk_jwt_cookie_name))
|
||||
|
||||
## TALK_JWT_USER_ID_CLAIM
|
||||
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"user": {
|
||||
"id": "123123"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Then we would set `TALK_JWT_USER_ID_CLAIM` to:
|
||||
|
||||
```plain
|
||||
TALK_JWT_USER_ID_CLAIM=user.id
|
||||
```
|
||||
|
||||
## TALK_KEEP_ALIVE
|
||||
|
||||
The keepalive timeout that should be used to send keep alive messages through
|
||||
the websocket to keep the socket alive, parsed by
|
||||
[ms](https://www.npmjs.com/package/ms). (Default `30s`)
|
||||
|
||||
## TALK_RECAPTCHA_PUBLIC
|
||||
|
||||
Setting a reCAPTCHA Public and Secret key will enable and require reCAPTCHA upon multiple failed login attempts.
|
||||
|
||||
Client secret used for enabling reCAPTCHA powered logins. If
|
||||
[TALK_RECAPTCHA_SECRET](#talk_recaptcha_secret) and
|
||||
[TALK_RECAPTCHA_PUBLIC](#talk_recaptcha_public) are not provided it will instead
|
||||
default to providing only a time based lockout. Refer to
|
||||
[reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) for information
|
||||
on getting an account setup.
|
||||
|
||||
## TALK_RECAPTCHA_SECRET
|
||||
|
||||
Server secret used for enabling reCAPTCHA powered logins. If
|
||||
[TALK_RECAPTCHA_SECRET](#talk_recaptcha_secret) and
|
||||
[TALK_RECAPTCHA_PUBLIC](#talk_recaptcha_public) are not provided it will instead
|
||||
default to providing only a time based lockout. Refer to
|
||||
[reCAPTCHA](https://www.google.com/recaptcha/intro/index.html) for information
|
||||
on getting an account setup.
|
||||
|
||||
## TALK_REDIS_CLIENT_CONFIGURATION
|
||||
|
||||
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](https://github.com/luin/ioredis) docs on the
|
||||
available options. (Default `{}`)
|
||||
|
||||
## TALK_REDIS_CLUSTER_CONFIGURATION
|
||||
|
||||
The JSON encoded form of the cluster nodes. Only required when
|
||||
[TALK_REDIS_CLUSTER_MODE](#talk_redis_cluster_mode) is `CLUSTER`. See
|
||||
[https://github.com/luin/ioredis#cluster](https://github.com/luin/ioredis#cluster)
|
||||
for configuration details. (Default `[]`)
|
||||
|
||||
## TALK_REDIS_CLUSTER_MODE
|
||||
|
||||
The cluster mode of the redis client. Can be either `NONE` or `CLUSTER`.
|
||||
(Default `NONE`)
|
||||
|
||||
## TALK_REDIS_RECONNECTION_BACKOFF_FACTOR
|
||||
|
||||
The time factor that will be multiplied against the current attempt count
|
||||
between attempts to connect to redis, parsed by
|
||||
[ms](https://www.npmjs.com/package/ms). (Default `500 ms`)
|
||||
|
||||
## TALK_REDIS_RECONNECTION_BACKOFF_MINIMUM_TIME
|
||||
|
||||
The minimum time used to delay before attempting to reconnect to redis, parsed
|
||||
by [ms](https://www.npmjs.com/package/ms). (Default `1 sec`)
|
||||
|
||||
## TALK_ROOT_URL_MOUNT_PATH
|
||||
|
||||
When set to `TRUE`, the routes will be mounted onto the `<PATHNAME>` component
|
||||
of the [TALK_ROOT_URL](./configuration/#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:
|
||||
|
||||
```plain
|
||||
TALK_ROOT_URL=https://coralproject.net/talk/
|
||||
TALK_ROOT_URL_MOUNT_PATH=TRUE
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## TALK_SMTP_FROM_ADDRESS
|
||||
|
||||
The email address to send emails from using the SMTP provider in the format:
|
||||
|
||||
```plain
|
||||
TALK_SMTP_FROM_ADDRESS="The Coral Project" <support@coralproject.net>
|
||||
```
|
||||
|
||||
Including the name and email address.
|
||||
|
||||
## TALK_SMTP_HOST
|
||||
|
||||
The domain for the SMTP provider that you are using.
|
||||
|
||||
## TALK_SMTP_PASSWORD
|
||||
|
||||
The password for the SMTP provider you are using.
|
||||
|
||||
## TALK_SMTP_PORT
|
||||
|
||||
The port for the SMTP provider that you are using.
|
||||
|
||||
## TALK_SMTP_USERNAME
|
||||
|
||||
The username of the SMTP provider you are using.
|
||||
|
||||
## TALK_STATIC_URI
|
||||
|
||||
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](./configuration/#talk_root_url))
|
||||
|
||||
## TALK_THREADING_LEVEL
|
||||
|
||||
This is a **Build Variable** and must be consumed during build. If using the
|
||||
[Docker-onbuild](./installation-from-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.**
|
||||
|
||||
## TALK_WEBSOCKET_LIVE_URI
|
||||
|
||||
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](./configuration/#talk_root_url)
|
||||
is a https url, then this defaults to `wss://${location.host}${MOUNT_PATH}api/v1/live`.
|
||||
Otherwise, it defaults to `ws://${location.host}${MOUNT_PATH}api/v1/live`.
|
||||
|
||||
Where `MOUNT_PATH` is either `/` if [TALK_ROOT_URL_MOUNT_PATH](#talk_root_url_mount_path)
|
||||
is `FALSE`, or the path component of
|
||||
[TALK_ROOT_URL](./configuration/#talk_root_url) if it's `TRUE`.
|
||||
|
||||
**Warning: if used without managing the auth state manually, auth
|
||||
cannot be persisted due to browser restrictions.**
|
||||
|
||||
## TRUST_THRESHOLDS
|
||||
|
||||
Configure the reliability thresholds for flagging and commenting. (Default
|
||||
`comment:2,-1;flag:2,-1`)
|
||||
|
||||
The form of the environment variable:
|
||||
|
||||
```plain
|
||||
TRUST_THRESHOLDS=comment:<RELIABLE COMMENTER>,<UNRELIABLE COMMENTER>;flag:<RELIABLE FLAGGER>,<UNRELIABLE FLAGGER>
|
||||
```
|
||||
|
||||
The default value of:
|
||||
|
||||
```plain
|
||||
TRUST_THRESHOLDS=comment:2,-1;flag:2,-1
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
## TALK_DISABLE_IGNORE_FLAGS_AGAINST_STAFF
|
||||
|
||||
When `TRUE`, staff members will have their accounts and comments moderated the
|
||||
same as any other user in the system. (Default `FALSE`)
|
||||
|
||||
## TALK_EMAIL_SUBJECT_PREFIX
|
||||
|
||||
The prefix for the subject of emails sent. An email with the specified subject
|
||||
of `Email Confirmation` would then be sent as `[Talk] Email Confirmation`.
|
||||
(Default `[Talk]`)
|
||||
|
||||
## DISABLE_CREATE_MONGO_INDEXES
|
||||
|
||||
When `TRUE`, Talk will not attempt to create any indices. This is recommended
|
||||
for production systems that have ran Talk at least once during setup while unset
|
||||
or set to `FALSE`.
|
||||
|
||||
## TALK_SETTINGS_CACHE_TIME
|
||||
|
||||
The duration of time that the settings object will be kept in the Redis cache,
|
||||
parsed by [ms](https://www.npmjs.com/package/ms). (Default
|
||||
`1hr`)
|
||||
|
||||
## APOLLO_ENGINE_KEY
|
||||
|
||||
Used to set the key for use with
|
||||
[Apollo Engine](https://www.apollographql.com/engine/) for
|
||||
tracing of GraphQL requests.
|
||||
|
||||
**Note: Apollo Engine is a premium service, charges may apply.**
|
||||
@@ -0,0 +1,40 @@
|
||||
---
|
||||
title: How Talk Works
|
||||
permalink: /how-talk-works/
|
||||
---
|
||||
|
||||
Talk is an open-source commenting platform. It has two pieces. One is the
|
||||
embedded script, which allows newsrooms to have a unique comments section on
|
||||
each story/post/page they have on their site, and allows their readers to
|
||||
comment and discuss articles. The other is the Admin, which is where newsrooms
|
||||
moderate their comments and manage and configure Talk.
|
||||
|
||||
## Talk Core
|
||||
|
||||
As we’re building Talk, our vision was always to have it be very modular, so
|
||||
there are features we have built and are opinionated about, but we allow
|
||||
newsrooms and their developers to customize Talk easily so that it fits their
|
||||
use cases and needs.
|
||||
|
||||
Talk Core is the core application of Talk - this contains all of the standard
|
||||
commenting features that are necessary for a comment section, and ones that we
|
||||
believe are important to be universal. If you would like to contribute to Talk,
|
||||
be sure to check out our
|
||||
[Contributor's Guide](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md).
|
||||
|
||||
## Plugins
|
||||
|
||||
Plugins are additional functionality which are optional to use with Talk. You
|
||||
can turn these on or off, depending on your specific needs. Plugins are either
|
||||
part of our core plugins, which ship with Talk, or they are developed by 3rd
|
||||
parties and either used privately and internally, or are open sourced for use
|
||||
across the greater community. You can explore the plugins we offer by visiting our [Default Plugins](./default-plugins/)
|
||||
and [Additional Plugins](./additional-plugins/) pages.
|
||||
|
||||
## Recipes
|
||||
|
||||
Recipes are plugin templates that are created by the Talk team and 3rd party
|
||||
developers, in order to help contributors and newsrooms build plugins easily.
|
||||
You can explore the recipes we offer by visiting our [Plugin Recipes](./plugin-recipes/)
|
||||
page.
|
||||
|
||||
@@ -0,0 +1,200 @@
|
||||
---
|
||||
title: Commenter Features
|
||||
permalink: /commenter-features/
|
||||
---
|
||||
|
||||
## Signing up for Talk
|
||||
|
||||
There are 2 ways that newsrooms can support signup/login functionality with Talk:
|
||||
|
||||
* Use Talk’s auth plugin out of the box (supports account registration with username and password, as well as features like forgot password)
|
||||
|
||||
* Create their own auth plugin to integrate with your own auth systems
|
||||
|
||||
We also provide a Facebook auth plugin that supports logging in with Facebook (you must provide your own Facebook App ID and Secret, which you can read more about here: [https://developers.facebook.com](https://developers.facebook.com))
|
||||
|
||||
## Comments and Replies
|
||||
|
||||
Talk supports a standard comment hierarchy. There are top-level (or parent) comments, and then replies to that comment (or children comments).
|
||||
|
||||
### Permalinks
|
||||
|
||||
All levels of comments and replies are able to be linked to via permalink. Permalinks are structured using a `commentId` query param:
|
||||
|
||||
```text
|
||||
https://<your asset url>?commentId=<the comment id>
|
||||
```
|
||||
{:.no-copy}
|
||||
|
||||
### Threading
|
||||
|
||||
Talk supports by default 3 levels of threading, meaning each top-level comment
|
||||
has a depth of 3 replies; replies beyond that are not nested below the 3rd
|
||||
level. You can adjust this using the
|
||||
[TALK_THREADING_LEVEL](./advanced-configuration/#talk_threading_level)
|
||||
configuration variable. We don’t recommend deep threading because it can cause
|
||||
issues with styling, especially on mobile.
|
||||
|
||||
You can style threaded comments using these CSS classes:
|
||||
|
||||
```
|
||||
talk-stream-comment-wrapper-level-${depth}
|
||||
talk-stream-comment
|
||||
talk-stream-comment-level-${depth}
|
||||
talk-stream-highlighted-comment
|
||||
talk-stream-pending-comment
|
||||
```
|
||||
{:.no-copy}
|
||||
|
||||
### Automatic Updates
|
||||
|
||||
Talk supports real-time loading and updating of comments, via subscriptions
|
||||
(specifically GraphQL Subscriptions); this enables us to not have to refresh to
|
||||
see new comments on a given comment stream.
|
||||
|
||||
Talk enables this via “Load More” buttons for both top-level comments (this
|
||||
button appears at the top of the stream), and within conversation threads (this
|
||||
button appears in situ for replies).
|
||||
|
||||
We’ve decided to go this route in order to make the viewing experience as smooth
|
||||
as possible, so that the feed of comments doesn’t change as you’re reading just
|
||||
because new comments are coming in. This could be especially disruptive on
|
||||
breaking news and/or controversial stories with very active discussions.
|
||||
|
||||
### Comment Character Limits
|
||||
|
||||
You can enable Talk to limit the character length for comments, for example,
|
||||
some newsrooms we’ve worked with prefer a limit between 2000 and 5000
|
||||
characters. Commenters will be alerted that they have gone over that number and
|
||||
won’t be able to submit their comment until they’ve edited it. This can be a
|
||||
useful tool to ensure commenters are concise with their comments.
|
||||
|
||||
## Comment Reactions
|
||||
|
||||
Talk comes with a `respect` button out of the box. Why a “respect” button, you
|
||||
ask?
|
||||
[Read more here](https://mediaengagement.org/research/engagement-buttons/).
|
||||
|
||||
We also have 2 more plugins, `like` and `love`, that you can turn on and
|
||||
experiment with on your own Talk install.
|
||||
|
||||
And our plugin architecture makes it easy to create your own custom reaction
|
||||
buttons too.
|
||||
|
||||
## Reporting Comments
|
||||
|
||||
Readers can report comments if they feel they’re unsuitable. They can choose one
|
||||
of the following reasons:
|
||||
|
||||
* This comment is offensive
|
||||
* This looks like an ad/marketing
|
||||
* I don’t agree with this comment
|
||||
* Other
|
||||
|
||||
They can also include more information and this shows for moderators in the Flag
|
||||
Detail area on the comments in the moderation queues.
|
||||
|
||||
Comments that are reported go to the Reported queue, with the exception of “I
|
||||
don’t agree with this comment”. This option is a useful way to let other readers
|
||||
vent their frustration, but since just disagreeing with something doesn’t mean
|
||||
it’s not suitable, we leave it be.
|
||||
|
||||
|
||||
## Reporting Usernames
|
||||
|
||||
Usernames can also be reported by readers, if the username is inappropriate or
|
||||
offensive. They can choose one of the following reasons:
|
||||
|
||||
* This username is offensive
|
||||
* I don't like this username
|
||||
* This user is impersonating
|
||||
* This looks like an ad/marketing
|
||||
|
||||
Reported usernames go to the Reported Usernames queue which is located in the
|
||||
Community tab. If a username is rejected by a moderator, the commenter is
|
||||
prompted to change their username and they are suspended from commenting,
|
||||
replying or reacting to comments until they do so. They receive an email, and
|
||||
also a message at the top of their comment streams that let’s them know they’re
|
||||
suspended.
|
||||
|
||||
If the commenter changes their username, it goes back to the Reported Usernames
|
||||
queue for approval. If the updated username is accepted by a moderator, the
|
||||
commenter is no longer suspended and continue interacting with the community. If
|
||||
the username is rejected, the commenter remains suspended until they change
|
||||
their username to something appropriate.
|
||||
|
||||
Approved usernames that are reported do not show up in the Reported Usernames
|
||||
queues any longer, since they have been specifically OK’ed by a moderator.
|
||||
|
||||
## Ignoring Users
|
||||
|
||||
Commenters can ignore other commenters and essentially mute them entirely from
|
||||
the comment platform. Commenters can manage their ignored users list in their My
|
||||
Profile tab.
|
||||
|
||||
## Featured Comments
|
||||
|
||||
Moderators can feature comments that they want to highlight and recommend to
|
||||
their community. Featured comments show up on a separate tab, that is the
|
||||
default for the comment stream. Featured comments within the stream show a
|
||||
Featured badge.
|
||||
|
||||
## Sorting the Stream
|
||||
|
||||
Readers can sort the stream in 4 ways based on their viewing preferences:
|
||||
|
||||
* Oldest first
|
||||
* Newest first
|
||||
* Most respect first (or most liked, most loved, etc., depending on what
|
||||
reactions you use)
|
||||
* Most replied first
|
||||
|
||||
We also make it easy to add more sorts via custom plugins.
|
||||
|
||||
## Badges
|
||||
|
||||
Badges differentiate users and comments on the stream. By default, Talk has two
|
||||
badges.
|
||||
|
||||
The Staff user badge that shows when a commenter has an Admin, Moderator, or
|
||||
Staff role.
|
||||
|
||||
The Featured comment badge shows when a comment has been featured.
|
||||
|
||||
Another optional badge is the Subscriber badge (which is available as a
|
||||
[Recipe](./plugin-recipes/#recipe-subscriber).
|
||||
|
||||
Badges are another easy part of Talk to customize by creating a new `tag`, then
|
||||
setting some rules for when it should show, and how the badge should be styled.
|
||||
|
||||
## My Profile
|
||||
|
||||
The My Profile tab is where commenters can go to see their comment history, as
|
||||
well as reactions and replies to their comments. They can also see their email
|
||||
address associated with Talk, and manage their Ignored Users list here.
|
||||
|
||||
## Notifications & Error Messaging
|
||||
|
||||
Talk leverages notification and messages on the stream to alert users to
|
||||
important information about their comment or their account.
|
||||
|
||||
### Pre-moderation of comments
|
||||
|
||||
If a stream is set to Pre-mod, or a commenter’s Trust karma score has fallen to
|
||||
negative, or if for any other reason their comment is being pre-moderated, they
|
||||
will get a notification letting them know this when they post a comment.
|
||||
|
||||
### Suspension because of Username
|
||||
|
||||
When a commenter has been suspended because their username is inappropriate,
|
||||
they will see a message at the top of their streams stating this.
|
||||
|
||||
### Timed Suspension
|
||||
|
||||
When a commenter has been suspended for a block of time (aka a “time-out”), they
|
||||
will see a message at the top of their streams stating this.
|
||||
|
||||
### Ban
|
||||
|
||||
When a commenter has been banned, they will see a message at the top of their
|
||||
streams stating this.
|
||||
@@ -0,0 +1,183 @@
|
||||
---
|
||||
title: Moderator Features
|
||||
permalink: /moderator-features/
|
||||
---
|
||||
|
||||
## The Talk Admin
|
||||
|
||||
The Admin is your moderators will moderate your comments, and your Admins will
|
||||
configure and manage the different parts of Talk.
|
||||
|
||||
### Moderate
|
||||
|
||||
This is the tab where Moderators will spend the majority of their time. They can
|
||||
choose (via the dropdown) which story they would like to moderate, or moderate
|
||||
site-wide.
|
||||
|
||||
#### Default Mod Queues
|
||||
|
||||
**New**
|
||||
|
||||
The New queue contains all comments that have not been moderated yet.
|
||||
|
||||
**Reported**
|
||||
|
||||
The Reported queue contains all comments that need moderator attention.
|
||||
|
||||
**Approved**
|
||||
|
||||
The Approved queue contains all approved comments.
|
||||
|
||||
**Rejected**
|
||||
|
||||
The Rejected queue contains all comments that have been rejected, either
|
||||
manually by moderators or automatically, e.g. they have used a banned word.
|
||||
|
||||
**All**
|
||||
|
||||
The All queue contains all comments that have been submitted either article or
|
||||
site-wide.
|
||||
|
||||
#### Moderation Badges
|
||||
|
||||
**Pre-mod**
|
||||
|
||||
The Pre-mod badge signifies comments that are being pre-modded.
|
||||
|
||||
**User**
|
||||
|
||||
The User badge signifies comments that have been reported by another user.
|
||||
|
||||
**History**
|
||||
|
||||
The History badge signifies comments that have been flagged because of a user’s
|
||||
history.
|
||||
|
||||
**Toxic**
|
||||
|
||||
The Toxic badge signifies comments that are above the set Toxicity Probability
|
||||
Threshold. Note you must have [talk-plugin-toxic-comments](./additional-plugins/#talk-plugin-toxic-comments) enabled.
|
||||
[Read more about Toxic Comments here](./toxic-comments/).
|
||||
|
||||
**Suspect**
|
||||
|
||||
The Suspect badge signifies comments that contain a Suspect Word.
|
||||
|
||||
**Contains Link**
|
||||
|
||||
The Contains Link badge signifies a comment that contains a link, which can
|
||||
sometimes mean it is a spam or ad comment.
|
||||
|
||||
**Flag Details View**
|
||||
|
||||
At the bottom of each comment in the moderation queues, you can see more
|
||||
information about a comment’s flags by clicking on More Detail.
|
||||
|
||||
#### Moderator Actions
|
||||
|
||||
**Accept**
|
||||
|
||||
Accepting a comment ensures that the comment is displayed on the stream.
|
||||
|
||||
**Reject**
|
||||
|
||||
Rejecting a comment removes the comment from the stream.
|
||||
|
||||
**Feature**
|
||||
|
||||
Featuring a comment adds that comment to the Featured Comments tab on the
|
||||
stream.
|
||||
|
||||
**Suspend User**
|
||||
|
||||
Suspending a user allows a moderator to give a commenter a “time-out”; during
|
||||
that time they won’t be allowed to post comments or react to comments.
|
||||
|
||||
**Ban User**
|
||||
|
||||
Banning a user allows a moderator to permanently disallow a commenter to
|
||||
interact with their community. The commenters previous comments will remain on
|
||||
the site. This action can only be un-done manually by a moderator.
|
||||
|
||||
#### Viewing a User’s Comment History
|
||||
|
||||
In order to get an idea of what sort of a commenter someone is, moderators can
|
||||
click on the commenters username in any moderation queue and see details about
|
||||
their history.
|
||||
|
||||
**Username, Email and Member Since Date**
|
||||
|
||||
This shows the basic details about a commenter.
|
||||
|
||||
**Total Comments**
|
||||
|
||||
This shows the number of comments that a commenter has made that currently
|
||||
display on the site.
|
||||
|
||||
**Reject Rate**
|
||||
|
||||
This shows the % of comments a commenter has had rejected by moderators, or
|
||||
automatically.
|
||||
|
||||
**Reports**
|
||||
|
||||
This shows if a commenter is a reliable flagger, an unreliable flagger, or a
|
||||
neutral flagger. [Read more about reliable and unreliable flaggers here](./trust/#reliable-and-unreliable-flaggers).
|
||||
|
||||
**Moderating from this View**
|
||||
|
||||
Talk also allows you to moderate a commenters recent comments from this view.
|
||||
|
||||
#### Keyboard Shortcuts
|
||||
|
||||
Talk also supports a number of keyboard shortcuts that moderators can leverage
|
||||
to moderate quickly:
|
||||
|
||||
| Shortcut | Action |
|
||||
| -------- | -------------------------- |
|
||||
| `j` | Go to the next comment |
|
||||
| `k` | Go to the previous comment |
|
||||
| `ctrl+f` | Open search |
|
||||
| `t` | Switch queues |
|
||||
| `z` | Zen mode |
|
||||
| `?` | Open this menu |
|
||||
| `d` | Approve |
|
||||
| `f` | Reject |
|
||||
|
||||
Note: "Zen mode" allows a moderator to view and action only one comment at a time. Enjoy the silence!
|
||||
|
||||
### Stories
|
||||
|
||||
In the Stories tab moderators can view all the stories that have Talk comments
|
||||
embedded on them, as well as be able to Open or Close comment streams on
|
||||
stories.
|
||||
|
||||
### Community
|
||||
|
||||
The Community tab houses everything having to do with your team and your
|
||||
commenters.
|
||||
|
||||
#### Moderating Usernames
|
||||
|
||||
Any usernames that have been reported will show in the Reported Usernames
|
||||
sub-tab. Moderators can approve usernames if they’re suitable, or reject a
|
||||
username. If a username is rejected, the commenter will be notified that they
|
||||
need to change their username; until they do, they will be suspended from Talk.
|
||||
The updated username then again appears in this queue for a decision by
|
||||
moderators.
|
||||
|
||||
#### Managing People & Roles
|
||||
|
||||
All your team and commenters show in the People sub-tab. From here, you can
|
||||
manage your team members’ roles (Admins, Moderators, Staff), as well as search
|
||||
for commenters and take action on them (e.g. Ban/Un-ban, Suspend, etc.). ###
|
||||
Configure
|
||||
|
||||
See [Configuring Talk](./configuring-talk/).
|
||||
|
||||
## Moderating via the Comment Stream
|
||||
|
||||
Moderators can also choose to moderate comments in situ. If you are logged in as
|
||||
a Moderator or Admin, you will see a caret dropdown on each comment that allows
|
||||
you to Approve, Reject, or Feature comments, or Ban a User directly from the
|
||||
comment stream.
|
||||
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Trust
|
||||
permalink: /trust/
|
||||
---
|
||||
|
||||
Trust is a set of components within Talk that incorporate automated moderation
|
||||
features based on a user's previous behavior.
|
||||
|
||||
## User Karma Score
|
||||
|
||||
Using Trust’s calculations, Talk will automatically pre-moderate comments of
|
||||
users who have a negative karma score. All users start out with a `0` neutral
|
||||
karma score. If they have a comment approved by a moderator, their score
|
||||
increases by `1`; if they have a comment rejected by a moderator, it decreases
|
||||
by `1`. When a commenter is labeled as Unreliable, their comments must be
|
||||
moderated before they are posted.
|
||||
|
||||
When a commenter has one comment rejected, their next comment must be 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.
|
||||
|
||||
Here are the default thresholds:
|
||||
|
||||
```text
|
||||
-2 and lower: Unreliable
|
||||
-1 to +2: Neutral
|
||||
+3 and higher: Reliable
|
||||
```
|
||||
|
||||
You can configure your own Trust thresholds by using [TRUST_THRESHOLD](./advanced-configuration/#trust_thresholds) in your
|
||||
configuration.
|
||||
|
||||
|
||||
## Reliable and Unreliable Flaggers
|
||||
|
||||
Trust also calculates how reliable users are in terms of the comments they
|
||||
report. This information is displayed to moderators in the User History drawer,
|
||||
which is accessed by clicking on a user’s name in the Admin.
|
||||
|
||||
If a user's reports mostly match what moderators reject, their Report status
|
||||
will display to moderators as Reliable in the user information drawer. If a
|
||||
user's reports mostly differ from what moderators reject, their Report status
|
||||
will show as Unreliable.
|
||||
|
||||
If we don't have enough reports to make a call, or the reports even out, their
|
||||
status is Neutral.
|
||||
|
||||
Note: Report Karma doesn't include reports of "I don't agree with this comment".
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
title: Toxic Comments
|
||||
permalink: /toxic-comments/
|
||||
---
|
||||
|
||||
Leveraging Google's Perspective API, you can now set a Toxicity Threshold for
|
||||
Talk (0.8 or 80% is the default), which works like this:
|
||||
|
||||
- If a comment exceeds the threshold, the commenter is warned that their comment
|
||||
may be toxic, and are given the chance to modify their comment before posting
|
||||
- If the revised comment is below the Toxicity Threshold, it is posted and
|
||||
displayed normally
|
||||
- If the revised comment still exceeds the Toxicity Threshold, it is not
|
||||
displayed on the stream and instead is sent to the Reported queue for
|
||||
moderation
|
||||
- If the moderator accepts the comment, it's displayed on the stream; if it's
|
||||
rejected, it will not be displayed
|
||||
- Moderators see a Toxic Probability Score on toxic comments in the Moderation
|
||||
queues
|
||||
|
||||
Read more about Coral’s take on toxicity
|
||||
[on our blog](https://blog.coralproject.net/toxic-avenging/).
|
||||
|
||||
## What is the Perspective API?
|
||||
|
||||
The likely toxicity of a comment is evaluated using scores generated from
|
||||
[Perspective API](http://perspectiveapi.com/). This is part of
|
||||
the [Conversation AI](https://conversationai.github.io/)
|
||||
research effort run by Jigsaw (a section of Google that works on global problems
|
||||
around speech and access to information).
|
||||
|
||||
Perspective API uses machine learning, based on existing databases of
|
||||
accepted/rejected comments, to guess the probability that a comment is abusive
|
||||
and/or toxic. It is currently English only, but the system is designed to work
|
||||
with multiple languages.
|
||||
|
||||
In order to activate our plugin, each news organization applies for an API key
|
||||
from Jigsaw (click “Request API access” on this site.) Sites can also work with
|
||||
Jigsaw to create an individualized data set specifically trained on their own
|
||||
comment history.
|
||||
|
||||
Perspective API was released earlier this year, and is currently in alpha
|
||||
(meaning that it is being continually refined and improved.) Jigsaw should
|
||||
certainly be praised for devoting serious resources to this issue, and making
|
||||
their work available for others, including us, to use.
|
||||
|
||||
We’ve talked with their team on several occasions, and have been impressed by
|
||||
their dedication and commitment to this issue. These are smart people who are
|
||||
trying to improve a broken part of the internet.
|
||||
|
||||
## How do I add the Toxic Comments plugin?
|
||||
To enable this behavior, visit the
|
||||
[talk-plugin-toxic-comments](./additional-plugins/#talk-plugin-toxic-comments)
|
||||
plugin documentation.
|
||||
|
||||
|
||||
## Request an API Key
|
||||
|
||||
You can read more about Google's Perspective API and/or request an API key here: [http://perspectiveapi.com/](http://perspectiveapi.com/).
|
||||
@@ -0,0 +1,101 @@
|
||||
---
|
||||
title: Configuring Talk
|
||||
permalink: /configuring-talk/
|
||||
---
|
||||
|
||||
## Configuring an Individual Stream
|
||||
|
||||
There are two ways Admins can configure Talk - the first is via the Configure
|
||||
tab on the comment stream.
|
||||
|
||||
### Enable Pre-moderation
|
||||
|
||||
Allows toggling pre-moderation for the current comment stream.
|
||||
|
||||
### Pre-moderation Comments Containing Links
|
||||
|
||||
Allows toggling of pre-moderating comments that have links.
|
||||
|
||||
### Ask Readers a Question & Question Icons
|
||||
|
||||
Admins can choose to Ask Readers a Question in order to help guide the
|
||||
discussion. [Read more about why this is important on our blog](https://blog.coralproject.net/the-empty-box/).
|
||||
|
||||
There are a selection of icons to display different messaging other than a
|
||||
question on a particular stream, like an announcement, or general information
|
||||
about the story.
|
||||
|
||||
### Closing a Stream
|
||||
|
||||
Closing a stream will prevent new comments. Previous comments will remain
|
||||
displayed on the stream for readers to view.
|
||||
|
||||
|
||||
## Global Configuration
|
||||
|
||||
Global configuration settings are available via Admin > Configure. These
|
||||
settings are site-wide and will affect all of your comment streams.
|
||||
|
||||
### Stream Settings
|
||||
|
||||
#### Limit Comment Length
|
||||
|
||||
A maximum comment length across the site.
|
||||
|
||||
#### Comment Stream Description
|
||||
|
||||
Description text that will appear above every comment stream site-wide. We
|
||||
recommend linking to your Code of Conduct or Community Guidelines. [Read tips on how to write a Code of Conduct here](https://guides.coralproject.net/create-a-code-of-conduct/).
|
||||
|
||||
#### Closed Stream Message
|
||||
|
||||
A message that will display when streams are closed.
|
||||
|
||||
#### Edit Comment Timeframe
|
||||
|
||||
The timeframe in seconds in which commenters have to edit their comment.
|
||||
|
||||
#### Close Comments After
|
||||
|
||||
Default time after which all comment streams will close.
|
||||
|
||||
### Moderation Settings
|
||||
|
||||
#### Require Email Verification
|
||||
|
||||
Require new users to verify their email address prior to commenting.
|
||||
|
||||
#### Enable Pre-moderation
|
||||
|
||||
Turn on pre-moderation across the site, meaning all comments will need to be
|
||||
moderated before they will be displayed.
|
||||
|
||||
#### Pre-moderate Comments Containing Links
|
||||
|
||||
Turn on pre-moderation for comments with links across the site, meaning all
|
||||
comments with links will need to be moderated before they will be displayed.
|
||||
|
||||
#### Banned Words List
|
||||
|
||||
A list of words that will trigger a comment to be automatically Rejected.
|
||||
|
||||
#### Suspect Words List
|
||||
|
||||
A list of words that will trigger a comment to be automatically Reported.
|
||||
Comments with suspect words will display until a moderator takes action on them.
|
||||
|
||||
### Technical Settings
|
||||
|
||||
#### Permitted Domains
|
||||
|
||||
A list of domains where your Talk instance is allowed to be embedded. Typical
|
||||
use is `localhost`, `staging.yourdomain.com`, `yourdomain.com`, etc.
|
||||
|
||||
#### Embed Script
|
||||
|
||||
This is the unique Talk script that is to be used to embed Talk on your website.
|
||||
|
||||
#### Custom CSS URL
|
||||
|
||||
The link to your custom stylesheet for Talk. This will override any default
|
||||
styles, so you can make Talk your own!
|
||||
@@ -0,0 +1,118 @@
|
||||
---
|
||||
title: Plugins Overview
|
||||
permalink: /plugins/
|
||||
---
|
||||
|
||||
Plugins are the integration point between the Talk core code and custom
|
||||
functionality. We provide methods to inject behavior into the server side and
|
||||
the client side application to affect different parts of the application
|
||||
life cycle.
|
||||
|
||||
## Recipes
|
||||
|
||||
Recipes are plugin templates provided by the Coral Core team. Developers can use
|
||||
these recipes to build their own plugins. You can find all the Talk recipes
|
||||
here: [github.com/coralproject/talk-recipes](https://github.com/coralproject/talk-recipes/).
|
||||
|
||||
## Plugin Registration
|
||||
|
||||
In order for a plugin to be active in a Talk install, it must be _registered_.
|
||||
The parsing order for the plugin registration is as follows:
|
||||
|
||||
- `TALK_PLUGINS_JSON` environment variable
|
||||
- `plugins.json` file
|
||||
- `plugins.default.json` file
|
||||
|
||||
If you need to "disable all plugins", you can simply provide `{}` as the
|
||||
contents of `TALK_PLUGINS_JSON` or the `plugins.json`.
|
||||
|
||||
The format for this is thus:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
"people"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Where we have a `server` key with an array of plugins that match the folder
|
||||
name in the `plugins/` folder. For example, the above config would
|
||||
require a plugin from `plugins/people`, which must provide a `index.js` file
|
||||
that returns an object that matches the Plugin Specification.
|
||||
|
||||
If the package is external (available on NPM) you can specify the string for
|
||||
the version by using an object instead, for example:
|
||||
|
||||
```json
|
||||
{
|
||||
"server": [
|
||||
{"people": "^1.2.0"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
External plugins can be resolved by running:
|
||||
|
||||
```bash
|
||||
./bin/cli plugins reconcile
|
||||
```
|
||||
|
||||
This achieves two things:
|
||||
|
||||
1. It will traverse into local plugin folders and install their dependencies.
|
||||
_Note that if the plugin is already installed and available in the
|
||||
node_modules folder, it will not be fetched again unless there is a version
|
||||
mismatch._ This will result in the project `package.json` and `yarn.lock`
|
||||
files to be modified, this is normal as this ensures that repeated deployments
|
||||
(with the same config) will have the same config, these changes should not be
|
||||
committed to source control.
|
||||
2. It will seek out dependencies that are listed in the object notation and try
|
||||
to install them from npm.
|
||||
|
||||
## Plugin Dependencies
|
||||
|
||||
You may also include additional external dependencies in your local packages by
|
||||
specifying a `package.json` at your plugin root which will result in a
|
||||
`node_modules` folder being generated at the plugin root with your specific
|
||||
dependencies.
|
||||
|
||||
## Deployment Solutions
|
||||
|
||||
Plugins can be deployed with a production instance of Talk.
|
||||
|
||||
### Source
|
||||
|
||||
Source deployments can just modify the `plugins.json` file and include any
|
||||
local plugins into the `plugins/` directory. After including the config, you
|
||||
need to reconcile the plugins and build the static assets:
|
||||
|
||||
```bash
|
||||
# get plugin dependencies and remote plugins
|
||||
./bin/cli plugins reconcile
|
||||
|
||||
# build static assets (including enabled client side plugins)
|
||||
yarn build
|
||||
```
|
||||
|
||||
Then the application can be started as is.
|
||||
|
||||
### Docker
|
||||
|
||||
If you deploy using Docker, you can extend from the `*-onbuild` image, an
|
||||
example `Dockerfile` for your project could be:
|
||||
|
||||
```Dockerfile
|
||||
FROM coralproject/talk:latest-onbuild
|
||||
```
|
||||
|
||||
Where the directory for your instance would contain a `plugins.json` file
|
||||
describing the plugin requirements and a `plugins` directory containing any
|
||||
other local plugins that should be included.
|
||||
|
||||
Onbuild triggers will execute when the image is building with your custom
|
||||
configuration and will ensure that the image is ready to use by building all
|
||||
assets inside the image as well.
|
||||
|
||||
For more information on the onbuild image, refer to the
|
||||
[Installation from Docker](./installation-from-docker/) documentation.
|
||||
@@ -0,0 +1,147 @@
|
||||
---
|
||||
title: Default Plugins
|
||||
permalink: /default-plugins/
|
||||
class: configuration
|
||||
---
|
||||
|
||||
The default Talk plugins can be found in the `plugins.default.json` file
|
||||
[here](https://github.com/coralproject/talk/blob/master/plugins.default.json).
|
||||
Talk ships out of the box with these plugins enabled.
|
||||
|
||||
We ship [Additional Plugins](./additional-plugins/) with
|
||||
Talk that are not enabled by default. You can enable these or disable these
|
||||
default plugins by consulting the [Plugins Overview](./plugins/)
|
||||
page.
|
||||
|
||||
## talk-plugin-auth
|
||||
|
||||
Source: [plugins/talk-plugin-auth](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-auth)
|
||||
|
||||
Enables generic registration via an email address, a username, a password, and a
|
||||
password confirmation. To sync Talk auth with your own auth systems, you can use
|
||||
this plugin as a template.
|
||||
|
||||
## talk-plugin-facebook-auth
|
||||
|
||||
Source: [plugins/talk-plugin-auth](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-auth)
|
||||
|
||||
Requires: [talk-plugin-facebook-auth](#talk-plugin-facebook-auth)
|
||||
|
||||
Enables sign-in via Facebook via the server side passport middleware.
|
||||
|
||||
Configuration:
|
||||
|
||||
- [TALK_FACEBOOK_APP_ID](./configuration/#talk_facebook_app_id) (**required**) - See the existing documentation for the [TALK_FACEBOOK_APP_ID](./configuration/#talk_facebook_app_id).
|
||||
- [TALK_FACEBOOK_APP_SECRET](./configuration/#talk_facebook_app_secret) (**required**) - See the existing documentation for the [TALK_FACEBOOK_APP_SECRET](./configuration/#talk_facebook_app_secret).
|
||||
|
||||
## talk-plugin-featured-comments
|
||||
|
||||
Source: [plugins/talk-plugin-featured-comments](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-featured-comments)
|
||||
|
||||
Enables the ability for Moderators to feature and un-feature comments via the
|
||||
Stream and the Admin. Featured comments show in a first-place tab on the Stream
|
||||
if there are any featured comments on that story.
|
||||
|
||||
## talk-plugin-respect
|
||||
|
||||
Source: [plugins/talk-plugin-respect](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-respect)
|
||||
|
||||
Enables a `respect` reaction button. Why a "respect" button, you ask?
|
||||
[Read more here](https://mediaengagement.org/research/engagement-buttons/).
|
||||
|
||||
## talk-plugin-comment-content
|
||||
|
||||
Source: [plugins/talk-plugin-comment-content](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-comment-content)
|
||||
|
||||
Pluginizes the text of a comment to support custom treatment of this text. This
|
||||
plugin currently parses the given text to see if it contains a link, and makes
|
||||
them clickable.
|
||||
|
||||
## talk-plugin-ignore-user
|
||||
|
||||
Source: [plugins/talk-plugin-ignore-user](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-ignore-user)
|
||||
|
||||
Enables ability for users to ignore (or "mute") other users. If a user is
|
||||
ignored, you will not see any of their comments. You can un-ignore a user via
|
||||
the My Profile tab.
|
||||
|
||||
## talk-plugin-permalink
|
||||
|
||||
Source: [plugins/talk-plugin-permalink](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-permalink)
|
||||
|
||||
Enables a `Link` button that will provide a permalink to the comment that can be
|
||||
shared with others.
|
||||
|
||||
## talk-plugin-viewing-options
|
||||
|
||||
Source: [plugins/talk-plugin-viewing-options](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-viewing-options)
|
||||
|
||||
Pluginizes the sorting/viewing options for a comment stream.
|
||||
|
||||
## talk-plugin-sort-newest
|
||||
|
||||
Source: [plugins/talk-plugin-sort-newest](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-newest)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options)
|
||||
|
||||
Provides a sort for the newest comments first. This isn't necessarily required
|
||||
as the default sort without options/plugins is newest first.
|
||||
|
||||
## talk-plugin-sort-oldest
|
||||
|
||||
Source: [plugins/talk-plugin-sort-oldest](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-oldest)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options)
|
||||
|
||||
Provides a sort for the newest comments first.
|
||||
|
||||
## talk-plugin-sort-most-respected
|
||||
|
||||
Source: [plugins/talk-plugin-sort-most-respected](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-respected)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options), [talk-plugin-respect](#talk-plugin-respect)
|
||||
|
||||
Provides a sort for the comments with the most `respect` reactions first.
|
||||
|
||||
## talk-plugin-sort-most-replied
|
||||
|
||||
Source: [plugins/talk-plugin-sort-most-replied](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-replied)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](#talk-plugin-viewing-options)
|
||||
|
||||
Provides a sort for the comments with the most replies first.
|
||||
|
||||
## talk-plugin-offtopic
|
||||
|
||||
Source: [plugins/talk-plugin-offtopic](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-offtopic)
|
||||
|
||||
Allows the comment authors to tag their comment as `Off-Topic` which will add a
|
||||
visible badge on the frontend to other users that their comment is off-topic.
|
||||
|
||||
## talk-plugin-author-menu
|
||||
|
||||
Source: [plugins/talk-plugin-author-menu](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-author-menu)
|
||||
|
||||
Pluginizes the author's name on hover.
|
||||
|
||||
## talk-plugin-member-since
|
||||
|
||||
Source: [plugins/talk-plugin-member-since](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-member-since)
|
||||
|
||||
Requires: [talk-plugin-author-menu](#talk-plugin-author-menu)
|
||||
|
||||
Displays the date that the user was created as a `Member Since ${created_at}`.
|
||||
|
||||
## talk-plugin-moderation-actions
|
||||
|
||||
Source: [plugins/talk-plugin-moderation-actions](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-moderation-actions)
|
||||
|
||||
Enables in-stream moderation so that Moderators can reject, approve comments,
|
||||
as well as ban users, directly from the comment stream. When [talk-plugin-featured-comments](#talk-plugin-featured-comments) is enabled
|
||||
|
||||
## talk-plugin-flag-details
|
||||
|
||||
Source: [plugins/talk-plugin-flag-details](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-flag-details)
|
||||
|
||||
Pluginizes the Flag Details area of comments in the Moderation Queues to display
|
||||
data. Some basic details are already included on flags by default.
|
||||
@@ -0,0 +1,117 @@
|
||||
---
|
||||
title: Additional Plugins
|
||||
permalink: /additional-plugins/
|
||||
class: configuration
|
||||
---
|
||||
|
||||
Talk ships with several plugins that aren't enabled by default. These plugins
|
||||
can be enabled by consulting the [Plugins Overview](./plugins/)
|
||||
page.
|
||||
|
||||
## talk-plugin-like
|
||||
|
||||
Source: [plugins/talk-plugin-like](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-like)
|
||||
|
||||
Enables a `like` reaction button.
|
||||
|
||||
## talk-plugin-sort-most-liked
|
||||
|
||||
Source: [plugins/talk-plugin-sort-most-liked](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-liked)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](./default-plugins/#talk-plugin-viewing-options), [talk-plugin-like](#talk-plugin-like)
|
||||
|
||||
Provides a sort for the comments with the most `like` reactions first.
|
||||
|
||||
## talk-plugin-love
|
||||
|
||||
Source: [plugins/talk-plugin-love](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-love)
|
||||
|
||||
Enables a `love` reaction button.
|
||||
|
||||
## talk-plugin-sort-most-loved
|
||||
|
||||
Source: [plugins/talk-plugin-sort-most-loved](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-sort-most-loved)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](./default-plugins/#talk-plugin-viewing-options), [talk-plugin-love](#talk-plugin-love)
|
||||
|
||||
Provides a sort for the comments with the most `love` reactions first.
|
||||
|
||||
## talk-plugin-remember-sort
|
||||
|
||||
Source: [plugins/talk-plugin-remember-sort](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-remember-sort)
|
||||
|
||||
Requires: [talk-plugin-viewing-options](./default-plugins/#talk-plugin-viewing-options)
|
||||
|
||||
Enables saving a user’s last sort selection as they browse other articles.
|
||||
|
||||
## talk-plugin-deep-reply-count
|
||||
|
||||
Source: [plugins/talk-plugin-deep-reply-count](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-deep-reply-count)
|
||||
|
||||
Enables counting of comments to include replies via a new graph edge. Not
|
||||
recommended for large installations as it will unreasonably reduce the query
|
||||
efficiency to compute this number.
|
||||
|
||||
## talk-plugin-slack-notifications
|
||||
|
||||
Source: [plugins/talk-plugin-slack-notifications](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-slack-notifications)
|
||||
|
||||
Enables all new comments that are written to be posted to a Slack channel as
|
||||
well. Configure an
|
||||
[Incoming Webhook](https://api.slack.com/incoming-webhooks)
|
||||
app and provide that url in the form of the `SLACK_WEBHOOK_URL`
|
||||
detailed below.
|
||||
|
||||
*Warning: On high volume sites, this means every single comment will flow into
|
||||
Slack, if this isn't what you want, be sure to use the provided plugin as a
|
||||
recipe to further customize the behavior*.
|
||||
|
||||
Configuration:
|
||||
|
||||
- `SLACK_WEBHOOK_URL` (**required**) - The webhook url that will be
|
||||
used to post new comments to.
|
||||
|
||||
## talk-plugin-toxic-comments
|
||||
|
||||
Source: [plugins/talk-plugin-toxic-comments](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-toxic-comments)
|
||||
|
||||
Using the [Perspective API](http://perspectiveapi.com/), this
|
||||
plugin will warn users and reject comments that exceed the predefined toxicity
|
||||
threshold. For more information on what Toxic Comments are, check out the
|
||||
[Toxic Comments](./toxic-comments/) documentation.
|
||||
|
||||
Configuration:
|
||||
|
||||
- `TALK_PERSPECTIVE_API_KEY` (**required**) - The API Key for Perspective. You
|
||||
can register and get your own key at [http://perspectiveapi.com/](http://perspectiveapi.com/).
|
||||
- `TALK_TOXICITY_THRESHOLD` - If the comments toxicity exceeds this threshold,
|
||||
the comment will be rejected. (Default `0.8`)
|
||||
- `TALK_PERSPECTIVE_API_ENDPOINT` - API Endpoint for hitting the
|
||||
perspective API. (Default `https://commentanalyzer.googleapis.com/v1alpha1`)
|
||||
- `TALK_PERSPECTIVE_TIMEOUT` - The timeout for sending a comment to
|
||||
be processed before it will skip the toxicity analysis, parsed by
|
||||
[ms](https://www.npmjs.com/package/ms). (Default `300ms`)
|
||||
- `TALK_PERSPECTIVE_DO_NOT_STORE` - Whether the API is permitted to store comment and context from this request. Stored comments will be used for future research and community model building purposes to improve the API over time. (Default `true`) [Perspective API - Analize Comment Request](https://github.com/conversationai/perspectiveapi/blob/master/api_reference.md#analyzecomment-request)
|
||||
|
||||
## talk-plugin-subscriber
|
||||
|
||||
Source: [plugins/talk-plugin-subscriber](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-subscriber)
|
||||
|
||||
Enables a `Subscriber` badge to be added to comments where the author has the
|
||||
`SUBSCRIBER` tag. This must match with a custom auth integration that adds the
|
||||
tag to the users that are subscribed to the service.
|
||||
|
||||
## talk-plugin-akismet
|
||||
|
||||
Source: [plugins/talk-plugin-akismet](https://github.com/coralproject/talk/tree/master/plugins/talk-plugin-akismet)
|
||||
|
||||
Enables spam detection from [Akismet](https://akismet.com/). Comments will be passed to the Akismet API for spam detection. If a comment
|
||||
is determined to be spam, it will prompt the user, indicating that the comment might be considered spam. If the user continues after this
|
||||
point with the still spam-like comment, the comment will be reported as containing spam, and sent for moderator approval.
|
||||
|
||||
**Note: [Akismet](https://akismet.com/) is a premium service, charges may apply.**
|
||||
|
||||
Configuration:
|
||||
|
||||
- `TALK_AKISMET_API_KEY` (**required**) - The Akismet API key located on your account page.
|
||||
- `TALK_AKISMET_SITE` (**required**) - The URL where you are embedding the comment stream on to provide context to Akismet. If you're hosting talk on https://talk.mynews.org/, and your news site is https://mynews.org/, then you should set this parameter to `https://mynews.org/`
|
||||
@@ -0,0 +1,48 @@
|
||||
---
|
||||
title: Plugin Recipes
|
||||
permalink: /plugin-recipes/
|
||||
class: configuration
|
||||
---
|
||||
|
||||
Plugin Recipes are plugin templates used to help bootstrap the development of a
|
||||
plugin. Recipes are available at the
|
||||
[coralproject/talk-recipes](https://github.com/coralproject/talk-recipes) repo.
|
||||
When first developing a plugin with a recipe, you can simply visit the
|
||||
aforementioned repository to find the desired recipe, and using the file
|
||||
listings on the page, determine which files need to be modified to suit your
|
||||
needs.
|
||||
|
||||
The following are the available recipes for use:
|
||||
|
||||
## recipe-avatar
|
||||
|
||||
Source: [talk-recipes/tree/master/plugins/avatar](https://github.com/coralproject/talk-recipes/tree/master/plugins/avatar)
|
||||
|
||||
Provides support for avatars hosted via third party, extends the User Model and
|
||||
provides UI on the client-side too.
|
||||
|
||||
|
||||
## recipe-translations
|
||||
|
||||
Source: [talk-recipes/tree/master/plugins/translations](https://github.com/coralproject/talk-recipes/tree/master/plugins/translations)
|
||||
|
||||
Provides an example for overriding application text through the translation
|
||||
system.
|
||||
|
||||
|
||||
## recipe-subscriber
|
||||
|
||||
Source: [talk-recipes/tree/master/plugins/subscriber](https://github.com/coralproject/talk-recipes/tree/master/plugins/subscriber)
|
||||
|
||||
Provides an example for adding `SUBSCRIBER` badges for users with the
|
||||
`SUBSCRIBER` tag added to their user model through a direct server plugin with
|
||||
the auth system.
|
||||
|
||||
|
||||
## recipe-author-name
|
||||
|
||||
Source: [talk-recipes/tree/master/plugins/author-name](https://github.com/coralproject/talk-recipes/tree/master/plugins/author-name)
|
||||
|
||||
Enables the ability to hover over a commenter’s name and add plugin
|
||||
functionality there. The Member Since plugin that is provided in this recipe is
|
||||
an example of this.
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: FAQ
|
||||
permalink: /faq/
|
||||
---
|
||||
|
||||
## How can I get help integrating Talk into my newsroom?
|
||||
|
||||
We're here to help with newsrooms of all sizes. Email our Integration Engineer
|
||||
([jeff@mozillafoundation.org](mailto:jeff@mozillafoundation.org)) to set up a meeting.
|
||||
|
||||
## How do I request a feature or submit a bug?
|
||||
|
||||
The best way is to [submit a Github issue](https://github.com/coralproject/talk/issues). Make sure you give plenty of details, our Core Team can usually respond within a few hours on weekdays.
|
||||
|
||||
## How can our dev team contribute to Talk?
|
||||
|
||||
We are lucky to work with newsroom dev teams and individual contributors who span the world, and come from newsrooms of all sizes. You can read our [Contribution Guide](https://github.com/coralproject/talk/blob/master/CONTRIBUTING.md) to get started, but feel free to reach out to us via Github, or get in touch directly with Jeff via jeff@mozillafoundation.org.
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Migrating to v4.1.0
|
||||
permalink: /migration/4.1/
|
||||
---
|
||||
|
||||
## Database Migrations
|
||||
|
||||
We have unified the database verifications that were introduced in 3.x.x into
|
||||
the migration system. This unification unfortunately required a database
|
||||
migration bump.
|
||||
|
||||
### Source
|
||||
|
||||
When running via source, you can run the following to start the migration
|
||||
process:
|
||||
|
||||
```bash
|
||||
./bin/cli migration run
|
||||
```
|
||||
This will prompt you to perform a database backup before starting the migration
|
||||
process. Data loss is entirely possible otherwise.
|
||||
|
||||
|
||||
### Docker Compose
|
||||
|
||||
If you are running Talk with docker-compose, you can use the following command
|
||||
to perform the migration:
|
||||
|
||||
```bash
|
||||
docker-compose run --rm talk cli migration run
|
||||
```
|
||||
This will prompt you to perform a database backup before starting the migration
|
||||
process. Data loss is entirely possible otherwise.
|
||||
|
||||
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: Migrating to v4.0.0
|
||||
permalink: /migration/4/
|
||||
---
|
||||
|
||||
Since our `v3.*` release, this is the most significant set of changes introduced
|
||||
into Talk so far, as a major database migration and template change are both required to
|
||||
run it.
|
||||
|
||||
## Dependencies
|
||||
|
||||
If you are running via source, once you update your code, it's always important
|
||||
to run the following in order to update your dependencies:
|
||||
|
||||
```bash
|
||||
yarn
|
||||
```
|
||||
|
||||
If you are running via Docker, you just have to replace your version number with
|
||||
the desired version from Dockerhub.
|
||||
|
||||
## Database Migrations
|
||||
|
||||
We have introduced several new fields that require the database to be modified.
|
||||
To run these migrations, ensure that all nodes of Talk are stopped. It is not
|
||||
well defined what will happen if a Talk application begins writing data mid
|
||||
migration.
|
||||
|
||||
Running the following will start the migration process:
|
||||
|
||||
```bash
|
||||
./bin/cli migration run
|
||||
```
|
||||
This will prompt you to perform a database backup before starting the migration
|
||||
process. Data loss is entirely possible otherwise.
|
||||
|
||||
|
||||
The migration itself may take some time to complete, as we're reformatting
|
||||
documents rather than performing a nice table alter. If the process crashes
|
||||
during the migration, simply re-run it. The migration operations are designed
|
||||
to act atomically, and be idempotent to documents already updated.
|
||||
|
||||
## Template Change
|
||||
|
||||
In `v4.0.0`, we introduced extensive support for compressing our javascript
|
||||
bundles. To support this, we had to modify our routing. All static files are now
|
||||
served out of a `/static` prefix, so you will have to change your embed code:
|
||||
|
||||
**Old:**
|
||||
|
||||
```https://your-talk-url.com/embed.js```
|
||||
|
||||
**New:**
|
||||
|
||||
```https://your-talk-url.com/static/embed.js```
|
||||
|
||||
This should be changed in your embed code on the site where you are embedding
|
||||
Talk.
|
||||
Reference in New Issue
Block a user