docs: add build from source guide (#32)

README.md

@@ -1,11 +1,10 @@
-<img  height="100" src="./docs/.vuepress/public/logo.svg" alt="logo" align="right" >
+<span>
+  <img height="125" src="./docs/.vuepress/public/logo.svg" alt="logo" align="right">
+</span>
 
 # Pomerium
 
-[![Travis CI](https://travis-ci.org/pomerium/pomerium.svg?branch=master)](https://travis-ci.org/pomerium/pomerium)
+[![Travis CI](https://travis-ci.org/pomerium/pomerium.svg?branch=master)](https://travis-ci.org/pomerium/pomerium) [![Go Report Card](https://goreportcard.com/badge/github.com/pomerium/pomerium)](https://goreportcard.com/report/github.com/pomerium/pomerium) [![GoDoc](https://godoc.org/github.com/pomerium/pomerium?status.svg)][godocs] [![LICENSE](https://img.shields.io/github/license/pomerium/pomerium.svg)](https://github.com/pomerium/pomerium/blob/master/LICENSE)
-[![Go Report Card](https://goreportcard.com/badge/github.com/pomerium/pomerium)](https://goreportcard.com/report/github.com/pomerium/pomerium)
-[![LICENSE](https://img.shields.io/github/license/pomerium/pomerium.svg)](https://github.com/pomerium/pomerium/blob/master/LICENSE)
-[![Docker Automated build](https://img.shields.io/docker/automated/pomerium/pomerium.svg)](https://hub.docker.com/r/pomerium/pomerium/)
 
 Pomerium is a tool for managing secure access to internal applications and resources.
 
@@ -16,24 +15,16 @@ Use Pomerium to:
 - deploy mutual authenticated encryption (mTLS).
 - aggregate logging and telemetry data.
 
-To learn more about some problems Pomerium attempts to address, check out this repository of [resources] covering zero-trust and BeyondCorp.
+Check out [awesome-zero-trust] to learn more about some problems Pomerium attempts to address.
 
-## Get started
+## Docs
 
-For instructions on getting started using Pomerium, see our [quick start guide].
+To get started with pomerium, check out our [quick start guide].
 
-## Start developing
+For comprehensive docs see our [documentation] and the [godocs].
 
-Assuming you have a working [Go environment].
+[awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust
-
+[documentation]: https://www.pomerium.io/
-```sh
-$ go get -d github.com/pomerium/pomerium
-$ cd $GOPATH/src/github.com/pomerium/pomerium
-$ make
-$ source ./env # see env.example
-$ ./bin/pomerium -debug
-```
-
-[resources]: https://github.com/pomerium/awesome-zero-trust
 [go environment]: https://golang.org/doc/install
+[godocs]: https://godoc.org/github.com/pomerium/pomerium
 [quick start guide]: https://www.pomerium.io/guide/

docs/guide/readme.md

@@ -1,27 +1,78 @@
 # Quick start
 
-
 ## Using Docker
 
-* Install [docker] and [docker-compose].
+- Install [docker] and [docker-compose].
-* Grab Pomerium's included example [`docker-compose.yml`](https://raw.githubusercontent.com/pomerium/pomerium/master/docker-compose.yml) directly or by cloning the repository.
+- Grab Pomerium's included example [`docker-compose.yml`](https://raw.githubusercontent.com/pomerium/pomerium/master/docker-compose.yml) directly or by cloning the repository.
-* Update `docker-compose.yml` to match your [identity provider] settings. 
+- Update `docker-compose.yml` to match your [identity provider] settings.
-* Copy your subdomain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
+- Copy your subdomain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
-* Run docker-compose by runnig the command `$ docker-compose up`. 
+- Run docker-compose by runnig the command `$ docker-compose up`.
-* Pomerium is configured to delegate access to two test apps [helloworld] and [httpbin]. Navigate to `hello.corp.example.com` or `httpbin.corp.example.com`. You should see something like the following in your browser and in your terminal. 
+- Pomerium is configured to delegate access to two test apps [helloworld] and [httpbin]. Navigate to `hello.corp.example.com` or `httpbin.corp.example.com`. You should see something like the following in your browser and in your terminal.
 
 ![Getting started](./get-started.gif)
 
 [![asciicast](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg.svg)](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg)
 
-[docker-compose]: (https://docs.docker.com/compose/install/)
+## From source
-[docker]: https://docs.docker.com/install/
+
-[download]: https://github.com/pomerium/pomerium/releases
+### Get the code
-[kms]: https://en.wikipedia.org/wiki/Key_management
+
+Using [git](https://git-scm.com/), retrieve the latest copy of pomerium's source code by cloning the repository.
+
+```bash
+# where `$HOME/pomerium` is the directory you want to save pomerium
+git clone https://github.com/pomerium/pomerium.git $HOME/pomerium
+```
+
+Build pomerium from source in a single step using make.
+
+```bash
+cd $HOME/pomerium
+make
+```
+
+The command will run all the tests, some code linters, then build the binary. If all is good, you should now have a freshly built pomerium binary in the `pomerium/bin` directory.
+
+### Configure
+
+Make a copy of the [env.example] and name it something like `env`.
+
+```bash
+cp env.example env
+```
+
+Modify your `env` configuration to to match your [identity provider] settings.
+
+```bash
+vim env
+```
+
+### Run
+
+Finally, source the the configuration `env` file and run pomerium.
+
+```bash
+source ./env
+./bin/pomerium
+```
+
+### All-in-one
+
+Assuming your configuration file ready to go, you can simply use this one-liner.
+
+```bash
+make && source ./env && ./bin/pomerium
+```
+
 [certbot]: https://certbot.eff.org/docs/install.html
-[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
+[docker]: https://docs.docker.com/install/
-[source]: https://github.com/pomerium/pomerium#start-developing
+[docker-compose]: (https://docs.docker.com/compose/install/)
-[identity provider]: ./identity-providers.md
+[download]: https://github.com/pomerium/pomerium/releases
+[env.example]: https://github.com/pomerium/pomerium/blob/master/env.example
 [helloworld]: https://hub.docker.com/r/tutum/hello-world
 [httpbin]: https://httpbin.org/
-[LetsEncrypt]: https://letsencrypt.org/
+[identity provider]: ./identity-providers.md
+[kms]: https://en.wikipedia.org/wiki/Key_management
+[letsencrypt]: https://letsencrypt.org/
+[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
+[source]: https://github.com/pomerium/pomerium#start-developing

env.example

@@ -51,5 +51,7 @@ export IDP_CLIENT_SECRET="REPLACEME"
 # export SCOPE="openid email" # generally, you want the default OIDC scopes
 
 # k/v seperated list of simple routes. If no scheme is set, HTTPS will be used.
-export ROUTES="example.corp.example.com=example.org"
+# Currently set to httpbin which is a handy utility letting you inspect requests recieved by
+# a client application
+export ROUTES="httpbin.corp.example.com=httpbin.org"
 # export ROUTES="https://weirdlyssl.corp.example.com=http://neverssl.com" #https to http!