Josh Siviour
e84753f9b9
* docs: bring doc titles and descriptions into SEO length limits Rewrite the frontmatter title and description of every published doc so the rendered <title> lands in 50-60 characters (including the site suffix) and the meta description lands in 150-160 characters. * docs: move SEO titles to a seoTitle field and restore display titles The frontmatter title renders as the page H1 and the sidebar label, so tuning it for the title tag shortened nothing and lengthened the visible navigation. Put the search-facing string in seoTitle and give title back its original value.
title, seoTitle, description, category, tags, resources
| title | seoTitle | description | category | tags | resources | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Single-Node Install | Install Spinifex on a Single Server — Spinifex Docs | Install Spinifex on one Ubuntu or Debian server with the binary installer and get an AWS-compatible EC2, S3, and VPC stack running on your own hardware. | Install |
|
|
Installing Spinifex
Install Spinifex on a single server using the binary installer.
Table of Contents
Overview
Spinifex is an open-source infrastructure platform that brings core AWS services to bare-metal, edge, and on-prem environments.
This guide installs Spinifex on a single server using the binary installer. For multi-server clusters, see Multi-Node Install. To build from source, see Source Install.
Supported Operating Systems:
- Ubuntu 26.04
- Debian 13
What Gets Installed:
- Spinifex daemon and CLI
- QEMU/KVM for virtual machine management
- OVN/Open vSwitch for VPC networking
- Predastore (S3-compatible object storage)
- Viperblock (EBS-compatible block storage)
- AWS CLI v2
Prerequisites
Important
Prerequisite — WAN bridge required.
Before running the installer, the host's WAN interface must already be enslaved to a Linux bridge named
br-wan. The host IP, default route, and DHCP must all live on the bridge — not on the bare NIC.The bootstrap installer does not create this bridge for you yet. Running it on a host whose default route is still on a bare NIC will leave the install in a non-working state. Auto-provisioning of
br-wanwill land in a future release.Verify before continuing:
ip -br link show br-wan— bridge exists and isUPip route— default route'sdevisbr-wanSetup references: VPC Networking → Bridge Setup for the topology.
Instructions
Step 1. Install Spinifex
curl -fsSL https://install.mulgadc.com | bash
The installer downloads the Spinifex binary and bootstraps all dependencies (QEMU, OVN/OVS, AWS CLI).
Step 2. Setup OVN Networking
If your WAN interface is already a bridge (e.g. br-wan), setup-ovn.sh auto-detects it:
sudo /usr/local/share/spinifex/setup-ovn.sh --management
If your WAN is a physical NIC:
sudo /usr/local/share/spinifex/setup-ovn.sh --management --wan-bridge=br-wan --wan-iface=eth1
Separating VPC tunnel traffic from WAN: If you want Geneve tunnel traffic (inter-VM east-west for VPC traffic) to use a dedicated interface instead of the WAN IP, add --encap-ip=<IP> to specify the tunnel endpoint address:
sudo /usr/local/share/spinifex/setup-ovn.sh --management --encap-ip=10.0.0.1
This is recommended for production and required in multi-node deployments. See Multi-Node Install for details.
Step 3. Initialize
sudo spx admin init --node node1 --nodes 1
This auto-detects your network topology, generates configuration and TLS certificates, installs the CA into the system trust store, and configures AWS CLI credentials (saved in ~/.aws/credentials)
Step 4. Start Services
sudo systemctl start spinifex.target
Step 5. Verify
export AWS_PROFILE=spinifex
aws ec2 describe-instance-types
If this returns a list of available instance types, your installation is working.
Congratulations! Spinifex is installed.
Continue to Setting Up Your Cluster to import an AMI, create a VPC, and launch your first instance.
Troubleshooting
spx Command Not Found
export PATH=$PATH:/usr/local/bin
CA Certificate Not Trusted
sudo spx admin init installs the CA automatically. If you need to re-install it manually:
sudo cp /etc/spinifex/ca.pem /usr/local/share/ca-certificates/spinifex-ca.crt
sudo update-ca-certificates
OVN Services Not Starting
sudo systemctl is-active ovn-controller
journalctl -u ovn-controller --no-pager -n 20