The full PR diff isn't as pleasant due to some poor line matching in the diff algorithm? I've ensured each sub-section has it's own commit with related commit message if you'd find that easier to review with.

URLs are only in the overview notes below (since I've seen some weird stuff when referencing github content in commits that get forked/rebased or something by other users, triggering multiple references on an issue/PR/commit).

NOTE: On a Ubuntu 21.04 VPS instance, docker-compose is version 1.25 (from 2020), this fails to run docker-compose.yml examples versioned 3.8, requiring the version be dropped down to 3.7.

Commit Overview:

• Added a warning to make users aware that using a public CA like Let's Encrypt will publicly log information that may be somewhat sensitive, or undesirable to have historic records made public which cannot be redacted.
• The letsencrypt repo that was linked early in this guide now redirects to the Certbot repo.
• More explicit volume mount instruction for CertBot; the local location was a tad vague.
• Better clarified /etc/letsencrypt/live contents structure, as well as FQDN info. Removed the misleading fqdn: from docker-compose.yml example snippet.
• General rewrite of the Certbot section with additional tips, and heavy rewrite of nginx-proxy sections.
• Links extracted to the bottom of the file, and many new supporting links added.

• letsencrypt-nginx-proxy-companion has changed project name to acme-companion, and transferred to new maintainers and the nginx-proxy organization. This also affects the DockerHub image references.
• acme-companion has switched from using simp_le to acme.sh for provisioning certificates. This requires mounting an additional volume for persisting provisioner state.
• The dummy container (webmail) is no longer library/nginx, just nginx. This container also doesn't appear to be required. I've verified that the ENV can be given to the mailserver service container directly.
• This setup implies SSL_TYPE=letsencrypt (due to the /etc/letsencrypt/live mount), but was never compatible with this mode (git blame from target/start-mailserver.sh letsencrypt handling in 2016 to current letsencrypt handling - both expect the FQDN as the directory name, not as the filename).. EDIT: Nevermind, it appears to provision to a directory with the correct filenames (although acme.sh docs warn against using these internal contents directly as it is subject to change), which are symlinked to from certs/. It's only with the Let's Encrypt staging endpoint that it would seem incompatible as that prefixes the the directory names with _test_. I'll need to test this a bit more.

Example - nginx-proxy + acme-companion with docker-compose.yml:

• The bulk of the mailserver service has been removed, users are advised to have an existing docker-compose.yml config for docker-mailserver and update only what is relevant to integrate with the cert provisioner.
• DEBUG is false by default.
• The htpasswd volume is unnecessary, only relevant if using "Basic Authentication" to protect access to web service endpoints. conf.d/ is also not required by default, it can be useful for the standalone mode (documented as a tip). Remaining volumes have inline-comments to document their purpose.
• The networks: portion of the example appears to be taken from upstream, which that has since dropped it. While we could continue to document this, I consider it more of an advanced config detail that we don't need to touch on in our docs.
• volumes_from: is not supported in v3 Compose format, only v2 and the Docker CLI. I did not want to advise v2, so I've duplicated the volumes between the two containers instead. Internally acme-companion would rely on volumes_from: to identify the nginx-proxy container, it provides alternative discovery methods, the label is outdated and refers the legacy label (their script logic is the same); using the ENV NGINX_PROXY_CONTAINER seemed most appropriate and has been added.
• Upstream acme-companion docs only cover support for v2 Compose format. There is a note regarding nginx-proxy having volumes configured in it's Dockerfile. Providing a volume for /etc/nginx/dhparam is required to avoid creating anonymous volumes each run of nginx-proxy. I've used a named data volume here to make it stick out more, it's not desirable and upstream should fix this, then we can drop it.
• I considered disabling DH param generation, as upstream is pointlessly generating DH params regardless of needing them, they have not yet adopted standardized DHE groups. acme-companion differs slightly in generation (a bit more secure by not using -DSAPARAM), but lacks an ENV to disable generation. Neither should be a concern for us, but I might open a PR to both projects to address it.
• I've also opted to only demonstrate the Two Container (Basic) setup that upstream documents. Previously our docs have been showing docker-gen with the Three Container (Advanced) setup, which allows for not having the Docker API socket attached as a volume to a container exposed to the web. This reduces the security a bit, and I have not mentioned that on our docs. I could caution the reader with a link to upstream about the risk, but I don't think we should maintain the docker-gen setup.
• acme-companion does support restarting a container when certificates are provisioned/renewed, but I assume that's not something we want to encourage vs having supervisorctl internally restart services? I've mentioned it along with other config ENV in a tip admonition.

These links on the top do not work:

• Using Traefik
• Using self-signed certificates
• Using your own certificates

These links on the top do not work

Good spotting! Thanks for that. I really need to get that link checking lint added to the CI 😅

Documentation preview for this PR is ready! 🎉

Built with commit: 07124f2

Nice PR! Ready to be merged I think :)