name: fermihdi-hd-sandbox description: Install and run the self-contained FermiHDI HD sandbox on a single host — a full end-to-end HD instance (DMS, SCC, storage nodes, proxy, query apps and synthetic flow generation) plus an optional benchmark suite, by downloading the published sandbox from downloads.fermihdi.io and pulling every image from cr.fermihdi.io. Customer-facing; one host, no source checkout, no external PKI. Covers host prep (hugepages, NVMe/VFIO), starting the lab, running the benchmark, and the must-relaunch-between-runs rule.

Run the FermiHDI HD sandbox

The sandbox is a complete HD deployment on one host for evaluation, demos and benchmarking. It ships its own CA/ICA and self-mints a licence, so it needs no external PKI and no source checkout. Everything is published:

Sandbox archive → https://downloads.fermihdi.io/hd/sandbox-latest.tar.gz (pinned: https://downloads.fermihdi.io/hd/<version>/fermihdi-hd-sandbox-<version>.tar.gz).
Container images → cr.fermihdi.io/hd/<service>:<tag> (base 2.0.4 = AVX-512 rock; 2.0.4-avx2 = AVX-2 rock; -ub2604 = Ubuntu variants). The launcher resolves the right variant for the host automatically.

For a production, multi-host deployment use fermihdi-hd-install instead; this skill is the single-host lab.

0. Requirements

A single Linux host (Debian, RHEL/Oracle/Rocky/Alma/Fedora, or Arch), Docker with the Compose plugin, and access to cr.fermihdi.io. For real storage nodes with ingestion, at least one NVMe device that can be handed to the engine via VFIO. ~32 GB RAM comfortably runs a 3-node lab.

1. Download and unpack

curl -fsSL https://downloads.fermihdi.io/hd/sandbox-latest.tar.gz -o fermihdi-hd-sandbox.tar.gz
tar -xzf fermihdi-hd-sandbox.tar.gz
cd fermihdi_sandbox

The archive extracts into a single fermihdi_sandbox/ directory containing start_sandbox.sh, run_benchmark.sh, pull_sandbox_images.sh, sandbox_host_setup.sh, configure_sandbox.py, the compose files, and the testing certs + licence the lab uses. Nothing is fetched from a developer workspace.

2. One-time host prep

sudo bash sandbox_host_setup.sh

This reserves and mounts hugepages (1 GB pool for SPDK NVMe DMA + 2 MB pool for DPDK/Seastar), raises fs.aio-max-nr, and prepares NVMe/VFIO. A 1 GB hugepage reservation needs a reboot to take effect — the script says so if one is required; reboot, then re-run it to verify. Mounting only one hugepage pool is the top cause of "device full / 0 rows", so let this script own it rather than doing it by hand.

3. (Optional) pre-pull images

bash pull_sandbox_images.sh --tag 2.0.4

Stages every image (HD services, the lab-support tier — flow routers, collector, Kafka, Redis, Locust, enrichment, demo web app — and the pinned third-party images) from cr.fermihdi.io/hd so start_sandbox.sh doesn't pause on first-run pulls. --type (auto/rock/ubuntu/avx2/arm64) forces a variant; auto (default) matches the host.

4. Start the lab

bash start_sandbox.sh --num-sns 1

Brings up the whole instance: DMS-CA/Core/OPA/WebUX, SCC, the storage node(s), the proxy (with its mock forward-auth), the query apps (GraphQL, Data Explore, MCP, SQL), Grafana, and synthetic flow generation feeding IPFIX through the ingester. Useful flags: --num-sns N (1–3), --registry <path> (defaults to cr.fermihdi.io/hd), --tag/-t, --type/-y, --numa-node.

Use --num-sns 1 (or 2/3) for a lab that actually ingests. Do not use --standalone to get ingestion: it sets FERMIHDI_SN_MODE=standalone, the SN never reports FullyReady, the DMS never pushes sn_targets, and ingest hangs forever while every component looks healthy.
Relaunch the whole lab between runs. Restarting the proxy alone (even stop+start) loses its DMS registration permanently and every service behind it then returns 502 — which looks exactly like a broken build. Recovery is a full relaunch, so just relaunch.
Bring statically-addressed services up before dynamic ones; a recreated service can otherwise steal another's static IP.

5. Run the benchmark (optional)

bash run_benchmark.sh --num-sns 3

Runs the 3-phase suite (YCSB 150 B, TSBS 512 B, HD-Pipeline 128 B) end to end and writes a JSON report under tests/test_logs/. configure_sandbox.py --benchmark-mode --num-sns N --numa-node 0 (with FERMIHDI_SN_DRIVES_PER_SN=2 for overflow) sets the node/drive layout first if you want to change it.

6. Verify and troubleshoot

The lab is healthy when every SN is FullyReady, the SCC data plane is bound, the WebUX and query apps answer through the proxy, and an ingest+query cycle returns rows with integrity OK. For 0-rows/hang, slow ingest, SN-won't-start, or rock/pebble startup problems, use fermihdi-hd-troubleshoot — most sandbox issues are host prep (hugepages/VFIO) or the relaunch rule above, not the engine.

downloads.fermihdi.io — SKILL.md