📘 Runbooks
The following is a list of Runbooks grouped by category.
🌐 DNS & Networking
| Runbook | Description |
|---|---|
| Ansible Pi-hole and DNS Management Runbook | Central reference for all Ansible playbooks managing Pi-hole and DNS, including installation, updates, and host records. |
| Update Pi-hole DNS Servers Runbook | Step-by-step instructions to deploy or update Pi-hole DNS servers. |
| Request Web Certificates Runbook | Step-by-step instructions to request and manage TLS certificates for all hosted websites in the homelab. |
| Request Web Certificates for a Specific Domain Runbook | Step-by-step instructions to request and manage TLS certificates for a specific website. |
| Join an Ubuntu 24 Host to Active Directory Runbook | Step-by-step instructions of joining an Ubuntu 24.04 host to the refol.us Active Directory domain. |
| Configure An Inventory For Entra ID OAuth2 | Step-by-step instructions on how to update an inventory so a site behind rproxy uses oauth2-proxy with Microsoft Entra ID. |
| Configure An Inventory Host Web Service For A Reverse Proxy | This runbook explains how to update an inventory so a host web service is available through the repository’s reverse proxy setup. |
| Rotate Azure Entra ID OAuth2 Client Secret Runbook | Follow these steps when Azure Entra ID App Registration secret expires. |
🎬 Media Services
| Runbook | Description |
|---|---|
| Deploy Plex Media Server Runbook | Step-by-step instructions to deploy or update Plex Media Server. |
| Deploy Lidarr Runbook | Step-by-step instructions to deploy or update Lidarr. |
| Deploy Radarr Runbook | Step-by-step instructions to deploy or update Radarr. |
| Deploy Sonarr Runbook | Step-by-step instructions to deploy or update Sonarr. |
| Deploy Lazy Librarian Runbook | Step-by-step instructions to deploy or update Lazy Librarian. |
| Deploy Calibre-web Runbook | Step-by-step instructions to deploy or update Calibre-web. |
| Deploy Calibre Runbook | Step-by-step instructions to deploy or update Calibre. |
| Deploy Sabnzbd Runbook | Step-by-step instructions to deploy or update Sabnzbd. |
💻 Development & Productivity
| Runbook | Description |
|---|---|
| Deploy Code Server Runbook | Step-by-step instructions to deploy or update Code Server. |
| Disable Code Server Runbook | Step-by-step instructions to disable Code Server. |
| Enable Code Server Runbook | Step-by-step instructions to enable Code Server. |
| Deploy SemaphoreUI Runbook | Instructions to deploy or update SemaphoreUI services. |
| Mirror wiki pages to HTML static page runbook | Step-by-step instructions on mirroring homelab wiki pages to https://homelab.refol.us |
| Configure Semaphore UI Projects Runbook | Instructions on adding or modifying a Semaphore UI project |
| Defining When Semaphore Runs a Scheduled Task | Provides details on configuring the cron field in a Semaphore UI scheduled task |
| Configure WSL2 as an Ansible Control Node Runbook | Step-by-step instructions on how to use WSL2 as an Ansible control node |
📈 Monitoring & Observability
| Runbook | Description |
|---|---|
| Adding Prometheus Support to a VM or Service | Choose the monitoring level you need. |
| Adding a Grafana Dashboard | Step-by-step instructions to add, provision, and deploy a new Grafana dashboard through Ansible. |
| Adding NGINX Exporter to an Inventory | Step-by-step instructions on adding Prometheus NGINX Exporter to an inventory. |
| Adding Node Exporter to an Inventory | Step-by-step instructions on adding Prometheus Node Exporter to an inventory. |
| Adding Blackbox Exporter Targets | Step-by-step instructions on adding web probe targets for the Prometheus Blackbox Exporter. |
| Adding Postgres Exporter to an Inventory | Step-by-Step instructions on adding Prometheus Postgres Exporter to an inventory. |
| Deploy nginx-prometheus-exporter to Reverse Proxy hosts | Step-by-Step instructions on deploying nginx-prometheus-exporter to the reverse proxy hosts. |
| Deploy Blackbox Exporter to Prometheus host | Step-by-Step instructions on deploying blackbox-exporter to the Prometheus host. |
| Deploy Node Exporter to a Specific Inventory Target | Step-by-Step instructions on deploying node exporter to a specific inventory. |
| Deploy PostgreSQL Exporter to the PostgreSQL Inventory | Step-by-Step instructions on deploying postgresql exporter to PostgreSQL inventories. |
| Deploy PVE Exporter to Proxmox Nodes | Step-by-Step instructions on deploying PVE exporter to Proxmox inventories. |
| Deploy Grafana Dashboards | Use an Ansible playbook to update provisioned dashboard files on an existing Grafana installation. |
🖥️ Virtual Machine & System Maintenance
| Runbook | Description |
|---|---|
| Proxmox VM Template Runbook | Step-by-step instructions to create a cloud-init VM template. |
| Virtual Machine Snapshot Runbook | Instructions to create and manage snapshots of virtual machines in the home lab. |
| Ubuntu Virtual Machine Disk Expansion Runbook | Instructions to expand disk size for Ubuntu virtual machines. |
| Deploy Linux Security Updates Runbook | Instructions to apply security updates to Linux hosts in the home lab. |
| Proxmox Cluster Update Runbook | Step‑by‑step instructions to safely update a three‑node Proxmox cluster. |
| Provision a Virtual Machine Runbook | Use an Ansible playbook to deploy a new virtual machine. |
| NFS Mount Troubleshooting Runbook | Troubleshoot NFS issues (autofs and fstab). |
| Web Service Outage Troubleshooting Runbook | Troubleshoot a web service outage. |
| Ubuntu LTS Release Upgrade Runbook | Step-by-step instructions to upgrade Ubuntu from one LTS upgrade to another. Currently configured to upgrade Ubuntu 24.04 LTS VM to Ubuntu 26.04 LTS |
| Migrate PostgreSQL 14 to PostgreSQL 18 | Manual migration of PostgreSQL 14 to 18. |
| Migrate PostgreSQL 17 to PostgreSQL 18 | Manual migration of PostgreSQL 17 to 18. |
| Migrate a PostgreSQL Instance Between Hosts | Migrate a PostgreSQL instance’s logical databases and approved roles from one host to another. |
| Decommission a Virtual Machine | Instructions on how to properly decommission a virtual machine. |
💾 TrueNAS Management
| Runbook | Description |
|---|---|
| Join or Reconfigure TrueNAS Active Directory | Manage TrueNAS network configuration and AD integration. |
| Add TrueNAS Shares | Create TrueNAS datasets and SMB or NFS shares. |
| Add TrueNAS Local Users | Add TrueNAS local users and groups. |
| Bootstrap TrueNAS for Ansible | Prepare TrueNAS to use with Ansible. |
| Manage TrueNAS Applications | Manage TrueNAS applications. |
| Create and Modify TrueNAS Datasets | Manage TrueNAS filesystem datasets. |
| Manage TrueNAS Dataset Permissions and ACLs | Define ownership, POSIX permissions, SMB ACLs, and multiprotocol access for TrueNAS datasets. |
| Manage TrueNAS Users and Credentials | Maintain existing TrueNAS local accounts, supplementary memberships, and credentials. |
| Modify or Retire TrueNAS Shares | Change or retire TrueNAS SMB/NFS exports. |
| Troubleshoot TrueNAS Configuration Runs | Diagnose TrueNAS configuration failures. |
| Update TrueNAS Safely | Install an approved TrueNAS release, optionally reboot, and verify service health. |
| Creating TrueNAS VMs with Ansible | Provision a VM in TrueNAS using Ansible. |
| Creating TrueNAS Apps with Ansible | Create an app in TrueNAS using Ansible. |
📄 Templates & Miscellaneous
| Runbook | Description |
|---|---|
| Runbook Ansible Template | Template for creating new Ansible runbooks in the home lab wiki. |