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

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 and assembled by the chat2db-community-start module. According to 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:

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:

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. First generate the encryption key if you have not already, then start the stack:

./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.

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:

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:

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:

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:

./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 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.
• 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 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.

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