Deploy

How to run Bigwave somewhere other than your laptop. Per ADR 0019, the default install mode is bare-metal (uv + Python on the host); Docker Compose is a fully-supported alternative for operators who prefer it.

Deployment shapes

Shape	When to pick it
Single host, bare-metal + systemd	Default. Lightest production deploy; ./install.sh --systemd writes the unit file.
Single host, Docker Compose	When you want one-stop multi-service orchestration (Postgres + Phoenix + nginx in the same docker compose up). --install-mode=docker.
Single host, Postgres backend	Either mode — set BIGWAVE_STORAGE_URL=postgresql+asyncpg://…. Bare-metal expects an externally-managed Postgres; Docker mode bundles it.
Multi-host, K8s (roadmap Helm chart)	When you need more than one GPU node or want HA.
Air-gapped on-premise	Compliance use case — see the compliance walkthrough for the network-posture verification steps. Bare-metal is preferred.

For most teams: start with bare-metal + systemd + an external Postgres. It's operationally simple, survives upgrades cleanly, and matches the production posture of regulated estates that don't allow Docker on the runtime path.

Steps for a production single-host deploy

1. Provision the host

Linux with Docker + Docker Compose v2. Storage layout:

/srv/bigwave/
  ├── data/        # datasets, vector store
  ├── logs/        # NDJSON inference logs
  ├── training/    # per-job workdirs
  └── postgres/    # database volume

Mount these as Compose volumes; back up /srv/bigwave/postgres/ nightly.

2. Run the installer with explicit flags

git clone https://github.com/bigwaveml/bigwave.git
cd bigwave
./install.sh --non-interactive \
    --profile=SME tier \
    --port=8080 \
    --model=qwen2.5:7b \
    --storage=postgres \
    --observability=phoenix \
    --auth=proxy_headers

The installer writes .env + docker-compose.yml and brings the stack up. Save the printed admin token.

3. Configure your reverse proxy

Front Bigwave with your existing oauth2-proxy / Authelia / Keycloak Gatekeeper. The proxy_headers auth adapter trusts identity headers from any peer in BIGWAVE_TRUSTED_PROXY_CIDRS:

# nginx — sketch
upstream bigwave {
    server localhost:8080;
}

server {
    listen 443 ssl;
    server_name bigwave.your-domain.com;

    auth_request /oauth2/auth;

    location / {
        proxy_pass http://bigwave;
        # Trust the oauth2-proxy's identity headers
        proxy_set_header X-Auth-Request-Email $upstream_http_x_auth_request_email;
        proxy_set_header X-Auth-Request-Groups $upstream_http_x_auth_request_groups;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

The Bigwave side:

BIGWAVE_AUTH=proxy_headers
BIGWAVE_TRUSTED_PROXY_CIDRS=127.0.0.1/32

Test by issuing a request without the proxy headers — expect 401.

4. Verify the deploy

What to check	How
Liveness	curl https://bigwave.your-domain.com/healthz
Auth	A request through the proxy succeeds; a direct request to the API port (bypassing the proxy) returns 401
Storage	docker compose exec api alembic current shows the latest migration applied to Postgres
Audit	curl …/admin/audit?limit=5 returns rows
Observability	If you wired Phoenix: traces appear in the Phoenix UI

5. Plan backup + restore

The full state lives in:

• Postgres database (audit log, eval runs, datasets, feedback, adapters, channel bindings)
• /srv/bigwave/data/ — vector store + uploaded raw datasets
• /srv/bigwave/training/ — adapter artefacts (small; can be re-trained from the database lineage)

Daily pg_dump of Postgres + a tarball of /srv/bigwave/data/ is sufficient for full recovery. The training workdir is reproducible from the lineage so it doesn't need backup.

What's not covered yet

• Helm chart — on the roadmap. For now, Compose is the supported path.
• Multi-GPU sharding — single-host deploys serve one model at a time. Multi-GPU lands with the vLLM adapter.
• HA Postgres — Bigwave doesn't ship a streaming-replication story. Use your standard Postgres HA pattern.
• Air-gapped install bundle — on the roadmap. Today's air-gap path is "mirror Ollama + Postgres images internally; run ./install.sh."

See also

• Configuration reference — every env var
• Docker Compose specifics — what the generated stack looks like
• Compliance use case — the air-gapped on-premise pattern