Hey there, fellow Docker wrangler! So you’ve got a bunch of containers humming along, but your static resources are playing hide-and-seek?
Been there, done that, bought the t-shirt. Let’s dive into the magical world of redirecting those stubborn static files with Nginx Proxy Manager (NPM).
The Static Resource Shuffle
Picture this: your Docker setup is almost perfect. Your backend services are happily containerized, NPM is handling your reverse proxying like a champ, but then… CSS files go missing, JavaScript won’t load, and images decide to take an unscheduled vacation. What gives?
The problem is often how paths get handled when you’re proxying to subdirectories. It’s like trying to give someone directions to your house but forgetting to mention they need to turn at the big oak tree!
The Docker Network Party Trick
First things first, let’s get your containers talking to each other properly with a dedicated network:
|
1 2 3 |
docker network create cool-proxy-network |
Then in your docker-compose.yml:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
networks: cool-proxy-network: external: true services: nginx-proxy-manager: image: 'jc21/nginx-proxy-manager' # other config here... networks: - cool-proxy-network my-awesome-app: # your app config here... networks: - cool-proxy-network |
Now your containers can chat using their service names instead of playing IP address ping-pong. It’s like giving them all walkie-talkies on the same channel! Check out NPM’s advanced configuration guide for more details on this approach.
The Magical Trailing Slash
Here’s where the real magic happens. When setting up your proxy host in NPM’s slick interface, pay attention to those trailing slashes:
|
1 2 3 4 5 |
location /cool-app/ { proxy_pass http://my-awesome-app:3000/; } |
See those slashes after /cool-app/ and /? They’re not just for decoration! That tells Nginx, “Hey buddy, strip off that ‘/cool-app/’ prefix before you send this to the backend.”
Without that trailing slash in the proxy_pass, your backend gets requests for /cool-app/styles.css instead of just /styles.css. Cue the 404 errors and sad trombones. This approach is well-documented in the Nginx docs.
The Rewrite Rule Rollercoaster
Sometimes you need a bit more control. Let’s roll up our sleeves and get explicit:
|
1 2 3 4 5 6 |
location /cool-app { rewrite /cool-app/(.*) /$1 break; proxy_pass http://my-awesome-app:3000; } |
This is like telling your mail carrier, “If it says ‘Apartment 4B’ on the envelope, just ignore that part and look at the rest of the address.” Check out this StackOverflow discussion for more details on this approach.
Sub_filter: The HTML Plastic Surgeon
Got an app that’s hardcoding absolute URLs in the HTML? No worries! Let’s perform some cosmetic surgery:
|
1 2 3 4 5 6 7 8 |
location /cool-app/ { proxy_pass http://my-awesome-app:3000/; sub_filter 'href="/' 'href="/cool-app/'; sub_filter 'src="/' 'src="/cool-app/'; sub_filter_once off; } |
This nifty trick finds all those pesky absolute links and injects your path prefix. It’s like having a tiny robot that edits all your HTML on the fly! The Nginx Module documentation explains how this works in detail.
The “I’ll Just Host It Myself” Approach
Sometimes the simplest solution is right under your nose. NPM can serve static files directly:
Drop your files in /data/my-cool-files within your NPM volume
Set up a proxy host with this custom config:
|
1 2 3 4 5 6 |
location / { root /data/my-cool-files; Look ma, no backend service needed! } |
Now NPM is serving those files all by itself, like a generous host offering appetizers at a party. Here’s a detailed guide on hosting static sites directly in NPM.
Troubleshooting: When Things Go Sideways
- 404 Party Crashers: First suspect is always the trailing slashes. Double-check those!
- CSS Ghost Town: Open your browser’s dev tools and look at the network tab. What paths is it trying to load?
- JavaScript Ghosting You: Make sure content types are preserved with
proxy_set_headerdirectives. - Mix-and-Match Content Warnings: HTTPS and HTTP content don’t play nice together. Make everything HTTPS!
The “This App Hates Subpaths” Workaround
Some applications are stubborn and refuse to live in a subdirectory. For these troublemakers, you have options:
- Give them their own subdomain (app1.yourdomain.com)
- Check if they have some hidden “base URL” setting
- Put them behind their own dedicated proxy container (it’s like giving the difficult child their own room)
For multi-app routing, check out this StackOverflow solution for jwilder/nginx-proxy.
Wrap-Up
There you have it! Taming the static resource beast doesn’t have to be a nightmare. With the right network setup, careful path handling, and maybe a dash of sub_filter magic, your Docker services and their static resources will play nice together.
Remember: in the world of proxying, a slash in the right place can be the difference between smooth sailing and pulling your hair out. Happy proxying, container captains!
FAQ
Got Docker containers running behind Nginx Proxy Manager but your static resources aren’t loading? Here are the most common questions and solutions for handling static files through NPM.
Why aren’t my static assets (CSS, JS, images) loading through Nginx Proxy Manager?
This common issue usually happens because the paths in your HTML reference absolute URLs that don’t account for being served from a subpath. There are three main approaches to fix this:
- Use a trailing slash in both location and proxy_pass directives
- Add explicit rewrite rules
- Use sub_filter to transform URLs in the response
Example with trailing slashes (most reliable):
|
1 2 3 4 5 |
location /app/ { proxy_pass http://backend:3000/; } |
How do I fix the “404 Not Found” errors for my static resources?
The 404 errors typically occur when your application expects files to be at the root path, but they’re being requested with a prefix. Use one of these approaches:
Option 1: Use explicit rewrite rules
|
1 2 3 4 5 6 |
location /app { rewrite /app/(.*) /$1 break; proxy_pass http://backend:3000; } |
Option 2: Fix it with sub_filter (for hardcoded URLs)
|
1 2 3 4 5 6 7 8 |
location /app/ { proxy_pass http://backend:3000/; sub_filter 'href="/' 'href="/app/'; sub_filter 'src="/' 'src="/app/'; sub_filter_once off; } |
How can I host a simple static website directly in Nginx Proxy Manager?
You can host static files directly in NPM without needing another container:
- Create a directory in your NPM data volume (e.g.,
/data/mysite) - Place your static files there
- Create a proxy host in NPM and add this to Custom Nginx Configuration:
|
1 2 3 4 5 |
location / { root /data/mysite; } |
You can use any domain name in the NPM UI, but the Forward Hostname/Port won’t be used – they can be set to anything.
What’s the best Docker network setup for Nginx Proxy Manager and backend services?
The recommended approach is to create a dedicated Docker network for NPM and all your backend services:
|
1 2 3 |
docker network create proxy-network |
Then in your docker-compose.yml:
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 |
networks: proxy-network: external: true services: nginx-proxy-manager: image: 'jc21/nginx-proxy-manager:latest' # other config... networks: - proxy-network backend-service: # your app config... networks: - proxy-network |
This allows services to communicate by container name rather than IP address, simplifying your proxy configuration and improving security.
How do I handle multiple services under different paths of the same domain?
To serve multiple Docker services under the same domain but different paths (e.g., example.com/app1, example.com/app2), use NPM’s custom locations feature:
- Create a proxy host for your main domain
- Add custom locations for each service
Example configuration:
|
1 2 3 4 5 6 7 8 9 |
location /app1/ { proxy_pass http://service1:3000/; } location /app2/ { proxy_pass http://service2:8080/; } |
Remember to use trailing slashes to ensure proper path handling.
My application doesn’t support being accessed from a subpath. What are my options?
Some applications don’t work well when accessed from a subpath. In these cases, you have several options:
- Use a subdomain instead – Instead of example.com/app, use app.example.com
- Check for base path configuration – Many applications have settings for a base URL or path prefix
- Use sub_filter for URL rewriting – This can fix hardcoded URLs in HTML responses
- Use a dedicated proxy container – Create a separate container with custom Nginx configuration
Subdomains are generally the most reliable approach for applications that don’t support subpaths natively.
How can I add custom Nginx configuration for better static file handling?
NPM allows adding custom Nginx configurations in several ways:
- Per proxy host – Using the “Custom Locations” and “Advanced” tabs in the UI
- Global configuration – By mounting custom snippets to specific locations
For global configuration, create files in these locations:
|
1 2 3 4 |
/data/nginx/custom/server_proxy.conf # Included in every proxy server block /data/nginx/custom/http.conf # Included at the end of the http block |
Example for better static file handling in server_proxy.conf:
|
1 2 3 4 5 6 7 8 |
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ { proxy_pass $proxy_pass; proxy_cache_valid 200 1d; expires 1d; add_header Cache-Control "public"; } |
How do I debug 404 errors for static resources?
To troubleshoot static resource issues:
- Check browser dev tools (Network tab) to see what paths are being requested
- Enable access logging in Nginx
- Compare the requested paths against your location directives
- Check if trailing slashes are used correctly
- Verify your application’s base URL configuration
You can add logging to your custom locations:
|
1 2 3 4 5 6 7 |
location /app/ { proxy_pass http://backend:3000/; access_log /data/logs/app-access.log; error_log /data/logs/app-error.log; } |
I’m getting mixed content warnings with my static resources. How do I fix this?
Mixed content warnings occur when your page is loaded over HTTPS but tries to load resources over HTTP. To fix this:
- Ensure all resources use HTTPS (or protocol-relative URLs starting with //)
- Configure your backend service to use HTTPS internally
- Use sub_filter to rewrite URLs in the response
Example configuration:
|
1 2 3 4 5 6 7 8 |
location /app/ { proxy_pass http://backend:3000/; proxy_set_header X-Forwarded-Proto $scheme; sub_filter 'http://' 'https://'; sub_filter_once off; } |
Can Nginx Proxy Manager handle WebSockets for my application?
Yes, NPM can handle WebSocket connections. For WebSocket support, add these directives to your custom Nginx configuration:
|
1 2 3 4 5 6 7 8 |
location /app/ { proxy_pass http://backend:3000/; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; } |
This configuration allows WebSocket connections to be proxied correctly to your backend service.
