Puppet module for Caddy

Table of Contents

1. Description
2. Setup - The basics of getting started with Caddy
   • What Caddy affects
   • Setup requirements
   • Beginning with Caddy
3. Usage - Configuration options and additional functionality
4. Limitations - OS compatibility, etc.
5. Development - Guide for contributing to the module

Description

This module installs and configures Caddy - The HTTP/2 web server with automatic HTTPS.

Important: This module only supports the installation of Caddy 2.x. If you want to install Caddy 1.x, you should use version v2.0.0 of this module.

Setup

What Caddy affects

• Caddy binary
• Caddy configuration file
• Caddy virtual hosts
• Caddy service

Setup Requirements

This module has the following dependencies:

• puppet/systemd
• puppet/archive
• puppetlabs/stdlib

When install_method is set to 'repo', this module implicitly requires either puppetlabs-apt module for Debian distro family, or puppet-yum module for RedHat distro family.

Beginning with Caddy

Install Caddy without any configuration:

include caddy

Usage

Install customized version of Caddy

class { 'caddy':
  caddy_features => 'http.git,http.filter,http.ipfilter',
}

Install specific version of Caddy

class { 'caddy':
  version        => '2.0.0',
  install_method => 'github',
}

Install Caddy and configure virtual host, based on source:

caddy::vhost { 'example1':
  source => 'puppet:///modules/caddy/etc/caddy/config/example1.conf',
}

Install Caddy and configure virtual host, based on content:

caddy::vhost { 'example2':
  content => 'localhost:2015',
}

Use apache-like configuration files layout:

class { 'caddy':
  config_dir => '/etc/caddy/conf-available',
  config_enabled_dir => '/etc/caddy/conf-enabled',
  vhost_dir => '/etc/caddy/sites-available',
  vhost_enable_dir => '/etc/caddy/sites-enabled',
  config_files => {
    admin_port_2020 => {
      content => "{\n  admin localhost:2020\n}\n",
    },
  },
  vhosts => {
    port_3000 => {
      content => "http://localhost:3000 {\n  respond \\"port 3000\\"\n}\n",
    },
    port_3001 => {
      ensure => 'disabled',
      content => "http://localhost:3001 {\n  respond \\"port 3001\\"\n}\n",
    }
  }
}

Same as above but configured in Hiera:

caddy::config_dir: /etc/caddy/conf-available
caddy::config_enable_dir: /etc/caddy/conf-enabled
caddy::vhost_dir: /etc/caddy/sites-available
caddy::vhost_enable_dir: /etc/caddy/sites-enabled
caddy::config_files:
  admin_port_2020:
    content: |
      {
        admin localhost:2020
      }
caddy::vhosts:
  port_3000:
    content: |
      http://localhost:3000 {
        respond "port 3000"
      }
  port_3001:
    ensure: disabled
    content: |
      http://localhost:3001 {
        respond "port 3001"
      }

You may consider setting following parameters also. This allows enabling/disabling config files and virtual hosts manually.

caddy::purge_config_enable_dir: false
caddy::purge_vhost_enable_dir: false

Reference

The reference documentation of this module is generated using puppetlabs/puppetlabs-strings.

Limitations

This module has been tested on:

• AlmaLinux 8/9
• CentOS 9
• Debian 11/12
• OracleLinux 8/9
• RedHat 8/9
• Rocky 8/9
• Ubuntu 20.04/22.04/24.04

For the official list of all tested distributions, please take a look at the metadata.json

Development

This module has grown over time based on a range of contributions from people using it. If you follow these contributing guidelines your patch will likely make it into a release a little more quickly.

Author

This module is maintained by Vox Pupuli. It was originally written and maintained by Lukasz Rohde.