I use it to provision the infrastructure for my personal website.

This is why I built it, what it does, and how to use it.

Why I built it

I prefer writing down my infrastructure as code. It’s something I’ve been doing for years now, and I don’t think I could go back to doing things manually, no matter how small or simple the setup.

I’d decided to use a Pi from Mythic Beasts to host my site and saw that they had APIs available, but no Terraform provider.

Terraform is a tool I’ve been using for infrastructure for a while now, and I wanted to use it with Mythic Beasts because:

• I wanted a fully reproducible setup
• I didn’t want to click around the control panel
• their Pis are IPv6-only, so I’d need to also set up the proxy
• • I wanted to declare the Pi and the endpoints for the proxy in the same place

Plus, I’d never written a Terraform provider before, and I wanted to see what it was like.

What it does

Terraform is a tool for writing your infrastructure as code, and a provider is a plugin that lets it work with different infrastructure providers.

For example you can write:

terraform {
  required_version = ">= 1.11.0"

  required_providers {
    mythicbeasts = {
      source = "paultibbetts/mythicbeasts"
    }
  }
}

resource "mythicbeasts_pi" "pi" {
	identifier   = "web"
	disk_size    = 10
	model        = 4
	memory       = 4096
	os_image     = "rpi-bookworm-arm64"
    ssh_key      = "ssh-ed25519 ..."
    wait_for_dns = true
}

then run terraform apply, and you would get a Raspberry Pi 4 from Mythic Beasts.

Resources

The provider uses the Mythic Beasts APIs to configure the following resources:

• VPS
• Raspberry Pi
• Proxy endpoint

The Raspberry Pis from Mythic Beasts are on an IPv6-only network, so the Proxy endpoints are to allow users trying to access from an IPv4-only network.

Data sources

Some of the settings for the resources require specific values, like the os_image to use, and data sources make it easy to get this info from the API.

For example, the mythicbeasts_pi_operating_systems data source can be used to get all valid os_image values for a Raspberry Pi 4:

data "mythicbeasts_pi_operating_systems" "four" {
  model = 4
}

where you would inspect the data to choose the right value to use.

Alternatively you could use Terraform to find the right value for you, for example to use “Bookworm” for “Arm64”:

data "mythicbeasts_pi_operating_systems" "four" {
  model = 4
}

locals {
  bookworm_arm64 = one([
    for image in data.mythicbeasts_pi_operating_systems.four.images :
    image.id
    if strcontains(image.id, "bookworm") &&
    strcontains(image.id, "arm64")
  ])
}

resource "mythicbeasts_pi" "bookworm" {
  model    = 4
  os_image = local.bookworm_arm64
  ...
}

where Terraform will find the image with both “bookworm” and “arm64” in the ID.

Attributes

Using Terraform for your infrastructure not only lets you write it down as code, with all the benefits that brings , but you can use the attributes of one thing as inputs for another.

For example: the Pis from Mythic Beasts are on an IPv6-only network and need endpoints set up on the proxy to let users access them from IPv4-only networks.

To do this you can get the attribute from a Pi, like the IP address, and then use that as the input for the proxy endpoint resource:

locals {
  domain = "example.com"
  subdomains = {
    apex  = "@"
    www   = "www"
  }
}

resource "mythicbeasts_pi" "web" {
	identifier   = "web"
	disk_size    = 10
	model        = 4
	memory       = 4096
	os_image     = "rpi-bookworm-arm64"
    ssh_key      = "ssh-ed25519 ..."
    wait_for_dns = true
}

resource "mythicbeasts_proxy_endpoint" "endpoint" {
  for_each = local.subdomains

  domain         = local.domain
  hostname       = each.value
  address        = mythicbeasts_pi.web.ip
  site           = "all"
  proxy_protocol = true
}

How to use it

The provider is available on the Terraform registry .

Authentication

The Mythic Beasts APIs require an API key for authentication.

When creating the key you must add permissions to work with the APIs you wish to use, such as:

• “Virtual Server Provisioning” for VPS
• “Raspberry Pi provisioning” for Pis
• “IPv4 to IPv6 Proxy API” for Proxy endpoints

Proxy endpoint domain management

The domain used for proxy endpoints must be registered with the Mythic Beasts control panel.

This can be done by registering the domain using their domain management or by adding it as a 3rd party domain .

Installation

terraform {
  required_version = ">= 1.11.0"

  required_providers {
    mythicbeasts = {
      source = "paultibbetts/mythicbeasts"
    }
  }
}

provider "mythicbeasts" {
  keyid  = "your-keyid"
  secret = "your-secret"
}

Alternatively, credentials can be supplied via environment variables:

• MYTHICBEASTS_KEYID
• MYTHICBEASTS_SECRET

Examples

Examples of each resource and data source can be found at /examples .

These are also used to generate the documentation hosted by the Terraform registry .

How it works

The provider uses the newer Terraform Plugin Framework .

For it to work with the Mythic Beasts APIs I had to create a Go client, which can be found on GitHub . The client handles the APIs and means that the provider only needs to focus on Terraform itself.

The Mythic Beasts VPS API needs values that are only ever used when creating a VPS and so the provider uses the new write-only arguments feature, which is only available in Terraform v1.11.0 and later. Write-only is normally used for sensitive values like passwords but the VPS API doesn’t return every attribute so write-only is used for these values when creating the VPS and then they are forgotten.

Support

To make it clear, this is an unofficial provider that is not endorsed by Mythic Beasts.

It’s currently at version v0.1 and I wouldn’t consider it stable until it hits v1.0.

Right now it supports the APIs I need it to. Further features will be added as needed.

In use

I use the provider to provision a Raspberry Pi 4 from Mythic Beasts and set up the proxy endpoints for my personal website.

The whole setup, with Terraform to provision the Pi and then Ansible to configure it, is documented at infra.paultibbetts.uk .

What’s next?

The provider works with the VPS, Pi, and Proxy APIs, as these are what I currently use or have used in the past.

Mythic Beasts also have a DNS API which lets you manage the DNS records for domains.

If I were to add this to the provider I could change the management of my domain from Cloudflare over to Mythic Beasts, which would improve my website’s sovereignty .

I use it for my personal site and in my homelab.

This is what it does and how to use it.

What it does

An Ansible role is like a plugin that extends Ansible with the ability to do something, and in this case it’s to install and manage Caddy .

Specifically it:

• installs Caddy
• • defaults to using the apt package manager
• • or it can be given the URL to a specific binary
• • or it can be given a list of plugins
• can be used to manage Caddy
• • or completely uninstall it
• can write the Caddyfile from a template

Why Caddy?

I use Caddy because it manages TLS certificates automatically and, with a plugin, supports DNS-01 challenges .

DNS-01 is useful when services aren’t reachable by Lets Encrypt, like in a homelab, so private networks can also have TLS.

Design goals

The role was designed with the following in mind:

• idempotent and safe to re-run
• Debian and Ubuntu
• works on x86 and ARM
• supports installing with plugins
• can optionally write the Caddyfile

There are already Ansible roles for Caddy, like the one listed in the docs , but I needed a role that could install Caddy with plugins.

How to use it

The role is available on Ansible Galaxy .

Install

You can install it by adding:

- name: paultibbetts.caddy
  version: 1.0.0

to your requirements.yml file and then running:

ansible-galaxy role install -r requirements.yml

Variables

The variables for the role, as well as the default settings, can all be overridden.

The most important ones are the install method, the plugins to include, and whether the role writes the Caddyfile for you.

caddy_install_method: apt

The role defaults to installing Caddy via apt, the package manager for Debian/Ubuntu.

This means Caddy does not include any plugins but it does get updated when you run apt upgrade.

caddy_install_method: download

Alternatively you can change the install method to download.

Now you can pass in the URL of a specific binary using:

caddy_download_url: ""

Using this you could build a binary for Caddy (including plugins), host it, then pass that URL to the role and that specific binary will be installed.

This is currently the only way to install a specific version of Caddy that isn’t “latest”.

If you want to install plugins for Caddy and don’t want to build your own binary you can leave the download URL empty and pass in the plugins:

caddy_plugins:
  - github.com/caddy-dns/cloudflare

and the role will generate a URL from the download page .

caddy_caddyfile_template: "" | "{{ playbook_dir }}/templates/Caddyfile.j2"

The Caddyfile template variable lets you pass in a template of a Caddyfile for Caddy to use and it will be written to the appropriate place.

Letting the role write the Caddyfile means you can import the role, set its variables, and have all of Caddy configured by one thing - you don’t need to write extra tasks after installation to get it up and running.

Examples

The following examples show how the role can be used for a public website and for a private homelab reverse proxy.

In both instances Caddy acquires TLS certificates from Lets Encrypt, using Cloudflare to do DNS-01 challenges.

Example: Personal website

The role can be used to setup Caddy to host a personal website.

- hosts: server
  become: true
  roles:
    - role: paultibbetts.caddy
      vars:
        caddy_caddyfile_template: "{{ playbook_dir }}/templates/Caddyfile.j2"
        caddy_install_method: download
        caddy_plugins:
          - github.com/caddy-dns/cloudflare
        caddy_manage_systemd_env_file: true
        caddy_systemd_env:
          CF_API_TOKEN: "{{ vault_cf_api_token }}"

The download install method is used to install Caddy with the Cloudflare plugin , the Cloudflare API token is passed to Caddy from Ansible vault, and a template is provided for the Caddyfile, which could look like:

(cf_tls) {
    tls {
        dns cloudflare {env.CF_API_TOKEN}
    }
}

{% for site in web_sites %}
{{ site }} {
  import cf_tls
  root * {{ web_sites_root }}/{{ site }}/current
  file_server
  encode zstd gzip
  log
}
{% endfor %}

This sets up Caddy to use Cloudflare to do DNS-01 challenges with Lets Encrypt to get a TLS certificate for each site in web_sites.

Example: Homelab

The role can also be used to setup Caddy in a private network, like a homelab.

- hosts: homelab
  become: true
  roles:
    - role: paultibbetts.caddy
      vars:
        caddy_caddyfile_template: "{{ playbook_dir }}/templates/Caddyfile.j2"
        caddy_install_method: download
        caddy_plugins:
          - github.com/caddy-dns/cloudflare
        caddy_manage_systemd_env_file: true
        caddy_systemd_env:
          CF_API_TOKEN: "{{ vault_cf_api_token }}"

{
        acme_dns cloudflare {env.CF_API_TOKEN}
}

service.homelab.example {
        reverse_proxy <ip>:<port>
}

where the Cloudflare plugin is configured once and is then used to do DNS-01 challenges for any TLS certificates Caddy requests. Note this style has been deprecated and you should do it per host, like the earlier example for a personal website.

DNS-01 challenges are solved by writing a TXT record to prove domain ownership. This means Lets Encrypt is able to issue certificates for domains it can’t reach, which makes DNS-01 ideal when Caddy is running in a homelab.

Molecule Scenarios

Ansible Molecule is a way to run tests for an Ansible role.

The role includes molecule scenarios that test it works on x86 as well as Arm, because I use the role on a Raspberry Pi 4, as well as scenarios for the Cloudflare plugin and the Caddyfile templating.

In use

I use this role as part of the code that sets up the infrastructure for my website.

Terraform is used to provision the server, then Ansible is used to configure it, with this role setting up Caddy and the Caddyfile it uses.

The complete setup - Terraform, Ansible, Caddy, and the rest of the files - is documented at infra.paultibbetts.uk , where I explain how it all fits together.

A Terraform provider for Mythic Beasts.

A client for the Mythic Beasts APIs, written in Go.

An Ansible role to install and operate Caddy web server.