Skip to content

Apache as a reverse proxy with mod_proxy

How to put Apache in front of an upstream app — ProxyPass, headers, timeouts, websocket upgrade, and the connection pool tuning that prevents 502s under load.

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

  1. Enable the proxy modules.

    sudo a2enmod proxy proxy_http headers ssl http2
    sudo apache2ctl configtest
    sudo systemctl restart apache2

    headers is needed for RequestHeader set. http2 is optional but typical — terminate HTTP/2 at Apache.

  2. Confirm the upstream binds to localhost only. A reverse-proxied app should listen on 127.0.0.1, not 0.0.0.0. Bind to localhost in the app config and verify with ss -ltnp. Otherwise the upstream is directly reachable on the public IP and the proxy is decorative.

  3. 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=0

    connectiontimeout=5 fails fast if the upstream is wedged; retry=0 prevents Apache from holding the connection in a failed state. timeout=30 is the per-request limit.

  4. 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_http

    Express, Django, Rails, Sinatra, and most frameworks read these. Without them, generated absolute URLs will be http:// and cookies marked Secure will not be set.

  5. Handle WebSockets if the app uses them. WebSocket connections start as HTTP with an Upgrade: websocket header. mod_proxy_wstunnel handles 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.

  6. 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=On reuses idle connections from a pool. For higher-traffic sites, also set ProxyIOBufferSize to a power of 2 (default 8192).

  7. 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=byrequests is round-robin; bytraffic weights by bytes sent; bybusyness favors the upstream with fewer in-flight requests.

Common pitfalls

  • ProxyPass / http://upstream/ (note the trailing slashes) maps /foo to /foo on the upstream. ProxyPass /api/ http://upstream/ maps /api/foo to /foo. Mismatched trailing slashes are the source of half of the 404s during initial setup.
  • Without ProxyPreserveHost On, the upstream receives Host: 127.0.0.1:3000 and 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_remoteip is loaded and configured to trust X-Forwarded-For from 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.