This document 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.
Retrieve the latest copy of pomerium's source code by cloning the repository.
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 to make locally trusted development certificates with any names you'd like.
# Install mkcert.
go install filippo.io/mkcert@latest
# Bootstrap mkcert's root certificate into your operating system's trust store.
# Create your wildcard domain.
# *.localhost.pomerium.io is helper domain we've hard-coded to route to localhost
Build Pomerium from source in a single step using 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
If you don't have the prerequisites for the tests (Docker, Redis, etc) locally, you can instead run
make build to just create the binary.
Pomerium supports setting configuration variables using both environmental variables and using a 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:
# See detailed configuration settings : https://www.pomerium.com/docs/reference/
# this is the domain the identity provider will callback after a user authenticates
# certificate settings: https://www.pomerium.com/docs/reference/certificates.html
# REMOVE FOR PRODUCTION
# If you're using mkcert to test Pomerium locally, comment the autocert keys and uncomment
# the keys below, adjusting for your mkcert path:
# certificate_file: /home/user/.local/share/mkcert/rootCA.pem
# certificate_key_file: /user/alex/.local/share/mkcert/rootCA-key.pem
# identity provider settings : https://www.pomerium.com/docs/identity-providers.html
# Generate 256 bit random keys e.g. `head -c32 /dev/urandom | base64`
- from: https://verify.localhost.pomerium.io
Finally, run Pomerium specifying the configuration file
./bin/pomerium -config config.yaml
verify.localhost.pomerium.io. Connections between you and verify will now be proxied and managed by Pomerium.