Reproxy is a simple edge HTTP(s) server / reverse proxy supporting various providers (docker, static, file, consul catalog). One or more providers supply information about the requested server, requested URL, destination URL, and health check URL. It is distributed as a single binary or as a docker container.

Automatic SSL termination with <a href="https://letsencrypt.org/" rel="nofollow noopener noreferrer" target="_blank">Let's Encrypt</a>
Support of user-provided SSL certificates
Simple but flexible proxy rules
Static, command-line proxy rules provider
Dynamic, file-based proxy rules provider
Docker provider with an automatic discovery
Consul Catalog provider with discovery by service tags
Support for multiple (virtual) hosts
Optional traffic compression
Optional IP-based access control
Per-route basic authentication
User-defined size limits and timeouts
Single binary distribution
Docker container distribution
Built-in static assets server with optional "SPA friendly" mode
Support for redirect rules
Optional limiter for the overall activity as well as for user's activity
Live health check and fail-over/load-balancing
Management server with routes info and prometheus metrics
Plugins support via RPC to implement custom functionality
Optional logging with both Apache Log Format, and simplified stdout reports.

</div>

Server (host) can be set as FQDN, i.e. s.example.com, * (catch all) or a regex. Exact match takes priority, so if there are two rules with servers example.com and example\.(com|org), request to example.com/some/url will match the former. Requested url can be regex, for example ^/api/(.*) and destination url may have regex matched groups in, i.e. http://d.example.com:8080/$1. For the example above http://s.example.com/api/something?foo=bar will be proxied to http://d.example.com:8080/something?foo=bar.

For convenience, requests with the trailing / and without regex groups expanded to /(.*), and destinations in those cases expanded to /$1. I.e. /api/ -> http://127.0.0.1/service will be translated to ^/api/(.*) -> http://127.0.0.1/service/$1.

The host substitution is supported in the destination URL. For example, /files/${host} will be replaced with the matched host name. $host (without braces) can also be used.

Both HTTP and HTTPS supported. For HTTPS, static certificate can be used as well as automated ACME (Let's Encrypt) certificates. Optional assets server can be used to serve static files. Starting reproxy requires at least one provider defined. The rest of parameters are strictly optional and have sane default.

Examples:

with a static provider: reproxy --static.enabled --static.rule="*,example.com/api/(.*),https://api.example.com/$1"
with an automatic docker discovery: reproxy --docker.enabled --docker.auto
as a docker container: docker up -p 80:8080 umputun/reproxy --docker.enabled --docker.auto
with automatic SSL: docker up -p 80:8080 -p 443:8443 umputun/reproxy --docker.enabled --docker.auto --ssl.type=auto --ssl.fqdn=example.com

Install

Reproxy distributed as a small self-contained binary as well as a docker image. Both binary and image support multiple architectures and multiple operating systems, including linux_x86_64, linux_arm64, linux_arm, macos_x86_64, macos_arm64, windows_x86_64 and windows_arm. We also provide both arm64 and x86 deb and rpm packages.

for a binary distribution download the proper file in the release section
for Homebrew users: brew install umputun/apps/reproxy
docker container available on Docker Hub as well as on Github Container Registry. I.e. docker pull umputun/reproxy or docker pull ghcr.io/umputun/reproxy.

Latest stable version has :vX.Y.Z docker tag (with :latest alias) and the current master has :master tag.

Providers

Proxy rules supplied by various providers. Currently included - file, docker, static and consul-catalog. Each provider may define multiple routing rules for both proxied request and static (assets). User can sets multiple providers at the same time.

See examples of various providers in examples

Static provider

This is the simplest provider defining all mapping rules directly in the command line (or environment). Multiple rules supported. Each rule is 3 to 5 comma-separated elements server,sourceurl,destination[,ping-url[,forward-health-checks]]. For example:

*,^/api/(.*),https://api.example.com/$1 - proxy all request to any host/server with /api prefix to https://api.example.com
example.com,/foo/bar,https://api.example.com/zzz,https://api.example.com/ping - proxy all requests to example.com and with /foo/bar url to https://api.example.com/zzz and it sees https://api.example.com/ping for the health check.
example.com,/foo/bar,https://api.example.com/zzz,https://api.example.com/ping,true - same as above but also forwards /ping and /health requests to the backend.

The last (4th) element defines an optional ping url used for health reporting. I.e.*,^/api/(.*),https://api.example.com/$1,https://api.example.com/ping. The 5th element optionally enables forwarding health check requests to the backend (true, yes, 1). See Health check section for more details.

File provider

This provider uses yaml file with routing rules.

reproxy --file.enabled --file.name=config.yml

Example of config.yml:

default: # the same as * (catch-all) server
  - { route: "^/api/svc1/(.*)", dest: "http://127.0.0.1:8080/blah1/$1" }
  - {
      route: "/api/svc3/xyz",
      dest: "http://127.0.0.3:8080/blah3/xyz",
      ping: "http://127.0.0.3:8080/ping",
      remote: "192.168.1.0/24, 127.0.0.1", # optional, restrict access to the route
      forward-health-checks: true # optional, forward /ping and /health to backend
    }
  - {
      route: "^/admin/(.*)",
      dest: "http://127.0.0.4:8080/$1",
      auth: "admin:$2y$05$..." # optional, per-route basic auth (htpasswd bcrypt format)
    }
srv.example.com:
  - { route: "^/api/svc2/(.*)", dest: "http://127.0.0.2:8080/blah2/$1/abc" }
  - { route: "/web/", dest: "/var/www", "assets": true }
"*.files.example.com":
  - { route: "^/files/(.*)", dest: "http://123.123.200.200:8080/$host/$1" }

This is a dynamic provider and file change will be applied automatically.

Multiple static sites on different domains can be served by using server names as keys with assets: true:

site-en.example.com:
  - { route: "/", dest: "/var/www/en", "assets": true }
site-ru.example.com:
  - { route: "/", dest: "/var/www/ru", "assets": true }

Important: the route field for asset rules must be a path prefix (e.g., /, /web/), not a regex. Regex patterns like ^/(.*) won't work with assets: true because static asset matching uses path prefix comparison, not regex.

Docker provider

Docker provider supports a fully automatic discovery (with --docker.auto) with no extra configuration needed. By default, it redirects all requests like http://<url>/<container name>/(.*) to the internal IP of the given container and the exposed port. Only active (running) containers will be detected.

This default can be changed with labels:

reproxy.server - server (hostname) to match. Also can be a list of comma-separated servers.
reproxy.route - source route (location)
reproxy.dest - destination path. Note: this is not full url, but just the path which will be appended to container's ip:port
reproxy.port - destination port for the discovered container
reproxy.ping - ping path for the destination container.
reproxy.remote - restrict access to the route with a list of comma-separated subnets or ips
reproxy.auth - require basic auth for the route with comma-separated user:bcrypt_hash pairs (generated by htpasswd -nbB)
reproxy.assets - set assets mapping as web-root:location, for example reproxy.assets=/web:/var/www
reproxy.keep-host - keep host header as is (yes, true, 1) or replace with destination host (no, false, 0)
reproxy.forward-health-checks - forward /ping and /health requests to the backend instead of reproxy handling them (yes, true, 1). Useful when the backend has its own health check endpoints with application-specific responses.
reproxy.enabled - enable (yes, true, 1) or disable (no, false, 0) container from reproxy destinations.

Pls note: without --docker.auto the destination container has to have at least one of reproxy.* labels to be considered as a potential destination.

With --docker.auto, all containers with exposed port will be considered as routing destinations. There are 3 ways to restrict it:

Exclude some containers explicitly with --docker.exclude, i.e. --docker.exclude=c1 --docker.exclude=c2 ...
Allow only a particular docker network with --docker.network
Set the lab

Reproxy

Install / Use

README

Install

Providers

Static provider

File provider

Docker provider