diff --git a/README.md b/README.md index 84fe6e869..9fc0e74dc 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,10 @@ -logo + + logo + # 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) -[![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/) +[![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) 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]. - -```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 +[awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust +[documentation]: https://www.pomerium.io/ [go environment]: https://golang.org/doc/install +[godocs]: https://godoc.org/github.com/pomerium/pomerium [quick start guide]: https://www.pomerium.io/guide/ diff --git a/docs/guide/readme.md b/docs/guide/readme.md index 67117e711..130edfde1 100644 --- a/docs/guide/readme.md +++ b/docs/guide/readme.md @@ -1,27 +1,78 @@ # Quick start - ## Using Docker -* 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. -* 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]. -* 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. +- 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. +- 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]. +- 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. ![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/) -[docker]: https://docs.docker.com/install/ -[download]: https://github.com/pomerium/pomerium/releases -[kms]: https://en.wikipedia.org/wiki/Key_management +## From source + +### Get the code + +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 -[source]: https://github.com/pomerium/pomerium#start-developing -[identity provider]: ./identity-providers.md +[docker]: https://docs.docker.com/install/ +[docker-compose]: (https://docs.docker.com/compose/install/) +[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/ \ No newline at end of file +[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 diff --git a/env.example b/env.example index a8d8b0892..4444722f7 100644 --- a/env.example +++ b/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!