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.
Start, stop, and inspect¶
Run Compose commands from the repository root:
Open http://localhost:4567. The container health check queries /health. To
publish a different host port:
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¶
- Stop the service:
docker compose stop numi-chat. - Copy
chats.db,state/,.env, and any external credential files to a safe backup location outside the repository. - Pull the target revision.
- Rebuild and start the service with
docker compose up --build -d, then checkdocker 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:
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.