Skip to main content

Docker Compose Installation

This page describes a complete single-server CleverThis installation using Docker Compose. This is the recommended path for small teams and initial deployments.

1. Prepare the server​

Ensure Docker Engine 24+ and Docker Compose v2 are installed:

curl -fsSL https://get.docker.com | sh
docker compose version  # should print v2.x.x

2. Download the compose stack​

curl -O https://github.com/cleverthis/cleverthis/releases/latest/download/docker-compose.yml
curl -O https://github.com/cleverthis/cleverthis/releases/latest/download/.env.example
cp .env.example .env

3. Configure environment variables​

Edit .env and fill in the required values. At minimum:

# App
SECRET_KEY=<generate with: openssl rand -hex 32>
NEXTAUTH_SECRET=<generate with: openssl rand -hex 32>
NEXTAUTH_URL=https://your-domain.com

# Database (uses bundled Postgres by default)
DATABASE_URL=postgresql://cleverthis:cleverthis@postgres:5432/cleverthis

# Redis (uses bundled Redis by default)
REDIS_URL=redis://redis:6379/0

# Email (required for account verification)
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=noreply@example.com
SMTP_PASSWORD=your-smtp-password
EMAIL_FROM=noreply@example.com

# LLM Provider (at least one required)
OPENAI_API_KEY=sk-...

# Stripe (required for billing)
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...

See Environment Variables for the full reference.

4. Start the stack​

docker compose up -d

This starts: postgres, redis, api (FastAPI server), and webapp (Next.js).

5. Run database migrations​

docker compose exec api alembic upgrade head

6. Create the first admin user​

docker compose exec api python -m cleverthis.cli create-admin \
  --email admin@example.com \
  --password <strong-password>

7. Configure TLS​

CleverThis does not handle TLS termination — use a reverse proxy. An example nginx configuration:

server {
    listen 443 ssl;
    server_name your-domain.com;
    ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:3000;  # webapp
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /v1/ {
        proxy_pass http://localhost:8000;  # api
    }

    location /a2a {
        proxy_pass http://localhost:8000;
    }
}
Coming soon

A fully integrated nginx + certbot service in the compose stack is being added.