mirror of
https://github.com/wassname/talk.git
synced 2026-07-31 12:50:48 +08:00
added base path support for router, spelling fixes
This commit is contained in:
Wyatt Johnson
+52
-17
@@ -5,39 +5,63 @@ permalink: /docs/faq/
|
||||
|
||||
### How are new stories/assets added to Talk? Is there an API?
|
||||
|
||||
There are three ways that new assets can make their way into Talk: _just in time_, _active_ and manual.
|
||||
There are three ways that new assets can make their way into Talk:
|
||||
|
||||
- Just in time
|
||||
- Active
|
||||
- Manual
|
||||
|
||||
#### Just in Time asset creation
|
||||
|
||||
Talk ships with a _just in time_ mechanism that works out of the box without integration with any CMS or manual work needed.
|
||||
Talk ships with a _just in time_ mechanism that works out of the box without
|
||||
integration with any CMS or manual work needed.
|
||||
|
||||
The _just in time_ flow looks like this:
|
||||
|
||||
* Request comes in for a stream on an asset that doesn't yet exist.
|
||||
* Talk screens the domain against the domain whitelist, fails if doesn't pass.
|
||||
* Then, concurrently
|
||||
* Talk creates a new asset record and returns the stream data (which will be empty)
|
||||
* Talk creates a new asset record and returns the stream data (which will be
|
||||
empty)
|
||||
* Schedules a job to scrape the new page and fill in asset information.
|
||||
|
||||
The scraping mechanism utilizes [metascraper](https://www.npmjs.com/package/metascraper) and is queued using the [Que](https://www.npmjs.com/package/kue). If your Talk deployments is configured to run separate job worker cluster, scraping will be performed by them.
|
||||
The scraping mechanism utilizes
|
||||
[metascraper](https://www.npmjs.com/package/metascraper) and is queued using the
|
||||
[Que](https://www.npmjs.com/package/kue). If your Talk deployments is configured
|
||||
to run separate job worker cluster, scraping will be performed by them.
|
||||
|
||||
#### Active (or push based) asset creation
|
||||
|
||||
If tighter CMS integration is required to push custom data into assets and/or keep data in sync as changes are made in a CMS an _active_ push based workflow must be implemented.
|
||||
If tighter CMS integration is required to push custom data into assets and/or
|
||||
keep data in sync as changes are made in a CMS an _active_ push based workflow
|
||||
must be implemented.
|
||||
|
||||
This is an ideal candidate for a plugin. If you are interested in working on it, please [contact us](https://coralproject.net/contact)!
|
||||
This is an ideal candidate for a plugin. If you are interested in working on it,
|
||||
please [contact us](https://coralproject.net/contact)!
|
||||
|
||||
#### Manual asset creation
|
||||
|
||||
Sometimes you want to load a lot of assets into the database. The most common use case for this is populating the database during an initial installation. We recommend writing a script that transforms the data from it's source and inserts it into the _assets_ collection.
|
||||
Sometimes you want to load a lot of assets into the database. The most common
|
||||
use case for this is populating the database during an initial installation. We
|
||||
recommend writing a script that transforms the data from it's source and inserts
|
||||
it into the _assets_ collection.
|
||||
|
||||
For current schema information, please see the [asset model](https://github.com/coralproject/talk/blob/master/models/asset.js).
|
||||
For current schema information, please see the
|
||||
[asset model](https://github.com/coralproject/talk/blob/master/models/asset.js).
|
||||
|
||||
### Where are your http API docs?
|
||||
|
||||
Coral relies on GraphQL for the vast majority of it's client <-> server communication. All core queries, mutations and subscriptions are defined along with types and comments in our central [TypeDef](https://github.com/coralproject/talk/blob/master/graph/typeDefs.graphql). For plugin graph api typedefs, see each plugin's `/server/` directory.
|
||||
Coral relies on GraphQL for the vast majority of it's client and server
|
||||
communication. All core queries, mutations and subscriptions are defined along
|
||||
with types and comments in our central
|
||||
[TypeDef](https://github.com/coralproject/talk/blob/master/graph/typeDefs.graphql).
|
||||
For plugin graph api typedefs, see each plugin's `/server/` directory.
|
||||
|
||||
In addition, Talk Server ships with [GraphiQL](https://github.com/graphql/graphiql). GraphiQL provides a full data layer IDE including interactive documentation. The autocompletes and documentation are populated from introspection meaning that Core _and plugin_ apis will be fully explorable.
|
||||
In addition, Talk Server ships with
|
||||
[GraphiQL](https://github.com/graphql/graphiql). GraphiQL provides a full data
|
||||
layer IDE including interactive documentation. The autocomplete and
|
||||
documentation are populated from introspection meaning that Core _and plugin_
|
||||
apis can be explored.
|
||||
|
||||
To access GraphiQL:
|
||||
|
||||
@@ -46,22 +70,33 @@ To access GraphiQL:
|
||||
|
||||
### Where is documentation for a specific component?
|
||||
|
||||
We strive for clear inline documentation across our codebase, but have gaps. Contributions to documentation would be greatly appreciated and is a great way to start contributing to the project!
|
||||
We strive for clear inline documentation across our codebase, but have gaps.
|
||||
Contributions to documentation would be greatly appreciated and is a great way
|
||||
to start contributing to the project!
|
||||
|
||||
If you are considering changing a core component (aka, one that is not in a plugin), you are entering the realm of a core developer. We strongly ask that you reach out the coral team before forking and changing core code. We are glad to help talk through your product need and come up with a strategy for implementing as a plugin, or working with you to extend the plugin API for your use case.
|
||||
If you are considering changing a core component (aka, one that is not in a
|
||||
plugin), you are entering the realm of a core developer. We strongly ask that
|
||||
you reach out the coral team before forking and changing core code. We are glad
|
||||
to help talk through your product need and come up with a strategy for
|
||||
implementing as a plugin, or working with you to extend the plugin API for your
|
||||
use case.
|
||||
|
||||
### How do I contribute to these docs?
|
||||
|
||||
Contributions to the docs are much appreciated and a great way to get involved in the project.
|
||||
Contributions to the docs are much appreciated and a great way to get involved
|
||||
in the project.
|
||||
|
||||
Fork the Talk repo, clone it locally (no need to go through the install from source process), then:
|
||||
Fork the Talk repo, clone it locally (no need to go through the install from
|
||||
source process), then:
|
||||
|
||||
```
|
||||
cd docs
|
||||
docker run --rm --volume=$PWD:/srv/jekyll -p 127.0.0.1:4000:4000 -it jekyll/jekyll:pages jekyll serve
|
||||
```
|
||||
|
||||
You can edit the files in docs with any editor and view the live updates in a browser by hitting From the docs directory.
|
||||
Then visit: [http://127.0.0.1:4000/talk/](http://127.0.0.1:4000/talk/).
|
||||
You can edit the files in docs with any editor and view the live updates in a
|
||||
browser by hitting From the docs directory. Then visit:
|
||||
[http://127.0.0.1:4000/talk/](http://127.0.0.1:4000/talk/).
|
||||
|
||||
Once you've made the changes, file a PR back to the `coralproject/talk` repo.
|
||||
Once you've made the changes, file a PR back to the `coralproject/talk`
|
||||
repository.
|
||||
|
||||
@@ -11,8 +11,9 @@ Available as [coralproject/talk](https://hub.docker.com/r/coralproject/talk/) on
|
||||
|
||||
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.
|
||||
- `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.
|
||||
- `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)**
|
||||
|
||||
@@ -36,7 +36,7 @@ git clone https://github.com/coralproject/talk.git
|
||||
We now have to install the dependencies and build the static assets.
|
||||
|
||||
```bash
|
||||
# Install package dependancies
|
||||
# Install package dependencies
|
||||
yarn
|
||||
|
||||
# Build static files
|
||||
|
||||
@@ -70,7 +70,7 @@ independently. Each variety of process can always have just enough resources.
|
||||
|
||||
An install that heavily utilizes the jobs queue could see delays in http service
|
||||
because of heavy jobs processes and/or delays in the execution of jobs processes
|
||||
due to increased server load as a result of Node's single thread infrustructure.
|
||||
due to increased server load as a result of Node's single thread infrastructure.
|
||||
|
||||
## Deployment Methodologies
|
||||
|
||||
|
||||
@@ -55,11 +55,18 @@ These are only used during the webpack build.
|
||||
### Server
|
||||
|
||||
- `TALK_ROOT_URL` (*required*) - root url of the installed application externally
|
||||
available in the format: `<scheme>://<host>` without the path.
|
||||
available in the format: `<scheme>://<host>:<port?>/<pathname>`.
|
||||
- `TALK_KEEP_ALIVE` (_optional_) - The keepalive timeout that should be used to
|
||||
send keep alive messages through the websocket to keep the socket alive. (Default `30s`)
|
||||
- `TALK_INSTALL_LOCK` (_optional for dynamic setup_) - When `TRUE`, disables the dynamic setup endpoint. (Default `FALSE`)
|
||||
|
||||
#### Advanced
|
||||
|
||||
- `TALK_ROOT_URL_MOUNT_PATH` (_optional_) - 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`)
|
||||
|
||||
### Word Filter
|
||||
|
||||
- `TALK_DISABLE_AUTOFLAG_SUSPECT_WORDS` (_optional_) When `TRUE`, disables flagging of comments that match the suspect word filter. (Default `FALSE`)
|
||||
@@ -110,7 +117,7 @@ will be used:
|
||||
"iss": TALK_JWT_ISSUER, // *optional* if TALK_JWT_DISABLE_ISSUER === 'TRUE', *required* otherwise
|
||||
|
||||
[TALK_JWT_USER_ID_CLAIM]: "<the user id>", // *required* the id of the user
|
||||
// Note, if TALK_JWT_USER_ID_CLAIM contains '.', it will be used to deliniate an object, for example
|
||||
// Note, if TALK_JWT_USER_ID_CLAIM contains '.', it will be used to delineate an object, for example
|
||||
// `user.id` would store it like: `{user: {id}}`
|
||||
}
|
||||
```
|
||||
@@ -135,8 +142,8 @@ will be used:
|
||||
|
||||
### Trust
|
||||
|
||||
Trust can automoderate comments based on user history. By specifying this
|
||||
option, the beheviour can be changed to offer different results.
|
||||
Trust can auto-moderate comments based on user history. By specifying this
|
||||
option, the behavior can be changed to offer different results.
|
||||
|
||||
- `TRUST_THRESHOLDS` (_optional_) - configure the reliability thresholds for
|
||||
flagging and commenting. (Default `comment:-1,-1;flag:-1,-1`)
|
||||
@@ -150,10 +157,10 @@ The form of the environment variable:
|
||||
The default could be read as:
|
||||
|
||||
- When a commenter has one comment rejected, their next comment must be
|
||||
premoderated once in order to post freely again. If they instead get rejected
|
||||
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, beheviour is not attached to the flagging
|
||||
- At the moment of writing, behavior is not attached to the flagging
|
||||
reliability, but it is recorded.
|
||||
|
||||
### Cache
|
||||
|
||||
@@ -67,7 +67,7 @@ for more details.
|
||||
|
||||
## Authentication Types
|
||||
|
||||
Talk also supports two methods of providing authenticationd details.
|
||||
Talk also supports two methods of providing authentication details.
|
||||
|
||||
- Single key: this is used when your secrets do not need to be rotated.
|
||||
- Multiple keys: this is used when you expect to rotate your secrets.
|
||||
|
||||
@@ -32,7 +32,7 @@ It basically consist in having two types of components:
|
||||
### Container Components
|
||||
* __How things work__
|
||||
* They don’t have markup nor styles
|
||||
* They provide data and behaviour to Presentational or Container Components
|
||||
* They provide data and behavior to Presentational or Container Components
|
||||
* They connect via `react-redux`’s `connect()` to the state.
|
||||
* They `mapStateToProps` the state to the Presentational Container.
|
||||
* They `mapDispatchToProps` to send actions to the Presentational Container.
|
||||
|
||||
@@ -82,7 +82,7 @@ need to reconcile the plugins and build the static assets:
|
||||
# get plugin dependancies and remote plugins
|
||||
./bin/cli plugins reconcile
|
||||
|
||||
# build staic assets (including enabled client side plugins)
|
||||
# build static assets (including enabled client side plugins)
|
||||
yarn build
|
||||
```
|
||||
|
||||
|
||||
@@ -236,6 +236,6 @@ Once you've taken this step, anyone can register your plugin into their Talk ser
|
||||
|
||||
### Publish to version control
|
||||
|
||||
This plugin is open source, so I'm also going to [publish it to github](https://github.com/jde/talk-plugin-asset-manager/commit/66b626caa85cb8030b3ddaa7c1a4821bf01e350a) and [cut a release](https://github.com/jde/talk-plugin-asset-manager/releases/tag/v0.1) that mirrors the npm relese.
|
||||
This plugin is open source, so I'm also going to [publish it to github](https://github.com/jde/talk-plugin-asset-manager/commit/66b626caa85cb8030b3ddaa7c1a4821bf01e350a) and [cut a release](https://github.com/jde/talk-plugin-asset-manager/releases/tag/v0.1) that mirrors the npm release.
|
||||
|
||||
## Done!
|
||||
|
||||
@@ -218,7 +218,7 @@ Basic settings can be added via json configuration in a plugin.
|
||||
* Default value
|
||||
* Variable name
|
||||
|
||||
#### Advanced Custom Configuration (low prioritiy)
|
||||
#### Advanced Custom Configuration (low priority)
|
||||
|
||||
Users can inject configuration interfaces that they create into the configuration allowing for more advanced configuration.
|
||||
|
||||
|
||||
@@ -220,7 +220,7 @@ when a valid token is provided but a user can't be found in the database that
|
||||
matches the provided id.
|
||||
|
||||
The function is async, and should return the user object that was created in the
|
||||
database, or null if the user wasn't found. The `jwt` paramenter of the object
|
||||
database, or null if the user wasn't found. The `jwt` parameter of the object
|
||||
is the unpacked token, while `token` is the original jwt token string.
|
||||
|
||||
### Routes
|
||||
@@ -314,14 +314,14 @@ module.exports = {
|
||||
const {passport} = require('services/passport');
|
||||
|
||||
/**
|
||||
* Facebook auth endpoint, this will redirect the user immediatly to facebook
|
||||
* Facebook auth endpoint, this will redirect the user immediately to facebook
|
||||
* for authorization.
|
||||
*/
|
||||
router.get('/facebook', passport.authenticate('facebook', {display: 'popup', authType: 'rerequest', scope: ['public_profile']}));
|
||||
|
||||
/**
|
||||
* Facebook callback endpoint, this will send the user a html page designed to
|
||||
* send back the user credentials upon sucesfull login.
|
||||
* send back the user credentials upon successful login.
|
||||
*/
|
||||
router.get('/facebook/callback', (req, res, next) => {
|
||||
|
||||
|
||||
Reference in New Issue
Block a user