cisagov/certboto repository overview

⁠certboto-docker 📜🤖☁️🐳

⁠Docker Image

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.

⁠Running

Consider using a compose.yml file to run Certboto.

⁠Running with Docker Compose

1. Create a compose.yml file similar to the one below to use Docker Compose⁠.

   ---
   name: certboto-docker
   
   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
   

   Copy

⁠Issue a new certificate

docker compose run certboto certonly -d lemmy.imotorhead.com

⁠Renew an existing certificate

docker compose run certboto

⁠Additional certbot commands

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

⁠Disabling Route53 challenges

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

⁠Using secrets with your container

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.

1. 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
   

   Copy

2. Then add the secret to your compose.yml file:

   ---
   name: certboto-docker
   
   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
   

   Copy

⁠Updating your container

⁠Docker Compose

1. Pull the new image from Docker Hub:

   docker compose pull
   

   Copy

2. Recreate the running container by following the previous instructions⁠:

   docker compose run certboto
   

   Copy

⁠Updating Python dependencies

This image uses [Pipenv] to manage Python dependencies using a Pipfile⁠. Both updating dependencies and changing the [Pipenv] configuration in src/Pipfile will result in a modified src/Pipfile.lock file that should be committed to the repository.

⁠Updating dependencies

If you want to update existing dependencies you would run the following command in the src/ subdirectory:

pipenv lock

⁠Modifying dependencies

If you want to add or remove dependencies you would update the src/Pipfile file and then update dependencies as you would above.

⁠Image tags

The images of this container are tagged with semantic versions⁠. It is recommended that most users use a version tag (e.g. :0.1.7).

See the tags tab⁠ on Docker Hub for a list of all the supported tags.

⁠Volumes

There are no volumes.

⁠Ports

There are no exposed ports.

⁠Environment variables

⁠Required

⁠Optional

There are no optional environment variables.

⁠Secrets

⁠Building from source

Build the image locally using this git repository as the build context⁠:

docker build \
  --tag cisagov/certboto:0.1.7 \
  https://github.com/cisagov/certboto-docker.git#develop

⁠Cross-platform builds

To create images that are compatible with other platforms, you can use the buildx⁠ feature of Docker:

1. 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
   

   Copy

2. Create the Dockerfile-x file with buildx platform support:

   ./buildx-dockerfile.sh
   

   Copy

3. Build the image using buildx:

   docker buildx build \
     --file Dockerfile-x \
     --platform linux/amd64 \
     --output type=docker \
     --tag cisagov/certboto:0.1.7 .
   

   Copy

⁠AWS policies

⁠Certboto roles

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"
            ]
        }
    ]
}

⁠Certificate access role

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/*"
        }
    ]
}

⁠Accessing and installing certificates at instance boot time

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⁠

⁠Contributing

We welcome contributions! Please see CONTRIBUTING.md⁠ for details.

⁠License

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.