Deployment

A self-contained Navi module for a server: dockerized PostgreSQL + the Navi API server under systemd + navi-code in PATH. One command, SSH-only access, web UI off by default.

Deploy

Two commands from zero to a working module:

ssh server
git clone -b deploy <repo-url> navi-1 && cd navi-1
bash deploy/install.sh

What install.sh does (idempotent — safe to re-run, e.g. after git pull):

1. Checks prerequisites: Docker, and a Python ≥ 3.11. If the system has none (Ubuntu 18.04 ships 3.6, 22.04 ships 3.10 — and the system python must never be replaced), the script fetches a standalone CPython build into .python/ inside the repo — self-contained, needs only glibc ≥ 2.17, so it runs on any distro, old or new. The downloaded tarball is kept next to the repo root and reused on re-runs; for an offline server, drop the tarball next to install.sh beforehand and it will be picked up instead of downloading. Same for the docker compose plugin: if the host doesn't have docker compose (18.04's docker packages predate it), the script installs the compose v2 binary itself into /usr/local/lib/docker/cli-plugins/.
2. Provisions .env — on the deploy branch it already ships with the deployment defaults (web UI off, auth off, Ollama Cloud, profile navi_code); the script generates the DB password in place of the CHANGEME placeholder.
3. Starts dockerized PostgreSQL (pgvector image, restart: always, bound to 127.0.0.1:5432, data in the navi-pgdata docker volume) and installs the vector + pg_trgm extensions Navi's DDL expects.
4. Builds .venv and installs navi — the navi-server and navi-code entry points.
5. Writes and enables the systemd unit navi.service (Restart=always): the server lives from installation — starts on boot, restarts on crash.
6. Waits for /health to answer, then symlinks navi-code and navi-server into /usr/local/bin.

After the install finishes, fill in the one remaining secret and restart:

$EDITOR .env            # OLLAMA_API_KEY=<your Ollama Cloud key>
sudo systemctl restart navi
navi-code               # terminal client, ready to work

What the default deployed state looks like

Branch layout

• master — the full project, unconfigured, with all deployment machinery (deploy/, the NAVI_WEBCLIENT_ENABLED / NAVI_HOST / NAVI_PORT flags, the navi-server launcher).
• deploy — identical to master except for a committed .env with the deployment defaults filled in. Deploying = git clone -b deploy.

Re-enabling the web panel later

Nothing is removed — the webclient and its code are all in the tree:

# in .env:
NAVI_WEBCLIENT_ENABLED=true
NAVI_UI_MCP_ENABLED=true
sudo systemctl restart navi

For remote browser access, tunnel or reverse-proxy to the API port; auth is off by default, so keep it behind SSH or enable NAVI_AUTH_ENABLED first.

Day-2 operations

systemctl status navi          # server supervision
journalctl -u navi -f          # live logs
sudo docker compose -f deploy/docker-compose.yml --env-file .env ps
sudo docker exec -it navi-postgres psql -U navi -d navi

Updating: git pull && sudo systemctl restart navi (the install script is idempotent — re-running it after a pull also refreshes the venv).

Full runbook for an update, with preflight, verification commands, rollback and the traps (frontend dist is committed and must be rebuilt before pushing, the tracked .env on deploy, secrets inside mcp_servers.d/): see UPDATE.md.

Files

• install.sh — everything above, in one command
• docker-compose.yml — the postgres container
• env.template — copied to .env on first install; the deploy branch carries a filled-in copy as its only diff from master