Skip to content

Run with Docker

For a first-time setup, follow the Docker tab in Install Numi. This guide covers day-to-day operations, persistent paths, backups, and reverse-proxy configuration for a Docker Compose deployment.

Replace an application container while the database and file storage remain on the host.

Start, stop, and inspect

Run Compose commands from the repository root:

docker compose up -d
docker compose ps
docker compose logs -f numi-chat

Open http://localhost:4567. The container health check queries /health. To publish a different host port:

NUMI_CHAT_PORT=8080 docker compose up -d

The container still listens on port 4567 internally. Add NUMI_CHAT_PORT to .env to make the port mapping permanent.

Task Command
Stop the service docker compose stop numi-chat
Start a stopped service docker compose start numi-chat
Recreate after .env changes docker compose up -d
Rebuild after pulling new code docker compose up --build -d
Run migrations explicitly docker compose run --rm numi-chat db-migrate
Stop and remove containers docker compose down

Container startup runs database migrations automatically. See Database migrations before upgrading an existing instance.

Runtime data

docker-compose.yml mounts these host paths into the container:

Host path Contents
./chats.db SQLite database, mounted at /app/state/chats.db
./state/uploads/ Per-chat uploaded files
./state/generated_files/ Generated files, plots, and images
./state/models.json Private model catalog, if customized
./state/avatars/ User avatar images
./state/deno-cache/ Deno runtime cache for code_interpreter
./state/tool_group_router/numi_route_alpha/ Optional private-beta local routing model
./logs/ Application logs

Because chats.db has its own bind mount alongside ./state:/app/state, always back up both ./chats.db and ./state/ together (including any chats.db-wal or chats.db-shm sidecar files in state/). Keep ./state mounted as a directory rather than mounting models.json as a single file so atomic catalog saves work properly.

The container runs under HOST_UID and HOST_GID (both default to 1000). Set them in .env if your host user uses a different UID or GID.

The default docker-compose.yml also includes two read-only volume entries for REWE certificate files (private_rewe.pem and private_rewe.key). If you do not use REWE grocery offers, remove those two lines from docker-compose.yml before starting the container. See the Tools reference for REWE certificate extraction.

Numi Route Alpha (private beta)

Numi Route Alpha is an opt-in local CPU classifier for pre-turn optional tool suggestions. Its weights are privately distributed and never downloaded automatically. If you have the release bundle, copy model.onnx, config.json, and the tokenizer/ directory into ./state/tool_group_router/numi_route_alpha/ on the host and set in .env:

DECISIONS_ENABLED=true
DECISIONS_TOOL_GROUP_ROUTER=numi_route_alpha
DECISIONS_LOCAL_TOOL_GROUP_MODEL_PATH=state/tool_group_router/numi_route_alpha

When confidence is uncertain, input is truncated, or weights are missing, the router falls back to Jev if OPENROUTER_API_KEY is configured. Set DECISIONS_TOOL_GROUP_ROUTER=jev to use the remote router directly, or DECISIONS_ENABLED=false to disable pre-turn routing altogether.

Back up and update

  1. Stop the service: docker compose stop numi-chat.
  2. Copy chats.db, state/, .env, and any external credential files to a safe backup location outside the repository.
  3. Pull the target revision.
  4. Rebuild and start the service with docker compose up --build -d, then check docker compose logs -f numi-chat.

To track a branch and deploy new commits automatically, see Automatic deploys.

Reverse proxy

For an internet-facing deployment, terminate TLS at a reverse proxy, forward WebSocket upgrades, and bind the Compose port to loopback on the host:

ports:
  - "127.0.0.1:${NUMI_CHAT_PORT:-4567}:4567"

Example Nginx location block inside a TLS server configuration:

location / {
    proxy_pass http://127.0.0.1:4567;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    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;
    proxy_read_timeout 86400;
}

Set your production origin and security flags in .env:

ENVIRONMENT=production
CORS_ALLOW_ORIGINS="https://chat.example.com"
TOOLS_CODE_INTERPRETER_UNSANDBOXED=false

Set FORWARDED_ALLOW_IPS to the proxy address as seen by the container so rate limiting and login throttling read the real client IP. See Security and Privacy and data for further deployment guidance.