# How to Set Up OtterMind/Chat2DB Locally: Docker and Source Build Guide

> Set up OtterMind Chat2DB locally using Docker or build from source. Follow our guide to quickly get this powerful AI tool running on your machine.

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

---

**Set up OtterMind/Chat2DB locally by first generating an encryption key, then either running the official Docker image on `127.0.0.1:10825` or building the Java backend and React frontend from source.**

Chat2DB Community is a free, cross-platform database client maintained by OtterMind. To set up OtterMind/Chat2DB locally, you need to understand its split architecture: a **Java 17 Spring Boot backend**, a **Umi React frontend** in `chat2db-community-client`, and an optional **JCEF desktop shell** in `chat2db-community-jcef`. This guide covers every supported local deployment path using the official repository structure.

## Prerequisites for a Local Chat2DB Setup

Before you begin, ensure your local environment meets these minimum requirements:

- **Java runtime:** Eclipse Temurin 17 (or any Java 17 distribution)
- **Node.js:** 18.17.0 or later
- **Maven:** 3.8 or later
- **Docker:** 19.03.0 or later (with Compose V2 if using the compose file)

The backend is organized through [`chat2db-community-server/pom.xml`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml) and assembled by the `chat2db-community-start` module. According to [`spec/code/server/java-module-boundaries.md`](https://github.com/OtterMind/Chat2DB/blob/main/spec/code/server/java-module-boundaries.md), the **domain-api** module defines business interfaces and the **spi** module defines plugin extension points. Database-specific capabilities live in `chat2db-community-plugins/*`.

## Generate the Encryption Key

Chat2DB encrypts stored datasource passwords and AI model API keys using **AES-256-GCM**. The server will refuse to start if a valid key is not present.

Run the official key-generation script from the repository root:

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

```

This writes the key to `~/.config/chat2db-community/encryption.key`. Keep this file safe; it is required for every subsequent startup.

## Run Chat2DB Locally with Docker

Docker is the fastest way to set up Chat2DB locally because the server is already packaged. By default, the service listens on `127.0.0.1:10825` and should remain bound to loopback for security.

### Single-Container Quick Start

Use the following `docker run` command to launch the latest image:

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

```

Open `http://localhost:10825` in your browser to access the web UI.

### Docker Compose Setup (Recommended)

For a repeatable local environment, use the compose file at [`docker/docker-compose.yml`](https://github.com/OtterMind/Chat2DB/blob/main/docker/docker-compose.yml). First generate the encryption key if you have not already, then start the stack:

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

```

The compose file mounts a named volume, `chat2db-community-data`, for persistent storage and maps the encryption key into the container read-only.

```yaml
services:
  chat2db:
    image: chat2db/chat2db:latest
    ports:
      - "127.0.0.1:10825:10825"
    volumes:
      - chat2db-community-data:/root/.chat2db-community
      - "$HOME/.config/chat2db-community/encryption.key:/run/secrets/chat2db-community-encryption.key:ro"
    environment:
      - CHAT2DB_COMMUNITY_ENCRYPTION_KEY_FILE=/run/secrets/chat2db-community-encryption.key
volumes:
  chat2db-community-data:

```

## Build and Run Chat2DB Locally from Source

Building from source lets you run the frontend with hot-reload and the backend directly from Maven. This is the best approach for active development or contribution.

### Start the Frontend in Hot-Reload Mode

Navigate to the React client directory and start the dev server:

```bash
cd chat2db-community-client
yarn install --frozen-lockfile
yarn run start:community:hot

```

The UI becomes available at `http://localhost:8889` and proxies API requests to the backend.

### Build and Start the Java Backend

From the repository root, compile the startup module and its dependencies:

```bash
mvn -B clean package \
  -Dmaven.test.skip=true \
  -Dchat2db.finalName=chat2db-community \
  -f chat2db-community-server/pom.xml \
  -pl chat2db-community-start -am

```

After building, launch the backend with the required system properties:

```bash
java -Dloader.path=chat2db-community-server/chat2db-community-start/target/lib \
     -Dchat2db.gui=false \
     -Dchat2db.runtime.mode=community \
     -Dchat2db.mode=WEB \
     -Dchat2db.network.status=OFFLINE \
     -Dchat2db.community.encryption-key-file="$HOME/.config/chat2db-community/encryption.key" \
     -Dserver.address=127.0.0.1 \
     -Dserver.port=10825 \
     -Dspring.profiles.active=dev \
     -jar chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

```

The server starts on `127.0.0.1:10825`. You can now point the dev frontend to this address.

## Optional: Build a Local Docker Image

If you need a custom image, use the helper script at [`docker/docker-build.sh`](https://github.com/OtterMind/Chat2DB/blob/main/docker/docker-build.sh):

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

```

Run the resulting image with the same `docker run` flags shown in the Docker section above.

## Summary

- **Every setup path requires the AES-256-GCM encryption key** generated by [`script/security/init-community-encryption-key.sh`](https://github.com/OtterMind/Chat2DB/blob/main/script/security/init-community-encryption-key.sh) and stored at `~/.config/chat2db-community/encryption.key`.
- **Docker and Docker Compose** provide the fastest way to run Chat2DB locally using the official image and [`docker/docker-compose.yml`](https://github.com/OtterMind/Chat2DB/blob/main/docker/docker-compose.yml).
- **Source builds** let you iterate on `chat2db-community-client` via hot-reload and `chat2db-community-start` via Maven.
- The backend defaults to `127.0.0.1:10825`, and database-specific drivers are loaded dynamically from `chat2db-community-plugins/*` via the `spi` extension points.

## Frequently Asked Questions

### What is the minimum Java version required to run Chat2DB?

Chat2DB requires **Java 17** (Eclipse Temurin 17 is recommended). The Maven build for `chat2db-community-start` and its upstream modules fails on older versions.

### Why does Chat2DB refuse to start without an encryption key?

The server uses AES-256-GCM to encrypt sensitive values such as datasource passwords and AI API keys. The startup sequence validates the key file specified by `chat2db.community.encryption-key-file`; without it, the Spring Boot context will not initialize.

### Can I run the backend without building the frontend?

Yes. You can build and run the Java backend independently using Maven and point any prebuilt static UI or a separate frontend client to `http://127.0.0.1:10825`. Set `-Dchat2db.mode=WEB` and the appropriate loader path as shown in the source build section.

### Is Docker Compose the recommended way to run Chat2DB locally?

Docker Compose is recommended when you want a **repeatable, persistent local environment**. The compose file at [`docker/docker-compose.yml`](https://github.com/OtterMind/Chat2DB/blob/main/docker/docker-compose.yml) declaratively mounts the named volume `chat2db-community-data` and the encryption key, making it easier to stop and restart the service without retyping run flags.