An Ansible playbook for configuring one or more Raspberry Pi devices running Raspberry Pi OS Lite (64-bit).

Why does this exist? Setting up a Pi from scratch involves a lot of steps that are easy to forget. This playbook automates the configuration so that every device ends up in a known, reproducible state — whether it's your first Pi or your fifth.

What it configures

← → Common (roles/common)

• Generate UTF-8 locale
• Install common dependencies not included with Raspberry Pi OS Lite
• Configure timezone ← group_vars/all/infrastructure.yml
• Configure hostname ← host_vars/<hostname>.yml, you can use host_vars/pi-01.yml as template
• Create an ops user, install your SSH public key, and grant passwordless sudo
• Disable root login and password-based SSH authentication

Network (roles/network)

• Disable IPv6
• Configure a static IPv4 address on a VLAN-tagged interface ← host_vars/<hostname>.yml

Print Server (roles/printServer)

• Install CUPS and Avahi for network printer discovery
• Configure Brother P-Touch and Dymo label printer drivers

Dotfiles (roles/chezmoi)

• Bootstrap chezmoi and apply personal configuration from your dotFiles repository

🚀 Quick Start

1 — Flash and boot the Pi

Follow the manual setup guide to flash the OS, set credentials, and get the device on the network. Come back here once you can SSH in.

2 — Configure the inventory

Edit inventory.ini to match your device's hostname or IP address:

[pi_nodes]
pi-01 ansible_host=192.168.1.50   # ← change this
pi-02 ansible_host=192.168.1.51   # ← change this

3 — Set global and host-specific variables

Copy the infrastructure vars file and adjust it for your ecosystem:

cp group_vars/all/infrastructure.yml group_vars/all/ecosystem.yml

Edit the new file to set the correct values. Refer to the comments inside the file for guidance.

Copy the example host vars file and adjust it for your device:

cp host_vars/pi-01.yml host_vars/<your-hostname>.yml

Edit the new file to set the correct static IP, VLAN interface, and any other device-specific values. Refer to the comments inside the file for guidance.

4 — Enable the roles you need

Open piSetup.yml and uncomment the roles you want to apply:

- name: Raspberry Pi Configuration
  hosts: pi_nodes
  roles:
    - common        # Always recommended
    - network       # Static IP + disable IPv6
    - printServer   # CUPS + label printer support
    - chezmoi       # Personal dotfiles

5 — Run the playbook

ansible-playbook piSetup.yml

For the very first run, Ansible needs to authenticate with a password before SSH key-based access is configured:

ansible-playbook piSetup.yml --ask-pass

You can also limit execution to a single host or a specific role using tags:

ansible-playbook piSetup.yml --limit pi-01
ansible-playbook piSetup.yml --tags network

Project structure

piSetup/
├── ansible.cfg            # Ansible defaults (SSH, privilege escalation)
├── inventory.ini          # List of Pi devices
├── piSetup.yml            # Main playbook
├── group_vars/all/        # Variables shared across all hosts
├── host_vars/             # Per-device overrides (IP, VLAN interface, etc.)
├── roles/
│   ├── common/            # Base system configuration
│   ├── network/           # Static IP and IPv6 hardening
│   ├── printServer/       # CUPS + label printers
│   └── chezmoi/           # dotFiles bootstrap
└── docs/
    ├── guide.md            # Manual setup guide (flash, hardware, firmware)
    └── troubleshooting.md  # LED codes, common errors, diagnostic commands

Documentation

• Manual guide — step-by-step guide to flash the OS, optimize hardware, and update firmware before running Ansible
• Troubleshooting — LED status codes, SSH errors, SD card health, and common issues

Contributing

Suggestions and pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Refer to the contribution guidelines and adhere to this project's code of conduct.

License

piSetup by Benoît H. Dicaire is shared under the MIT license.