https://github.com/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.
https://github.com/bybatkhuu/sidecar-certbot
certbot dns-challenge docker docker-compose domain http-challenge letsencrypt scripts sidecar ssl-cert ssl-tls standalone tls-termination
Last synced: 2 months ago
JSON representation
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.
- Host: GitHub
- URL: https://github.com/bybatkhuu/sidecar-certbot
- Owner: bybatkhuu
- License: mit
- Created: 2023-03-21T14:17:43.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-20T14:15:32.000Z (3 months ago)
- Last Synced: 2026-04-20T15:44:15.385Z (3 months ago)
- Topics: certbot, dns-challenge, docker, docker-compose, domain, http-challenge, letsencrypt, scripts, sidecar, ssl-cert, ssl-tls, standalone, tls-termination
- Language: Shell
- Homepage: http://certbot-docs.bybatkhuu.dev
- Size: 758 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Sidecar Certbot
[](https://choosealicense.com/licenses/mit/)
[](https://github.com/bybatkhuu/sidecar-certbot/actions/workflows/2.build-publish.yml)
[](https://github.com/bybatkhuu/sidecar-certbot/releases)
[](https://hub.docker.com/r/bybatkhuu/certbot/tags)
[](https://hub.docker.com/r/bybatkhuu/certbot/tags)
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 -
- Certbot -
- 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:
- API tokens -
- certbot-dns-cloudflare -
- DigitalOcean:
- API tokens -
- certbot-dns-digitalocean -
- GoDaddy:
- API keys -
- certbot-dns-godaddy -
- AWS Route53:
- AWS access keys -
- certbot-dns-route53 -
- Google Cloud DNS:
- GCP credentials/service accounts -
- certbot-dns-google -
- Install [**docker** and **docker compose**](https://docs.docker.com/engine/install) in **server**
- Docker image: [**bybatkhuu/certbot**](https://hub.docker.com/r/bybatkhuu/certbot)
For **DEVELOPMENT**:
- Install [**git**](https://git-scm.com/downloads)
- Setup an [**SSH key**](https://docs.github.com/en/github/authenticating-to-github/connecting-to-github-with-ssh)
### 2. 📥 Download or clone the repository
**2.1.** Prepare projects directory (if not exists) in your **server** with **public IP address**:
```sh
# Create projects directory:
mkdir -pv ~/workspaces/projects
# Enter into projects directory:
cd ~/workspaces/projects
```
**2.2.** Follow one of the below options **[A]**, **[B]** or **[C]**:
**A.** Clone the repository:
```sh
git clone https://github.com/bybatkhuu/sidecar-certbot.git && \
cd sidecar-certbot
```
**OPTION B.** Clone the repository (for **DEVELOPMENT**: git + ssh key):
```sh
git clone git@github.com:bybatkhuu/sidecar-certbot.git && \
cd sidecar-certbot
```
**OPTION C.** Download source code from **[releases](https://github.com/bybatkhuu/sidecar-certbot/releases)** page.
### 3. 🛠 Configure the environment
[TIP] Skip this step, if you've already configured environment!
#### 3.1. 🌎 Configure **`.env`** (environment variables) file
**[IMPORTANT]** Please, check **[environment variables](#-environment-variables)** section for more details.
```sh
# 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
[TIP] Skip this step, if you want run with default configuration!
You can use below template **`compose.override.yml`** files for different environments:
- **DEVELOPMENT**: [**`compose.override.dev.yml`**](./templates/compose/compose.override.dev.yml)
- **PRODUCTION/STAGING**: [**`compose.override.prod.yml`**](./templates/compose/compose.override.prod.yml)
```sh
# 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, STAGING 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. ✅ Check docker compose configuration is valid
**[WARNING]** If you get an error or warning, check your configuration files (**`.env`** or **`compose.override.yml`**).
```sh
./compose.sh validate
# Or:
docker compose config
```
### 4. 🚀 Start docker compose
**[CAUTION]**:
- If ports are conflicting, you should change ports from [**3. step**](#3--configure-the-environment).
- If container names are conflicting, you should change project directory name (from **`sidecar-certbot`** to something else, e.g: `prod.sidecar-certbot`) from [**2.2. step**](#2--download-or-clone-the-repository).
```sh
./compose.sh start -l
# Or:
docker compose up -d --remove-orphans --force-recreate && \
docker compose logs -f --tail 100
```
### 5. 🔐 Check certificates
```sh
./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 ./volumes/storage/certbot/ssl
```
### 7. 🪂 Stop docker compose
```sh
./compose.sh stop
# Or:
docker compose down --remove-orphans
```
👍
---
## ⚙️ Configuration
### 🌎 Environment Variables
You can use the following environment variables to configure:
[**`.env.example`**](./.env.example):
```sh
## --- CERTBOT configs --- ##
## Email address for Let's Encrypt domain registration:
CERTBOT_EMAIL=user@email.com
## Domain names to obtain certificates:
CERTBOT_DOMAINS="example.com,www.example.com"
## DNS propagation timeout (in seconds):
CERTBOT_DNS_TIMEOUT=30
## -- Docker configs -- ##
# CERTBOT_PORT=80 # port for bridge network and standalone mode
```
### 🐳 Docker container command arguments
You can use the following arguments to configure:
```txt
-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`**](./templates/compose/compose.override.dev.yml) file:
```yml
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](./docs/docker-build.md)
- [Certbot examples](./docs/certbot-examples.md)
### 🛤 Roadmap
- Add more DNS providers.
- Add more documentation.
---
## 📑 References
- Certbot -
- Certbot documentation -
- Let's Encrypt -
- Let's Encrypt documentation -
- Docker -
- Docker Compose -