Docker Configuration

Environment variables (for example, DATABASE_URL) can be provided to your containers in three ways. Pick the approach that best fits your deployment workflow.

Option 1: Directly in `docker-compose.yml`

Set variables inline in the environment block of each service:

docker-compose.yml

services:
  builder:
    image: ghcr.io/chatbotxio/chatbotx-builder:latest
    environment:
      - NEXT_PUBLIC_BUILDER_URL=https://app.yourdomain.com
      - NEXT_PUBLIC_PARTYSOCKET_URL=https://ws.yourdomain.com
      - BETTER_AUTH_SECRET=your-secret
      - DATABASE_URL=postgresql://chatbotx:password@postgres:5432/chatbotx?schema=public
      - REDIS_URL=redis://redis:6379

  worker:
    image: ghcr.io/chatbotxio/chatbotx-worker:latest
    environment:
      - DATABASE_URL=postgresql://chatbotx:password@postgres:5432/chatbotx?schema=public
      - REDIS_URL=redis://redis:6379
      - ENCRYPTION_KEY=your-encryption-key

  realtime:
    image: ghcr.io/chatbotxio/chatbotx-realtime:latest
    environment:
      - REDIS_URL=redis://redis:6379
      - PARTYSOCKET_API_KEY=your-api-key

Avoid hardcoding secrets directly in docker-compose.yml if you commit the file to version control. Use Option 2 or 3 instead.

Option 2: Using a `.env` file

Reference a separate .env file with env_file. Docker reads the file and injects every variable into the container.

docker-compose.yml

services:
  builder:
    image: ghcr.io/chatbotxio/chatbotx-builder:latest
    env_file:
      - .env

  worker:
    image: ghcr.io/chatbotxio/chatbotx-worker:latest
    env_file:
      - .env

  realtime:
    image: ghcr.io/chatbotxio/chatbotx-realtime:latest
    env_file:
      - .env

Add .env to .gitignore to keep secrets out of version control.

Option 3: Combine both

Use env_file for shared variables and environment to override specific values per service. Variables defined in environment take precedence over values in the .env file.

docker-compose.yml

services:
  builder:
    image: ghcr.io/chatbotxio/chatbotx-builder:latest
    env_file:
      - .env
    environment:
      - HOSTNAME=0.0.0.0
      - LOG_LEVEL=info

  worker:
    image: ghcr.io/chatbotxio/chatbotx-worker:latest
    env_file:
      - .env
    environment:
      - SCHEDULER_BUCKET_RANGE=0-255
      - NODE_OPTIONS=--max_old_space_size=4096

  realtime:
    image: ghcr.io/chatbotxio/chatbotx-realtime:latest
    env_file:
      - .env
    environment:
      - LOG_LEVEL=info

All environment variables must be defined before starting the containers. Services validate their required variables on startup and will exit immediately if any are missing.
When environment and env_file are both set, the environment block overrides values from the .env file.
DATABASE_URL, REDIS_URL, and storage credentials are shared across all three services — define them once in .env rather than repeating them per service.

Variable substitution

Docker Compose also supports substituting variables from the host shell or a .env file placed next to docker-compose.yml:

docker-compose.yml

services:
  builder:
    image: ghcr.io/chatbotxio/chatbotx-builder:latest
    environment:
      - DATABASE_URL=${DATABASE_URL}
      - BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}

This is useful when deploying from a CI/CD pipeline that injects secrets as environment variables rather than files.

See the full list of supported variables in the configuration reference.

Getting started

Installation

Configuration

Reverse Proxies

Super Admin

Channels

Option 1: Directly in `docker-compose.yml`

Option 2: Using a `.env` file

Option 3: Combine both

Variable substitution

​Option 1: Directly in docker-compose.yml

​Option 2: Using a .env file

​Option 3: Combine both

​Variable substitution

Option 1: Directly in `docker-compose.yml`

Option 2: Using a `.env` file

Option 3: Combine both

Variable substitution