#Using a Reverse Proxy

It is recommended to place a reverse proxy such as nginx, Apache, Caddy, HAProxy or relayd in front of Palpo. Doing so lets you expose the default HTTPS port (443) to Matrix clients without forcing Palpo to bind to a privileged port (any port below 1024).

Configure the proxy to forward any request whose path begins with /_matrix or /_palpo/client to Palpo, and make sure it adds the X-Forwarded-For and X-Forwarded-Proto headers.

Keep in mind that Matrix clients and remote homeservers don’t have to use the same hostname or port. Clients default to 443, while federation traffic normally arrives on 8448. When these are different, we speak of a “client port” and a “federation port.” The Matrix specification explains the algorithm in detail, and the Delegation page shows how to set it up.

NOTE: Your reverse proxy must not canonicalize or normalize the requested URI in any way (for example, by decoding %xx escapes).

Let's assume that we expect clients to connect to our server at https://matrix.example.com, and other servers to connect at https://example.com:8448. The following sections detail the configuration of the reverse proxy and the homeserver.

#Homeserver Configuration

The HTTP configuration will need to be updated for Palpo to correctly record client IP addresses and generate redirect URLs while behind a reverse proxy.

In palpo.toml set x_forwarded: true in the port 8008 section and consider setting bind_addresses: ['127.0.0.1'] so that the server only listens to traffic on localhost. (Do not change bind_addresses to 127.0.0.1 when using a containerized Palpo, as that will prevent it from responding to proxied traffic.)

Optionally, you can also set request_id_header so that the server extracts and re-uses the same request ID format that the reverse proxy is using.

#Reverse-proxy configuration examples

NOTE: You only need one of these.

#nginx

server {
    listen 443 ssl;
    listen [::]:443 ssl;

    # For the federation port
    listen 8448 ssl default_server;
    listen [::]:8448 ssl default_server;

    server_name matrix.example.com;

    location ~ ^(/_matrix|/_palpo/client) {
        # note: do not add a path (even a single /) after the port in `proxy_pass`,
        # otherwise nginx will canonicalise the URI and cause signature verification
        # errors.
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Host $host:$server_port;

        # Nginx by default only allows file uploads up to 1M in size
        # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
        client_max_body_size 50M;

        # Palpo responses may be chunked, which is an HTTP/1.1 feature.
        proxy_http_version 1.1;
    }
}

#Caddy v2

Delegation example:

#Apache

<VirtualHost *:443>
    SSLEngine on
    ServerName matrix.example.com

    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
    AllowEncodedSlashes NoDecode
    ProxyPreserveHost on
    ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
    ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
    ProxyPass /_palpo/client http://127.0.0.1:8008/_palpo/client nocanon
    ProxyPassReverse /_palpo/client http://127.0.0.1:8008/_palpo/client
</VirtualHost>

<VirtualHost *:8448>
    SSLEngine on
    ServerName example.com

    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
    AllowEncodedSlashes NoDecode
    ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
    ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
</VirtualHost>

NOTE: ensure the nocanon options are included.

NOTE 2: It appears that Palpo is currently incompatible with the ModSecurity module for Apache (mod_security2). If you need it enabled for other services on your web server, you can disable it for Palpo's two VirtualHosts by including the following lines before each of the two </VirtualHost> above:

<IfModule security2_module>
    SecRuleEngine off
</IfModule>

NOTE 3: Missing ProxyPreserveHost on can lead to a redirect loop.

#HAProxy

Example configuration, if using a UNIX socket. The configuration lines regarding the frontends do not need to be modified.

Example configuration when using a single port for both client and federation traffic.

Delegation example:

#Relayd

#Health check endpoint

Palpo exposes a health check endpoint for use by reverse proxies. Each configured HTTP listener has a /health endpoint which always returns 200 OK (and doesn't get logged).

#Palpo administration endpoints

Endpoints for administering your Palpo instance are placed under /_palpo/admin. These require authentication through an access token of an admin user. However as access to these endpoints grants the caller a lot of power, we do not recommend exposing them to the public internet without good reason.