Docker Installation

Overview

This document contains information on how to install, configure, and update your Keeper Gateway on Docker. The Docker container is built upon the base image of Rocky Linux 8 and it is hosted in DockerHub.

Prerequisites

• A Linux host with a x86 AMD processor

• docker and docker-compose installed (see Docker Install for help)

Note: The syntax is docker-compose for servers, but on a local Docker Desktop it might be docker compose (with no space).

Create a Gateway

A new Gateway deployment can be created by clicking on Create New > Gateway from the Web Vault or Desktop App (version 17.1 or newer required).

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

services:
      keeper-gateway:
        platform: linux/amd64
        image: keeper/gateway:latest
        shm_size: 2g
        security_opt:
          - "seccomp:docker-seccomp.json"
        environment:
          ACCEPT_EULA: Y
          GATEWAY_CONFIG: XXXXXXXXXXXXXXXXX

docker compose up -d

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

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

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

Enable 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:
          KEEPER_GATEWAY_LOG_LEVEL: "debug" # logs for gateway
          LOG_LEVEL: "debug" # logs for guacd

After debug is enabled, restart the service with docker compose restart

Tailing the logs:

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:

docker compose pull
docker compose down
docker compose up -d

Start up automatically

Adding the "restart" parameter in the docker-compose.yml file will assign a restart policy to the environment:

restart: always

Starting Gateway on Reboot

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 .service file in /etc/systemd/system/keeper-gateway.service

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

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/home/ec2-user
ExecStart=/usr/local/bin/docker-compose up -d
ExecStop=/usr/local/bin/docker-compose down
User=ec2-user
Group=docker

[Install]
WantedBy=multi-user.target

NOTE:

• Replace /home/ec2-user with the path to your docker-compose.yml

• Replace ec2-user user with your user running Docker

• Replace docker group with your defined group

Then enable the service:

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

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 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: 2g
        restart: always
        extra_hosts:
          - "host.docker.internal:host-gateway"
        security_opt:
          - "seccomp:docker-seccomp.json"
        environment:
          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 record with the SSH private key

• Create a PAM Machine record with the hostname to host.docker.internal and port 22

• Activate the SSH connection 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 Configuration

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

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.

References:

• DockerHub listing: https://hub.docker.com/r/keeper/gateway

• Quick reference for Installing Docker and Docker Compose on Linux