Better accommodate outside contributors (#895)

* Better accommodate outside contributors

These changes were made in an effort to better accommodate outside contributors:

- Because `.env.frontend` was only used by the legacy NodeJS API, consolidate everything into a single `.env` file. I also created a new `.env` file on S3
- Update `scripts/bootstrap` to generate a stub `.env` file, on the first run, if the file on S3 is inaccessible
- Update the README file so that non-Azaveans can quickly setup an instance of OAR to contribute to the project

These changes are additional:

- Update Ansible to the 2.8.x series
- Update the Compose file format to 2.4

* Add note to .env.sample

* Merge development data subheading into development

* changelog

* fixup! Merge development data subheading into development

.env.sample

@@ -0,0 +1,4 @@
+# Note: You will need to restart the server to pick up changes to these variables.
+GOOGLE_SERVER_SIDE_API_KEY=
+REACT_APP_GOOGLE_CLIENT_SIDE_API_KEY=
+REACT_APP_GOOGLE_ANALYTICS_KEY=

.gitignore

@@ -31,8 +31,7 @@ yarn-error.log
 .DS_Store
 
 # OAR
-.env.backend
-.env.frontend
+.env
 factories.csv
 *_factories.csv
 src/django/static

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changed
 - Replace facility history feature switch with feature flag [#881](https://github.com/open-apparel-registry/open-apparel-registry/pull/881)
+- Better accommodate outside contributors [#895](https://github.com/open-apparel-registry/open-apparel-registry/pull/895)
 
 ### Deprecated
 

README.md

@@ -4,71 +4,77 @@ The Open Apparel Registry (OAR) is a tool to identify every apparel facility wor
 
 - [Requirements](#requirements)
 - [Setup](#setup)
+  - [Google Maps Platform](#google-maps-platform)
 - [Development](#development)
   - [Hot Reloading 🔥](#hot-reloading-)
-  - [Development Data](#development-data)
   - [Ports](#ports)
-- [Scripts](#scripts)
+- [Scripts 🧰](#scripts-)
 
 ## Requirements
 
-- Vagrant 2.1+
-- VirtualBox 5.0+
-- AWS CLI 1.1+
-- IAM credentials (for artifacts, secrets, etc)
+- [Vagrant](https://www.vagrantup.com/docs/installation/) 2.1+
+- [VirtualBox](https://www.virtualbox.org/wiki/Downloads) 5.0+
 
 ## Setup
 
-First, configure a local AWS profile with access to an S3 bucket with files containing project specific environment variables:
+Run `setup` to bring up the development environment:
 
 ```bash
-$ aws configure --profile open-apparel-registry
-AWS Access Key ID [None]: AKIAIOSFODNN7EXAMPLE
-AWS Secret Access Key [None]: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
-Default region name [None]: eu-west-1
-Default output format [None]:
+./scripts/setup
 ```
 
-Next, use `setup` to bring up the development environment:
+`setup` will provision a virtual machine (VM) that contains the tools needed to get started.
 
-```bash
-$ ./scripts/setup
-```
-
-`setup` will provision a Vagrant VM, using `vboxsf` to mount `./` (relative to `Vagrantfile`) to `/vagrant`, as well as `~/.aws` to `/home/vagrant/.aws`, and execute `update`.
-
-After running `setup`, you can access the VM by running:
+After executing `setup`, you can access the VM with:
 
 ```bash
 $ vagrant ssh
 vagrant@vagrant:/vagrant$
 ```
 
+### Google Maps Platform
+
+The OAR requires a Google Maps Platform API key to interface with the Maps JavaScript API, Maps Static API, and Maps Geocoding API. 
+
+Without an API key, facility detail maps will not load on the client and geocoding will not function on the server. The basemap will also be low-resolution and watermarked with "for development purposes only."
+
+See [Getting Started with Google Maps Platform](https://developers.google.com/maps/gmp-get-started#procedures) and [Get the API key](https://developers.google.com/maps/documentation/javascript/get-api-key#get-the-api-key) for an overview on how to get setup. 
+
+`setup` will stub out an environment variables file (`.env`) in the root of the project. To wire up your API key, simply update `.env`:
+
+```diff
+-GOOGLE_SERVER_SIDE_API_KEY=
+-REACT_APP_GOOGLE_CLIENT_SIDE_API_KEY=
++GOOGLE_SERVER_SIDE_API_KEY=YOUR_API_KEY
++REACT_APP_GOOGLE_CLIENT_SIDE_API_KEY=YOUR_API_KEY
+ REACT_APP_GOOGLE_ANALYTICS_KEY=
+ ```
+
+ _Note: Google Maps Platfom requires creation of a billing account, but [they offer](https://cloud.google.com/maps-platform/pricing/) $200 of free monthly usage, which is enough to support development._
+
 ## Development
 
-To start the application, run:
+To destroy the existing development database and load fresh fixture data, including users, facility lists, facility matches, and facilities, run:
 
 ```bash
 # Access the VM console
 $ vagrant ssh
 
-# Start the application
-vagrant@vagrant:/vagrant$ ./scripts/server
+# Load fixtures
+vagrant@vagrant:/vagrant$ ./scripts/resetdb
 ```
 
-### Hot Reloading 🔥
-
-Because the frontend uses [Create React App](https://github.com/facebook/create-react-app/), which integrates with webpack, the page will automatically reload if you make changes to the code.
+To start the application, run:
 
-In development, the [Django](https://www.djangoproject.com) app sits behind a [Gunicorn](https://www.gunicorn.org) worker that is passed the [`--reload` flag](https://docs.gunicorn.org/en/stable/settings.html#reload).
+```bash
+vagrant@vagrant:/vagrant$ ./scripts/server
+```
 
-### Development Data
+### Hot Reloading 🔥
 
-To destroy any existing development database and load fresh fixture data including users, facility lists, facility matches, and facilities run:
+The frontend uses [Create React App](https://github.com/facebook/create-react-app/). When running `server`, the page will automatically [reload](https://github.com/facebook/create-react-app/#whats-included) if you make changes to the code.
 
-```bash
-vagrant@vagrant:/vagrant$ ./scripts/resetdb
-```
+The [Django](https://www.djangoproject.com) app runs inside a [Gunicorn](https://www.gunicorn.org) worker. The worker will [restart](https://docs.gunicorn.org/en/stable/settings.html#reload) if you make changes to the code.
 
 ### Ports
 
@@ -77,14 +83,14 @@ vagrant@vagrant:/vagrant$ ./scripts/resetdb
 | React development server   | [`6543`](http://localhost:6543) |
 | Gunicorn for Django app    | [`8081`](http://localhost:8081) |
 
-## Scripts
+## Scripts 🧰
 
 | Name                                                   | Description                                                                                                                                                                                  |
 | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `bootstrap`                                            | Pull `.env` files from S3                                                                                                                                                                    |
+| `bootstrap`                                            | Update environment variables file                                                                                                                                                                    |
 | `infra`                                                | Plan and apply remote infrastructure changes                                                                                                                                                 |
 | `resetdb`                                              | Clear development database & load fixture data including users, facility lists, matches, and facilities                                                                                      |
 | `server`                                               | Run `docker-compose.yml` services                                                                                                                                                            |
 | `setup`                                                | Provision Vagrant VM and run `update`                                                                                                                                                        |
 | `test`                                                 | Run tests                                                                                                                                                                                    |
-| `update`                                               | Builds and pulls container images using docker-compose                                                                                                                                       |
+| `update`                                               | Build container images and execute database migrations                                                                                                                                       |

Vagrantfile

@@ -3,7 +3,7 @@
 
 Vagrant.require_version ">= 2.1"
 
-ANSIBLE_VERSION = "2.4.*"
+ANSIBLE_VERSION = "2.8.*"
 
 Vagrant.configure("2") do |config|
 

docker-compose.batch.yml

@@ -1,4 +1,4 @@
-version: '2.3'
+version: '2.4'
 services:
   batch:
     image: "openapparelregistry-batch:${GIT_COMMIT:-latest}"

docker-compose.ci.yml

@@ -1,4 +1,4 @@
-version: '2.3'
+version: '2.4'
 services:
   django:
     image: "openapparelregistry:${GIT_COMMIT:-latest}"

docker-compose.yml

@@ -1,4 +1,4 @@
-version: '2.3'
+version: '2.4'
 services:
   database:
     image: quay.io/azavea/postgis:2.4-postgres10.9-slim
@@ -14,7 +14,7 @@ services:
 
   django:
     image: openapparelregistry
-    env_file: .env.backend
+    env_file: .env
     environment:
         - POSTGRES_HOST=database
         - POSTGRES_PORT=5432
@@ -54,10 +54,8 @@ services:
       - /var/cache/open-apparel-registry-node-modules:/usr/local/src/node_modules
       - ./src/django/static:/usr/local/src/build
       - $HOME/.aws:/root/.aws:ro
-    env_file: .env.frontend
     environment:
       - REACT_APP_GIT_COMMIT=${REACT_APP_GIT_COMMIT:-latest}
-      - REACT_APP_API_URL=http://localhost:8081
       - CHOKIDAR_USEPOLLING=true
       - CHOKIDAR_INTERVAL=2000
       - PORT=6543

scripts/bootstrap

@@ -6,15 +6,12 @@ if [[ -n "${OAR_DEBUG}" ]]; then
     set -x
 fi
 
-# fail without OAR_SETTINGS_BUCKET
-set -u
-
 DIR="$(dirname "${0}")/../"
 
 function usage() {
     echo -n \
         "Usage: $(basename "$0")
-Pull .env files from S3.
+Update environment variables file.
 "
 }
 
@@ -24,11 +21,12 @@ if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
     else
         pushd "${DIR}"
 
-        echo "Pulling .env.backend from s3://${OAR_SETTINGS_BUCKET}"
-        aws s3 cp "s3://${OAR_SETTINGS_BUCKET}/.env.backend" ".env.backend"
-
-        echo "Pulling .env.frontend from s3://${OAR_SETTINGS_BUCKET}"
-        aws s3 cp "s3://${OAR_SETTINGS_BUCKET}/.env.frontend" ".env.frontend"
+        if aws s3 cp "s3://${OAR_SETTINGS_BUCKET}/.env" ".env"; then
+            echo "Updated environment variables file from ${OAR_SETTINGS_BUCKET}"
+        elif [[ ! -f ".env" ]]; then
+            cp .env.sample .env
+            echo "Updated environment variables file from .env.sample"
+        fi
 
         popd
     fi

scripts/update

@@ -9,7 +9,7 @@ fi
 function usage() {
     echo -n \
         "Usage: $(basename "$0")
-Builds and pulls container images using docker-compose.
+Build container images and execute database migrations.
 "
 }