Certboto combines all the convenience of Certbot with the cloudiness of AWS S3 buckets and AWS Route53 all wrapped up in a tasty Docker container.
Consider using a docker-compose.yml
file to run Certboto.
-
Create a
docker-compose.yml
file similar to the one below to use Docker Compose.--- version: "3.7" secrets: credentials: file: /home/username/.aws/credentials services: certboto: image: cisagov/certboto init: true restart: "no" environment: - AWS_DEFAULT_REGION=us-east-1 - BUCKET_NAME=my-certificates - BUCKET_PROFILE=certsync-role - DNS_PROFILE=dns-role secrets: - source: credentials target: credentials
docker compose run certboto certonly -d lemmy.imotorhead.com
docker compose run certboto
The certbot
help can be displayed without synchronizing with a bucket.
docker compose run certboto --help
More complicated certbot
commands may be impossible to escape correctly. The
--shell
flag can be used to drop into a shell within the container after the
bucket is synchronized to the container. This allows users to issue commands
directly to certbot
. Once the shell exits cleanly, the container will be
synchronized back to the bucket.
docker compose run certboto --shell
To disable usage of the Route53 DNS plugin pass --no-dns-route53
as the first
argument. This is useful if you need to use other types of challenges.
docker compose run certboto --no-dns-route53 --manual certonly -d lemmy.imotorhead.com
This container also supports passing sensitive values via Docker secrets. Passing sensitive values like your credentials can be more secure using secrets than using environment variables. See the secrets section below for a table of all supported secret files.
-
To use secrets, create a
certboto_credentials
file containing the values you want set:[default] aws_access_key_id = XXXXXXXXXXXXXXXXXXXX aws_secret_access_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx [dns-role] role_arn = arn:aws:iam::1234567890ab:role/ModifyPublicDNS source_profile = default [bucket-role] role_arn = arn:aws:iam::1234567890ab:role/CertbotBucket source_profile = default # If running on EC2 with an instance profile that allows sts:AssumeRole # you can assume delegated roles using the metadata as the credential source # See: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html [dns-role-ec2] role_arn = arn:aws:iam::1234567890ab:role/ModifyPublicDNS credential_source = Ec2InstanceMetadata [bucket-role-ec2] role_arn = arn:aws:iam::1234567890ab:role/CertbotBucket credential_source = Ec2InstanceMetadata
-
Then add the secret to your
docker-compose.yml
file:--- version: "3.7" secrets: credentials: file: certboto_credentials services: certboto: image: cisagov/certboto init: true restart: "no" environment: - AWS_DEFAULT_REGION=us-east-1 - BUCKET_NAME=my-certificates - BUCKET_PROFILE=certsync-role - DNS_PROFILE=dns-role secrets: - source: credentials target: credentials
-
Pull the new image from Docker Hub:
docker compose pull
-
Recreate the running container by following the previous instructions:
docker compose run certboto
The images of this container are tagged with
semantic versions. It is recommended that most users use
a version tag (e.g. :0.1.4
).
Image:tag | Description |
---|---|
cisagov/certboto:0.1.4 |
An exact release version. |
cisagov/certboto:0.1 |
The most recent release matching the major and minor version numbers. |
cisagov/certboto:0 |
The most recent release matching the major version number. |
cisagov/certboto:edge |
The most recent image built from a merge into the develop branch of this repository. |
cisagov/certboto:nightly |
A nightly build of the develop branch of this repository. |
cisagov/certboto:latest |
The most recent release image pushed to a container registry. Pulling an image using the :latest tag should be avoided. |
See the tags tab on Docker Hub for a list of all the supported tags.
There are no volumes.
There are no exposed ports.
Name | Purpose |
---|---|
AWS_DEFAULT_REGION | Default AWS region. |
BUCKET_NAME | The bucket to store the Certbot configuration. |
BUCKET_PROFILE | The profile of your credentials to use for bucket access. |
DNS_PROFILE | The profile of your credentials to use for route53 access. |
There are no optional environment variables.
Filename | Purpose |
---|---|
credentials |
The AWS credentials file. |
Build the image locally using this git repository as the build context:
docker build \
--build-arg VERSION=0.1.4 \
--tag cisagov/certboto:0.1.4 \
https://github.com/cisagov/certboto-docker.git#develop
To create images that are compatible with other platforms, you can use the
buildx
feature of
Docker:
-
Copy the project to your machine using the
Code
button above or the command line:git clone https://github.com/cisagov/certboto-docker.git cd certboto-docker
-
Create the
Dockerfile-x
file withbuildx
platform support:./buildx-dockerfile.sh
-
Build the image using
buildx
:docker buildx build \ --file Dockerfile-x \ --platform linux/amd64 \ --build-arg VERSION=0.1.4 \ --output type=docker \ --tag cisagov/certboto:0.1.4 .
The BUCKET_PROFILE
should assume a role with the following policy:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": [
"s3:PutObject",
"s3:GetObject",
"s3:ListBucket",
"s3:DeleteObject"
],
"Resource": [
"arn:aws:s3:::cert-bucket-name",
"arn:aws:s3:::cert-bucket-name/*"
]
}
]
}
The DNS_PROFILE
should assume a role with the following policy:
{
"Version": "2012-10-17",
"Id": "certbot-dns-route53 sample policy",
"Statement": [
{
"Effect": "Allow",
"Action": [
"route53:ListHostedZones",
"route53:GetChange"
],
"Resource": [
"*"
]
},
{
"Effect" : "Allow",
"Action" : [
"route53:ChangeResourceRecordSets"
],
"Resource" : [
"arn:aws:route53:::hostedzone/YOURHOSTEDZONEID"
]
}
]
}
To access a specific certificate, a role with the following profile should be assumed:
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "allow-cert-read",
"Effect": "Allow",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::cert-bucket-name/live/lemmy.imotorhead.com/*"
}
]
}
The certificates created by Certboto can be installed on a booting instance
using cloud-init. An implementation
of this can be found in the
openvpn-server-tf-module
project. Specifically
install-certificates.py
We welcome contributions! Please see CONTRIBUTING.md
for
details.
This project is in the worldwide public domain.
This project is in the public domain within the United States, and copyright and related rights in the work worldwide are waived through the CC0 1.0 Universal public domain dedication.
All contributions to this project will be released under the CC0 dedication. By submitting a pull request, you are agreeing to comply with this waiver of copyright interest.