Acquiring and Loading the Image

When deploying KingbaseES (KES) in a standalone environment, utilizing Docker significantly streamlines the process compared to traditional command-line installations. As the official Docker Hub does not currently host a public KES image, the installation package must be downloaded from the official website as a tar archive.

Once the archive is downloaded, it can be loaded into the local Docker environment via the CLI. Using command-line import is often more reliable than GUI-based panel imports.

docker load --input kes_local_image.tar

Configuring the Stack with Docker Compose

Rather than executing lengthy docker run commands, defining the deployment through a Docker Compose file provides better flexibility and configuration management.

version: "3.8"
services:
  kes-db:
    image: kes_v9_single:x86_64
    container_name: kes-standalone
    privileged: true
    environment:
      CASE_INSENSITIVE: "true"  # true for case-insensitive, false for case-sensitive
      AUTO_START: "true"        # true to auto-start the database
      ADMIN_USER: dbadmin
      ADMIN_PASS: SecureP@ssw0rd!
      COMPAT_MODE: oracle       # Compatible with oracle, pg, or mysql
    volumes:
      - /data/kes/storage:/opt/kingbase/userdata
    ports:
      - "5432:54321"
    restart: always
    command: /sbin/init

Apply the configuration by running docker-compose up -d. A common pitfall during startup is failing to clear previously mounted persistent directories from older installations. Ensuring a clean mapping directory is crucial for a successful initialization.

Database Initialization and Access

After the container starts, verify the database status and attempt a connection. First, check if the service is running properly inside the container:

sys_ctl status -D /opt/kingbase/userdata/db_data

Although passwordless login via the kql command might be documented, it can occasionally fail due to environment specifics. A more reliable approach is to authenticate using the credentials specified in the Compoce environment variables:

ksql -U dbadmin -d postgres -p 54321

Once connected, new databases can be created and managed as needed. Managing database instances purely through CLI requires extensive environment configuration, whereas containerized deployments abstract these intricacies, aligning better with modern Kubernetes-driven operations.

Pushing to a Container Registry

Without an official public image repository, downloading the tar file on every host machine is inefficient. To optimize this workflow, pushing the local image to a private or public cloud container registry (such as Tencent Cloud Container Registry) is highly recommended. This allows nodes to pull the image directly without manual transfers.

After tagging and pushing the image to your registry, update the Compose file to reference the remote path:

version: "3.8"
services:
  kes-cloud:
    image: registry.example.com/kingbase/kes-db:v030
    container_name: kes-cloud-instance
    privileged: true
    environment:
      CASE_INSENSITIVE: "true"
      AUTO_START: "true"
      ADMIN_USER: dbadmin
      ADMIN_PASS: SecureP@ssw0rd!
      COMPAT_MODE: oracle
    volumes:
      - /data/kes/cloud_storage:/opt/kingbase/userdata
    ports:
      - "5433:54321"
    restart: always
    command: /sbin/init

When running multiple instances on the same host, ensure that the host port mappings (e.g., 5432, 5433) and volume paths do not conflict with existing running containers to prevent startup failures.