Infrastructure guide

For whoever runs Magnum BI: from a try on your computer to a server your company relies on. Then hand over to the platform owner.

Try it on your computer

All you need is Docker (or Podman) with Compose, and git. In a minute you have Magnum BI with its own database:

git clone https://github.com/giobinda/magnumbi.git && cd magnumbi
MAGNUM_ADMIN_EMAIL=you@example.com docker compose up -d   # http://localhost:8000
docker compose logs magnum | grep one-time                # your first password
docker compose exec magnum magnum-bi seed-sample          # sample data (Sales overview)
docker compose exec magnum magnum-bi demo --months 1      # optional: the NYC demo

Sign in with the one-time password; you choose your own right away. The Get started list on the home page then takes you through the rest. Stop with docker compose down; your data stays in Docker volumes (docker compose down -v deletes it).

How it runs

• One server (the ghcr.io/giobinda/magnum-bi image, about 150 MB) serves the app and its API on one address. It keeps no state of its own, so you can run several.
• A primary ScramDB (MAGNUM_DATABASE_URL) holds sign-in, settings, organisations and usage. ScramDB speaks the PostgreSQL protocol.
• One ScramDB per organisation holds that organisation's dashboards, connections, models and cache. The platform owner points each organisation at its own.
• A data folder (/data in the image, MAGNUM_DUCKDB_DIR) holds files read with DuckDB, one folder per organisation.
• Going out: besides organisations' databases, the server reaches the mail servers (ports 587, 465 or 25) and webhooks (https) that the platform workspace and each organisation set up for themselves. Allow that in your firewall if reports should leave. Set MAGNUM_PUBLIC_URL: links in scheduled reports point there. Each server checks for due reports every minute; with several, each report is still sent once.

The server applies database migrations itself when it starts, and waits up to a minute for its database, so the start order doesn't matter.

The secret key

The secret key encrypts each organisation's database address and its connection secrets (passwords, service-account keys). Without it, organisations' databases and connections can't be used, and if you lose it they must all be entered again.

• Compose and Helm make one for you on the first start: Compose in the magnum-secrets volume (MAGNUM_SECRET_KEY_FILE=/secrets/key), Helm in a Kubernetes Secret that's kept on upgrade.
• Or set your own: magnum-bi gen-key prints one; put it in MAGNUM_SECRET_KEY, or in a file named by MAGNUM_SECRET_KEY_FILE.
• Back it up somewhere safe, apart from the database backups. Every replica needs the same key.

docker compose exec magnum cat /secrets/key                                   # Compose
kubectl get secret bi-magnum-bi -o jsonpath='{.data.secret-key}' | base64 -d     # Helm

Https and the public address

On your own computer, http://localhost:8000 is fine. For anyone else, put Magnum BI behind https and tell it its public address: sign-in cookies, passkeys, single sign-on callbacks and origin checks depend on it.

bi.example.com {
  reverse_proxy localhost:8000
}

MAGNUM_PUBLIC_URL=https://bi.example.com
MAGNUM_ENV=production
MAGNUM_CLIENT_IP_HEADER=x-forwarded-for     # behind a proxy: the client's address for sign-in limits

With MAGNUM_ENV=production the server refuses to start without an https MAGNUM_PUBLIC_URL, a secret key and a sign-in method, and organisations' connections can't reach private networks (list exceptions in MAGNUM_CONNECTION_ALLOWED_HOSTS). The startup log says what's missing.

Kubernetes (Helm)

# try it: a ScramDB inside the release, no ingress
helm install bi oci://ghcr.io/giobinda/charts/magnum-bi --set production=false
kubectl port-forward svc/bi-magnum-bi 8000:80
# for real: https, an ingress, your own ScramDB (a Secret with the key database-url)
helm install bi oci://ghcr.io/giobinda/charts/magnum-bi \
  --set publicUrl=https://bi.example.com --set ingress.enabled=true \
  --set admin.email=you@example.com --set database.existingSecret=bi-scramdb
helm test bi

• The first password is in the pod's log: kubectl logs deploy/bi-magnum-bi | grep "first start".
• The bundled ScramDB has no password, so a NetworkPolicy lets only Magnum BI reach it (your cluster must enforce NetworkPolicies). For production, run your own ScramDB.
• The chart refuses settings that can't work, such as production without an https publicUrl, or several replicas on a volume only one pod can mount. Any MAGNUM_* setting goes in env or secretEnv (see the chart's values.yaml).

Settings worth knowing

Every setting is in the documentation.

Backups and upgrades

Back up the secret key, the primary ScramDB, each organisation's ScramDB, and the data folder (/data). With Compose those are the magnum-secrets, scramdb and magnum-data volumes.

docker compose pull && docker compose up -d          # Compose: the newest image
helm upgrade bi oci://ghcr.io/giobinda/charts/magnum-bi --version 0.1.11 --reuse-values

Migrations run when the new version starts. Read the release's changes first: while Magnum BI is an alpha, there's no guaranteed upgrade path.

When something's wrong

• Is it up? curl http://localhost:8000/api/health answers {"ok":true}.
• Read the log (docker compose logs magnum, kubectl logs deploy/bi-magnum-bi): it says what's missing at start, and a failed query's reference (ref …) shown in the app is in it.
• "organisation databases can't be used": the secret key isn't set (above).
• "refuses to start" with MAGNUM_ENV=production: an https MAGNUM_PUBLIC_URL, a secret key or a sign-in method is missing.
• Locked out? magnum-bi user set-password you@example.com on the server sets a password.

Developing Magnum BI

For changes to Magnum BI itself: Rust 1.94+, Node 20+, Podman or Docker, and the OpenSSL development library.

git clone https://github.com/giobinda/magnumbi.git && cd magnumbi
make install && make db-up && make seed
echo 'MAGNUM_SYSTEM_OWNERS=you@example.com' > .env.local && make key
make user EMAIL=you@example.com
make dev-backend      # API on :8000; in another terminal:
make dev-frontend     # UI on :5173
make test-db          # every test (ScramDB, DuckDB extensions)

The repository's AGENTS.md has the house rules and every command, for you and for coding agents.