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!

• Project Goals
• Technologies Used
• Development Environment
  • 1. Prerequisites
  • 2. Project Dependencies
  • 3. Credentials
    • ssh-agent
    • Ansible Vault Password
  • 4. Verify Ansible Connection
• Ansible Roles
  • Security

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.

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.

This project uses uv to manage Python, Ansible, and related tools.

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

This project uses uv to manage Python dependencies in a consistent, isolated environment:

Install them like so:

uv sync

Verify they are available:

$ uv which ansible
<path_to_this_project>/Homelab/.venv/bin/ansible

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.

Homelab uses Ansible Vault to managed its secrets. Before executing any Playbooks, Ansible will check that it can access the vault.

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

You can set this variable permanently by adding the password in the vault.secret file:

#!/usr/bin/env bash

export ANSIBLE_VAULT_PASSWORD='xxxxxxxxxxxxxx'

If you aren't using direnv, then load it into your current shell session like so:

source vault.secrets

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:

uv run ansible localhost -m ping

Managed Node:

uv run ansible unprovisioned_yoshimo -m ping

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.

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

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