Merge pull request #1279 from coralproject/docs

Updated docs for 4.0

bin/cli-users

@@ -273,7 +273,7 @@ program
   .action(deleteUser);
 
 program
-  .command('search')
+  .command('list')
   .description('searches for a user based on their stored username and email')
   .action(searchUsers);
 

docs/_config.yml

@@ -21,7 +21,7 @@ url: "https://coralproject.github.io" # the base hostname & protocol for your si
 google_analytics: UA-73335347-5
 versions:
   node: 8+
-  yarn: 1.0.1+
+  yarn: 1.3.2+
   mongodb: 3.2+
   redis: 3.2.5+
   docker: 17.06.2+

docs/_data/nav.yaml

@@ -41,3 +41,7 @@ items:
     children:
       - title: FAQ
         url: /faq/
+  - title: Migrating
+    children:
+      - title: Migrating to v4.0.0
+        url: /migration/4/

docs/_docs/01-01-talk-quickstart.md

@@ -147,7 +147,7 @@ will definitely not work unless you change those values as well.
 You can now start the application by running:
 
 ```bash
-yarn dev-start
+yarn watch:server
 ```
 
 Continue onto the [Running](#running) section for details on how to complete the

docs/_docs/01-02-installation-from-docker.md

@@ -121,7 +121,7 @@ your containerized infrastructure. The versioning of our Docker tags as well
 lets you do something like:
 
 ```docker
-FROM coralproject/talk:3.5-onbuild
+FROM coralproject/talk:4.0-onbuild
 ```
 
-Which would pin your image to `3.5` release's.
+Which would pin your image to `4.0` release's.

docs/_docs/01-03-installation-from-source.md

@@ -73,7 +73,7 @@ values as well.
 You can now start the application by running:
 
 ```bash
-yarn dev-start
+yarn watch:server
 ```
 
 At this stage, you should refer to the [configuration]({{ "/configuration/" | relative_url }}) for

docs/_docs/02-01-required-configuration.md

@@ -8,7 +8,7 @@ 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/){:target="_blank"}.
 In development, you can specify configuration in a file named `.env` and it will
-be loaded into the environment when you run `yarn dev-start`.
+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:

docs/_docs/02-02-advanced-configuration.md

@@ -8,7 +8,7 @@ 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/){:target="_blank"}.
 In development, you can specify configuration in a file named `.env` and it will
-be loaded into the environment when you run `yarn dev-start`.
+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:
@@ -467,3 +467,23 @@ same as any other user in the system. (Default `FALSE`)
 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){:target="_blank"}. (Default
+`1hr`)
+
+## APOLLO_ENGINE_KEY
+
+Used to set the key for use with
+[Apollo Engine](https://www.apollographql.com/engine/){:target="_blank"} for
+tracing of GraphQL requests.
+
+**Note: Apollo Engine is a premium service, charges may apply.**

docs/_docs/06-01-migrating-4.md

@@ -0,0 +1,80 @@
+---
+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.
+{: .code-aside}
+
+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.
+
+## Database Verifications
+
+In `v3.*`, we introduced the concept of "verifying the database". Some of our
+operations update cached values that live along side the original document to
+improve performance. Running the cli command for verifying the database's cache
+ensures that all the cached values are up to date.
+
+Running the following will start the database verification process:
+
+```bash
+./bin/cli verify db --fix
+```
+You can notice the `--fix` option, without it, the tool should instead perform
+a dry run of the operations it intends to perform.
+{: .code-aside}
+
+This process, like the migration process, should take some time to complete on
+large databases.
+
+Once you have updated your databases, that's all you have to do! Talk should now
+function even better and faster with all the new features we poured into v4.0.0!
+
+## 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.

routes/index.js

@@ -15,6 +15,7 @@ const staticMiddleware = require('express-static-gzip');
 const {DISABLE_STATIC_SERVER} = require('../config');
 const {createGraphOptions} = require('../graph');
 const {passport} = require('../services/passport');
+const {MOUNT_PATH} = require('../url');
 
 const router = express.Router();
 
@@ -30,6 +31,17 @@ if (!DISABLE_STATIC_SERVER) {
   const public = path.resolve(path.join(__dirname, '../public'));
   router.use('/public', express.static(public));
 
+  /**
+   * Redirect old embed calls.
+   */
+  router.get('/embed.js', (req, res) => {
+    const oldEmbed = path.resolve(MOUNT_PATH, 'embed.js');
+    const newEmbed = path.resolve(MOUNT_PATH, 'static/embed.js');
+
+    console.warn(`deprecation warning: ${oldEmbed} will be phased out soon, please replace calls from ${oldEmbed} to ${newEmbed}`);
+    res.redirect(301, newEmbed);
+  });
+
   /**
    * Serve the directories under dist.
    */