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 mango.properties file
Ensure Mango is stopped
/opt/mango/bin/mango-stop.sh > /dev/null 2>&1
Edit your mango.properties file
nano /opt/mango/mango.properties
Use the following settings
ssl.on=true
ssl.keystore.watchFile=true
ssl.keystore.location=/opt/mango-data/keystore.jks
ssl.keystore.password=<Enter a strong generated password here>
#Leave the following setting commented out
#ssl.key.password=
# mango must be accessible on port 80
web.port=80
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. As long as the
mango.properties file variable points to the keystore, the command will work.
keytool -genkey -alias mango -keystore /opt/mango-data/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-data/keystore.jks
chmod 400 /opt/mango-data/keystore.jks
Start Mango
Start Mango and wait for it to fully initialise
/opt/mango/bin/mango-start.sh > /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 certonly --webroot --deploy-hook "/opt/mango/bin/certbot-deploy.sh" -w "/opt/mango/web" -d yourdomain.com -d domain2.com
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
certbot certonly --webroot --deploy-hook "sh -c 'mango_paths_home=/opt/mango /opt/mango/bin/certbot-deploy.sh'" -d yourdomain.com -d domain2.com
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.
Environment variable | Description | Default |
---|---|---|
MA_HOME | Path to the Mango installation directory | The directory below where the script is located or /opt/mango |
MA_ENV_PROPERTIES | Path to env.properties file | $MA_HOME/overrides/properties/env.properties |
MA_KEYSTORE | Path to the keystore file | ssl.keystore.location from env.properties file |
MA_KEYSTORE_PASSWORD | Keystore password | ssl.keystore.password from env.properties file |
MA_KEY_PASSWORD | Password for the individual key inside the keystore | sl.key.password from env.properties or ssl.keystore.password if not specified |
MA_KEY_ALIAS | Alias for the individual key inside the keystore | mango |