Skip to main content

Building Pomerium From Source

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.

Prerequisites​

Download​

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.
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.

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.

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.

Configure​

Pomerium supports setting configuration variables using both environmental variables and using a configuration file. Here, we'll use a 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
authenticate_service_url: https://authenticate.localhost.pomerium.io

# certificate settings:  https://www.pomerium.com/docs/reference/certificates.html
autocert: true
# REMOVE FOR PRODUCTION
autocert_use_staging: true

# 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
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://pomerium.io/reference/#routes
routes:
  - from: https://verify.localhost.pomerium.io
    to: https://verify.pomerium.com
    policy:
      - allow:
          or:
            - email:
                is: user@example.com
    pass_identity_headers: true

Run​

Finally, run Pomerium specifying the configuration file config.yaml.

./bin/pomerium -config config.yaml

Browse to verify.localhost.pomerium.io. Connections between you and verify will now be proxied and managed by Pomerium.