{"id":16179389,"url":"https://github.com/valb3r/letsencrypt-helper","last_synced_at":"2025-03-19T01:30:58.297Z","repository":{"id":45567308,"uuid":"425714819","full_name":"valb3r/letsencrypt-helper","owner":"valb3r","description":"Generates and keeps up-to-date your Spring Boot applications' Let's Encrypt or other ACME compliant SSL certificates. Pure Java in a single file of library code. An automated embedded alternative to Certbot and docker-sidecars. No JVM restart is needed on certificate update.","archived":false,"fork":false,"pushed_at":"2024-05-18T07:37:25.000Z","size":180,"stargazers_count":39,"open_issues_count":9,"forks_count":5,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-03-17T01:41:20.227Z","etag":null,"topics":["acme","autorenew","java","letsencrypt","letsencrypt-certificates","spring-boot","ssl","ssl-certificate","tomcat"],"latest_commit_sha":null,"homepage":"https://valb3r.github.io/letsencrypt-helper","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/valb3r.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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":"2021-11-08T05:55:05.000Z","updated_at":"2025-03-10T17:13:55.000Z","dependencies_parsed_at":"2024-10-10T05:33:54.441Z","dependency_job_id":"0a7d094a-5988-4855-9c3a-af3767e5153b","html_url":"https://github.com/valb3r/letsencrypt-helper","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valb3r%2Fletsencrypt-helper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valb3r%2Fletsencrypt-helper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valb3r%2Fletsencrypt-helper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/valb3r%2Fletsencrypt-helper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/valb3r","download_url":"https://codeload.github.com/valb3r/letsencrypt-helper/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244336141,"owners_count":20436774,"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","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","autorenew","java","letsencrypt","letsencrypt-certificates","spring-boot","ssl","ssl-certificate","tomcat"],"created_at":"2024-10-10T05:27:42.090Z","updated_at":"2025-03-19T01:30:57.961Z","avatar_url":"https://github.com/valb3r.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![](https://jitpack.io/v/valb3r/letsencrypt-helper.svg)](https://jitpack.io/#valb3r/letsencrypt-helper)\n\n# What is this\n\nIf you have ever tried getting Let's Encrypt certificate for Spring Boot application, you know that it is painful as\nit involves using either CertBot or Docker-sidecar/Cron-job to manage certificate lifecycle, especially if it is small pet application. This library solves these\nproblems by managing certificate lifecycle directly in Java code with the help of awesome [Acme4j](https://github.com/shred/acme4j) library.\n\n**Note: This version is for Spring Boot 3.x and Spring 6.x, for older Spring/Spring Boot versions see [Release 0.2.5](https://github.com/valb3r/letsencrypt-helper/tree/67f28268c5c8882ce8f1821c7b6940e3abfcf906)**\n\n## Key features:\n\n1. Obtain Let's Encrypt certificate on fresh start (or from other ACME compliant certificate provider)\n2. Store generated keys and certificate into single KeyStore (`server.ssl.keystore`)\n3. Renew Let's Encrypt certificate (it watches for certificate expiration date and updates it to new before old is expired)\n4. **No JVM restart needed** when certificate gets updated\n\n# Application requirements\n\nTo perform HTTP-01 ACME (Automatic Certificate Management Environment) challenge, the application must listen on port `80`, this library will automatically create\nTomcat connector to this port, so the only thing needed on your side is to open `80` port for the application.\n\n# Servlet containers supported (embedded)\n\n - [Tomcat](tomcat)\n - [Jetty](jetty)\n \n# Usage\n\n## From JitPack maven repository\n\n### 1. Import this library:\n\n#### For Tomcat:\n##### Gradle:\n```groovy\n allprojects {\n     repositories {\n         ...\n         maven { url 'https://jitpack.io' }\n     }\n }\n\ndependencies {\n   implementation 'com.github.valb3r.letsencrypt-helper:letsencrypt-helper-tomcat:0.4.0'\n}\n```\n##### Maven:\n```xml\n\u003crepositories\u003e\n     \u003crepository\u003e\n         \u003cid\u003ejitpack.io\u003c/id\u003e\n         \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n     \u003c/repository\u003e\n \u003c/repositories\u003e\n\n\u003cdependencies\u003e\n   \u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.valb3r.letsencrypt-helper\u003c/groupId\u003e\n      \u003cartifactId\u003eletsencrypt-helper-tomcat\u003c/artifactId\u003e\n      \u003cversion\u003e0.4.0\u003c/version\u003e\n   \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n\n#### For Jetty:\n##### Gradle:\n```groovy\n allprojects {\n     repositories {\n         ...\n         maven { url 'https://jitpack.io' }\n     }\n }\n\ndependencies {\n   implementation 'com.github.valb3r.letsencrypt-helper:letsencrypt-helper-jetty:0.4.0'\n}\n```\n##### Maven:\n```xml\n\u003crepositories\u003e\n     \u003crepository\u003e\n         \u003cid\u003ejitpack.io\u003c/id\u003e\n         \u003curl\u003ehttps://jitpack.io\u003c/url\u003e\n     \u003c/repository\u003e\n \u003c/repositories\u003e\n\n\u003cdependencies\u003e\n   \u003cdependency\u003e\n      \u003cgroupId\u003ecom.github.valb3r.letsencrypt-helper\u003c/groupId\u003e\n      \u003cartifactId\u003eletsencrypt-helper-jetty\u003c/artifactId\u003e\n      \u003cversion\u003e0.4.0\u003c/version\u003e\n   \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\n### 2. Declare on your configuration\n#### Tomcat:\n`@Import(TomcatWellKnownLetsEncryptChallengeEndpointConfig.class)`\n\n#### Jetty:\n`@Import(JettyWellKnownLetsEncryptChallengeEndpointConfig.class)`\n\n\n### 3. Define following properties in your application configuration or environment:\n 1. `lets-encrypt-helper.domain` the domain to issue certificate for\n 2. `lets-encrypt-helper.contact` your contact for Let's Encrypt (i.e. your email in format `mailto:john.doe@example.com`)\n\n\n### 4. Configure SSL as usual for Tomcat+TLS using `server.ssl.keystore` for certificate and keys storage\n\n\n### 5. Ensure your security layer (i.e. Spring security) allows anonymous access to `/.well-known/acme-challenge/*` paths\n\n\n## Configuration\n\n\n| Property                                                   | Description                                                                                                             | Default value, if any  |\n|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|------------------------|\n| server.ssl.key-store                                       | Path to the KeyStore, where Let's Encrypt certificates and account key are to be stored (or are already there)          |                        |\n| server.ssl.key-store                                       | KeyStore type (i.e. PKCS12)                                                                                             |                        |\n| server.ssl.key-store-pasword                               | Password for KeyStore with Let's Encrypt certificate and account key                                                    |                        |\n| server.ssl.key-alias                                       | Let's Encrypt certificate key alias in the keystore                                                                     |                        |\n| server.port                                                | Port (secure SSL/TLS) on which your application is deployed                                                             |                        |\n| lets-encrypt-helper.domain                                 | Your applications' domain (i.e. example.com)                                                                            |                        |\n| lets-encrypt-helper.contact                                | The contact of person responsible for the domain (i.e. mailto:john@example.com)                                         |                        |\n| lets-encrypt-helper.account-key-alias                      | Account key alias                                                                                                       | letsencrypt-user       |\n| lets-encrypt-helper.letsencrypt-server                     | Let's Encrypt server to use                                                                                             | acme://letsencrypt.org |\n| lets-encrypt-helper.key-size                               | Certificate and Account key RSA key size                                                                                | 2048                   |\n| lets-encrypt-helper.update-before-expiry                   | Start trying to update certificate this time before expiration                                                          | P30D (30 days)         |\n| lets-encrypt-helper.busy-wait-interval                     | Busy wait interval for thread that checks if the certificate is valid                                                   | PT1M (1 minute)        |\n| lets-encrypt-helper.account-cert-validity                  | Validity duration for Account key                                                                                       | P3650D (3650 days)     |\n| lets-encrypt-helper.store-cert-chain                       | Store entire trust chain or only domain certificate (for browsers domain ceritificate is enough)                        | true                   |\n| lets-encrypt-helper.enabled                                | Is the helper enabled                                                                                                   | true                   |\n| lets-encrypt-helper.return-null-model                      | If challenge endpoint should return null model (i.e. `true` is sane default for cases with Thymeleaf rendering the page) | true                   |\n| lets-encrypt-helper.development-only.http01-challenge-port | For development only, port for HTTP-01 ACME challenge                                                                   | 80                     |\n\n\n### Example configuration\n\nLaunch your application with `-Dspring.profiles.active=ssl`\n\n`application-ssl.yaml`:\n```yaml\nserver:\n  port: 443\n  ssl:\n    key-store: file:/home/user/letsencrypt/application-keystore # Path to KeyStore with certificates and keys\n    key-store-password: change-me # Password for KeyStore protection\n    key-store-type: PKCS12\n    key-alias: tomcat # Certificate name in KeyStore\n    enabled: true # Important to place this explicitly\nlets-encrypt-helper:\n  domain: my-domain.example.com # Domain to issue certificate for\n  contact: mailto:john.doe@mymail.example.com # Your contact for Let's Encrypt\n```\n\n**Note:** On your server ensure you have opened port `80` for Java (i.e. in Firewall) and Java can bind to it (i.e. follow [Linux allow listening to low port without sudo](https://superuser.com/a/892391) to open ports 80,443 for `java`)\n\n**Example project** with SSL and Let's Encrypt management using this library **[is located here](example)**\n\n## Alternative\n\nThe library is itself just 1 Java class. You can add library dependencies and: \n - [For Tomcat this java file](https://github.com/valb3r/letsencrypt-helper/blob/master/tomcat/src/main/java/com/github/valb3r/letsencrypthelper/tomcat/TomcatWellKnownLetsEncryptChallengeEndpointConfig.java)\nto your configuration\n - [For Jetty this java file](https://github.com/valb3r/letsencrypt-helper/blob/master/jetty/src/main/java/com/github/valb3r/letsencrypthelper/jetty/JettyWellKnownLetsEncryptChallengeEndpointConfig.java)\nto your configuration\n\n\n## Testing locally\n\nThe library has integration tests in:\n - [tomcat/src/test/java](tomcat/src/test/java) \n - [jetty/src/test/java](jetty/src/test/java)\n\ndirectories. One can adapt these tests according to own needs, as they use Pebble - LetsEncrypt testing server.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalb3r%2Fletsencrypt-helper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvalb3r%2Fletsencrypt-helper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvalb3r%2Fletsencrypt-helper/lists"}