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 for an overview of the services that make up the application.

Requirements

Docker 24+
Docker Compose v2.20+
Minimum 4 GB RAM and 4 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

Clone the Docker Compose repository

git clone https://github.com/chatbotxio/chatbotx-docker-compose.git

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.

Run the docker-compose command

docker compose -p chatbotx up

Wait for it to load

Access your frontend at: http://localhost:3123 (unless changed in variables)

There is a configuration reference page with a list of configuration settings.

Example `docker-compose.yml` file

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.

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

docker compose -p chatbotx up -d

To follow the startup logs:

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
Password: Demo@1234

Updating

Pull the latest images and restart:

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:

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:

docker compose logs filesystem-init

Environment variable not picked up Restart the affected service after editing .env:

docker compose up -d --force-recreate builder

Getting started

Installation

Configuration

Reverse Proxies

Super Admin

Channels

Docker Compose

Docker Compose

Requirements

Configuration

Installation

Example `docker-compose.yml` file

Step 2: Configure environment variables

Step 3: Start the services

Step 4: Access the application

Default Account

Updating

Troubleshooting

Next Steps

Architecture

Channels

​Docker Compose

​Requirements

​Configuration

​Installation

​Example docker-compose.yml file

​Step 2: Configure environment variables

​Step 3: Start the services

​Step 4: Access the application

​Default Account

​Updating

​Troubleshooting

​Next Steps

Architecture

Channels

Docker Compose

Requirements

Configuration

Installation

Example `docker-compose.yml` file

Step 2: Configure environment variables

Step 3: Start the services

Step 4: Access the application

Default Account

Updating

Troubleshooting

Next Steps