harmy/caddy-ansible

Ansible role for installing and configuring the Caddy web server

Caddy Ansible Role

• Dependencies
• Role Variables
  • The Caddyfile
  • The OS to download caddy for
  • The type of license to use
  • Auto update Caddy?
  • Additional Available Features
  • Use setcap?
  • Verify the PGP signature on download?
  • Use systemd capabilities controls
  • Add additional environment variables
  • Use additional CLI arguments
  • Use a GitHub OAuth token to request the list of caddy releases
• Example Playbooks
• Debugging
• Contributing

This role installs and configures the caddy web server. The user can specify any http configuration parameters they wish to apply their site. Any number of sites can be added with configurations of your choice.

Dependencies

None

Role Variables

The Caddyfile

See Caddyfile docs. Notice the | used to include a multi-line string.

default:

caddy_config: |
  http://localhost:2020
  respond "Hello, world!"

If you wish to use a template for the config you can do this:

caddy_config: "{{ lookup('template', 'templates/Caddyfile.j2') }}"

The OS to download caddy for

default:

caddy_os: linux

The type of license to use

default:

caddy_license: personal

If you set the license type to commercial then you should also specify (replacing the dummy values with your real ones):

caddy_license_account_id: YOUR_ACCOUNT_ID
caddy_license_api_key: YOUR_API_KEY

Auto update Caddy?

default:

caddy_update: true

Additional Available Packages

Changing this variable will reinstall Caddy with the new packages if caddy_update is enabled. Check https://caddyserver.com/download for available packages.

default:

caddy_packages: []

Use setcap?

This allows Caddy to open a low port (under 1024 - e.g. 80, 443).

default:

caddy_setcap: true

Verify the PGP signature on download?

default:

caddy_pgp_verify_signatures: false

Use systemd capabilities controls

default:

caddy_systemd_capabilities_enabled: false
caddy_systemd_capabilities: "CAP_NET_BIND_SERVICE"

NOTE: This feature requires systemd v229 or newer and might be needed in addition to caddy_setcap: yes.

Supported:

• Debian 9 (stretch)
• Fedora 25
• Ubuntu 16.04 (xenial)

RHEL/CentOS has no release that supports systemd capability controls at this time.

Add additional environment variables

Add environment variables to the systemd script.

default:

caddy_environment_variables: {}

Example usage:

caddy_environment_variables:
  FOO: bar
  SECONDVAR: spam

Use additional CLI arguments

default:

caddy_additional_args: ""

Example for LetsEncrypt staging:

caddy_additional_args: "-ca https://acme-staging.api.letsencrypt.org/directory"

Use a GitHub OAuth token to request the list of caddy releases

This role uses the GitHub releases list to check when a new version is available. GitHub has some fairly agressive rate-limiting which can cause failures. You can set your GitHub token to increase the limits for yourself when running the role (e.g. if deploying many servers behind a NAT or running this role repeatedly as part of a CI process).

default:

caddy_github_token: ""

Example Playbooks

---
- hosts: all
  roles:
    - role: caddy-ansible
      caddy_config: |
        localhost:2020
        gzip

        tls email@example.com

        root /var/www
        git github.com/antoiner77/caddy-ansible

Example with Cloudflare DNS for TLS:

---
- hosts: all
  roles:
    - role: caddy-ansible
      caddy_features: tls.dns.cloudflare
      caddy_environment_variables:
        CLOUDFLARE_EMAIL: your@email.com
        CLOUDFLARE_API_KEY: 1234567890
      caddy_config: |
        yourcloudflareddomain.com {
            tls {
                dns cloudflare
            }

            gzip

            root /var/www
            git github.com/antoiner77/caddy-ansible
        }

Debugging

If the service fails to start you can figure out why by looking at the output of Caddy.

systemctl status caddy -l

If something doesn't seem right, open an issue!

Contributing

Pull requests are welcome. Please test your changes beforehand with vagrant:

vagrant up
vagrant provision   # (since it already provisioned there should be no changes here)
vagrant destroy