Docker Deployment

Deploying Commander Service Mode using Docker

Docker Deploy

The Docker container provides a streamlined way to deploy Keeper Commander Service with automatic device registration and persistent login setup.

Prerequisites

Install Docker

Pull Docker Image

Pull the latest Docker image from Docker Hub:

docker pull keeper/commander:latest

Verify the image was pulled:

docker images | grep keeper/commander

Authentication Methods

The Docker container supports four authentication methods:

Method 1: Using KSM Config File

Use Keeper Secrets Manager (KSM) config file to download the config.json configuration from a Keeper record. The container will:

Download the config.json attachment from the specified record using the mounted KSM config file
Use the downloaded config for authentication

Two approaches available:

Approach A - KSM Config Base64: Pass the KSM config base64-encoded string
Approach B - KSM Config File mounting: Mount the ksm-config.json file to the container

Method 2: Using KSM Token

Use a KSM one-time access token to download the config.json configuration from a Keeper record. The container will:

Download the config.json attachment from the specified record using the provided KSM token
Use the downloaded config for authentication

Method 3: Using Credentials

Pass credentials directly via command line arguments. The container will automatically:

Register the device with Keeper
Enable persistent login
Start the service

Method 4: Using Config File

Mount an existing Keeper configuration file to the container.

Common Setup Steps for Config File Preparation

For authentication methods that require uploading a config.json file to your vault (KSM Config File, KSM Token, and Config File authentication), follow these steps on your host machine:

Login to Keeper on your host machine:

keeper shell
# Then login with your credentials
login [email protected]

Register device:
```
this-device register
```
Enable persistent login:
```
this-device persistent-login on
```
Set timeout:
```
this-device timeout 43200
```
Upload config file: Once configured, locate the config.json file in the .keeper directory on your host machine. Upload this file as an attachment to a record within a shared folder in your vault.
Remove the original config file: After uploading, delete the config.json file from the .keeper directory on your host machine to prevent duplicate configurations with the same device token/clone code.

Run Docker Container

With KSM Config File Authentication

Approach A: Using Base64-Encoded KSM Config

For environments where mounting files is not practical (e.g., container orchestration platforms), you can pass the KSM configuration as a base64-encoded string:

Prerequisites:

Before using KSM config file authentication, you must:

Create a KSM Application in your Keeper vault
Generate a KSM config base64 value
Create a Keeper record containing your service config.json as an attachment
Share the record with your KSM application

Setup Steps:

Complete the Common Setup Steps for Config File Preparation
Create KSM Configuration File:
- Go to Vault → Secrets Manager → My Applications.
- Create new application and provide access to your shared folder.
- Select your application, go to Devices, and click on Add Device.
- Use Configuration File method and select Base64 as configuration type.
- Copy the KSM config base64-encoded string and keep it stored securely for future use.

Docker Compose File:

services:
    commander:
        ports:
            - <port>:<port>
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --ksm-config <BASE64_ENCODED_CONFIG> 
            --record <RECORD_UID_OR_TITLE>

Docker Run:

docker run -d -p <port>:<port> \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml> \
  --ksm-config <BASE64_ENCODED_CONFIG> \
  --record <RECORD_UID_OR_TITLE>

Example:

docker run -d -p 9007:9007 \
  keeper/commander:latest \
  service-create -p 9007 -c 'ls,tree' -f json \
  --ksm-config eyJhcHBsaWNhdGlvbiI6ZXN0LWNsaWVudC1pZCJ9 \
  --record ABC123-DEF456-GHI789

The --record parameter supports both record UID and record title. If multiple records exist with the same title, you must use the specific UID instead.

Approach B: Mounting KSM Config File inside the container

Prerequisites:

Before using KSM config file authentication, you must:

Create a KSM Application in your Keeper vault
Generate a KSM config file (ksm-config.json)
Create a Keeper record containing your service config.json as an attachment
Share the record with your KSM application

Setup Steps:

Complete the Common Setup Steps for Config File Preparation
Create KSM Configuration File:
- Go to Vault → Secrets Manager → My Applications.
- Create new application and provide access to your shared folder.
- Select your application, go to Devices, and click on Add Device.
- Use Configuration File method and download the JSON file.
- Rename the downloaded file to ksm-config.json to avoid any conflict with .keeper/config.json.

Docker Compose File:

services:
    commander:
        ports:
            - <port>:<port>
        volumes:
            - /path/to/local/ksm-config.json:/home/commander/ksm-config.json
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --ksm-config /home/commander/ksm-config.json 
            --record <RECORD_UID_OR_TITLE>

Docker Run:

docker run -d -p <port>:<port> \
  -v /path/to/local/ksm-config.json:/home/commander/ksm-config.json \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml> \
  --ksm-config /home/commander/ksm-config.json \
  --record <RECORD_UID_OR_TITLE>

Example:

docker run -d -p 9007:9007 \
  -v /path/to/local/ksm-config.json:/home/commander/ksm-config.json \
  keeper/commander:latest \
  service-create -p 9007 -c 'ls,tree' -f json \
  --ksm-config /home/commander/ksm-config.json \
  --record ABC123-DEF456-GHI789

The --record parameter supports both record UID and record title. If multiple records exist with the same title, you must use the specific UID instead.

With KSM Token Authentication

Prerequisites:

Before using KSM Token authentication, you must:

Create a KSM Application in your Keeper vault
Store the generated access token securely
Create a Keeper record containing your config.json as an attachment
Share the record with your KSM application

Setup Steps:

Complete the Common Setup Steps for Config File Preparation
Create KSM Access Token:
- Go to Vault → Secrets Manager → My Applications
- Create new application and provide access to your shared folder
- Grant "Can Edit" permission and generate the access token
- Store the generated access token securely

Docker Compose File:

services:
    commander:
        ports:
            - <port>:<port>
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --ksm-token <KSM_TOKEN> 
            --record <RECORD_UID_OR_TITLE>

Docker Run:

docker run -d -p <port>:<port> \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml> \
  --ksm-token <KSM_TOKEN> \
  --record <RECORD_UID_OR_TITLE>

Example:

docker run -d -p 9007:9007 \
  keeper/commander:latest \
  service-create -p 9007 -c 'ls,tree' -f json \
  --ksm-token US:odncsdcindsijiojijj32i3ij2iknm23 \
  --record ABC123-DEF456-GHI789

The --record parameter supports both record UID and record title. If multiple records exist with the same title, you must use the specific UID instead.

With User/Password Authentication

Parameters:

-p, --port: Port number for the service
-c, --commands: Comma-separated list of allowed commands
-f, --fileformat: Configuration file format (json/yaml)
--user: Keeper username for authentication
--password: Keeper password for authentication
--server: Keeper server (optional, defaults to keepersecurity.com)

Docker Compose File:

services:
    commander:
        ports:
            - <port>:<port>
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml> 
            --user <keeper-username> 
            --password <keeper-password>
            --server <keeper-server>

Docker Run:

docker run -d -p <port>:<port> keeper/commander:latest \
  service-create \
  -p <port> \
  -c '<comma-separated-commands>' \
  -f <json-or-yaml> \
  --user <keeper-username> \
  --password <keeper-password> \
  --server <keeper-server>

Example:

docker run -d -p 9009:9009 keeper/commander:latest \
  service-create \
  -p 9009 \
  -c 'tree,ls' \
  -f json \
  --user [email protected] \
  --password mypassword

With Config File Authentication

Prerequisites:

Before using config file authentication, you must first create a properly configured config.json file on your host machine.

Setup Steps:

Follow steps 1-4 from the Common Setup Steps for Config File Preparation
Copy config file: Once configured, locate the config.json file in the .keeper directory on your host machine and copy the contents of the config.json file to your desired path (e.g., /path/to/local/config.json) for Docker mounting.
Remove the original config file: After copying, delete the config.json file from the .keeper directory on your host machine to prevent duplicate configurations with the same device token/clone code.

Mount your existing Keeper config file:

Docker Compose File:

services:
    commander:
        ports:
            - <port>:<port>
        volumes:
            - /path/to/local/config.json:/home/commander/.keeper/config.json
        image: keeper/commander:latest
        command: service-create -p <port> -c '<commands>' -f <json-or-yaml>

Docker Run:

docker run -d -p <port>:<port> \
  -v /path/to/local/config.json:/home/commander/.keeper/config.json \
  keeper/commander:latest \
  service-create -p <port> -c '<commands>' -f <json-or-yaml>

Verify Deployment

Check container status:

docker ps

View container logs:

docker logs <container-name-or-id>

Get API key from logs: Look for the API key in the container logs:

Generated API key: <API-KEY>

Follow logs in real-time:

docker logs -f <container-name-or-id>

Container Architecture

Base Image: python:3.11-slim
Working Directory: /commander
Config Directory: /home/commander/.keeper/
Entrypoint: docker-entrypoint.sh with automatic authentication setup

Execute Command Endpoint

# Queue enabled (v2 - async)
curl --location 'http://localhost:<port>/api/v2/executecommand-async' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
   "command": "<command>"
}'

# Queue disabled (v1 - direct)  
curl --location 'http://localhost:<port>/api/v1/executecommand' \
--header 'Content-Type: application/json' \
--header 'api-key: <your-api-key>' \
--data '{
   "command": "<command>"
}'

Keeper Commander supports persistent login mode (e.g. "Stay Logged In"), which keeps the session active for a specific amount of time. To activate persistent login mode on an account, type the following:

this-device persistent-login on
this-device register
this-device timeout 43200

If persistent login is enabled with the above timeout settings, you won't be prompted to authenticate in Commander for next 30 days (43,200 minutes). Persistent login is required to ensure uninterrupted background execution of the Service Mode APIs, allowing seamless authentication without repeated login prompts.

Learn more about persistent login sessions.

Logging

The service includes a comprehensive logging system that tracks:

Service startup/shutdown events
Configuration changes
API execution
Security events
Error conditions

Configuration:

Once service mode started the logging_config.yaml is generated at default path (~.keeper) with default level INFO. You can disable logging by setting enabled: false or can change log level (INFO, DEBUG, ERROR) by setting level value.

   logging:
     enabled: true
     level: INFO

Background Process Logging

When running in background mode, service logs are stored in:

Location: keepercommander/service/core/logs/service_subprocess.log
Content: Subprocess output, errors, and service events
Auto-created: Log directory is automatically created when service starts in background

Ngrok Logging

When ngrok tunneling is enabled, additional logs are maintained:

Location: keepercommander/service/core/logs/ngrok_subprocess.log
Content: Ngrok tunnel startup, connection events, public URL generation, and tunnel errors
Includes: Tunnel establishment, reconnection attempts, and ngrok-specific error messages
Auto-created: Created automatically when ngrok tunneling is configured and service starts

Cloudflare Logging

When Cloudflare tunneling is enabled, additional logs are maintained:

Location: keepercommander/service/core/logs/cloudflare_tunnel_subprocess.log
Content: Cloudflare tunnel startup, connection events, public URL generation, and tunnel errors
Includes: Tunnel establishment, reconnection attempts, and Cloudflare-specific error messages
Auto-created: Created automatically when Cloudflare tunneling is configured and service starts

PreviousService Tunneling NextAdvanced Settings

Last updated 2 days ago

Was this helpful?

Docker Deploy

Prerequisites

Pull Docker Image

Authentication Methods

Common Setup Steps for Config File Preparation

Run Docker Container

Verify Deployment

Check container status:

View container logs:

Get API key from logs: Look for the API key in the container logs:

Follow logs in real-time:

Container Architecture

Execute Command Endpoint

Persistent Login Mode

Logging