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

> Deploy Chat2DB to production using Docker. Learn to bind the service, generate encryption keys, and manage persistent data and secrets for a robust setup.

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: how-to-guide
- Published: 2026-07-27

---

**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:

```bash
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:

```bash
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`](https://github.com/OtterMind/Chat2DB/blob/main/docker/docker-compose.yml) which defines the volume, environment variables, and restart policies:

```bash
./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:

```bash
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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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.