How Do You Set up Nginx as an HTTP Load Balancer for Other Instances of Nginx Running in Docker?

Problem scenario
You have many Docker containers running Nginx.  You want to leverage these instances for users to go to one web site and then be automatically routed to different underlying Nginx instances in Docker containers.  How do you create a single website for web clients to go to with a reverse proxy balancing the load behind-the-scenes?

We accomplish an example with four Docker containers each using a free version of Nginx.  One Docker container with Nginx will be the invisible landing page.  As a reverse proxy, this instance will not be visible to web users beyond typing in its URL or IP address in a web browser.  The other three Docker containers with Nginx will be websites.  The distributor Docker Nginx instance (aka reverse proxy or invisible landing page) will relay inbound connections to the other normal web severs.

This assumes you have three Docker containers running Nginx and you know the internal IP addresses of each of the containers.  You can use this article to set up the Docker containers with Nginx.  When you create Docker containers with nginx, there is an --ip flag that is optional.  This is when their internal IP addresses are assigned.  These IP addresses will be necessary for this solution.  Retrieve them now.

#1.a. For the landing page Nginx instance (to relay traffic to the three Docker containers with IP addresses), create the Docker container like this command:

docker run --name docker-nginxbalancer nginx

The Nginx instance that will function as a load balancer router (or pass-through portal reverse proxy) and distribute traffic should not be part of a user-defined network.  Nor should it have an IP address.

#1b.  Go inside the Docker container.  Modify this file: /etc/nginx/conf.d/default.conf in three ways.

#1.c.i. First find the location stanza in the server {} clause.  Comment out these two lines like this (with a "#" sign):

# root   /usr/share/nginx/html;
# index index.html index.htm;

#1.c.ii.  Second, insert this stanza beneath the commented out lines above (and before the closing brace of server "}"):

proxy_pass http://backend;

#1.c.iii  Thirdly at the very bottom of the entire file, add this block of text (but substitute the x.x.x.x, y.y.y.y, and z.z.z.z with the internal IP addresses of the three Docker containers with Nginx that will be members of the load balancer):

upstream backend {
   server x.x.x.x;
   server y.y.y.y;
   server z.z.z.z;

2.  Exit this Docker container.  Stop the container.  Start it again. 

3.  Summary
You are done at this point.  Now you can test it by opening a web browser and going to the URL of the landing page Nginx Docker container.  Below is for information on testing it and how it all works.

The user will type in the URL or IP address with a port number for the landing page that is created by the Docker container with Nginx.  The IP address would be found by going to the Docker server and using the "curl" command.  The port number would be found by running "docker ps -a".  This command will show a colon with two integer values in a row of data for the Docker container with the landing page.  The integer on the left of the column is the port number to uniquely identify the Nginx instance.  The socket for Nginx is the external IP address of the server with a colon and the port number (e.g.,  This is the URL the user will type into a web browser to get to the landing page.

Have users go to the URL that will get them to the landing page (supported by Nginx in a Docker container that was referred to in steps #1 and #2).  The clients will see only a web UI but their inbound connections will be relayed to one of the possible web servers (be that x.x.x.x, y.y.y.y, or z.z.z.z).  The requests will be distributed via a round robin method.  Behind the scenes the first web page request will go to x.x.x.x.  The second request from a client workstation will go to y.y.y.y.  The third will go to z.z.z.z.  For your edification you may want test this round robin mechanism (that happens automatically and requires no user or administrator intervention).  To do this go to the three Docker containers with Nginx serving as a regular web server via the the back-end and modify the /usr/share/nginx/html/index.html file in the Docker container itself. Go to the <h1> stanza that says "Welcome to Nginx!".  Replace the "Welcome to Nginx!" with "AAAAA", "BBBBB" or "CCCCC" (so as to uniquely identify the server when the page is rendered in a web browser).  This way you'll see the round-robin distribution as you click refresh in the web browser once you have gone to the URL that will take you to the Nginx landing page (the container that was involved in step #1 above).  You will see "AAAAA", "BBBBB" or "CCCCC" as evidence of the distribution upon each refresh.

If you want to need to troubleshoot problems with your Nginx load balancer, see this link.

Leave a comment

Your email address will not be published. Required fields are marked *