How to Build Chat2DB from Source Code: A Complete Developer Guide

To build Chat2DB from source, compile the React front-end with Yarn, generate an encryption key using the provided shell script, and package the Spring Boot back-end with Maven to produce a runnable JAR at chat2db-community-start/target/chat2db-community.jar.

Chat2DB is an AI-powered database client built as a multi-module Spring Boot application with a React + Umi front-end. This guide walks through how to build Chat2DB from source code using the official build pipeline defined in the OtterMind/Chat2DB repository.

Prerequisites

Before building Chat2DB from source, install the following toolchain:

• Java 17 (Eclipse Temurin recommended)
• Node.js 18 or later (for the UI build)
• Maven 3.8+ (for back-end compilation)
• Yarn package manager

Verify your installations:

java -version
node -v
mvn -v
yarn -v

Clone the Repository

Download the source code and navigate into the project root:

git clone https://github.com/OtterMind/Chat2DB.git
cd Chat2DB

The repository splits into two main directories: chat2db-community-server/ (Java back-end) and chat2db-community-client/ (React front-end).

Build the Front-End

The UI resides in chat2db-community-client/ and uses Umi, React, and Ant Design. You must compile this before packaging the back-end.

Install Dependencies

cd chat2db-community-client
yarn install --frozen-lockfile

Development Build (Optional)

To start the UI in hot-reload mode for development:

yarn run start:community:hot

This serves the front-end separately on its own dev server.

Production Build

To generate the static assets that embed into the final JAR:

yarn run build:web:community --app_version=0.0.0

The build output is copied into the back-end resources during the Maven packaging phase.

Generate the Encryption Key

Chat2DB encrypts sensitive data (database passwords and AI API keys) using AES-256-GCM. You must initialize the encryption key before first run:

./script/security/init-community-encryption-key.sh

This script generates a 32-byte Base64 key and writes it to ~/.config/chat2db-community/encryption.key. It is safe to re-run the script; it will preserve an existing valid key.

Build the Back-End

The back-end is a Maven reactor project defined in chat2db-community-server/pom.xml. The assembly module chat2db-community-start produces the final executable JAR.

Execute the following from the repository root:

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

Command breakdown:

• -pl chat2db-community-start -am builds the start module and all required dependencies (domain, storage, web layer, and database plugins).
• -Dchat2db.finalName=chat2db-community sets the output filename.
• Tests are skipped to speed up the build.

The resulting artifact is located at:

chat2db-community-server/chat2db-community-start/target/chat2db-community.jar

Run the Application

Launch the server 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

Open http://localhost:10825 in your browser to access the application.

Build a Docker Image (Optional)

For containerized deployment, use the provided helper script:

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

This script packages the compiled JAR and UI assets into a Docker image. Run the container with the same environment variables used in the raw Java command above.

Summary

• Chat2DB is a Java Spring Boot multi-module project with a React front-end located in chat2db-community-client/.
• Prerequisites include Java 17, Node 18, Maven 3.8+, and Yarn.
• Front-end build uses yarn run build:web:community to generate static assets.
• Encryption setup requires running ./script/security/init-community-encryption-key.sh once to create ~/.config/chat2db-community/encryption.key.
• Back-end build uses Maven with -pl chat2db-community-start -am to produce chat2db-community-server/chat2db-community-start/target/chat2db-community.jar.
• Execution requires specific JVM arguments including the encryption key path and runtime mode flags.

Frequently Asked Questions

What Java version is required to build Chat2DB?

Chat2DB requires Java 17 or later. The build and runtime are tested against Eclipse Temurin 17. Using older Java versions will cause compilation failures due to modern Spring Boot and library dependencies.

Where does the encryption key get stored?

The initialization script writes the AES-256-GCM key to ~/.config/chat2db-community/encryption.key on Linux/macOS or the equivalent config directory on Windows. You must reference this path via the -Dchat2db.community.encryption-key-file JVM argument when starting the application.

Can I build Chat2DB without running the front-end separately?

Yes. The Maven build in chat2db-community-start/pom.xml automatically includes the compiled front-end assets if they exist in chat2db-community-client/. Run yarn run build:web:community first, then execute the Maven package command to create a self-contained JAR with the UI embedded.

How do I speed up the Maven build?

Skip tests and build only the start module with its dependencies using the -pl chat2db-community-start -am flags as shown above. This avoids compiling test suites and unnecessary modules while ensuring all required dependencies are built.

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