Skip to main content

Mango Behind a Reverse Proxy

Apache (or Nginx) can be configured to proxy requests from a public-facing HTTPS port to a private Mango instance behind your firewall. Benefits of using a reverse proxy include:

  • Simplified SSL/TLS certificate management
  • Configurable content caching
  • Request logging and rate limiting
  • Protection against DDoS attacks
  • Running multiple services on the same public IP

For more background on reverse proxies, see:

Requirements​

Apache Configuration​

Enable Required Modules​

Add the following to your httpd.conf (module paths may vary by OS):

LoadModule proxy_module libexec/apache2/mod_proxy.so
LoadModule proxy_http_module libexec/apache2/mod_proxy_http.so
LoadModule proxy_connect_module libexec/apache2/mod_proxy_connect.so
LoadModule proxy_wstunnel_module libexec/apache2/mod_proxy_wstunnel.so
LoadModule rewrite_module libexec/apache2/mod_rewrite.so

Virtual Host Configuration​

Add a virtual host section to proxy requests from the public server to Mango:

# Proxy from public.example.com:443 to private Mango on mango.example.com:8081
<VirtualHost *:443>
    ProxyPreserveHost Off
    ServerName public.example.com
    ServerAlias public.example.com
    ProxyRequests Off

    CustomLog "/var/log/apache-access-public-mango.log" common
    ErrorLog "/var/log/apache-error-public-mango.log"

    ProxyPass / http://mango.example.com:8081/
    ProxyPassReverse / http://mango.example.com:8081/
    ProxyPassReverseCookieDomain http://mango.example.com:8081 http://public.example.com:443

    # WebSocket proxy rules
    RewriteEngine On
    RewriteCond %{HTTP:Upgrade} websocket [NoCase]
    RewriteCond %{HTTP:Connection} upgrade [NoCase]
    RewriteRule /(.*) ws://mango.example.com:8081/$1 [Proxy,Last]

    # SSL configuration
    SSLEngine On
    SSLProxyEngine On
    Include /etc/letsencrypt/options-ssl-apache.conf
    SSLCertificateFile /opt/ssl/sslPublic.pem
    SSLCertificateKeyFile /opt/ssl/sslPrivate.pem
</VirtualHost>

Understanding the Configuration​

ProxyPreserveHost Off -- The Host header from the incoming request is not passed to the proxied host. Instead, the hostname from the ProxyPass setting is used. See Apache documentation.

ProxyRequests Off -- Disables forward proxy functionality. Leaving this enabled is a security risk. See Apache documentation.

WebSocket rewrite rules -- Mango uses WebSockets for real-time UI updates. The rewrite rules detect WebSocket upgrade requests and route them through the proxy correctly.

SSL settings -- Configure the SSL engine and certificate paths. The example uses Let's Encrypt certificates managed by Certbot.

warning

The RequestHeader set Host and RequestHeader set Origin directives were required for Mango 3.6.x but will break WebSocket connections in Mango 3.7.x and later. Do not include these directives for current Mango versions.

Configure Mango (3.7.0+)​

Starting in Mango 3.7.0, you must enable forwarded header processing and trust the proxy's IP address.

In mango.properties:

# Enable processing of forwarded headers (X-Forwarded-For, X-Forwarded-Proto, etc.)
web.forwardedHeaders.enabled=true

# Trust the proxy IP (use the actual IP address, not hostname)
web.forwardedHeaders.trustedIpRanges=127.0.0.0/8,::1,PROXY_IP_ADDRESS

Replace PROXY_IP_ADDRESS with the actual IP address of your reverse proxy server. You can specify multiple addresses or CIDR ranges separated by commas.

Nginx Alternative​

If you prefer Nginx, the equivalent configuration uses proxy_pass and proxy_set_header directives. The key requirements are the same:

  • Proxy HTTP traffic to Mango's internal port
  • Handle WebSocket upgrades with proxy_http_version 1.1 and appropriate Upgrade/Connection headers
  • Terminate SSL at the proxy
  • Forward the original client IP address

Troubleshooting​

WebSocket Connections Failing​

If real-time UI updates are not working, verify that:

  • The mod_proxy_wstunnel module is loaded
  • The WebSocket rewrite rules are present and correct
  • Mango's web.forwardedHeaders.enabled=true is set

CORS Errors​

If you see cross-origin errors in the browser console, ensure that ProxyPreserveHost is set appropriately and that the web.forwardedHeaders.trustedIpRanges includes the proxy IP.

Session Issues​

If users are repeatedly logged out, verify that the ProxyPassReverseCookieDomain directive is correctly mapping between the internal and external domains.