noxy
A simple Docker container that uses nginx as a reverse proxy to some backend microservices.
Use as a replacement for k8s ingress for use in a docker-compose development stack.
install
$ docker pull binocarlos/noxy
example
Here is a docker-compose file that uses noxy to front 3 other services and serves static content from a local build folder.
version: '2'
services:
# some backend api servers
products:
build:
context: ./products
reviews:
build:
context: ./reviews
webserver:
build:
context: ./webserver
# the router config
router:
image: binocarlos/noxy:v3
links:
- products:products
- reviews:reviews
- webserver:webserver
environment:
NOXY_PRODUCTS_FRONT: /products/v1
NOXY_PRODUCTS_HOST: products
NOXY_PRODUCTS_BACK: /
NOXY_REVIEWS_FRONT: /reviews/v1
NOXY_REVIEWS_HOST: reviews
NOXY_REVIEWS_PORT: 8273
NOXY_REVIEWS_BACK: /custombackendpath
NOXY_REVIEWS_BASIC_AUTH_USERNAME: admin
NOXY_REVIEWS_BASIC_AUTH_PASSWORD: apples
# enable websockets for this virtual host
NOXY_REVIEWS_WS: 1
NOXY_DEFAULT_HOST: webserver
usage
For each backend service you have - there are 4 env variables:
NOXY_XXX_FRONT
- the incoming route to match (anything below this will also match)NOXY_XXX_HOST
- the hostname for the serviceNOXY_XXX_REDIRECT
- means all routes will get a 302 redirect to hereNOXY_XXX_PORT
- the port for the service (default = 80)NOXY_XXX_BACK
- map the frontend route onto the backend routeNOXY_XXX_WS
- enable websockets for this backendNOXY_XXX_BASIC_AUTH_USERNAME
- activate basic auth for this route using the given usernameNOXY_XXX_BASIC_AUTH_PASSWORD
- activate basic auth for this route using the given password
FRONT
The FRONT setting for a route matches the incoming request and will proxy if it matches.
For example a GET /products/v1/1234
would match our NOXY_PRODUCTS_FRONT
and the request would be proxied to the products service.
HOST
The HOST
setting controls where to proxy matching requests to.
If the value starts with env:
- for example NOXY_PRODUCTS_HOST=env:PRODUCTS_SERVICE_HOST
- it means:
set the
PRODUCTS
service hostname to the value of thePRODUCTS_SERVICE_HOST
env var
This is useful if you are running something like Kubernetes where the backend service hostname is written into the env and you can only know it at runtime.
PORT
The PORT
value controls the port for the backend service - this defaults to 80.
BACK (optional)
If you provide a BACK setting - the frontend setting will be replaced by it for the request to the backend service. This is useful if the backend service has a different mount-point and you want to map requests from a public frontend url to a different backend url.
For example a GET /reviews/v1/123
would result in a GET /custombackendpath/123
to our reviews service.
If you don't provide a BACK option - the bnackend url will be the same as the incoming request.
WS (optional)
If this is set to a truthy value, the following headers will be added to the nginx location block:
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
REDIRECT (optional)
This changes the meaning of the virtual host entry from proxy requests to this backend
to redirect requests to this other host
.
The HOST
property is used as the hostname for the server and the REDIRECT
value is used as the target redirect.
For example - to redirect any incoming request for abc.com
to xyz.con
:
NOXY_ABC_HOST: abc.com
NOXY_ABC_REDIRECT: http://xyz.com
You must include http://
or https://
in the redirect value - this lets you use noxy as a HTTPS redirector.
BASIC_AUTH_{USERNAME,PASSWORD} (optional)
Providing both of these values for a group will activate basic authentication for the route
NOXY_DEFAULT_HOST
You must provide a NOXY_DEFAULT_HOST
setting - this is the service to which requests that do not match any other service will be routed.
The FRONT
and BACK
settings are ignored - it is usually the case you use your static webserver as the default route.
change the port of noxy itself
To make noxy itself (nginx) listen on a different port, set NOXY_PORT
. It defaults to 80.
debug
To get a printout of the nginx config noxy is creating:
$ make debug
license
MIT