Deployment

Deploy Enclavr to production.

Quick Start

Deploy Enclavr using Docker Compose, or use Neon (serverless PostgreSQL) for the database.

Option 1: Neon PostgreSQL (Recommended)

Neon is the default database - create a project at neon.tech:

1. Create a Neon project at neon.tech
2. Get your connection string from the Neon dashboard
3. Set NEON_CONNECTION_STRING environment variable:

   NEON_CONNECTION_STRING=postgres://user:password@host.neon.tech/neondb?sslmode=require

4. Run Redis with Docker: docker run -d --name enclavr-redis -p 6379:6379 redis:8

Option 2: Docker Compose

# Clone with submodules
git clone --recurse-submodules https://github.com/enclavr/enclavr.git
cd enclavr/infra

# Copy environment file
cp .env.example .env
# Edit .env with your values

# Start services
docker compose up -d

Production Checklist

• Change JWT_SECRET to a secure random string
• Set strong DB_PASSWORD
• Configure REDIS_PASSWORD
• Set up SSL/TLS with Caddy (automatic HTTPS) or reverse proxy
• Configure TURN server credentials
• Set up regular database backups
• Enable monitoring profile for observability
• PostgreSQL 18+: Set PGDATA: /var/lib/postgresql/18/docker environment variable (volume path changed from older versions)

Docker Compose Profiles

Enclavr uses Docker Compose profiles for flexible deployment. Use the Makefile shortcuts:

# Core services only (default)
make up

# With monitoring (Prometheus, Grafana, Loki, Alertmanager)
make monitoring

# With voice (Coturn TURN server)
make voice

# With automated backups
make backup

# With automatic HTTPS (Caddy)
make tls

# With object storage (MinIO)
make storage

# Full stack (all profiles)
make full

# Production (full + TLS)
make prod

# Development mode (hot reload)
make dev

All Makefile Targets

Development Mode

The docker-compose.override.yml file is automatically loaded by Docker Compose when present. Use make dev to start in development mode.

Production Overrides

A docker-compose.prod.yml file provides production-specific overrides. It is not automatically loaded — you must explicitly include it:

# Start with production overrides
docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d

# Or use the Makefile (make prod uses --profile full --profile tls)
make prod

Production Override Settings

Development Features

Automatic HTTPS with Caddy

Caddy provides automatic HTTPS via Let's Encrypt:

# In .env, set:
DOMAIN=enclavr.example.com
ACME_EMAIL=admin@example.com
MONITORING_DOMAIN=monitoring.example.com
GRAFANA_BASIC_AUTH_USER=admin
GRAFANA_BASIC_AUTH_HASH=...  # htpasswd hash

# Start with TLS profile
make tls

Caddy features:

• Automatic Let's Encrypt certificate management
• API subdomain routing (api.{DOMAIN}) with separate reverse proxy to server:8080
• Monitoring subdomain ({MONITORING_DOMAIN}) with basic auth protection, proxying to Grafana
• WebSocket upgrade support for voice signaling (automatic with reverse_proxy)
• API rate limiting (requires custom Caddy build with caddy-ratelimit module; disabled by default)
• Security headers (HSTS, X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy)
• Path blocking for sensitive files (/.git*, /.env*, /.docker*, /docker-compose*)
• Gzip compression
• QUIC/HTTP3 support (port 443/udp)
• ACME staging CA available (commented out) for testing

Caddy Subdomain Routing

Automatic Container Updates

Watchtower automatically updates running containers:

# Enable the maintenance profile
docker compose --profile maintenance up -d

Containers with the com.centurylinklabs.watchtower.enable=true label are eligible for auto-updates.

Database Backups

Automated backups run via the backup Docker Compose profile:

# Enable automated backups (daily at 2 AM by default)
make backup

# Manual backup
make pg-backup

# Restore from backup
make pg-restore FILE=backup.sql.gz

Volumes marked for backup: postgres_data, server_uploads, grafana_data, backup_data.

Alternative Reverse Proxy

If you prefer nginx or another reverse proxy instead of Caddy:

server {
    listen 443 ssl;
    server_name enclavr.example.com;
    
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
    
    location / {
        proxy_pass http://frontend:3000;
    }
    
    location /api/ {
        proxy_pass http://server:8080;
    }
    
    location /ws {
        proxy_pass http://server:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}