diff --git a/README.md b/README.md index 40d147a..82d3dd4 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,17 @@ Installs and configures Certbot (for Let's Encrypt). ## Requirements -If installing from source, Git is required. You can install Git using the `geerlingguy.git` role. +If installing from source (deprecated), Git is required. You can install Git using the `geerlingguy.git` role. -Generally, installing from source (see section `Source Installation from Git`) leads to a better experience using Certbot and Let's Encrypt, especially if you're using an older OS release. +For the `pip` install method, only Debian-family targets are supported (apt is used for the `python3-venv` / `libaugeas-dev` / `gcc` prerequisites). + +If you want an always-latest Certbot install on modern distros, prefer `pip` (see `Pip Installation` below) over `source` — the legacy source method relies on `certbot-auto`, which EFF removed from the Certbot repo in 2021. ## Role Variables certbot_install_method: package -Controls how Certbot is installed. Available options are 'package', 'snap', and 'source'. +Controls how Certbot is installed. Available options are 'package', 'snap', 'pip', and 'source' (deprecated). certbot_auto_renew: true certbot_auto_renew_user: "{{ ansible_user | default(lookup('env', 'USER')) }}" @@ -86,7 +88,29 @@ This install method is currently experimental and may or may not work across all When using the `webroot` creation method, a `webroot` item has to be provided for every `certbot_certs` item, specifying which directory to use for the authentication. Also, make sure your webserver correctly delivers contents from this directory. -### Source Installation from Git +### Pip Installation + +Setting `certbot_install_method: pip` installs Certbot into a Python virtual environment at `{{ certbot_dir }}` (default `/opt/certbot`) using EFF's recommended pip install path: . The `certbot` binary is symlinked into `/usr/local/bin` so it is on `PATH`. + +This is the modern equivalent of the legacy `source` install — use it when you want an always-latest Certbot on a distro whose packaged version is too old. Only Debian-family targets are supported by the included tasks; the necessary apt prerequisites (`python3-venv`, `libaugeas-dev`, `gcc`, etc.) are installed automatically. + +If `certbot_keep_updated: true` (the default), each role run will upgrade Certbot to the latest version on PyPI. + + certbot_dir: /opt/certbot + +The directory used as the venv root for the `pip` install (and the clone target for the legacy `source` install). + + certbot_pip_extra_packages: [] + +Extra pip packages installed alongside Certbot in the same venv when using the `pip` install method. Use this for plugins, e.g.: + + certbot_pip_extra_packages: + - certbot-dns-rfc2136 + - certbot-dns-cloudflare + +### Source Installation from Git (deprecated) + +> **Deprecated.** EFF removed the `certbot-auto` shim from the Certbot repo in 2021, so this install path no longer produces a working `certbot` binary. Use `certbot_install_method: pip` for the modern equivalent. You can install Certbot from it's Git source repository if desired with `certbot_install_method: source`. This might be useful in several cases, but especially when older distributions don't have Certbot packages available (e.g. CentOS < 7, Ubuntu < 16.10 and Debian < 8). @@ -96,10 +120,6 @@ You can install Certbot from it's Git source repository if desired with `certbot Certbot Git repository options. If installing from source, the configured `certbot_repo` is cloned, respecting the `certbot_version` setting. If `certbot_keep_updated` is set to `yes`, the repository is updated every time this role runs. - certbot_dir: /opt/certbot - -The directory inside which Certbot will be cloned. - ### Wildcard Certificates Let's Encrypt supports [generating wildcard certificates](https://community.letsencrypt.org/t/acme-v2-and-wildcard-certificate-support-is-live/55579), but the process for generating and using them is slightly more involved. See comments in [this pull request](https://github.com/geerlingguy/ansible-role-certbot/pull/60#issuecomment-423919284) for an example of how to use this role to maintain wildcard certs. diff --git a/defaults/main.yml b/defaults/main.yml index 3f29db0..81ba585 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -58,13 +58,23 @@ certbot_create_standalone_stop_services: # - apache # - varnish -# Available options: 'package', 'snap', 'source'. +# Available options: 'package', 'snap', 'source', 'pip'. +# Note: 'source' is deprecated — it relies on certbot-auto, which EFF removed +# from the certbot repo in 2021. Use 'pip' for the equivalent always-latest +# install (creates a venv at {{ certbot_dir }} and pip-installs certbot). certbot_install_method: 'package' -# Source install configuration. +# Source / pip install configuration. certbot_repo: https://github.com/certbot/certbot.git certbot_version: master certbot_keep_updated: true -# Where to put Certbot when installing from source. +# Where to put Certbot when installing from source or pip (venv root for pip). certbot_dir: /opt/certbot + +# Extra pip packages installed alongside certbot in the same venv (pip method only). +# Use this for plugins, e.g.: +# certbot_pip_extra_packages: +# - certbot-dns-rfc2136 +# - certbot-dns-cloudflare +certbot_pip_extra_packages: [] diff --git a/tasks/install-with-pip.yml b/tasks/install-with-pip.yml new file mode 100644 index 0000000..2336e0f --- /dev/null +++ b/tasks/install-with-pip.yml @@ -0,0 +1,40 @@ +--- +# Pip-in-venv install — EFF's recommended path now that certbot-auto is gone. +# https://certbot.eff.org/instructions?os=pip +# Debian-family only; RedHat goes through setup-RedHat.yml + package install. + +- name: Install certbot pip prerequisites. + ansible.builtin.apt: + name: + - python3 + - python3-dev + - python3-venv + - libaugeas-dev + - gcc + state: present + update_cache: true + cache_valid_time: 3600 + +- name: Install certbot in a venv via pip. + ansible.builtin.pip: + name: certbot + state: "{{ 'latest' if certbot_keep_updated else 'present' }}" + virtualenv: "{{ certbot_dir }}" + virtualenv_command: python3 -m venv + +- name: Install certbot pip plugins. + ansible.builtin.pip: + name: "{{ certbot_pip_extra_packages }}" + state: "{{ 'latest' if certbot_keep_updated else 'present' }}" + virtualenv: "{{ certbot_dir }}" + when: certbot_pip_extra_packages | length > 0 + +- name: Symlink certbot binary onto PATH. + ansible.builtin.file: + src: "{{ certbot_dir }}/bin/certbot" + dest: /usr/local/bin/certbot + state: link + +- name: Set Certbot script variable. + ansible.builtin.set_fact: + certbot_script: "{{ certbot_dir }}/bin/certbot" diff --git a/tasks/main.yml b/tasks/main.yml index 7723212..7b0998d 100644 --- a/tasks/main.yml +++ b/tasks/main.yml @@ -13,6 +13,9 @@ - import_tasks: install-from-source.yml when: certbot_install_method == 'source' +- import_tasks: install-with-pip.yml + when: certbot_install_method == 'pip' + - include_tasks: create-cert-standalone.yml with_items: "{{ certbot_certs }}" when: