Forge Home

Modules

Puppet

Resources

PuppetEcosystemPuppet CommunityUpdates

hx_website

Module to configure Apache and Let's Encrypt for a single website.
Project URLRSS FeedReport issues

9,096 downloads

6,285 latest version

4.6 quality score

We run a couple of automated
scans to help you access a
module's quality. Each module is
given a score based on how well
the author has formatted their
code and documentation and
modules are also checked for
malware using VirusTotal.

Please note, the information below
is for guidance only and neither of
these methods should be considered
an endorsement by Puppet.

Support the Puppet Community by contributing to this module

You are welcome to contribute to this module by suggesting new features, currency updates, or fixes. Every contribution is valuable to help ensure that the module remains compatible with the latest Puppet versions and continues to meet community needs. Complete the following steps:

  1. Review the module’s contribution guidelines and any licenses. Ensure that your planned contribution aligns with the author’s standards and any legal requirements.
  2. Fork the repository on GitHub, make changes on a branch of your fork, and submit a pull request. The pull request must clearly document your proposed change.

For questions about updating the module, contact the module’s author.

Version information

  • 1.0.6 (latest)
  • 1.0.5
  • 1.0.4
  • 1.0.3
  • 1.0.2
  • 1.0.1
  • 1.0.0
released Nov 24th 2017
This version is compatible with:

Start using this module

  • r10k or Code Manager
  • Bolt
  • Manual installation
  • Direct download

Add this module to your Puppetfile:

mod 'pieterdp-hx_website', '1.0.6'
Learn more about managing modules with a Puppetfile

Add this module to your Bolt project:

bolt module add pieterdp-hx_website
Learn more about using this module with an existing project

Manually install this module globally with Puppet module tool:

puppet module install pieterdp-hx_website --version 1.0.6

Direct download is not typically how you would use a Puppet module to manage your infrastructure, but you may want to download the module in order to inspect the code.

Download

Documentation

pieterdp/hx_website — version 1.0.6 Nov 24th 2017

hx_website

Table of Contents

  1. Description
  2. Setup
  3. Usage
  4. Reference
  5. Limitations
  6. Development

Description

Setting up websites is a time-consuming process. This module attempts to make it easier by preconfiguring the Apache HTTP Web Server and optionally configuring the website to use Let's Encrypt certificates.

This module will install and configure the Apache web server and configure any website you define using hx_website::website by creating a new name-based Virtual Host. Optionally, it will also take care of installing new Let's Encrypt certificates.

Setup

What hx_website affects

  • This module uses the puppetlabs-apache-module, so it will automatically purge all (Apache) configuration files not managed by Puppet. It will not be possible to create your own Virtual Hosts, unless you disable the module first.

Beginning with hx_website

The module consists of two parts: hx_website which will do some configuration checks and hx_website::website which will configure your website.

The most simple configuration is:

class {'hx_website': }

Creating a website is done by using the defined type hx_website::website:

hx_website::website { 'www.example.org':
    vhost_data => {
        servername    => 'www.example.org',
        port          => '80',
        docroot       => '/var/www/www.example.org/html',
        docroot_owner => 'www-data',
        docroot_group => 'www-data',

    }
}

This will configure an Apache Virtual Host listening on port 80 for any requests to www.example.org, using /var/www/www.example.org/html as docroot.

Usage

Virtual Hosts

vhost_data is passed directly to apache::vhost. All valid parameters for that class can appear in vhost_data.

hx_website::website creates name-based virtual hosts. Two websites can have the same vhost_data['servername'], provided the vhost_data['port'] parameter is different. This can be used to create two hx_website::website, one HTTP version that redirects to a HTTPS version. This can be done automatically however.

SSL

To configure SSL-based virtual hosts, you can set either use_letsencrypt to true (see below) or provide the certificates manually. Note that, if you set use_letsencrypt, it will only request certificates when it encounters vhost_data['port'] == 443.

In a lot of cases, you want to redirect any traffic for the non-encrypted site (e.g. http://www.example.org) to the encrypted one (i.e. https://www.example.org). This can be done automatically, if you set configure_redirect to true. A new Virtual Host will be created which will redirect all non-encrypted traffic to a HTTPS-version of the vhost_data['servername'] parameter.

Let's Encrypt

It is possible to automatically configure Let's Encrypt, but it comes with some caveats.

After you enable use_letsencrypt, but before your first run, you must provide a certificate (it can be the snake-oil certificate) at the location you specified in vhost_data (on the client). Otherwise, the Apache web server won't start and letsencrypt will fail because it can't check your secret. After the first run and after the certificate has been assigned, it will automatically use the Let's Encrypt-provided one.

Reference

Class hx_website

The base class, that must be included and/or configured before you can use hx_website::website.

Parameters

  • configure_redirect (default false): if you provide a website that is HTTPS (port 443), should we create a redirect from the HTTP version to the HTTPS version.

  • maintainer (default hostname@domain): required for Let's Encrypt: an email address to send expiration notices to. Set this to a working email address if you want to receive them, keep at the default if that isn't necessary.

  • set_default_headers (default false): insert the always set Referrer-Policy "strict-origin-when-cross-origin" and always set Strict-Transport-Security "max-age=63072000;includeSubdomains;" (only for HTTPS hosts) headers.

  • set_default_docroot (default false): automatically insert the <Directory> configuration for the docroot. Sets Indexes, FollowSymLinks and AllowOverride All.

Defined type hx_website::website

Configure a website. It will configure an apache Virtual host, and optionally configure Let's Encrypt. Note that you must have a temporary certificate in place at vhost_data['ssl_cert'] and vhost_data['ssl_key'] before you attempt to run Puppet if you want a Let's Encrypt certificate. This is because the webserver must be running before a certificate can be requested, and the server will only run if the certificate referred to in the configuration file is already present.

If you don't want Let's Encrypt, you can provide your own certificate. This can be either a certificate present on the Puppet master (recommended) or one on the client. Use cert_loc and key_loc to specify where it is. Both parameters accept the same settings the source parameter of the file type uses (as cert_loc and key_loc are passed directly to file->source, this should not come as a surprise). If you specified vhost_data['ssl_ca'], you can specify ca_loc, which will then be used to copy the CA certificate to the ca_loc location.

Parameters

  • vhost_data: hash of key-value pairs that is passed directly to apache::vhost. Must contain all required parameters for apache::vhost and can contain aything this module accepts. It must contain a servername and port parameter for hx_website::website to function however. If you use SSL, you must use port 443 and set ssl_cert and ssl_key (and even optionally ssl_ca).

  • use_letsencrypt (default: false): request a Let's Encrypt certificate. A certificate must be present on the system before requesting a new certificate. Renewal is handled automatically. The root certificate is downloaded, but if you want to use it with your website, you must set vhost_data['ssl_ca'] to /etc/ssl/certs/lets-encrypt-x3-cross-signed.pem.

  • cert_loc (optional, required only if use_letsencrypt is set to false and vhost_data['port'] is set to 443): location of the certificate file that will be copied to the location referred to in vhost_data['ssl_cert']. Accepts the same syntax as file->source.

  • key_loc (optional, required only if use_letsencrypt is set to false and vhost_data['port'] is set to 443): location of the key file that will be copied to the location referred to in vhost_data['ssl_key']. Accepts the same syntax as file->source.

Under-the-hood classes

  • hx_website::config::vhost: backend class for hx_website::website. Accepts the same parameters.

  • hx_website::config::ssl::letsencrypt: configure Let's Encrypt. Accepts no parameters.

Limitations

This module was tested on Ubuntu 14.04, but should work with all Ubuntu versions. Only works for Apache >= 2.4.

Development

Pull requests welcome at https://github.com/pieterdp/hx_website.