Skip to content
DRAFT

Runbooks

Comprehensive, step-by-step guides for building complete deployments from the ground up. Each runbook helps you understand and implement infrastructure patterns through clear, actionable instructions.

Purpose

The runbooks serve as instructional guides that break down the implementation process into clear, actionable steps, making them ideal for:

  • New users learning to build infrastructure from scratch
  • Developers who want to understand the implementation details
  • Teams adapting these patterns to their own environments
  • Anyone who prefers a guided, step-by-step approach

Runbook Usage Patterns

All runbooks follow the same pattern: set up workspace variables, then call tasks to do the work.

  1. Set up workspace variables — Each runbook has you configure a Windsor context and put the right values in contexts/<context>/windsor.yaml (and optionally secrets). That might mean choosing a context name (e.g. dev-cluster, prod-rpi), setting things like INCUS_REMOTE_NAME, VM_INSTANCE_NAME, IPs, image versions, or paths. The runbook tells you which variables to set and where.

  2. Call tasks — Once the context and variables are in place, the runbook has you run taskfile commands (e.g. task vm:instantiate, task tc:instantiate, task device:write-talos-disk). Those tasks read from the current Windsor context and variables, so they behave consistently without you having to remember flags or one-off commands.

So every runbook is: configure the context and variables for this deployment, then run the tasks that use them. The details (which context, which variables, which tasks) change by runbook; the pattern stays the same.

Workspace Prerequisites

All runbooks assume you're starting with a working workspace that has been initialized and set up for running the Windsor CLI. This means:

  • The workspace structure has been created with the proper directory layout
  • Windsor CLI has been initialized with a context configuration
  • The workspace is ready to execute Windsor CLI commands and taskfiles

If you're starting fresh or need to set up a new workspace, you'll need to complete these foundational steps first:

  • Initialize Workspace: Step-by-step guide for creating and initializing a new workspace with Windsor CLI. This is typically the first step when starting a new project.

  • Secrets Management: Complete guide for managing encrypted secrets using SOPS. You'll likely need this runbook frequently as you work with different deployments that require secure credential management.

For more information about Windsor CLI, including installation and detailed documentation, see the Windsor CLI documentation.

Available Runbooks

🚀 Initialize Workspace

Step-by-step guide for initializing a new workspace using the workspace initialization task and Windsor CLI. This is typically the first step when starting a new project, covering workspace structure creation, directory setup, and Windsor CLI initialization with proper context configuration.

🔐 Secrets Management

Complete guide for managing encrypted secrets using SOPS (Secrets Operations). Learn how to generate, encrypt, decrypt, and manage secrets within your workspace contexts, including integration with Windsor CLI.

🐳 IncusOS Server

Complete guide for installing and configuring IncusOS on Intel NUC devices. Covers BIOS configuration, Secure Boot setup, boot media preparation using the IncusOS customizer, installation process, and connecting to the Incus server via CLI. This is the foundational setup required before using any other IncusOS runbooks.

☸️ Talos Kubernetes Cluster

Deploy a Talos Linux Kubernetes cluster using Infrastructure as Code with Terraform and the Incus provider. This approach uses Terraform to manage your cluster declaratively, making it easy to version control, reproduce, and manage your infrastructure. Includes workspace setup, environment variable configuration, Terraform variable generation, Talos image download and import, network bridge creation, Terraform initialization and application, IP address management, kubeconfig retrieval, and cluster verification. Also covers cluster destruction and management procedures.

🐧 Ubuntu Virtual Machines

Create and manage Ubuntu virtual machines on a remote IncusOS server. This runbook covers creating generic VMs, development VMs, and GitHub Actions runner VMs. All are just named instances of Ubuntu VMs created using the vm: task namespace. Includes workspace initialization, Terraform-based VM creation, developer tools installation, Docker setup, SSH configuration for direct network access, workspace syncing capabilities, and VM lifecycle management. Provides isolated, persistent Ubuntu environments with direct SSH access from your local network, suitable for development work, CI/CD runners, or any other workload.

📱 Application Deployment

Complete guides for deploying self-hosted applications and services. Each runbook provides end-to-end deployment workflows from initial setup through ongoing management.

🔧 Bootstrapping Nodes

Instructions for bootstrapping Talos clusters and Operating Systems to prepar devices for deployment, including image preparation and initial configuration.

Complete guide for installing and configuring Ubuntu on Intel NUC devices, including BIOS configuration, boot media preparation, installation process, and post-installation setup for development and server workloads.

🏃 Self-Hosted GitHub Actions Runners

Step-by-step guides for setting up self-hosted GitHub Actions runners on various platforms. These runbooks cover installing and configuring runners on different operating systems, enabling you to run CI/CD workflows on your own infrastructure.

  • VM Runner Setup: Deploy a GitHub Actions runner on an Ubuntu VM running on IncusOS. Leverages the standard VM creation workflow for consistent, manageable runner deployments. Recommended for most use cases.
  • Bare Metal Runner Setup: Set up Ubuntu-based GitHub Actions runners on bare metal Raspberry Pi (ARM64) or Intel NUC (x86_64) devices. Covers Ubuntu Server installation, post-installation configuration, and runner setup.

Getting Started

  1. Review the prerequisites: Ensure you have all required tools installed by following the Installation Guide

  2. Choose a runbook: Select a runbook that matches your needs

  3. Follow step-by-step: Each runbook provides detailed instructions from initial setup through final deployment

  4. Customize as needed: Once you understand the pattern, adapt it to your specific requirements

Tips for Success

  • Read the entire runbook first: Understanding the full process before starting helps avoid common pitfalls
  • Follow steps in order: Each step builds on the previous one
  • Check prerequisites: Ensure all required tools and access are available before beginning
  • Test incrementally: Verify each step works before moving to the next

Getting Help