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)
• An API key for at least one AI provider. Providers are added after the first login in Admin → Models (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;
• have at least one AI provider API key ready for Admin → Models;
• 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/develop/docs/deployment/docker-compose.yml
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/docker-compose.object-content.yml
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/env_backend.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/env_frontend.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/env_db.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/.env.template
 
# Only if you plan to run optional modules (see "Optional modules" below)
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/docker-compose.modules.yml
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/env_modules.template
curl -O https://raw.githubusercontent.com/eneo-ai/eneo/develop/docs/deployment/env_module_ttt.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 (backend token signing key)
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 (MUST match in env_backend.env AND env_db.env)
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, Traefik, or module 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

The tables below cover the values you must set or are most likely to change. The templates in docs/deployment/ are the complete reference: every variable is listed there with its shipped value and a comment.

# .env
REDIS_PASSWORD=<output of: openssl rand -hex 32>

# 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

Signed file references

When an assistant may open attached files itself (the “Låt assistenten öppna bifogade filer själv” switch, inline_file_text=false), or when a tool edits an attached or generated image, the model receives each file as a signed link instead of its content:

{FILE_REFERENCE_BASE_URL}/api/v1/files/{file_id}/original/download/?token=...

Both Eneo’s built-in file tool and external MCP servers receive the same link. The built-in tool verifies the token locally and never makes an HTTP request. An external MCP server redeems the link over HTTP, so the Eneo backend must be reachable from the network where that MCP server runs. This is independent of where the file bytes live: originals stored in PostgreSQL and originals stored in object storage are served through the same endpoint.

The download endpoint accepts no session cookie or API key. The signed token is the only credential: it names the file and tenant, is signed with URL_SIGNING_KEY, and expires after FILE_REFERENCE_URL_EXPIRY_SECONDS (default one hour). Anyone holding an unexpired link can download the file. Treat every MCP server that receives file links as a recipient of the file contents, and enable such servers only where that data flow is acceptable.

Two controls limit the exposure of a link:

• Every redemption is audited as file_original_downloaded under File operations, with the caller’s address and user agent, next to the file_original_download_link_created entry written when the link was minted.
• The token is stripped from tool-call arguments and results before they are stored, shown in the chat, or replayed to the model. Only the tool that was called ever holds the live link. Deleting the file revokes every outstanding link for it.

Choose FILE_REFERENCE_BASE_URL by where the MCP servers run:

On a private network with no route from the MCP server to the backend, the tool call fails. The model is told the link is valid, so it reports that the tool cannot reach the file rather than asking the user to upload it again. The fix is always network reachability or a corrected base URL, never a re-upload.

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.

Policy changes take effect without a backend or worker restart. They affect eligible new writes only; existing content stays in its recorded backend until an explicit verified migration moves it. The product has one provider-neutral object-store path, not vendor-specific storage modes. Admin > File storage also compares Eneo’s recorded file-content size with the entire PostgreSQL database on disk. These figures overlap: inline file content is part of both totals, and the PostgreSQL figure also includes searchable text, pgvector embeddings, tables, indexes, and internal storage. The page does not report remaining host or bucket capacity. See What do the storage-usage figures mean? for the exact boundaries.

The same page presents current status before configuration: the active target, object-store health, file-content distribution, and migration state appear first. PostgreSQL allocation and detailed effective limits remain available as technical details instead of competing with routine storage decisions.

The page also shows the portable multipart envelope when it constrains object-store session uploads. FastAPI/Starlette multipart parsing happens before route admission and may use temporary disk. Eneo rejects an oversized File or Icon before its own capture/spool or any storage mutation. Operators must use ingress/request-body limits and configure and monitor temporary-disk capacity to protect that earlier parsing boundary.

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.

Optional modules

Modules are optional web applications (for example speech-to-text) that run next to Eneo on their own domain. A module container joins only module_net, calls the backend at http://backend:8000 with a scoped sk_ service key, and can never reach PostgreSQL or Redis. Users log in through their Eneo session; modules have no IdP configuration of their own.

Modules ship as a Compose overlay that is inert until you enable a profile:

cp env_modules.template env_modules.env
cp env_module_ttt.template env_module_ttt.env
# In .env, uncomment and set ENEO_DOMAIN, MODULE_TTT_DOMAIN and MODULE_STT_VERSION
 
docker compose -f docker-compose.yml -f docker-compose.modules.yml \
  --profile speech-to-text up -d

The module domain must point at the same Traefik ingress; the overlay routes it over eneo_module_net. See Module Authentication for the login handoff, ticket exchange, and session refresh contract, and Module administration below for the admin-side prerequisites.

Reverse Proxy Requirements

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

Routing:

These are the exact prefixes the shipped Traefik labels route to the backend.

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";
    }
 
    # SCIM provisioning (identity provider calls /scim/v2/...)
    location /scim/ {
        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;
    }
 
    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 environment and user/service credentials for separate tasks.

Both are sent in the X-API-Key header (configurable with API_KEY_HEADER_NAME).

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 {provider} values: openai, anthropic, azure, mistral, ovhcloud, gemini, cohere

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

Module administration

Configure modules in Admin → Modules with an ordinary signed-in administrator holding the modules permission. The organization is derived from the session; module administration does not require a separate environment key or a tenant ID. The container side is covered in Optional modules.

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

The backend is not published on a host port in the reference stack, so run these through your public domain (or from inside a container).

# Check all services are running
docker compose ps
 
# Liveness: the API process answers
curl -fsS https://your-domain.com/api/livez
 
# Health: backend, worker heartbeat, and object-content readiness (503 if the worker is unhealthy)
curl -fsS https://your-domain.com/api/healthz
 
# Readiness alias of /api/healthz on current images (older released images only have /api/healthz)
curl -fsS https://your-domain.com/api/readyz
 
# Detailed crawler diagnostics (requires the deployment's super API key)
curl -fsS https://your-domain.com/api/healthz/crawler \
  -H "X-API-Key: $ENEO_SUPER_API_KEY"
 
# Running backend version
curl -fsS https://your-domain.com/version
 
# Check database
docker compose exec db psql -U postgres -d 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
db-init:
  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 postgres 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 postgres 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

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

docker compose stop backend worker
docker compose pull
docker compose run --rm db-init
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 \
  stop backend worker
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 \
  run --rm db-init
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 compose logs --since=30m worker \
  | grep "File/Icon legacy backfill"

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

The reference docker-compose.yml sets a fixed container_name on every service, so docker compose up --scale ... is refused. To run more than one backend or worker replica, define additional services without container_name (or run the images under an orchestrator) and place the backend replicas behind your load balancer. Additional workers are safe: only one crawl feeder runs across all workers through leader election.

Related Documentation

• AI Provider Configuration - Configure AI models and providers
• Multi-Tenant OIDC Federation - Enterprise SSO setup
• Single-Tenant OIDC - Simple SSO setup
• SCIM Provisioning - Automated user and group provisioning
• SharePoint Integration - Connect SharePoint and OneDrive
• Module Authentication - Login handoff contract for optional modules
• 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