How to install Let’s Encrypt with Tomcat

5 min readJun 29, 2018

So, I have heard you are a sysadmin and want to setup your Apache Tomcat with a free SSL certificate from Let’s Encrypt — the free, automated, and open Certificate Authority (CA). Glad you are here! It is actually much simpler than purchasing a SSL/TLS from a regular CA.

If you are not sure if Let’s Encrypt is the right CA for you: Have a look at this tweet:

Yes, you can be one of them. Let’s Encrypt is here to stay.

Pre-installation requirements

This guide assumes you have a host named foo.example.com running some flavour of Linux. We stick to Ubuntu 16.04.4 LTS, but any other will suffice. You are the sysadmin, they should all be the same to you.

Make sure the ports 80 (http) and 443 (https) are open to the world.

You need correct DNS settings. Let’s Encrypt authenticates your host with Domain Validation. You won’t get a SSL certificate from Let’s Encrypt if foo.example.com does not resolve to your host. Make sure your A Record resolves foo.example.com.

You also need Apache Tomcat 8.5.x. I really doubt it works with any version less than 8.5. Haven’t tried. Be my guest.

Install certbot

First you need to install certbot. A small tool that creates keys, signs and downloads Let’s Encrypt certificates to your host. Yes, the certbot does all of the above. Forget the CSR uploading and signing ceremony you have been doing in the past. And leave the credit card in your pocket. It is not needed, anymore, ever.

The website of certbot provides detailed installation instructions for all kind of operating systems. If you are on Ubuntu the following commands get you up and running:

$ sudo su
# apt-get install software-properties-common
# add-apt-repository ppa:certbot/certbot
# apt-get update
# apt-get install certbot

We continue working as root.

Next we create the SSL certificate for foo.example.com.

# certbot certonly --standalone -d foo.example.com

Boom! Congrats, you are done. Yes, that is all you have to do. It Doesn’t Get Any Easier.

# ls /etc/letsencrypt/live/foo.example.com/
cert.pem  chain.pem  fullchain.pem  privkey.pem  README

These are all the files you need.

Install Apache Tomcat with Let’s Encrypt

I won’t go into detail about how to install Apache Tomcat 8.5.x. Many Linux distributions already come with prebuild packages. In theory, there is some apt install tomcat waiting for you.

In case you are like me and like to roll you own Tomcat installation I suggest the following two articles:

Just make sure you install Apache Tomcat 8.5.x.

Let us assume your Apache Tomcat installation directory is /opt/tomcat. Connoisseurs call it CATALINA_BASE.

# ls -l /opt/tomcat/
drwx------  2 tomcat tomcat  4096 Jun 21 09:36 bin
drwx------  3 tomcat tomcat  4096 Jun 27 11:08 conf
drwx------  2 tomcat tomcat  4096 Jun 25 17:23 lib
-rw-------  1 tomcat tomcat 57092 Apr 27 22:26 LICENSE
drwx------  2 tomcat tomcat  4096 Jun 29 08:14 logs
-rw-------  1 tomcat tomcat  1723 Apr 27 22:26 NOTICE
-rw-------  1 tomcat tomcat  7138 Apr 27 22:26 RELEASE-NOTES
-rw-------  1 tomcat tomcat 16246 Apr 27 22:26 RUNNING.txt
drwx------ 37 tomcat tomcat  4096 Jun 29 14:50 temp
drwxr-xr-x  4 tomcat tomcat  4096 Jun 28 16:03 webapps
drwx------  3 tomcat tomcat  4096 Jun 21 09:38 work

Next copy the files cert.pem, chain.pem and privkey.pem to CATALINA_BASE/conf. Any other directory works, too. Even symlinks work, provided the permissions are set properly.

Just make sure not to move the pem-files! Only copy them.

# cd /etc/letsencrypt/live/foo.example.com
# cp cert.pem /opt/tomcat/conf
# cp chain.pem /opt/tomcat/conf
# cp privkey.pem /opt/tomcat/conf

Don’t forget to set the permissions.

# chown tomcat:tomcat *.pem

Your conf directory should now look like this:

# ls -l /opt/tomcat/conf
drwxr-x--- 6 tomcat tomcat   4096 Jun 27 11:10 Catalina
-rw------- 1 tomcat tomcat  13824 Apr 27 22:26 catalina.policy
-rw------- 1 tomcat tomcat   7576 Apr 27 22:26 catalina.properties
-rw-r--r-- 1 tomcat tomcat   2175 Jun 29 08:12 cert.pem
-rw-r--r-- 1 tomcat tomcat   1647 Jun 29 08:12 chain.pem
-rw------- 1 tomcat tomcat   1338 Apr 27 22:26 context.xml
-rw------- 1 tomcat tomcat   1149 Apr 27 22:26 jaspic-providers.xml
-rw------- 1 tomcat tomcat   2313 Apr 27 22:26 jaspic-providers.xsd
-rw------- 1 tomcat tomcat   3429 Jun 25 17:02 logging.properties
-rw-r--r-- 1 tomcat tomcat   1704 Jun 29 08:12 privkey.pem
-rw------- 1 tomcat tomcat   8647 Jun 27 11:08 server.xml
-rw------- 1 tomcat tomcat   2164 Apr 27 22:26 tomcat-users.xml
-rw------- 1 tomcat tomcat   2633 Apr 27 22:26 tomcat-users.xsd
-rw------- 1 tomcat tomcat 169322 Apr 27 22:26 web.xml

The last step is to edit server.xml and configure the HTTPS connector. Fire up your favorite editor (should be vim) and scroll through the file until you find the HTTPS connector tag.

This section is commented by default. Syntax highlighting is your friend.

Remove the open and closing comments and configure the connector with the pem files we copied earlier. This part of your server.xml should now look like this:

<Connector port="8443" protocol="org.apache.coyote.http11.Http11NioProtocol"
maxThreads="150" SSLEnabled="true">
  <SSLHostConfig>
    <Certificate certificateFile="conf/cert.pem"
                 certificateKeyFile="conf/privkey.pem"
                 certificateChainFile="conf/chain.pem" />
  </SSLHostConfig>
</Connector>

Now restart your tomcat, open your browser and go to https://foo.example.com

Excuse my non-existent photoshop skills. Unfortunately I do not own foo.example.com.

Refresh your certificate every 90 days

Yes, unfortunately, or luckily - depending who you ask - SSL certificates provided by Let’s Encrypt expire after 90 days, unless you refresh them.

Refreshing is easy. First shutdown Apache Tomcat.

# certbot certonly --standalone -d foo.example.com

Now copy the new generated pem files back to your conf directory.

# cd /etc/letsencrypt/live/foo.example.com
# cp cert.pem /opt/tomcat/conf
# cp chain.pem /opt/tomcat/conf
# cp privkey.pem /opt/tomcat/conf

Start Apache Tomcat and you are done.

Summary

It is really easy to setup Apache Tomcat with SSL/TLS certificates from Let’s Encrypt if you are using certbot from EEF.

Encrypt the web: Install HTTPS everywhere today.

FAQ

Do I need openssl and this strange APR connector? You can use openSSL and APR but it is not required.
Does Let’s Encrypt provide EV SSL certificates? No. Only domain validation certificates are supported.
I am running Apache Tomcat behind Apache HTTPD. This guide covers only Apache Tomcat running standalone.
What is the difference between Let’s Encrypt and certbot? Let’s Encrypt is a service provided by the Internet Security Research Group (ISRG). Certboot is a program written by the Electronic Frontier Foundation (EFF).