The shape of a typical modern Apache deployment is Apache as a TLS-terminating reverse proxy in front of one or more upstream application servers — Node, Gunicorn, Java, Go binaries. Apache handles SNI, sane HTTP parsing, gzip, request logging, and mod_security if present; the upstream handles the application logic. This article is the proxy block we write for that pattern, plus the failure modes that cause 502s and 504s under load.
How to verify
Confirm the proxy modules are loaded and that the upstream is reachable from the Apache host:
apachectl -M | grep -E 'proxy|http2'
sudo ss -ltnp | grep -E ':(3000|8080|8000)\b'
curl -sI http://127.0.0.1:3000/healthz
sudo apache2ctl -S
After config changes, the critical check is that the proxy is forwarding intact requests with the right headers — curl -sI -H 'Host: example.com' against both Apache (port 80/443) and the upstream (loopback port) and diff the headers. The upstream should see the original Host:, X-Forwarded-For, and X-Forwarded-Proto.
What’s happening
mod_proxy is the base reverse-proxy module. By itself it does nothing useful — you need a protocol-specific submodule:
mod_proxy_http— proxy HTTP/1.1 to an upstream over HTTP.mod_proxy_http2— proxy HTTP/2 end-to-end (rare; most setups terminate HTTP/2 at Apache and use HTTP/1.1 upstream).mod_proxy_fcgi— proxy to a FastCGI process (typically PHP-FPM, see Apache + PHP-FPM proxy).mod_proxy_uwsgi— proxy to uWSGI.mod_proxy_wstunnel— proxy WebSocket upgrades.mod_proxy_balancer— round-robin or weighted load balancing across multiple upstreams.
For an HTTPS frontend proxying to a Node app on 127.0.0.1:3000, the modules you need are proxy, proxy_http, headers, and ssl. The basic vhost:
<VirtualHost *:443>
ServerName api.example.com
SSLEngine on
SSLCertificateFile /etc/letsencrypt/live/api.example.com/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/api.example.com/privkey.pem
Include /etc/letsencrypt/options-ssl-apache.conf
ProxyPreserveHost On
ProxyRequests Off
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Port "443"
ProxyPass / http://127.0.0.1:3000/ retry=0 timeout=30 connectiontimeout=5
ProxyPassReverse / http://127.0.0.1:3000/
ErrorLog ${APACHE_LOG_DIR}/api-error.log
CustomLog ${APACHE_LOG_DIR}/api-access.log combined
</VirtualHost>
ProxyPreserveHost On passes the original Host: header to the upstream — important for apps that vary content by hostname. ProxyRequests Off disables the forward-proxy capability (the dangerous default in the absence of Off is an open relay). RequestHeader set X-Forwarded-Proto "https" tells the upstream the original scheme so it can build correct redirect URLs and signed-URL hashes.
The procedure
-
Enable the proxy modules.
sudo a2enmod proxy proxy_http headers ssl http2 sudo apache2ctl configtest sudo systemctl restart apache2headersis needed forRequestHeader set.http2is optional but typical — terminate HTTP/2 at Apache. -
Confirm the upstream binds to localhost only. A reverse-proxied app should listen on
127.0.0.1, not0.0.0.0. Bind to localhost in the app config and verify withss -ltnp. Otherwise the upstream is directly reachable on the public IP and the proxy is decorative. -
Set timeouts that match the workload. The defaults (typically a 60s
ProxyTimeout) are too long for some APIs and too short for others. For a typical synchronous API:ProxyTimeout 30 ProxyPass / http://127.0.0.1:3000/ timeout=30 connectiontimeout=5 retry=0connectiontimeout=5fails fast if the upstream is wedged;retry=0prevents Apache from holding the connection in a failed state.timeout=30is the per-request limit. -
Forward the headers the upstream actually needs. Most apps need three:
RequestHeader set X-Forwarded-Proto "https" RequestHeader set X-Forwarded-Port "443" # X-Forwarded-For is set automatically by mod_proxy_httpExpress, Django, Rails, Sinatra, and most frameworks read these. Without them, generated absolute URLs will be
http://and cookies markedSecurewill not be set. -
Handle WebSockets if the app uses them. WebSocket connections start as HTTP with an
Upgrade: websocketheader.mod_proxy_wstunnelhandles them:RewriteEngine On RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) ws://127.0.0.1:3000/$1 [P,L]The
[P]flag makes the rewrite a proxy pass. After this rule, websocket frames flow without HTTP framing. -
Tune the connection pool for sustained load. The default is a fresh TCP connection per request to the upstream, which is wasteful. Enable connection reuse:
<Proxy http://127.0.0.1:3000> ProxySet keepalive=On ProxySet timeout=30 ProxySet connectiontimeout=5 ProxySet retry=0 </Proxy>keepalive=Onreuses idle connections from a pool. For higher-traffic sites, also setProxyIOBufferSizeto a power of 2 (default 8192). -
Add load balancing if there are multiple upstreams.
<Proxy "balancer://api-cluster"> BalancerMember http://10.0.1.10:3000 retry=10 BalancerMember http://10.0.1.11:3000 retry=10 ProxySet lbmethod=byrequests </Proxy> ProxyPass / "balancer://api-cluster/" ProxyPassReverse / "balancer://api-cluster/"lbmethod=byrequestsis round-robin;bytrafficweights by bytes sent;bybusynessfavors the upstream with fewer in-flight requests.
Common pitfalls
ProxyPass / http://upstream/(note the trailing slashes) maps/footo/fooon the upstream.ProxyPass /api/ http://upstream/maps/api/footo/foo. Mismatched trailing slashes are the source of half of the 404s during initial setup.- Without
ProxyPreserveHost On, the upstream receivesHost: 127.0.0.1:3000and any hostname-dependent routing (multi-tenant apps) breaks. - Apache logs the client IP for the upstream connection at the proxy log level — to log the real client IP, ensure
mod_remoteipis loaded and configured to trustX-Forwarded-Forfrom your edge. - HTTP/2 between Apache and the upstream is rarely worth the operational complexity; HTTP/2 on the public side, HTTP/1.1 with keepalive to the upstream, is the conventional setup.
- A 502 Bad Gateway under load almost always means the upstream connection pool is exhausted or the upstream’s accept queue is full. Tune
worker(Apache) and the upstream’s connection backlog together.
Stack Harbor runs Apache reverse-proxy fronts for Node, Python, Java, and Go upstreams across regulated workloads — proxy headers right, timeouts matched to SLOs, and the load balancer pool sized from real traffic. If your Apache front is throwing 502s under spikes and nobody is sure whether the cap is Apache or upstream, that diagnosis is part of Managed Operations.