Pomerium using Docker

In this quick-start document, we'll create a minimal but complete environment for running Pomerium with containers.

Prerequisites

• A configured identity provider
• Docker and docker-compose

Configure

Create a configuration file (e.g. config.yaml) for defining 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       #
# You do not need to generate your own certificates. We auto-generate and populate # 
# the certificate variables below with an X.509 public and private key.            #
####################################################################################
# certificate_file: /pomerium/cert.pem
# certificate_key_file: /pomerium/privkey.pem

##################################################################################
# Identity provider settings : https://www.pomerium.com/docs/identity-providers/ #
# The keys required in this section vary depending on your IdP. See the          #
# appropriate docs for your IdP to configure Pomerium accordingly.               #
##################################################################################
idp_provider: google
idp_client_id: REPLACE_ME
idp_client_secret: REPLACE_ME

##################################################################################
# Cookie secret settings: https://www.pomerium.com/docs/reference/cookie-secret  #
# You do not need to generate a cookie secret. We auto-generate and populate the #
# cookie secret for you below to encrypt and sign session cookies.               #
##################################################################################
# cookie_secret: V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=

# https://pomerium.com/reference/#routes
routes:
  - from: https://verify.localhost.pomerium.io
    to: http://verify:8000
    policy:
      - allow:
          or:
            - email:
                is: user@example.com
    pass_identity_headers: true

Note

Keep track of the path to this file, relative to the docker-compose.yml file created in the next step. docker-compose.yml will need the correct relative path to your config.yaml.

Create or copy the following docker-compose.yaml file and modify it to match your configuration, including the correct paths to your config.yaml and certificate files:

version: "3"
services:
  pomerium:
    image: pomerium/pomerium:latest
    volumes:
      #################################################################################
      # Certificate settings: https://www.pomerium.com/docs/reference/certificates    #
      # You do not need to mount your certificate files. We auto-generate certificate #
      # files in your config.yaml file that will mount on your Docker container.      #
      #################################################################################
      # - ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro
      # - ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/privkey.pem:ro

      ## Mount your config file : https://www.pomerium.com/docs/reference/
      - ./config.yaml:/pomerium/config.yaml:ro
    ports:
      - 443:443

  ## https://verify.localhost.pomerium.io --> Pomerium --> http://verify
  verify:
    image: pomerium/verify:latest
    expose:
      - 8000

Run

Run docker compose:

docker-compose up

Docker will automatically download the required container images for Pomerium and verify. Then, Pomerium will run with the configuration details set in the previous steps.

You should now be able to access the routes (e.g. https://verify.localhost.pomerium.io) as specified in your policy file.

Handle self-signed certificate warning

When navigating to the https://verify.localhost.pomerium.io route defined in your policy, you may encouter the following self-signed certificate warning:

To resolve this error:

1. Click anywhere inside the browser window
2. Type thisisunsafe
3. Make sure Reload is selected
4. Press ENTER

Your browser will redirect you to the route defined in your policy:

Next Steps

Now, you can experiment with adding services to Docker and defining routes and policies for them in Pomerium. See Guides for help or inspiration.

caution

This is a test environment! If you followed all the steps in this doc your Pomerium environment is not using trusted certificates. Remember to use a valid certificate solution before moving this configuration to a production environment. See Certificates for more information.