How to Deploy Chat2DB to a Production Environment: A Complete Docker Guide

Deploy Chat2DB in production using the official Docker image, bind the service to 127.0.0.1:10825, generate a persistent AES-256-GCM encryption key, and mount volumes for data persistence and read-only secret access.

Chat2DB is an open-source database management platform built on a Spring Boot backend (chat2db-community-server) and a React/Umi frontend (chat2db-community-client). To deploy Chat2DB to a production environment securely, use Docker with the Community edition configuration, ensuring the encryption key and SQLite data persist outside the container while keeping the HTTP interface bound to localhost.

Generate the Encryption Key First

Before launching the container, create the 32-byte AES-256-GCM encryption key that decrypts stored datasource passwords and AI API keys. This key must be generated once per host and retained across upgrades.

Run the initialization script from the repository root:

git clone https://github.com/OtterMind/Chat2DB.git && cd Chat2DB
./script/security/init-community-encryption-key.sh

Architecture Overview

Understanding the four core components ensures a secure, production-ready deployment:

• Backend Service: The chat2db-community-start JAR in chat2db-community-server/chat2db-community-start/ runs REST APIs and AI integrations in community runtime mode
• Frontend Client: A Umi-based React single-page application served on port 10825, bundled with the backend or served separately
• Encryption Key: A sensitive file mounted read-only at /run/secrets/chat2db-community-encryption.key inside the container, referenced by the environment variable CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE
• Persistent Storage: SQLite databases and plugin files stored in /root/.chat2db-community inside the container, mapped to a Docker volume named chat2db-community-data or a host bind mount

Deployment Methods

Option 1: Docker CLI (Single Container)

For quick, single-container deployments, run the chat2db/chat2db:latest image with explicit security bindings to localhost:

docker run --detach \
  --name chat2db-community \
  --restart unless-stopped \
  --publish 127.0.0.1:10825:10825 \
  --volume "$HOME/.chat2db-community-docker:/root/.chat2db-community" \
  --env CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/run/secrets/chat2db-community-encryption.key \
  --volume "$HOME/.config/chat2db-community/encryption.key:/run/secrets/chat2db-community-encryption.key:ro" \
  chat2db/chat2db:latest

Option 2: Docker Compose (Recommended)

For reproducible, maintainable production deployments, use the official docker/docker-compose.yml which defines the volume, environment variables, and restart policies:

./script/security/init-community-encryption-key.sh
docker compose --file docker/docker-compose.yml up --detach

This configuration automatically creates the chat2db-community-data volume mounted to /root/.chat2db-community and manages the encryption key path.

Security Hardening

Production-ready deployments require two critical security measures according to the Chat2DB source code:

1. Bind to Loopback Interface: Always publish port 10825 to 127.0.0.1:10825 only. This prevents external network access unless you deliberately add a reverse proxy (Nginx, Apache, or cloud load balancer) in front of the service.
2. Read-Only Key Mount: Mount the encryption key file with the :ro (read-only) flag to prevent the container process from modifying the key at /run/secrets/chat2db-community-encryption.key.

Upgrading Chat2DB

To upgrade to the latest image while preserving your data and encryption configuration:

docker pull chat2db/chat2db:latest
docker stop chat2db-community
docker rm chat2db-community
docker compose --file docker/docker-compose.yml up --detach

This workflow ensures the SQLite data in /root/.chat2db-community persists in the Docker volume across container recreations.

Summary

• Generate once: Run script/security/init-community-encryption-key.sh to create the AES-256-GCM key and store it securely on the host filesystem
• Bind locally: Expose port 10825 strictly to 127.0.0.1 in production environments
• Persist data: Mount volumes to /root/.chat2db-community to retain query history and metadata across restarts
• Use Compose: Deploy via docker/docker-compose.yml for production-grade reliability and easier maintenance
• Protect secrets: Mount encryption keys as read-only files using the CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE environment variable

Frequently Asked Questions

What port does Chat2DB use in production?

Chat2DB exposes its HTTP service on port 10825. The official deployment configurations bind this to 127.0.0.1:10825 (localhost only) to prevent unauthorized external access. If you require remote access, place a reverse proxy in front of the container rather than exposing the port directly to 0.0.0.0.

How do I back up Chat2DB data?

Back up the Docker volume or host directory mounted to /root/.chat2db-community inside the container. This directory contains the SQLite database files storing metadata, datasource configurations, and query history. For Docker Compose deployments, back up the chat2db-community-data volume using docker run --rm -v chat2db-community-data:/source -v $(pwd):/backup alpine tar czf /backup/chat2db-backup.tar.gz -C /source ..

Can I run Chat2DB without Docker?

Yes, you can execute the Spring Boot JAR directly from chat2db-community-server/chat2db-community-start/ using Java with the community runtime mode flag. However, Docker is strongly recommended for production because it ensures consistent environments, simplifies secret management for the encryption key, and isolates the application dependencies defined in the official chat2db/chat2db image.

Where is the encryption key stored?

The encryption key is generated by script/security/init-community-encryption-key.sh and should be stored on the host filesystem outside the container, typically at ~/.config/chat2db-community/encryption.key. In production, mount this file into the container at /run/secrets/chat2db-community-encryption.key with read-only permissions (:ro), and reference it via the CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE environment variable.

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