mirror of
https://github.com/pomerium/pomerium.git
synced 2025-05-10 07:37:33 +02:00
docs: make from source quickstart (#519)
- move building from so - remove dnsmasq instructions Signed-off-by: Bobby DeSimone <bobbydesimone@gmail.com>
This commit is contained in:
Bobby DeSimone
GitHub
parent
3d211a8931
commit
27909f22ce
5 changed files with 99 additions and 152 deletions
|
|
@ -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"
|
||||
]
|
||||
},
|
||||
{
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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). 
|
||||
|
||||
#### 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 <https://www.pomerium.io/docs>. 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.
|
||||
|
|
|
|||
78
docs/docs/quick-start/from-source.md
Normal file
78
docs/docs/quick-start/from-source.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue