bybatkhuu / sidecar.certbot

Certbot Docker image for automatic TLS/SSL certificate obtain & renewal from Let's Encrypt. Supports sidecar/standalone mode, DNS & HTTP challenges, multiple domains, subdomains, and wildcards.

Sidecar Certbot

This is a certbot docker image that can be used as a sidecar or standalone container to automatically obtain and renew TLS/SSL certificates from Let's Encrypt.

Features

• Let's Encrypt - https://letsencrypt.org
• Certbot - https://certbot.eff.org
• TLS/SSL certificates
• Automatic certificate obtain
• Automatic certificate renewal (checks every week)
• DNS challenges [recommended]:
  • Cloudflare DNS
  • DigitalOcean DNS
  • GoDaddy DNS
  • AWS Route53
  • Google Cloud DNS
• HTTP challenges:
  • Standalone
  • Webroot
• Sidecar or standalone mode
• Multiple domains per certificate
• Subdomains:
  • Multiple subdomains per domain/certificate
  • Wildcard subdomains (only DNS challenges)
• Docker and docker-compose

---

Getting started

1. Prerequisites

• Prepare server/PC with public IP address
• Buy or register domain name
• [RECOMMENDED] DNS provider API token/credentials (required for DNS challenges and wildcard subdomains):
  • Cloudflare - https://dash.cloudflare.com/profile/api-tokens
  • DigitalOcean - https://cloud.digitalocean.com/account/api/tokens
  • GoDaddy - https://developer.godaddy.com/keys
  • AWS Route53 - https://docs.aws.amazon.com/general/latest/gr/aws-sec-cred-types.html#access-keys-and-secret-access-keys
  • Google Cloud DNS - https://cloud.google.com/docs/authentication/getting-started
• Install docker and docker compose in server

For DEVELOPMENT:

• Install git
• Setup an SSH key (video tutorial)

2. Download or clone the repository

2.1. Prepare projects directory (if not exists) in your server with public IP address:

# Create projects directory:
mkdir -pv ~/workspaces/projects

# Enter into projects directory:
cd ~/workspaces/projects

2.2. Follow one of the below options [A] or [B]:

A. Clone the repository:

git clone https://github.com/bybatkhuu/sidecar.certbot.git && \
    cd sidecar.certbot

B. Download source code from releases page.

3. Configure environment

Tip

Skip this step, if you've already configured environment.

3.1. Configure .env file:

Important

Please, check environment variables!

# Copy .env.example file into .env file:
cp -v .env.example .env

# Edit environment variables to fit in your environment:
nano .env

3.2. Configure compose.override.yml file:

Important

Please, check arguments!

# Copy 'compose.override.[ENV].yml' file to 'compose.override.yml' file:
cp -v ./templates/compose/compose.override.[ENV].yml ./compose.override.yml
# For example, DEVELOPMENT environment:
cp -v ./templates/compose/compose.override.dev.yml ./compose.override.yml
# For example, STATGING or PRODUCTION environment:
cp -v ./templates/compose/compose.override.prod.yml ./compose.override.yml

# Edit 'compose.override.yml' file to fit in your environment:
nano ./compose.override.yml

3.3. Validate docker compose configuration:

Warning

If you get an error or warning, check your configuration files (.env or compose.override.yml).

./compose.sh validate
# Or:
docker compose config

4. Run docker compose

./compose.sh start -l
# Or:
docker compose up -d --remove-orphans --force-recreate && \
    docker compose logs -f --tail 100

5. Check certificates

./compose.sh certs
# Or check certificates in container:
docker compose exec certbot certbot certificates
# Or check certificates in host:
ls -alhF ./volumes/storage/certbot/ssl
# Or check certificates in host with tree:
tree -alFC --dirsfirst -L 5 ./volumes/storage/certbot/ssl

6. Stop docker compose

./compose.sh stop
# Or:
docker compose down --remove-orphans

👍 ✨

---

Environment Variables

You can use the following environment variables to configure:

.env.example

## --- CERTBOT configs --- ##
## Email address for Let's Encrypt domain registration:
CERTBOT_EMAIL=[e-mail]

## Domain names to obtain certificates:
CERTBOT_DOMAINS="example.com,www.example.com"

## DNS propagation timeout (in seconds):
CERTBOT_DNS_TIMEOUT=30

Arguments

You can use the following arguments to configure:

-s=, --server=[staging | production]
    Let's Encrypt server. Default: staging.
-n=, --new=[standalone | webroot]
    Obtain option for new certificates. Default: standalone.
-r=, --renew=[webroot | standalone]
    Renew option for existing certificates. Default: webroot.
-d=, --dns=[cloudflare | route53 | google | godaddy | digitalocean]
    Use DNS challenge instead of HTTP challenge.
-D, --disable-renew
    Disable automatic renewal of certificates.
-b, --bash, bash, /bin/bash
    Run only bash shell.

For example as in compose.override.yml file:

    command: ["--server=production"]
    command: ["--server=production", "--renew=standalone"]
    command: ["--new=webroot", "--disable-renew"]
    command: ["--server=production", "--dns=cloudflare"]
    command: ["--dns=digitalocean"]
    command: ["--dns=route53"]
    command: ["--dns=google"]
    command: ["--dns=godaddy"]
    command: ["/bin/bash"]

Documentation

• Build docker image
• Certbot examples

Roadmap

• Add more DNS providers.
• Add more documentation.

---

References

• Certbot - https://certbot.eff.org
• Certbot documentation - https://eff-certbot.readthedocs.io/en/stable
• Let's Encrypt - https://letsencrypt.org
• Let's Encrypt documentation - https://letsencrypt.org/docs