{"id":20181927,"url":"https://github.com/devteds/ssl-agent","last_synced_at":"2025-09-08T06:42:44.473Z","repository":{"id":132073122,"uuid":"107894860","full_name":"devteds/ssl-agent","owner":"devteds","description":"Containerized (Docker) ACME client for SSL automation with Let'sEncrypt","archived":false,"fork":false,"pushed_at":"2017-10-22T19:39:13.000Z","size":6,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-10T05:12:24.941Z","etag":null,"topics":["acme","acme-client","acme-protocol","automation","docker","docker-compose","free-ssl-certificates","lets-encrypt","letsencrypt","ssl","ssl-agent","ssl-automation","ssl-certificate"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/devteds.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-10-22T19:11:29.000Z","updated_at":"2024-03-20T22:18:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"347d56d4-83d0-48d9-bb6c-feece3705ad5","html_url":"https://github.com/devteds/ssl-agent","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/devteds/ssl-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fssl-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fssl-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fssl-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fssl-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devteds","download_url":"https://codeload.github.com/devteds/ssl-agent/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devteds%2Fssl-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274146689,"owners_count":25230116,"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-09-08T02:00:09.813Z","response_time":121,"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":["acme","acme-client","acme-protocol","automation","docker","docker-compose","free-ssl-certificates","lets-encrypt","letsencrypt","ssl","ssl-agent","ssl-automation","ssl-certificate"],"created_at":"2024-11-14T02:37:09.239Z","updated_at":"2025-09-08T06:42:44.451Z","avatar_url":"https://github.com/devteds.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Automate SSL Certificate creation and renewal with Docker\n\nDockerization of ACME client implementation that can be used to automate creating and renewal of SSL certificates. It uses [acme-client](https://github.com/unixcharles/acme-client), a client implementation of [ACME](https://letsencrypt.github.io/acme-spec) protocol in ruby.\n\n## References\n\n- ACME Implementation in ruby: https://github.com/unixcharles/acme-client\n- ACME (Auomated Certificate Management Environment): https://en.wikipedia.org/wiki/Automated_Certificate_Management_Environment\n- Let's Encrypt: https://letsencrypt.org/how-it-works/\n\n## With Docker Compose\n\n### Docker Compose file\n\n- Create a docker-compose.yml file. Below is an example compose file\n- Set environment variables in compose servie definition - Refer below for environment variable details\n- Map volumes on the docker host for web server doc root and a directory for certs\n\n```\nversion: '3'\nservices:\n  ssl-agent:\n    image: devteds/ssl-agent:latest\n    environment:\n      LETSENCRYPT_ENV: staging\n      CONTACT_EMAIL: youremailaddress@domain.xxx\n      DOMAIN_NAMES: devteds.xyz\n    volumes:\n      - \"/root/website/html:/ssl-agent/webserver-root:rw\"\n      - \"/root/website/certs:/ssl-agent/certs:rw\"\n```\n\n### Docker Host\n\nIf you are using Docker Machine, set docker environment variables to point to the docker host where you have your web-server running.\n\n```\neval $(docker-machine env \u003cMACHINE NAME\u003e)\n```\n\nThe nginx doc root and certs folder should be as mentioned under volumes in the compose service 'ssl-agent' definition. Update otherwise.\n\n### Create new certificate\n\nThis will require two types of private keys. One for the certificate and other for registering with Let's Encrypt as well as for Domain Validation process. If you have private keys, copy those files in the certs directory and set environment variables ACCT_PRIVATE_KEY_FILENAME and CERT_PRIVATE_KEY_FILENAME in the compose file.\n\nIf you don't have private keys, this command will first generate private keys for both account registration and certificate.\n\n```\ndocker-compose run --rm ssl-agent create\n```\n\nThis will place the certificate file under certs folder. Also, if you it generated the private keys, those will be placed in certs folder. It will not delete or move private keys if you supplied any.\n\n\n### Renew certificate\n\nThis will skip the account registration step but will check if the domain names are verified. This will require both the private keys that was used or created when the certificate was created.\n\nMake sure the private keys are placed under certs directory. If you don't have the previous private keys, you might want to create a new one instead of attempting to renew.\n\n```\ndocker-compose run --rm ssl-agent renew\n```\n\n## Without Docker Compose\n\nFollow the same notes as described for creation and renewal with docker compose above.\n\nYou can either run the docker command remotely by setting DOCKER_HOST environment or with docker machine environment variables. \n\n```\neval $(docker-machine env \u003cMACHINE NAME\u003e)\n```\n\nOr you can run the commands directly on the docker host where you have your webserver is running.\n\n```\ndocker-machine ssh \u003cMACHINE NAME\u003e\n# or ssh to server\n```\n\n### Create new certificate\n\n```\ndocker run -it -e LETSENCRYPT_ENV=staging -e DOMAIN_NAMES=YOURDOMAIN.COM -e CONTACT_EMAIL=YOURMEMAIL@DOMAIN.COMM -v \"\u003cNGINX ROOT ON DOCKER HOST\u003e:/ssl-agent/webserver-root:rw\" -v \"\u003cDIRECTORY FOR CERTS \u0026 KEYS\u003e:/ssl-agent/certs:rw\" devteds/ssl-agent:latest create\n```\n\n### Renew certificate\n\n```\ndocker run -it -e LETSENCRYPT_ENV=staging -e DOMAIN_NAMES=YOURDOMAIN.COM -e CONTACT_EMAIL=YOURMEMAIL@DOMAIN.COMM -v \"\u003cNGINX ROOT ON DOCKER HOST\u003e:/ssl-agent/webserver-root:rw\" -v \"\u003cDIRECTORY FOR CERTS \u0026 KEYS\u003e:/ssl-agent/certs:rw\" devteds/ssl-agent:latest renew\n```\n\n## Environment Variables\n\n**LETSENCRYPT_ENV**\n\nValues can either be prod or staging. Use staging while you test the process. Certificates issues on Let's Encrypt staging are not trusted ones or are more like self-signed but it will let you test the automation of SSL cert creation and renewal. Use 'prod' when you configure for prod. Below is how it maps to Let's Encrypt API endpoints\n\n- staging: https://acme-staging.api.letsencrypt.org/\n- prod:  https://acme-v01.api.letsencrypt.org/\n\n**CONTACT_EMAIL**\n\nEmail address for account registration with Let's Encrypt\n\n**DOMAIN_NAMES**\n\nCommand seperated domain names that you want to create or renew certificates for. These domain names should resolve to the web server (nginx) that serves resources from the root directory that you mapped under volumes for '/ssl-agent/webserver-root'\n\n**ACCT_PRIVATE_KEY_FILENAME**\n\n*Default:* acct_private_key.pem\n\nFile name of the private key used for account registration and domain verification. You may either supply a private key or let ssl-agent generate one. If you would like to supply one, set this environment variable with the file name and place the file in the certificates directory that you mounted to '/ssl-agent/certs'\n\n**CERT_PRIVATE_KEY_FILENAME**\n\n*Default:* cert_private_key.pem\n\nFile name of the private key used for certificate creation or renewal. You may either supply a private key or let ssl-agent generate one. If you would like to supply one, set this environment variable with the file name and place the file in the certificates directory that you mounted to '/ssl-agent/certs'\n\n**OBTAINED_CERT_FILENAME**\n\n*Default:* cert_fullchain.pem\n\nName of the generated or renewed certificate. If you would like to name this file differently in your nginx configuration, specify that name. Or you can copy the generated certificate file to a location or path where it gets used by nginx.\n\n## Volumes\n\n**Directory for certs**\n\nThis is where ssl-agent container will read and write certificate files to/from.\n\n**Nginx root**\n\nDuring the domain authorization verification step, ssl-agent will create a folder under this directory \".well-known/acme/\" to place the verification challenge file which then Let's Encrypt will try to access using the URL on the domain name you're attempting to generate the certificate for.\n\nThis directory should be your nginx root or the root that serves content for '/.well-known/*'\n\n## Customize and build your image\n\nClone this repo, customize for your needs and build your image\n\n```\ndocker-compose build\ndocker tag devteds/ssl-agent:latest \u003cYOUR PRIVATE REGISTRY URL\u003e:latest\n# docker tag devteds/ssl-agent:latest devteds/ssl-agent:v1.0\n# docker push devteds/ssl-agent:v1.0\n# docker push devteds/ssl-agent:latest\ndocker push \u003cYOUR PRIVATE REGISTRY URL\u003e:latest\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevteds%2Fssl-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevteds%2Fssl-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevteds%2Fssl-agent/lists"}