Custom certificates

Note: since version 2.5, YunoHost integrates Let's Encrypt certificates automated management. You can easily and freely install a Let's Encrypt certificate. The following document describes the steps for installing a paid certificate from a certification authority (Gandi, RapidSSL, StartSSL, Cacert).

Some changes have taken place which impact the procedures indicated below:

  • Metronome group is no longer used directly but ssl-cert.
  • A /etc/yunohost/certs/DOMAIN.LTD-history/stamp directory is used to keep each configuration created and a symlink is created.

Adding a signed certificate by an authority (other than Let's Encrypt)

After the certificate creation with your registration authority, you must have a private key, the key file, and a public certificate, the crt file.

Note that the key file is very sensitive, it is strictly personal and must be very well secured.

These two files should be copied to the server, if they are not already there.

scp CERTIFICATE.crt admin@DOMAIN.TLD:ssl.crt
scp KEY.key admin@DOMAIN.TLD:ssl.key

From Windows, scp can be used with Putty, by downloading the tool pscp

pscp -P 22 CERTIFICATE.crt admin@DOMAIN.TLD:ssl.crt
pscp -P 22 KEY.key admin@DOMAIN.TLD:ssl.key

As soon as the files are on the server, the rest of the work will be done on it. In ssh or locally. First, create a folder to store the obtained certificates.

sudo mkdir /etc/yunohost/certs/DOMAIN.TLD/ae_certs
sudo mv ssl.key ssl.crt /etc/yunohost/certs/DOMAIN.TLD/ae_certs/

Then, go to the parent folder to continue.

cd /etc/yunohost/certs/DOMAIN.TLD/

As a caution, back up the certificates of origin from YunoHost.

sudo mkdir yunohost_self_signed
sudo mv *.pem *.cnf yunohost_self_signed/

Depending on the registration authority, intermediate and root certificates must be obtained.


sudo wget -O ae_certs/ca.pem
sudo wget -O ae_certs/intermediate_ca.pem


sudo wget -O ae_certs/intermediate_ca.pem


sudo wget -O ae_certs/intermediate_ca.pem


sudo wget -O ae_certs/ca.pem
sudo wget -O ae_certs/intermediate_ca.pem

Intermediate and root certificates must be combined with the obtained certificate to create a unified certificate chain.

cat ae_certs/ssl.crt ae_certs/intermediate_ca.pem ae_certs/ca.pem | sudo tee crt.pem

The private key must be converted to .pem format.

sudo openssl rsa -in ae_certs/ssl.key -out key.pem -outform PEM

To ensure the certificates syntax, check the files contents.

cat crt.pem key.pem

The certificates and private key should look like this:


Finally, secure your certificate files.

sudo chown root:metronome crt.pem key.pem
sudo chmod 640 crt.pem key.pem
sudo chown root:root -R ae_certs
sudo chmod 600 -R ae_certs

Now the certificates (two files with the extension .pem) must be copied in /etc/yunohost/certs/DOMAIN.TLD.

cp ae_certs/*.pem ./

Reload NGINX configuration to take into account the new certificate.

sudo service nginx reload

Your certificate is ready. However, you can ensure that it is in place by testing the certificate using the geocerts.

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to suggest changes.