Reverse Proxy
A reverse proxy in front of HumHub can be set up in two ways:
- TLS termination: The proxy handles HTTPS and forwards the requests to HumHub via plain HTTP. HumHub relies on forwarded headers to generate correct HTTPS links, so the proxy must be configured as a trusted host.
- Encrypted connection to HumHub (recommended): The proxy also connects to HumHub via HTTPS. HumHub generates correct links without forwarded headers. A trusted host entry is only needed to see the real visitor IP.
Proxy Configuration
The proxy has to keep the original Host header and send the headers X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-For. The defaults differ between proxies, e.g.:
- Apache: Add
ProxyPreserveHost On(ProxyPreserveHost) andRequestHeader set X-Forwarded-Proto https. mod_proxy sendsX-Forwarded-HostandX-Forwarded-For, but notX-Forwarded-Proto(X-Forwarded headers). - Caddy: Nothing to add, the headers are sent by default (reverse_proxy defaults).
- nginx: All headers have to be set explicitly, including
Host $host(proxy_set_header). - Traefik: Nothing to add, the headers are sent by default (services).
Common pitfalls:
- Under FrankenPHP (e.g. the Docker image),
X-Forwarded-Hostis required, otherwise URLs end up with:80. - Without
X-Forwarded-Proto, all URLs including the live updates URL usehttp://. - Live updates (
/.well-known/mercure) usually pass the proxy without extra settings. For nginx, disabling response buffering for this location is a sensible precaution (proxy_buffering):
location /.well-known/mercure {
proxy_buffering off;
# Further proxy settings
}
Encrypted connection to HumHub
It is recommended to encrypt the connection between the proxy and HumHub as well. In addition to the settings above, the proxy has to send the public host name as SNI and verify the certificate of HumHub. Settings for common proxies, e.g.:
- Apache:
SSLProxyEngine on,SSLProxyVerify requireandSSLProxyCACertificateFile(SSLProxyVerify). For a CA with an intermediate certificate,SSLProxyVerifyDepth 2is needed (SSLProxyVerifyDepth). - Caddy: Since v2.11, Caddy replaces the
Hostheader with the upstream address for HTTPS upstreams. Restore it withheader_up Host {hostport}(reverse_proxy HTTPS). Otherwise HumHub answers with an empty page. - nginx:
proxy_ssl_server_name onandproxy_ssl_name $hostfor SNI,proxy_ssl_verify onwithproxy_ssl_trusted_certificatefor verification (proxy_ssl_verify). - Traefik: A
serversTransportwithserverNameandrootCAs(ServersTransport).
Common pitfalls:
- Missing or wrong SNI fails with
tlsv1 alert internal errorortls: internal error. - nginx and Apache do not verify the certificate of HumHub by default. Without verification, the encryption only protects against passive eavesdropping. Accept this only if the proxy and HumHub run on the same host.
For the container side (TLS options, internal CA for an encrypted connection from the proxy), see the Docker image documentation.
Trusted Hosts
The following headers are only accepted from a trusted host:
- X-Forwarded-For
- X-Forwarded-Host
- X-Forwarded-Proto
- X-Forwarded-Port
- Front-End-Https
- X-Rewrite-Url
- X-Original-Host
Headers sent by any other host are ignored. Without a trusted host entry, HumHub records the proxy address instead of the visitor IP and, with TLS termination, generates links with the wrong protocol or host name.
Configuration
The trusted hosts can be configured in the web configuration file or with an environment variable:
- Configuration file
- .env file
- Docker Compose
In protected/config/web.php (in Docker: /data/config/web.php):
<?php
/**
* This file provides to overwrite the default HumHub / Yii configuration by your local Web environments
* @see https://www.yiiframework.com/doc-2.0/guide-concept-configurations.html
* @see https://docs.humhub.org/docs/admin/advanced-configuration
*/
return [
'components' => [
'request' => [
'trustedHosts' => ['192.168.0.0/24'],
],
],
];
In the .env file (see Dot Env):
HUMHUB_WEB_CONFIG__COMPONENTS__REQUEST__TRUSTED_HOSTS='["192.168.0.0/24"]'
The value is parsed as JSON. The single quotes keep the double quotes intact in .env files.
In docker-compose.yml, the quoting depends on the syntax:
# List syntax: no single quotes
environment:
- HUMHUB_WEB_CONFIG__COMPONENTS__REQUEST__TRUSTED_HOSTS=["192.168.0.0/24"]
# Map syntax: single quotes
environment:
HUMHUB_WEB_CONFIG__COMPONENTS__REQUEST__TRUSTED_HOSTS: '["192.168.0.0/24"]'
With the list syntax, single quotes become part of the value and every request fails with HTTP 500.
A file included with env_file: is read like a .env file, so single quotes work there. docker run --env-file and env_file with format: raw keep the quotes as part of the value. Writing the value without quotes (HUMHUB_WEB_CONFIG__COMPONENTS__REQUEST__TRUSTED_HOSTS=["192.168.0.0/24"]) works in all cases.
Do not configure the trusted hosts in protected/config/common.php or with the HUMHUB_CONFIG__ prefix. Both also apply to the console application, whose request component has no trustedHosts property. Every yii command (migrations, queue workers, cron jobs) then fails with Setting unknown property: yii\console\Request::trustedHosts. The web frontend keeps working, so the error is easy to miss.
Environment variables are merged after the configuration files. List entries are appended, not replaced, so configure the setting in one place only.
Value format
The value can be a list or a map:
- List:
['192.168.0.0/24']trusts all headers listed above from these addresses. - Map:
['10.0.0.1' => ['X-Forwarded-For']]trusts only the given headers from this address.
Addresses are IPv4 or IPv6 addresses in CIDR notation. The entries are checked in order, the first match wins.
You can find more information in the Yii2 documentation: https://www.yiiframework.com/doc/api/2.0/yii-web-request#$trustedHosts-detail
Which address to trust
Trust the address HumHub sees as the direct peer of the request (REMOTE_ADDR), e.g. 127.0.0.1 if the proxy runs on the same host.
- Keep the range as narrow as possible. Any trusted peer can spoof the host name used in generated links (e.g. in password reset e-mails) and the visitor IP recorded in sessions and logs.
- HumHub must not be reachable directly, bypassing the proxy.
- Under FrankenPHP (e.g. the Docker image),
REMOTE_ADDRstays the proxy address even if Caddy is configured withtrusted_proxies. That setting only affects Caddy's own access log, HumHub still needs its own trusted hosts entry to see the visitor IP.
HTTPS/SSL Detection
Typically HumHub detects the currently used protocol (HTTP or HTTPS) and uses this automatically to generate links. With TLS termination at the proxy, this is done using the X-Forwarded-Proto header from a trusted host.
If this detection fails, the generation of HTTPS URLs can be forced in protected/config/web.php. Use this only as a fallback, a correctly configured trusted host is the preferred solution.
<?php
// Enforce HTTPS link generation
$_SERVER['HTTPS'] = 'on';
return [
// Further configuration options
];
Existing Installations
Check the stored Base URL in Administration > Settings > General after putting an existing installation behind a proxy. Links in e-mails and notifications created by background jobs use this setting, not the current request.
Caching
If the proxy also acts as a cache, it is important that query parameters are taken into account.
When static files are modified (e.g. during an upgrade), HumHub automatically adds a new query parameter value (cache bust).
The following paths can be cached:
- /assets/*
- /themes/*
- /uploads/*
- /static/*
Example NGINX caching snippet (incomplete):
location ~ ^/(assets|themes|uploads|static)/.*$ {
add_header X-ECache 1;
add_header X-ECache-Key $host$uri$is_args$args;
add_header X-ECache-Status $upstream_cache_status;
proxy_ignore_headers "Expires";
proxy_ignore_headers "Cache-Control";
proxy_cache_key "$host$uri$is_args$args";
proxy_cache_valid 200 1d;
proxy_pass $target;
}