Deploy Eneo

Deploy Eneo in production with Docker Compose. This page is the primary deployment guide: it takes you from prerequisites to a verified installation, then links to focused guides for storage, authentication, and AI providers.

Start here

Architecture overview

Eneo uses a small service stack. Durable content defaults to bounded PostgreSQL-inline bytes; an optional private object-store byte plane can be enabled when needed.

Prerequisites

Before deploying, ensure you have:

• Docker and Docker Compose v2+ installed
• Domain name with DNS pointing to your server
• SSL certificate (Let’s Encrypt via Traefik, or your own PKI/CA)
• At least one AI provider API key (see AI Provider Configuration)

System Requirements

Quick start

Before running docker compose up:

• replace every your-domain.com, changeme, and CHANGEME;
• generate the database password, JWT_SECRET, and URL_SIGNING_KEY;
• set PUBLIC_ORIGIN in the backend and frontend files;
• configure at least one AI provider;
• create the proxy_tier network;
• pin released Eneo images instead of mutable latest tags;
• leave the optional object-store block commented unless you have chosen and prepared that storage path.

# Option A: Clone the repository
git clone https://github.com/eneo-ai/eneo.git
cd eneo/docs/deployment/
 
# Option B: Download files directly
mkdir eneo-deployment && cd eneo-deployment
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/docker-compose.yml
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/docker-compose.object-content.yml
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/env_backend.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/env_frontend.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/env_db.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/main/docs/deployment/.env.template

cp env_backend.template env_backend.env
cp env_frontend.template env_frontend.env
cp env_db.template env_db.env
cp .env.template .env
chmod 600 .env env_backend.env env_frontend.env env_db.env

# Generate JWT_SECRET (MUST match in backend AND frontend)
JWT_SECRET=$(openssl rand -hex 32)
echo "JWT_SECRET=$JWT_SECRET"
 
# Generate URL_SIGNING_KEY
echo "URL_SIGNING_KEY=$(openssl rand -hex 32)"
 
# Generate database password
echo "POSTGRES_PASSWORD=$(openssl rand -base64 24)"

# Create external network for Traefik
docker network create proxy_tier
 
# Start all services
docker compose up -d
 
# Check status
docker compose ps
 
# View logs
docker compose logs -f

Network Isolation

The Docker Compose stack uses four networks:

PostgreSQL and Redis are only attached to data_net. They are not reachable from frontend or Traefik containers, and they have no outbound internet access.

Verify the isolation after upgrading:

# Should fail: frontend can no longer resolve the database
docker exec eneo_frontend getent hosts db
 
# Should succeed
docker exec eneo_backend python -c "import socket; socket.getaddrinfo('db', 5432)"
curl -fsS https://your-domain.com/version

Environment Configuration

# Development (with uv)
uv run python -m eneo.cli.generate_encryption_key
 
# Production (Docker)
docker compose run --rm backend python -m eneo.cli.generate_encryption_key
 
# Alternative (Python)
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

openssl rand -base64 24

Object Content Storage

The reference stack defaults to bounded PostgreSQL-inline content. An optional Compose profile runs private, Eneo-built SeaweedFS. Deployments that need an existing storage platform or multi-node availability can instead use another compatible endpoint, including MinIO. Both object-store paths use the same contract and fail closed when configuration or the database/bucket binding does not match.

Follow Object Content Storage for the image digest, credentials, MinIO policy, TLS, readiness, backup, and troubleshooting steps. See Object Content Architecture for the control-plane boundary, lifecycle, reconciliation, and image supply chain.

Reverse Proxy Requirements

Any reverse proxy (Traefik, nginx, HAProxy, Caddy) must meet these requirements:

Routing:

Headers:

• X-Forwarded-Proto - original protocol (https)
• X-Forwarded-For - client IP address
• Host - original host header

Requirements:

• WebSocket support (for real-time features)
• TLS termination with valid certificate

Using nginx Instead of Traefik

upstream frontend {
    server frontend:3000;
}
 
upstream backend {
    server backend:8000;
}
 
server {
    listen 443 ssl http2;
    server_name eneo.example.com;
 
    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;
 
    # API routes to backend
    location /api/ {
        proxy_pass http://backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
 
        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
 
    location /docs {
        proxy_pass http://backend;
        proxy_set_header Host $host;
    }
 
    location /openapi.json {
        proxy_pass http://backend;
    }
 
    location /version {
        proxy_pass http://backend;
    }
 
    # Everything else to frontend
    location / {
        proxy_pass http://frontend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

API Key Hierarchy

Eneo uses a three-tier API key system for different administrative tasks.

Credentials API

Manage AI provider credentials per tenant using the sysadmin API.

curl -X PUT "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/credentials/{provider}" \
  -H "X-API-Key: your-super-api-key" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "sk-..."}'

curl "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/credentials" \
  -H "X-API-Key: your-super-api-key"

curl -X DELETE "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/credentials/{provider}" \
  -H "X-API-Key: your-super-api-key"

Supported providers: openai, anthropic, azure, google, mistral, vllm

Crawler Settings API

Configure crawling behavior per tenant.

curl -X PUT "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/crawler-settings" \
  -H "X-API-Key: your-super-api-key" \
  -H "Content-Type: application/json" \
  -d '{"crawl_feeder_enabled": true, "closespider_itemcount": 20000}'

curl "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/crawler-settings" \
  -H "X-API-Key: your-super-api-key"

curl -X DELETE "https://eneo.example.com/api/v1/sysadmin/tenants/{tenant_id}/crawler-settings" \
  -H "X-API-Key: your-super-api-key"

Enabling Features

After deployment, some features require additional configuration in the Admin panel.

Crawler & Document Upload

Apps (Voice/Audio Features)

Sysadmin API Access

To use system administration endpoints (tenants, credentials, crawler settings), set the API key in env_backend.env:

ENEO_SUPER_API_KEY=your-secure-api-key

Modules API Access

To manage module assignments to tenants, set a separate higher-privileged API key:

ENEO_SUPER_DUPER_API_KEY=your-other-secure-api-key

Troubleshooting

Common Issues

Debug Mode

Enable detailed logging for troubleshooting:

# In env_backend.env
LOGLEVEL=DEBUG

Then restart and view logs:

docker compose restart backend
docker compose logs -f backend

Service Health Checks

# Check all services are running
docker compose ps
 
# Test backend API
curl https://your-domain.com/api/health
 
# Check database
docker compose exec db psql -U eneo -c "SELECT version()"
 
# Check Redis
docker compose exec redis redis-cli ping
 
# View db-init logs (for first-run issues)
docker logs eneo_db_init

Container Logs

# All services
docker compose logs -f
 
# Specific service
docker compose logs -f backend
 
# Last 100 lines
docker compose logs --tail=100 backend worker

Maintenance

Version Pinning (Recommended)

The example docker-compose.yml uses :latest tags for simplicity, but for production you should pin versions:

# Default (not recommended for production)
frontend:
  image: ghcr.io/eneo-ai/eneo-frontend:latest
 
# Production (pin to specific version)
frontend:
  image: ghcr.io/eneo-ai/eneo-frontend:v1.2.3
backend:
  image: ghcr.io/eneo-ai/eneo-backend:v1.2.3
worker:
  image: ghcr.io/eneo-ai/eneo-backend:v1.2.3

Find available versions:

• GitHub Releases: https://github.com/eneo-ai/eneo/releases 
• Container Registry: https://github.com/orgs/eneo-ai/packages 

Backups

Database backup with pg_dump (recommended):

# Create timestamped database backup
docker compose exec -T db pg_dump -U eneo eneo | gzip > backup_$(date +%Y%m%d_%H%M%S).sql.gz
 
# Restore from backup (if needed)
gunzip -c backup_20250108.sql.gz | docker compose exec -T db psql -U eneo eneo

Volume backup (for complete recovery):

# Stop services first
docker compose down
 
# Backup PostgreSQL data volume
docker run --rm -v eneo_eneo_postgres_data:/data -v $(pwd):/backup ubuntu \
  tar czf /backup/postgres_volume_$(date +%Y%m%d).tar.gz /data
 
# Backup Redis data volume (optional)
docker run --rm -v eneo_eneo_redis_data:/data -v $(pwd):/backup ubuntu \
  tar czf /backup/redis_volume_$(date +%Y%m%d).tar.gz /data

If object-store rows exist, also archive eneo_eneo_object_content_data while backend, worker, and the object-content service are stopped, or take the matching versioned snapshot in your external provider. Follow the object-content backup and restore procedure, including checksum and skew-recovery checks.

Updating Eneo

# Database backup (required)
docker compose exec -T db pg_dump -U eneo eneo | gzip > backup_$(date +%Y%m%d).sql.gz

docker compose pull
docker compose up -d
docker compose ps

docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  config --quiet
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  pull
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  up -d
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  ps

curl -fsS https://eneo.example.eu/api/readyz \
  | jq -e '.detail.object_content.code == "ready"'

docker image prune -a

docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  stop backend worker object-content
# Restore the matching PostgreSQL dump and object-store snapshot as described
# in the linked procedure, then start the pinned versions:
docker compose \
  --profile object-content \
  -f docker-compose.yml \
  -f docker-compose.object-content.yml \
  up -d
curl -fsS https://eneo.example.eu/api/readyz \
  | jq -e '.detail.object_content.code == "ready"'

Scaling

# Scale backend instances (with load balancer)
docker compose up -d --scale backend=3 --scale worker=2

Related Documentation

• AI Provider Configuration - Configure AI models and providers
• Multi-Tenant OIDC Federation - Enterprise SSO setup
• Single-Tenant OIDC - Simple SSO setup
• SharePoint Integration - Connect SharePoint and OneDrive
• Authentication Architecture - Technical authentication details
• System Architecture - Complete architecture overview
• Object Content Storage - Configure SeaweedFS, MinIO, backups, and readiness
• Release SBOMs and attestations - Verify shipped image digests and provenance