Skip to content

KDB.AI Server – Configuration Guide

This page describes advanced configuration and deployment options for KDB.AI Server. For the standard setup, refer to the Setup Guide.

This guide covers:

1. Docker Compose deployment

Running KDB.AI Server with Docker Compose makes it easier to manage configuration, ports, and volume mounts — particularly when integrating into a broader container stack.

1.1 Prepare a data directory

mkdir -p /path/to/vdbdata
chmod 777 /path/to/vdbdata

KDB.AI Server reads and writes vector index files to this directory.

1.2 Set the license

A KDB-X license must be provided when starting KDB.AI Server.

Pass a Base64-encoded license string via an environment variable. Encode your license file before starting the container, updating the paths to match your license file location.:

export KDB_LICENSE_B64=$(base64 -w0 ~/.kx/kc.lic)

Decode it again if needed:

echo -n "$KDB_LICENSE_B64" | base64 --decode > ~/.kx/kc.lic

export KDB_K4LICENSE_B64=$(base64 -w0 k4.lic)

Decode it again if needed:

echo -n "$KDB_K4LICENSE_B64" | base64 --decode > k4.lic

1.3 Run the container

Minimal service definition using a kc.lic community license:

services:
  kdbai-db:
    image: portal.dl.kx.com/kdbai-db:latest
    environment:
      - KDB_LICENSE_B64=${KDB_LICENSE_B64}
    volumes:
      - /path/to/vdbdata:/tmp/kx/data
    ports:
      - "8081:8081"
      - "8082:8082"

Start the container:

docker compose up -d

Verify it is running:

docker compose ps
Use the reference file

The reference docker-compose.yaml shows all configuration options and is a useful starting point for managing your deployment.

Example using a kc.lic community license:

docker run -d \
  -p 8081:8081 \
  -p 8082:8082 \
  -e KDB_LICENSE_B64=$KDB_LICENSE_B64 \
  -v /path/to/vdbdata:/tmp/kx/data \
  portal.dl.kx.com/kdbai-db:latest

Verify it is running:

docker ps

2. Air-gapped deployment

KDB.AI Server can be deployed on machines without internet access.

  1. On an internet-connected machine, download and save the image:

    docker pull portal.dl.kx.com/kdbai-db:latest
docker save -o kdbai-db.tar portal.dl.kx.com/kdbai-db:latest

  2. Encode your license. The example below uses a community license; for a k4.lic commercial license, refer to Set the license.

    export KDB_LICENSE_B64=$(base64 -w0 /path/to/kc.lic)

  3. Transfer the image and the encoded license to the air-gapped machine using your preferred method (for example, scp, USB, or a secure file share):

    scp kdbai-db.tar user@server:~/

  4. On the air-gapped machine, create a data directory, load the image, and start KDB.AI Server:

    mkdir -p /path/to/vdbdata
chmod 777 /path/to/vdbdata
docker load -i kdbai-db.tar
docker run -d \
  -p 8081:8081 \
  -p 8082:8082 \
  -e KDB_LICENSE_B64=$KDB_LICENSE_B64 \
  -v /path/to/vdbdata:/tmp/kx/data \
  portal.dl.kx.com/kdbai-db:latest

For full docker run and docker compose examples, refer to Run the container.

3. Mount external data

To make existing kdb data on your host filesystem available to KDB.AI Server, mount an additional volume as read-only:

services:
  kdbai-db:
    image: portal.dl.kx.com/kdbai-db:latest
    environment:
      - KDB_LICENSE_B64=${KDB_LICENSE_B64}
    volumes:
      - /path/to/vdbdata:/tmp/kx/data
      - /path/to/external/data:/tmp/kx/remote:ro
    ports:
      - "8081:8081"
      - "8082:8082"

docker run -d \
  -p 8081:8081 \
  -p 8082:8082 \
  -e KDB_LICENSE_B64=$KDB_LICENSE_B64 \
  -v "/path/to/vdbdata":/tmp/kx/data \
  -v /path/to/external/data:/tmp/kx/remote:ro \
  portal.dl.kx.com/kdbai-db:latest

The example below shows how to set up an external database with KDB.AI. First create the table, then update the index.

q API: create external table and update indexes.

python API: create external table and update indexes.

The table name must match the name of the target table in the external kdb+ database.

4. Encryption (TLS)

KDB.AI Server does not terminate TLS directly. To encrypt connections in production, a TLS-terminating proxy must sit in front of the service. The proxy handles encryption and forwards connections to KDB.AI unencrypted on the standard ports.

A common pattern is to run a sidecar container (for example, nginx or Envoy) alongside kdbai-db in the same Docker Compose stack. The sidecar listens on a TLS port, holds the certificate and key, and proxies decrypted traffic to kdbai-db on 8081 or 8082. This keeps TLS concerns separate from the database container and makes certificate rotation straightforward. In cloud or Kubernetes environments, a load balancer or ingress controller is a natural alternative.

For details on configuring the Python client to connect over TLS, refer to Create session.

5. Configuration reference

5.1 Environment variables

The tables below describe the environment variables that configure KDB.AI Server behaviour.

Performance

For more details on these variables and related performance questions, refer to the Performance FAQ.

Variable Default Description
NUM_WRK 1 Number of worker processes
THREADS 1 Number of threads per worker

License

Set one of the following license variables to match your license type.

Variable Default Description
KDB_LICENSE_B64 — Base64-encoded kc.lic community license
KDB_K4LICENSE_B64 — Base64-encoded k4.lic commercial license

Static authentication

Refer to the Static Authentication guide for full setup details.

Variable Default Description
AUTH_TYPE — Set to static to enable static authentication
AUTH_PASSWORD — Static auth password; omit if mounting a password file at /opt/kx/secret/auth_pwd

OAuth 2.0

Refer to the OAuth 2.0 Authentication guide for full setup details.

Variable Default Description
AUTH_TYPE — Set to oauth to enable OAuth 2.0
OAUTH_CLIENT_ID — OAuth application name; must match the aud claim in your tokens
OAUTH_TENANT_CLAIM — JWT claim that holds the tenant ID
OAUTH_GROUPS_CLAIM — JWT claim that holds the groups ID
OAUTH_ISSUERS — Comma-separated list of allowed issuer URLs
ACL_SYSTEM_ADMIN_TENANT — Tenant the system admin group belongs to
ACL_SYSTEM_ADMIN_GROUP — Group whose members have system admin privileges

5.2 Reference docker-compose.yaml

services:
  kdbai-db:
    image: portal.dl.kx.com/kdbai-db:latest
    environment:
      # --- Performance settings (optional) ---
      #- NUM_WRK=${NUM_WRK}
      #- THREADS=${THREADS}

      # --- License — uncomment ONLY the line that matches your license type ---
      #- KDB_LICENSE_B64=${KDB_LICENSE_B64}       # For kc.lic (Base64 encoded)
      #- KDB_K4LICENSE_B64=${KDB_K4LICENSE_B64}   # For k4.lic (Base64 encoded)

      # --- Static authentication — uncomment to enable; do not combine with OAuth variables ---
      #- AUTH_TYPE=static
      #- AUTH_PASSWORD=<secret>                   # omit if mounting a password file

      # --- OAuth 2.0 — uncomment to enable; do not combine with static authentication variables ---
      #- AUTH_TYPE=oauth
      #- OAUTH_CLIENT_ID=${OAUTH_CLIENT_ID}
      #- OAUTH_TENANT_CLAIM=${OAUTH_TENANT_CLAIM}
      #- OAUTH_GROUPS_CLAIM=${OAUTH_GROUPS_CLAIM}
      #- OAUTH_ISSUERS=${OAUTH_ISSUERS}
      #- ACL_SYSTEM_ADMIN_TENANT=${ACL_SYSTEM_ADMIN_TENANT}
      #- ACL_SYSTEM_ADMIN_GROUP=${ACL_SYSTEM_ADMIN_GROUP}
    volumes:
      # VDB data mount
      - /path/to/vdbdata:/tmp/kx/data

      # External data mount (optional) — uncomment to make external data available to the service.
      #- /path/to/external/data:/tmp/kx/remote:ro

      # ACL grants — required when using OAuth.
      #- /path/to/acl-dir:/tmp/acl
    ports:
      # host:container — change the host port (left) if needed
      - "8081:8081"
      - "8082:8082"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8081/api/v2/ready"]
      interval: 10s
      retries: 3

Next steps