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

docs: tweaks

Browse Source
This commit is contained in:
Julian Sommer
2026-03-31 13:10:59 +10:00
parent b76953bfb4
commit 355decd406
7 changed files with 26 additions and 132 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/creating-accounts/README.md
+1 -1
View File
@@ -32,7 +32,7 @@ Spinifex supports multi-tenant account isolation. Each account gets its own IAM
## Create Account
```bash
./bin/spx admin account create --name myteam
spx admin account create --name myteam
export AWS_PROFILE=spinifex-myteam
```
docs/creating-an-environment/README.md
-110
View File
@@ -1,110 +0,0 @@
---
title: "Creating an Environment"
description: "End-to-end guide: user accounts, SSH keys, VPCs, AMIs, and launching instances."
category: "Environments"
tags:
- environment
- vpc
- ec2
- ssh
resources:
- title: "Spinifex Repository"
url: "https://github.com/mulgadc/spinifex"
- title: "Debian Cloud Images"
url: "https://cloud.debian.org/images/cloud/bookworm/latest/"
---
# Creating an Environment
> End-to-end guide: user accounts, SSH keys, VPCs, AMIs, and launching instances.
## Table of Contents
- [Overview](#overview)
- [Instructions](#instructions)
- [Troubleshooting](#troubleshooting)
---
## Overview
This guide walks through the complete workflow for creating a production-ready Spinifex environment.
## Instructions
## 1. Import SSH Key
```bash
aws ec2 import-key-pair --key-name "spinifex-key" --public-key-material fileb://~/.ssh/id_rsa.pub
```
## 2. Create VPC
```bash
aws ec2 create-vpc --cidr-block 10.200.0.0/16
export SPINIFEX_VPC="vpc-XXX"
aws ec2 create-subnet --vpc-id $SPINIFEX_VPC --cidr-block 10.200.1.0/24
export SPINIFEX_SUBNET="subnet-XXX"
```
## 3. Import AMI
```bash
./bin/spx admin images list
./bin/spx admin images import --name debian-12-x86_64
export SPINIFEX_AMI="ami-XXX"
```
## 4. Launch Instance
```bash
aws ec2 run-instances \
--image-id $SPINIFEX_AMI \
--instance-type t3.small \
--key-name spinifex-key \
--subnet-id $SPINIFEX_SUBNET \
--count 1
```
## 5. Connect via SSH
```bash
ps auxw | grep $INSTANCE_ID
# Look for: hostfwd=tcp:127.0.0.1:<port>-:22
ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>
```
## Troubleshooting
## Instance Stuck in Pending
Check the Spinifex daemon and QEMU logs for boot errors:
```bash
ls ~/spinifex/logs/
cat ~/spinifex/logs/spinifex.log
```
Verify the AMI exists and architecture matches your host:
```bash
aws ec2 describe-images --image-ids $SPINIFEX_AMI
```
## SSH Connection Refused
cloud-init takes 30-60 seconds to configure networking and SSH after boot. Wait and retry.
Verify the SSH port forwarding is active:
```bash
ps auxw | grep hostfwd
```
Ensure you're using the correct key and port:
```bash
ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>
```
docs/installing-spinifex/README.md
+1 -1
View File
@@ -38,7 +38,7 @@ This guide installs Spinifex on a single server using the binary installer. For
- Ubuntu 22.04 / 24.04 / 25.10
- Debian 12 / 13
**What gets installed:**
**What Gets Installed:**
- Spinifex daemon and CLI
- QEMU/KVM for virtual machine management
docs/launching-instances/README.md
+6 -2
View File
@@ -125,11 +125,15 @@ aws ec2 describe-instance-types \
## SSH (Development)
In development mode, find the QEMU port forward and connect via localhost:
```bash
ps auxw | grep $INSTANCE_ID
ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p <port>
```
For production SSH via public IPs, see [Setting Up Your Cluster](/docs/setting-up-your-cluster).
## Troubleshooting
### Instance Fails to Boot
@@ -144,8 +148,8 @@ aws ec2 describe-images --image-ids $SPINIFEX_AMI
If the AMI is for a different architecture (e.g. arm64 on an x86_64 host), import the correct image:
```bash
./bin/spx admin images list
./bin/spx admin images import --name debian-12-x86_64
spx admin images list
spx admin images import --name debian-12-x86_64
```
### Cannot SSH Into Instance
docs/placement-groups/README.md
+1 -1
View File
@@ -99,7 +99,7 @@ aws ec2 delete-placement-group --group-name my-spread-group
Not enough distinct physical hosts for a spread launch. Reduce `--count` or terminate existing instances to free host slots:
```bash
./bin/spx admin nodes list
spx admin nodes list
```
### Cannot Delete Placement Group
docs/source-install/README.md
+9 -9
View File
@@ -57,15 +57,7 @@ cd spinifex
Confirm `./bin/spx` exists.
## Step 3. Initialize
```bash
sudo ./bin/spx admin init --node node1 --nodes 1
```
Save the admin credentials printed during init.
## Step 4. Setup OVN
## Step 3. Setup OVN
If your WAN interface is already a bridge (e.g. `br-wan`), setup-ovn.sh auto-detects it:
@@ -83,6 +75,14 @@ If your WAN is a physical NIC, choose one:
./scripts/setup-ovn.sh --management --macvlan --wan-iface=enp0s3
```
## Step 4. Initialize
```bash
sudo ./bin/spx admin init --node node1 --nodes 1
```
Save the admin credentials printed during init.
## Step 5. Start Services
```bash
docs/spinifex-admin-cli/README.md
+8 -8
View File
@@ -27,7 +27,7 @@ resources:
The `spx` binary is the central administration tool for managing your Spinifex infrastructure. It provides commands for cluster initialization, account management, node operations, VM lifecycle, and service control.
**Binary location:** `~/Development/mulga/spinifex/bin/spx`
**Binary location:** `/usr/local/bin/spx` (binary install) or `~/Development/mulga/spinifex/bin/spx` (source install)
All services in the Spinifex platform are managed through this single binary.
@@ -36,14 +36,14 @@ All services in the Spinifex platform are managed through this single binary.
## Account Management
```bash
./bin/spx admin account create --name myteam
spx admin account create --name myteam
export AWS_PROFILE=spinifex-myteam
```
## Node Management
```bash
./bin/spx get nodes
spx get nodes
```
```
@@ -56,20 +56,20 @@ node3 Ready 127.0.0.3 ap-southeast-2 ap-southeast-2a 2m 0
## Monitor Resources
```bash
./bin/spx top nodes
spx top nodes
```
## Image Management
```bash
./bin/spx admin images list
./bin/spx admin images import --name debian-12-arm64
spx admin images list
spx admin images import --name debian-12-arm64
```
## Cluster Shutdown
```bash
./bin/spx admin cluster shutdown
spx admin cluster shutdown
```
## Troubleshooting
@@ -79,7 +79,7 @@ node3 Ready 127.0.0.3 ap-southeast-2 ap-southeast-2a 2m 0
The binary may not be executable. Fix permissions:
```bash
chmod +x ./bin/spx
chmod +x /usr/local/bin/spx
```
If you get permission errors during operations, ensure you're running with appropriate privileges. Some OVN and networking commands require `sudo`.