Using Certbot to get single domain certificates

You can use Certbot to easily get single domain certificates (non-wildcard, you can actually get a certificate that covers several domains) using web root verification.

Requirements and preliminary information

• You must be using a Linux OS

• Certbot is supported on macOS but these instructions and the scripts provided in Mango may not work on macOS

• Certbot is not supported on Windows, other LetsEncrypt clients do exist but these instructions are for Certbot

• You must be running Mango version >= 3.5.4 so the certificate keystore can be automatically be reloaded and the scripts are present

• Mango must be accessible on the internet via HTTP on port 80 using the domain name that you are trying to get a certificate for

• Throughout these instructions Mango is assumed to be installed at /opt/mango, this may be different for your installation

• You may need to set environment variables to customise the behaviour of the deploy/keygen script, see the section at the bottom

• Run all the commands listed as root, be careful!

Install Certbot

Follow the instructions from https://certbot.eff.org/ to install Certbot on your particular Linux distribution. If you have trouble you might consider the alternative installation methods.

Configure your env.properties file

Ensure Mango is stopped

/opt/mango/bin/ma.sh stop > /dev/null 2>&1

Edit your env.properties file

nano /opt/mango/overrides/properties/env.properties

Use the following settings

Ensure that you have an initial temporary keystore

In order to start mango you need to have a keystore in the location specified in your env.properties file. You can generate a temporary one (a self signed certificate) by running

/opt/mango/bin/genkey.sh

Or you can manually generate one my using keytool which is supplied with your Java installation

keytool -genkey -alias mango -keystore /opt/mango/overrides/keystore.jks

Ensure your keystore has the correct owner and permissions so it remains private. Assuming that you run Mango under the user mango and group mango

chown mango:mango /opt/mango/overrides/keystore.jks

chmod 400 /opt/mango/overrides/keystore.jks

Start Mango

Start Mango and wait for it to fully initialise

/opt/mango/bin/ma.sh start > /dev/null 2>&1

Run Certbot to get your initial certificate

You might need to use certbot-auto instead of certbot depending on your installation method.

Certbot will ask you for your email and ask you to agree to the terms of service. Provided you set everything up correctly it should tell you everything was successful. You should see that certbot ran the certbot-deploy.sh script. The deploy script will automatically use the keystore password from your env.properties file.

Check your ma.log file, you should see a line at the bottom telling you that Mango reloaded your keystore.

If you need to change any of the environment variables (see bottom of document) you can add them like so

Renewing certificates

In order to renew all of your certificates you can just run

certbot renew

Certbot knows how to verify your domain from a configuration file located at /etc/letsencrypt/renewal/yourdomain.com, and knows to run the deploy script so Mango gets an updated Java keystore.

Scheduling automated renewal

You probably want to automate the renewal process, you simply need to setup a cron job to run Certbot renewal command.

Edit the root crontab

crontab -e

Add the following line so certbot runs twice a day (first number is the minutes, you can randomize this)

0 */12 * * * root /usr/bin/certbot renew --quiet

Re-creating your keystore

If you have any issues with getting certificates from Let’s Encrypt you might want to manually trigger the deploy script to create your keystore from the Certbot certificate directory.

RENEWED_LINEAGE=/etc/letsencrypt/live/yourdomain.com /opt/mango/bin/certbot-deploy.sh

Environment variables

You may need to customise the behaviour of the scripts by setting environment variables if you have a non-standard setup.