Deploying ChatterUI with Docker Compose

ChatterUI is a lightweight, feature-rich web interface for interacting with multiple Large Language Model (LLM) providers. It focuses on a clean, responsive design and supports a wide variety of backends including OpenAI-compatible APIs, Ollama, and local inference servers.

This guide details how to deploy ChatterUI as a self-hosted service using Docker Compose, secure it with a reverse proxy, and maintain the installation.

1. Overview & Architecture

What is ChatterUI?

ChatterUI serves as a unified frontend for AI conversations. Instead of logging into multiple vendor dashboards, you can route your queries through a single interface that supports conversation history, system prompts, and custom model endpoints.

Core Architecture

The application runs entirely in the browser for rendering but relies on a backend server (the Docker container) to handle API authentication and routing. Data is stored locally within the container's persistent volumes.

Practical Trade-offs

• Use ChatterUI if: You want a fast, modern interface for testing multiple LLMs, prefer local control over your data, or need a simple setup for personal experimentation.
• Consider alternatives if: You require heavy team collaboration features, complex role-based access controls, or deep integration with enterprise knowledge bases (in which case, tools like Open WebUI or MaGPT might be more suitable).

2. System Requirements & Directory Structure

As a UI-focused frontend, ChatterUI has modest hardware requirements. It does not run models itself; it proxies requests to other services.

Recommended Hardware

• CPU: Any modern 64-bit processor (1 core is sufficient).
• RAM: 512 MB available to the container (1 GB recommended).
• Storage: Minimal space required; the main size driver is the conversation log database.

Directory Layout

We will organize the deployment in a standard homelab structure to keep configurations clean.

# Create the main application directory
mkdir -p ~/homelab/chatterui/config
mkdir -p ~/homelab/chatterui/data

3. Docker Compose Configuration

Create the docker-compose.yml file inside your new directory. This configuration uses the official vali-98/chatterui image, defines persistent volumes for configuration and user data, and restricts network access to localhost by default.

File: ~/homelab/chatterui/docker-compose.yml

services:
  chatterui:
    # Official image from the upstream repository
    image: vali-98/chatterui:latest
    container_name: chatterui
    restart: unless-stopped
    ports:
      # Map internal port 8080 to host port 8080
      - "127.0.0.1:8080:8080"
    volumes:
      # Persistent storage for application configuration
      - ./config:/app/config
      # Persistent storage for user data and chat history
      - ./data:/app/data
    environment:
      - PUID=1000
      - PGID=1000
      # Optional: Set specific timezone if needed
      - TZ=UTC
      # Optional: Adjust log level
      - LOG_LEVEL=info
    networks:
      - chatterui-network

networks:
  chatterui-network:
    driver: bridge

File: ~/homelab/chatterui/.env

Create an environment file to manage secrets, though ChatterUI primarily handles API keys via the web interface, you may store general configuration here.

# Application Environment Variables
COMPOSE_PROJECT_NAME=chatterui
APP_PORT=8080

4. Step-by-Step Deployment

Navigate to your project directory and bring up the service.

Start the Service

cd ~/homelab/chatterui

docker compose up -d

Verify Container Health

Check that the container is running and inspect the logs to ensure the server initialized correctly.

# Check status
docker compose ps

# View real-time logs
docker compose logs -f

Once the logs indicate the server is listening (typically on port 8080), you can access the web interface by navigating to http://localhost:8080 in your browser.

5. Reverse Proxy & Network Access

For remote access or to handle TLS termination automatically, we recommend using Caddy. Add the following block to your Caddyfile.

Caddyfile Configuration:

chatterui.example.com {
    reverse_proxy localhost:8080
    
    # Enable compression
    encode gzip
}

If you are using Nginx, use this configuration:

server {
    listen 80;
    server_name chatterui.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

6. Common Pitfalls & Troubleshooting

File Permission Errors

If the container fails to write to the mounted volumes, check the ownership of the host directories.

# Fix ownership (assuming PUID/PGID 1000)
sudo chown -R 1000:1000 ~/homelab/chatterui

Port Conflicts

If port 8080 is already in use, the container may fail to bind. Check for conflicts:

sudo lsof -i :8080

If another service is using the port, either stop that service or modify the ports mapping in docker-compose.yml (e.g., change to "127.0.0.1:9090:8080").

Missing API Keys

ChatterUI requires valid API keys for most providers. If you see connection refused errors in the UI, double-check that you have added valid credentials in the Settings menu of the ChatterUI interface. Ensure the host has outbound internet access if you are using cloud-based LLMs.

Logs Diagnostics

If the UI is unresponsive, tail the logs while reproducing the issue:

docker compose logs -f --tail=50

7. Backup & Maintenance

Since ChatterUI stores conversation history and settings in local files, regular backups are essential.

Backup Commands

To backup your data, simply copy the persistent volume directories:

# Create a timestamped backup archive
tar -czvf chatterui-backup-$(date +%Y%m%d).tar.gz \
    ~/homelab/chatterui/config \
    ~/homelab/chatterui/data

Updating the Container

To update to the latest version of ChatterUI:

cd ~/homelab/chatterui
docker compose pull
docker compose up -d

8. Official Resources & Upstream Links

• GitHub Repository: Vali-98/ChatterUI
• Container Image: vali-98/chatterui
• Project Documentation: Refer to the README.md in the official repository for the full list of supported models and advanced configuration options.