---
title: How to Add a New Node to the Homelab
description: This guide outlines the process for onboarding a new execution node into the GitOps-lite environment.

phases:
  - phase: 1. Preparation (on SATURN)
    steps:
      - "Define Node Inventory: Create hosts/<hostname>/ directory"
      - "Add host.yaml with hardware metadata"
      - "Add networking.yaml with IP and Tailscale info"
      - "Add capabilities.yaml with node capability description"
      - "Add services.txt listing assigned services"
      - "Update inventory/topology.yaml"
      - "Commit and push changes to Forgejo"

  - phase: 2. Bootstrapping (on the New Node)
    steps:
      - "Install OS (Debian/Ubuntu recommended)"
      - "Configure SSH and user access"
      - "Install Docker, Docker Compose, Tailscale, Git"
      - "Join the tailnet"
      - "Clone repository: git clone <forgejo-url>/homelab-codex.git ~/homelab-codex-ws"
      - "Setup runtime: sudo mkdir -p /opt/homelab/{services,config,state,logs} && sudo chown -R $USER:$USER /opt/homelab"

  - phase: 3. Initial Deployment
    steps:
      - "Run prepare: ~/homelab-codex-ws/scripts/deploy/deploy.sh prepare"
      - "Run deploy: ~/homelab-codex-ws/scripts/deploy/deploy.sh deploy"
      - "Run verify: ~/homelab-codex-ws/scripts/deploy/deploy.sh verify"