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

# Development Environment

> Set up ChatbotX for local development

<Note>
  See [how it works](/howitworks) for an overview of the architecture before diving in.
</Note>

## Requirements

| Tool               | Version | Install                                                       |
| ------------------ | ------- | ------------------------------------------------------------- |
| **Node.js**        | >= 24   | [nodejs.org](https://nodejs.org) or `nvm install 24`          |
| **pnpm**           | 10.33.2 | `corepack enable && corepack prepare pnpm@10.33.2 --activate` |
| **Docker**         | 24+     | [docs.docker.com](https://docs.docker.com/get-docker/)        |
| **Docker Compose** | v2.20+  | Included with Docker Desktop                                  |

***

## Installation

<Steps>
  <Step title="Clone the repository">
    ```bash theme={null}
    git clone https://github.com/ChatbotXIO/ChatbotX.git
    cd ChatbotX
    ```
  </Step>

  <Step title="Install dependencies">
    ```bash theme={null}
    pnpm install
    ```

    This installs dependencies for all apps and packages in the monorepo via [Turborepo](https://turbo.build). Git hooks (Lefthook) are also set up automatically at this step.
  </Step>

  <Step title="Start infrastructure services">
    Spin up PostgreSQL, Redis, Storage, and ClickHouse (optional) using Docker Compose:

    ```bash theme={null}
    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            |
    | ClickHouse       | `8124` | Analytics database         |
    | Adminer          | `8080` | Database admin UI          |
    | MailHog          | `8025` | Email catch-all (web UI)   |
    | RedisInsight     | `5540` | Redis admin UI             |
  </Step>

  <Step title="Configure environment variables">
    Copy the example env file:

    ```bash theme={null}
    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:

    ```bash theme={null}
    # Auth secret
    openssl rand -base64 32

    # Inter-service API key
    openssl rand -hex 32
    ```

    Then update these values in your `.env`:

    ```bash theme={null}
    BETTER_AUTH_SECRET=<generated-above>
    REALTIME_API_KEY=<generated-above>
    ENCRYPTION_KEY=<any-string-for-local-dev>
    ```

    <Warning>
      Never commit your `.env` file to version control. It is already listed in `.gitignore`.
    </Warning>
  </Step>

  <Step title="Run database migrations">
    Apply the schema and seed initial data:

    ```bash theme={null}
    pnpm --filter database db:setup
    ```

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

    <Tip>
      To run migrations only without seeding, use `pnpm --filter database db:migrate`.
    </Tip>
  </Step>

  <Step title="Start the development servers">
    ```bash theme={null}
    pnpm dev
    ```

    Turborepo starts all apps concurrently with hot-reload:

    <Columns cols={3}>
      <Card title="Builder" icon="browser" href="http://localhost:3123">
        Web UI and API 

        `localhost:3123`
      </Card>

      <Card title="PartySocket" icon="bolt" href="http://localhost:1999">
        WebSocket server 

        `localhost:1999`
      </Card>
    </Columns>

    <Note>
      The first run may take a minute while Next.js compiles the Builder.
    </Note>
  </Step>
</Steps>

***

## Git hooks

Git hooks are managed by [Lefthook](https://github.com/evilmartians/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](https://www.conventionalcommits.org) format             |

**Commit message format:**

```text theme={null}
<type>(<scope>): <subject>
```

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

<CodeGroup>
  ```bash Feature theme={null}
  git commit -m "feat(auth): add OAuth2 login"
  ```

  ```bash Fix theme={null}
  git commit -m "fix: handle null response from API"
  ```

  ```bash Refactor theme={null}
  git commit -m "refactor(worker): simplify queue retry logic"
  ```
</CodeGroup>

***

## Useful commands

```bash theme={null}
# 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:

<CodeGroup>
  ```bash Stop only theme={null}
  docker compose down
  ```

  ```bash Stop and wipe all data theme={null}
  docker compose down -v
  ```
</CodeGroup>

<Warning>
  Running `docker compose down -v` permanently deletes all database data, cached files, and storage volumes.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure uploads" icon="cloud-arrow-up" href="/configuration/r2">
    Set up R2 for file storage
  </Card>

  <Card title="Architecture" icon="diagram-project" href="/howitworks">
    Learn the architecture of the project
  </Card>

  <Card title="Email notifications" icon="envelope" href="/configuration/emails">
    Set up email for notifications
  </Card>

  <Card title="Channels" icon="plug" href="/channels/channels-overview">
    Set up channels such as Whatsapp, Messenger and Instagram
  </Card>
</CardGroup>