gsadmin/spinifex
1
0
Fork 0
mirror of https://github.com/mulgadc/spinifex.git synced 2026-10-15 09:01:31 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
562e19aeca5cad551d5b830e44dbbdeb6779e577
spinifex/docs/install/install
T
History
Ben Duncan 70007405c1 fix(oci): install the dev channel by environment variable, not --channel (#1155) 
The installer served by install.mulgadc.com is the latest release's, so it
predates the --channel flag the harness was passing and would have died with an
unknown option. Document the same form in both install guides.
2026-10-02 15:55:51 -05:00
..
README.md
fix(oci): install the dev channel by environment variable, not --channel (#1155)
2026-10-02 15:55:51 -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).

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.

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:

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