# How to Set Up a Development Environment for Chat2DB

> Set up your Chat2DB development environment quickly. Install Java & Node.js, initialize encryption, and run frontend and backend with simple commands. Get started today!

- Repository: [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB)
- Tags: getting-started
- Published: 2026-07-27

---

**To set up a Chat2DB development environment, install Java 17 and Node.js 18+, initialize the encryption key using the provided shell script, then run the React frontend with Yarn and the Spring Boot backend with Maven.**

Chat2DB is a modern, AI-enhanced database client maintained in the [OtterMind/Chat2DB](https://github.com/OtterMind/Chat2DB) repository. The codebase consists of a Umi/React TypeScript frontend and a Spring Boot Java backend that must run concurrently during development. This guide walks through the complete setup process based on the actual source structure and build configurations.

## Prerequisites

Before cloning the repository, ensure your workstation meets these tooling requirements:

| Tool | Minimum Version | Purpose |
|------|-----------------|---------|
| **JDK** | Eclipse Temurin 17 | Compiles and runs the Spring Boot backend |
| **Node.js** | 18.17.0 or later | Executes the Yarn-based frontend build system |
| **Maven** | 3.8 or later | Manages multi-module Java dependencies |
| **OpenSSL** | Recent version | Generates the AES-256-GCM encryption key via [script/security/init-community-encryption-key.sh](/blob/main/script/security/init-community-encryption-key.sh) |
| **Docker** | 19.03.0+ (optional) | Enables container-based development workflows |

Verify your installation with:

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

```

## Repository Structure

Understanding the directory layout helps you locate configuration files quickly:

```

Chat2DB/
├─ chat2db-community-client/       # React/TypeScript frontend

├─ chat2db-community-server/      # Spring Boot backend (Maven reactor)

│   ├─ chat2db-community-start/   # Executable JAR assembly module

│   └─ ...                        # Domain, plugins, and SPI modules

├─ script/security/               # Encryption utilities

│   └─ init-community-encryption-key.sh
├─ docker/                        # Container orchestration

│   └─ docker-compose.yml
└─ README.md

```

Key files you will interact with during setup:

- [chat2db-community-client/package.json](/blob/main/chat2db-community-client/package.json) – Frontend dependency definitions and Yarn scripts
- [chat2db-community-server/pom.xml](/blob/main/chat2db-community-server/pom.xml) – Maven parent POM for the Java backend
- [script/security/init-community-encryption-key.sh](/blob/main/script/security/init-community-encryption-key.sh) – Generates the encryption key required for storing datasource credentials
- [docker/docker-compose.yml](/blob/main/docker/docker-compose.yml) – Full-stack container configuration

## Frontend Setup

Navigate to the client directory and install dependencies using Yarn:

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

```

Start the development server with hot-reload enabled for the Community edition:

```bash
yarn run start:community:hot

```

The Umi dev server binds to `http://localhost:8000` by default. The frontend automatically proxies API requests to the backend at `127.0.0.1:10825` when running in development mode.

## Backend Setup

Return to the repository root and initialize the encryption key before building. This step creates the AES-256-GCM key file used to secure datasource passwords and AI model credentials:

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

```

Compile the backend using Maven. This command builds the executable JAR while skipping tests to reduce compilation time:

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

```

Run the server with the Community runtime configuration:

```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 backend starts on `127.0.0.1:10825`. The main application class is located at [chat2db-community-server/chat2db-community-start/src/main/java/ai/chat2db/start/Chat2DBCommunityApplication.java](/blob/main/chat2db-community-server/chat2db-community-start/src/main/java/ai/chat2db/start/Chat2DBCommunityApplication.java).

## Docker-Based Development

For container isolation, generate the encryption key locally, then use Docker Compose:

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

```

This exposes the backend on port `10825` and the UI on port `8889`. Access the application at `http://localhost:8889`.

## Verification Steps

Confirm your environment is functional with these checks:

1. **Frontend Health**: Open `http://localhost:8000` and verify the browser console shows successful API calls to `127.0.0.1:10825`
2. **Backend Health**: Look for the log message `Started Chat2DBCommunityApplication` in the terminal running the Java process
3. **Database Integration**: Create a test SQLite datasource in the UI and execute `SELECT 1` to confirm end-to-end connectivity

Test the REST API directly using curl:

```bash
curl -X POST http://127.0.0.1:10825/api/datasource \
     -H "Content-Type: application/json" \
     -d '{
           "name":"test-sqlite",
           "type":"SQLITE",
           "url":"jdbc:sqlite:/tmp/test.db"
         }'

```

```bash
curl -X POST http://127.0.0.1:10825/api/query \
     -H "Content-Type: application/json" \
     -d '{"datasourceId":1,"sql":"SELECT 1 AS test"}'

```

## Summary

- Install Java 17, Node.js 18+, and Maven 3.8+ before attempting to build
- Run [script/security/init-community-encryption-key.sh](/blob/main/script/security/init-community-encryption-key.sh) to generate the encryption key required by the backend
- Use `yarn run start:community:hot` in the `chat2db-community-client` directory to launch the frontend
- Build the backend with Maven targeting the `chat2db-community-start` module, then execute the JAR with the Community-specific system properties
- Alternatively, use [docker/docker-compose.yml](/blob/main/docker/docker-compose.yml) for a containerized workflow

## Frequently Asked Questions

### What is the encryption key used for in Chat2DB development?

The encryption key is an AES-256-GCM key generated by [script/security/init-community-encryption-key.sh](/blob/main/script/security/init-community-encryption-key.sh). It encrypts sensitive information such as database passwords and AI API keys stored locally by the application. Without this key, the backend will fail to start with a configuration error.

### Can I use a different Java version for the backend?

No. The backend specifically requires Java 17 (Eclipse Temurin recommended) as defined in the [chat2db-community-server/pom.xml](/blob/main/chat2db-community-server/pom.xml). Using Java 8 or 11 will result in compilation errors, while Java 21+ may cause runtime compatibility issues with certain dependencies.

### How do I connect the frontend to a backend running on a different port?

Modify the proxy configuration in the frontend's Umi configuration file. The default `start:community:hot` script assumes the backend runs on `127.0.0.1:10825`. If you change the backend port via `-Dserver.port`, update the corresponding proxy entry in the frontend configuration to match.

### Is Docker required for local development?

No. Docker is optional. You can run the frontend and backend directly on your host machine using Yarn and Maven respectively. Docker is primarily useful for testing the complete application stack in an isolated environment or for users who prefer containerized workflows.