name: fermihdi-hd-install description: Install and provision a FermiHDI HD deployment in any supported topology (Kubernetes/Helm, bare-metal Ansible, bare-Docker multi-host with host networking, or the dev sandbox), by downloading the published installer from downloads.fermihdi.io and pulling images from cr.fermihdi.io — no source-code workspace required. Includes distro-portable host prep for hugepages, VFIO and CPU isolation across Debian, RHEL and Arch.

Install a FermiHDI HD deployment

A customer host has no source checkout. Everything you need is published:

• Installer + scripts → https://downloads.fermihdi.io (versioned archive).
• Container images → cr.fermihdi.io/hd/<service>:<tag> (base 2.0.4 = AVX-512 rock; 2.0.4-avx2 = AVX-2 rock; -ub2604 variants).
• Manual → https://docs.fermihdi.io/hd.

Never assume a local repo path; download the installer and run from the unpacked bundle.

0. Get the installer (every host)

curl -fsSL https://downloads.fermihdi.io/install.sh | sh

This downloads fermihdi-hd-install-<version>.tar.gz, verifies it against its published SHA-256, unpacks it into the current directory, and runs the read-only host inventory (changes nothing, needs no root). The unpacked bundle is the working set for everything below: fermihdi-discover, fermihdi-prepare, fermihdi-configure, ansible/, helm/, fermihdi-k8s (and fermihdi-talos-*), and lib/lib_distro.sh. Pin a version with FERMIHDI_VERSION=2.0.4; mirror with FERMIHDI_BASE_URL. Any script that calls another fetches it from the same archive — nothing is pulled from a developer workspace.

1. Detect the host and its distro (every node)

. ./lib/lib_distro.sh; fhd_detect_distro sets FHD_PKG_INSTALL, FHD_GRUB_MKCONFIG, FHD_GRUB_CFG for Debian (apt), RHEL/Oracle/Rocky/Alma/Fedora (dnf/yum), and Arch (pacman). Never hardcode apt-get/update-grub — the three families differ in package names, the grub-mkconfig command, and the grub.cfg path (/boot/grub/grub.cfg vs /boot/grub2/grub.cfg). RHEL BLS uses grubby; a long isolcpus can overflow grubenv, so write kernel args into the BLS entries (grubby --update-kernel=ALL --args=...) or /etc/tuned/bootcmdline, not just grubenv.

2. Choose a topology

3. Host prep — hugepages (every SN and SCC host)

Each SN or SCC instance needs 4 × 1 GB + 512 × 2 MB hugepages, both GRUB-reserved at boot AND mounted:

• 1 GB pages can't be allocated on a running host — reserve at boot: default_hugepagesz=2M hugepagesz=1G hugepages=<4×instances> hugepagesz=2M hugepages=<512×instances>, then ${FHD_GRUB_MKCONFIG} (or grubby on RHEL/BLS) and reboot. fermihdi-prepare --apply installs this via its boot unit.
• Mount both: /dev/hugepages1G (pagesize=1G, SPDK NVMe DMA) and /dev/hugepages (pagesize=2M, DPDK/Seastar). SPDK uses the 1 GB pool; mounting only one is the top cause of "device full / 0 rows".
• Verify: fhd_verify_hugepages <instances> (in lib/lib_distro.sh) checks the GRUB reservation, the sysfs pool sizes, and both mounts. Also fermihdi-prepare --verify.

4. Host prep — VFIO (NVMe, and NIC only if using DPDK on the NIC), made persistent

Bind each data NVMe (and the NIC, only if NOT FERMIHDI_FORCE_POSIX) to vfio-pci. Runtime binding reverts on reboot — make it persistent: fhd_vfio_persist <pci-addr...> (driverctl if present, else a systemd oneshot that rebinds by PCI address at boot; portable across the three distros). fermihdi-prepare --apply can install this. Prefer per-address binding over vfio-pci.ids=vendor:device when the OS drive shares a model with the data drives; never bind the boot device.

5. Bare-Docker multi-host (host networking; the "chess.com" pattern)

Don't hand-write these commands: fermihdi-docker cluster.yaml -o docker-deploy renders one docker run script per host (nodes with --network host; the DMS on its own bridge networks) plus deploy-all.sh, which copies each to its host over SSH and runs it, DMS first. It reads secrets from the environment (never bakes them in) and refuses to emit a host whose instances collide on an exclusive port. The rest of this section is what those scripts encode.

One control host runs DMS-CA, DMS-Core, SCC and the ingester; each other host runs one SN. All node containers use --network host, so planes are coordinated by PORT, not network:

• 6985 DMS-CA · 6986 DMS-Core command · 6989 DMS-Core mgmt · 8080 observability
• SCC command (default 6986, or non-default when co-located with DMS-Core) → verify = +10, query-dispatch = +11, all control-plane · 6987 FHDWP data plane (ingest + query results)
• The SN derives verify/query ports from the learned command port (DMS discovery must propagate a non-default SCC port).

Launch order: DMS-CA → DMS-Core (seed nodes.jsonl, chown to the runtime uid, restart) → SCC → SN(s) with bootstrap tokens + CA bundle → ingester. Each SN: --privileged, --ulimit memlock=-1:-1, mount /dev/hugepages + /dev/hugepages1G, pass the VFIO group devices, FERMIHDI_FORCE_POSIX=1, MASTER_CPUSET=<isolated lCPUs>, and set FERMIHDI_JUMBO=1 on SCC and every SN if the instance uses jumbo. All images come from cr.fermihdi.io/hd. Rocks start via pebble (which passes the container env through, so FERMIHDI_JUMBO etc. reach the binary); the entrypoint can be overridden to the bare binary (/app/hd_storage_controller, /app/hd_storage_node) for launcher-driven runs.

6. Verify

fhd_verify_hugepages, VFIO bindings present and persistent, all SNs FullyReady, SCC data plane bound on 6987, and an ingest+query cycle returns rows with integrity OK. If not, use fermihdi-hd-troubleshoot.