ChatAgents Docker Deployment with Compose and Health Checks

ChatAgents ships with a single Dockerfile and a docker-compose.yml that spin up two containers from the same image — one running the FastAPI backend (python app.py) and one running the Streamlit frontend (streamlit run streamlit_app.py). Both containers share a bridge network so the frontend can reach the backend by its service name (http://backend:8080) without any manual IP configuration.

Prerequisites

Docker — Engine 20.10 or later recommended.
Docker Compose — V2 (docker compose) or the classic V1 plugin (docker-compose). Both work with the provided docker-compose.yml.

Local Docker Deployment

Clone the repository

git clone https://github.com/EllisYuan/ChatAgents.git
cd ChatAgents

Configure environment variables

Copy the sample file and fill in your API keys before building — the Compose file reads from .env at startup:

cp .env.sample .env

Open .env and set at minimum your ANTHROPIC_API_KEY and TAVILY_API_KEY:

ANTHROPIC_API_KEY=sk-ant-api-your-key-here
TAVILY_API_KEY=tvly-your-key-here

# Optional
OPENAI_API_KEY=sk-your-key-here
GROQ_API_KEY=gsk_your-key-here

# Override default host ports if needed
# BACKEND_PORT=8080
# FRONTEND_PORT=8501

Build and start the containers

Run both services in detached mode with a fresh build:

docker-compose up -d --build

Docker will build the image once and launch two named containers: chatbot-backend and chatbot-frontend. The frontend depends_on the backend passing its health check before it starts, so startup order is guaranteed.

Verify both containers are running

docker ps | grep chatbot

You should see both containers with status Up (and healthy for the backend once the health check passes):

CONTAINER ID   IMAGE          COMMAND                  STATUS                    PORTS
a1b2c3d4e5f6   chatagents     "streamlit run strea…"   Up 30 seconds             0.0.0.0:8501->8501/tcp
f6e5d4c3b2a1   chatagents     "python app.py"          Up 45 seconds (healthy)   0.0.0.0:8080->8080/tcp

Open the application

Navigate to http://localhost:8501 in your browser. The chat interface will be live and connected to the backend automatically.

docker-compose.yml Reference

Here is the full Compose configuration shipped with the project:

version: '3.8'

services:
  backend:
    build: .
    container_name: chatbot-backend
    ports:
      - "${BACKEND_PORT:-8080}:8080"
    volumes:
      - ./data:/app/data
    environment:
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - TAVILY_API_KEY=${TAVILY_API_KEY}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GROQ_API_KEY=${GROQ_API_KEY}
      - PORT=8080
    command: python app.py
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    restart: unless-stopped
    networks:
      - chatbot-network

  frontend:
    build: .
    container_name: chatbot-frontend
    ports:
      - "${FRONTEND_PORT:-8501}:8501"
    volumes:
      - ./data:/app/data
    environment:
      - BACKEND_URL=http://backend:8080
    command: streamlit run streamlit_app.py --server.port=8501 --server.address=0.0.0.0
    depends_on:
      backend:
        condition: service_healthy
    restart: unless-stopped
    networks:
      - chatbot-network

networks:
  chatbot-network:
    driver: bridge

Port Configuration

Both host-side ports are configurable via environment variables in your .env file. The container-internal ports (8080 for the backend, 8501 for the frontend) are fixed.

Variable	Default	Description
`BACKEND_PORT`	`8080`	Host port mapped to the FastAPI backend container
`FRONTEND_PORT`	`8501`	Host port mapped to the Streamlit frontend container

To run on non-default ports, add these lines to your .env:

BACKEND_PORT=9080
FRONTEND_PORT=9501

Then restart with docker-compose up -d. The ${VARIABLE:-default} syntax in the Compose file ensures the defaults apply even when the variables are absent.

Health Checks

The backend service has a built-in Docker health check configured in docker-compose.yml:

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Docker polls GET /health every 30 seconds. The endpoint returns {"message": "后端 API 正在运行", "status": "healthy"} when the FastAPI app and LangGraph agent are fully initialised. The frontend container will not start until this check passes (condition: service_healthy), preventing connection errors on boot. To tail recent backend logs and check for errors:

docker logs chatbot-backend --tail 50

To follow logs in real time:

docker logs chatbot-backend -f

Data Persistence

Both containers mount the local ./data directory into /app/data inside the container:

volumes:
  - ./data:/app/data

The session manager writes conversation history as JSON files under data/sessions/. Because the volume is bind-mounted from the host, session data survives container restarts and image rebuilds — you will not lose conversation history when you run docker-compose up -d --build again.

Environment Variables in Docker

All API keys and configuration values flow from your host .env file into the containers through the environment: block in docker-compose.yml:

Variable	Injected into	Notes
`ANTHROPIC_API_KEY`	`backend`	Required for Claude models
`TAVILY_API_KEY`	`backend`	Required for all web tools
`OPENAI_API_KEY`	`backend`	Optional — for OpenAI models
`GROQ_API_KEY`	`backend`	Optional — for Groq models
`PORT`	`backend`	Hard-coded to `8080` inside the container
`BACKEND_URL`	`frontend`	Set to `http://backend:8080` — uses Docker’s internal DNS

The frontend never receives API keys directly; it sends them as request headers to the backend, which validates and uses them per request.

Production Deployment with Nginx

The default docker-compose.yml binds both services to 0.0.0.0, exposing them on all network interfaces. For any internet-facing deployment you should place an Nginx reverse proxy in front to handle TLS termination, rate limiting, and access control.

Basic steps:

Start the containers as described above:
```
docker-compose up -d --build
```
Install and configure Nginx on the host, proxying your-domain.com → localhost:8501 (frontend) and api.your-domain.com → localhost:8080 (backend). See guides/nginx-setup for a complete Nginx configuration with SSL.

Verify the backend health endpoint is reachable through your domain:

curl https://your-domain.com/health

A successful response looks like:

{"message": "后端 API 正在运行", "status": "healthy"}

Useful Docker Commands

Check container status

# Show all ChatAgents containers
docker ps | grep chatbot

# Show resource usage (CPU, memory, network)
docker stats chatbot-backend chatbot-frontend

View logs

# Last 50 lines from the backend
docker logs chatbot-backend --tail 50

# Stream frontend logs in real time
docker logs chatbot-frontend -f

Stop and remove containers

# Stop containers, preserve volumes and images
docker-compose down

# Stop and remove named volumes as well
docker-compose down -v

Rebuild after code changes

# Rebuild image and recreate containers
docker-compose up -d --build

# Force a clean rebuild (no layer cache)
docker-compose build --no-cache
docker-compose up -d

Open a shell inside a container

# Debug the backend container interactively
docker exec -it chatbot-backend /bin/bash

Getting Started

Core Concepts

Configuration

Guides

ChatAgents Docker Deployment with Compose and Health Checks

Prerequisites

Local Docker Deployment

docker-compose.yml Reference

Port Configuration

Health Checks

Data Persistence

Environment Variables in Docker

Production Deployment with Nginx

Useful Docker Commands

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Configuration

Guides

Documentation Index

​Prerequisites

​Local Docker Deployment

​docker-compose.yml Reference

​Port Configuration

​Health Checks

​Data Persistence

​Environment Variables in Docker

​Production Deployment with Nginx

​Useful Docker Commands

Build docs developers (and LLMs) love

Prerequisites

Local Docker Deployment

docker-compose.yml Reference

Port Configuration

Health Checks

Data Persistence

Environment Variables in Docker

Production Deployment with Nginx

Useful Docker Commands