In air-gapped or disconnected environments, Spinifex can be deployed without internet access. This guide covers preparing offline packages on a connected machine, creating USB deployment media, and installing on the target server with package verification.

Instructions

Step 1. Download the Release (on a connected machine)

Each Spinifex release publishes a self-contained tarball, the matching setup.sh, and a SHA-256 checksum to GitHub Releases. Resolve the latest tag and download the assets for your architecture:

ARCH=amd64   # or arm64
TAG=$(curl -fsSL https://api.github.com/repos/mulgadc/spinifex/releases/latest \
  | grep '"tag_name"' | cut -d'"' -f4)

BASE="https://github.com/mulgadc/spinifex/releases/download/${TAG}"
curl -fsSLO "${BASE}/spinifex-${TAG}-linux-${ARCH}.tar.gz"
curl -fsSLO "${BASE}/spinifex-${TAG}-linux-${ARCH}.tar.gz.sha256"
curl -fsSLO "${BASE}/setup.sh"

sha256sum -c "spinifex-${TAG}-linux-${ARCH}.tar.gz.sha256"

Step 2. Stage Dependencies (on the connected machine)

Pre-download the APT packages installed by the production setup. apt install --download-only writes .deb files to /var/cache/apt/archives/ without installing them, so the connected machine isn't modified:

sudo apt update
sudo apt install --download-only -y \
  nbdkit nbdkit-plugin-dev pkg-config \
  qemu-system-x86 qemu-utils \
  ovmf qemu-efi-aarch64 \
  libvirt-daemon-system libvirt-clients libvirt-dev \
  ovn-central ovn-host openvswitch-switch \
  dhcpcd-base make gcc jq curl iproute2 netcat-openbsd \
  wget unzip xz-utils file

Download AWS CLI v2:

curl -fsSL "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" \
  -o awscliv2.zip

Mirror the cloud image you intend to run as guest VMs, together with the sums file it was published with. Keep the upstream filename, because the import looks the image up in the sums file by name:

mkdir -p images
cd images
curl -fsSLO "https://cloud.debian.org/images/cloud/trixie/latest/debian-13-genericcloud-amd64.qcow2"
curl -fsSLO "https://cloud.debian.org/images/cloud/trixie/latest/SHA512SUMS"
sha512sum -c --ignore-missing SHA512SUMS
cd ..

The sums file only proves the image matches it; a sums file fetched over the same channel as the image can be tampered with alongside it. Where the vendor publishes a signature for the sums file (for example Ubuntu's SHA256SUMS.gpg), download it too and check it with gpg --verify against the vendor's signing key on this connected machine.

Step 3. Assemble Transfer Media

mkdir -p /media/spinifex-deploy/{tarball,apt-packages,aws,images}
cp spinifex-${TAG}-linux-${ARCH}.tar.gz /media/spinifex-deploy/tarball/
cp setup.sh /media/spinifex-deploy/
cp /var/cache/apt/archives/*.deb /media/spinifex-deploy/apt-packages/
cp awscliv2.zip /media/spinifex-deploy/aws/
cp images/*.qcow2 images/SHA512SUMS /media/spinifex-deploy/images/

Step 4. Install on the Air-Gapped Target

Mount the media, install APT dependencies, install AWS CLI, then run setup.sh with the local tarball:

sudo mount /dev/sdb1 /mnt/usb

sudo dpkg -i /mnt/usb/apt-packages/*.deb
sudo apt-get install -f --no-download   # resolve any leftover deps from local cache

cd /tmp && unzip /mnt/usb/aws/awscliv2.zip && sudo ./aws/install

INSTALL_SPINIFEX_TARBALL=/mnt/usb/tarball/spinifex-*-linux-*.tar.gz \
INSTALL_SPINIFEX_SKIP_APT=1 \
INSTALL_SPINIFEX_SKIP_AWS=1 \
bash /mnt/usb/setup.sh

Run setup.sh without sudo — the script handles privilege escalation internally and ends by exec-ing into a newgrp spinifex subshell so your current shell picks up spinifex group membership. Without that membership, AWS CLI cannot traverse /etc/spinifex/ (mode 0750) to read ca.pem and Step 9 will fail with a TLS error. Type exit to leave the subshell when finished.

Step 5. Setup OVN Networking

spx admin init requires OVN/OVS to be configured before the daemon can manage tenant networks. setup-ovn.sh ships in the tarball and runs purely against local commands (no network access required):

sudo /usr/local/share/spinifex/setup-ovn.sh --management

If your WAN interface is a physical NIC rather than a bridge, pass --wan-bridge=br-wan --wan-iface=<nic>.

Step 6. Initialize Without Telemetry

sudo spx admin init --node node1 --nodes 1 --no-telemetry

This generates the cluster configuration, TLS certificates, installs the CA into the system trust store, and writes AWS CLI credentials. See Single-Node Install for what spx admin init does.

Step 7. Start Services

setup.sh enables spinifex.target but does not start it on a fresh install. Start it now so predastore is online before you import images:

sudo systemctl start spinifex.target

Step 8. Import Cloud Images

sudo spx admin images import --file /mnt/usb/images/debian-13-genericcloud-amd64.qcow2 \
  --checksum /mnt/usb/images/SHA512SUMS \
  --distro debian --version 13 --arch x86_64 --boot-mode uefi

A digest mismatch exits before anything is written to storage. On success the import prints the verified digest, which spx admin images describe --image-id <ami> shows again later.

Step 9. Verify

export AWS_PROFILE=spinifex
aws ec2 describe-instance-types
aws ec2 describe-images

If both calls return data, your air-gapped install is working. Continue to Setting Up Your Cluster to launch your first instance.

Troubleshooting

Missing APT Dependencies

dpkg -i does not resolve transitive dependencies. After installing, run:

sudo apt-get install -f --no-download

The --no-download flag forces apt to use only what's in the local cache. If a dependency is genuinely missing, add it to the apt --download-only step on the connected machine and re-stage.

Setup.sh Tries to Download Anyway

Confirm both skip flags are exported and that INSTALL_SPINIFEX_TARBALL points at a readable file:

sudo INSTALL_SPINIFEX_TARBALL=/mnt/usb/tarball/spinifex-...tar.gz \
     INSTALL_SPINIFEX_SKIP_APT=1 \
     INSTALL_SPINIFEX_SKIP_AWS=1 \
     bash -x /mnt/usb/setup.sh

Init Telemetry Attempted

spx admin init posts a one-shot record to https://install.mulgadc.com/install. Pass --no-telemetry on every init and join invocation, or export SPX_NO_TELEMETRY=1 in the operator's shell profile.

Image Import Fails

spx admin images import --file requires the distro/version/arch/boot-mode flags so the image registers in the catalogue. A checksum entry for image filename not found error means the image was renamed after download; restore the upstream filename so it matches its line in the sums file. If the import succeeds but aws ec2 describe-images returns empty, check journalctl -u spinifex-daemon -f for predastore upload errors.

README.md

Air-Gapped Installation

Table of Contents

Overview