fnichol/nginx-tcp-lb repository overview

⁠docker-nginx-tcp-lb

A small Docker image for running an nginx⁠ TCP load balancer.

Table of Contents

• Getting the Image⁠
• Usage⁠
• Issues⁠
• Contributing⁠
• Authors⁠
• License⁠

⁠Getting the Image

The image is hosted on Docker Hub and can be pulled down with:

$ docker pull fnichol/nginx-tcp-lb

⁠Usage

By default, nginx will be run with no arguments:

$ docker run --rm -ti fnichol/nginx-tcp-lb
/docker-entrypoint.sh: /docker-entrypoint.d/ is not empty, will attempt to perform configuration
/docker-entrypoint.sh: Looking for shell scripts in /docker-entrypoint.d/
...

Now, to add TCP listeners which forward to their upstreams, you need to do 2 things:

1. set an environment variable which contains the listening port and upstream host/port information
2. expose the corresponding listening Docker port entry for external access

For example, to set up HTTP and HTTPS forwarding listeners to 2 upstream servers on www1.local and www2.local you can run:

docker run --rm -ti \
  -p 8080:8080 -e NGINX_TCP_HTTP=8080:www1.local,www2.local:80 \
  -p 8443:8443 -e NGINX_TCP_HTTPS=8443:www1.local,www2.local:443 \
  fnichol/nginx-tcp-lb

Note that each environment variable entry is of this form:

               Upstream hosts, delimited with comma
                              |
    Listener name             |
           |                  |
          ----      ---------------------
NGINX_TCP_HTTP=8080:www1.local,www2.local:80
----------     ----                       --
    |            |                         |
Variable prefix  |                         |
                 |                         |
        Listening/serving TCP port         |
                                           |
                        Upstream TCP port (all upstreams are the same)

⁠Issues

If you have any problems with or questions about this image, please contact us through a GitHub issue⁠.

⁠Contributing

You are invited to contribute to new features, fixes, or updates, large or small; we are always thrilled to receive pull requests, and do our best to process them as fast as we can.

Before you start to code, we recommend discussing your plans through a GitHub issue⁠, especially for more ambitious contributions. This gives other contributors a chance to point you in the right direction, give you feedback on your design, and help you find out if someone else is working on the same thing.

⁠Authors

Created and maintained by Fletcher Nichol⁠ ([email protected]⁠).

⁠License

This Docker image is licensed under the MIT⁠ license. The nginx project is also licensed under a 2-clause BSD-like⁠ license.