acme.sh

Installs acme.sh and issues TLS certificates from Let's Encrypt via Hetzner DNS challenge.

Requirements

• Debian/Ubuntu host (uses apt to install cron and git)

Variables

Variable	Default	Description
acme_user_mail	~	Email address registered with Let's Encrypt. Does not need to be a real mailbox. Required.
acme_install_dir	/tmp/acme	Temporary path used to clone acme.sh during installation. Removed after install.
acme_config_home	/root/myacme/data	Path where acme.sh stores its internal config.
acme_cert_home	/root/mycerts	Path where acme.sh stores its internal cert copies.
acme_certs	[]	Certificates to issue. See Certificates below.
acme_dns_credentials	[]	Hetzner DNS Console credentials. See DNS credentials below.
acme_uninstall	false	Uninstalls acme.sh instead of setting it up.
acme_prune	false	Also removes acme_cert_home and acme_config_home on uninstall. Requires acme_uninstall: true. Irreversible.

Usage

Minimal setup:

acme_user_mail: acme@example.com
acme_dns_credentials:
  - api: hetzner
    token: "{{ vault_hetzner_dns_token }}"
acme_certs:
  - domain: example.com
    full_path: /etc/ssl/example.com/fullchain.pem
    key_path: /etc/ssl/example.com/privkey.pem
    custom_options: "--keylength ec-256"

Target directories for cert files must exist before the role runs — acme.sh does not create them. Create them in a pre_tasks block.

Certificates

acme_certs is a list of certificates to issue. Each entry runs acme.sh --issue followed by --install-cert, which registers the target paths so the cron renewal job keeps them up to date automatically.

Field	Description
domain	Domain name. Required.
validation	acme.sh DNS provider. Default: dns_hetzner.
full_path	--fullchain-file destination (cert + intermediates). Use this for coturn and most TLS consumers.
key_path	--key-file destination.
cert_path	--cert-file destination (leaf cert only, optional).
ca_path	--ca-file destination (optional).
reloadcmd	Shell command run after every renewal, e.g. docker compose -f /docker/app/compose.yml restart.
custom_options	Extra acme.sh flags, e.g. --keylength ec-256 for ECDSA P-256.

acme_certs:
  - domain: example.com
    full_path: /etc/ssl/example.com/fullchain.pem
    key_path: /etc/ssl/example.com/privkey.pem
    cert_path: /etc/ssl/example.com/cert.pem
    custom_options: "--keylength ec-256"
    reloadcmd: "docker compose -f /docker/myapp/compose.yml restart"

DNS credentials

acme_dns_credentials configures the Hetzner DNS Console API for DNS challenge. Token from https://dns.hetzner.com/settings/api-token.

acme_dns_credentials:
  - api: hetzner
    token: "{{ vault_hetzner_dns_token }}"

Uninstall

To uninstall acme.sh:

acme_uninstall: true

To also remove all stored certificates and config (irreversible):

acme_uninstall: true
acme_prune: true