Docker Deployment

ChatterMate can be deployed using Docker in both development and production environments.

Development Setup

For local development, we use docker-compose.yml which sets up:

Frontend (Vue.js) with hot-reloading
Backend (FastAPI) with auto-reload
PostgreSQL with pgvector extension
Redis for caching and rate limiting

Prerequisites

Docker
Docker Compose
Git

Quick Start

Clone the repository:

git clone https://github.com/chattermate/chattermate.chat
cd chattermate.chat

Create environment files:

# Frontend environment
cp frontend/.env.example frontend/.env

# Backend environment
cp backend/.env.example backend/.env

Start the development environment:

docker-compose up --build

Services will be available at:

Frontend: http://localhost:3000
Backend API: http://localhost:8000
Backend Docs: http://localhost:8000/docs
PostgreSQL: localhost:5432
Redis: localhost:6379

Development Features

Hot-reloading for frontend changes
Auto-reload for backend changes
Volume mounts for live code updates
Development-mode Firebase credentials
Automatic database migrations
Health checks for all services

Production Deployment

For production deployment, we use docker-compose.prod.yml which provides:

Optimized multi-stage builds
Nginx for frontend serving
Gunicorn for backend serving
Production-grade configurations
Health monitoring
Automatic restarts

Production Setup

Set up environment files:

# Frontend production environment
cp frontend/.env.prod.example frontend/.env

# Backend production environment
cp backend/.env.prod.example backend/.env

Configure Firebase (Optional):

# Place your Firebase credentials in
./config/firebase-credentials.json

Start production services:

docker-compose -f docker-compose.prod.yml up -d

Production Features

Multi-stage builds for smaller images
Nginx configuration for frontend
Gunicorn with multiple workers
Redis persistence
Database backups
Automatic health checks
Container restart policies

Docker Images

Frontend Images

Development: Dockerfile.frontend
- Node.js development server
- Hot-reloading enabled
- Volume mounts for live updates
Production: Dockerfile.frontend.prod
- Multi-stage build
- Nginx for static file serving
- Optimized build size
- Health monitoring

Backend Images

Development: Dockerfile
- Python development server
- Auto-reload enabled
- Debug mode
Production: Dockerfile.backend.prod
- Multi-stage build
- Gunicorn server
- Optimized dependencies
- Worker configuration

Database Image

Custom PostgreSQL image with pgvector
Vector similarity search support
Automatic initialization
Health checks

Environment Variables

Frontend Variables

VITE_API_URL=http://localhost:8000
VITE_WS_URL=ws://localhost:8000

Backend Variables

DATABASE_URL=postgresql://postgres:postgres@db:5432/chattermate
CORS_ORIGINS=["http://localhost:3000"]
FIREBASE_CREDENTIALS=/app/config/firebase-credentials.json

Production Additional Variables

REDIS_ENABLED=true
REDIS_URL=redis://redis:6379/0
WORKERS=4
TIMEOUT=120
LOG_LEVEL=info

Health Checks

All services include health checks:

Frontend: Checks HTTP endpoint
Backend: Monitors API health
PostgreSQL: Verifies database connection
Redis: Ensures cache availability

Volumes

Persistent data is managed through Docker volumes:

postgres_data: Database files
redis_data: Cache data
backend_data: Uploaded files
frontend_node_modules: NPM packages

Networks

Services communicate through Docker networks:

Development: app-network
Production: chattermate-network

Monitoring

Monitor your deployment using Docker commands:

# View all logs
docker-compose logs -f

# Service-specific logs
docker-compose logs -f frontend
docker-compose logs -f backend
docker-compose logs -f db
docker-compose logs -f redis

# Container health
docker ps

Help Center custom domains (self-hosted)

The Help Center can be served on your customers’ own domains with automatic HTTPS. The chattermate-deploy CLI bundles a Caddy edge proxy that terminates TLS and issues certificates automatically — no manual certbot or nginx.

Deploy with a domain

Run chattermate-deploy init and answer yes to the domain prompt. Enter your app domain (e.g. app.example.com) and, optionally, a Help Center base domain (e.g. help.example.com) for org subdomains. Then chattermate-deploy start.

Point DNS at your server

Add an A/AAAA record for your app domain to the server’s IP. For Help Center org subdomains, add a wildcard *.help.example.com A/AAAA record too. Certificates are issued automatically on the first HTTPS request.

Add a customer's custom domain

In Customization → Custom domain, add the domain and create the TXT record shown. Add a CNAME from the customer’s domain to your app domain (which already resolves to your server), then click Verify.

Under the hood the edge only requests a certificate for a hostname the backend confirms it serves (a verified custom domain or an org subdomain), so a random domain pointed at your server cannot trigger certificate issuance.

TLS options

When you give init a domain, it asks how HTTPS should be handled:

Automatic (default) — Caddy obtains and renews free Let’s Encrypt certificates, and issues Help Center custom-domain certs on demand.
Bring your own certificate — provide a cert + key (PEM); they’re copied into ./certs and served by Caddy, with no calls to Let’s Encrypt. For Help Center domains, add a block per domain (or a wildcard) — the generated Caddyfile includes a commented example.
Terminated upstream — your own reverse proxy / load balancer handles TLS and forwards plain HTTP to the stack. It must preserve the Host header so the backend can dispatch Help Center domains.

Renewal is automatic — Caddy renews certificates well before expiry with no cron or certbot. Certificates and the ACME account are stored in the caddy_data Docker volume, so keep it across restarts and upgrades — deleting it forces re-issuance and can hit Let’s Encrypt rate limits. If a custom domain sits behind Cloudflare, set the record to DNS only (grey cloud) for verification, or the CNAME check fails.

Troubleshooting

Common issues and solutions:

Frontend not starting:

# Check frontend logs
docker-compose logs frontend

# Rebuild frontend
docker-compose build --no-cache frontend

Backend migrations failing:

# Check backend logs
docker-compose logs backend

# Manual migration
docker-compose exec backend alembic upgrade head

Database connection issues:

# Check database logs
docker-compose logs db

# Verify database health
docker-compose exec db pg_isready -U postgres

Redis connection issues:

# Check Redis logs
docker-compose logs redis

# Verify Redis connection
docker-compose exec redis redis-cli ping

Backend build fails with No space left on device or pip ReadTimeoutError:

The backend image pulls several GB of ML wheels (torch, opencv, onnxruntime), and the amd64/x86_64 wheels are noticeably larger than the arm64 ones. On a small root volume the build overflows with No space left on device.

Give the host at least ~15 GB free disk when building from source.
This only affects building the image yourself — the prebuilt Docker Hub images (chattermate/backend, chattermate/frontend) avoid it entirely.
Slow-link download timeouts are already handled in the Dockerfiles (PIP_DEFAULT_TIMEOUT=120 and pip --retries 10).

Help Center custom domain stuck on “SSL Provisioning” / returns 404:

The domain never reached the edge, so no certificate was issued.

Deploy with the chattermate-deploy CLI and a domain (see Help Center custom domains) — a plain localhost deploy has no TLS edge and can’t serve custom domains.
Check the domain resolves to your server (CNAME to your app domain) and that ports 80 and 443 are open — Let’s Encrypt validates over both.
The certificate is issued on the first HTTPS request; give it a few seconds, then re-check Verify. Inspect the edge with docker compose logs caddy.

Getting Started

Features

Channels

Developer Tools

Deployment

Docker Deployment

Docker Deployment

Development Setup

Prerequisites

Quick Start

Development Features

Production Deployment

Production Setup

Production Features

Docker Images

Frontend Images

Backend Images

Database Image

Environment Variables

Frontend Variables

Backend Variables

Production Additional Variables

Health Checks

Volumes

Networks

Monitoring

Help Center custom domains (self-hosted)

TLS options

Troubleshooting

​Docker Deployment

​Development Setup

​Prerequisites

​Quick Start

​Development Features

​Production Deployment

​Production Setup

​Production Features

​Docker Images

​Frontend Images

​Backend Images

​Database Image

​Environment Variables

​Frontend Variables

​Backend Variables

​Production Additional Variables

​Health Checks

​Volumes

​Networks

​Monitoring

​Help Center custom domains (self-hosted)

​TLS options

​Troubleshooting

Docker Deployment

Development Setup

Prerequisites

Quick Start

Development Features

Production Deployment

Production Setup

Production Features

Docker Images

Frontend Images

Backend Images

Database Image

Environment Variables

Frontend Variables

Backend Variables

Production Additional Variables

Health Checks

Volumes

Networks

Monitoring

Help Center custom domains (self-hosted)

TLS options

Troubleshooting