Skip to content
mulga

Single-Node Install

Install Spinifex on one Debian, Ubuntu or Oracle Linux server with the binary installer and run an AWS-compatible EC2, S3 and VPC stack on your hardware.

installsingle nodequickstart
OverviewPrerequisitesInstructionsTroubleshooting

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
  • Oracle Linux 10.2 or a later 10.x, on UEK R8, x86_64 only, as a single node or, with Multi-Node Install, a cluster. Open vSwitch and OVN come from the CentOS NFV SIG, a community repository that Oracle does not support. Prepare the host with Oracle Linux Hosts first.

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-wan will land in a future release.

Verify before continuing:

  • ip -br link show br-wan — bridge exists and is UP
  • ip route — default route's dev is br-wan

Setup references: VPC Networking → Bridge Setup for the topology.

Instructions

Step 1. Install Spinifex

bash
curl -fsSL https://install.mulgadc.com | bash

The installer downloads the Spinifex binary and bootstraps all dependencies (QEMU, OVN/OVS, AWS CLI).

This installs the latest release. To try the newest development build instead, set the channel — it carries unreleased work and has not been through release testing, so use it to evaluate a fix or a new feature rather than for anything you depend on.

bash
curl -fsSL https://install.mulgadc.com -o /tmp/spx-install.sh
sudo INSTALL_SPINIFEX_CHANNEL=dev bash /tmp/spx-install.sh

Step 2. Setup OVN Networking

If your WAN interface is already a bridge (e.g. br-wan), setup-ovn.sh auto-detects it:

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

If your WAN is a physical NIC:

bash
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:

bash
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

bash
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

bash
sudo systemctl start spinifex.target

Step 5. Verify

bash
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.

Step 6. Set Up Your Cluster

Spinifex is running, but it holds nothing yet — no machine images, no networks, no instances.

Continue to Setting Up Your Cluster to import an AMI, create an SSH key pair, create a VPC with a public subnet, and launch your first instance.

Troubleshooting

spx Command Not Found

The installer puts spx in /usr/local/bin. Where sudo's secure_path leaves that directory out, as on Oracle Linux, the installer also links /usr/bin/spx to it, so sudo spx works; changing PATH in your shell does not reach commands run with sudo. Check both:

bash
ls -l /usr/local/bin/spx /usr/bin/spx
sudo sh -c 'command -v spx'

If sudo still finds no spx, run the installer again, or call sudo /usr/local/bin/spx meanwhile.

CA Certificate Not Trusted

sudo spx admin init installs the CA automatically. If you need to re-install it manually on Debian or Ubuntu:

bash
sudo cp /etc/spinifex/ca.pem /usr/local/share/ca-certificates/spinifex-ca.crt
sudo update-ca-certificates

On Oracle Linux:

bash
sudo cp /etc/spinifex/ca.pem /etc/pki/ca-trust/source/anchors/spinifex-ca.crt
sudo update-ca-trust

OVN Services Not Starting

bash
sudo systemctl is-active ovn-controller
journalctl -u ovn-controller --no-pager -n 20