Merge pull request #145 from ubclaunchpad/rob/#143-dist

Homebrew install instructions

Makefile

@@ -1,4 +1,4 @@
-.PHONY: inertia test test-verbose testenv clean daemon testdaemon bootstrap
+.PHONY: commands inertia inertia-tagged clean test test-v testenv testdaemon daemon bootstrap web-deps web-run web-build
 
 TAG = `git describe --tags`
 PACKAGES = `go list ./... | grep -v vendor/`
@@ -9,6 +9,10 @@ RELEASE = canary
 
 all: inertia
 
+# List all commands
+commands:
+	@$(MAKE) -pRrq -f $(lastword $(MAKEFILE_LIST)) : 2>/dev/null | awk -v RS= -F: '/^# File/,/^# Finished Make data base/ {if ($$1 !~ "^[#.]") {print $$1}}' | sort | egrep -v -e '^[^[:alnum:]]' -e '^$@$$' | xargs
+
 # Install Inertia with release version
 inertia:
 	go install -ldflags "-X main.Version=$(RELEASE)"
@@ -29,7 +33,7 @@ test:
 	go test $(PACKAGES) -ldflags "-X main.Version=test" --cover
 
 # Run test suite - creates test VPS and test daemon beforehand
-test-verbose:
+test-v:
 	make testenv VPS_OS=$(VPS_OS) VPS_VERSION=$(VPS_VERSION)
 	make testdaemon	
 	go test $(PACKAGES) -ldflags "-X main.Version=test" -v --cover
@@ -74,10 +78,14 @@ daemon:
 bootstrap:
 	go-bindata -o client/bootstrap.go -pkg client client/bootstrap/...
 
-# Run local development instance of Inertia web.
-web-dev:
-	(cd ./daemon/web; npm install; npm start)
+# Install Inertia Web dependencies.
+web-deps:
+	(cd ./daemon/web; npm install)
+
+# Run local development instance of Inertia Web.
+web-run:
+	(cd ./daemon/web; npm start)
 
-# Build and minify Inertia web.
+# Build and minify Inertia Web.
 web-build:
 	(cd ./daemon/web; npm install --production; npm run build)

README.md

@@ -23,31 +23,28 @@
 
 ----------------
 
-Inertia is a cross-platform command line tool that aims to simplify setup and management of automated deployment of docker-compose projects on any virtual private server. It aims to provide the ease and flexibility of services like Heroku without the complexity of Kubernetes while still giving users full control over their projects.
+Inertia is a cross-platform command line tool that simplifies setup and management of automated project deployment on any virtual private server. It aims to provide the ease and flexibility of services like Heroku without the complexity of Kubernetes while still giving users full control over their projects.
 
-- [Installation](#package-installation)
-- [Usage](#rocket-usage)
+- [Usage](#package-usage)
   - [Setup](#setup)
   - [Continuous Deployment](#continuous-deployment)
   - [Deployment Management](#deployment-management)
   - [Release Streams](#release-streams)
 - [Motivation and Design](#bulb-motivation-and-design)
 - [Development](#construction-development)
 
-## :package: Installation
+# :package: Usage
 
-To get started, just download an Inertia CLI binary for your platform from the [Releases](https://github.com/ubclaunchpad/inertia/releases) page. You can add this binary to your PATH or execute it directly to use the CLI:
+All you need to get started is a docker-compose project, the Inertia CLI, and access to a virtual private server. To download the CLI:
 
 ```bash
-$> mv $INERTIA_IMAGE ./inertia
-$> ./inertia
+$> brew install ubclaunchpad/tap/inertia
+$> inertia
 ```
 
-You can also [install Inertia from source](#installing-from-source).
+For other platforms, you can also [download the appropriate binary for your platform from the Releases page](https://github.com/ubclaunchpad/inertia/releases) or [install Inertia from source](#installing-from-source).
 
-## :rocket: Usage
-
-### Setup
+## Setup
 
 Initializing a project for use with Inertia only takes a few simple steps:
 
@@ -64,65 +61,62 @@ $> inertia $VPS_NAME status
 # Confirms that the daemon is online and accepting requests
 ```
 
-An Inertia daemon is now running on your remote instance. This daemon will be used to manage your deployment.
+This daemon will be used to manage your deployment.
 
-See our [wiki](https://github.com/ubclaunchpad/inertia/wiki/VPS-Compatibility) for more details on platform compatibility.
+See our [wiki](https://github.com/ubclaunchpad/inertia/wiki/VPS-Compatibility) for more details on VPS platform compatibility.
 
-### Continuous Deployment
+## Deployment Management
 
-You can now set up continuous deployment using the output of `inertia $VPS_NAME init`:
+To manually deploy your project, you must first grant Inertia permission to clone your repository. This can be done by adding the GitHub Deploy Key that is displayed in the output of `inertia $VPS_NAME init` to your repository settings:
 
 ```bash
 GitHub Deploy Key (add here https://www.github.com/<your_repo>/settings/keys/new):
 ssh-rsa <...>
 ```
 
-The Inertia daemon requires readonly access to your GitHub repository. Add the deploy key to your GitHub repository settings at the URL provided in the output - this will grant the daemon access to clone your repository.
+Once this is done, you can use Inertia to bring your project online on your remote VPS:
 
 ```bash
-GitHub WebHook URL (add here https://www.github.com/<your_repo>/settings/hooks/new):
-http://myhost.com:8081
-Github WebHook Secret: inertia
-``` 
+$> inertia $VPS_NAME up --stream
+```
 
-The daemon will accept POST requests from GitHub at the URL provided. Add this webhook URL in your GitHub settings area (at the URL provided) so that the daemon will receive updates from GitHub when your repository is updated.
+Run `inertia $VPS_NAME --help` to see the other commands Inertia offers for managing your deployment.
 
-### Deployment Management
+## Continuous Deployment
 
-To manually deploy your project:
+To enable continuous deployment, you need the webhook URL that is printed during `inertia $VPS_NAME init`:
 
 ```bash
-$> inertia $VPS_NAME up --stream
-```
+GitHub WebHook URL (add here https://www.github.com/<your_repo>/settings/hooks/new):
+http://myhost.com:8081
+Github WebHook Secret: inertia
+``` 
 
-There are a variety of other commands available for managing your project deployment. See the CLI documentation for more details:
+The daemon will accept POST requests from GitHub at the URL provided. Add this webhook URL in your GitHub settings area (at the URL provided) so that the daemon will receive updates from GitHub when your repository is updated. Once this is done, the daemon will automatically build and deploy any changes that are made to the deployed branch.
 
-```bash
-$> inertia $VPS_NAME --help
-```
-
-### Release Streams
+## Release Streams
 
-The version of Inertia you are using can be seen in Inertia's `.inertia.toml` configuration file, or by running `inertia --version`.
+The version of Inertia you are using can be seen in Inertia's `.inertia.toml` configuration file, or by running `inertia --version`. The version in `.inertia.toml` is used to determine what version of the Inertia daemon to use when you run `inertia $VPS_NAME init`.
 
-You can manually change the daemon version pulled by editing the Inertia configuration file. If you are building from source, you can also check out the desired version and run `make inertia-tagged`.
+You can manually change the daemon version used by editing the Inertia configuration file. If you are building from source, you can also check out the desired version and run `make inertia-tagged` or `make RELEASE=$STREAM`. Inertia daemon releases are tagged as follows:
 
 - `v0.x.x` denotes [official, tagged releases](https://github.com/ubclaunchpad/inertia/releases) - these are recommended.
 - `latest` denotes the newest builds on `master`.
 - `canary` denotes experimental builds used for testing and development - do not use this.
 
 The daemon component of an Inertia release can be patched separately from the CLI component - see our [wiki](https://github.com/ubclaunchpad/inertia/wiki/Daemon-Releases) for more details.
 
-### Swag
-
-[![Deployed with Inertia](https://img.shields.io/badge/Deploying%20with-Inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
+## Swag
 
+Add some bling to your Inertia-deployed project :sunglasses:
 
 ```
 [![Deployed with Inertia](https://img.shields.io/badge/Deploying%20with-Inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
 ```
 
-## :bulb: Motivation and Design
+[![Deployed with Inertia](https://img.shields.io/badge/Deploying%20with-Inertia-blue.svg)](https://github.com/ubclaunchpad/inertia)
+
+# :bulb: Motivation and Design
 
 At [UBC Launch Pad](http://www.ubclaunchpad.com), we are frequently changing hosting providers based on available funding and sponsorship. Inertia is a project to develop an in-house continuous deployment system to make deploying applications simple and painless, regardless of the hosting provider.
 
@@ -132,7 +126,7 @@ The primary design goals of Inertia are to:
 * maximimise compatibility across different client and VPS platforms
 * offer a convenient interface for managing the deployed application
 
-### How It Works
+## How It Works
 
 Inertia consists of two major components: a deployment daemon and a command line interface.
 
@@ -144,71 +138,86 @@ The deployment daemon runs persistently in the background on the server, receivi
 
 Inertia is set up serverside by executing a script over SSH that installs Docker and starts an Inertia daemon image with [access to the host Docker socket](https://bobheadxi.github.io/dockerception/#docker-in-docker). This Docker-in-Docker configuration gives the daemon the ability to start up other containers *alongside* it, rather than *within* it, as required. Once the daemon is set up, we avoid using further SSH commands and execute Docker commands through Docker's Golang API. Instead of installing the docker-compose toolset, we [use a docker-compose image](https://bobheadxi.github.io/dockerception/#docker-compose-in-docker) to build and deploy user projects.
 
-## :construction: Development
+# :construction: Development
+
+This section outlines the various tools available to help you get started developing Inertia. Run `make commands` to list all the Makefile shortcuts available.
+
+If you would like to contribute, feel free to comment on an issue or make one and open up a pull request!
+
+## Installing from Source
 
-### Installing from Source
+First, [install Go](https://golang.org/doc/install#install) and grab Inertia's source code:
 
 ```bash
 $> go get -u github.com/ubclaunchpad/inertia
 ```
 
-It is highly recommended that you use a [tagged build](https://github.com/ubclaunchpad/inertia/releases) to ensure compatibility between the CLI and your Inertia daemon.
+We use [dep](https://github.com/golang/dep) for managing Golang dependencies, and [npm](https://www.npmjs.com) to manage dependencies for Inertia's React web app. Make sure both are installed before running the following commands.
+
+```bash
+$> dep ensure     # Inertia CLI and daemon dependencies
+$> make web-deps  # Inertia Web dependencies
+```
+
+For usage, it is highly recommended that you use a [tagged build](https://github.com/ubclaunchpad/inertia/releases) to ensure compatibility between the CLI and your Inertia daemon.
 
 ```bash
-$> git checkout v0.1.0
-$> make inertia-tagged
-$> inertia --version
+$> git checkout $VERSION
+$> make inertia-tagged    # installs a tagged version of Inertia
+$> inertia --version      # check what version you have installed
 ```
 
 Alternatively, you can manually edit `.inertia.toml` to use your desired daemon version - see the [Release Streams](#release-streams) documentation for more details.
 
-### Dependencies
+Note that if you install Inertia using these commands or any variation of `go install`, you may have to remove the binary using `go clean -i github.com/ubclaunchpad/inertia` to go back to using an Inertia CLI installed using Homebrew.
 
-We use [dep](https://github.com/golang/dep) for managing dependencies.
+For development, you should install a build tagged as `test` so that you can make use `make testdaemon` for local development. See the next section for more details.
 
 ```bash
-$> go get -u github.com/golang/dep/cmd/dep
-$> dep ensure
+$> make RELEASE=test    # installs current Inertia build and mark as "test"
 ```
 
-### Testing
+## Testing and Locally Deploying
 
-To run the Inertia test suite:
+You will need Docker installed and running to run the Inertia test suite, which includes a number of integration tests.
 
 ```bash
 $> make test                              # test against ubuntu:latest
 $> make test VPS_OS=ubuntu VERSION=14.04  # test against ubuntu:14.04
 ```
 
-You can also start a container that sets up a mock VPS for testing.
+You can also manually start a container that sets up a mock VPS for testing:
 
 ```bash
-$> make
-# installs current Inertia build and mark as "test"
 $> make testenv VPS_OS=ubuntu VERSION=16.04
-# defaults to ubuntu:lastest without args
-# note the location of the key that is printed
+# This defaults to ubuntu:lastest without args.
+# Note the location of the key that is printed and use that when
+# adding your local remote.
 ```
 
-You can [SSH into this container](https://bobheadxi.github.io/dockerception/#ssh-services-in-docker) and treat it just as you would treat a real VPS:
+You can [SSH into this testvps container](https://bobheadxi.github.io/dockerception/#ssh-services-in-docker) and otherwise treat it just as you would treat a real VPS:
 
 ```bash
 $> cd /path/to/my/dockercompose/project
 $> inertia init
 $> inertia remote add local
-# PEM file: /test_env/test_key, User: 'root', Address: 0.0.0.0
+# PEM file: inertia/test_env/test_key, User: 'root', Address: 0.0.0.0
 $> inertia local init
-$> inertia remote status local
-Remote instance 'local' accepting requests at http://0.0.0.0:8081
+$> inertia local status
 ```
 
-The above steps will pull a daemon image from Docker Hub based on the version in your `.inertia.toml`. To use a daemon compiled from source, set your version to `test` and run:
+The above steps will pull and use a daemon image from Docker Hub based on the version in your `.inertia.toml`.
+
+### Daemon
+
+To use a daemon compiled from source, set your Inertia version in `.inertia.toml` to `test` and run:
 
 ```bash
 $> make testdaemon
+$> inertia local init
 ```
 
-Setting up a `testvps` using `inertia local init` will now use the custom daemon.
+This will build a daemon image and `scp` it over to the test VPS, and use that image for the daemon when setting up `testvps` using `inertia local init`
 
 If you run into this error when deploying onto the `testvps`:
 
@@ -227,7 +236,17 @@ You probably need to go into your Docker settings and add this line to the Docke
 
 This sneaky configuration file can be found under `Docker -> Preferences -> Daemon -> Advanced -> Edit File`.
 
-### Compiling Bash Scripts
+### Web App
+
+Inertia Web is a React application. To run a local instance of Inertia Web:
+
+```bash
+$> make web-run
+```
+
+Make sure you have a local daemon set up for this web app to work - see the previous section for more details.
+
+## Compiling Bash Scripts
 
 To bootstrap servers, some bash scripting is often involved, but we'd like to avoid shipping bash scripts with our go binary. So we use [go-bindata](https://github.com/jteeuwen/go-bindata) to compile shell scripts into our go executables.