Skip to main content

Documentation Index

Fetch the complete documentation index at: https://chatbotx.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Requirements

ToolVersionInstall
Node.js>= 24nodejs.org or nvm install 24
pnpm10.33.2corepack enable && corepack prepare pnpm@10.33.2 --activate
Docker24+docs.docker.com
Docker Composev2.20+Included with Docker Desktop

​
Installation

1

Clone the repository

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

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

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:
ServicePortPurpose
PostgreSQL5432Primary database
Redis6379Cache and job queue
Storage (RustFS)9000S3-compatible file storage
Storage Console9001RustFS admin UI
ClickHouse8124Analytics database
Adminer8080Database admin UI
MailHog8025Email catch-all (web UI)
RedisInsight5540Redis admin UI
4

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

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

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.
HookWhat it does
pre-commitRuns ultracite fix (format + lint) on staged files and type-checks the entire project
commit-msgEnforces 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"

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