Jekyll Initial Commit

docs-tmp/plugins/README.md

@@ -0,0 +1,163 @@
+# Plugins
+
+The talk platform ships with a plugin architecture featuring that allows
+developers to:
+
+* extend or replace server side graph, rest and auth functionality
+* inject functionality into front end embeds and the admin application
+* create new front end build targets for embedding
+* build plugins from local folders or published via npm/yarn
+* deploy plugins throughout the application lifecycle
+
+## Basic Concepts
+
+All plugin code lives in the `/plugin` directory.
+
+Each plugin is provided in a single folder named after the plugin.
+
+### Naming a Plugin
+
+Each plugin has a name which must be globally unique. Plugins with name
+collisions will not be able to be run together in an instance of Talk.
+
+If you are creating a plugin for the open source community, we recommend the
+following naming convention:
+
+```
+coral-talk-plugin-[name]
+```
+
+If you are creating a variant of a plugin for an organization, we recommend
+adding the organization's name:
+
+```
+coral-talk-plugin-[name]-[organization]
+```
+
+## Plugin Registration
+
+In order for a Plugin to be active 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 `process.env.TALK_PLUGINS_JSON` or the `plugins.json`.
+
+### Local Plugins
+
+The format for plugins.json looks like this:
+
+```json
+{
+  "server": [
+    "coral-plugin-respect",
+    "coral-plugin-facebook-auth"
+  ],
+  "client": [
+    "coral-plugin-respect"
+  ]
+}
+```
+
+The `server` array specifies which plugins will be loaded when the server
+starts. The `client` array specifies which plugins will be built into the
+front end bundles.
+
+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/coral-plugin-respect` and
+`plugins/coral-plugin-facebook-auth`.
+
+### Published Plugins
+
+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"}
+  ]
+}
+```
+
+### Resolving Plugins
+
+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 dependancies and remote plugins
+./bin/cli plugins reconcile
+
+# build staic assets (including enabled client side plugins)
+yarn build
+```
+
+Then the application can be started as is.
+
+If you are working on a plugin, our changes to the plugins will be picked up
+naturally by our development scripts:
+
+```bash
+# Watch for changes to client files and rebuild
+yarn build-watch
+```
+
+```bash
+# Watch for changes to server files and restart
+yarn dev-start
+```
+
+
+### 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.