How to Deploy DB-GPT in Production with Docker and Configure Horizontal Scaling

Deploy DB-GPT in production by building the multi-stage GPU-enabled image from docker/base/Dockerfile, orchestrating services with the provided docker-compose.yml, and scaling horizontally by configuring the deploy section with replicas and resource limits on the webserver service.

DB-GPT is an open-source AI-native data app development framework that requires careful orchestration for production workloads. This guide covers the complete production deployment path using the official Docker configuration files found in the eosphoros-ai/DB-GPT repository, including horizontal scaling strategies and hardening best practices.

Building the Production Docker Image

The production image is defined in docker/base/Dockerfile and uses a multi-stage build optimized for GPU acceleration and dependency caching.

The Dockerfile performs the following operations:

• Starts from an NVIDIA CUDA base image to enable GPU support for model inference
• Optionally switches to Tsinghua mirrors for faster apt and pip downloads in restricted networks
• Installs system dependencies and Rust toolchain for building native Python extensions
• Uses uv (a high-performance Python package installer) to create a virtual environment with all dependencies
• Copies the prepared environment into the final image and exposes the dbgpt CLI as the entry point

Build the production image with:

docker build -f docker/base/Dockerfile -t eosphorosai/dbgpt:latest .

Orchestrating the Stack with Docker Compose

The repository provides a docker-compose.yml at the repository root that defines the core services required for production operation.

The compose configuration creates two primary services:

Service	Image	Purpose	Exposed Ports
db	mysql/mysql-server	MySQL 8.0 server for metadata and conversation persistence	3306
webserver	eosphorosai/dbgpt:latest	DB-GPT API and web UI	5670

Start the production stack after building the image:

# Export required API keys (example: SiliconFlow)

export SILICONFLOW_API_KEY=your_key_here

docker compose up -d

The configuration uses named volumes (dbgpt-mysql-db, dbgpt-data, dbgpt-message) to ensure data persists across container restarts. The webserver service mounts ./configs for runtime configuration files and depends on the db service for automatic startup ordering.

Configuring Horizontal Scaling for the Web Server

Horizontal scaling allows you to run multiple DB-GPT web server instances behind a load balancer to handle increased traffic. Docker Compose supports this through the deploy section when using Docker Swarm or Docker Desktop's built-in orchestrator.

Add the following configuration to the webserver service in docker-compose.yml:

  webserver:
    # ... existing configuration ...

    deploy:
      mode: replicated
      replicas: 3
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
        reservations:
          cpus: '1.0'
          memory: 2G
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3

Key scaling parameters:

• replicas: Defines the number of parallel web server containers (set to 3 in the example)
• resources.limits: Prevents any single container from consuming excessive host resources
• restart_policy: Automatically replaces failed containers

Alternatively, scale dynamically via command line without modifying the compose file:

docker compose up -d --scale webserver=3

Load balancing considerations: Docker's internal DNS automatically distributes requests among replicas when other services resolve the webserver hostname. For external traffic, place a reverse proxy (Nginx, Traefik, or HAProxy) in front of the webserver service to handle SSL termination, health checks, and sticky sessions if required.

Production Hardening and Best Practices

Running DB-GPT in production requires additional security and reliability measures beyond the basic Docker Compose setup.

Secrets Management

Never commit API keys or database passwords to version control. Use Docker secrets or environment files:

# Create an environment file

echo "SILICONFLOW_API_KEY=sk-..." > .env
echo "MYSQL_ROOT_PASSWORD=secure_password" >> .env

# Start with explicit env file

docker compose --env-file .env up -d

For Docker Swarm deployments, create secrets:

echo "your_api_key" | docker secret create siliconflow_key -

Then reference in docker-compose.yml:

secrets:
  - siliconflow_key

Health Checks

Add a health check to the webserver service to enable automatic recovery:

  webserver:
    # ... other config ...

    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5670/health"]
      interval: 30s
      timeout: 5s
      retries: 3
      start_period: 40s

Logging Configuration

Forward logs to a centralized system (ELK, Loki, or CloudWatch) using Docker's logging drivers:

  webserver:
    logging:
      driver: "json-file"
      options:
        max-size: "10m"
        max-file: "3"

Zero-Downtime Updates

To update DB-GPT without service interruption:

# Build new version with unique tag

docker build -f docker/base/Dockerfile -t eosphorosai/dbgpt:v0.5.0 .

# Update service with rolling restart

docker compose up -d --no-deps --force-recreate webserver

Database Backups

Schedule regular backups of the MySQL volume:

# Create backup container

docker run --rm \
  --volumes-from db-gpt_db_1 \
  -v $(pwd)/backups:/backup \
  mysql:8.0 \
  mysqldump -u root -p dbgpt > /backup/dbgpt_$(date +%F).sql

Complete Production docker-compose.yml Example

Below is a consolidated configuration incorporating scaling, health checks, and resource limits:

services:
  db:
    image: mysql/mysql-server
    environment:
      MYSQL_USER: user
      MYSQL_PASSWORD: password
      MYSQL_ROOT_PASSWORD: aa123456
    ports:
      - 3306:3306
    volumes:
      - dbgpt-mysql-db:/var/lib/mysql
      - ./docker/examples/my.cnf:/etc/my.cnf
      - ./docker/examples/sqls:/docker-entrypoint-initdb.d
      - ./assets/schema/dbgpt.sql:/docker-entrypoint-initdb.d/dbgpt.sql
    restart: unless-stopped
    networks:
      - dbgptnet

  webserver:
    image: eosphorosai/dbgpt:latest
    command: dbgpt start webserver --config /app/configs/dbgpt-proxy-siliconflow-mysql.toml
    environment:
      - SILICONFLOW_API_KEY=${SILICONFLOW_API_KEY}
      - MYSQL_PASSWORD=aa123456
      - MYSQL_HOST=db
      - MYSQL_PORT=3306
      - MYSQL_DATABASE=dbgpt
      - MYSQL_USER=root
    volumes:
      - ./configs:/app/configs
      - /data:/data
      - /data/models:/app/models
      - dbgpt-data:/app/pilot/data
      - dbgpt-message:/app/pilot/message
    depends_on:
      - db
    ports:
      - 5670:5670
    deploy:
      mode: replicated
      replicas: 3
      resources:
        limits:
          cpus: '2.0'
          memory: 4G
      restart_policy:
        condition: on-failure
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:5670/health"]
      interval: 30s
      timeout: 5s
      retries: 3
    networks:
      - dbgptnet
    ipc: host

volumes:
  dbgpt-mysql-db:
  dbgpt-data:
  dbgpt-message:

networks:
  dbgptnet:
    driver: bridge

Summary

• Build the production image using docker/base/Dockerfile, which creates a GPU-enabled, multi-stage build with the dbgpt CLI entry point.
• Orchestrate services with the provided docker-compose.yml, which configures a MySQL database and the DB-GPT web server with persistent volumes.
• Scale horizontally by adding a deploy section with replicas and resource limits, or use docker compose up --scale webserver=N for dynamic scaling.
• Harden for production by externalizing secrets, implementing health checks, configuring log rotation, and scheduling regular database backups.

Frequently Asked Questions

How do I configure DB-GPT to use external LLM APIs like SiliconFlow?

Set the appropriate environment variable before starting the containers. For SiliconFlow, export SILICONFLOW_API_KEY in your shell or .env file. The webserver service passes this variable through to the application runtime, allowing DB-GPT to authenticate with the SiliconFlow API endpoints defined in your configuration file.

Can I run DB-GPT without GPU support in production?

Yes, though the docker/base/Dockerfile uses an NVIDIA CUDA base image for GPU acceleration, you can modify the base image to a CPU-only Python image (such as python:3.10-slim) and remove GPU-specific dependencies. However, for production workloads involving large language models, GPU acceleration is strongly recommended to maintain acceptable response latency.

What is the recommended approach for zero-downtime deployments?

Build your new image version with a unique tag (e.g., eosphorosai/dbgpt:v0.5.0), then use docker compose up -d --no-deps --force-recreate webserver to recreate the web server containers without affecting the database service. If running multiple replicas, Docker performs a rolling update by default, ensuring continuous availability while updating instances one by one.

How do I back up the MySQL data volume used by DB-GPT?

Create a temporary container that mounts the DB-GPT MySQL volume and dumps the database to a backup directory on the host. Run: docker run --rm --volumes-from <db_container_name> -v $(pwd)/backups:/backup mysql:8.0 mysqldump -u root -p<password> dbgpt > /backup/dbgpt_$(date +%F).sql. Schedule this command via cron or your orchestrator's job scheduler for automated daily backups.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}