First-run OS bootstrap

Audience: Anyone performing a first install on a fresh Linux or Windows host.

Purpose: One idempotent entry point that detects the OS, installs missing prerequisites, and delegates to the canonical role installers — without duplicating Edge or Compose logic.

Entry points

Platform	Command
Linux (all roles)	`sudo ./scripts/install/hokeka-install.sh --role control-plane\|edge\|console`
Windows (Edge / Console)	`.\scripts\install\hokeka-install.ps1 -Role edge\|console`

Audit only (no changes):

./scripts/install/hokeka-install.sh --role edge --check
./scripts/install/hokeka-install.sh --role control-plane --check

Dry-run:

sudo ./scripts/install/hokeka-install.sh --role control-plane --dry-run

Non-interactive: pass --yes or run from CI with non-TTY stdin (auto-yes).

Roles

Role	What it does	Delegates to
control-plane	Docker + Compose v2, Node LTS, git, `.env` with strong secrets (never logged), `docker-compose.prod.yml` up, systemd unit, health check	`03-control-plane.md`, `docs/deploy/DEPLOYMENT-READINESS-RUNBOOK.md`
edge	JRE 21 (native), Docker (container), optional Rust pin + build (`--build-rust`)	`edge-host/deploy/install.sh` / `install.ps1` — see 01-client-edge-node.md
console	Node LTS, Docker, Playwright chromium, `npm ci` in `FRONTEND/`	05-local-developer-stack.md

Production Control Plane remains Linux/Docker on the Hostinger VPS. Windows -Role control-plane only validates Docker/Node and prints the Linux command.

Robustness

Feature	Environment / flag
Registry mirror (Docker Hub timeouts)	`HOKEKA_DOCKER_REGISTRY_MIRROR` or `DOCKER_REGISTRY_MIRROR`
Offline images	`HOKEKA_DOCKER_IMAGE_TARBALLS_DIR` (`.tar` / `.tar.gz` from `docker save`)
HTTP(S) proxy	Standard `HTTP_PROXY` / `HTTPS_PROXY`
Retries	Built into curl/get.docker.com/docker pull paths
Minimum RAM/disk	Enforced per role; `--check` reports shortfalls

Edge passthrough

Arguments after -- are forwarded to edge-host/deploy/install.sh:

sudo ./scripts/install/hokeka-install.sh --role edge --yes -- \
  --pspid 42 --edgeid acme-eu-1 --controlplane https://edge.hokeka.com \
  --enrollment-code ABCD-1234

Native Linux + local Rust build:

sudo HOKEKA_EDGE_BUILD_RUST=1 ./scripts/install/hokeka-install.sh --role edge --build-rust --native -- \
  --pspid 42 --edgeid acme-eu-1

What `--role control-plane` generates and installs

scripts/install/roles/control-plane.sh runs these steps in order:

.env with secrets (hokeka_write_control_plane_env in scripts/install/lib/control-plane-env.sh). It writes /opt/aml-fraud-detector/.env (or $HOKEKA_INSTALL_DIR/.env), mode 600. Each key is generated only when absent, and no value is ever printed. The keys include:
- database, Neo4j, JWT, encryption, audit HMAC, PII lookup HMAC and password-reset pepper secrets;
- SEED_ADMIN_PASSWORD, the password of the bootstrap admin user;
- Console session hardening defaults when missing (SESSION_COOKIE_SECURE=true, SESSION_TIMEOUT=15m, HOKEKA_SESSION_IDLE_TIMEOUT=15m, and the related cookie/lockout keys). docker-compose.prod.yml also defaults these into backend-prod so production does not need a server-only override.
Edge channel keys (hokeka_write_edge_channel_secrets, same file):
- EDGE_BUNDLE_SIGNING_KEY / EDGE_BUNDLE_SIGNING_PUBLIC_KEY (Ed25519; signs bundles and the Edge config);
- EDGE_METRICS_INGEST_KEY / EDGE_METRICS_INGEST_PUBLIC_KEY (X25519; Edges seal metrics and decision records to it);
- EDGE_TUNNEL_CURSOR_SECRET (HMAC of tunnel composite cursors);
- EDGE_PROXY_SHARED_SECRET (nginx → Control Plane trust of forwarded mTLS headers);
- EDGE_CA_KEY / EDGE_CA_CERT (the Hokeka Edge CA, EC P-256, 10 years; signs Edge CSRs). On the prod / production profiles the Control Plane refuses to start without the bundle and metrics keys (BACKEND/.../config/edge/EdgeControlPlaneKeys.java) and without the Edge CA (BACKEND/.../service/edge/pki/EdgeCertificateAuthority.java). Ephemeral development keys would break every enrolled Edge on the next restart. Keep these keys stable across upgrades and back up the .env file (docs/operations/KEY_MANAGEMENT.md).
Edge vhost (hokeka_install_edge_vhost). It installs BACKEND/nginx/edge-tunnel.conf as /etc/nginx/conf.d/hokeka-edge-tunnel.conf for edge.hokeka.com (override with HOKEKA_EDGE_HOST). It also writes:
- the Edge CA certificate, the proxy-secret include and an initial CRL under /etc/nginx/hokeka/;
- the hokeka-edge-crl.path systemd unit, which reloads nginx whenever the Control Plane re-writes the CRL. If there is no TLS certificate for the host yet, the vhost is staged as hokeka-edge-tunnel.conf.pending. Set HOKEKA_CERTBOT_EMAIL to let the installer run certbot itself. Edge Nodes cannot enrol until this vhost is live (03-control-plane.md Step 5b).
Stack up. It runs docker-compose.prod.yml up, installs the systemd unit and checks health. Compose refuses to start the backend without SEED_ADMIN_PASSWORD (${SEED_ADMIN_PASSWORD:?…} in docker-compose.prod.yml). On a production profile, DataSeeder also fails when it is blank.

After bootstrap

First login. Read SEED_ADMIN_PASSWORD from the .env file on the host (sudo grep '^SEED_ADMIN_PASSWORD=' /opt/aml-fraud-detector/.env; do not paste it anywhere else). Log in to the Console as admin.
Rotate the bootstrap password. Change it straight away from your profile (PUT /api/v1/users/me/password, which enforces the password policy). Then create named platform administrators and stop using the shared admin account. DataSeeder creates admin only when no such user exists, so changing SEED_ADMIN_PASSWORD later does not change an existing admin's password.
Control Plane: run the verification in DEPLOYMENT-READINESS-RUNBOOK.md §3–9, including the residency checks.
Edge vhost: if the installer staged .pending, finish the certbot step it printed. Then confirm nginx -t passes and that https://edge.hokeka.com/api/v1/edge/ca/crl answers.
Edge: complete enrolment in the Console (01-client-edge-node.md). The Edge sends a CSR at enrolment and receives its mTLS client certificate automatically.
Secrets: rotate any other bootstrap-generated values before public traffic (03-control-plane.md Step 2; KEY_MANAGEMENT.md).
Operations: day-2 tasks (PSP lifecycle, Edge node lifecycle, certificates, support access) are in docs/operations/PLATFORM_ADMIN_RUNBOOK.md.

Legacy deploy-to-hostinger.sh remains an SSH/rsync helper; prefer hokeka-install.sh --role control-plane on the VPS for dependency and .env handling.

Entry points​

Roles​

Robustness​

Edge passthrough​

What --role control-plane generates and installs​

After bootstrap​