Skip to main content

Run Pomerium Enterprise With Docker

Run Pomerium Enterprise with Docker containers and connect to the Console.

This guide uses our Hosted Authenticate Service. If you use our hosted service and have a license key, you can complete this guide in under 5 minutes.

See the Self-Hosted Authenticate Service page if you want to self-host Pomerium.

Prerequisites

To complete this guide, you need:

note

This guide assumes you've already registered for Pomerium Enterprise and have credentials to access the private Cloudsmith.io Docker registry, and a license key. If you haven't registered for Pomerium Enterprise, sign up here for a free trial. Then, follow the steps below to install the Enterprise Console with Docker.

Install Pomerium Enterprise with Docker
1. In your terminal, run the following command:
docker login docker.cloudsmith.io
  1. Enter your username and password:
% docker login docker.cloudsmith.io
Username: <username>
Password: <password>
  1. Pull a specific tagged release of the Pomerium Enterprise image:
docker pull docker.cloudsmith.io/pomerium/enterprise/pomerium-console:${vX.X.X}

Configure Pomerium Core

If you haven't, create a file called config.yaml and add the following code:

config.yaml
routes:
- from: https://verify.localhost.pomerium.io
to: http://verify:8000
policy:
- allow:
or:
- email:
is: user@example.com
- from: https://console.localhost.pomerium.io
to: http://pomerium_console:8701
allowed_users:
- user@example.com
pass_identity_headers: true

Replace user@example.com with your email address.

Configure Pomerium Enterprise Console

Create a file called console-config.yaml and update the following values:

administrators: admin@example.com
license_key: REPLACE_ME

You must configure at least one administrator for console access. This user (or users) can then configure additional administrators in the console UI.

Multiple administrators are defined as a comma-separated string.

Configure Docker Compose services

Create a file called docker-compose.yaml in your project's root folder and add the configuration below:

docker-compose.yaml
version: '3'
services:
pomerium:
image: pomerium/pomerium:latest
volumes:
- ./config.yaml:/pomerium/config.yaml:ro
ports:
- 443:443
environment:
- AUTHENTICATE_SERVICE_URL=https://authenticate.pomerium.app
- COOKIE_SECRET=j9jZgysWVxCs3uqbmw9a2LxWwz1ZPLKQZ8v20eoDT8Y=
- SHARED_SECRET=mxGl062SqkrbQKvqG9R2jqHqxq1Oi1BNj2AAeZHNq7c=
- DATABROKER_STORAGE_TYPE=postgres
- DATABROKER_STORAGE_CONNECTION_STRING=postgresql://postgres:postgres@database/postgres?sslmode=disable
- SIGNING_KEY=LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUc0R0N4bjlxaDBHRVZnV3VCM0VoRm51RlptZ2VkZXJsMEtLd0ZoRWo4Tk9vQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFMXFOWXNUMFpSZEVTS0djSXRqZFUxcGJZREVDTktRd2lNcmNHVFl6RUhLM1V5MnVoT1N3bgpXVGdWUHppTk4vcWozYXFJeSs3Sk55ZEFLVlo3bURPNGtnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
pomerium_console:
depends_on:
database:
condition: service_healthy
pomerium:
condition: service_started
image: docker.cloudsmith.io/pomerium/enterprise/pomerium-console:v0.22.0
command:
- 'serve'
- '--config'
- '/pomerium/console-config.yaml'
expose:
- 8701
- 9090
environment:
- AUDIENCE=console.localhost.pomerium.io
- DATABASE_ENCRYPTION_KEY=tXBj4gGDj45m8cW7ehhcy5lRuxsEeNl0X/nnsN5YJPw=
- DATABROKER_SERVICE_URL=http://pomerium:5443
- SHARED_SECRET=mxGl062SqkrbQKvqG9R2jqHqxq1Oi1BNj2AAeZHNq7c=
- DATABASE_URL=postgresql://postgres:postgres@database/postgres?sslmode=disable
- PROMETHEUS_LISTEN_ADDR=:9090
- PROMETHEUS_DATA_DIR=/data
- SIGNING_KEY=LS0tLS1CRUdJTiBFQyBQUklWQVRFIEtFWS0tLS0tCk1IY0NBUUVFSUc0R0N4bjlxaDBHRVZnV3VCM0VoRm51RlptZ2VkZXJsMEtLd0ZoRWo4Tk9vQW9HQ0NxR1NNNDkKQXdFSG9VUURRZ0FFMXFOWXNUMFpSZEVTS0djSXRqZFUxcGJZREVDTktRd2lNcmNHVFl6RUhLM1V5MnVoT1N3bgpXVGdWUHppTk4vcWozYXFJeSs3Sk55ZEFLVlo3bURPNGtnPT0KLS0tLS1FTkQgRUMgUFJJVkFURSBLRVktLS0tLQo=
volumes:
- metrics:/data:rw
- ./console-config.yaml:/pomerium/console-config.yaml:ro
database:
image: postgres:latest
restart: always
healthcheck:
test: ['CMD-SHELL', 'pg_isready -d postgres -U postgres']
interval: 5s
timeout: 5s
retries: 5
start_period: 30s
environment:
- POSTGRES_USER=postgres
- POSTGRES_PASSWORD=postgres
- POSTGRES_DB=postgres
expose:
- 5432
volumes:
- pgdata:/var/lib/postgresql/data
verify:
image: pomerium/verify:latest
expose:
- 8000
restart: always
volumes:
pgdata:
metrics:

Below are a few points to note about services running in docker-compose.yaml:

  • pomerium_console exposes ports 8701 and 9090. In your config.yaml file, you define port 8701 in a route that connects to the Pomerium Enterprise Console. Port 9090 is the default port used by Prometheus to scrape metrics.
  • The healthcheck parameter ensures the database is ready to receive requests. Without a healthcheck, other containers that depend on the database service (like Pomerium Console) will attempt to connect to the database before it is in a ready state, which will crash the container. (See the Docker healthcheck docs for more information.)

Connect to Pomerium Enterprise Console

Run docker compose up.

Go to https://console.localhost.pomerium.io to access your Console.

Next Steps

If you want to try connecting Pomerium with other services, see some of our Guides.

Did you finish this quickstart guide? We'd love to hear what you think. Get in touch with us on our Discuss forum, message us on Twitter, LinkedIn, or check out our Community page.