Skip to content

acme.sh: An alternative to Let's Encrypt's Certbot

Use cases

If you have a local service without a public IP address, you can't use the usual Let's Encrypt method. However, there is an alternative method where you prove ownership of your domain by adding a TXT record with a challenge text. For example, you might have a local

  • HomeAssistant
  • OctoPi / OctoPrint
  • PiHole
  • paperlessNG
  • ...

service in your network that you don't want to expose to the internet (with port forwarding).

Requirements

For acme.sh, you need:

  • Your own domain registered at a supported DNS provider (see next section)
  • A Unix shell

and that's it.

These recommendations are based on my previous experiences:

DNS provider Recommendation
Porkbun Yes. Just create your API credentials and you're done.
Namecheap No. You have to whitelist your IP address manually from which you access the API. As a static IP from your ISP is not guaranteed for home connections, you always have to change the settings when your IP changes.

Installation

Open the acme.sh GitHub repository. You have multiple installation methods. This is taken from the repository, please check beforehand whether there were changes (and don't just blindly pipe curl to shell!).

Note

After running the installation command, restart your shell so that the alias takes effect.

Method 1

curl https://get.acme.sh | sh -s email=my@example.com

alternatively with wget:

wget -O -  https://get.acme.sh | sh -s email=my@example.com

Method 2

You can also clone the repository and run the shell script:

git clone https://github.com/acmesh-official/acme.sh.git
cd ./acme.sh
./acme.sh --install -m my@example.com

Issue a new certificate

We want to create a certificate with API method.

  1. Read the wiki and check if your DNS provider is supported (the list is split into two pages):
  2. After you've found your DNS provider, get the necessary credentials (API tokens, API name, etc.)
    • Example: Porkbun requires PORKBUN_API_KEY and PORKBUN_SECRET_API_KEY.

  3. Open the configuration file located in ~./acme.sh/account.conf and add the required environment variables.

    • Example:

      # ...
ACCOUNT_EMAIL='my@email.com'
UPGRADE_HASH='...'

PORKBUN_API_KEY='my_key_...'
PORKBUN_SECRET_API_KEY='my_secret_key_..:'
# ...

  4. After that, you can issue a new certificate. Make sure to pass your own DNS provider for the --dns argument.

    • Example:

      acme.sh --issue -d my.own.domain --dns dns_porkbun -reloadcmd /home/user/after_install_script.sh

And you're done! By default, your certificate is located under /home/[username]/.acme.sh/[domain name].

Useful arguments

With the --reloadcmd [cmd] argument, you can run a command or shell script after your certificates have been renewed. For example, you can use it to combine the private and public key to a .pem file:

#!/bin/bash
# Combine by just concatenating public and private key (order is important)
cat my.own.domain.cer my.own.domain.key > my.own.domain.pem
# Read access only for current users
chmod g-r,o-r my.own.domain.pem