Merge pull request #187 from reactioncommerce/asj-updates

[WIP] 1.2 Doc updates

admin/faq.md

@@ -1,9 +1,5 @@
 # Frequently Asked Questions
 
-## Is Reaction live and ready for production? Can I start selling now?
-
-It depends! We do have a few shops in production, but your individual requirements may vary. We're currently in our Beta release, so we're still rolling out features with each new release. For more info, check out our [Features page](https://reactioncommerce.com/features) roadmap, or our [project board](https://waffle.io/reactioncommerce/reaction).
-
 ## How do I sign up for an account, login to my dashboard, and set up my domain?
 
 Currently, Reaction is only available locally via GitHub. In early 2017, we'll be launching the Beta release of our hosted platform, which will allow anyone to set up shop via our intuitive dashboard. Our custom hosting solution, which runs on Docker, will support domains, SSL, and more. Our vision is to allow anyone to customize, extend, and deploy his or her Reaction shop directly from on our platform.
@@ -36,8 +32,14 @@ We're always testing! During our Alpha release, we performed extensive tests, de
 
 We're always open to contributions from our community. To learn more about becoming a contributor, [click here](http://blog.reactioncommerce.com/how-to-get-involved-with-reaction-commerce/). And don't forget to read our [Community Guidelines](https://docs.reactioncommerce.com/reaction-docs/master/guidelines)!
 
-## Reaction runs on JavaScript. Does this have a negative impact on SEO?
+## Reaction is all JavaScript. Does this have a negative impact on SEO?
 
 Nope! [Google indexes JavaScript when crawling websites](https://googlewebmastercentral.blogspot.com.es/2014/05/understanding-web-pages-better.html).
 
-Additionally, Reaction uses the Meteor spiderable package, which renders a search engine-friendly static page version of your shop using PhantomJS. You can read more about it [here](https://www.eventedmind.com/feed/meteor-the-spiderable-package).
+Additionally, Reaction can use a [modified version](https://github.com/ongoworks/spiderable) of the Meteor spiderable package, which renders a search engine-friendly static page version of your shop using PhantomJS.
+
+It's worth noting that the spiderable package is slotted for deprecation. The reasons for this include:
+
+-   Google has deprecated the AJAX crawling specification that the spiderable package is based on
+-   Search engine crawlers (like Google's) have gotten much better at dealing with JavaScript/AJAX based applications, without the need for any special handling
+-   There are now several better options for SEO goodness, like pre-rendering services (e.g. Prerender.io - which is included in Reaction and can easily be setup), server-side rendering techniques, etc.

developer/community.md

@@ -0,0 +1,35 @@
+# Community
+
+Welcome to the Reaction community!
+
+This is the starting point for becoming a contributor - improving docs, improving code, giving talks etc.
+
+Participating in our Gitter channels, our planning meetings, are welcome contributions to Reaction.
+
+If you'd like to contribute code, you'll want to review the [contribution guidelines](contributing.md) and the [code styleguide](styleguide.md).
+
+## Roadmap
+
+Reaction is a series of projects that combine the efforts of [community contributors](https://github.com/orgs/reactioncommerce/outside-collaborators) and core product development from the [@reactioncommerce](https://github.com/orgs/reactioncommerce/people) team.
+
+A long term roadmap and completed features list is on our [features page](https://reactioncommerce.com/features).
+
+You will find these roadmap items defined as projects on the [Reaction repository's project page](https://github.com/reactioncommerce/reaction/projects).
+
+Specific features in progress are found grouped on the [Reaction repository's milestones page](https://github.com/reactioncommerce/reaction/milestones).
+
+## Projects
+
+Reaction projects can have both @core leads as well as community leads.
+Chat channels and meetings are open to all.
+
+| Name                | Leads                   | Gitter Channel                                                                     | [Schedule](http://getrxn.io/2rcCal)       |
+| ------------------- | ----------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------- |
+| Connectors, Catalog | @aaronjudd @jshimko     | [reactioncommerce/catalog](https://gitter.im/reactioncommerce/catalog)             | Every 2 weeks on Wednesday 2PM Pacific    |
+| Core                | @aaronjudd              | [reactioncommerce/core](https://gitter.im/reactioncommerce/core)                   | Every 2 weeks on Wednesday 2PM Pacific    |
+| Components          | @mikemurray @kieckhafer | [reactioncommerce/components](https://gitter.im/reactioncommerce/components)       | Every 2 weeks on Tuesday 3PM Pacific      |
+| Deployment          | @jshimko                | [reactioncommerce/deployment](https://gitter.im/reactioncommerce/deployment)       | Every 2 weeks on Thursday 10AM Eastern    |
+| Design              | @rymorgan               | [reactioncommerce/design](https://gitter.im/reactioncommerce/design)               | Every 2 weeks on Wednesday 3PM Pacific    |
+| Documentation       | @sophiehe               | [reactioncommerce/documentation](https://gitter.im/reactioncommerce/documentation) | Monthly on the Fourth Tuesday 3PM Pacific |
+| Marketplace         | @spencern               | [reactioncommerce/marketplace](https://gitter.im/reactioncommerce/marketplace)     | Every 2 weeks on Wednesday 7AM Pacific    |
+| Plugins             | @zenweasel @impactmass  | [reactioncommerce/plugins](https://gitter.im/reactioncommerce/plugins)             | Every 2 weeks on Tuesday 1 PM Pacific     |

developer/configuration.md

@@ -12,7 +12,7 @@ Environment variables take priority over variables set in _settings.json_.
 
 You can also assign these variables before the `reaction` command.
 
-### REACTION_
+### REACTION\_
 
 The `REACTION_EMAIL`, `REACTION_USER`, `REACTION_AUTH` environment variables will configure the default administrator account.
 
@@ -39,20 +39,22 @@ Set the Reaction [logging level](/developer/architecture/logging.md). Defaults t
 Provide a [standard connection string for mongoDB](https://docs.mongodb.com/manual/reference/connection-string/).
 
 ```sh
-
 MONGO_URL=mongodb://[username:password@]host1[:port1][,host2[:port2],...[,hostN[:portN]]][/[database][?options]]
-
 ```
 
 During development, mongoDB is installed and running locally, and can be accessed on the port above the http port.  Use [RoboMongo](https://robomongo.org/) and create a connection to `localhost:3001`, or `meteor mongo` on the CLI to access the local mongoDB instance. The default database is `meteor`.
 
 ### ROOT_URL
 
-_Export `ROOT_URL` and [packages/reaction-core/registry.js](https://github.com/reactioncommerce/reaction/blob/development/packages/reaction-core/server/registry.js) will update the domain in the `shops` collection to match the domain from `ROOT_URL`._ This lets you use alternate domains, or enforce SSL on a fresh installation. An empty ROOT_URL will just default to _localhost_.
+Export `ROOT_URL` and Reaction will update the domain in the `Shops` collection to match the domain from `ROOT_URL`. This lets you use alternate domains, or enforce SSL on a fresh installation. An empty `ROOT_URL` will just default to `localhost`.
 
 ### MAIL_URL
 
-To send email you should pre-configure the administrative SMTP email server. [env MAIL_URL variable](https://docs.meteor.com/api/email.html#Email-send).  The Reaction dashboard provides a UI for quick configuration of the email server as well.
+To send email you should pre-configure the administrative SMTP email server from `reaction.json` or using [env MAIL_URL variables](https://docs.meteor.com/api/email.html#Email-send).
+
+Reaction supports sending mail over SMTP; the `MAIL_URL` environment variable should be of the form `smtp://USERNAME:PASSWORD@HOST:PORT`.
+
+The Email dashboard provides a UI for quick configuration of the email server as well.
 
 ## Settings
 
@@ -193,15 +195,14 @@ Use `reaction.json` to provide an initial pre-configuration of Reaction. This wi
 
 _Note: Where `name` is Reaction package name, the `settings` object will update the `Packages` collection on every restart/reload._
 
-
 ## Default Data
 
 Reaction installs sample data, translations, and other fixture defaults from `/private/data/` and `/private/data/i18n` using the `Reaction.Import` class.
 
-- Products.json
-- Shipping.json
-- Shops.json
-- Tags.json
+-   Products.json
+-   Shipping.json
+-   Shops.json
+-   Tags.json
 
 You can overwrite or delete these import files to alter the default data. If altered, the changed data will be merged with existing documents, but changes in the database will not overwrite on restart if there are no changes.
 
@@ -225,7 +226,6 @@ Meteor.startup(function () {
 });
 ```
 
-
 ### loadSettings
 
 ```js

developer/deploying.md

@@ -1,5 +1,13 @@
 # Deploying
 
+Reaction is an open source platform, and you can run Reaction anywhere just like regular Node.js or Meteor applications. Operating Meteor apps correctly, so that your apps work for everyone, can be tricky if you are managing your infrastructure manually. This is why we recommend running production Reaction deployments on the [Reaction Commerce managed platform](https://reactioncommerce.com/features#get-a-demo).
+
+If you are looking to deploy Reaction manually, head on over to the [Meteor deployment documentation](https://guide.meteor.com/deployment.html) for an excellent, detailed tutorial.
+
+## Containers
+
+Docker images are pushed when Reaction successfully builds and passes all tests on the `master` or `development` branches. These images are released on [Reaction Commerce Docker Hub](https://hub.docker.com/u/reactioncommerce/). There are two images available: [reactioncommerce:prequel](https://hub.docker.com/r/reactioncommerce/prequel/) - the latest `development` image and [reactioncommerce:reaction](https://hub.docker.com/r/reactioncommerce/reaction/), the `master` image.
+
 All Reaction [configuration options](configuration.md) can be used with these deployment choices.
 
 Reaction can be deployed as a [standard Node application](https://guide.meteor.com/deployment.html) or as a [Docker container](https://www.docker.com/).
@@ -8,5 +16,50 @@ The Reaction core team recommends using Docker for deploying Reaction.
 
 We recommend you deploy with at least **2GB of memory** for Node and Reaction to run well.
 
-- [Docker and AWS](deploying/docker.md)
-- [Galaxy (MDG)](deploying/galaxy.md)
+-   [Docker Deployment Guide](deploying/docker.md)
+
+The database is included in development, and our containers also include a MongoDB instance inside the container, but it is only intended for development and testing. It’s not a production solution, and you should provide an external replica-set db instance with oplog access enabled for production deployment.
+
+## Hosting
+
+Meteor offers hosting on their Galaxy platform.
+
+-   [Galaxy (MDG)](https://www.meteor.com/hosting)
+
+## Build System
+
+While Meteor provide some key framework components to Reaction, the heaviest lifting is the build system. The `reaction-cli` command line tool wraps the Meteor command line functionality and provides additional Reaction specific deployment options in addition to the Meteor build system.
+
+You can [read the entire guide for the Meteor build system](https://guide.meteor.com/build-tool.html), but the sections below are direct from that page, compiled for just the most Reaction relevant portions.
+
+### Meteor build system
+
+The Meteor build system is the actual command line tool that you get when you install Meteor. You run it by typing the `reaction` command in your terminal, possibly followed by a set of arguments. Read the [docs about the command line tool](https://github.com/reactioncommerce/reaction-cli) or type `reaction help` in your terminal to learn about all of the commands.
+
+**What does it do?**
+
+The Meteor build tool is what compiles, runs, deploys, and publishes all of your Meteor apps and packages. It's Meteor's built-in solution to the problems also solved by tools like Grunt, Gulp, Webpack, Browserify, Nodemon, and many others, and uses many popular Node.js tools like Babel and UglifyJS internally to enable a seamless experience.
+
+**Reloads app on file change**
+
+When you run `reaction`, the tool starts up, and you should leave it running continuously while developing your app. The tool automatically detects any relevant file changes and recompiles the necessary changes, restarting your client or server environment if needed.
+
+**Compiles files with build plugins**
+
+The main function of the Meteor build tool is to run "build plugins". These plugins define different parts of your app build process. Meteor puts heavy emphasis on reducing or removing build configuration files, so you won't see any large build process config files like you would in Gulp or Webpack. The Meteor build process, and [file load order](structure.html#load-order), is configured almost entirely through adding and removing packages to your app and putting files in specially named directories. For example, to get all of the newest stable ES2015 JavaScript features in your app, you just add the [`ecmascript` package](http://docs.meteor.com/#/full/ecmascript). This package provides support for ES2015 modules, which gives you even more fine grained control over file load order using ES2015 `import` and `export`. As new Meteor releases add new features to this package you just get them for free.
+
+**Combines and minifies code**
+
+Another important feature of the Meteor build tool is that it automatically concatenates and minifies all of your files in production mode. This is enabled by the [`standard-minifier-js`](https://atmospherejs.com/meteor/standard-minifiers-js) and [`standard-minifier-css`](https://atmospherejs.com/meteor/standard-minifiers-css) packages, which are in all Meteor apps by default. If you need different minification behavior, you can replace these packages. Below, we'll talk about how to [switch out a minifier to add PostCSS to your build process](#postcss).
+
+**Development vs. production**
+
+Running an app in development is all about fast iteration time. All kinds of different parts of your app are handled differently and instrumented to enable better reloads and debugging. In production, the app is reduced to just the necessary code, and functions like a regular Node.js app. Therefore, you shouldn't run your app in production by running the `reaction` command. Instead, follow the directions in the [production deployment article](https://guide.meteor.com/deployment.html#custom-deployment).
+
+**Minification**
+
+The current best practice for deploying web production applications is to concatenate and minify all of your app assets. This lets you add all of the comments and whitespace you want to your source code, and split it into as many files as is necessary without worrying about app performance.
+
+Every Meteor app comes with production minification by default with the `standard-minifier-js` and `standard-minifier-css` packages. These minifiers go to some extra effort to do a good job - for example, Meteor automatically splits up your files if they get too big to maintain support for older versions of Internet Explorer which had a limit on the number of CSS rules per file.
+
+Minification usually happens when you `reaction deploy` or `reaction build` your app. If you have an error in production that you suspect is related to minification, you can run the minified version of your app locally with `reaction --production`.

developer/deploying/launchdock.md

@@ -0,0 +1,87 @@
+# Managed
+
+Reaction Commerce offers managed deployments for Reaction. The `reaction-cli` incorporates functionality for any team to deploy Reaction to multiple environments.
+
+`Launchdock` is the name of our registration gateway for the managed platform.
+
+## reaction register
+
+As a user of the Reaction managed platform, you'll receive an email with a `Launchdock` registration token.
+
+**Register as a platform user**
+
+```sh
+# Register with invite token
+reaction register
+```
+
+**Set up an SSH key pair to securely communicate with Launchdock**
+
+```sh
+# https://help.github.com/articles/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent/
+#
+# create a new SSH key pair
+# prompts for filename
+# suggest "~/.ssh/launchdock" for ease
+ssh-keygen -t rsa -b 4096 -C "you@example.com"
+
+# make sure the ssh-agent is running in the background
+eval "$(ssh-agent -s)"
+
+# add your new key to the agent
+ssh-add -K ~/.ssh/<private key created above>
+
+# add your public key to Launchdock
+reaction keys add ~/.ssh/<keyname>.pub
+```
+
+## reaction create
+
+**Create an app from a prebuilt image**
+
+```sh
+reaction apps create --name <appname> --image myorg/myapp:v1.0.0
+
+# To deploy an updated version of your pre-built image
+reaction deploy --name <appname> --image myorg/myapp:v1.1.0
+```
+
+**Or run a custom build**
+
+```sh
+# (Must be in a Reaction project dir. This adds a git remote called 'launchdock-<appname>' to your project)
+reaction apps create --name <appname>
+# Push your custom code and start a build
+reaction deploy --name <appname>
+```
+
+## reaction deploy
+
+```sh
+# Push your custom code and start a build
+reaction deploy --name <appname>
+```
+
+**Example deployment**
+
+An example deployment with a custom smtp server and preconfigured settings deploying the latest Reaction image from Docker Hub.
+
+```sh
+reaction apps create --name demo
+reaction env set \
+--app demo \
+-e REACTION_EMAIL="testing@yourdomain.com" \
+-e REACTION_USER="Administrator" \
+-e REACTION_AUTH="PaSSw0Rd" \
+-e MAIL_URL="smtp://USERNAME:PASSWORD@HOST:PORT"
+
+
+reaction deploy \
+--name demo \
+--image reactioncommerce/reaction:latest \
+--registry ../config/reaction.json \
+--settings ../config/settings.json
+
+reaction domains add -a demo -d demo.yourdomain.com
+reaction open -n demo
+```