Public Repository

Last pushed: 6 months ago
Short Description
ZeroSSL client for obtaining Let's Encrypt certificates.
Full Description

Lightweight client for Let's Encrypt - Docker version, Alpine Linux based.

Current base version: 0.31, runs as 'zerossl' user in the container, not as 'root'.

This version supports both ACME v1 and ACME v2 protocol, as well as wildcard certificates issuance). It is fully compatible with previous version and capable of selecting protocol automatically or via "--api" switch. Previous version can be pulled using "previous" tag ("docker pull zerossl/client:previous").

For additional details, documentation, Online SSL Certificate Wizard and other tools visit:

How to use:

To make it possible to write certificate-related files on the host file system, map /data appropriately or as shown below in the alias example.

  • Pull the image (Note: you may need to be in docker group to use it)

    $ docker pull zerossl/client

  • Decide which host directory you will be keeping certificate files and keys in and which host directory is your 'acme-challenge' one (the latter is usually created as /webroot/.well-known/acme-challenge, where 'webroot' is the main directory with your web-server pages, often public_html). Let's say you keep files in /home/my_user/keys_and_certs and you are using /home/my_user/public_html/.well-known/acme-challenge. Those directories should be writable by your current user.

  • Run the container directly or create an alias similar to the one shown below

    $ alias'docker run -it -v /home/my_user/keys_and_certs:/data -v /home/my_user/public_html/.well-known/acme-challenge:/webroot -u $(id -u) --rm zerossl/client'

  • If you have created an alias (you can add it into your .bashrc for convenience), you can then run as normal. Without parameters you will be presented with a help screen listing the available options. To see the extended help screen, including usage examples, use --help option.

    $ --help

  • If you are using --path option (with or without --unlink) to create verification files automatically, use the mapped path, not the real one, so in the example above it will be /webroot

    $ --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "," --generate-missing --path /webroot --unlink

If you want to include domains with different webroots on the same certificate, you should define the mappings first (as demonstrated above, using -v option in an alias command example) and then list webroots for each domain in the --path option (comma separated, in the same order as you list domains themselves).

  • If you want to issue a wildcard certificate for your domain, use DNS verification and specify the domain in the following format: *.some.domain. You will also need to use --handle-as dns and --api 2 parameters:

    $ --key account.key --csr domain.csr --csr-key domain.key --crt domain.crt --domains "*" --generate-missing --handle-as dns --api 2

Important - if you are issuing a wildcard certificate and also want a so-called "naked domain" ("some.domain") to be covered, list both of those names in the domains parameter. You will then need to create two TXT records with identical names but different values - this is normal and this is how you should create them.

$ ... --domains "*.some.domain, some.domain" --generate-missing --handle-as dns --api 2

Don't forget that by default the test certificate is generated, so you will need to use --live option to generate a 'real' trusted one.

By default RSA encryption is used, if you want to use ECC, specify a curve name with --curve option. You can use --curve default to use prime256v1.

To update your contact details at Let's Encrypt (to receive expiration notifications), you can use --update-contacts option as shown below:

$ --key account.key --update-contacts "one@email.address, another@email.address" --live

To remove your contact details use "none" as a value:

$ --key account.key --update-contacts "none" --live

You can also use --quiet option to suppress all messages but errors (useful when run from crontab).

This version of the client fully supports IDN (internationalized domain names).

Docker Pull Command