Ben Duncan
704874c0c7
All 3 install guides (binary, multi-node, source) now end at the same verification point: aws ec2 describe-instance-types. Installation is complete when that command returns instance types. New docs/setting-up-your-cluster/README.md is the common guide all 3 install paths point to. Covers: AMI import, SSH key creation, VPC with public subnet (IGW + modify-subnet-attribute), instance launch with public IP, SSH via public IP, instance lifecycle management. Removed SSH-via-hostfwd from all guides — public subnet is the default connectivity path. Private subnet documented as an alternative.
title, description, category, tags, badge, resources
| title | description | category | tags | badge | resources | ||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Installing Spinifex | Install Spinifex on a single server using the binary installer. | Getting Started |
|
quickstart |
|
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 — EC2, VPC, EBS, and S3 — 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 Installation. To build from source, see Source Install.
Supported Operating Systems:
- Ubuntu 22.04 / 24.04 / 25.10
- Debian 12 / 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
Instructions
Step 1. Install Spinifex
curl https://install.mulgadc.com | bash
The installer downloads the Spinifex binary and bootstraps all dependencies (QEMU, OVN/OVS, AWS CLI).
Step 2. Initialize
spx admin init --region ap-southeast-2 --az ap-southeast-2a --node node1 --nodes 1
This auto-detects your network topology and configures external networking. Save the admin credentials printed during init — they will not be shown again.
Step 3. Trust the CA certificate
sudo cp ~/spinifex/config/ca.pem /usr/local/share/ca-certificates/spinifex-ca.crt
sudo update-ca-certificates
Step 4. Setup OVN networking
sudo /usr/local/share/spinifex/setup-ovn.sh --management --external-bridge --external-iface=enp0s3 --dhcp
Replace enp0s3 with your WAN interface. Single-NIC hosts should add --single-nic.
Step 5. Start services
sudo systemctl start spinifex.target
export AWS_PROFILE=spinifex
Step 6. Verify
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 cp ~/spinifex/config/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