Enable Automatic Let’s Encrypt SSL on Yunohost: From Domain Addition to Verification

Desired Outcome

Automatically provision and renew a valid Let’s Encrypt TLS certificate for a new domain on Yunohost, ensuring the web server presents a trusted certificate without manual intervention.

Prerequisites

• Yunohost 2.x (or later) installed and running on a machine with a public IP.
• Root or sudo access to the host.
• Domain name (e.g., example.com) whose DNS records can be edited.
• Port 80 reachable from the internet and not blocked by a firewall or NAT.
• Basic command‑line familiarity (bash, dig, openssl).

Step‑by‑Step Procedure

1. Point the Domain to the Server

Configure DNS so that example.com resolves to the server’s public IP. Use an A record for the apex domain or a CNAME for subdomains.

# Example for apex domain
example.com.  IN  A  203.0.113.10
# Example for a subdomain
mail.example.com.  IN  CNAME  example.com.

Verify resolution from the server:

dig +short example.com

2. Ensure Port 80 Is Exposed

Yunohost uses the HTTP‑01 challenge on port 80. Confirm the port is open:

sudo ufw allow 80/tcp
# or for iptables
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT

3. Add the Domain to Yunohost

Run the domain‑add command. Yunohost will automatically request a Let’s Encrypt certificate during this step.

sudo yunohost domain add --domain example.com

During execution you should see messages indicating:

• Domain added to /etc/yunohost/domain.conf
• ACME client started and HTTP‑01 challenge requested
• Certificate stored in /etc/ssl/yunohost/domains/example.com/

4. Verify the Certificate Issuance

1. Check the domain list for a ready status:

   sudo yunohost domain list
   

2. Validate the SSL handshake with openssl:

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

   Look for issuer "Let's Encrypt Authority X3" and expiry dates.

3. Review the SSL log for a successful challenge:

   sudo tail -n 20 /var/log/yunohost/ssl.log
   

4. Confirm the web server reloaded after renewal (if applicable):

   sudo grep -i Reloaded /var/log/yunohost/apache2/error.log | tail -1
   

Troubleshooting & Recovery

• HTTP‑01 challenge fails: Ensure port 80 is reachable from the public internet. Test with curl http://example.com/.well-known/acme-challenge/test from an external host.
• DNS not propagated: Wait for TTL to expire or use dig +trace example.com to confirm propagation.
• Conflicting DNS records: Remove any other CNAME or TXT entries that could interfere with the challenge path.
• Firewall blocks inbound HTTP: Verify with sudo ufw status or iptables -L INPUT -n -v and open the port.
• Certificate not present: Inspect /etc/ssl/yunohost/domains/example.com/ for fullchain.pem and privkey.pem. If missing, delete the domain entry and retry.

Recovery: Re‑add Domain

If the domain was added but the certificate never issued, remove it and re‑add:

sudo yunohost domain delete example.com
sudo yunohost domain add --domain example.com

After re‑adding, re‑run the verification steps above.

Automatic Renewal

Yunohost schedules a cron job that renews certificates 30 days before expiry. No manual action is required. To force a renewal for testing:

sudo yunohost ssl renew --domain example.com

Verify that a new certificate appears in /etc/ssl/yunohost/domains/example.com/ and that the web server reloads.

Key Takeaways

• Adding a domain via yunohost domain add automatically provisions a Let’s Encrypt certificate.
• Port 80 must be publicly reachable; DNS A/CNAME records must point to the server.
• Use openssl s_client and log files to verify successful issuance and renewal.
• Automatic renewal keeps the domain secure without manual intervention.