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

# Docker Compose

> Install ChatbotX using Docker Compose

## Docker Compose

The quickest way to get a self-hosted instance running is with Docker Compose. All services — including the database, cache, and file storage — are bundled into a single docker-compose.yml file.

> **Note:** See [how it works](../howitworks.mdx) for an overview of the services that make up the application.

## Requirements

* [Docker](https://docs.docker.com/get-docker/) 24+
* [Docker Compose](https://docs.docker.com/compose/install/) v2.20+
* Minimum **2 GB RAM** and **2 vCPUs** (tested on Ubuntu 24.04)

## Configuration

Environment variables can be provided in one of three ways:

| Method                        | How                                                   |
| ----------------------------- | ----------------------------------------------------- |
| **`.env` file** (recommended) | Place a `.env` file alongside `docker-compose.yml`    |
| **Inline in compose**         | Add an `environment:` block directly to each service  |
| **External secrets manager**  | Mount secrets as files and reference with `env_file:` |

The `.env` file approach is recommended for self-hosted deployments.

***

## Installation

<Steps>
  <Step title="Clone the Docker Compose repository">
    ```text theme={null}
    git clone https://github.com/chatbotxio/chatbotx-docker-compose.git
    ```
  </Step>

  <Step title="Configure you docker compose">
    All environment variables are pre-configured in the docker-compose.yml file. You can skip this step and directly run docker compose.\
    If you want to customize the environment variables, you can create a `.env` file and edit the corresponding values.
  </Step>

  <Step title="Run the docker-compose command">
    ```text theme={null}
    docker compose -p chatbotx up
    ```
  </Step>

  <Step title="Wait for it to load">
    Access your frontend at: [http://localhost:3123 ](http://localhost:3123)(unless changed in variables)
  </Step>
</Steps>

There is a [configuration reference](/configuration/reference) page with a list of configuration settings.

## Example `docker-compose.yml` file

```yaml theme={null}
x-network: &network
  networks:
    - main  

x-depends-datastores: &depends-datastores
  depends_on:
    postgres:
      condition: service_healthy
    redis:
      condition: service_healthy
    filesystem:
      condition: service_healthy

x-environment: &common-vars
  BETTER_AUTH_SECRET: VLu1KcS63DTTnZU3Dh/ykI9Ld26YQXy/1IMJdZf/kHI=
  BETTER_AUTH_URL: http://localhost:3123
  DATABASE_URL: postgresql://chatbotx:secretkey@postgres:5432/chatbotx?schema:public
  NEXT_PUBLIC_ASSET_URL: http://localhost:9000/chatbotx/
  NEXT_PUBLIC_BUILDER_URL: http://localhost:3123
  NEXT_PUBLIC_EDITION: community
  NEXT_PUBLIC_ENVIRONMENT: dev
  NEXT_PUBLIC_SMTP_FROM: no-reply@localhost
  NEXT_PUBLIC_REALTIME_URL: http://localhost:1999
  NODE_OPTIONS: "--max_old_space_size=4096"
  REALTIME_AUTH_URL: http://host.docker.internal:3123
  REALTIME_API_KEY: secretkey
  REDIS_URL: redis://redis:6379
  S3_ACCESS_KEY_ID: chatbotx
  S3_BUCKET: chatbotx
  S3_ENPOINT: http://localhost:9000
  S3_REGION: us-west-2
  S3_SECRET_ACCESS_KEY: secretkey
  SCHEDULER_BUCKET_RANGE: 0-255
  SMTP_SERVER: smtp://username:password@localhost:1025

x-worker: &worker
  <<: [ *network, *depends-datastores ]
  image: ghcr.io/chatbotxio/chatbotx-worker:main
  platform: linux/amd64
  restart: unless-stopped
  extra_hosts:
    - "host.docker.internal:host-gateway"
  environment:
    <<: *common-vars

x-rustfs-environment: &rustfs-environment
  RUSTFS_ACCESS_KEY: ${RUSTFS_ACCESS_KEY:-chatbotx}
  RUSTFS_SECRET_KEY: ${RUSTFS_SECRET_KEY:-secretkey}

services:
  postgres:
    <<: *network
    image: pgvector/pgvector:pg18-trixie
    ports:
      - "5432:5432"
    volumes:
      - db-data:/var/lib/postgresql/data
    command: [ "postgres", "-c", "log_statement=${POSTGRES_LOG_STATEMENT:-none}" ]
    environment:
      - POSTGRES_DB=${POSTGRES_DB:-chatbotx}
      - POSTGRES_USER=${POSTGRES_USER:-chatbotx}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD:-secretkey}
      - PGDATA=/var/lib/postgresql/data/pgdata
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -d $${POSTGRES_DB} -U $${POSTGRES_USER}" ]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  adminer:
    <<: *network
    image: adminer:latest
    depends_on:
      postgres:
        condition: service_healthy
    ports:
      - "${ADMINER_PORT:-8080}:8080"

  mailhog:
    <<: *network
    image: mailhog/mailhog
    ports:
      - 1025:1025
      - 8025:8025

  filesystem:
    <<: *network
    image: rustfs/rustfs:latest
    command: server /data --console-address ":9001"
    ports:
      - "9000:9000"
      - "9001:9001"
    environment:
      <<: *rustfs-environment
    volumes:
      - filesystem-data:/data
    healthcheck:
      test:
        [
          "CMD",
          "sh",
          "-c",
          "curl -f http://127.0.0.1:9000/health && curl -f
            http://127.0.0.1:9001/rustfs/console/health",
        ]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    extra_hosts:
      - "host.docker.internal:host-gateway"

  filesystem-init:
    <<: *network
    image: rustfs/rc:latest
    depends_on:
      filesystem:
        condition: service_healthy
    environment:
      <<: *rustfs-environment
    entrypoint: >
      /bin/sh -c "rc alias set local http://filesystem:9000
      $${RUSTFS_ACCESS_KEY} $${RUSTFS_SECRET_KEY}; rc mb local/chatbotx
      --ignore-existing; touch /tmp/empty && rc cp /tmp/empty
      local/chatbotx/public/; rc anonymous set public local/chatbotx/public;"

  redis:
    <<: *network
    image: redis:8-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis-data:/data
    healthcheck:
      test: [ "CMD", "redis-cli", "ping" ]
      interval: 10s
      timeout: 5s
      retries: 5

  builder:
    <<: [ *network, *depends-datastores ]
    image: ghcr.io/chatbotxio/chatbotx-builder:main
    platform: linux/amd64
    restart: unless-stopped
    environment:
      <<: *common-vars
    ports:
      - "3123:3000"
    healthcheck:
      test: [ "CMD", "curl", "-f", "http://localhost:3000/api/health" ]
      interval: 30s
      timeout: 10s
      retries: 3
    extra_hosts:
      - "host.docker.internal:host-gateway"

  # BullMQ Worker
  worker:
    <<: [ *worker ]
    command: [ "worker", "all" ]

  realtime:
    <<: [ *network ]
    image: ghcr.io/chatbotxio/chatbotx-realtime:latest
    platform: linux/amd64
    restart: unless-stopped
    environment:
      <<: *common-vars
    ports:
      - "1999:1999"
    extra_hosts:
      - "host.docker.internal:host-gateway"

networks:
  main:
    driver: bridge

volumes:
  db-data:
  redis-data:
  filesystem-data:
```

***

### Step 2 — Configure environment variables

Create a `.env` file in the same directory. At minimum, replace all `changeme` values with secure secrets.

```bash theme={null}
NEXT_PUBLIC_ENVIRONMENT=dev
NEXT_PUBLIC_EDITION=community

# S3 Configuration
S3_ACCESS_KEY_ID=chatbotx
S3_BUCKET=chatbotx
S3_REGION=us-west-2
S3_SECRET_ACCESS_KEY=secretkey
S3_ENPOINT=http://localhost:9000

# Auth Configuration
BETTER_AUTH_SECRET=VLu1KcS63DTTnZU3Dh/ykI9Ld26YQXy/1IMJdZf/kHI=
BETTER_AUTH_URL=http://localhost:3123

# Database Configuration
DATABASE_URL=postgresql://chatbotx:secretkey@localhost:5432/chatbotx?schema=public

# Next.js Configuration
NEXT_PUBLIC_ASSET_URL=http://localhost:9000/chatbotx/
NEXT_PUBLIC_BUILDER_URL=http://localhost:3123
NEXT_PUBLIC_REALTIME_URL=http://localhost:1999
NEXT_PUBLIC_SMTP_FROM=no-reply@localhost

REALTIME_AUTH_URL=http://host.docker.internal:3123
REALTIME_API_KEY=secretkey
REDIS_URL=redis://localhost:6379

# SMTP Configuration
SMTP_SERVER=smtp://username:password@localhost:1025

# Sequence Scheduler
SCHEDULER_BUCKET_RANGE=0-255
NODE_OPTIONS="--max_old_space_size=4096"

# Logging Configuration
LOG_LEVEL=debug
```

> **Security:** Never commit `.env` to version control. Add it to `.gitignore`.

***

### Step 3 — Start the services

```bash theme={null}
docker compose -p chatbotx up -d
```

To follow the startup logs:

```bash theme={null}
docker compose logs -f
```

Wait until you see the Builder service report healthy before accessing the UI. This typically takes 30–60 seconds on first boot while the database is initialised.

***

### Step 4 — Access the application

| Service              | URL                     | Notes                   |
| -------------------- | ----------------------- | ----------------------- |
| **Builder** (web UI) | `http://localhost:3123` | Main application        |
| **PartySocket**      | `http://localhost:1999` | WebSocket endpoint      |
| **Storage console**  | `http://localhost:9001` | RustFS admin UI         |
| **Database admin**   | `http://localhost:8080` | Adminer (optional)      |
| **Redis UI**         | `http://localhost:5540` | RedisInsight (optional) |

***

## Default Account

By default, in the open-source version, ChatbotX already has a Workspace set up, and you only need to log in to use it.

Account information:

* Email: [demo@example.com](mailto:demo@example.com)
* Password: Demo\@1234

***

## Updating

Pull the latest images and restart:

```bash theme={null}
docker compose pull
docker compose up -d
```

Database migrations run automatically on Builder startup.

***

## Troubleshooting

**Builder fails to start**

Check that the database and Redis are healthy before the Builder comes up:

```bash theme={null}
docker compose ps
docker compose logs builder
```

**Storage upload errors**

Confirm `filesystem-init` exited with code `0`. It creates the default bucket and sets public read permissions:

```bash theme={null}
docker compose logs filesystem-init
```

**Environment variable not picked up**

Restart the affected service after editing `.env`:

```bash theme={null}
docker compose up -d --force-recreate builder
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Architecture" icon="diagram-project" href="/howitworks">
    Learn the architecture of the project
  </Card>

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