Provisioning Let's Encrypt Certificates and Enforcing HTTPS in Yunohost

Desired outcome

After completing this guide, a domain managed by Yunohost will have a valid Let's Encrypt TLS certificate, Yunohost’s SSOwat/nginx stack will terminate HTTPS for that domain, and all HTTP requests will be automatically redirected to HTTPS.

Prerequisites

1. Administrative access to the Yunohost server (able to run commands with sudo).
2. The domain you want to secure must be registered and its DNS A/AAAA records must point to the public IP address of the Yunohost server.
3. Ports 80 (HTTP) and 443 (HTTPS) must be reachable from the Internet (no firewall or NAT blocking).
4. Yunohost version 4.2 or newer (the built‑in ACME client used in these releases).

Procedure

1. Add the domain to Yunohost (if not already present)

Run the domain‑add command. Replace example.com with your actual domain.

sudo yunohost domain add example.com

This creates the necessary DNS entry (if you manage DNS through Yunohost) and configures a basic web server entry for the domain.

2. Request a Let's Encrypt certificate

Yunohost can automatically issue a certificate when a domain is added, but you can also trigger it manually:

sudo yunohost domain cert-install example.com --force

The --force flag tells Yunohost to request a new certificate even if one already exists. The command runs the ACME client, performs the HTTP‑01 challenge on port 80, and, on success, stores the certificate under /etc/yunohost/certs/example.com/ and reloads nginx/SSOwat.

3. Verify HTTPS enforcement

After the command finishes, Yunohost should have enabled HTTPS and set up a permanent redirect from HTTP to HTTPS. You can check this with a simple curl command from any machine that can reach the server:

curl -I http://example.com

Look for a response header similar to:

HTTP/1.1 301 Moved Permanently
Location: https://example.com/

If you see the 301 redirect and the Location points to HTTPS, enforcement is active.

4. Confirm certificate validity

Inspect the certificate file directly:

sudo openssl x509 -in /etc/yunohost/certs/example.com/crt.pem -noout -dates

Expected output includes notBefore and notAfter dates; the notAfter should be at least 60 days in the future (Let's Encrypt certificates are valid for 90 days).

Expected checks

• Domain resolves publicly: dig +short example.com returns the server’s IP.
• Port 80 reachable: nc -zv example.com 80 succeeds (or use an external port‑scan tool).
• Certificate issuance log: sudo yunohost log display --timestamp --lines 20 shows an ACME success message for the domain.
• HTTPS endpoint responds: curl -I https://example.com returns a 200 OK (or the expected application response) with a valid TLS handshake.

Recovery options

If certificate issuance fails, Yunohost leaves the domain in a “pending” state and logs the ACME error. You can:

1. Fix the underlying issue (DNS, firewall, port 80 availability) and retry the install command:

sudo yunohost domain cert-install example.com --force

1. Force a renewal attempt without waiting for the scheduled job:

sudo yunohost tools renew-certs --domain example.com

1. Temporarily disable HTTPS enforcement for local testing (this does not remove the certificate):

sudo yunohost settings set ssowat.skip_https_redirect -v 1
sudo systemctl reload nginx ssowat

To re‑enable enforcement later, set the value back to 0 and reload the services.

1. Restore a previously working certificate from a backup (if you have one):

sudo cp /path/to/backup/example.com/crt.pem /etc/yunohost/certs/example.com/crt.pem
sudo cp /path/to/backup/example.com/key.pem /etc/yunohost/certs/example.com/key.pem
sudo systemctl reload nginx ssowat

After restoration, verify the certificate dates and HTTPS redirect as described above.

Limitations and practical verification

Let's Encrypt enforces rate limits (currently 50 certificates per registered domain per week). Repeated failed attempts due to mis‑configured DNS or blocked ports can consume these limits and block new issuance for several hours. Before retrying, ensure that:

• The domain’s A/AAAA records are correct and propagate globally.
• Any upstream firewall or cloud security group allows inbound TCP 80 and TCP 443 to the Yunohost host.
• No other service on the server is already listening on port 80 that would interfere with the HTTP‑01 challenge.

You can confirm that the ACME client can reach the challenge file by placing a test file manually:

sudo mkdir -p /var/www/yunohost/ssowat/acme-challenge
sudo echo 'test-content' > /var/www/yunohost/ssowat/acme-challenge/testfile
sudo chown -R www-data:www-data /var/www/yunohost/ssowat/acme-challenge

Then, from an external network, run:

curl http://example.com/.well-known/acme-challenge/testfile

If you see test-content, the challenge path is reachable and the firewall/DNS are configured correctly.

After successful verification, remove the test file:

sudo rm /var/www/yunohost/ssowat/acme-challenge/testfile