# 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.

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

**Manual Step**: If you are using Tailscale, you must manually authenticate it after the script runs:
```bash
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.

```bash
./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.

```bash
./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:
   ```bash
   ./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.