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

> Build Chat2DB from source by compiling the React frontend with Yarn, generating an encryption key, and packaging the Spring Boot backend with Maven. Get the runnable JAR file.

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

---

**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:

```bash
java -version
node -v
mvn -v
yarn -v

```

## Clone the Repository

Download the source code and navigate into the project root:

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

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

```

### Development Build (Optional)

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

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

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

```bash
./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`](https://github.com/OtterMind/Chat2DB/blob/main/chat2db-community-server/pom.xml). The assembly module `chat2db-community-start` produces the final executable JAR.

Execute the following from the repository root:

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

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

```

## Run the Application

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

```

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

## Build a Docker Image (Optional)

For containerized deployment, use the provided helper script:

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