# How to Deploy Chat2DB Community Using Docker: Complete Setup Guide

> Deploy Chat2DB Community with Docker using this comprehensive guide. Learn the simple steps to set up your AI-powered database client effortlessly.

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

---

**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`](https://github.com/OtterMind/Chat2DB/blob/main/script/security/init-community-encryption-key.sh).

Run the initialization script from a local checkout:

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

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

```

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

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

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

```

The [`docker/docker-build.sh`](https://github.com/OtterMind/Chat2DB/blob/main/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:

```text
-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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/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`](https://github.com/OtterMind/Chat2DB/blob/main/docker/docker-build.sh) and modify the Dockerfile's entrypoint flags.