homelab-codex-ws/docs/node-onboarding.md

Node Onboarding Workflow

This document describes the process of onboarding a new Linux machine into the homelab platform.

Overview

The onboarding process consists of three main stages:

1. Preparation: Setting up the runtime environment and dependencies.
2. Discovery: Collecting hardware and software characteristics of the node.
3. Inventory Generation: Creating the YAML configuration files for the node in the central inventory.

Prerequisites

• A fresh Linux machine (Debian/Ubuntu recommended).
• SSH access with sudo privileges.
• Tailscale account (if using Tailscale for networking).

Onboarding Steps

1. Node Preparation

Run the prepare-node.sh script on the target node. This script will install Docker, Tailscale, and create the /opt/homelab directory structure.

sudo ./scripts/bootstrap/prepare-node.sh

Manual Step: If you are using Tailscale, you must manually authenticate it after the script runs:

sudo tailscale up

2. Node Discovery

Run the discover-node.sh script to collect system information. It is recommended to redirect the output to a file.

./scripts/bootstrap/discover-node.sh > discovery-$(hostname).json

3. Inventory Generation

Copy the discovery JSON file to your management machine (where the homelab repository is located) and run the inventory generator.

./scripts/bootstrap/generate-node-inventory.py discovery-node-name.json

This will create a new directory in hosts/<hostname>/ with the following files:

• host.yaml: Basic host identity and roles.
• capabilities.yaml: Hardware and software capabilities.
• paths.yaml: Runtime path definitions.
• networking.yaml: Networking configuration.

4. Finalization

1. Review the generated YAML files in hosts/<hostname>/.
2. Assign appropriate roles to the node in hosts/<hostname>/host.yaml.
3. Commit the new host configuration to the repository.
4. Run the deployment script to apply the initial configuration:

   ./scripts/deploy/deploy-node.sh <hostname>
   

Recovery Onboarding

If a node needs to be re-onboarded after a failure:

1. Run prepare-node.sh again. It is idempotent and will ensure the environment is correct.
2. Restore any critical data to /opt/homelab/data/ and /opt/homelab/backups/.
3. Re-run discover-node.sh if hardware has changed, or reuse the existing inventory if it hasn't.

Tailscale Assumptions

• Nodes are assumed to use Tailscale for management and inter-node communication.
• The networking.yaml will be populated with the Tailscale IP found during discovery.
• If Tailscale is not used, manual adjustment of networking.yaml and host.yaml is required.

Troubleshooting

• Docker not starting: Check journalctl -u docker.
• Discovery fails: Ensure all required tools (lscpu, lsblk, ip, etc.) are installed.
• Inventory Generation error: Ensure PyYAML is installed on the management machine.