From 876f4ef700d947095a879381d959810d63f9672e Mon Sep 17 00:00:00 2001 From: Wyatt Johnson Date: Thu, 11 Jan 2018 16:51:08 -0700 Subject: [PATCH 1/3] updated docs for 4.0 --- bin/cli-users | 2 +- docs/_config.yml | 2 +- docs/_data/nav.yaml | 4 + docs/_docs/01-01-talk-quickstart.md | 2 +- docs/_docs/01-02-installation-from-docker.md | 4 +- docs/_docs/01-03-installation-from-source.md | 2 +- docs/_docs/02-01-required-configuration.md | 2 +- docs/_docs/02-02-advanced-configuration.md | 22 +++++- docs/_docs/06-01-migrating-4.md | 80 ++++++++++++++++++++ routes/index.js | 7 ++ 10 files changed, 119 insertions(+), 8 deletions(-) create mode 100644 docs/_docs/06-01-migrating-4.md diff --git a/bin/cli-users b/bin/cli-users index 208db5053..fc50319b5 100755 --- a/bin/cli-users +++ b/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); diff --git a/docs/_config.yml b/docs/_config.yml index ce28d72c0..6bc934521 100644 --- a/docs/_config.yml +++ b/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+ diff --git a/docs/_data/nav.yaml b/docs/_data/nav.yaml index 9138d6603..c765b0fb7 100644 --- a/docs/_data/nav.yaml +++ b/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/ diff --git a/docs/_docs/01-01-talk-quickstart.md b/docs/_docs/01-01-talk-quickstart.md index 811bfe5ed..e3c12cc10 100644 --- a/docs/_docs/01-01-talk-quickstart.md +++ b/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 diff --git a/docs/_docs/01-02-installation-from-docker.md b/docs/_docs/01-02-installation-from-docker.md index fc699f127..3921a368f 100644 --- a/docs/_docs/01-02-installation-from-docker.md +++ b/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. \ No newline at end of file +Which would pin your image to `4.0` release's. \ No newline at end of file diff --git a/docs/_docs/01-03-installation-from-source.md b/docs/_docs/01-03-installation-from-source.md index 646a100a9..d6799df15 100644 --- a/docs/_docs/01-03-installation-from-source.md +++ b/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 diff --git a/docs/_docs/02-01-required-configuration.md b/docs/_docs/02-01-required-configuration.md index dc09a1707..da235ed90 100644 --- a/docs/_docs/02-01-required-configuration.md +++ b/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: diff --git a/docs/_docs/02-02-advanced-configuration.md b/docs/_docs/02-02-advanced-configuration.md index d39fab4b8..e985f8f20 100644 --- a/docs/_docs/02-02-advanced-configuration.md +++ b/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.** \ No newline at end of file diff --git a/docs/_docs/06-01-migrating-4.md b/docs/_docs/06-01-migrating-4.md new file mode 100644 index 000000000..5cd5d3cf7 --- /dev/null +++ b/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 yet as a major database migration, and template change is 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. \ No newline at end of file diff --git a/routes/index.js b/routes/index.js index 3f7041654..272b4eea1 100644 --- a/routes/index.js +++ b/routes/index.js @@ -30,6 +30,13 @@ 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) => { + res.redirect(301, '/static/embed.js'); + }); + /** * Serve the directories under dist. */ From 204b442e2f2fe7bae6b8fb8e292b3ac004d580cd Mon Sep 17 00:00:00 2001 From: Wyatt Johnson Date: Thu, 11 Jan 2018 17:32:52 -0700 Subject: [PATCH 2/3] added deprecation warning --- routes/index.js | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/routes/index.js b/routes/index.js index 272b4eea1..9b1e81ca7 100644 --- a/routes/index.js +++ b/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(); @@ -34,7 +35,11 @@ if (!DISABLE_STATIC_SERVER) { * Redirect old embed calls. */ router.get('/embed.js', (req, res) => { - res.redirect(301, '/static/embed.js'); + 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); }); /** From bb9a93986e2f5f3dafd00e01b924fc531614c100 Mon Sep 17 00:00:00 2001 From: Kim Gardner Date: Thu, 11 Jan 2018 19:41:45 -0500 Subject: [PATCH 3/3] Small wording tweak --- docs/_docs/06-01-migrating-4.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/_docs/06-01-migrating-4.md b/docs/_docs/06-01-migrating-4.md index 5cd5d3cf7..b66921cf0 100644 --- a/docs/_docs/06-01-migrating-4.md +++ b/docs/_docs/06-01-migrating-4.md @@ -4,7 +4,7 @@ permalink: /migration/4/ --- Since our `v3.*` release, this is the most significant set of changes introduced -into Talk yet as a major database migration, and template change is required to +into Talk so far, as a major database migration and template change are both required to run it. ## Dependencies @@ -77,4 +77,4 @@ served out of a `/static` prefix, so you will have to change your embed code: ```https://your-talk-url.com/static/embed.js``` This should be changed in your embed code on the site where you are embedding -Talk. \ No newline at end of file +Talk.