diff --git a/docs/creating-accounts/README.md b/docs/creating-accounts/README.md index bc4862379..44524ed65 100644 --- a/docs/creating-accounts/README.md +++ b/docs/creating-accounts/README.md @@ -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 ``` diff --git a/docs/creating-an-environment/README.md b/docs/creating-an-environment/README.md deleted file mode 100644 index 9d0d32f70..000000000 --- a/docs/creating-an-environment/README.md +++ /dev/null @@ -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:-:22 - -ssh -i ~/.ssh/spinifex-key ec2-user@127.0.0.1 -p -``` - -## 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 -``` diff --git a/docs/installing-spinifex/README.md b/docs/installing-spinifex/README.md index 26fbfe660..b6ce956a6 100644 --- a/docs/installing-spinifex/README.md +++ b/docs/installing-spinifex/README.md @@ -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 diff --git a/docs/launching-instances/README.md b/docs/launching-instances/README.md index 46ec2e673..6d8e39cc2 100644 --- a/docs/launching-instances/README.md +++ b/docs/launching-instances/README.md @@ -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 ``` +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 diff --git a/docs/placement-groups/README.md b/docs/placement-groups/README.md index eac300165..16e3e2ef6 100644 --- a/docs/placement-groups/README.md +++ b/docs/placement-groups/README.md @@ -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 diff --git a/docs/source-install/README.md b/docs/source-install/README.md index cef4a5cad..b88840ed9 100644 --- a/docs/source-install/README.md +++ b/docs/source-install/README.md @@ -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 diff --git a/docs/spinifex-admin-cli/README.md b/docs/spinifex-admin-cli/README.md index 99abdd574..f4619ddf0 100644 --- a/docs/spinifex-admin-cli/README.md +++ b/docs/spinifex-admin-cli/README.md @@ -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`.