{"id":31955872,"url":"https://github.com/cisagov/certboto-docker","last_synced_at":"2025-10-14T14:32:23.288Z","repository":{"id":37076243,"uuid":"200927445","full_name":"cisagov/certboto-docker","owner":"cisagov","description":"Certbot container that stores its configuration in an AWS S3 bucket","archived":false,"fork":false,"pushed_at":"2025-10-06T21:29:28.000Z","size":1264,"stargazers_count":15,"open_issues_count":3,"forks_count":5,"subscribers_count":3,"default_branch":"develop","last_synced_at":"2025-10-06T23:26:21.318Z","etag":null,"topics":["aws","boto","bucket","certbot","docker","s3"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cisagov.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2019-08-06T21:33:57.000Z","updated_at":"2025-04-04T03:54:15.000Z","dependencies_parsed_at":"2025-01-12T12:18:27.583Z","dependency_job_id":"67fde63b-8399-4bd7-b6be-f570e7a9ff2e","html_url":"https://github.com/cisagov/certboto-docker","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/cisagov/certboto-docker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcertboto-docker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcertboto-docker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcertboto-docker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcertboto-docker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cisagov","download_url":"https://codeload.github.com/cisagov/certboto-docker/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cisagov%2Fcertboto-docker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279019126,"owners_count":26086680,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-14T02:00:06.444Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","boto","bucket","certbot","docker","s3"],"created_at":"2025-10-14T14:30:41.547Z","updated_at":"2025-10-14T14:32:23.280Z","avatar_url":"https://github.com/cisagov.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# certboto-docker 📜🤖☁️🐳 #\n\n[![GitHub Build Status](https://github.com/cisagov/certboto-docker/workflows/build/badge.svg)](https://github.com/cisagov/certboto-docker/actions/workflows/build.yml)\n[![CodeQL](https://github.com/cisagov/certboto-docker/workflows/CodeQL/badge.svg)](https://github.com/cisagov/certboto-docker/actions/workflows/codeql-analysis.yml)\n[![Known Vulnerabilities](https://snyk.io/test/github/cisagov/certboto-docker/badge.svg)](https://snyk.io/test/github/cisagov/certboto-docker)\n\n## Docker Image ##\n\n[![Docker Pulls](https://img.shields.io/docker/pulls/cisagov/certboto)](https://hub.docker.com/r/cisagov/certboto)\n[![Docker Image Size (latest by date)](https://img.shields.io/docker/image-size/cisagov/certboto)](https://hub.docker.com/r/cisagov/certboto)\n[![Platforms](https://img.shields.io/badge/platforms-amd64%20%7C%20arm%2Fv6%20%7C%20arm%2Fv7%20%7C%20arm64%20%7C%20ppc64le%20%7C%20s390x-blue)](https://hub.docker.com/r/cisagov/certboto/tags)\n\nCertboto combines all the convenience of [Certbot](https://certbot.eff.org)\nwith the cloudiness of [AWS S3 buckets](https://aws.amazon.com/s3/)\nand [AWS Route53](https://aws.amazon.com/route53/)\nall wrapped up in a tasty [Docker](https://www.docker.com) container.\n\n## Running ##\n\nConsider using a `docker-compose.yml` file to run Certboto.\n\n### Running with Docker Compose ###\n\n1. Create a `docker-compose.yml` file similar to the one below to use [Docker Compose](https://docs.docker.com/compose/).\n\n    ```yaml\n    ---\n    version: \"3.7\"\n\n    secrets:\n      credentials:\n        file: /home/username/.aws/credentials\n\n    services:\n      certboto:\n        image: cisagov/certboto\n        init: true\n        restart: \"no\"\n        environment:\n          - AWS_DEFAULT_REGION=us-east-1\n          - BUCKET_NAME=my-certificates\n          - BUCKET_PROFILE=certsync-role\n          - DNS_PROFILE=dns-role\n        secrets:\n          - source: credentials\n            target: credentials\n    ```\n\n#### Issue a new certificate ####\n\n```console\ndocker compose run certboto certonly -d lemmy.imotorhead.com\n```\n\n#### Renew an existing certificate ####\n\n```console\ndocker compose run certboto\n```\n\n#### Additional `certbot` commands ####\n\nThe `certbot` help can be displayed without synchronizing with a bucket.\n\n```console\ndocker compose run certboto --help\n```\n\nMore complicated `certbot` commands may be impossible to escape correctly. The\n`--shell` flag can be used to drop into a shell within the container after the\nbucket is synchronized to the container.  This allows users to issue commands\ndirectly to `certbot`.  Once the shell exits cleanly, the container will be\nsynchronized back to the bucket.\n\n```console\ndocker compose run certboto --shell\n```\n\n#### Disabling Route53 challenges ####\n\nTo disable usage of the Route53 DNS plugin pass `--no-dns-route53` as the first\nargument.  This is useful if you need to use other types of challenges.\n\n```console\ndocker compose run certboto --no-dns-route53 --manual certonly -d lemmy.imotorhead.com\n```\n\n## Using secrets with your container ##\n\nThis container also supports passing sensitive values via [Docker\nsecrets](https://docs.docker.com/engine/swarm/secrets/).  Passing sensitive\nvalues like your credentials can be more secure using secrets than using\nenvironment variables.  See the\n[secrets](#secrets) section below for a table of all supported secret files.\n\n1. To use secrets, create a `certboto_credentials` file containing the values you\nwant set:\n\n    ```ini\n    [default]\n    aws_access_key_id = XXXXXXXXXXXXXXXXXXXX\n    aws_secret_access_key = xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\n\n    [dns-role]\n    role_arn = arn:aws:iam::1234567890ab:role/ModifyPublicDNS\n    source_profile = default\n\n    [bucket-role]\n    role_arn = arn:aws:iam::1234567890ab:role/CertbotBucket\n    source_profile = default\n\n    # If running on EC2 with an instance profile that allows sts:AssumeRole\n    # you can assume delegated roles using the metadata as the credential source\n    # See: https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html\n\n    [dns-role-ec2]\n    role_arn = arn:aws:iam::1234567890ab:role/ModifyPublicDNS\n    credential_source = Ec2InstanceMetadata\n\n    [bucket-role-ec2]\n    role_arn = arn:aws:iam::1234567890ab:role/CertbotBucket\n    credential_source = Ec2InstanceMetadata\n    ```\n\n1. Then add the secret to your `docker-compose.yml` file:\n\n    ```yaml\n    ---\n    version: \"3.7\"\n\n    secrets:\n      credentials:\n        file: certboto_credentials\n\n    services:\n      certboto:\n        image: cisagov/certboto\n        init: true\n        restart: \"no\"\n        environment:\n          - AWS_DEFAULT_REGION=us-east-1\n          - BUCKET_NAME=my-certificates\n          - BUCKET_PROFILE=certsync-role\n          - DNS_PROFILE=dns-role\n        secrets:\n          - source: credentials\n            target: credentials\n    ```\n\n## Updating your container ##\n\n### Docker Compose ###\n\n1. Pull the new image from Docker Hub:\n\n    ```console\n    docker compose pull\n    ```\n\n1. Recreate the running container by following the\n[previous instructions](#running-with-docker-compose):\n\n    ```console\n    docker compose run certboto\n    ```\n\n## Image tags ##\n\nThe images of this container are tagged with\n[semantic versions](https://semver.org).  It is recommended that most users use\na version tag (e.g. `:0.1.4`).\n\n| Image:tag | Description |\n|-----------|-------------|\n|`cisagov/certboto:0.1.4`| An exact release version. |\n|`cisagov/certboto:0.1`| The most recent release matching the major and minor version numbers. |\n|`cisagov/certboto:0`| The most recent release matching the major version number. |\n|`cisagov/certboto:edge` | The most recent image built from a merge into the `develop` branch of this repository. |\n|`cisagov/certboto:nightly` | A nightly build of the `develop` branch of this repository. |\n|`cisagov/certboto:latest`| The most recent release image pushed to a container registry.  Pulling an image using the `:latest` tag [should be avoided.](https://vsupalov.com/docker-latest-tag/) |\n\nSee the [tags tab](https://hub.docker.com/r/cisagov/certboto/tags) on Docker\nHub for a list of all the supported tags.\n\n## Volumes ##\n\nThere are no volumes.\n\n\u003c!--\n| Mount point | Purpose        |\n|-------------|----------------|\n| `/path/to/volume` | Describe its purpose. |\n--\u003e\n\n## Ports ##\n\nThere are no exposed ports.\n\n\u003c!--\n| Port | Purpose        |\n|------|----------------|\n| PORT_NUMBER | Describe its purpose. |\n--\u003e\n\n## Environment variables ##\n\n### Required ###\n\n| Name | Purpose |\n|------|---------|\n| AWS_DEFAULT_REGION | Default AWS region. |\n| BUCKET_NAME | The bucket to store the Certbot configuration. |\n| BUCKET_PROFILE | The profile of your `credentials` to use for bucket access. |\n| DNS_PROFILE | The profile of your `credentials` to use for route53 access. |\n\n### Optional ###\n\nThere are no optional environment variables.\n\n\u003c!--\n| Name  | Purpose | Default |\n|-------|---------|---------|\n| `OPTIONAL_VARIABLE` | Describe its purpose.  | `null` |\n--\u003e\n\n## Secrets ##\n\n| Filename | Purpose |\n|----------|---------|\n| `credentials` | The [AWS credentials](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) file. |\n\n## Building from source ##\n\nBuild the image locally using this git repository as the [build context](https://docs.docker.com/engine/reference/commandline/build/#git-repositories):\n\n```console\ndocker build \\\n  --build-arg VERSION=0.1.4 \\\n  --tag cisagov/certboto:0.1.4 \\\n  https://github.com/cisagov/certboto-docker.git#develop\n```\n\n## Cross-platform builds ##\n\nTo create images that are compatible with other platforms, you can use the\n[`buildx`](https://docs.docker.com/buildx/working-with-buildx/) feature of\nDocker:\n\n1. Copy the project to your machine using the `Code` button above\n   or the command line:\n\n    ```console\n    git clone https://github.com/cisagov/certboto-docker.git\n    cd certboto-docker\n    ```\n\n1. Create the `Dockerfile-x` file with `buildx` platform support:\n\n    ```console\n    ./buildx-dockerfile.sh\n    ```\n\n1. Build the image using `buildx`:\n\n    ```console\n    docker buildx build \\\n      --file Dockerfile-x \\\n      --platform linux/amd64 \\\n      --build-arg VERSION=0.1.4 \\\n      --output type=docker \\\n      --tag cisagov/certboto:0.1.4 .\n    ```\n\n## AWS policies ##\n\n### Certboto roles ###\n\nThe `BUCKET_PROFILE` should assume a role with the following policy:\n\n```javascript\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"VisualEditor0\",\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"s3:PutObject\",\n                \"s3:GetObject\",\n                \"s3:ListBucket\",\n                \"s3:DeleteObject\"\n            ],\n            \"Resource\": [\n                \"arn:aws:s3:::cert-bucket-name\",\n                \"arn:aws:s3:::cert-bucket-name/*\"\n            ]\n        }\n    ]\n}\n```\n\nThe `DNS_PROFILE` should assume a role with the following policy:\n\n```javascript\n{\n    \"Version\": \"2012-10-17\",\n    \"Id\": \"certbot-dns-route53 sample policy\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"route53:ListHostedZones\",\n                \"route53:GetChange\"\n            ],\n            \"Resource\": [\n                \"*\"\n            ]\n        },\n        {\n            \"Effect\" : \"Allow\",\n            \"Action\" : [\n                \"route53:ChangeResourceRecordSets\"\n            ],\n            \"Resource\" : [\n                \"arn:aws:route53:::hostedzone/YOURHOSTEDZONEID\"\n            ]\n        }\n    ]\n}\n```\n\n### Certificate access role ###\n\nTo access a specific certificate, a role with the following profile should be\nassumed:\n\n```javascript\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Sid\": \"allow-cert-read\",\n            \"Effect\": \"Allow\",\n            \"Action\": \"s3:GetObject\",\n            \"Resource\": \"arn:aws:s3:::cert-bucket-name/live/lemmy.imotorhead.com/*\"\n        }\n    ]\n}\n```\n\n### Accessing and installing certificates at instance boot time ###\n\nThe certificates created by Certboto can be installed on a booting instance\nusing [cloud-init](https://cloudinit.readthedocs.io/en/latest/).  An implementation\nof this can be found in the\n[openvpn-server-tf-module](https://github.com/cisagov/openvpn-server-tf-module)\nproject.  Specifically\n[`install-certificates.py`](https://github.com/cisagov/openvpn-server-tf-module/blob/develop/cloudinit/install-certificates.py)\n\n## Contributing ##\n\nWe welcome contributions!  Please see [`CONTRIBUTING.md`](CONTRIBUTING.md) for\ndetails.\n\n## License ##\n\nThis project is in the worldwide [public domain](LICENSE).\n\nThis project is in the public domain within the United States, and\ncopyright and related rights in the work worldwide are waived through\nthe [CC0 1.0 Universal public domain\ndedication](https://creativecommons.org/publicdomain/zero/1.0/).\n\nAll contributions to this project will be released under the CC0\ndedication. By submitting a pull request, you are agreeing to comply\nwith this waiver of copyright interest.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisagov%2Fcertboto-docker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcisagov%2Fcertboto-docker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcisagov%2Fcertboto-docker/lists"}