Skip to content
XeroML XeroML

Docker Compose

Docker Compose is the simplest way to self-host XeroML. It runs all services on a single machine and is ideal for development, testing, and small production deployments.

Prerequisites

  • Docker Engine 24.0 or later
  • Docker Compose v2.20 or later
  • A server with at least 4GB RAM and 2 CPUs

Quick Start

Terminal window
# Clone the XeroML repository
git clone https://github.com/xeroml/xeroml.git
cd xeroml


# Copy the example environment file
cp .env.example .env


# Generate secure secrets
openssl rand -hex 32  # Use for NEXTAUTH_SECRET
openssl rand -hex 32  # Use for SALT


# Edit .env with your secrets
nano .env


# Start all services
docker compose up -d

XeroML will be available at http://localhost:3000 after all services start (usually 30-60 seconds).

Environment Configuration

Edit .env with at minimum:

Terminal window
# Required: Application secrets
NEXTAUTH_SECRET=<generate with: openssl rand -hex 32>
SALT=<generate with: openssl rand -hex 32>


# Required: Database connection (auto-configured for Docker Compose)
DATABASE_URL=postgresql://xeroml:xeroml@db:5432/xeroml


# Optional: Email (for account verification)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=user@example.com
SMTP_PASS=password
EMAIL_FROM=noreply@yourdomain.com


# Optional: Object storage for media
LANGFUSE_S3_MEDIA_UPLOAD_ENABLED=true
S3_BUCKET_NAME=your-bucket
S3_ACCESS_KEY=...
S3_SECRET_KEY=...

Services Included

The default docker-compose.yml starts:

ServicePortPurpose
web3000XeroML web application
worker—Background job processor
db5432PostgreSQL database
clickhouse8123Analytics database
redis6379Cache and queues
minio9000Local S3-compatible storage

Updating

Terminal window
# Pull latest images
docker compose pull


# Restart with new images
docker compose up -d


# Check for migration status
docker compose logs worker | grep migration

Production Considerations

For production use with Docker Compose:

  1. Use a reverse proxy — put Nginx or Caddy in front for TLS termination
  2. External PostgreSQL — use a managed database (RDS, Cloud SQL) instead of the containerized one
  3. Persistent volumes — ensure Docker volumes are backed up
  4. Resource limits — set memory and CPU limits on containers
  5. Health checks — monitor the /api/health endpoint

Troubleshooting

Check service status:

Terminal window
docker compose ps
docker compose logs web
docker compose logs worker

See Troubleshooting & FAQ for common issues.