{
  "$type": "site.standard.document",
  "bskyPostRef": {
    "cid": "bafyreigvrugu4he73vzb2bg2zccvpecifnfyiamdusbdwzc5zhswpgfqyq",
    "uri": "at://did:plc:5y2ps7xhcqmc2d63b73ui72s/app.bsky.feed.post/3mlqv4pa6n4h2"
  },
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreibgjycorhpnfxylnd4joaidtifmxftvohamxffxvese46ub52hisi"
    },
    "mimeType": "image/jpeg",
    "size": 266799
  },
  "description": "Learn how to install operating systems, configure SSH access, and prepare your Raspberry Pi ClusterHAT cluster for automation with Ansible and Kubernetes in this step-by-step guide.",
  "path": "/setting-up-a-raspberry-pi-cluster-with-clusterhat-part-1-os-installation-ssh-setup/",
  "publishedAt": "2026-05-13T18:00:54.000Z",
  "site": "https://blog.php-systems.com",
  "tags": [
    "https://clusterctrl.com/setup-software",
    "Part 2",
    "https://medium.com/@dhuck/the-missing-clusterhat-tutorial-45ad2241d738"
  ],
  "textContent": "Building a Raspberry Pi cluster with a ClusterHAT is a fantastic way to experiment with distributed systems, automation, and Kubernetes at a low cost. While installing the hardware is straightforward, the software setup can feel under-documented. This guide fills that gap.\n\nIn this first part, we’ll focus on:\n\n  * Installing operating systems on all nodes\n  * Preparing access credentials\n  * Setting up SSH for seamless cluster management\n\n\n\nLater, we’ll build on this foundation with Ansible automation and Kubernetes deployment.\n\n* * *\n\n## Step 1: Prepare Boot Configuration Files\n\nStart by creating a working directory (e.g., `dir`) containing the following files:\n\n  * `ssh` (empty file to enable SSH)\n  * `userconfig.txt`\n\n\n\nEdit `userconfig.txt` with your desired username and password using this format:\n\n\n    <username>:<encrypted_password>\n\nTo generate the encrypted password, run:\n\n\n    echo 'mypassword' | openssl passwd -6 -stdin\n\nIf you're scripting this step, double-check the generated hash before copying it—mistakes here can lock you out later.\n\n* * *\n\n## Step 2: Download and Flash the OS\n\nDownload the ClusterHAT-compatible OS images from:\n\nhttps://clusterctrl.com/setup-software\n\nFor this setup, the **CNAT Lite** versions are a good lightweight choice.\n\nFlash each SD card with the appropriate image. After flashing:\n\n  1. Reinsert the SD card\n  2. Mount the boot partition (`bootfs`)\n  3. Copy your prepared files:\n\n\n\n\n    cp /dir/* /path/to/bootfs/\n\n* * *\n\n## Step 3: Boot the Controller Node\n\nInsert the controller’s SD card and power it on.\n\n  * Allow time for initial setup to complete\n  * Log in and verify everything is working\n  * If something fails, recheck the boot partition files\n\n\n\nPatience matters here—first boot can take a minute.\n\n* * *\n\n## Step 4: Boot and Assign Worker Nodes\n\nInsert the correct SD cards into each Raspberry Pi Zero connected via ClusterHAT.\n\nPower on each node individually using:\n\n\n    clusterctrl on p1\n\nIf the wrong node powers on:\n\n\n    clusterctrl off p1\n\nCorrect the issue and retry.\n\nRepeat this process until all nodes (`p1`–`p4`) are powered and correctly mapped.\n\n* * *\n\n## Step 5: Set Up SSH Key-Based Access\n\nSSH keys make cluster management dramatically easier.\n\n### Generate Your SSH Key\n\nRun:\n\n\n    ssh-keygen -t rsa -b 4096\n\n* * *\n\n### Configure SSH Client\n\nEdit your SSH config:\n\n\n    nano ~/.ssh/config\n\nAdd:\n\n\n    Host controller <controller_ip>\n      HostName <controller_ip>\n      User <username>\n      IdentityFile ~/.ssh/id_rsa\n\n    Host p1 <p1_ip>\n      HostName <p1_ip>\n      User <username>\n      ProxyCommand ssh <username>@<controller_ip> -W %h:%p\n      IdentityFile ~/.ssh/id_rsa\n\n    Host p2 <p2_ip>\n      HostName <p2_ip>\n      User <username>\n      ProxyCommand ssh <username>@<controller_ip> -W %h:%p\n      IdentityFile ~/.ssh/id_rsa\n\n    Host p3 <p3_ip>\n      HostName <p3_ip>\n      User <username>\n      ProxyCommand ssh <username>@<controller_ip> -W %h:%p\n      IdentityFile ~/.ssh/id_rsa\n\n    Host p4 <p4_ip>\n      HostName <p4_ip>\n      User <username>\n      ProxyCommand ssh <username>@<controller_ip> -W %h:%p\n      IdentityFile ~/.ssh/id_rsa\n\n* * *\n\n### Copy SSH Keys to Controller\n\nRun:\n\n\n    ssh-copy-id -i <identity file> <username>@<controller_ip>\n\n* * *\n\n### Update Controller Hosts File\n\nOn the controller, edit:\n\n\n    sudo nano /etc/hosts\n\nAdd:\n\n\n    172.19.181.1 p1\n    172.19.181.2 p2\n    172.19.181.3 p3\n    172.19.181.4 p4\n\n* * *\n\n### Copy Keys to Worker Nodes\n\nFrom your local machine:\n\n\n    ssh-copy-id -i ~/.ssh/id_rsa p1\n    ssh-copy-id -i ~/.ssh/id_rsa p2\n    ssh-copy-id -i ~/.ssh/id_rsa p3\n    ssh-copy-id -i ~/.ssh/id_rsa p4\n\nOnce complete, verify you can SSH into each node without a password.\n\n* * *\n\n## What’s Next?\n\nYour Raspberry Pi cluster is now:\n\n  * Fully imaged\n  * Networked\n  * Accessible via SSH\n\n\n\nIn Part 2, we’ll use Ansible to automate configuration and provisioning across the cluster.\n\nIn **Part 3** , we’ll deploy Kubernetes and turn this into a fully functional container orchestration platform.\n\n* * *\n\n## Additional Resources\n\nIf you’re looking for more background on ClusterHAT setups, this guide is worth a read:\n\n  * _The Missing ClusterHAT Tutorial_\nhttps://medium.com/@dhuck/the-missing-clusterhat-tutorial-45ad2241d738\n\n\n\n* * *\n\nStay tuned for the next part—this is where things start to scale.",
  "title": "Setting Up a Raspberry Pi Cluster with ClusterHAT (Part 1: OS Installation & SSH Setup)",
  "updatedAt": "2026-05-21T10:45:53.873Z"
}