go/reproxy
1
0
Fork 0
mirror of https://github.com/umputun/reproxy.git synced 2024-11-24 08:12:31 +02:00
Code Issues Releases Activity

add some info to readme

Browse Source
This commit is contained in:
Umputun 2021-04-09 17:48:22 -05:00
parent 17c1c8ba92
commit 1e7f940b01
1 changed files with 73 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

92
README.md
View File

@ -1,49 +1,92 @@
# reproxy [![build](https://github.com/umputun/reproxy/actions/workflows/ci.yml/badge.svg)](https://github.com/umputun/reproxy/actions/workflows/ci.yml)
Simple edge reverse HTTP(s) proxy for various providers (docker, static, file). One or more providers supply information
about requested server, requested url and destination url. Distributed as a single binary and a docker container.
Reproxy is simple edge HTTP(s) sever / reverse proxy for various providers (docker, static, file). One or more providers supply information
about requested server, requested url and destination url. Distributed as a single binary or as a docker container.
Server can be FQDN, i.e. `s.example.com` or `*` (catch all). Requested url can be regex, for example `^/api/(.*)` and destination url
Server can be set as FQDN, i.e. `s.example.com` or `*` (catch all). Requested url can be regex, for example `^/api/(.*)` and destination url
may have regex matched groups, 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 in 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`
Both HTTP and HTTPS supported for the server. 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 dpx requires at least one provider defined. The rest of parameters are strictly optional and have sane default.
Starting reproxy requires at least one provider defined. The rest of parameters are strictly optional and have sane default.
example with a static provider: `reproxy --static.enabled --rule="example.com/api/(.*),https://api.example.com/$1"`
## Providers
User can sets multiple providers at the same time.
### Static
This is the simplest provider defining all mapping rules directly in the command line (or environment). Multiple rules can be defined.
Each rule is 2 or 3 comma-separated elements `[server,]sourceurl,destination`. For example:
This is the simplest provider defining all mapping rules directly in the command line (or environment). Multiple rules supported.
Each rule is 3 or 4 comma-separated elements `server,sourceurl,destination,[ping-url]`. For example:
- `^/api/(.*),https://api.example.com/$1` - proxy all request to any host/server with `/api` prefix to `https://api.example.com`
- `*,^/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` - proxy all requests to `example.com` and with `/foo/bar` url to `https://api.example.com/zzz`
## File
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`. See [Health check]() section for more details.
### File
`reproxy --file.enabled --file.name=config.yml`
example of `config.yml`:
```yaml
- {server: "*", route: "^/api/svc1/(.*)", dest: "http://127.0.0.1:8080/blah1/$1"}
- {server: "srv.example.com", route: "^/api/svc2/(.*)", dest: "http://127.0.0.2:8080/blah2/$1/abc"}
- {server: "*", route: "/api/svc3/xyz", dest: "http://127.0.0.3:8080/blah3/xyz"}
```
## Docker
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"}
srv.example.com:
- {route: "^/api/svc2/(.*)", dest: "http://127.0.0.2:8080/blah2/$1/abc"}
## Application Options
```
This is a dynamic provider and file change will be applied automatically.
### Docker
Docker provider works with no extra configuration and by default redirects all requests like `https://server/api/<container_name>/(.*)` to the internal IP of 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
- reproxy.route - source route (location)
- reproxy.dest - destination URL
- reproxy.ping - ping url for the destination container
This is a dynamic provider and any change in container's status will be applied automatically.
## SSL support
SSL mode (by default none) can be set to `auto` (ACME/LE certificates), `static` (existing certificate) or `none`. If `auto` turned on SSL certificate will be issued automatically for all discovered server names. User can override it by setting `--ssl.fqdn` value(s)
## Logging
By default no request log generated. This can be turned on by setting `--logger.enabled`. The log (auto-rotated) has [Apache Combined Log Format](http://httpd.apache.org/docs/2.2/logs.html#combined)
## Assets Server
User may turn assets server on (off by default) to serve static files. As long as `--assets.location` set it will treat every non-proxied request under `assets.root` as a request for static files.
## More options
- `--gzip` enables gizp compression for responses.
- `--max=N` allows to set the maximum size of request (default 64k)
- `--header` sets extra header(s) added to each proxied request
## All Application Options
```
-l, --listen= listen on host:port (default: 127.0.0.1:8080) [$LISTEN]
-t, --timeout= proxy timeout (default: 5s) [$TIMEOUT]
--max= max response size (default: 64000) [$MAX_SIZE]
-m, --max= max response size (default: 64000) [$MAX_SIZE]
-g, --gzip enable gz compression [$GZIP]
-x, --header= proxy headers [$HEADER]
--no-signature disable reproxy signature headers [$NO_SIGNATURE]
--dbg debug mode [$DEBUG]
ssl:
@ -52,21 +95,28 @@ ssl:
--ssl.key= path to key.pem file [$SSL_KEY]
--ssl.acme-location= dir where certificates will be stored by autocert manager (default: ./var/acme) [$SSL_ACME_LOCATION]
--ssl.acme-email= admin email for certificate notifications [$SSL_ACME_EMAIL]
--ssl.http-port= http port for redirect to https and acme challenge [$SSL_HTTP_PORT]
--ssl.http-port= http port for redirect to https and acme challenge test (default: 80) [$SSL_HTTP_PORT]
--ssl.fqdn= FQDN(s) for ACME certificates [$SSL_ACME_FQDN]
assets:
-a, --assets.location= assets location [$ASSETS_LOCATION]
--assets.root= assets web root (default: /) [$ASSETS_ROOT]
logger:
--logger.enabled enable access and error rotated logs [$LOGGER_ENABLED]
--logger.file= location of access log (default: access.log) [$LOGGER_FILE]
--logger.max-size= maximum size in megabytes before it gets rotated (default: 100) [$LOGGER_MAX_SIZE]
--logger.max-backups= maximum number of old log files to retain (default: 10) [$LOGGER_MAX_BACKUPS]
docker:
--docker.enabled enable docker provider [$DOCKER_ENABLED]
--docker.host= docker host (default: unix:///var/run/docker.sock) [$DOCKER_HOST]
--docker.network= docker network (default: default) [$DOCKER_NETWORK]
--docker.network= docker network (default: bridge) [$DOCKER_NETWORK]
--docker.exclude= excluded containers [$DOCKER_EXCLUDE]
file:
--file.enabled enable file provider [$FILE_ENABLED]
--file.name= file name (default: dpx.yml) [$FILE_NAME]
--file.name= file name (default: reproxy.yml) [$FILE_NAME]
--file.interval= file check interval (default: 3s) [$FILE_INTERVAL]
--file.delay= file event delay (default: 500ms) [$FILE_DELAY]
@ -77,4 +127,8 @@ static:
Help Options:
-h, --help Show this help message
```
```
## Status
The project is under active development and may have breaking changes till `v1` released.