docker-compose.yml

services:
  code-index-api:
    image: dvcdsys/code-index:latest
    container_name: code-index
    restart: unless-stopped
    ports:
      - "${PORT:-21847}:21847"
    environment:
      - CIX_API_KEY=${CIX_API_KEY}
      # Defense in depth — the image already defaults to 21847 (since
      # v0.5.1) but pinning it here keeps the host:container port mapping
      # honest if a third-party fork or custom build sets a different
      # default.
      - CIX_PORT=${CIX_PORT:-21847}
      - CIX_EMBEDDING_MODEL=${CIX_EMBEDDING_MODEL:-awhiteside/CodeRankEmbed-Q8_0-GGUF}
      - CIX_CHROMA_PERSIST_DIR=/data/chroma
      - CIX_SQLITE_PATH=/data/sqlite/projects.db
      - CIX_MAX_FILE_SIZE=${CIX_MAX_FILE_SIZE:-524288}
      - CIX_EXCLUDED_DIRS=${CIX_EXCLUDED_DIRS:-node_modules,.git,.venv,__pycache__,dist,build,.next,.cache,.DS_Store}
      # GGUF cache lives on the named volume below — survives `docker compose
      # down` (without -v) and is owned by the image's 65532:65532 (nonroot)
      # user on the CPU image, so the cix-server process can always write to
      # it regardless of host bind-mount permissions.
      - CIX_GGUF_CACHE_DIR=/data/models
      - CIX_LLAMA_BIN_DIR=/app
      - CIX_LLAMA_STARTUP_TIMEOUT=120
      - CIX_EMBEDDINGS_ENABLED=${CIX_EMBEDDINGS_ENABLED:-true}
      # ── First-boot admin seed (required when the DB has no users yet) ──
      # cix-server refuses to start when the users table is empty AND these
      # are unset. Set BOTH in your .env, log in once, change the password
      # immediately (the user is flagged must_change_password=true).
      - CIX_BOOTSTRAP_ADMIN_EMAIL=${CIX_BOOTSTRAP_ADMIN_EMAIL:-}
      - CIX_BOOTSTRAP_ADMIN_PASSWORD=${CIX_BOOTSTRAP_ADMIN_PASSWORD:-}
      # ── PR-E runtime tunables (all DB-overridable from /dashboard/server) ──
      # 0 = auto. Threads → runtime.NumCPU()/2; batch → match n_ctx.
      - CIX_LLAMA_THREADS=${CIX_LLAMA_THREADS:-0}
      - CIX_LLAMA_BATCH=${CIX_LLAMA_BATCH:-0}
      # Embedding queue parallelism. Default 5 (was 1) — pipelines host-side
      # prep with device inference. Drop to 1 if you observe contention.
      - CIX_MAX_EMBEDDING_CONCURRENCY=${CIX_MAX_EMBEDDING_CONCURRENCY:-5}
      - CIX_EMBEDDING_QUEUE_TIMEOUT=${CIX_EMBEDDING_QUEUE_TIMEOUT:-300}
      # Optional: skip the first-boot HF download by pointing at a GGUF
      # file the operator already has on disk. cix copies it into the
      # cix-models named volume once (atomic .partial → rename) and never
      # touches the source again. Subsequent boots find the file in cache
      # and ignore the env. See volumes block below for an example bind.
      - CIX_BOOTSTRAP_GGUF_PATH=${CIX_BOOTSTRAP_GGUF_PATH:-}
      # ── Pluggable embedding providers (added in migration 12) ──
      # The active provider is selected from the dashboard
      # (/dashboard/server → Embedding provider). On first boot with an
      # empty runtime_settings row, cix-server seeds the ollama provider
      # using the CIX_EMBEDDING_MODEL + CIX_LLAMA_* vars above — so the
      # default deployment is unchanged.
      #
      # To use a remote provider (OpenAI-compatible or Voyage AI) you
      # MUST export the API-key env var below. The dashboard reads it on
      # every embed call; cix-server NEVER persists API keys in the DB,
      # only the env-var NAME a provider should look up. Switching
      # providers triggers a full reindex per project on the next clone
      # job (existing model-change pipeline).
      #
      # OpenAI-compatible (api.openai.com, vLLM, TEI, LocalAI, …):
      # - CIX_OPENAI_API_KEY=${CIX_OPENAI_API_KEY:-}
      #
      # Voyage AI:
      # - CIX_VOYAGE_API_KEY=${CIX_VOYAGE_API_KEY:-}
    volumes:
      # Operator-managed bind for sqlite + chroma so backups and inspection
      # are one `cd` away on the host. The CPU image runs as
      # nonroot:nonroot (uid 65532) — chown your bind directory to
      # 65532:65532 OR add `user: "0:0"` to fall back to root. See
      # doc/SECURITY_DEPLOYMENT.md.
      - ${HOME}/.cix/data:/data
      # Docker-managed named volume layered ON TOP of /data/models. This
      # isolates the GGUF cache from host-side bind permission issues and
      # guarantees the model is downloaded exactly once across container
      # recreates (`docker compose up --force-recreate`, image bumps, etc.).
      - cix-models:/data/models
      # Optional bootstrap: bind a host-side .gguf read-only into
      # /bootstrap/model.gguf and set CIX_BOOTSTRAP_GGUF_PATH=/bootstrap/model.gguf
      # in your .env. cix imports it into the cix-models cache on first boot,
      # then ignores both the env and the bind. After verifying the cache is
      # seeded, the bind can be removed entirely.
      # - /Users/me/.cache/huggingface/hub/.../coderankembed-q8_0.gguf:/bootstrap/model.gguf:ro
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: "${CPUS:-2.0}"
        reservations:
          memory: 1G
    healthcheck:
      test: ["CMD", "/cix-server", "-healthcheck"]
      interval: 30s
      timeout: 10s
      start_period: 120s
      retries: 3

volumes:
  cix-models:
    # GGUF model cache. Persisted by Docker; only `docker compose down -v`
    # (or explicit `docker volume rm cix_cix-models`) wipes it.