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!
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
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
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 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
In order to renew all of your certificates you can just run
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
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.
You may need to customise the behaviour of the scripts by setting environment variables if you have a non-standard setup.
|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|