Guides

Deployment

Copy page

This guide covers deploying Cortex to production environments using Docker Compose and Coolify.

Prerequisites

• A server with Docker and Docker Compose installed
• At least 4GB RAM (8GB+ recommended for production)
• Domain name with DNS configured (for HTTPS)
• OpenAI API key (or alternative LLM provider)

Docker Compose Deployment

Production Configuration

Create a docker-compose.prod.yml:

Code
 
services:
  frontend:
    build:
      context: ./frontend
      dockerfile: Dockerfile.prod
    environment:
      - NODE_ENV=production
      - NEXT_PUBLIC_API_URL=https://api.yourdomain.com
    restart: unless-stopped
    depends_on:
      - backend

  backend:
    build:
      context: ./backend
      dockerfile: Dockerfile.prod
    environment:
      - DEBUG=false
      - REQUIRE_API_KEY=true
      - NEO4J_URI=bolt://neo4j:7687
      - NEO4J_USER=neo4j
      - NEO4J_PASSWORD=${NEO4J_PASSWORD}
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - ADMIN_API_KEY=${ADMIN_API_KEY}
    volumes:
      - uploads:/app/uploads
      - custom_inputs:/app/custom_inputs
    restart: unless-stopped
    depends_on:
      neo4j:
        condition: service_healthy

  neo4j:
    image: neo4j:5-enterprise
    environment:
      - NEO4J_AUTH=neo4j/${NEO4J_PASSWORD}
      - NEO4J_PLUGINS=["apoc"]
      - NEO4J_dbms_memory_heap_initial__size=1G
      - NEO4J_dbms_memory_heap_max__size=2G
    volumes:
      - neo4j_data:/data
      - neo4j_logs:/logs
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "neo4j", "status"]
      interval: 10s
      timeout: 10s
      retries: 5

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
      - ./nginx/ssl:/etc/nginx/ssl:ro
    restart: unless-stopped
    depends_on:
      - frontend
      - backend

volumes:
  neo4j_data:
  neo4j_logs:
  uploads:
  custom_inputs:

Deploy

Code
 
# Set environment variables
export NEO4J_PASSWORD=your-secure-password
export OPENAI_API_KEY=sk-your-key
export ADMIN_API_KEY=cortex_admin_your-key

# Deploy
docker compose -f docker-compose.prod.yml up -d

Coolify Deployment

Cortex includes Coolify-ready configuration for easy deployment.

Setup Steps

1. Create a New Resource

   • Go to your Coolify dashboard
   • Click "New Resource" → "Docker Compose"

2. Configure Git Repository

   • Repository: https://github.com/mocaOS/cortex-app
   • Branch: main
   • Compose file: coolify/docker-compose.coolify.yml

3. Set Environment Variables

   In Coolify's environment section, add:

   Code
    
   NEO4J_PASSWORD=your-secure-password
   OPENAI_API_KEY=sk-your-api-key
   ADMIN_EMAIL=admin@yourdomain.com
   ADMIN_PASSWORD=your-admin-password
   ADMIN_API_KEY=cortex_admin_your-secure-key
   SESSION_SECRET=your-32-character-secret

4. Configure Domains

   • Frontend: cortex.yourdomain.com
   • Backend API: api.cortex.yourdomain.com

5. Deploy

   • Click "Deploy"
   • Wait for containers to start
   • Coolify handles SSL certificates automatically

Coolify Compose File

The coolify/docker-compose.coolify.yml includes Coolify-specific magic variables:

Code
 
services:
  frontend:
    environment:
      - SERVICE_FQDN_FRONTEND_3000=${FRONTEND_URL:-}
    
  backend:
    environment:
      - SERVICE_FQDN_BACKEND_8000=${BACKEND_URL:-}

Nginx Configuration

For manual deployments, configure Nginx as a reverse proxy:

Code
 
# /etc/nginx/nginx.conf
events {
    worker_connections 1024;
}

http {
    upstream frontend {
        server frontend:3000;
    }

    upstream backend {
        server backend:8000;
    }

    # Frontend
    server {
        listen 80;
        server_name cortex.yourdomain.com;
        return 301 https://$server_name$request_uri;
    }

    server {
        listen 443 ssl http2;
        server_name cortex.yourdomain.com;

        ssl_certificate /etc/nginx/ssl/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/privkey.pem;

        location / {
            proxy_pass http://frontend;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection 'upgrade';
            proxy_set_header Host $host;
            proxy_cache_bypass $http_upgrade;
        }
    }

    # API
    server {
        listen 443 ssl http2;
        server_name api.cortex.yourdomain.com;

        ssl_certificate /etc/nginx/ssl/fullchain.pem;
        ssl_certificate_key /etc/nginx/ssl/privkey.pem;

        client_max_body_size 50M;

        location / {
            proxy_pass http://backend;
            proxy_http_version 1.1;
            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;
            
            # SSE support for streaming
            proxy_buffering off;
            proxy_cache off;
        }
    }
}

Health Checks

Backend Health

Code
 
curl https://api.yourdomain.com/health

Expected response:

Code
 
{
  "status": "healthy",
  "neo4j_connected": true,
  "schema_initialized": true,
  "version": "1.0.0"
}

A degraded instance (Neo4j unreachable or schema not yet confirmed) answers HTTP 503 with "status": "degraded" — so curl -f, the compose healthchecks, depends_on: service_healthy, and health-aware proxies all gate on it. The compose healthchecks carry a 60s start_period to cover schema initialization at startup.

Neo4j Health

Code
 
curl https://api.yourdomain.com/api/stats

Redeploy Safety

Before restarting or upgrading an instance (e.g. rolling out a new version), confirm it isn't mid-flight on destructible work:

Code
 
curl https://api.yourdomain.com/api/instance/status \
  -H "X-API-Key: your-manage-key"

Code
 
{
  "safe_to_redeploy": false,
  "reasons": ["2 document(s) currently processing", "1 AskAI query(ies) in flight"],
  "processing_count": 2,
  "pending_count": 5,
  "running_task_count": 0,
  "active_query_count": 1,
  "last_query_at": "2026-06-23T10:14:02+00:00",
  "neo4j_connected": true,
  "checked_at": "2026-06-23T10:15:00+00:00"
}

safe_to_redeploy is false while documents are processing/extracting, background tasks are running (a restart interrupts them — their records survive in Neo4j and are marked failed so pollers get a real answer, but the work must be re-run), or an AskAI/research query is in flight (a restart kills the stream). Pending documents persist in Neo4j and resume after a restart, so they never block. Poll this endpoint in deploy automation and proceed only once safe_to_redeploy is true. Requires manage permission.

Scaling

Backend Scaling

Scale the backend vertically (more CPU/RAM for the single backend container):

Code
 
services:
  backend:
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 4G
        reservations:
          cpus: '1'
          memory: 2G

Do not run multiple backend replicas behind one Neo4j instance: task progress, SSE streams, and rate-limit buckets are tracked in process memory, so replicas would see inconsistent state. For more capacity per deployment, scale vertically; for more isolation, run one full Cortex stack per workload (the container-per-tenant model Cortex Cloud uses).

Neo4j Scaling

For large knowledge bases, increase Neo4j resources:

Code
 
neo4j:
  environment:
    - NEO4J_dbms_memory_heap_initial__size=4G
    - NEO4J_dbms_memory_heap_max__size=8G
    - NEO4J_dbms_memory_pagecache_size=4G

Backup & Recovery

The backup sidecar (recommended)

The Dokploy and Coolify composes include the backup sidecar; on the standalone prod stack add the overlay:

Code
 
docker compose -f docker-compose.prod.yml -f docker-compose.backup.yml up -d

Nightly (BACKUP_INTERVAL_SECONDS), online and verified: a server-side APOC logical export of the graph (graph.cypher.gz) plus a tar of the file volumes, with checksums and a .complete marker. Retention (BACKUP_RETENTION_DAYS, default 7) only rotates after a verified success and never removes the newest complete backup. The sidecar's healthcheck goes unhealthy when the newest verified backup is older than twice the interval, so a silently failing backup shows up in docker ps.

Code
 
# Manual backup / list backups
docker compose exec backup /backup.sh
docker compose exec backup ls /backups

Restore

Code
 
docker compose stop backend
docker compose exec -e RESTORE_WIPE=yes backup /restore.sh <timestamp>
docker compose start backend   # startup recreates all indexes (incl. vector)

File volumes are mounted read-only in the sidecar — restore them from the host with a throwaway container (full runbook in ops/backup/restore.sh). Backups live in the backups volume on the same host; ship them off-host (restic/rclone) for disaster recovery.

Manual physical dump (alternative, requires downtime)

Code
 
docker compose stop backend frontend
docker compose exec neo4j neo4j-admin database dump neo4j --to-path=/backups
docker cp $(docker compose ps -q neo4j):/backups/neo4j.dump ./backups/
docker compose start backend frontend

The two formats are not interchangeable: a .dump restores only via neo4j-admin database load, a sidecar export only via restore.sh.

Monitoring

Logs

Code
 
# All services
docker compose logs -f

# Specific service
docker compose logs -f backend

Resource Usage

Code
 
docker stats

Security Checklist

• Strong NEO4J_PASSWORD set
• ADMIN_API_KEY rotated from default
• SESSION_SECRET is 32+ characters
• HTTPS enabled with valid certificates
• API key authentication enabled (REQUIRE_API_KEY=true)
• CORS configured for your domains only
• Firewall blocks direct access to Neo4j (7687)
• Regular backups scheduled