https://github.com/kingsquare/dokku-nginx-vhost-trustproxy

Dokku plugin for trusting nginx-vhost proxy headers
https://github.com/kingsquare/dokku-nginx-vhost-trustproxy

dokku dokku-plugin wip

Last synced: 9 days ago
JSON representation

Dokku plugin for trusting nginx-vhost proxy headers

• Host: GitHub
• URL: https://github.com/kingsquare/dokku-nginx-vhost-trustproxy
• Owner: kingsquare
• Created: 2019-03-18T21:20:00.000Z (over 5 years ago)
• Default Branch: master
• Last Pushed: 2020-11-19T08:48:45.000Z (almost 4 years ago)
• Last Synced: 2024-08-01T13:38:33.108Z (3 months ago)
• Topics: dokku, dokku-plugin, wip
• Language: Shell
• Size: 21.5 KB
• Stars: 10
• Watchers: 5
• Forks: 1
• Open Issues: 0
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
[![DOKKU](https://img.shields.io/badge/DOKKU->=0.4.x-success.svg)](http://dokku.viewdocs.io/dokku/development/plugin-creation/)

[![Blazing Fast](https://img.shields.io/badge/Blazing-Fast-success.svg)](https://twitter.com/acdlite/status/974390255393505280)

# dokku-nginx-vhost-trustproxy

If your deployment architecture is `proxy* -> dokku-host -> app` then you most probably want the client's

remote IP within the app to actually be the correct client IP and not the IP of the known `proxy`.

This plugin enables allowing an application's dokku-host nginx-vhost to forward the correct headers (`X-Forwarded-*`) from the [upstream proxy](http://tools.ietf.org/html/rfc2616#section-1.3) to the downstream app.

## Installation

    # on 0.4.x+

    sudo dokku plugin:install https://github.com/kingsquare/dokku-nginx-vhost-trustproxy.git#v0.0.1-alpha2

## Commands

|Command|Description|

|---|---|

|`nginx-vhost-trustproxy:enable  [depth]`|Trust the nth hop from the dokku host as the client IP. Default is 1 so `dokku-host -> app`. For each extra proxy increase the depth. This sets an environment property `NGINX_VHOST_TRUSTPROXY` with the depth + 1|

|`nginx-vhost-trustproxy:disable `|Disable trustproxy *This reverts to the default dokku behaviour.*|

|`nginx-vhost-trustproxy:status `|Get trustproxy status (if its enabled / disabled) |

## Application usage

Your app will be able to access the environment `NGINX_VHOST_TRUSTPROXY`. The value will be the trusted depth (including the dokku host; i.e. 1 + 1). The left most IP according to your depth should be used as the Client/Remote IP.

e.g.

|Hop 0|Hop 1|Hop 2|

|---|---|---|

|`app` | `dokku-vhost` | `proxy` |

### expressjs example

In your application you will have to use some kind of `trust proxy` to use the "correct" IP as the client IP. For example the `trust proxy` setting in [expressjs](https://expressjs.com/en/guide/behind-proxies.html). If you are not using express see the implementation in [proxy-addr](https://www.npmjs.com/package/proxy-addr). For other technologies/languages/platforms see their relevant documentation.

````javascript

  app.set('trust proxy', process.env.NGINX_VHOST_TRUSTPROXY || 1);

````

This will trust either the configured depth of hops (including the dokku host) or just the one (to the dokku host).

## Credits

This is slightly based on the reasoning for [expressjs's ](https://expressjs.com/en/guide/behind-proxies.html) `trust proxy` setting.