How Yunohost’s Let’s Encrypt Integration Secures Your Domains Automatically

Why Let’s Encrypt is the Default for Yunohost

When you add a new domain to a Yunohost instance, the platform automatically runs the ACME protocol against Let’s Encrypt, installs the resulting TLS certificates, and keeps them fresh. This feature removes the manual steps of creating a CSR, uploading a CSR, and configuring the web server for HTTPS.

Enabling HTTPS with a Single Command

Assuming your domain’s A/AAAA records point to the public IP of the Yunohost server and ports 80/443 are reachable, you can trigger the whole flow with:

sudo yunohost domain add example.com

The command performs the following actions:

• Creates a new domain entry in Yunohost’s configuration.
• Runs the ACME challenge via HTTP‑01 (listening on port 80).
• Downloads the signed certificate from Let’s Encrypt.
• Stores the certificate chain in /etc/yunohost/certs/example.com/ and the private key in /etc/yunohost/certs/example.com/privkey.pem.
• Reloads the web server (NGINX or Apache) so the new cert is served immediately.

Verifying the Certificate is Served

After the command finishes, confirm the HTTPS setup by inspecting the certificate chain:

openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -issuer -subject

You should see the issuer as Let's Encrypt Authority X3 and the subject matching CN=example.com. A quick browser check (https://example.com) should also show a valid lock icon.

Automatic Renewal and Logging

Yunohost schedules a daily cron job that calls certbot renew under the hood. Certificates are renewed 30 days before expiry. Renewal attempts and outcomes are logged to:

/var/log/yunohost/letsencrypt.log

To inspect the current status of all domains and whether HTTPS is enforced, run:

yunohost domain list

Each domain entry will show an https flag set to yes if the certificate is active.

Enforcing HTTPS Redirects

Yunohost can automatically redirect HTTP traffic to HTTPS by adding the httpsRedirect option to the domain configuration:

sudo yunohost domain edit example.com --httpsRedirect true

Alternatively, edit the virtual host file (e.g., /etc/yunohost/websites/example.com.conf) to include the Redirect permanent / https://example.com/ directive.

Limits and Common Pitfalls

• DNS Propagation: The ACME challenge will fail if the domain’s A/AAAA records are not fully propagated. Wait for DNS to resolve before adding the domain.
• Firewall Rules: Ports 80 and 443 must be open to the public. If a firewall blocks 443, the certificate will be issued but clients will see connection errors.
• Rate Limits: Let’s Encrypt enforces 50 certificates per week per IP. Adding many subdomains or testing repeatedly can hit this limit.
• Wildcard Support: Yunohost does not currently support wildcard certificates out of the box. Each subdomain requires its own entry.
• Service Disruption: Disabling the yunohost domain service stops automatic renewal. Ensure the service is running.
• Misconfigured DNS: A common mistake is pointing the domain to a load balancer that does not forward port 80/443 to Yunohost, causing validation failures.

Practical Checklist Before Adding a Domain

1. Verify DNS A/AAAA records resolve to the Yunohost server’s public IP.
2. Confirm ports 80 and 443 are open (e.g., sudo ufw allow 80/tcp and sudo ufw allow 443/tcp).
3. Run yunohost domain add example.com as root or with sudo.
4. Check /var/log/yunohost/letsencrypt.log for any errors.
5. Use openssl s_client or a browser to validate HTTPS.
6. Enable httpsRedirect if you want all traffic forced to TLS.

What Happens If Renewal Fails?

When a renewal attempt fails, the cron job logs the error and leaves the existing certificate in place. The web server continues to serve the old cert until it expires. You can manually trigger a renewal with:

sudo yunohost domain renew example.com

Review /var/log/yunohost/letsencrypt.log for details and resolve any underlying issues (DNS, firewall, or rate limits) before retrying.

Conclusion

Yunohost’s built‑in Let’s Encrypt integration turns domain addition into a one‑liner that automatically delivers secure HTTPS. By following the checklist above and monitoring the renewal logs, you can confidently keep your domains protected without manual certificate management.