How to Set Up a Development Environment for Chat2DB

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 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
Docker	19.03.0+ (optional)	Enables container-based development workflows

Verify your installation with:

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 – Frontend dependency definitions and Yarn scripts
• chat2db-community-server/pom.xml – Maven parent POM for the Java backend
• script/security/init-community-encryption-key.sh – Generates the encryption key required for storing datasource credentials
• docker/docker-compose.yml – Full-stack container configuration

Frontend Setup

Navigate to the client directory and install dependencies using Yarn:

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

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

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:

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

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:

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.

Docker-Based Development

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

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

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"
         }'

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

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