Guides

Deployment

Copy page

This guide covers deploying Cortex to production — with the npx @mocaos/cortex installer, by hand from the release stack, or with Docker Compose and Coolify.

Prerequisites

• A server with Docker Engine 24+ and the Docker Compose v2 plugin (docker compose version — apt install docker.io does not include it)
• At least 4GB RAM (8GB+ recommended for production)
• curl and tar for the installer; git, jq, and openssl as well if you follow the manual release-stack path, whose commands use all three (a minimal server image ships none of them)
• Domain name with DNS configured (for HTTPS)
• OpenAI API key (or alternative LLM provider)

Install with the installer (recommended)

Code
 
npx @mocaos/cortex

One command brings up the whole stack — Cortex, Neo4j, a nightly backup sidecar, and Caddy for automatic HTTPS if you deploy on a domain — from prebuilt, version-pinned images. Cortex Chat is offered as an opt-in extra, off by default. Nothing to clone, nothing to build, no Compose file to edit.

It runs in this order, and stops at the first thing that would waste your time:

1. Environment preflight — Docker daemon, Compose v2, architecture, free disk, RAM, and the ports it is about to bind. The fatal ones stop the install with a plain reason.
2. Live credential validation — a real chat completion and a real embedding call. Nothing is written to disk and no image is pulled until both succeed, so a wrong key costs you seconds instead of a 1.6 GB pull. The embedding dimension is measured here rather than assumed, because it gets baked into the Neo4j vector index on first use.
3. Interactive configuration — localhost or a public domain, whether to install Cortex Chat (default no), your provider and models (embeddings may come from a different provider), your admin identity, and secrets, which are generated for you unless you'd rather set them.
4. Pull, start, verify — writes .env at mode 0600, fetches that release's Compose files, pulls the pinned images, and waits for every service to report healthy before printing your login.

It also owns the instance afterwards, so you rarely touch Compose directly:

Code
 
npx @mocaos/cortex status     # service state, health, URLs
npx @mocaos/cortex doctor     # one pasteable diagnostic block
npx @mocaos/cortex backup     # verified backup now
npx @mocaos/cortex update     # move to the latest tested stack
npx @mocaos/cortex logs       # follow logs

start, stop, restart, config, restore and uninstall round it out. Your data lives in Docker volumes, so stop and uninstall never touch it — removing volumes needs a confirmation and a typed phrase. And if a project name already owns volumes on that machine, the installer stops and offers to rename rather than adopting data that might not be yours.

Requirements: Docker with the Compose v2 plugin, plus curl and tar (both present on macOS and virtually every Linux desktop; Debian's minimal images ship wget instead, and preflight names whichever is missing). npx brings its own Node, but if one is already on your PATH it must be 20.12 or newer.

Two npx failures worth knowing

Neither message points at its real cause:

• could not determine executable to run — there is no install subcommand. npx already means "fetch and run", so npx install @mocaos/cortex asks npm to run a package literally named install. The command is just npx @mocaos/cortex.
• ENOVERSIONS — No versions available for @mocaos/cortex — the package is public and fine; npm is hiding it from you. An .npmrc with min-release-age set (increasingly common after the npm supply-chain compromises of recent months, and worth keeping) filters out every version published inside that window, so a release that is hours old has none left. Override it for the single command rather than disabling the policy:

Code
 
npx --min-release-age=0 @mocaos/cortex

The flag works on any verb, and once the release is older than your window plain npx @mocaos/cortex resolves normally. npm has no way to exempt a single package, so it is the flag or the wait.

Self-host from the release stack (manual)

Everything the installer does, done by hand. Use this if you want to see each step, script it yourself, or manage the stack with existing tooling — the two are kept in sync, so this document also describes the files the installer created.

Since v1.0.0 you don't have to build Cortex to run it. Each release publishes multi-arch images to GHCR plus a static Compose stack under selfhost/ that is configured entirely through .env — you never edit the Compose files, so updates never conflict with local changes.

stack.json, attached to every GitHub release, is the version manifest: it pins the stack version and the component versions that were tested together.

Code
 
curl -fsSL https://github.com/mocaOS/cortex-app/releases/latest/download/stack.json -o stack.json
# {"stack":"1.2.1","components":{"backend":"1.2.1","frontend":"1.2.1","chat":"1.1.0",
#  "neo4j":"5.26-community","caddy":"2-alpine"},"minInstaller":"1.2.2", ... }

git clone --depth 1 --branch "v$(jq -r .stack stack.json)" \
  https://github.com/mocaOS/cortex-app.git /tmp/cortex-src

mkdir -p cortex && cd cortex
cp -r /tmp/cortex-src/selfhost/. .
cp -r /tmp/cortex-src/ops ./ops
cp Caddyfile.template Caddyfile        # or Caddyfile.chat.template, with chat
cp .env.example .env
chmod 600 .env

Fill in at least the secrets block and the LLM block in .env (the comments there carry ready-to-run openssl commands), then:

Code
 
docker compose up -d
docker compose ps

The stack runs Cortex. Cortex Chat is optional — set COMPOSE_PROFILES=chat in .env to include it. With chat installed the two share one identity — ADMIN_EMAIL + ADMIN_PASSWORD — and Chat mints its own scoped backend keys using ADMIN_API_KEY.

Choosing a mode

COMPOSE_FILE in .env selects the topology. Each mode also sets the URL and cookie flags correctly for you, which is what makes the LAN/HTTPS foot-guns below a non-issue here.

Code
 
# Localhost — ports published on BIND_ADDR (127.0.0.1) only
COMPOSE_FILE=docker-compose.yml:docker-compose.ports.yml

Code
 
# Public domain — Caddy with automatic HTTPS
COMPOSE_FILE=docker-compose.yml:docker-compose.caddy.yml
APP_DOMAIN=cortex.example.com
ACME_EMAIL=you@example.com
# with chat only:
COMPOSE_PROFILES=chat
CHAT_DOMAIN=chat.example.com
CHAT_BASE_URL=https://chat.example.com
CORS_ALLOWED_ORIGINS=https://cortex.example.com,https://chat.example.com

Point both A records at the host before the first up — Let's Encrypt issuance fails otherwise. In domain mode only Caddy publishes ports; the API and the Neo4j browser stay private on the Compose network, and the API remains reachable at https://cortex.example.com/api/... because the frontend proxies it.

The ports overlay sets SESSION_COOKIE_SECURE=false (browsers drop Secure cookies on plain HTTP) while domain mode leaves it unset so it defaults to secure — nothing to configure either way. Note that Cortex Chat has no equivalent switch: its cookie is always Secure, which works at http://localhost:3001 but silently fails to log in if you point BIND_ADDR at a LAN IP over plain HTTP. Use domain mode for remote access.

Rules and updates

• Put local changes in docker-compose.override.yml — Compose merges it automatically and updates never touch it. Do not edit docker-compose.yml.
• Never rename the backend service. The published frontend image bakes API_URL=http://backend:8000 into its Next.js rewrite manifest at build time.
• Apps are enabled by default in this stack (the backend's own default is off). Set ENABLE_APPS=false if you want the smaller attack surface.
• Error tracking is off here: SENTRY_DSN_BACKEND / SENTRY_DSN_FRONTEND default to empty rather than to the project's GlitchTip, so a self-hoster's stack traces never leave their box unless they opt in with their own DSN.

To update, re-fetch stack.json and set the three CORTEX_*_IMAGE lines in .env to its component versions — then re-fetch that release's stack files too. New image tags alone are not an update: the Compose files and the ops/ scripts change between releases, and a fix that lives in a shell script arrives no other way.

Code
 
docker compose exec backup /backup.sh   # back up first

rm -rf /tmp/cortex-src
git clone --depth 1 --branch "v$(jq -r .stack stack.json)" \
  https://github.com/mocaOS/cortex-app.git /tmp/cortex-src
cp -r /tmp/cortex-src/selfhost/. .
cp -r /tmp/cortex-src/ops ./ops

docker compose pull
docker compose up -d --build

Your .env, your Caddyfile and any docker-compose.override.yml survive that copy: the release ships .env.example and both Caddyfile templates and carries no override file. If you never hand-edited Caddyfile, re-copy it from the refreshed template so template changes land too — Caddyfile.template without chat, Caddyfile.chat.template with it.

--build is not optional here. The backup sidecar is built from ops/backup rather than pulled — it has no image:, so docker compose pull skips it — and Compose will not rebuild an existing image just because its build context changed. Without --build, a release shipping a corrected backup.sh or restore.sh writes it to disk and keeps running the old one. That is precisely how the v1.0.1 graph-restore fix fails to reach an install that already has a sidecar image built. npx @mocaos/cortex update passes it for you, and stack.json's minInstaller requires an installer version that does.

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 self-host, 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 — uploads, custom inputs, chat data, installed skills, and installed apps — with checksums and a .complete marker. Skills and apps were added in v1.0.0; before that they were silently excluded, and since they are user-authored with no other copy, verify that any older backup you are relying on actually contains them. 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

Restoring is a six-step procedure, not one command: restore.sh replays the graph only, leaving uploads, skills, apps, and chat data untouched.

Code
 
# 1. Pick a <timestamp>
docker compose exec backup ls /backups

# 2. Stop the backend — its graph is about to be wiped and replayed underneath it
docker compose stop backend

# 3. Restore the graph. RESTORE_WIPE=yes is required: it DETACH DELETEs the
#    whole graph and drops its constraints and indexes before replaying the
#    chosen export, which recreates them. Vector indexes are left in place —
#    the export doesn't carry them, the backend rebuilds them at startup, and
#    dropping them would force a pointless re-embed of every chunk.
docker compose exec -e RESTORE_WIPE=yes backup /restore.sh <timestamp>

# 4. Restore the file volumes. The sidecar mounts them read-only, so this runs
#    in a throwaway container. Volume names are ${COMPOSE_PROJECT_NAME}_<name>
#    (the self-host .env.example sets COMPOSE_PROJECT_NAME=cortex).
docker run --rm \
  -v cortex_uploads_data:/data/uploads \
  -v cortex_custom_inputs_data:/data/custom_inputs \
  -v cortex_chat_data:/data/chat \
  -v cortex_skills_data:/data/skills \
  -v cortex_apps_data:/data/apps \
  -v cortex_backups:/backups:ro \
  alpine tar -xzf /backups/<timestamp>/files.tar.gz -C /

# 5. Start the backend — startup recreates every constraint and index,
#    including the vector indexes the logical export does not carry
docker compose start backend

# 6. Verify document/entity counts on GET /api/stats

The authoritative runbook is the header comment 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