Ansible LetsEncrypt

This is a role to help you automatically manage LetsEncrypt certificates.

Current Status: Beta
Required Ansible Version: 2.x

What It Does

This role installs the official Certbot client and uses it to obtain or renew a certificate for your chosen domain.

Key Features

• Works on Ubuntu 14.04, Debian 8, and Debian 9.
• Allows only one domain per role.
• Operates in certonly mode (no web server installation).

We welcome pull requests with more features!

Installation

To install this role, run:

ansible-galaxy install jaywink.letsencrypt

Details

Certbot Client Info

For Ubuntu 14.04 and Debian 8:

• The client is installed at /opt/certbot as root.
• Each run installs the client from a specific release version. You can specify the version using letsencrypt_certbot_version.

For Debian 9:

• The client is installed via APT in the usual location based on the latest repository version.

Important Notes

• You can configure services to pause before getting a new certificate using letsencrypt_pause_services.
• certonly mode is used, which means no web server is set up automatically.
• After getting the certificate, you can find it in /etc/letsencrypt/live/<domainname>. Use it in your Apache2 configuration, ensuring Apache2 isn't running with an active virtual host until the LetsEncrypt role runs.

SSLCertificateFile /etc/letsencrypt/live/{{ letsencrypt_domain }}/cert.pem
SSLCertificateKeyFile /etc/letsencrypt/live/{{ letsencrypt_domain }}/privkey.pem
SSLCertificateChainFile /etc/letsencrypt/live/{{ letsencrypt_domain }}/chain.pem

• If the role fails while requesting the certificate, it might be due to stopped services.
• If a certificate has been requested previously, it will try to renew it automatically unless you set letsencrypt_force_renew to false.
• It will automatically request a www. subdomain with the certificate. To disable this, set letsencrypt_request_www to false.

Requirements

This role has been tested with:

• Ubuntu 14.04 and Debian 8, 9
• Apache2 and Nginx
• Ansible version 2.x

Role Variables

Required

• letsencrypt_domain: The domain for the certificate.
• letsencrypt_email: Your email for certificate notifications.

Optional

• letsencrypt_certbot_args: Extra command line arguments for Certbot.
• letsencrypt_certbot_default_args: Default arguments for Certbot, which you can override.
• letsencrypt_certbot_verbose: Output detailed logs to console (default is true).
• letsencrypt_certbot_version: Specify a specific Certbot version.
• letsencrypt_force_renew: Whether to always attempt to renew (default is true).
• letsencrypt_pause_services: List of services to stop/start during Certbot calls.
• letsencrypt_request_www: Automatically request www. (default is true).

Example Playbook

Use this role right before your main site role in your playbook. It requires root access on the target host.

---
- hosts: myhost
  become: yes
  become_user: root
  roles:
    - role: ansible-letsencrypt
      letsencrypt_email: [email protected]
      letsencrypt_domain: example.com
      letsencrypt_pause_services:
        - apache2

License

MIT License

Author Information

Jason Robinson (@jaywink) - mail@jasonrobinson.me - https://jasonrobinson.me - Twitter

Special thanks to Stefan Grönke (@gronke) for his contributions to this role.

For a complete list of contributors, please see CONTRIBUTORS.