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.

It was simple and free, but it didn’t really feel like it was mine.

I’ve fixed that with a Raspberry Pi.

Why leave GitHub Pages?

GitHub Pages is excellent at what it does.

You upload the code for your site to GitHub and they will build and host it for you.
All for free.

So why leave?

Independence

GitHub is owned by Microsoft, one of the biggest companies on the planet.

I have no problem with Microsoft, or using their economies of scale to do something for free that would otherwise cost me money, but ultimately I didn’t feel very indie hosting my site on something I didn’t control.

Sovereignty

GitHub and Microsoft are companies based in the USA, and those of us in Europe are re-considering our dependence on US tech.

Moving has brought my website closer to home - physically, legally, and ethically.

Portability

The work to move from GitHub Pages to anything else has also made it easier to move it all again to another provider, should I ever choose to do so.

I’ve taken the script to build the site out of GitHub Actions and made it part of the code itself. This decouples the site from any specific CI platform and makes both hosting and deployment replaceable.

What it now runs on

There’s no good reason for using a Raspberry Pi for this, I just thought it would be cool.

It is some of the cheapest hosting I could find from a UK-based provider, but there are cheaper options and hosting in Europe works just the same and is even cheaper.

The Pi is from Mythic Beasts , a UK company based in Cambridge. It lives in London and runs on green energy .

I provision it with Terraform, which lets me write the Pi down as code, and then I configure it using Ansible, another tool that sets up the software it runs.

Ansible installs and manages Caddy, which is a web server that has been configured to serve my site.

Deployment is still handled by GitHub Actions but now it goes to the Pi instead of Pages.

From the outside it all works exactly the same, but now it’s on hardware I control, with a setup that’s more portable than it was before.

Under the hood

To make this all possible I ended up writing more code than I set out to.

There wasn’t a Terraform provider for Mythic Beasts, so I wrote one .

For that to work it needed a client to talk to their APIs, so I wrote that too .

And to set up Caddy using Ansible I wrote my own role . There were already others that did this but none of them did exactly what I wanted, so I made my own.

None of this was really required, I could have moved to the Pi without writing any code, but the change from a manual setup to an automated one - driven by code - has forced me to treat the infrastructure of my website as a real system, that can change and evolve over time.

What this means

As a result my setup is now reproducible, portable and more independent.

I can see all the parts that make up my infrastructure and swap them out for alternatives. I’m not tied down to a provider I can replace with a few lines of code.

And ultimately, there’s no difference to visitors of the site, who still get the same experience as before.

What comes next

Through doing this I can see that I might also be able to move my domain from Cloudflare to Mythic Beasts, another win for sovereignty.

If I did that, and moved the code hosting away from GitHub, I’d have a website that’s fully independent.

But that’s for another time.

Over the next few posts I’ll go over:

• how to use the Ansible role
• making a provider for Terraform
• the code that ties it all together
• the site that explains it all in-depth

Now

For now this post marks that this site’s no longer hosted by GitHub Pages.

It’s on a tiny computer, closer to home, set up by my own code.

That feels a bit more mine.

A documentation site for the infrastructure that runs paultibbetts.uk.

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.