HomeCentr - certbot

The image contains Certbot compliant with the HomeCenter docker images standard (S6 overlay, privilege drop etc.). All DNS plugins endorsed by Certbot are installed (list).

This image is supposed to be used as a single purpose certificate manager. It does not include any reverse proxy. The proxy should be running in a separate container and read the certificates from a mounted volume.

Usage

version: "3.7"
services:
  certbot
    build: .
    image: homecentr/certbot
    # Example uses Cloudflare dns verification, if you use a different provider, you need to adjust the arguments
    environment:
      CERTBOT_ARGS: "--email [email protected] --dns-cloudflare --dns-cloudflare-credentials /secrets/cloudflare.ini"
    volumes:
      - cloudflare.ini:/secrets/cloudflare.ini

If you are just testing/are not 100% sure the arguments are correct, add the --dry-run which will not actually make the request to Let's encrypt or --staging argument which will use Let's encrypts staging servers instead of the production ones. The production servers have low rate limits and running too many unsuccessful requests could block you out for a week.

Environment variables

Name	Default value	Description
PUID	7077	UID of the user certbot be running as.
PGID	7077	GID of the user certbot be running as.
CERTBOT_ARGS		Additional arguments passed to certbot's certonly command. The argument --agree-tos is passed automatically, but you have to provide the --email argument.
CERTS_GID	7077	GID of a group which set as group owner of the certificates in the /certs directory. This is to simplify sharing the certificates with other containers/components.

Exposed ports

This image does not expose any ports.

Volumes

Container path	Description
/state	Directory where certbot keeps its state. This directory should be persisted to avoid issuing the same certificate multiple times. This directory must be writable by PUID or PGID.
/certs	The output certificates will be placed in this directory. This is the directory you can/want share with other components. The certificates are standard files, not symlinks. This directory must be writable by PUID or PGID.
/logs	Certbot will output detailed logs into this directory. Make sure the PUID user has write permissions in this directory. This directory must be writable by PUID or PGID.

Security

The container is regularly scanned for vulnerabilities and updated. Further info can be found in the Security tab.

Container user

The container supports privilege drop. Even though the container starts as root, it will use the permissions only to perform the initial set up. The certbots runs as UID/GID provided in the PUID and PGID environment variables.

⚠️ Do not change the container user directly using the user Docker compose property or using the --user argument. This would break the privilege drop logic.