reverse_proxy¶

The reverse_proxy directive is the main way to configure MXProxy.

It defines a domain, an optional path, and an upstream destination. When the destination is a port on the container carrying the label, MXProxy automatically detects that container's IP address.

Basic usage¶

labels:
  reverse_proxy: example.com -> 8080

This forwards requests for example.com to port 8080 on the current container.

You can define multiple reverse proxies in one label:

labels:
  reverse_proxy: |
    example.com -> 8080
    api.example.com -> 8081

Each line creates a separate reverse proxy.

Upstreams¶

The destination doesn't have to be a port on the current container. You can proxy to other containers, custom addresses, remote URLs, or services running on the Docker host.

Another Docker container¶

labels:
  reverse_proxy: example.com -> other-app:8000

The destination can be a container name and port, provided the address is reachable from MXProxy.

A custom IP address¶

labels:
  reverse_proxy: example.com -> 192.168.1.100:8080

A remote URL¶

labels:
  reverse_proxy: example.com -> https://example.org

A service on the Docker host¶

For services running directly on the Docker host, use the special :port syntax:

labels:
  reverse_proxy: example.com -> :8080

This is equivalent to:

labels:
  reverse_proxy: example.com -> dockerhost:8080

The dockerhost hostname points to the Docker host through its host gateway.

For this to work, the MXProxy container must have the following Compose configuration:

extra_hosts:
  - "dockerhost:host-gateway"

The default MXProxy Compose configuration includes this entry.

See the general usage guide for using dockerhost in custom configuration files.

External services¶

Docker labels must belong to a Docker container. To proxy a service that isn't running in Docker, you can use the malasaur/dummy image as a lightweight container whose only purpose is to carry MXProxy labels.

For example:

services:
  copyparty-proxy:
    image: malasaur/dummy:latest
    networks: [mxproxy]
    labels:
      reverse_proxy: files.example.com -> 192.168.1.100:3923

networks:
  mxproxy:
    external: true

The dummy container doesn't run an actual application. It exists solely to provide a Docker service on which you can define MXProxy configuration.

You can use the same approach for services running on another machine, a host system, or any other address reachable from MXProxy.

Paths¶

MXProxy supports paths on both sides of a proxy. You can strip a path prefix, append a path, or rewrite both sides.

Strip a path¶

labels:
  reverse_proxy: example.com/api -> 8080

Requests are translated like this:

Append a path¶

labels:
  reverse_proxy: example.com -> 8080/backend

Results in:

Rewrite both sides¶

labels:
  reverse_proxy: example.com/api -> 8080/backend

Results in:

Multiple proxies under one domain¶

You can send different paths on the same domain to different upstreams:

labels:
  reverse_proxy: |
    example.com -> 8080
    example.com/api -> 8081

The resulting routing behavior is:

This is useful when different applications serve different parts of the same website.

Headers¶

Use the reverse_proxy.headers subdirective to control headers sent to the upstream or returned to the client.

Set a header¶

To set a request header sent to the upstream:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "> X-MXProxy-Test hello"

The upstream receives the header X-MXProxy-Test: hello.

To set a response header visible to the client:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "< X-MXProxy-Test hello"

To set the header in both directions:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "<> X-MXProxy-Test hello"

Add a header¶

Prefix the header name with + to pass through an existing header:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "> +X-MXProxy-Test"

For example, this request:

curl -H "X-MXProxy-Test: hello" https://example.com

causes the upstream to receive X-MXProxy-Test: hello.

Delete a header¶

Prefix the header name with - to remove it.

From upstream requests:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "> -X-MXProxy-Test"

From downstream responses:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "< -X-MXProxy-Test"

In both directions:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: "<> -X-MXProxy-Test"

Multiple header rules¶

You can specify multiple rules in one label:

labels:
  reverse_proxy: example.com -> 8080
  reverse_proxy.headers: |
    > X-Request-Source mxproxy
    > +X-Forwarded-For
    < X-Served-By mxproxy
    <> X-Test enabled
    < -Server

Subdirectives can also be applied to multiple reverse proxies through groups.

Middleware¶

Middleware lets MXProxy integrate additional services into a reverse proxy.

The syntax is:

labels:
  reverse_proxy: source -> middleware -> destination

Currently, the supported middleware is Anubis.

Anubis¶

To protect a service with Anubis:

labels:
  reverse_proxy: example.com -> anubis -> 8080

MXProxy automatically pulls and deploys an Anubis container, then configures it to proxy requests to port 8080.

When the container with this configuration is removed, MXProxy also stops and removes the associated Anubis container.

This lets you protect your services without manually deploying or configuring Anubis.