Load Balancing Apache Tomcat with nginx


Nginx (pronounced ‘engine x’) is an HTTP and reverse proxy server. It is well known for its high performance and stability. It is pretty feature rich and very simple to configure. Nginx hosts nearly 12.18% (22.2M) of active sites across all domains. Nginx uses event-driven architecture to handle requests. When compared to a thread-per-request model, event-driven is highly scalable with a low and predicatble memory footprint.

Nginx is very easy to setup as a load balancer for an Apache Tomcat farm. In this blog post, I will show you how to set it up as a round-robin load balancer for two Tomcat servers.

You first need to install , you can find the installation instructions here. If you are on a Mac, then you could use Homebrew
brew install nginx
After installing, you can run it using the nginx command
sudo nginx
You can now test the installation by opening the following URL in a browser
Lets change the default port 8080 to port 80. You can do that in the nginx.conf file which by default is located at /usr/local/etc/nginx/nginx.conf. First stop nginx
sudo nginx -s stop
Now open the nginx.conf file and locate the listen attribute of the server. Change the value from 8080 to 80. Here is where I made the change in my configuration:

server {
listen 80;
server_name localhost;

Save the file and start nginx. You should now be able to test the configuration change by visiting http://localhost
Install two instances of Apache Tomcat. Open their server.xml files and change the HTTP port numbers to 8080 and 8081 respectively. You can find more information on Apache Tomcat configuration here. Once you have made the change and saved the configuration files, you should now start each instance of Apache Tomcat. Here are a few ways you can start Apache Tomcat. Typically you should be able to locate the bin directory of inside your installation and invoke the startup.sh file as shown:

Now that the Tomcat instances are started, lets setup the round robin load balancer. You would need to use the nginx upstream module. The upstream module allows you to group servers that can be referenced by the proxy_pass directive. In your nginx.conf, locate the http block and add the upstream block to create a group of servers:

http {
upstream tomcat_servers{

ip_hash above configures the load balancing method where requests are routed to servers based on IP Addresses of the client i.e. a request from a client with a particular IP will always go to the same backend Tomcat Server.

Finally, you need to locate the location block within the server block and map the root(/) location to the tomcat_servers group created using the upstream module above.

location / {
proxy_pass http://tomcat_servers;

Thats it!. Restart nginx and you should now be able to send a request to http://localhost and the request will be served by one of the Tomcat servers.

We'd love to hear your opinion on this post

7 Responses to “Load Balancing Apache Tomcat with nginx”

  1. You’ll typically want to add directives to forward the remote IP address, original host, etc… so the Tomcat servers will have a incoming HTTP request with more context from the original request that hit Nginx.

    Also, though very old, this Nginx vs HAProxy comparison is worth being aware of: http://affectioncode.wordpress.com/2008/06/11/comparing-nginx-and-haproxy-for-web-applications/

    • Good point David. I had those in my original config, removed them because then I would’ve had to add another paragraph to the blog explaining those directives. Probably will mention them in a follow up blog, where I could explain more directives.

  2. Good topic! Thanks! However this subject is a bit broader. In the session mgmt area. Would you please add some research or at least include some relevant links


  3. Nice post. However, for the sake of completeness, you might want to discuss how to provide HA to the load balancer itself to avoid a new single point of failure 🙂 In my experience, open source options such as Heartbeat (http://linux-ha.org/wiki/Heartbeat), part of the Linux-HA project, work perfectly as a “virtual IP manager”. It can be configured to monitor a particular process (in this case Nginx) and in case of failure of the master node, it can switch the “shared virtual IP” to the slave node. I have only tested this config with HAProxy but should work with Nginx as well.



  4. My pleasure

  5. I’m getting Nginx 502 gateway error in my Java Hosting VPS, even before starting tomcat instance. Any ideas?