gsadmin/spinifex
1
0
Fork 0
mirror of https://github.com/mulgadc/spinifex.git synced 2026-10-15 17:11:30 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
e9b9600bbc7ca12aaa2179ee35229a91b3c4ea17
spinifex/docs/install/install
T
History
Ben Duncan 2ba8f5e4ab docs: separate the install guides from the reference material they had absorbed 
Both install guides had grown sections that were not install steps, which is what made the multi-node one hard to follow. Each now ends on a step that hands off to Setting Up Your Cluster, and the reference material moves under Administration where it can be read on its own.

- Single-node and multi-node both end on a "Set Up Your Cluster" step rather than a trailing sentence.
- The multi-node cluster-state check via `spx admin kv digest` is gone. Verification is now every node Ready, capacity pooled, and the AWS API answering.
- "How Multi-Node Storage Works" becomes docs/admin/predastore-distributed-storage, expanded with the host and node model, the write and read paths, degraded writes, hinted handoff, repair, encryption at rest, and what each class of failure costs.
- "Firewall and Cluster Membership" becomes docs/admin/host-firewall, expanded with the full public, cluster and encap port groups, how to narrow SSH, and which files under /etc/spinifex/firewall survive an upgrade.
- Setting Up Your Cluster gains a closing step that arms the firewall and narrows SSH, so the securing work lands after a cluster that works rather than during the install.

install-usb and vpc-networking followed the two moved sections to their new paths.
2026-09-18 10:58:25 -05:00
..
README.md
docs: separate the install guides from the reference material they had absorbed
2026-09-18 10:58:25 -05:00

README.md

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
install
single node
quickstart
title url
Spinifex Repository https://github.com/mulgadc/spinifex
title url
Predastore (S3) https://github.com/mulgadc/predastore
title url
Viperblock (EBS) https://github.com/mulgadc/viperblock

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

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.

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

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
Reference in New Issue View Git Blame Copy Permalink