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.
- 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.
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.
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.
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.
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.
The base class, that must be included and/or configured before you can use hx_website::website
.
-
configure_redirect
(defaultfalse
): if you provide a website that is HTTPS (port 443), should we create a redirect from the HTTP version to the HTTPS version. -
maintainer
(defaulthostname@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
(defaultfalse
): insert thealways set Referrer-Policy "strict-origin-when-cross-origin"
andalways set Strict-Transport-Security "max-age=63072000;includeSubdomains;"
(only for HTTPS hosts) headers. -
set_default_docroot
(defaultfalse
): automatically insert the<Directory>
configuration for the docroot. SetsIndexes
,FollowSymLinks
andAllowOverride All
.
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.
-
vhost_data
: hash of key-value pairs that is passed directly toapache::vhost
. Must contain all required parameters forapache::vhost
and can contain aything this module accepts. It must contain aservername
andport
parameter forhx_website::website
to function however. If you use SSL, you must use port 443 and setssl_cert
andssl_key
(and even optionallyssl_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 setvhost_data['ssl_ca']
to/etc/ssl/certs/lets-encrypt-x3-cross-signed.pem
. -
cert_loc
(optional, required only ifuse_letsencrypt
is set tofalse
andvhost_data['port']
is set to443
): location of the certificate file that will be copied to the location referred to invhost_data['ssl_cert']
. Accepts the same syntax asfile
->source
. -
key_loc
(optional, required only ifuse_letsencrypt
is set tofalse
andvhost_data['port']
is set to443
): location of the key file that will be copied to the location referred to invhost_data['ssl_key']
. Accepts the same syntax asfile
->source
.
-
hx_website::config::vhost
: backend class forhx_website::website
. Accepts the same parameters. -
hx_website::config::ssl::letsencrypt
: configure Let's Encrypt. Accepts no parameters.
This module was tested on Ubuntu 14.04, but should work with all Ubuntu versions. Only works for Apache >= 2.4.
Pull requests welcome at https://github.com/pieterdp/hx_website.