From 27909f22ced9202c9a6f5afa332e07a0774e0933 Mon Sep 17 00:00:00 2001 From: Bobby DeSimone Date: Thu, 5 Mar 2020 18:07:43 -0800 Subject: [PATCH] docs: make from source quickstart (#519) - move building from so - remove dnsmasq instructions Signed-off-by: Bobby DeSimone --- docs/.vuepress/config.js | 5 +- .../examples/config/config.minimal.yaml | 21 ++- docs/docs/community/contributing.md | 140 +----------------- docs/docs/quick-start/from-source.md | 78 ++++++++++ package.json | 7 +- 5 files changed, 99 insertions(+), 152 deletions(-) create mode 100644 docs/docs/quick-start/from-source.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 55db3fb4e..624b6b5c1 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -28,7 +28,7 @@ module.exports = { { text: "Enterprise", link: "/enterprise/" }, { - text: "v0.6.x", // current tagged version + text: "🚧Dev", // current tagged version ariaLabel: "Version menu", items: [ { text: "🚧Dev", link: "https://master.docs.pomerium.io/docs" }, @@ -72,7 +72,8 @@ module.exports = { "quick-start/binary", "quick-start/helm", "quick-start/kubernetes", - "quick-start/synology" + "quick-start/synology", + "quick-start/from-source" ] }, { diff --git a/docs/configuration/examples/config/config.minimal.yaml b/docs/configuration/examples/config/config.minimal.yaml index 1d8f2bef1..a0ee5850d 100644 --- a/docs/configuration/examples/config/config.minimal.yaml +++ b/docs/configuration/examples/config/config.minimal.yaml @@ -1,16 +1,23 @@ # See detailed configuration settings : https://www.pomerium.io/docs/reference/reference/ -authenticate_service_url: https://authenticate.corp.beyondperimeter.com + +# this is the domain the identity provider will callback after a user authenticates +authenticate_service_url: https://authenticate.localhost.pomerium.io + +# certificate settings: https://www.pomerium.io/docs/reference/certificates.html +certificate_file: "./_wildcard.localhost.pomerium.io.pem" +certificate_key_file: "./_wildcard.localhost.pomerium.io-key.pem" # identity provider settings : https://www.pomerium.io/docs/identity-providers.html idp_provider: google idp_client_id: REPLACE_ME idp_client_secret: REPLACE_ME +# Generate 256 bit random keys e.g. `head -c32 /dev/urandom | base64` +cookie_secret: WwMtDXWaRDMBQCylle8OJ+w4kLIDIGd8W3cB4/zFFtg= + +# https://www.pomerium.io/configuration/#policy policy: - - from: https://httpbin.corp.beyondperimeter.com - to: http://httpbin - allowed_domains: - - pomerium.io - - from: https://external-httpbin.corp.beyondperimeter.com + - from: https://httpbin.localhost.pomerium.io to: https://httpbin.org - allow_public_unauthenticated_access: true + allowed_users: + - bdd@pomerium.io diff --git a/docs/docs/community/contributing.md b/docs/docs/community/contributing.md index 19afbf2f2..a505ce44a 100644 --- a/docs/docs/community/contributing.md +++ b/docs/docs/community/contributing.md @@ -39,149 +39,11 @@ Here are some of the expectations we have of contributors: - **Recommended reading** - - [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments) for an idea of what we look for in good, clean Go code + - [CodeReviewComments](https://github.com/golang/go/wiki/CodeReviewComments) - [Linus Torvalds describes a good commit message](https://gist.github.com/matthewhudson/1475276) - [Best Practices for Maintainers](https://opensource.guide/best-practices/) - [Shrinking Code Review](https://alexgaynor.net/2015/dec/29/shrinking-code-review/) -## Code - -### Build From Source - -The following quick-start guide covers how to retrieve and build Pomerium from its source-code as well as how to run Pomerium using a minimal but complete configuration. One of the benefits of compiling from source is that Go supports building static binaries for a [wide array of architectures and operating systems](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63) -- some of which may not yet be supported by Pomerium's official images or binaries. - -#### Prerequisites - -- [git](https://git-scm.com/) -- [go](https://golang.org/doc/install) programming language -- A configured [identity provider] -- A [wild-card TLS certificate] - -#### Download - -Retrieve the latest copy of pomerium's source code by cloning the repository. - -```bash -git clone https://github.com/pomerium/pomerium.git $HOME/pomerium -``` - -#### Make - -Build Pomerium from source in a single step using make. - -```bash -cd $HOME/pomerium -make -``` - -[Make] will run all the tests, some code linters, then build the binary. If all is good, you should now have a freshly builtPpomerium binary for your architecture and operating system in the `pomerium/bin` directory. - -#### Configure - -Pomerium supports setting [configuration variables] using both environmental variables and using a configuration file. - -#### Configuration file - -Create a config file (`config.yaml`). This file will be use to determine Pomerium's configuration settings, routes, and access-policies. Consider the following example: - -<<< @/docs/configuration/examples/config/config.minimal.yaml - -#### Environmental Variables - -As mentioned above, Pomerium supports mixing and matching where configuration details are set. For example, we can specify our secret values and domains certificates as [environmental configuration variables]. - -<<< @/docs/configuration/examples/config/config.minimal.env - -#### Run - -Finally, source the the configuration `env` file and run Pomerium specifying the configuration file `config.yaml`. - -```bash -source ./env -./bin/pomerium -config config.yaml -``` - -#### Navigate - -Browse to `external-httpbin.your.domain.example`. Connections between you and [httpbin] will now be proxied and managed by Pomerium. - -### Offline Domains (OPTIONAL) - -Publicly resolvable domains are central in how Pomerium works. For local offline development, we'll have to do some additional configuration to mock that public workflow on our local machine. - -The following guide assumes you do _not_ want to expose your development server to the public internet and instead want to do everything, with the exception of identity provider callbacks, locally. - -If you are comfortable with a public development configuration, see the Synology quick-start which covers how to set up your network, domain, and retrieve wild-card certificates from LetsEncrypt, the only difference being you would route traffic to your local development machine instead of the docker image. - -#### Pick an identity provider friendly domain name - -Though typically you would want to use one of the TLDs specified by [RFC-2606](http://tools.ietf.org/html/rfc2606) for testing, unfortunately, google explicitly does not support oauth calls to test domains. As such, it's recommended to use a domain you control using a wildcard-subdomain that you know will not be used. - -If you do not control a domain, you can use `*.localhost.pomerium.io` which I've established for this use and has a [public A record](https://en.wikipedia.org/wiki/List_of_DNS_record_types) pointing to localhost. - -#### Wildcard domain resolution with `dnsmasq` - -If you are on a plane (for example), you may not be able to access public DNS. Unfortunately, `/etc/hosts` does not support wildcard domains and would require you specifying a new entry for each Pomerium managed route. The workaround is to use [dnsmasq](https://en.wikipedia.org/wiki/Dnsmasq) locally which _does_ support local resolution of wildcard domains. - -#### OSX - -1. Install `brew update && brew install dnsmasq` -2. Edit `/usr/local/etc/dnsmasq.conf` to tell dnsmasq to resolve your test domains. - -```bash -echo 'address=/.localhost.pomerium.io/127.0.0.1' > $(brew --prefix)/etc/dnsmasq.conf -``` - -```bash -sudo mkdir -pv /etc/resolver -sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/localhost.pomerium.io' -``` - -1. Restart `dnsmasq` - -```bash -sudo brew services restart dnsmasq -``` - -1. Tell OSX to use `127.0.0.1` as a the primary DNS resolver (followed by whatever public DNS you are using). ![osx dns resolution](./img/local-development-osx-dns.png) - -#### Locally trusted wildcard certificates - -In production, we'd use a public certificate authority such as LetsEncrypt. For local development, enter [mkcert](https://mkcert.dev/) which is a "simple zero-config tool to make locally trusted development certificates with any names you'd like." - -1. Install `mkcert`. - -```bash -go get -u github.com/FiloSottile/mkcert -``` - -1. Bootstrap `mkcert`'s root certificate into your operating system's trust store. - -```bash -mkcert -install -``` - -1. Create your wildcard domain. - -```bash -mkcert "*.localhost.pomerium.io" -``` - -1. Viola! Now you can use locally trusted certificates with pomerium! - -| Setting | Certificate file location | -| ---------------------------- | ------------------------------------------- | -| `certificate_file` | `./_wildcard.localhost.pomerium.io-key.pem` | -| `certificate_key_file` | `./_wildcard.localhost.pomerium.io.pem` | -| `certificate_authority_file` | `$(mkcert -CAROOT)/rootCA.pem` | - -See also: - -- [Set up a local test domain with dnsmasq](https://github.com/aviddiviner/til/blob/master/devops/set-up-a-local-test-domain-with-dnsmasq.md) -- [USE DNSMASQ INSTEAD OF /ETC/HOSTS](https://www.stevenrombauts.be/2018/01/use-dnsmasq-instead-of-etc-hosts/) -- [How to setup wildcard dev domains with dnsmasq on a mac](https://hedichaibi.com/how-to-setup-wildcard-dev-domains-with-dnsmasq-on-a-mac/) -- [mkcert](https://github.com/FiloSottile/mkcert) is a simple tool for making locally-trusted development certificates - ## Docs Pomerium's documentation is available at . If you find a typo, feel a section could be better described, or have an idea for a totally new application or section, don't hesitate to make a pull request change. There are few ways you can do this. diff --git a/docs/docs/quick-start/from-source.md b/docs/docs/quick-start/from-source.md new file mode 100644 index 000000000..f8e350641 --- /dev/null +++ b/docs/docs/quick-start/from-source.md @@ -0,0 +1,78 @@ +--- +title: From Source +lang: en-US +meta: + - name: keywords + content: pomerium identity-access-proxy oidc reverse-proxy from-source +--- + +# From Source + +The following quick-start guide covers how to retrieve and build Pomerium from its source-code as well as how to run Pomerium using a minimal but complete configuration. One of the benefits of compiling from source is that Go supports building static binaries for a [wide array of architectures and operating systems](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63). + +## Prerequisites + +- [git](https://git-scm.com/) +- [go](https://golang.org/doc/install) programming language +- A configured [identity provider] + +## Download + +Retrieve the latest copy of pomerium's source code by cloning the repository. + +```bash +git clone https://github.com/pomerium/pomerium.git $HOME/pomerium +``` + +## Create local certs + +In production, we'd use a public certificate authority such as LetsEncrypt. For local development, we can use [mkcert](https://mkcert.dev/) to make locally trusted development certificates with any names you'd like. + +```bash +# Install mkcert. +go get -u github.com/FiloSottile/mkcert +# Bootstrap mkcert's root certificate into your operating system's trust store. +mkcert -install +# Create your wildcard domain. +# *.localhost.pomerium.io is helper domain we've hard-coded to route to localhost +mkcert "*.localhost.pomerium.io" +``` + +## Build + +Build Pomerium from source in a single step using make. + +```bash +cd $HOME/pomerium +make +``` + +[Make] 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 for your architecture and operating system in the `pomerium/bin` directory. + +## Configure + +Pomerium supports setting [configuration variables] using both environmental variables and using a configuration file. + +## Configuration file + +Create a config file (`config.yaml`). This file will be use to determine Pomerium's configuration settings, routes, and access-policies. Consider the following example: + +<<< @/docs/configuration/examples/config/config.minimal.yaml + +## Run + +Finally, run Pomerium specifying the configuration file `config.yaml`. + +```bash +make && ./bin/pomerium -config config.yaml +``` + +### Navigate + +Browse to `httpbin.localhost.pomerium.io`. Connections between you and [httpbin] will now be proxied and managed by Pomerium. + +[configuration variables]: ../../configuration/readme.md +[httpbin]: https://httpbin.org/ +[identity provider]: ../docs/identity-providers/ +[make]: https://en.wikipedia.org/wiki/Make_(software) +[wild-card tls certificate]: ../reference/certificates.md diff --git a/package.json b/package.json index 7bb3ecc1b..36c12861e 100644 --- a/package.json +++ b/package.json @@ -1,13 +1,12 @@ { "devDependencies": { - "@vuepress/plugin-google-analytics": "1.2.0", - "vuepress": "1.2.0", + "@vuepress/plugin-google-analytics": "1.3.1", + "vuepress": "1.3.1", "vuepress-plugin-sitemap": "2.3.1" }, "scripts": { "docs:dev": "vuepress dev docs", - "docs:build": "vuepress build docs", - "docs:deploy": "firebase deploy" + "docs:build": "vuepress build docs" }, "dependencies": { "esm": "3.2.25"