# Gateway with Docker

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FZdCwOSIZ90eIqXaHSQ7N%2FDocker%20Install.jpg?alt=media&#x26;token=577af308-2d82-4423-8d62-a94826e60bc6" alt=""><figcaption></figcaption></figure>

## Overview

This document contains information on how to install, configure, and update your Keeper Gateway on Docker. The Keeper Gateway container is built upon the base image of Rocky Linux 9 and it is hosted in [DockerHub](https://hub.docker.com/r/keeper/gateway).

### Prerequisites

* A Linux host with a x86 AMD processor for all PAM capabilities
* `docker` and `docker compose` installed (see [Docker Install](https://docs.keeper.io/en/keeperpam/privileged-access-manager/references/installing-docker-on-linux) for help)

***

### Create a Gateway

A new Gateway deployment can be created by clicking on **Create New** > **Gateway** from the Web Vault or Desktop App.

You can also create a Gateway and configuration file from the Commander CLI:

```
pam gateway new -n "<Gateway Name>" -a <Application Name or UID> -c b64
```

The Application names and UIDs can be found with `secrets-manager app list`

### Installation Options

Keeper provides 2 ways of setting up the Gateway:

* [Auto Docker Installation](#auto-docker-installation)
* [Manual Installation](#manual-installation)

***

### Option 1: Auto Docker Installation

Keeper's automatic installer will set up the environment for you.

{% stepper %}
{% step %}
**Create a Docker Gateway and Copy the Installation Command**

Create a new Gateway with either the [Gateway Wizard](https://docs.keeper.io/en/keeperpam/privileged-access-manager/getting-started/one-time-access-token#using-the-gateway-wizard) or using [Keeper Secrets Manager](https://docs.keeper.io/en/keeperpam/privileged-access-manager/getting-started/one-time-access-token#using-keeper-secrets-manager) for the Docker Operating System.

You will be provided with an installation command to paste into your Linux host.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2F6zwK3zKAu6TgLk9BjNkQ%2Finstallerscreen.png?alt=media&#x26;token=238369f1-e1ee-4954-8ef0-dc2c1b62e09b" alt=""><figcaption></figcaption></figure>
{% endstep %}

{% step %}
**Run the Installation Command**

On your Linux host, navigate to your desired working directory and execute the copied installation command.

The installation command will:

* Install Docker and Docker Compose (if needed)
* Generate the Docker Compose, Seccomp and AppArmor files.
* Prepare the service
  {% endstep %}

{% step %}
**Start the Service**

Ensure that you are located in the folder where the `docker-compose.yml`, `docker-seccomp.json` and `gateway-apparmor-profile` files are saved.

Executing the following command will run the Keeper Gateway in the background:

```bash
docker compose up -d
```

{% endstep %}
{% endstepper %}

***

### Option 2: Manual Docker Installation

If you prefer to set up the Docker environment yourself, follow the instructions below.

{% stepper %}
{% step %}
**Docker Compose**

A Docker Compose file is provided through the Vault UI. Typically this file would be saved in your local environment as `docker-compose.yml` in your preferred folder. An example is below:

```
services:
      keeper-gateway:
        platform: linux/amd64
        image: keeper/gateway:latest
        shm_size: 16g
        restart: unless-stopped
        security_opt:
          - seccomp:docker-seccomp.json
          - apparmor:gateway-apparmor-profile
        environment:
          LC_ALL: "C.UTF-8"
          ACCEPT_EULA: Y
          GATEWAY_CONFIG: XXXXXXXXXXXXXXXXX
```

{% hint style="warning" %}
The `shm_size` is a critical parameter. We recommend maximizing this value to at least half of the available server memory. Production gateways should have as much memory and CPU allocated as possible. When using remote browser isolation sessions, Chromium uses a lot of memory for each process.
{% endhint %}

The only required environment variable setting is `GATEWAY_CONFIG` which is the resulting base64-encoded configuration provided by Keeper when creating a Gateway.
{% endstep %}

{% step %}
**Seccomp File**

The file called `docker-seccomp.json` needs to be downloaded and placed in the same folder as your Docker Compose file.

[Download File](https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/docker-seccomp.json) or:

{% code overflow="wrap" %}

```bash
curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/docker-seccomp.json
```

{% endcode %}
{% endstep %}

{% step %}
**AppArmor Profile (Required for Ubuntu/Debian distributions)**

{% hint style="info" %}
This step is **required** for Ubuntu and Debian-based distributions.\
For all other Linux distributions (RHEL, CentOS, Fedora, Amazon Linux, etc.) skip to Step 4.
{% endhint %}

The file called `gateway-apparmor-profile` needs to be placed in the same folder as your Docker Compose file.

[Download File](https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/gateway-apparmor-profile) or:

{% code overflow="wrap" %}

```bash
curl -O https://raw.githubusercontent.com/Keeper-Security/KeeperPAM/refs/heads/main/gateway/gateway-apparmor-profile
```

{% endcode %}

Activate the apparmor config

```
sudo apparmor_parser -r gateway-apparmor-profile
sudo cp gateway-apparmor-profile /etc/apparmor.d/
```

{% endstep %}

{% step %}
**Start the Service**

Ensure that you are located in the folder where the `docker-compose.yml` is saved. Executing the following command will run the Keeper Gateway container in the background, as specified in the docker compose file:

```bash
docker compose up -d
```

{% endstep %}
{% endstepper %}

{% hint style="info" %}
Note: There's a typo in Vault version 17.4 that references `gateway-app-armor-profile` instead of `gateway-apparmor-profile` in the provided docker-compose.yml file when creating a new gateway.\
\
To fix this issue, remove the extra dash. It needs to be labeled as `gateway-apparmor-profile`
{% endhint %}

***

### **Logging**

When running the latest version of the Keeper Gateway, you'll see the output in the logs like below:

```
docker compose logs keeper-gateway
```

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FuLk5SZEF58TniLsYGKII%2FScreenshot%202024-12-27%20at%209.29.10%E2%80%AFAM.png?alt=media&#x26;token=e9a6d790-80d2-4bdc-8ebe-a08cd88119a5" alt=""><figcaption><p>Docker Logs from Keeper Gateway</p></figcaption></figure>

On the Vault UI in the **Secrets Manager** > **Applications** > **Gateways** screen, the Gateway will show Online.

<figure><img src="https://762006384-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F-MJXOXEifAmpyvNVL1to%2Fuploads%2FpdccmtxqPQDtpeTrL7gh%2FScreenshot%202024-12-27%20at%209.38.24%E2%80%AFAM.png?alt=media&#x26;token=3c64598f-c12e-4e6a-9fa9-9a948c605397" alt=""><figcaption><p>Gateway is Online</p></figcaption></figure>

***

### Gateway Service Management

#### Starting the service

```
docker compose up -d
```

#### Stopping the service

```
docker compose stop
```

#### Restarting the service

```
docker compose restart
```

#### Connecting to the Gateway container

```
docker compose exec keeper-gateway bash
```

***

### Starting the Gateway Automatically on Reboot

In the `docker-compose.yml` file, ensure that a restart policy is enabled. For example:

```
services:
  keeper-gateway:
    restart: unless-stopped
```

Adding the "restart: unless-stopped" or "restart: always" parameter in the `docker-compose.yml` file will assign a restart policy to the environment.

If you would like to force the host operating system to automatically start the Keeper Gateway on a Docker installation, follow these steps (Linux host).

First, create a file `/etc/systemd/system/keeper-gateway.service`

```
[Unit]
Description=Keeper Gateway Docker Compose
Requires=docker.service
After=docker.service

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/path/to/install
ExecStart=/usr/bin/docker compose up -d
ExecStop=/usr/bin/docker compose down
User=myusername
Group=docker

[Install]
WantedBy=multi-user.target
```

NOTE:

* Replace `/path/to/install` with the path to your docker-compose.yml
* Replace `myusername` user with your user running Docker
* Replace `docker` group with your defined group
* Ensure the binary path for ExecStart and ExecStop are correct

Then enable the service:

```
sudo systemctl daemon-reload
sudo systemctl enable keeper-gateway.service
sudo systemctl start keeper-gateway.service
```

Important: Ensure that the apparmor file is loaded up and available on reboot

```
sudo apparmor_parser -r gateway-apparmor-profile
sudo cp gateway-apparmor-profile /etc/apparmor.d/
```

After a reboot, verify that it's running:

```
systemctl status keeper-gateway
```

***

### Debugging

If you need to enable verbose debug logs on the Gateway, enable debug logging by adding the below `environment` section variables to your Docker Compose file:

```
services:
      keeper-gateway:
        .....
        environment:
          LC_ALL: "C.UTF-8"
          KEEPER_GATEWAY_LOG_LEVEL: "debug" # logs for gateway
          LOG_LEVEL: "debug" # logs for guacd
```

After changing the log level, apply the changes to the docker

```
docker compose up -d
```

Tail the logs of the Keeper Gateway using this command:

```
docker compose logs -f keeper-gateway
```

***

### **Updating**

Executing the following command will update the Keeper Gateway container to the latest version and restart the service:

```sh
docker compose pull
docker compose up -d
```

***

### **Health Checks**

To monitor the Gateway service, you can configure health checks that expose its operational status. These checks are useful for Docker orchestration, load balancing, and automated monitoring. See the [Health Check section](https://docs.keeper.io/en/keeperpam/privileged-access-manager/getting-started/gateways/health-checks) for full setup details and examples.

***

### Connecting to the Host Instance

A very useful capability of the Keeper Gateway is being able to open connections and tunnels to the host machine. By adding the `extra_hosts` section to your docker compose file with a value of `host.docker.internal:host-gateway`, you can open sessions directly to the host.

Example docker compose with the Gateway container:

```
services:
      keeper-gateway:
        platform: linux/amd64
        image: keeper/gateway:latest
        shm_size: 16g
        restart: always
        extra_hosts:
          - "host.docker.internal:host-gateway"
        security_opt:
          - seccomp:./docker-seccomp.json
          - apparmor=./gateway-apparmor-profile
        environment:
          LC_ALL: "C.UTF-8"
          ACCEPT_EULA: Y
          GATEWAY_CONFIG: xxxxxxxx
```

Enabling this option allows you to establish a Connection to the host. For example, to open an SSH connection:

* Create a [PAM User](https://docs.keeper.io/en/keeperpam/privileged-access-manager/getting-started/pam-resources/pam-user) record with the SSH private key
* Create a [PAM Machine](https://docs.keeper.io/keeperpam/privileged-access-manager/getting-started/pam-resources/pam-machine) record with the hostname to `host.docker.internal` and port `22`
* Activate the [SSH connection](https://docs.keeper.io/en/keeperpam/privileged-access-manager/connections/session-protocols/ssh-connections) in PAM settings referencing the PAM User

### Upgrading the Keeper Gateway service through the host

If you use KeeperPAM to SSH over to the host service, you can upgrade the container by running the container update of the gateway in the background:

```
docker compose pull
nohup docker compose up -d keeper-gateway &
```

### Network Requirements

The Keeper Gateway establishes outbound-only connections and does not require any inbound firewall rules. The following outbound connections must be allowed:

<table><thead><tr><th width="310.1015625">Destination Endpoint</th><th>Ports Needed</th><th>More Info</th></tr></thead><tbody><tr><td><p><strong>Keeper Cloud</strong><br><code>keepersecurity.[x]</code></p><p>Endpoints:</p><p>US: <code>.com</code></p><p>EU: <code>.eu</code></p><p>AU: <code>.com.au</code></p><p>JP: <code>.jp</code></p><p>CA: <code>.ca</code></p><p>US_GOV: <code>.us</code></p></td><td>TLS Port 443</td><td>Communicates with Keeper Cloud to access target infrastructure via native protocols (e.g., SSH, RDP)</td></tr><tr><td><p><strong>Keeper Router</strong><br><code>connect.keepersecurity.[x]</code></p><p>Endpoints:</p><p>US: <code>.com</code></p><p>EU: <code>.eu</code></p><p>AU: <code>.com.au</code></p><p>JP: <code>.jp</code></p><p>CA: <code>.ca</code></p><p>US_GOV: <code>.us</code></p></td><td>TLS Port 443</td><td>Communicates with Keeper Router to establish secure, real-time WebSocket connections</td></tr><tr><td><p><strong>Keeper Stun/Turn Service</strong></p><p><code>krelay.keepersecurity.[x]</code></p><p>Endpoints:</p><p>US: <code>.com</code></p><p>EU: <code>.eu</code></p><p>AU: <code>.com.au</code></p><p>JP: <code>.jp</code></p><p>CA: <code>.ca</code></p><p>US_GOV: <code>.us</code></p></td><td>TCP and UDP opened on Port 3478<br><br>Outbound access to TCP and UDP ports 49152 through 65535<br></td><td>Facilitates secure and encrypted WebRTC connections between end-user's vault and target systems via the Gateway</td></tr></tbody></table>

The Gateway preserves zero knowledge by performing all encryption and decryption of data locally. Keeper Secrets Manager APIs are used to communicate with the Keeper cloud.

The initial Gateway installation files are retrieved from keepersecurity.com. After installation, the Gateway’s steady-state outbound connections can be restricted to the regional endpoints as documented.

***

### Managing Disk Space

Over time, as new versions of the Gateway are deployed, old Docker images may accumulate on the host server. This can consume a significant amount of disk space. To ensure smooth operation and avoid storage issues, we recommend periodically checking your available disk space and removing unused Docker images.

#### Checking Disk Space Usage

To view your current disk usage, run the following command on your Keeper Gateway server:

```bash
df -h
```

This command displays available disk space on all mounted filesystems in a human-readable format. Pay particular attention to the partition where Docker stores its data (typically `/var/lib/docker`).

If you notice the disk space running low (for example, more than 80–90% full), it’s a good idea to clean up old Docker images.

#### Cleaning Up Old Docker Images

When you update the Keeper Gateway, Docker keeps older images on your system. To remove all unused Docker images, you can use the following command:

```bash
docker image prune -a
```

* The `-a` flag ensures that **all** unused images are deleted (not just dangling ones).
* You may be prompted to confirm the action — type `y` when prompted.

**Example output:**

```
WARNING! This will remove all images without at least one container associated to them.
Are you sure you want to continue? [y/N] y
Deleted Images:
...
Total reclaimed space: 4.8GB
```

This operation safely removes old images that are no longer used by any running containers.

***

### References:

* DockerHub listing: <https://hub.docker.com/r/keeper/gateway>
* Quick reference for [Installing Docker](https://docs.keeper.io/en/keeperpam/privileged-access-manager/references/installing-docker-on-linux)[ and Docker Compose on Linux](https://docs.keeper.io/en/keeperpam/privileged-access-manager/references/installing-docker-on-linux)