TLS termination using Let's Encrypt
As you know, Otoroshi is capable of doing TLS termination for your services. You can import your own certificates, generate certificates from scratch and you can also use the @link:ACME protocol to generate certificates. One of the most popular service offering ACME certificates creation is @link:Let's Encrypt.
In order to make this tutorial work, your otoroshi instance MUST be accessible from the internet in order to be reachable by Let's Encrypt ACME process. Also, the domain name used for the certificates MUST be configured to reach your otoroshi instance at your DNS provider level.
this tutorial can work with any ACME provider with the same rules. your otoroshi instance MUST be accessible by the ACME process. Also, the domain name used for the certificates MUST be configured to reach your otoroshi instance at your DNS provider level.
Setup let's encrypt on otoroshi
Go on the danger zone page by clicking on the cog icon / Danger Zone. Scroll to the Let's Encrypt settings section. Enable it, and specify the address of the ACME server (for production Let's Encrypt it's acme://letsencrypt.org, for testing, it's acme://letsencrypt.org/staging. Any ACME server address should work). You can also add one or more email addresses or contact urls that will be included in your Let's Encrypt account. You don't have to fill the public/private key inputs as they will be automatically generated on the first usage.
Creating let's encrypt certificate from FQDNs
You can go to the certificates page by clicking on the cog icon / SSL/TLS Certificates. Here, click on the + Let's Encrypt certificate button. A popup will show up to ask you the FQDN that you want for you certificate. Once done, click on the Create button. A few moment later, you will be redirected on a brand new certificate generated by Let's encrypt. You can now enjoy accessing your service behind the FQDN with TLS.
Creating let's encrypt certificate from a route
Open any route in the designer, go to the Informations tab and enable the Issue a Let's Encrypt Certificate flag (it is stored as the otoroshi-core-issue-lets-encrypt-certificate metadata). Do not forget to save your route. A few moment later, the certificate will be available in the certificates page and you will be able to enjoy accessing your route with TLS.
Otoroshi checks for routes needing a certificate every 2 minutes, so a route whose domain is not covered yet gets one shortly after being saved. In cluster mode this only runs on the leader.
Renewal
Otoroshi renews its ACME certificates automatically, in place: the renewed chain is written back into the same certificate entity, which keeps its id, so a renewal never adds an entity and never changes the id your routes may refer to. The certificate is re-ordered for every domain it covers, so multi-SAN certificates keep their SANs.
By default a certificate is renewed once less than 20 % of its total lifetime remains — 18 days for a 90-day Let's Encrypt certificate. Two settings in Danger Zone / Let's Encrypt settings let you change that:
| Setting | Default | Meaning |
|---|---|---|
Renewal threshold (%) | 20 | renew once less than this percentage of the total lifetime remains |
Renew before (days) | empty | absolute margin in days. When set, it takes precedence over the percentage |
A pure percentage degrades on short-lived certificates: public CAs are moving to 100-day certificates in March 2027 and 47-day ones in March 2029, where 20 % is only 9 days. Set Renew before (days) to get a fixed margin instead.
The renewal job runs about once an hour, and on the leader only when running in cluster mode.
Cleaning up old certificates
Every renewal keeps a copy of the previous certificate, named [UNTIL EXPIRATION] <name>. That copy exists for keypairs: JWT verifiers use it to keep validating tokens signed with the previous key. It serves no purpose for a TLS server certificate, and nothing ever deletes it.
Enable Delete old certificates after renewal in Danger Zone / Let's Encrypt settings to stop keeping those copies for Let's Encrypt certificates. It only ever applies to certificates flagged letsEncrypt, so keypair rotation is left untouched. It is opt-in: deleting certificates on your behalf is not a decision Otoroshi makes silently.
If your instance already accumulated duplicated certificates, a maintenance endpoint collapses them:
# what would be deleted (dry run by default)
curl -X POST -u 'admin-api-apikey-id:admin-api-apikey-secret' \
'http://otoroshi-api.oto.tools:8080/api/certificates/_dedupLetsEncrypt'
# actually delete them, expired leftovers included
curl -X POST -u 'admin-api-apikey-id:admin-api-apikey-secret' \
'http://otoroshi-api.oto.tools:8080/api/certificates/_dedupLetsEncrypt?dryRun=false&deleteExpired=true'
It only ever touches certificates flagged letsEncrypt, and it collapses each group of entities holding the exact same chain down to a single one. With deleteExpired=true it also drops expired Let's Encrypt certificates, but only for domains that are still covered by a surviving certificate — it can never leave a domain without one.
Troubleshooting
A failed ACME order is reported as such: the certificate is left untouched, no [UNTIL EXPIRATION] copy is created, and a CertRenewalFailedAlert is emitted carrying the error. Look for otoroshi-lets-encrypt-helper in the logs to see the reason returned by the ACME server.