Development Environment

See how it works for an overview of the architecture before diving in.

Requirements

Tool	Version	Install
Node.js	>= 24	nodejs.org or `nvm install 24`
pnpm	10.33.2	`corepack enable && corepack prepare pnpm@10.33.2 --activate`
Docker	24+	docs.docker.com
Docker Compose	v2.20+	Included with Docker Desktop

Installation

Clone the repository

git clone https://github.com/ChatbotXIO/ChatbotX.git
cd ChatbotX

Install dependencies

pnpm install

This installs dependencies for all apps and packages in the monorepo via Turborepo. Git hooks (Lefthook) are also set up automatically at this step.

Start infrastructure services

Spin up PostgreSQL, Redis, Storage, and ClickHouse (optional) using Docker Compose:

docker compose up -d

This starts the following services in the background:

Service	Port	Purpose
PostgreSQL	`5432`	Primary database
Redis	`6379`	Cache and job queue
Storage (RustFS)	`9000`	S3-compatible file storage
Storage Console	`9001`	RustFS admin UI
Adminer	`8080`	Database admin UI
MailHog	`8025`	Email catch-all (web UI)
RedisInsight	`5540`	Redis admin UI

Configure environment variables

Copy the example env file:

cp .env.example .env

The defaults in .env.example are pre-configured to match the Docker Compose service addresses — no changes are needed for local development except for secrets.Generate the required secrets:

# Auth secret
openssl rand -base64 32

# Inter-service API key
openssl rand -hex 32

Then update these values in your .env:

BETTER_AUTH_SECRET=<generated-above>
REALTIME_API_KEY=<generated-above>
ENCRYPTION_KEY=<any-string-for-local-dev>

Never commit your .env file to version control. It is already listed in .gitignore.

Run database migrations

Apply the schema and seed initial data:

pnpm --filter database db:setup

This runs db:migrate (Drizzle migrations) followed by db:seed.

To run migrations only without seeding, use pnpm --filter database db:migrate.

Start the development servers

pnpm dev

Turborepo starts all apps concurrently with hot-reload:

Builder

Web UI and API localhost:3123

PartySocket

WebSocket server localhost:1999

The first run may take a minute while Next.js compiles the Builder.

Git hooks

Git hooks are managed by Lefthook and are installed automatically when you run pnpm install.

Hook	What it does
`pre-commit`	Runs `ultracite fix` (format + lint) on staged files and type-checks the entire project
`commit-msg`	Enforces Conventional Commits format

Commit message format:

<type>(<scope>): <subject>

Valid types: feat, fix, bugfix, refactor, docs, style, test, chore, ci, perf, build, revert

git commit -m "feat(auth): add OAuth2 login"

git commit -m "fix: handle null response from API"

git commit -m "refactor(worker): simplify queue retry logic"

Useful commands

# Run linter across all packages
pnpm lint

# Type-check all packages
pnpm turbo check-types

# Migrate database
pnpm --filter database db:migrate

# Remove all build artifacts and node_modules
pnpm clean

Stopping services

Stop the application servers with Ctrl+C, then stop the Docker infrastructure:

docker compose down

docker compose down -v

Running docker compose down -v permanently deletes all database data, cached files, and storage volumes.

Next Steps

Configure uploads

Set up R2 for file storage

Architecture

Learn the architecture of the project

Email notifications

Set up email for notifications

Channels

Set up channels such as Whatsapp, Messenger and Instagram

Getting started

Installation

Configuration

Reverse Proxies

Super Admin

Channels

Requirements

Installation

Builder

PartySocket

Git hooks

Useful commands

Stopping services

Next Steps

Configure uploads

Architecture

Email notifications

Channels

​Requirements

​Installation

Builder

PartySocket

​Git hooks

​Useful commands

​Stopping services

​Next Steps

Configure uploads

Architecture

Email notifications

Channels

Requirements

Installation

Git hooks

Useful commands

Stopping services

Next Steps