Deploying a change, adding a pull source, provisioning an API key, or working the navi traffic-tile cutover/rollback for [[conduit]]. See [[conduit]] for architecture and current state.
`scripts/provision.sh` (repo root) is the canonical from-scratch installer — it stands up one Conduit instance from nothing: Postgres role + database (plain Postgres, no timescaledb/postgis), generated secrets (AES-256 master key + session secret), a uv-managed venv with an editable install, schema migrations, an optional GUI operator, and (optionally) a systemd unit. It takes every name/path/port as an env var or flag — no Matt-specific values are hardcoded, so it's the same script for the live deploy and for a disposable test instance.
Example (adjust for a real deploy — this example matches the throwaway shape used to prove the script works):
For a real systemd-managed deploy, set `SYSTEMD=on` plus `SERVICE_NAME`/`SERVICE_USER`/`SERVICE_GROUP`/`BIND_HOST`/`BIND_PORT` to taste; the script renders, installs, enables, and starts the unit. Run `scripts/provision.sh --help` for the full parameter list.
**Migrations are schema-only.** As of the `feat/provisioning` schema-only-migrations change, `003_sources.sql` creates the `sources` table but seeds no rows — a fresh install's `sources` table is empty after `conduit-migrate`. Sources (and the API keys they reference) are provisioned **after** the schema exists, via the GUI or `conduit-admin`/SQL — see "Add a pull source" and "Provision an API key" below. (The live `conduit` DB's `tomtom_flow_tiles` row predates this change and is untouched — 003 already applied there and won't re-run.)
Sources are rows in the `sources` table — there is **no hot-reload**, `app.py` loads enabled sources once at startup. Any INSERT/UPDATE/DELETE requires a `systemctl restart conduit` to take effect.
`url_template` contract: a Python `str.format()` template filled with two named substitutions —
-`{path}` — the upstream path only (no query string), taken from the inbound request after the source name and before the first `?`.
-`{key}` — the decrypted API key for `api_key_alias`, if set.
If the inbound request itself carries a query string, it's appended to the templated URL (`&` if the template already has its own `?`, else `?`) rather than substituted in — so caller-supplied params compose instead of colliding into a double `?`. If `header_auth` is true, the key is injected as a header instead of into the URL.
**Worked example — `tomtom_flow_tiles`:**
```bash
sudo -u conduit bash -c 'cd /opt/conduit && set -a && . /etc/conduit/conduit.env && set +a && psql "$CONDUIT_DB_DSN" -c "
INSERT INTO sources (name, url_template, api_key_alias, ttl_seconds, header_auth)
API keys live in Conduit's own AES-256-GCM encrypted keystore (`api_keys` table), addressed by the `alias` a source's `api_key_alias` references — separate from central's keystore, encrypted under Conduit's own master key (`/etc/conduit/master.key`).
The pattern used for `tomtom`: the plaintext key was decrypted from central's `config.api_keys` and re-encrypted under Conduit's master key, in-process, never logged in plaintext. Use the same approach for any key that already lives in central; for a brand-new key, insert it directly through the keystore's encrypt path (no plaintext in shell history or logs).
---
## navi traffic-tile cutover (2026-07-14)
navi's `/api/traffic/` tiles were repointed from [[central]] to [[conduit]]. Exact change:
**On CT 104 — widen Conduit's bind:**
`conduit.service`'s `ExecStart` uvicorn flag was changed from loopback to mesh-reachable — `--host 127.0.0.1` → `--host 0.0.0.0` (the `--port 8010` is unchanged). Unit backed up first (see Rollback below), then:
```bash
# edit the ExecStart --host token in /etc/systemd/system/conduit.service:
# --host 127.0.0.1 → --host 0.0.0.0
sudo systemctl daemon-reload
sudo systemctl restart conduit
```
**On recon-vm — rewrite the nginx proxy:**
`/etc/nginx/sites-available/navi.echo6.co`, `location ^~ /api/traffic/` block changed to:
[[central]] must stay running — it's the rollback target.
---
## Gotchas
- **Single-worker only.** Single-flight coalescing is per-process; adding uvicorn `--workers` breaks the "one upstream call" guarantee. Do not add workers.
- **`/up` rejects HEAD** (405) — GET only.
- **`/up` is unauthenticated**, like central's auth-exempt tile endpoints. Fine for tiles; revisit before adding sensitive sources.
