Skip to main content

Using Certbot to Get Single Domain Certificates

Certbot allows you to obtain free SSL certificates from Let's Encrypt using web root verification. Mango includes helper scripts that automatically convert the certificate into a Java keystore and reload it without restarting.

Requirements​

  • Linux OS (Certbot is supported on macOS but the Mango helper scripts may not work)
  • Mango version >= 3.5.4 (required for automatic keystore reload and the included deploy scripts)
  • Mango must be accessible on the internet via HTTP on port 80 using the domain name you are requesting a certificate for
  • Certbot is not supported on Windows (other Let's Encrypt clients exist, but these instructions are specific to Certbot)
  • All commands should be run as root
note

Throughout these instructions, Mango is assumed to be installed at /opt/mango. Adjust paths if your installation differs.

Step 1: Install Certbot​

Follow the instructions at https://certbot.eff.org/ for your specific Linux distribution. If you have trouble, try the alternative installation methods.

Step 2: Configure mango.properties​

Stop Mango before making configuration changes:

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

Edit mango.properties:

nano /opt/mango/mango.properties

Set the following properties:

ssl.on=true
ssl.keystore.watchFile=true
ssl.keystore.location=/opt/mango-data/keystore.jks
ssl.keystore.password=YOUR_STRONG_GENERATED_PASSWORD
# Leave ssl.key.password commented out
#ssl.key.password=

# Mango must be accessible on port 80 for domain verification
web.port=80

The ssl.keystore.watchFile=true setting allows Mango to automatically reload the keystore when it changes on disk, which is how Certbot certificate renewals take effect without restarting Mango.

Step 3: Create an Initial Keystore​

Mango requires a keystore to start. Generate a temporary self-signed certificate:

/opt/mango/bin/genkey.sh

Or manually using keytool:

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

Set proper ownership and permissions:

chown mango:mango /opt/mango-data/keystore.jks
chmod 400 /opt/mango-data/keystore.jks

Step 4: Start Mango​

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

Wait for Mango to fully initialize before proceeding.

Step 5: Obtain the Certificate​

Run Certbot to request a certificate using the web root method:

certbot certonly --webroot \
  --deploy-hook "/opt/mango/bin/certbot-deploy.sh" \
  -w "/opt/mango/web" \
  -d yourdomain.com -d www.yourdomain.com

Certbot will:

  1. Ask for your email and terms of service agreement.
  2. Place a challenge file in Mango's web directory.
  3. Verify domain ownership via HTTP.
  4. Download the certificate.
  5. Run the certbot-deploy.sh script, which converts the certificate to a Java keystore.

The deploy script automatically reads the keystore password from your mango.properties file.

Check ma.log -- you should see a message confirming that Mango reloaded the keystore.

Custom Environment Variables​

If you need to override default paths:

certbot certonly --webroot \
  --deploy-hook "sh -c 'mango_paths_home=/opt/mango /opt/mango/bin/certbot-deploy.sh'" \
  -d yourdomain.com

Renewing Certificates​

Let's Encrypt certificates are valid for 90 days. To renew all certificates:

certbot renew

Certbot reads the configuration from /etc/letsencrypt/renewal/yourdomain.com.conf and automatically runs the deploy script to update the Java keystore.

Scheduling Automated Renewal​

Set up a cron job to run Certbot renewal twice daily:

crontab -e

Add the following line:

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

The first number (0) is the minute -- you can randomize this to avoid peak load on Let's Encrypt servers.

Manually Re-Creating the Keystore​

If you need to regenerate the keystore from existing Certbot certificates:

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

Environment Variables Reference​

VariableDescriptionDefault
MA_HOMEMango installation directoryParent of the script directory, or /opt/mango
MA_ENV_PROPERTIESPath to mango.properties$MA_HOME/overrides/properties/env.properties
MA_KEYSTOREPath to the keystore filessl.keystore.location from mango.properties
MA_KEYSTORE_PASSWORDKeystore passwordssl.keystore.password from mango.properties
MA_KEY_PASSWORDPassword for the key inside the keystoressl.key.password or keystore password
MA_KEY_ALIASAlias for the key inside the keystoremango