From eace82a56dfb225f87ea14daf5bd86ca8e9eec00 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 14 Nov 2019 13:13:26 -0800 Subject: [PATCH 1/2] Add example of using certbot and Let's Encrypt for Deployment via Ansible --- deployment/customization.rst | 47 +++++++++++++++++++++++++++++++++++- 1 file changed, 46 insertions(+), 1 deletion(-) diff --git a/deployment/customization.rst b/deployment/customization.rst index b8ec755a5..1f27ad425 100644 --- a/deployment/customization.rst +++ b/deployment/customization.rst @@ -187,7 +187,8 @@ Alternatively, you could specify use of certificates already on the server: Log in and delete it if needed. Yes, this is an exception to the "don't login to change configuration rule". -**Extra tricks** +Extra tricks +^^^^^^^^^^^^ There are a couple of extra setting that allow you to do extra customization if you know nginx directives. For example: @@ -202,6 +203,50 @@ This is a *redirect to https*. It takes advantage of the fact that if you do not specify a zodb_path, the playbook will not automatically create a location stanza with a rewrite and proxy_pass directives. + +.. _letsencrypt_certbot: + +Let's Encrypt Certificates and certbot +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +All websites should use TLS. +We use an Ansible role that will automatically install `certbot `_, a free secure certificate from `Let's Encrypt `_, and create a cron job that will automatically renew the certificate. +This role is installed from ``requirements.yml``. + +To use the role, you will need to add the following variables to your ``local-configure.yml`` and substitute your values as needed. + +.. code-block:: yaml + + # https://github.com/geerlingguy/ansible-role-certbot#role-variables + # override roles/geerlingguy.certbot/defaults/main.yml + certbot_create_if_missing: true + certbot_admin_email: email@example.com + certbot_certs: + - domains: + - "{{ inventory_hostname }}" + + webserver_virtualhosts: + - hostname: "{{ inventory_hostname }}" + port: 80 + protocol: http + extra: return 301 https://$server_name$request_uri; + - hostname: "{{ inventory_hostname }}" + default_server: yes + zodb_path: /Plone + address: 1.1.1.1 + port: 443 + protocol: https + lets_encrypt_certificate: + key: /etc/letsencrypt/live/{{ inventory_hostname }}/privkey.pem + crt: /etc/letsencrypt/live/{{ inventory_hostname }}/fullchain.pem + +The above configuration redirects all traffic from http to https, using the ``extra`` key mentioned earlier. + +.. seealso:: + + `Read documentation of the role geerlingguy.certbot `_. + + Mail Relay ---------- From c9f55c186414ca7f94b003c6b17498250494d74d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 17 Nov 2019 11:33:42 -0800 Subject: [PATCH 2/2] Move example of using certbot and Let's Encrypt to a separate file - add cross-references --- deployment/customization.rst | 50 ++++---------------------- deployment/letsencrypt-certbot.rst | 58 ++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+), 43 deletions(-) create mode 100644 deployment/letsencrypt-certbot.rst diff --git a/deployment/customization.rst b/deployment/customization.rst index 1f27ad425..52035929d 100644 --- a/deployment/customization.rst +++ b/deployment/customization.rst @@ -120,6 +120,8 @@ If you're conservative, you'll first try starting and stopping the reserved clie You don't need to worry that an automated restart might occur after a failed buildout. +.. _web-hosting-options: + Web Hosting Options ------------------- @@ -187,6 +189,11 @@ Alternatively, you could specify use of certificates already on the server: Log in and delete it if needed. Yes, this is an exception to the "don't login to change configuration rule". +.. seealso:: + + For an example of using free Let's Encrypt certificates with certbot and auto-renewal, see :doc:`letsencrypt-certbot`. + + Extra tricks ^^^^^^^^^^^^ @@ -204,49 +211,6 @@ It takes advantage of the fact that if you do not specify a zodb_path, the playbook will not automatically create a location stanza with a rewrite and proxy_pass directives. -.. _letsencrypt_certbot: - -Let's Encrypt Certificates and certbot -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -All websites should use TLS. -We use an Ansible role that will automatically install `certbot `_, a free secure certificate from `Let's Encrypt `_, and create a cron job that will automatically renew the certificate. -This role is installed from ``requirements.yml``. - -To use the role, you will need to add the following variables to your ``local-configure.yml`` and substitute your values as needed. - -.. code-block:: yaml - - # https://github.com/geerlingguy/ansible-role-certbot#role-variables - # override roles/geerlingguy.certbot/defaults/main.yml - certbot_create_if_missing: true - certbot_admin_email: email@example.com - certbot_certs: - - domains: - - "{{ inventory_hostname }}" - - webserver_virtualhosts: - - hostname: "{{ inventory_hostname }}" - port: 80 - protocol: http - extra: return 301 https://$server_name$request_uri; - - hostname: "{{ inventory_hostname }}" - default_server: yes - zodb_path: /Plone - address: 1.1.1.1 - port: 443 - protocol: https - lets_encrypt_certificate: - key: /etc/letsencrypt/live/{{ inventory_hostname }}/privkey.pem - crt: /etc/letsencrypt/live/{{ inventory_hostname }}/fullchain.pem - -The above configuration redirects all traffic from http to https, using the ``extra`` key mentioned earlier. - -.. seealso:: - - `Read documentation of the role geerlingguy.certbot `_. - - Mail Relay ---------- diff --git a/deployment/letsencrypt-certbot.rst b/deployment/letsencrypt-certbot.rst new file mode 100644 index 000000000..1e13d94a1 --- /dev/null +++ b/deployment/letsencrypt-certbot.rst @@ -0,0 +1,58 @@ +.. _letsencrypt_certbot: + +====================================== +Let's Encrypt Certificates and certbot +====================================== + +All websites should use TLS. +We use an Ansible role that will automatically install `certbot `_, a free secure certificate from `Let's Encrypt `_, and create a cron job that will automatically renew the certificate. + +Installation +============ + +You need to install the role. + +.. code-block:: bash + + cd ansible-playbook + git clone https://github.com/geerlingguy/ansible-role-certbot.git geerlingguy.certbot + + +Configuration +============= + +To use the role, you need to add the following variables to your ``local-configure.yml``, and substitute your values as needed. + +.. code-block:: yaml + + # https://github.com/geerlingguy/ansible-role-certbot#role-variables + # override roles/geerlingguy.certbot/defaults/main.yml + certbot_create_if_missing: true + certbot_admin_email: email@example.com + certbot_auto_renew_options: '--quiet --no-self-upgrade + --pre-hook "service nginx stop" --post-hook "service nginx start"' + + certbot_certs: + - domains: + - "{{ inventory_hostname }}" + + webserver_virtualhosts: + - hostname: "{{ inventory_hostname }}" + port: 80 + protocol: http + extra: return 301 https://$server_name$request_uri; + - hostname: "{{ inventory_hostname }}" + default_server: yes + zodb_path: /Plone + address: 1.1.1.1 + port: 443 + protocol: https + certificate: + key: /etc/letsencrypt/live/{{ inventory_hostname }}/privkey.pem + crt: /etc/letsencrypt/live/{{ inventory_hostname }}/fullchain.pem + +The above configuration redirects all traffic from http to https, using the ``extra`` key mentioned in :ref:`web-hosting-options`. + +.. seealso:: + + `Read documentation of the role geerlingguy.certbot `_.