Quick overview
This is a hands on guide to build a lean Docker image that runs Nginx as a reverse proxy, route traffic to backend services, and handle TLS termination. If you are tired of copy paste confusion and mysterious 502s this will get you to a predictable proxy that you can version, ship, and replace without crying.
What to configure first
Start with server blocks that proxy pass requests to backends by host name or IP and port. Use upstream blocks when you have multiple backends for the same service. Add simple health checks in your upstreams if you need graceful failover. Avoid overcomplicated rewrite rules unless your app requires them. Simpler is faster to debug and less likely to explode during traffic spikes.
Key proxy settings to include
- Preserve X forward headers and any custom headers your apps expect
- Configure timeouts so slow clients do not exhaust your worker processes
- Set proper buffering and client body limits for uploads
- Use upstream blocks for load balancing and simple health checks
Build the Docker image
Base the image on the official Nginx image and copy your custom configuration and any static files into the image. Keep layers tidy to reduce image size and make builds faster. Use a clear tag that reflects the role and version of the proxy so your CI and deploys do not confuse which proxy is live.
Store artifacts in a registry when multiple hosts or pipelines need to pull the image. A consistent tag strategy will save you a lot of late night troubleshooting when someone rolled back to the wrong image.
Run the container
Start the container with host port mapping so Nginx can listen on the ports you need. Mount the configuration directory so you can update rules without rebuilding the image. Use a restart policy and give the container a meaningful name. Labels are helpful for monitoring, service discovery, and tooling that expects metadata.
Recommended run checklist
- Map ports for HTTP and HTTPS as needed
- Mount the Nginx config directory and certificate directory if you manage certs outside the image
- Set a restart policy to handle crashes or host reboots
- Label the container for your observability stack
Testing and debugging
Test proxy routes by requesting host endpoints and watching response headers and status codes. Confirm that backend services see expected forwarded headers and that proxy pass rules are applied correctly. Check Nginx logs for errors and increase verbosity while debugging. If you see unexpected 502 or 504 errors inspect upstream health and timeouts first.
Use small, repeatable tests. Curl the endpoint and inspect headers. Then call the backend directly and compare behavior. That will tell you whether the proxy is the bad actor or the backend is just having a bad day.
Handling TLS
Add certificates by mounting a directory with PEM files into the container or by running an ACME client in a companion container that manages certificates for you. Make sure Nginx can read the files and that file permissions are not playing hard to get. Keep certificate paths consistent across environments so your deployment scripts do not need a PhD in arcane paths.
Certificate tips
- Mount certificates as read only where possible
- Confirm Nginx user has permission to read cert and key files
- Automate renewal with an ACME client if you do not want certificate expiry surprises
Best practices summary
- Keep the image small and the layers logical for fast builds
- Use meaningful tags and store the image in a registry for CI and multi host deployments
- Mount configs and certs so swapping containers is painless
- Label containers for monitoring and discovery
- Test proxy behavior and backend health before trusting production traffic
This guide gives you the essentials to build and run an Nginx reverse proxy using Docker. Follow these steps and you will have a predictable proxy container that handles routing and TLS termination without drama. If anything goes wrong remember logs are your friend and coffee is optional but recommended.