feat: add deploying to digital ocean using ansible

guides/deploying-to-digital-ocean-with-ansible.md

@@ -0,0 +1,167 @@
+## At a Glance
+
+This deployment guide's purpose is to provide a simple and easy way to deploy Open Commerce for evaluation purposes or small deployments. This guide is not meant to generate an enterprise production grade deployment, rather Docker Compose is used to manage containers which is not suitable for production deployments.
+
+> Note: It is important to understand that Open Commerce cannot provide support for your deployment. If you need 
+> help you can reach out to the community on our [Discord Server](https://discord.gg/Bwm63tBcQY)
+
+## What you need
+
+- A Linux host with at least 2GB of RAM, this guide uses a DigitalOcean droplet
+- A registered domain
+- A DNS manager that supports Certification Authority Authorization (CCA) records, such as Digital Ocean
+- Some familiarity with [Traefik](https://github.com/containous/traefik/)
+
+## Understand what the deployment will look like
+
+**Open Commerce Services Overview**
+
+- **Open Commerce GraphQL API**:
+  The [Open Commerce GraphQL API](https://github.com/reactioncommerce/reaction) service provides the GraphQL interface 
+  to the Open Commerce core functionality.
+- **Storefront**:
+  The [Example storefront](https://github.com/reactioncommerce/example-storefront) service provides the public facing storefront interface that customers will interact with.
+- **Open Commerce Admin**:
+  The [Admin](https://github.com/reactioncommerce/reaction-admin) service is a Meteor application that provides the UI to manage products, orders etc.
+
+Open Commerce services will be exposed to the public using [Traefik](https://github.com/containous/traefik/), which 
+is a cloud native router. Traefik will act as a reverse proxy that will route traffic to Docker containers. As stated above, you will need a registered domain to complete this step, as it will be necessary to manage DNS records for it.
+
+This guide will use the following subdomains, where `example.com` will need to substitute it with your domain:
+
+| Subdomain              | Description                       |
+| ---------------------- |-----------------------------------|
+| api.example.com        | The open Commerce GraphQL API     |
+| storefront.example.com | The example storefront            |
+| admin.example.com      | The Open Commerce admin interface |
+| traefik.example.com    | Traefik's admin UI                |
+
+Each of your domains will need an `A` DNS record that resolves to your host's IP. It's recommend to use DigitalOcean's free [DNS manager](https://www.digitalocean.com/docs/networking/dns/overview/). Further, in order to obtain SSL certificates for your subdomains, you will need a DNS manager that supports [CAA](https://support.dnsimple.com/articles/caa-record/) records.
+
+
+Further, you will need a [DigitalOcean Auth token](https://docs.digitalocean.com/reference/api/create-personal-access-token/) to generate CAA records for your sub-domains.
+
+## Clone the Proxy-Traefik Repo to your local machine
+
+The project that contains all the playbooks, etc. is located [here](https://github.com/reactioncommerce/proxy-traefik).
+
+In order to use these files you need to have a local copy on your machine. To clone the files locally just run:
+```sh
+git clone git@github.com:reactioncommerce/proxy-traefik.git
+```
+
+To make the project disconnected from the original repository you should `rm -rf .git` from within the newly created directory and then `git init`.
+You should not push any of your changes, especially your DO key, to a public repository and there is no need to do so since the command are intended to run from your local machine.
+
+## Prepare the Remote Host
+
+In this guide a DigitalOcean node will be used to host the Open Commerce Platform. If you don't yet have an account, 
+create one at [digitalocean.com](https://digitalocean.com). Once you are signed in to your account, create a new droplet using the Ubuntu 18.4 image with at least 2GB of RAM. Enable DigitalOcean's [free firewall](https://www.digitalocean.com/docs/networking/firewalls/) and add inbound rules for SSH, HTTP, HTTPS and add your droplet to the firewall.
+
+After the droplet is created either select an existing SSH key to login or click on the "New SSH Key" under the authentication section  and copy your public SSH key from your local computer.
+
+Copy the newly created IP address and verify that you can log in into the new server by executing:
+
+```
+ssh root@XXX.XXX.XXX.XXX
+```
+
+## Prepare the Control Node
+
+Ansible requires a control node, which is a computer that manages a remote host. This guide assumes a Mac laptop/desktop as the control node.
+
+Install Ansible using [homebrew](https://brew.sh), this guide assumes some familiarity with Ansible, if you need an introduction to basic concepts click [here](https://www.ansibletutorials.com).
+
+`brew install ansible`
+
+Also install python3 to avoid deprecation warnings.
+
+`brew install python3`
+
+## Configure the remote host to be managed with Ansible
+
+On the control node (i.e. a developer's machine) create an inventory file in which `python3` is specified as the interpreter. On your machine, create a new file named `hosts` at `/etc/ansible` that shall act as your ansible inventory file.
+```
+touch /etc/ansible/hosts
+```
+
+Add the following content to the inventory file:
+```
+[servers]
+reaction.server
+
+[servers:vars]
+ansible_python_interpreter=/usr/bin/python3
+[web]
+```
+
+Edit your hosts file (your local DNS hosts file, NOT your newly created Ansible hosts/inventory file)
+```
+sudo vim /etc/hosts
+```
+
+And add an entry for the DigitalOcean droplet, ensuring to substitute the XXX octet's for your droplets external IP 
+address.
+
+```
+XXX.XXX.XXX.XXX reaction.server
+```
+
+Verify that Ansible can communicate with your remote host by executing:
+
+```
+ansible all -m ping -u root
+```
+
+Your should see output similar to:
+
+```
+reaction.dev | SUCCESS => {
+    "changed": false,
+    "ping": "pong"
+}
+```
+
+## Set Ansible Environment Variables
+
+Before executing the Ansible playbook, it's necessary to set variables that are specific to your deployment. Find the
+`vars` section in the `reaction.yml` playbook and update as necessary, below is a list of the variable
+that need to be updated and a description of each.
+
+| Variable               | Description                                                                 |
+| ---------------------- | ----------------------------------------------------------------------------|
+| do_auth_token          | The Authentication token for the Digital Ocean API                          |
+| email                  | An email address to receive SSL certificate notifications                   |
+| domain                 | Your registered domain                                                      |
+
+For the rest of the variables, the default values should be used, DO NOT change otherwise the playbook might fail.
+
+## Execute the playbook
+
+Now it's time to execute the `reaction.yml` playbook, which automates most of the tedious server configuration tasks, execute the following command:
+
+```
+ansible-playbook playbooks/reaction.yml -l reaction.server
+```
+
+NOTE: the `-l reaction.server` limits the execution of the playbook to the `reaction.server` host.
+
+## Create the Primary Shop
+
+At this point the Open Commerce GraphQL API, Example Storefront, Admin should be accessible over the internet.
+
+To create the primary shop login into the Open Commerce Admin at the following URL, first substitute the `example.com` 
+with your 
+actual domain:
+```
+https://admin.example.com
+```
+
+Upon navigating to the Admin interface, you will be presented with a login form, it will be necessary to create a user first, so click on the "Register" link and fill out the form. Once logged in, proceed to create a shop in the admin interface.
+
+Further, the `GraphQL API` explorer will be available at `https://api.example.com/graphql`.
+
+## Wrapping Up
+
+You have now successfully deployed Open Commerce to Digital Ocean using Ansible. You can now tweak your installation 
+to meet your needs including substituting your custom images for the stock ones that Open Commerce provides