spinifex/docs/source-install/README.md

title, description, category, tags, badge, resources

title	description	category	tags	badge	resources
Source Install	Build Spinifex from source for development, custom builds, or contributing. Includes dependency setup, compilation, and OVN configuration.	Getting Started	install source development	source	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 title url Go Downloads https://go.dev/dl/ title url AWS CLI Install https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html

Source Install

Build Spinifex from source for development, custom builds, or contributing.

Table of Contents

• Overview
• Instructions
• Troubleshooting

---

Overview

This guide covers building Spinifex from source code. Use this if you want to contribute to Spinifex, build custom versions, or inspect the codebase. For production deployments, the binary installer is recommended.

Supported Operating Systems:

• Ubuntu 22.04 / 24.04 / 25.10
• Debian 12.13

Requirements:

• Go 1.26.1+
• GCC, make, pkg-config
• QEMU/KVM
• OVN/Open vSwitch
• AWS CLI v2

Instructions

Step 1. Install system dependencies

Quick Install

Bootstrap all dependencies in one step:

sudo make -C spinifex quickinstall

Ensure Go is in your PATH:

export PATH=$PATH:/usr/local/go/bin/

Manual Install

Alternatively, install packages individually:

sudo add-apt-repository universe
sudo apt install nbdkit nbdkit-plugin-dev pkg-config qemu-system qemu-utils qemu-kvm libvirt-daemon-system libvirt-clients libvirt-dev make gcc unzip xz-utils file ovn-central ovn-host openvswitch-switch

Install Go 1.26.1+ from https://go.dev/dl/ and verify:

go version

Install AWS CLI v2:

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install
aws --version

Step 2. Clone and build

mkdir -p ~/Development/mulga/
cd ~/Development/mulga/
git clone https://github.com/mulgadc/spinifex.git
cd spinifex
./scripts/clone-deps.sh    # Clone viperblock + predastore
./scripts/dev-setup.sh     # Setup complete dev environment

Confirm ./bin/spx exists and is executable.

Step 3. Setup OVN

For a single-node dev environment:

./scripts/setup-ovn.sh --management

This creates the br-int integration bridge, starts ovn-controller, configures Geneve tunnel endpoints, and enables IP forwarding.

Step 4. Initialize

Create a region and availability zone:

./bin/spx admin init --region ap-southeast-2 --az ap-southeast-2a --node node1 --nodes 1

Step 5. Trust the CA certificate

sudo cp ~/spinifex/config/ca.pem /usr/local/share/ca-certificates/spinifex-ca.crt
sudo update-ca-certificates

Step 6. Start services

./scripts/start-dev.sh
export AWS_PROFILE=spinifex

Troubleshooting

Go not found in PATH

After installing Go, it may not be in your current shell session. Add it:

export PATH=$PATH:/usr/local/go/bin/

Add this to your ~/.bashrc or ~/.zshrc for persistence. Verify with:

go version

./bin/spx missing after build

The build did not complete successfully. Re-run the setup:

./scripts/dev-setup.sh

Check the output for compilation errors. Common causes are missing Go version or missing system packages.

OVN services not starting

Verify the setup script was run with --management:

./scripts/setup-ovn.sh --management

Check OVN controller status:

sudo systemctl is-active ovn-controller
sudo ovn-sbctl show

CA certificate not trusted

AWS CLI will reject HTTPS connections to Spinifex services. Re-add the certificate:

sudo cp ~/spinifex/config/ca.pem /usr/local/share/ca-certificates/spinifex-ca.crt
sudo update-ca-certificates

clone-deps.sh fails

Ensure you have access to the GitHub repositories. If using SSH and it fails, try HTTPS:

git config --global url."https://github.com/".insteadOf "git@github.com:"
./scripts/clone-deps.sh