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.