KDB.AI Server Setup

This page details the steps to set up KDB.AI Server.

Hardware requirements

KDB.AI Server works on Intel, AMD, ARM, and Apple CPUs that meet the below specifications:

  • Intel CPUs that support AVX2 instructions (Haswell architecture).

  • AMD CPUs that support AVX2 instructions (Zen architecture).

  • ARM (aarch64) CPUs that support NEON instructions.

  • Apple MX CPUs (M1, M2, and M3) that support NEON instructions.

Note

KDB.AI Server supports Linux ARM-based CPUs using Docker and on Apple Silicon using Docker desktop or Rancher desktop.

Tip

For Rancher desktop on Apple Silicon, we recommend the following setup:

  1. Go to Preferences > Virtual Machine.

  2. In the Volumes tab > tick virtiofs as Mount type.

  3. Emulation tab > select VZ as the Virtual Machine Type.

Software requirements

You can run KDB.AI Server under Docker or Rancher.

For demonstration purposes, the following steps provide guidance for running the KDB.AI Server under Docker:

  1. A Linux kernel of 4.18.0 or later is required to run the KDB.AI container. Examples of such distros include:

    • CentOS 8 or later

    • Red Hat Enterprise Linux (RHEL) 8 or later

    • Ubuntu 18.04 or later

  2. If you run KDB.AI Server on Windows, we recommend using the Windows Subsystem for Linux (WSL) instead of running it directly on Windows. This way, the volume mounts are from a Linux filesystem (for example, ext4) and avoid any related errors.

System requirements

The KDB.AI Server Standard Edition license is limited to 24 cores. When running the Docker container, if the machine contains more than 24 cores, adjust the Docker run command to include --cpuset-cpus, for example --cpuset-cpus 1-24. See step 3 of Start the KDB.AI docker image for more details. If you're using Rancher, make sure to tick dockered(moby) in General > Preferences > Container Engine > General.

Sign up

Ensure you have signed up for KDB.AI Server Edition here.

  1. Check your spam folder.

  2. Add support@kdb.ai to the Safe senders list to prevent your personal or corporate antivirus or email protection software to block the email from being delivered.

  1. Check your spam folder. The subject of the Welcome email is **Your KDB.AI Server: Standard Edition evaluation is ready**.

  2. Add support@kdb.ai to the Safe senders list to prevent your personal or corporate antivirus or email protection software to block the email from being delivered.

  3. Contact the [Support team].

Bearer token

Once you receive your registration email, obtain a bearer token by doing the following:

  1. Log into the KX downloads portal.

  2. Once authenticated, navigate to https://portal.dl.kx.com/auth/token.

  3. Click Add New Bearer token.

  4. Click Copy Bearer.

Download the KDB.AI image

Using the credentials provided after you register, you can download the image for the specified version of KDB.AI Server.

  1. Login to the docker registry in the downloads portal:

    Python

    Copy 
    export USERNAME=<Signup email address>
    export BEARER=<Copied from KX downloads portal>
    docker login portal.dl.kx.com -u $USERNAME -p $BEARER

    Note

    Your username is your email address registered with KX, your password is the bearer token.

  2. Pull the kdbai-db image:

    Python

    Copy 
    docker pull portal.dl.kx.com/kdbai-db:latest

Download your KDB.AI license

In your registration email, click Download License. Your license is either a k4.lic or kc.lic file - you'll need it to access your KDB.AI Server database.

You need to save the license within your mounted Linux filesystem. It doesn't work if you save it in your Windows filesystem.

For example, this command works:

Bash

Copy 
export KDB_LICENSE_B64=$(base64 kc.lic)

This command doesn't work:

Bash

Copy 
export KDB_LICENSE_B64=\mnt\c\users\yourname\downloads\kc.lic

Provide a license

Create the environment variable using the corresponding command depending on the format of your license:

kc.lic

k4.lic

Python

Copy 
export KDB_LICENSE_B64=$(base64 path-to/kc.lic) #For Windows, Linux
export KDB_LICENSE_B64=$(base64 -i path-to/kc.lic) #For macOS 

Python

Copy 

export KDB_K4LICENSE_B64=$(base64 path-to/k4.lic) #For Windows, Linux
export KDB_K4LICENSE_B64=$(base64 -i path-to/k4.lic) #For macOS 

Start the KDB.AI docker image

  1. Create a location on the local disk to write data:

    Bash

    Copy 
    tree .
    .
    └── vdbdata

    1 directory, 0 files

    Bash

    Copy 
    mkdir vdbdata

  2. Set permissions to read and write to this directory:

    Bash

    Copy 
    chmod 0777 vdbdata

  3. Run the container in detached mode using the following command:

    Python

    Copy 
    docker run -d \
    -p 8081:8081 \
    -p 8082:8082 \
    -e KDB_LICENSE_B64 \
    -e VDB_DIR="/tmp/kx/data/vdb" \
    -v $PWD/vdbdata:/tmp/kx/data \
    -e THREADS="8" \
    portal.dl.kx.com/kdbai-db:latest

    Log into the KX Docker registry using the email you signed up with and the Bearer Token string from your Welcome email:

    Python

    Copy 
    docker login portal.dl.kx.com -u <the email you signed up with> -p <long Bearer Token string from your Welcome email>

    Run the container in detached mode, including the KDB_LICENSE_B64 string from your Welcome email:

    Python

    Copy 
    export KDB_LICENSE_B64=$(base64 -w 0 /<path-to-your-downloaded-license-file>/kc.lic)
    docker run -d \
        -p 8081:8081 \
        -p 8082:8082 \
        -e KDB_LICENSE_B64=$KDB_LICENSE_B64 \
        -e VDB_DIR="/tmp/kx/data/vdb" \
        -v "$PWD/vdbdata":/tmp/kx/data \
        -e THREADS="8" \
        portal.dl.kx.com/kdbai-db
       

    Note

    The first port in the -p line is configurable, but the second port 8082 must not be changed.

    Information

    The THREADS environment variable determines the number of threads utilized by each worker in multithreaded operations. Setting this variable helps optimize performance by allowing parallel execution of tasks.

    • Syntax: THREADS=<number_of_threads>

    • Example: THREADS="8"

    We recommend setting THREADS to the number of CPU cores available on the machine running KDB.AI Server. For a comprehensive understanding of how multithreading works and how to optimize the THREADS variable, refer to the dedicated multithreading page.

    • Didn't get a success message? Try removing -d from the above command to view the container logs and any potential errors.

    • If you attempt to run the Docker container on a machine with more than 24 cores, the execution fails with a cores error. To work around it, add a --cpuset-cpus parameter to the Docker run command, for example --cpuset-cpus 1-24.

  4. Check if the KDB.AI container is running:

    Python

    Copy 
    docker ps

    Add the -E flag so environmental variables like KDB_LICENSE_B64 are picked up. Therefore, the command becomes: -E docker ps.

Install the KDB.AI client

  1. Install the latest version of KDB.AI client using pip from PyPI using the following command:

    Python

    REST

    Python

    Copy 
    pip install kdbai-client

    Ensure curl is installed, for example:

    Shell

    Copy 
    which curl

    KDB.AI supports Python (versions 3.8 to 3.11).

  2. Establish and verify the connection with the KDB.AI Server:

    Python

    REST

    Python

    Copy 
    import kdbai_client as kdbai
    session = kdbai.Session(endpoint='http://localhost:8082')
    database = session.database('default')
    print(database.tables)
    # expected response should be an empty list [] because you haven't created any tables yet

    Shell

    Copy 
    curl http://localhost:8081/api/v2/ready
    # expected response 'OK'

Export the KDB.AI docker logs

If you encounter an issue, we recommend exporting your log file by running the following:

Python

Copy 
docker logs <your-container-name> > yourDocker.log 2>&1  

Send your log file yourDocker.log to the Support team.

Stop the KDB.AI docker image

If you wish you stop the KDB.AI Server, stop the container by running:

Python

Copy 
docker stop <your-container-name>

WARNING: KDB.AI Server License Validity

The KDB.AI Server setup is valid for 90 days. To continue using the server after this period, you need to update the license by following the steps in the email reminder and contacting Sales for the paid license.

Next steps

Go to our Quickstart Guide page to set up your table schema and start inserting data.