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 documentation site for the infrastructure that runs paultibbetts.uk.

An Ansible role to install and operate Caddy web server.

Using both of them together, with a dynamic inventory to link them, has been technically possible for years but never obvious enough for me to work out.

Until I found the Terraform provider.

Ansible provider for Terraform

By using the Ansible provider you can teach Terraform what an Ansible inventory entry would look like next to the rest of its code.

You start by defining the provider:

terraform {
  required_providers {
    ansible = {
      source  = "ansible/ansible"
      version = "1.3.0"
    }
  }
}

and then you can define the Ansible inventory entry right next to the resource:

resource "proxmox_vm_qemu" "gitea" {
  cores = 1
	...
}

resource "ansible_host" "gitea" {
  name   = proxmox_vm_qemu.gitea.ssh_host
  groups = ["gitea"]
  variables = {
    ansible_user = "ansible"
  }
}

which means you don’t need to hardcode IP addresses anywhere.

You would need to terraform apply this plan so that Terraform adds these resources to the state file so that Ansible can use them.

Terraform plugin for Ansible

On the Ansible side you use a plugin to tell it how to use Terraform as its inventory.

Add the following to your requirements.yaml file:

collections:
  - name: cloud.terraform
    version: 1.1.0

and then install the collection using ansible-galaxy collection install -r requirements.yaml,

then create an inventory.yaml with the following content:

plugin: cloud.terraform.terraform_provider
# project_path: ../terraform # if your Terraform code is in a different directory
# state_file: mycustomstate.tfstate # if you wanted to define which state file

and set it as the default inventory in ansible.cfg:

[defaults]
inventory = inventory.yaml

You can confirm the plugin works by doing:

ansible-inventory --graph

which should return something like the following:

@all:
  |--@ungrouped:
  |--@gitea:
  |  |--192.168.1.211

🎉

What’s good about this is now you can be hands-off with IP addresses.

Terraform can request a new machine, wait for it to receive an IP address and then make it available for Ansible to use, without you needing to do anything.

Remote state

The Ansible plugin will default to using whichever backend you use for the Terraform state file, whether that’s local or in an S3-compatible location.

This means Ansible is always running against the current infrastructure, which helps when colleagues and automations are updating things a hundred thousand times a day.

In Conclusion

Using Terraform and Ansible together can cover all aspects of Infrastructure as Code.

The Ansible provider lets you keep all your resource code together in Terraform and then makes it available to Ansible, which uses a plugin to let it use the state file as its inventory.