How to Deploy Chat2DB Community Using Docker: Complete Setup Guide

You can deploy Chat2DB Community using the official chat2db/chat2db:latest image by generating an AES-256-GCM encryption key, mounting it read-only to /run/secrets/chat2db-community-encryption.key, and exposing port 10825 with a persistent volume at /root/.chat2db-community.

Chat2DB Community is an AI-enhanced database client that runs as a self-contained web application inside a Docker container. The official image bundles a minimal Eclipse Temurin Java 17 JRE along with the compiled chat2db-community.jar and its supporting libraries from the OtterMind/Chat2DB repository. This guide covers the exact steps to deploy Chat2DB Community using Docker, including encryption key setup, volume configuration, and the specific JVM flags that control runtime behavior.

Generate the Encryption Key First

Chat2DB encrypts stored datasource passwords and AI model API keys using AES-256-GCM, requiring a unique 32-byte Base64-encoded key for each installation. Before starting the container, you must generate this key using the helper script provided in script/security/init-community-encryption-key.sh.

Run the initialization script from a local checkout:

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

This creates the file ~/.config/chat2db-community/encryption.key on your host machine. The container expects to find this key mounted read-only at /run/secrets/chat2db-community-encryption.key inside the container.

Deploy with Docker Run

For quick testing or manual container management, use the docker run command with the exact volume mounts and environment variables required by the application.

Execute the following command after generating the encryption key:

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

Access the web UI at http://localhost:10825. The container persists application data in $HOME/.chat2db-community-docker on your host, which maps to /root/.chat2db-community inside the container.

Deploy with Docker Compose

For production environments or reproducible setups, use the official docker-compose.yml file located in the repository's docker/ directory. This approach handles volume creation and networking automatically.

Run these commands from the repository root:

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

The Compose file defines a named volume chat2db-community-data that persists the application's internal state across container recreations. It also configures the required encryption key mount and exposes port 10825 to the host.

Build a Custom Image from Source

When you need to modify the application jar or include custom plugins, build a local image using the provided build script.

Execute the build script with your desired version tag:

./docker/docker-build.sh 5.3.0 chat2db/chat2db:5.3.0

The docker/docker-build.sh script compiles the current source checkout and creates an image using docker/Dockerfile, which is based on eclipse-temurin:17-jre. The resulting image includes the compiled chat2db-community.jar and the lib/ directory copied into /app.

Container Configuration and JVM Flags

The container entrypoint launches Java with specific system properties defined in docker/Dockerfile that configure the Community edition runtime:

-Dloader.path=/app/lib
-Dchat2db.gui=false
-Dchat2db.runtime.mode=community
-Dchat2db.network.status=OFFLINE
-Dserver.address=0.0.0.0
-Dserver.port=10825
-Dspring.profiles.active=release

These flags bind the HTTP service to port 10825 on all container interfaces (0.0.0.0) while running in headless mode (-Dchat2db.gui=false). The -Dchat2db.network.status=OFFLINE flag enforces that no external AI service calls are made unless explicitly configured otherwise.

Summary

Deploying Chat2DB Community using Docker requires three essential components: the official image, a generated encryption key, and persistent volume storage.

• Generate the encryption key using script/security/init-community-encryption-key.sh before first startup
• Mount the key read-only to /run/secrets/chat2db-community-encryption.key and set the environment variable CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE to point to this location
• Expose port 10825 and mount a volume to /root/.chat2db-community to preserve datasource configurations and application state
• Use Docker Compose for production deployments to simplify volume management and container updates

Frequently Asked Questions

How do I generate the required encryption key for Chat2DB Community?

Run the init-community-encryption-key.sh script from the OtterMind/Chat2DB repository. This creates a Base64-encoded 32-byte AES-256-GCM key at ~/.config/chat2db-community/encryption.key on your host machine, which you must mount into the container at /run/secrets/chat2db-community-encryption.key.

Why does the container fail to start with an encryption key error?

The Chat2DB Community container requires the CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE environment variable to point to a valid encryption key file mounted at /run/secrets/chat2db-community-encryption.key. Ensure you generated the key using the provided script and mounted it as a read-only volume with the :ro flag.

What is the difference between Docker Run and Docker Compose deployment?

Docker Run is suitable for quick tests or single-container management, requiring manual specification of all volume mounts and environment variables. Docker Compose uses the official docker/docker-compose.yml file to automatically handle the named volume for data persistence, environment configuration, and service dependencies, making it the recommended approach for production deployments.

Can I change the default port 10825 to something else?

While you can map the container port to a different host port using Docker's publish syntax (e.g., --publish 8080:10825), the internal server port 10825 is fixed by the -Dserver.port=10825 JVM argument in the container entrypoint. To change the internal port, you must build a custom image using docker/docker-build.sh and modify the Dockerfile's entrypoint flags.

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