Mirrors/dokku
1
0
Fork 0
mirror of https://github.com/dokku/dokku.git synced 2025-12-29 00:25:08 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3042 from dokku/port-management-docs

Browse Source 
docs: Improve documentation around port handling.
This commit is contained in:
Jose Diaz-Gonzalez
2018-01-21 17:49:53 -05:00
committed by GitHub
parent 5ee42f876e 463c5b8120
commit c09e102692
6 changed files with 173 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/deployment/methods/dockerfiles.md
View File

@@ -13,15 +13,7 @@ To use a dockerfile for deployment, commit a valid `Dockerfile` to the root of y
## Exposed ports
> Changed as of 0.5.0
Dokku will extract all tcp ports exposed using the `EXPOSE` directive (one port per line) and setup nginx to proxy the same port numbers to listen publicly. If you would like to change the exposed port, you should do so within your `Dockerfile` and app.
> Note: If ports are specified via `EXPOSE` in your `Dockerfile`, we will proxy requests to the first port specified. Your application must be configured to listen on that port.
If you do not explicitly `EXPOSE` a port in your `Dockerfile`, Dokku will configure the nginx proxy to listen on port 80 (and 443 for TLS) and forward traffic to your app listening on port 5000 inside the container. Just like buildpack apps, you can also use the `$PORT` environment variable in your app to maintain portability.
When ports are exposed through the default nginx proxy, they are proxied externally as HTTP ports. At this time, in no case do we proxy plain TCP or UDP ports. Nginx does not support proxying UDP. UDP ports can be exposed by disabling the nginx proxy with `dokku proxy:disable myapp`. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/docs/advanced-usage/proxy-management.md).
See the [port management documentation](/docs/advanced-usage/port-management.md).
## Build-time Configuration Variables

7
docs/deployment/methods/images.md
View File

@@ -20,6 +20,10 @@ The Dokku tags plugin allows you to add docker image tags to the currently deplo
## Usage
### Exposed ports
See the [port management documentation](/docs/advanced-usage/port-management.md).
### Listing tags for an application
For example, you can list all tags for a given application:
@@ -124,9 +128,6 @@ You can alternatively add image pulled from a docker Registry and deploy app fro
dokku tags:deploy test-app v12
```
> Note: When deploying an image, we will use `docker inspect` to extract the `ExposedPorts` configuration and if defined, use that to populate `DOKKU_DOCKERFILE_PORTS`. If this behavior is not desired, you can override that configuration variable with the `config:set` command.
> Example: `dokku config:set test-app DOKKU_DOCKERFILE_PORTS="5984/tcp 80/tcp"`
### Deploying an image from CI
To ensure your builds are always reproducible, it's considered bad practice to store build

1
docs/networking/dns.md
View File

@@ -24,7 +24,6 @@ Please remember that DNS relies heavily on _caching_. Changes you make to DNS c
Don't be afraid to ask if you need help. Create a [new issue](https://github.com/dokku/dokku/issues) and someone will be glad to assist you.
## Getting started
For the examples, we will use the domain name `example.tld` and the IP address `127.0.0.1`.

162
docs/networking/port-management.md Normal file
View File

@@ -0,0 +1,162 @@
# Port Management
> New as of 0.5.0, Enhanced in 0.6.0
```
proxy:ports <app> # List proxy port mappings for app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set proxy port mappings for app
proxy:ports-clear <app> # Clear all proxy port mappings for app
proxy:ports-remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Unset proxy port mappings for app
```
In Dokku 0.5.0, port proxying was decoupled from the `nginx-vhosts` plugin into the proxy plugin. Dokku 0.6.0 introduced the ability to map host ports to specific container ports. In the future this will allow other proxy software - such as HAProxy or Caddy - to be used in place of nginx.
## Usage
### Proxy port mapping
> New as of 0.6.0
You can now configure `host -> container` port mappings with the `proxy:ports-*` commands. This mapping is currently supported by the built-in nginx-vhosts plugin.
To inspect the port mapping for a given application, use the `proxy:ports` command:
```shell
dokku proxy:ports node-js-app
```
```
-----> Port mappings for node-js-app
-----> scheme host port container port
http 80 5000
```
The above application is listening on the host's port `80`, which we can test via curl:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
There are cases where we may wish for the service to be listening on more than one port, such as port 8080. Normally, this would not be possible:
```shell
curl http://node-js-app.dokku.me:8080
```
```
curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused
```
However, we can use the `proxy:ports-add` command to add a second external port mapping - `8080` - to our application's port `5000`.
```shell
dokku proxy:ports-add node-js-app http:8080:5000
```
```
-----> Setting config vars
DOKKU_PROXY_PORT_MAP: http:80:5000 http:8080:5000
-----> Configuring node-js-app.dokku.me...(using built-in template)
-----> Creating http nginx.conf
-----> Running nginx-pre-reload
Reloading nginx
```
We can now test that port 80 still responds properly:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
And our new listening port of `8080` also works:
```shell
curl http://node-js-app.dokku.me:8080
```
```
Hello World!
```
You can also remove a port mapping that is no longer necessary:
```shell
dokku proxy:ports-remove node-js-app http:80:5000
```
By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.
> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `proxy:ports-*` syntax detailed above.
## Port management by Deployment Method
> WARNING: If you set a proxy port map but _do not have a global domain set_, Dokku will reset that map upon first deployment.
### Buildpacks
For buildpack deployments, your application *must* respect the `PORT` environment variable. We will typically set this to port `5000`, but this is not guaranteed. If you do not respect the `PORT` environment variable, your containers may start but your services will not be accessible outside of that container.
### Dockerfile
> Changed as of 0.5.0
Dokku's default proxy implementation - nginx - only supports HTTP request proxying. At this time, we do not support proxying plain TCP or UDP ports. UDP ports can be exposed by disabling the nginx proxy with `dokku proxy:disable myapp`. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/docs/advanced-usage/proxy-management.md).
#### Applications using EXPOSE
Dokku will extract all tcp ports exposed using the `EXPOSE` directive (one port per line) and setup nginx to proxy the same port numbers to listen publicly. If you would like to change the exposed port, you should do so within your `Dockerfile`.
For example, if the Dokku installation is configured with the domain `dokku.me` and an application named `node-js-app` is deployed with following Dockerfile:
```
FROM ubuntu:14.04
EXPOSE 1234
RUN python -m SimpleHTTPServer 1234
```
The application would be exposed to the user at `node-js-app.dokku.me:1234`. If this is not desired, the following application configuration may be applied:
```shell
# add a port mapping to port 80
dokku proxy:ports-add node-js-app http:80:1234
# remove the incorrect port mapping
dokku proxy:ports-remove node-js-app http:1234:1234
```
#### Applications not using EXPOSE
Any application that does not use an `EXPOSE` directive will result in Dokku defaulting to port `5000`. This behavior mimics the behavior of a Buildpack deploy. If your application _does not_ support the `PORT` environment variable, then you will either need to:
- modify your application to support the `PORT` environment variable.
- switch to using an `EXPOSE` directive in your Dockerfile.
#### Switching between `EXPOSE` usage modes
When switching between `EXPOSE` usage modes, it is important to reset your port management. The following two commands can be used to reset your state and redeploy your application.
```shell
# assuming your application is called `node-js-app`
dokku config:unset --no-restart node-js-app DOKKU_DOCKERFILE_PORTS PORT
dokku proxy:ports-clear node-js-app
```
### Docker Image
When deploying an image, we will use `docker inspect` to extract the `ExposedPorts` configuration and if defined, use that to populate port mapping. If this behavior is not desired, you can override that configuration variable with the following commands.
```shell
# assuming your application is called `node-js-app`
dokku config:set node-js-app DOKKU_DOCKERFILE_PORTS="1234/tcp 80/tcp"
dokku proxy:ports-clear node-js-app
```
All other port-related behavior is the same as when deploying via Dockerfile.

91
docs/networking/proxy-management.md
View File

@@ -5,10 +5,6 @@
```
proxy:disable <app> # Disable proxy for app
proxy:enable <app> # Enable proxy for app
proxy:ports <app> # List proxy port mappings for app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set proxy port mappings for app
proxy:ports-clear <app> # Clear all proxy port mappings for app
proxy:ports-remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Unset proxy port mappings for app
proxy:report [<app>] [<flag>] # Displays a proxy report for one or more apps
proxy:set <app> <proxy-type> # Set proxy type for app
```
@@ -67,89 +63,6 @@ You can pass flags which will output only the value of the specific information
dokku proxy:report node-js-app --proxy-type
```
### Proxy port mapping
> New as of 0.6.0
You can now configure `host -> container` port mappings with the `proxy:ports-*` commands. This mapping is currently supported by the built-in nginx-vhosts plugin.
To inspect the port mapping for a given application, use the `proxy:ports` command:
```shell
dokku proxy:ports node-js-app
```
```
-----> Port mappings for node-js-app
-----> scheme host port container port
http 80 5000
```
The above application is listening on the host's port `80`, which we can test via curl:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
There are cases where we may wish for the service to be listening on more than one port, such as port 8080. Normally, this would not be possible:
```shell
curl http://node-js-app.dokku.me:8080
```
```
curl: (7) Failed to connect to node-js-app.dokku.me port 8080: Connection refused
```
However, we can use the `proxy:ports-add` command to add a second external port mapping - `8080` - to our application's port `5000`.
```shell
dokku proxy:ports-add node-js-app http:8080:5000
```
```
-----> Setting config vars
DOKKU_PROXY_PORT_MAP: http:80:5000 http:8080:5000
-----> Configuring node-js-app.dokku.me...(using built-in template)
-----> Creating http nginx.conf
-----> Running nginx-pre-reload
Reloading nginx
```
We can now test that port 80 still responds properly:
```shell
curl http://node-js-app.dokku.me
```
```
Hello World!
```
And our new listening port of `8080` also works:
```shell
curl http://node-js-app.dokku.me:8080
```
```
Hello World!
```
You can also remove a port mapping that is no longer necessary:
```shell
dokku proxy:ports-remove node-js-app http:80:5000
```
By default, buildpack apps and dockerfile apps **without** explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on port `80` (and additionally a listener on 443 if ssl is enabled) that will proxy to the application container on port `5000`. Dockerfile apps **with** explicitly exposed ports will be configured with a listener on each exposed port and will proxy to that same port of the deployed application container.
> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `proxy:ports-*` syntax detailed above.
#### Proxy Port Scheme
The proxy port scheme is as follows:
@@ -167,3 +80,7 @@ To change the proxy implementation in use for an application, use the `proxy:set
# the specified proxy implementation
dokku proxy:set node-js-app nginx
```
### Proxy port mapping
See the [port management documentation](/docs/advanced-usage/port-management.md).

3
docs/template.html
View File

@@ -144,7 +144,8 @@
<a href="/{{NAME}}/networking/dns/" class="list-group-item">DNS Configuration</a>
<a href="/{{NAME}}/networking/network/" class="list-group-item">Network Management</a>
<a href="/{{NAME}}/networking/proxy-management/" class="list-group-item">Proxy and Port Management</a>
<a href="/{{NAME}}/networking/port-management/" class="list-group-item">Port Management</a>
<a href="/{{NAME}}/networking/proxy-management/" class="list-group-item">Proxy Management</a>
<a href="#" class="list-group-item disabled">Advanced Usage</a>