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

> How to pass environment variables to ChatbotX services in Docker and Docker Compose.

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:

```yaml docker-compose.yml theme={null}
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
```

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

***

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

```yaml docker-compose.yml theme={null}
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
```

<Tip>
  Add `.env` to `.gitignore` to keep secrets out of version control.
</Tip>

***

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

```yaml docker-compose.yml theme={null}
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
```

<Note>
  * 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.
</Note>

***

## Variable substitution

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

```yaml docker-compose.yml theme={null}
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.

<Tip>
  See the full list of supported variables in the [configuration reference](/configuration/reference).
</Tip>