proxy_set_header directives resolves the connectivity and functionality issues.
Understanding the Direct Connection Success
When you access http://garnet.local:8083 directly, the browser communicates straight with the Docker container running FreshRSS. This bypasses Nginx entirely, which is why basic RSS fetching and page loading work perfectly in this scenario. However, FreshRSS relies heavily on Server-Sent Events (SSE) and potentially WebSockets for real-time notification of new feeds and background polling. When a reverse proxy sits between the client and the application, it must be explicitly configured to handle these persistent connections. If the proxy treats the connection as a standard short-lived HTTP request, it will drop the stream after the initial response, causing the "strange networking issues" such as failed auto-refreshes or broken UI elements.
Core Nginx Configuration Requirements
To fix this, you need to ensure your Nginx configuration file properly proxies both standard HTTP traffic and the specific headers required for stateful connections. Below is the essential structure for the server block that should point to your FreshRSS container.
server {
listen 80;
server_name freshrss.example.com;
location / {
proxy_pass http://localhost:8083;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Important for large feed payloads
proxy_buffering off;
proxy_cache off;
}
}The lines proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade" are critical. They tell Nginx to allow the protocol switch from HTTP to WebSocket or SSE if requested by the client. Without these, Nginx defaults to HTTP/1.0 behavior, which closes the connection immediately after sending the header. Additionally, proxy_buffering off ensures that Nginx does not buffer the incoming stream from FreshRSS, which is vital for real-time updates to appear instantly in the browser.
Docker Networking Considerations on Garnet
Since your setup involves a physical machine named Garnet hosting a Docker container, you must verify how Docker maps ports. While you mentioned port 8083 works, ensure that the Nginx container (if separate) can reach the FreshRSS container via the Docker internal network rather than just localhost. If Nginx and FreshRSS are in different Docker networks, using http://localhost:8083 inside the Nginx config might fail if they do not share the same network namespace.
If you are running Nginx in a separate container, use the Docker service name of the FreshRSS container as the upstream address. For example:
location / {
proxy_pass http://freshrss_container:8083;
# ... other headers ...
}This approach is more robust than mapping to localhost on the host machine, as it avoids potential firewall rules or binding issues on Garnet’s network interface. If you are running Nginx directly on the host OS alongside Docker, then localhost is acceptable, but you must ensure the Nginx process has permission to connect to the loopback interface where Docker exposes the port.
Debugging Common Symptoms
If the configuration above does not resolve the issue, check the following areas. First, inspect the Nginx error logs located at /var/log/nginx/error.log. Look for messages regarding "upstream prematurely closed connection" or "no live upstreams." These errors usually indicate that the backend (FreshRSS) is rejecting the connection or timing out because Nginx is not sending the correct keep-alive settings.
Secondly, verify that FreshRSS itself is configured to trust the reverse proxy. In your FreshRSS configuration file (usually ./data/config.php), ensure that the base URL matches the domain you are accessing via Nginx, not the internal Docker IP. If the URLs mismatch, FreshRSS may generate links pointing to http://localhost:8083, which the browser cannot resolve when accessed through the public Nginx domain.
Additionally, consider caching issues. Nginx might be caching static assets aggressively. Disable caching for the dynamic parts of FreshRSS by adding proxy_no_cache 1 and proxy_cache_bypass 1 for specific API endpoints if you suspect stale data is being served.
Related Resources
For more complex setups involving multiple services, refer to Setting up Reverse Proxy across Multiple Devices on Local Network for broader networking context. If you encounter specific gateway errors like 502 or 504, see Troubleshooting React/Express on Nginx/Ubuntu for general Nginx debugging techniques.
Frequently Asked Questions
Why does FreshRSS load but never update?
This is almost always caused by missing WebSocket or SSE upgrade headers in the Nginx configuration. Ensure you have included proxy_set_header Upgrade $http_upgrade and Connection "upgrade" in your location block. Without these, the persistent connection required for real-time updates is terminated immediately after the initial page load.
Can I use HTTPS with this setup?
Yes, but you must configure SSL certificates in the Nginx server block and set proxy_set_header X-Forwarded-Proto https;. FreshRSS needs to know the original request was secure to generate correct HTTPS links. You can use Let's Encrypt with Certbot to automate certificate renewal for Garnet.
What if I get a 502 Bad Gateway error?
A 502 error means Nginx cannot communicate with the upstream FreshRSS container. Verify that the container is running and that the port mapping is correct. Check docker ps to ensure port 8083 is exposed. Also, confirm that Nginx is pointing to the correct IP or hostname for the upstream service.
Does FreshRSS support subdirectories instead of subdomains?
It is possible but requires additional configuration. You would need to set the base URL in FreshRSS to include the subdirectory path and adjust the Nginx location directive to match. Subdomains are generally recommended for FreshRSS to avoid path rewriting complexities and cookie scope issues.
How do I clear Nginx cache if FreshRSS looks broken?
If you have enabled caching, delete the contents of the Nginx cache directory (often /var/cache/nginx) or restart the Nginx service. For immediate testing, disable caching entirely by adding proxy_cache off; to your configuration and reloading Nginx with nginx -s reload.