oskar/homelab-codex-ws
1
0
Fork 0
Code Issues Pull requests Actions Packages Projects Releases Wiki Activity
homelab-codex-ws/kb/runbooks/node-onboarding.md
oskar 454a8f18f3 feat(kb): przenosiny type=runbook do kb/runbooks/ (5 plikow, bez SPLIT) 
ollama-solaria-cutover, node-onboarding-tool (ze scripts/onboard/README.md),
ha-diag-agent-deploy, npm-api (ze scripts/npm/README.md),
node-onboarding (public).

UWAGA: scripts/onboard/README.md jest linkowany z CLAUDE.md — odwolanie
naprawiane w grupie 7.

git mv + frontmatter, tresc nietknieta.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-04 16:58:04 +02:00

3 KiB
Raw Blame History

okf type visibility status updated links
0.1 runbook public active 2026-05-12

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.