reproxy

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 Let's Encrypt
• 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.

---

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 7 comma-separated elements server,sourceurl,destination[,ping-url[,forward-health-checks[,timeout[,throttle]]]]. 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.
• example.com,^/upload/(.*),https://api.example.com/$1,,,5m - per-route request timeout of 5 minutes (4th and 5th fields left empty to skip ping-url and forward-health-checks).
• example.com,^/login,https://api.example.com/login,,,,2 - per-route throttle of 2 req/sec per user (positional fields before are left empty).

The 4th element defines an optional ping url used for health reporting. The 5th element optionally enables forwarding health check requests to the backend (true, yes, 1). See Health check section for more details. The 6th element is an optional per-route request timeout (Go duration, e.g. 5m, 30s); 0 or empty inherits the global --timeout.write setting. The 7th element is an optional per-route req/sec limit per user; 0 or empty inherits --throttle.user. Empty positional fields are allowed (e.g. ,, for the unused middle fields).

File provider

This provider uses yaml file with routing rules.

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

Example of config.yml: