Pomerium offers several ways to install the Enterprise Console to suit your organization's needs. Watch the video below for a quick primer on deploying Pomerium Core and Enterprise, or view the sections below for specific installation instructions.

## Install Pomerium Enterprise

**Docker:**

The Pomerium Enterprise Docker image is available at a private Cloudsmith Docker registry.

To access the Pomerium Enterprise Docker image:

1. In your terminal, run the following command:

```shell
docker login docker.cloudsmith.io
```

2. Enter your **username** and **password**:

```shell
 % docker login docker.cloudsmith.io
Username: <username>
Password: <password>
```

3. Pull a specific tagged release of the Pomerium Enterprise image:

```shell
docker pull docker.cloudsmith.io/pomerium/enterprise/pomerium-console:${vX.X.X}
```

See the [Enterprise Quickstart](https://www.pomerium.com/docs/deploy/enterprise/quickstart.md) for instructions to run and deploy the Enterprise Console with Docker Compose.

**OS Packages:**

You can find the latest `rpm` and `deb` packages on [Cloudsmith](https://cloudsmith.io/~pomerium/repos/pomerium/groups/) or download them from the [GitHub releases](https://github.com/pomerium/pomerium/releases) page.

| **Supported Operating Systems** | **Supported Architectures** |
| :------------------------------ | :-------------------------- |
| `linux`                         | `amd64`                     |
| `darwin`                        | `arm64`                     |

### DEB installation

To automatically configure the repository for Debian and Ubuntu distributions:

1. Replace `[access-key]` in the command below and run it:

```bash
curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.deb.sh' \
| sudo -E bash
```

To manually configure the repository, do the following:

```bash
apt-get install -y debian-keyring  # debian only
apt-get install -y debian-archive-keyring  # debian only
apt-get install -y apt-transport-https
# For Debian Stretch, Ubuntu 16.04 and later
keyring_location=/usr/share/keyrings/pomerium-enterprise-archive-keyring.gpg
# For Debian Jessie, Ubuntu 15.10 and earlier
keyring_location=/etc/apt/trusted.gpg.d/pomerium-enterprise.gpg
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key' |  gpg --dearmor >> ${keyring_location}
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.deb.txt?distro=debian&codename=wheezy&component=main' > /etc/apt/sources.list.d/pomerium-enterprise.list
sudo chmod 644 ${keyring_location}
sudo chmod 644 /etc/apt/sources.list.d/pomerium-enterprise.list
apt-get update
```

2. Update `apt` and install Pomerium Enterprise:

```bash
sudo apt update; sudo apt install pomerium-console
```

After you've installed the package, enable and start the system service:

```bash
sudo systemctl enable --now pomerium-console
```

### RPM installation

To automatically configure the repository for RHEL based distributions:

1. Replace \[access-key] in the command below and run it:

```bash
curl -1sLf \
'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/setup.rpm.sh' \
| sudo -E bash
```

To manually configure the repository, run:

```bash
yum install yum-utils pygpgme
rpm --import 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/gpg.B1D0324399CB9BC3.key'
curl -1sLf 'https://dl.cloudsmith.io/[access-key]/pomerium/enterprise/config.rpm.txt?distro=el&codename=9' > /tmp/pomerium-enterprise.repo
yum-config-manager --add-repo '/tmp/pomerium-enterprise.repo'
yum -q makecache -y --disablerepo='*' --enablerepo='pomerium-enterprise'
```

2. Update `yum` and install Pomerium Enterprise:

```bash
yum -y install pomerium-console
```

After you've installed the package, enable and start the system service:

```bash
sudo systemctl enable --now pomerium-console
```

**Kubernetes with Kustomize:**

These steps cover installing Pomerium Enterprise into your existing Kubernetes cluster. It's designed to work with an existing cluster running Pomerium, as described in [Pomerium Kustomize]. Follow that document before continuing here.

The assumption is that Pomerium is installed into the `pomerium` namespace, and Enterprise would be installed into the `pomerium-enterprise` namespace.

## Prepare Core

The below command will expose the Pomerium Core Databroker gRPC interface.

```console
kubectl apply -k github.com/pomerium/documentation/k8s/core\?ref=0-31-0
```

## Deploy Enterprise Console

```console
kubectl apply -k github.com/pomerium/documentation/k8s/console\?ref=0-31-0
```

The Enterprise Console need be configured before it becomes fully operational.

## Create Cloudsmith Directory Secret

```console
kubectl create secret docker-registry pomerium-enterprise-docker \
    --namespace pomerium-enterprise \
    --docker-server=docker.cloudsmith.io \
    --docker-username=pomerium/enterprise \
    --docker-password="your password provided by Pomerium Sales"
```

## Configure Enterprise Console

Create a `config` directory, and fill in the configuration parameters for the following template files:

See [Environment Variables] for Config and Secret keys description.

Create [Ingress] for Console.

```console

kubectl apply -k ./config

```

[pomerium kustomize]: https://www.pomerium.com/docs/deploy/k8s/install.md

[environment variables]: https://www.pomerium.com/docs/deploy/enterprise/configure.md

[ingress]: https://www.pomerium.com/docs/deploy/k8s/ingress.md

**Kubernetes with Terraform:**

You can deploy Pomerium Enterprise to Kubernetes using Terraform modules from the [`pomerium/install`](https://github.com/pomerium/install) repository. This approach uses two modules:

1. **Ingress Controller** — deploys Pomerium Core as a Kubernetes ingress controller
2. **Enterprise Console** — deploys the Pomerium Enterprise Console, connecting it to the ingress controller

Keep installation and [configuration](https://www.pomerium.com/docs/deploy/terraform.md) in separate Terraform runs. The Pomerium Terraform provider must connect to a running Enterprise Console, so if Pomerium is misconfigured or an essential component (such as the console database) is down, all dependent configuration resources will fail and the entire `terraform plan` / `terraform apply` will be blocked.

### Prerequisites

- A Kubernetes cluster with a configured Terraform [Kubernetes provider](https://registry.terraform.io/providers/hashicorp/kubernetes/latest)
- [Terraform](https://www.terraform.io/downloads) >= 1.0
- A PostgreSQL database for the Enterprise Console
- A Pomerium Enterprise license key and Cloudsmith registry credentials

### Required Providers

```hcl
terraform {
  required_providers {
    kubernetes = {
      source  = "hashicorp/kubernetes"
      version = "~> 2.0"
    }
    # Required by the ingress-controller module
    tls = {
      source  = "hashicorp/tls"
      version = "~> 4.0"
    }
    random = {
      source  = "hashicorp/random"
      version = "~> 3.0"
    }
    kubectl = {
      source  = "gavinbunney/kubectl"
      version = ">= 1.7.0"
    }
  }
}
```

### Deploy the Ingress Controller

The ingress controller module is an all-in-one deployment of Pomerium Core and the ingress controller. It creates the following Kubernetes resources: Namespace, CRDs, RBAC (ClusterRole, ClusterRoleBinding, ServiceAccounts), IngressClass, Deployment, Services, and Secrets.

```hcl
module "pomerium_ingress_controller" {
  source = "git::https://github.com/pomerium/install.git//ingress-controller/terraform?ref=main"

  namespace_name    = "pomerium"
  enable_databroker = true

  config = {
    # Reference TLS certificates available in the namespace
    certificates = ["pomerium/wildcard-tls"]
    # See https://www.pomerium.com/docs/k8s/reference for all options
  }
}
```

See the [ingress-controller module variables](https://github.com/pomerium/install/tree/main/ingress-controller/terraform) for a full list of configuration options, including identity provider settings, resource limits, and proxy service type.

### Deploy the Enterprise Console

The enterprise console module deploys the Pomerium Enterprise Console and connects it to the ingress controller using shared secrets.

```hcl
module "pomerium_enterprise_console" {
  source = "git::https://github.com/pomerium/install.git//enterprise/terraform/kubernetes?ref=main"

  # Secrets from the ingress controller module
  shared_secret_b64 = module.pomerium_ingress_controller.shared_secret_b64
  signing_key_b64   = module.pomerium_ingress_controller.signing_key_b64

  # Namespace where Pomerium Core is deployed
  core_namespace_name = "pomerium"

  # Enterprise image registry credentials
  image_registry_password = var.cloudsmith_password

  # Enterprise license
  license_key = var.pomerium_license_key

  # PostgreSQL database connection string
  database_url = "postgres://console:${var.db_password}@db-host:5432/pomerium-enterprise?sslmode=require"

  # Console web UI and API ingress configuration
  console_ingress = {
    dns         = "console.example.com"
    annotations = {}
  }
  console_api_ingress = {
    dns         = "console-api.example.com"
    annotations = {}
  }

  # Initial administrator emails for console bootstrap
  administrators = ["admin@example.com"]

  # Sidecar containers (e.g. cloud-sql-proxy for GCP Cloud SQL)
  sidecars = []

  depends_on = [module.pomerium_ingress_controller]
}
```

See the [enterprise console module variables](https://github.com/pomerium/install/tree/main/enterprise/terraform/kubernetes) for a full list of configuration options, including resource limits, clustered databroker settings, and observability options.

### DNS Records

After deployment, point your console DNS records to the ingress controller's proxy service load balancer IP:

```hcl
data "kubernetes_service" "pomerium_proxy" {
  metadata {
    name      = "pomerium-proxy"
    namespace = "pomerium"
  }

  depends_on = [module.pomerium_ingress_controller]
}

# Create DNS records for the console and API endpoints pointing to the
# load balancer IP:
# - console.example.com     -> data.kubernetes_service.pomerium_proxy.status[0].load_balancer[0].ingress[0].ip
# - console-api.example.com -> data.kubernetes_service.pomerium_proxy.status[0].load_balancer[0].ingress[0].ip
```