Homelab

This repo automates my home network setup. This automation is hardware-agnostic, but I like to run it on small single-board computers like Raspberry Pis.

Think: small computers, big network!

Table of Contents

• Project Goals
• Technologies Used
• Development Environment
  • 1. Prerequisites
  • 2. pyenv
  • 3. Install Dependencies
  • 4. Credentials
    • ssh-agent
    • Ansible Vault Password
  • 5. Verify Ansible Connection
• Ansible Roles
  • Security
• Problems & Solutions
  • You Upgraded Homebrew and it Broke your Python Virtual Environment
    • Problem
    • Cause
    • Solution

Project Goals

This project aims to:

• Come with batteries included so that setup is quick and easy.
• Maintain a test environment that mirrors my home network for fast, safe deployment.
• Deploy across multiple operating-systems and CPU architectures.
• Support both on-metal and cloud deployments.
• Ensure cross-OS service interoperability.
• Track Ansible and Salt configurations in parallel project branches for comparison.

Technologies Used

Homelab makes use of the following tools:

• Ansible: playbooks to configure services on each device.
• Docker: containers that run and manage the services:
  • webdavis/docker-raspios-lite: a hand spun Raspberry Pi OS Lite Docker Image
• Scripts: these simplify working with Ansible and other tools in this project.

Development Environment

This project requires Python 3 and uses a Pyprojectx / Poetry combo to manage Ansible and related tools.

Follow these steps to ensure your environment is ready to work on this project:

1. Prerequisites

Tip

If this is your first time working on this project, follow the instructions in macos-dev-environment.md first.

The instructions below assume you've done this.

2. pyenv

pyenv is used to manage and track this projects Python version. The current version is specified in the .python-version file.

Run this command to activate pyenv in your current shell:

eval "$(pyenv init -)"

Once pyenv is activated, it reads the .python-version file and activates the Python version specified there.

Important

• This command must be run every time you start a new terminal session before working on this project.
• You can run this command from any folder in the project.

3. Install Dependencies

This project uses Pyprojectx and Poetry to manage Python dependencies in a consistent, isolated environment:

• Pyprojectx: Provides the ./pw wrapper script, ensuring all project tools run consistently without needing global installations (including Poetry).
• Poetry: manages the Python dependencies used by this project (including Ansible).

Install the dependencies:

./pw poetry install

Warning

Make sure you're using the project's Poetry, not a system-wide one:

./pw which poetry

Example Output: the output should point to a path like:

<path_to_this_project>/Homelab/.pyprojectx/venvs/main-ab061d9d4f9bea1cc2de64816d469baf-py3.13/bin/poetry

Tip

Having trouble? Check the Problems and Solutions section.

4. Credentials

ssh-agent

Ansible uses SSH to connect to managed nodes.

To avoid repeatedly entering the private key passphrase, load your SSH private key into ssh-agent:

ssh-add ~/.ssh/id_rsa

Other tools may provide an ssh-agent service. I personally use KeePassXC.

Ansible Vault Password

Homelab manages secrets with Ansible Vault Before executing any Playbooks, Ansible ensures it can access the vault.

Ansible Vault fetches the vault password using the [vault.password.py](./vault.password.py script, which reads it from the ANSIBLE_VAULT_PASSWORD environment variable.

You can set this variable permanently by adding the following to your shell configuration file (e.g., ~/.bashrc):

export ANSIBLE_VAULT_PASSWORD='xxxxxxxxxxxxxx'

Alternatively, you can create a vault.secret file with the following contents:

#!/usr/bin/env bash

export ANSIBLE_VAULT_PASSWORD='xxxxxxxxxxxxxx'

Then, load it into your current shell session with:

source vault.secrets

5. Verify Ansible Connection

Before you do anything else, verify that you can connect to both the managing node (your localhost) and a managed node using Ansible's ping module:

Manager Node:

./pw poetry run ansible localhost -m ping

Managed Node:

./pw poetry run ansible unprovisioned_yoshimo -m ping

Tip

See inventory.yml for other managed nodes.

Now you should be good to go!

Follow these steps every time you return to the project. Once done, you’re ready to run Ansible plays or work on the project safely.

Ansible Roles

This project uses the following Ansible roles. Most of these will eventually be moved to their own repositories.

Security

To run this role, your playbook must include the following:

• become: yes: required to execute tasks requiring administrative access.
• gather_facts: yes: to collect essential system details before executing tasks.

For example:

- name: Configure security settings
  hosts: yoshimo
  become: yes
  gather_facts: yes
  tasks:
    - name: Import security role
      ansible.builtin.import_role:
        name: security

Problems & Solutions

You Upgraded Homebrew and it Broke your Python Virtual Environment

Problem

After updating Homebrew, your .pyprojectx/ environment may break. For example you might get a dyld error like this one:

$ ./pw poetry run ansible unprovisioned_yoshimo -m ping

dyld[74408]: Library not loaded: /opt/homebrew/Cellar/python@3.13/3.13.5/Frameworks/Python.framework/Versions/3.13/Python
...

Cause

The .pyprojectx/ environment was created before the correct Python version was activated with pyenv, so it linked to a Homebrew-managed Python that may no longer exist after the update.

Solution

Rebuild the .pyprojectx/ environment using the correct Python version.

1. Remove the broken environment:

rm -rf .pyprojectx/

2. Activate the shell environment for pyenv:

eval "$(pyenv init -)"

3. Recreate the environment:

pyprojectx bootstrap

After this, your Python virtual environment will use the pyenv-managed Python, resolving the Homebrew-related break.