Skip to main content

Pomerium Core using Docker

In this quickstart guide, you'll run Pomerium Core with Docker containers.

Prerequisites​

Configure​

Create a configuration file (e.g. config.yaml) for defining Pomerium's configuration settings, routes, and access policies.

# See detailed configuration settings: https://www.pomerium.com/docs/reference/

authenticate_service_url: https://authenticate.localhost.pomerium.io

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

# Update the signing key: https://www.pomerium.com/docs/reference/signing-key
signing_key: LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSURRemVZWDZyT2tuemFnTjRJVTYxaEtRc3pzY1EvRllmbzZPcXhWd2YvdGZvQY9HQ0NxR1NNNDkKQXdFSG9VUURRE0FFc1V0V2psYXZ3eHprSU9DVUNDeFVnTDJza2NjL3QxSTFmQXlxUDgrMWw5YU1CWDlzdm1pYgpRajJxcWFUbUJZZWhuQzhmak5LODZmVXhpc3d1SXN5bnp3PT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=

# 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

Update signing key​

Generate a signing key:

# Generates an P-256 (ES256) signing key
openssl ecparam  -genkey  -name prime256v1  -noout  -out ec_private.pem
# Prints the base64 encoded value of the signing key
cat ec_private.pem | base64

Add the base64-encoded signing key to the signing_key variable in your config.yaml file.

Note

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

Copy the following docker-compose.yaml file and modify it to include the correct path to your config.yaml file:

version: "3"
networks:
  main: {}
services:
  pomerium:
    image: pomerium/pomerium:latest
    volumes:
      ## Mount your config file: https://www.pomerium.com/docs/reference/
      - ./config.yaml:/pomerium/config.yaml:ro
    ports:
      - 443:443
    ## A network alias is only required when using `localhost.pomerium.io`
    networks:
      main:
        aliases:
        - authenticate.localhost.pomerium.io
  ## https://verify.localhost.pomerium.io --> Pomerium --> http://verify
  verify:
    networks:
      main: {}
    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 encounter the following self-signed certificate warning:

proceed to verify

To resolve this error:

  1. Select Advanced
  2. Select Proceed to verify.localhost.pomerium.io (unsafe)

Your browser will redirect you to the verify route.

Under Signed Identity Token, you will see a list of JWT claims with your user details:

jwt claims

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.