github/dokku
0
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

refactor: move all port management code to standalone ports plugin

Browse Source 
This change makes interacting with port mappings more clear - folks might previously set the port mapping to the proxy type or vice-versa.

The existing proxy:ports* commands still exist but will show a deprecation warning for a single minor release.
This commit is contained in:
Jose Diaz-Gonzalez
2023-07-02 01:29:01 -04:00
parent a0b84d52ef
commit 64f0f2674d
43 changed files with 894 additions and 553 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
docs/networking/port-management.md
View File

@@ -1,37 +1,52 @@
# Port Management
> New as of 0.5.0, Enhanced in 0.6.0
> New as of 0.31.0, replaces the previous `proxy:ports*` commands
```
proxy:ports <app> # List proxy port mappings for an app
proxy:ports-add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Add proxy port mappings to an app
proxy:ports-clear <app> # Clear all proxy port mappings for an app
proxy:ports-remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Remove specific proxy port mappings from an app
proxy:ports-set <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set proxy port mappings for an app
ports:list <app> # List port mappings for an app
ports:add <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Add port mappings to an app
ports:clear <app> # Clear all port mappings for an app
ports:remove <app> <host-port> [<host-port>|<scheme>:<host-port>:<container-port>...] # Remove specific port mappings from an app
ports:set <app> <scheme>:<host-port>:<container-port> [<scheme>:<host-port>:<container-port>...] # Set port mappings for an 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
> Warning: Mapping alternative ports may conflict with the active firewall installed on your server or hosting provider. Such software includes - but is not limited to - AWS Security Groups, iptables, and UFW. Please consult the documentation for those softwares as applicable.
>
> Users should also avoid setting the `PORT` environment variable. Dokku will use port mappings to set this value. Overriding this manually may cause issues in application routing.
> 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.
You can now configure `host -> container` port mappings with the `ports:*` commands. This mapping is currently supported by the built-in nginx-vhosts plugin.
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-*` commands detailed below.
> Note: This default behavior **will not** be automatically changed on subsequent pushes and must be manipulated with the `ports:*` commands detailed below.
### Port Scheme
The proxy port scheme is as follows:
- `SCHEME:HOST_PORT:CONTAINER_PORT`
The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in `nginx-vhosts` proxy implementation supports the `http`, `https`, `grpc` and `grpcs` schemes.
For the `grpc` and `grpcs` see [nginx blog post on grpc](https://www.nginx.com/blog/nginx-1-13-10-grpc/).
Developers of proxy implementations are encouraged to use whatever schemes make the most sense, and ignore configurations which they do not support. For instance, a `udp` proxy implementation can safely ignore `http` and `https` port mappings.
To change the proxy implementation in use for an application, use the `proxy:set` command:
```shell
# no validation will be performed against
# the specified proxy implementation
dokku proxy:set node-js-app nginx
```
### Listing port mappings
To inspect the port mapping for a given application, use the `proxy:ports` command:
To inspect the port mapping for a given application, use the `ports:list` command:
```shell
dokku proxy:ports node-js-app
dokku ports:list node-js-app
```
```
@@ -62,10 +77,10 @@ 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`.
However, we can use the `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
dokku ports:add node-js-app http:8080:5000
```
```
@@ -98,10 +113,10 @@ Hello World!
### Setting all port mappings at once
Port mappings can also be force set using the `proxy:ports-set` command.
Port mappings can also be force set using the `ports:set` command.
```shell
dokku proxy:ports-set node-js-app http:8080:5000
dokku ports:set node-js-app http:8080:5000
```
```
@@ -114,21 +129,21 @@ dokku proxy:ports-set node-js-app http:8080:5000
### Removing a port mapping
A port mapping can be removed using the `proxy:ports-remove` command if it no longer necessary:
A port mapping can be removed using the `ports:remove` command if it no longer necessary:
```shell
dokku proxy:ports-remove node-js-app http:80:5000
dokku ports:remove node-js-app http:80:5000
```
Ports may also be removed by specifying only the `host-port` value. This effectively acts as a wildcard and removes all mappings for that particular host port.
```shell
dokku proxy:ports-remove node-js-app http:80
dokku ports:remove node-js-app http:80
```
## 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.
> Warning: If you set a port map but _do not have a global domain set_, Dokku will reset that map upon first deployment.
### Buildpacks
@@ -156,10 +171,10 @@ The application would be exposed to the user at `node-js-app.dokku.me:1234`. If
```shell
# add a port mapping to port 80
dokku proxy:ports-add node-js-app http:80:1234
dokku ports:add node-js-app http:80:1234
# remove the incorrect port mapping
dokku proxy:ports-remove node-js-app http:1234:1234
dokku ports:remove node-js-app http:1234:1234
```
#### Applications not using EXPOSE
@@ -176,7 +191,7 @@ When switching between `EXPOSE` usage modes, it is important to reset your port
```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
dokku ports:clear node-js-app
```
### Docker Image
@@ -186,7 +201,41 @@ When deploying an image, we will use `docker inspect` to extract the `ExposedPor
```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
dokku ports:clear node-js-app
```
All other port-related behavior is the same as when deploying via Dockerfile.
### Displaying ports reports for an app
You can get a report about the app's ports status using the `ports:report` command:
```shell
dokku ports:report
```
```
=====> node-js-app ports information
Port map: http:80:5000 https:443:5000
=====> python-sample ports information
Port map: http:80:5000
=====> ruby-sample ports information
Port map: http:80:5000
```
You can run the command for a specific app also.
```shell
dokku ports:report node-js-app
```
```
=====> node-js-app ports information
Port map: http:80:5000 https:443:5000
```
You can pass flags which will output only the value of the specific information you want. For example:
```shell
dokku ports:report node-js-app --ports-map
```

2
docs/networking/proxies/nginx.md
View File

@@ -506,7 +506,7 @@ See the [proxy documentation](/docs/networking/proxy-management.md) for more inf
### Managing Proxy Port mappings
See the [proxy documentation](/docs/networking/proxy-management.md#proxy-port-mapping) for more information on how to manage ports proxied for your app.
See the [ports documentation](/docs/networking/port-management.md) for more information on how to manage ports proxied for your app.
### Regenerating nginx config

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

@@ -73,15 +73,12 @@ dokku proxy:report
=====> node-js-app proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000 https:443:5000
=====> python-sample proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000
=====> ruby-sample proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000
```
You can run the command for a specific app also.
@@ -94,7 +91,6 @@ dokku proxy:report node-js-app
=====> node-js-app proxy information
Proxy enabled: true
Proxy type: nginx
Proxy port map: http:80:5000 https:443:5000
```
You can pass flags which will output only the value of the specific information you want. For example:
@@ -105,22 +101,7 @@ dokku proxy:report node-js-app --proxy-type
#### Proxy Port Scheme
The proxy port scheme is as follows:
- `SCHEME:HOST_PORT:CONTAINER_PORT`
The scheme metadata can be used by proxy implementations in order to properly handle proxying of requests. For example, the built-in `nginx-vhosts` proxy implementation supports the `http`, `https`, `grpc` and `grpcs` schemes.
For the `grpc` and `grpcs` see [nginx blog post on grpc](https://www.nginx.com/blog/nginx-1-13-10-grpc/).
Developers of proxy implementations are encouraged to use whatever schemes make the most sense, and ignore configurations which they do not support. For instance, a `udp` proxy implementation can safely ignore `http` and `https` port mappings.
To change the proxy implementation in use for an application, use the `proxy:set` command:
```shell
# no validation will be performed against
# the specified proxy implementation
dokku proxy:set node-js-app nginx
```
See the [port scheme documentation](/docs/networking/port-management.md#port-scheme) for more information on the port mapping scheme used by dokku.
### Proxy port mapping
@@ -136,7 +117,7 @@ From Dokku versions `0.5.0` until `0.11.0`, enabling or disabling an application
Custom plugins names _must_ have the suffix `-vhosts` or scheduler overriding via `proxy:set` may not function as expected.
At this time, the following dokku commands are used to implement a complete proxy implementation.
At this time, the following dokku commands are used to interact with a complete proxy implementation.
- `domains:add`: Adds a given domain to an app.
- triggers: `post-domains-update`
@@ -158,13 +139,13 @@ At this time, the following dokku commands are used to implement a complete prox
- triggers: `proxy-disable`
- `proxy:enable`: Enables the proxy configuration for an app.
- triggers: `proxy-enable`
- `proxy:ports-add`: Adds one or more port mappings to an app
- `ports:add`: Adds one or more port mappings to an app
- triggers: `post-proxy-ports-update`
- `proxy:ports-clear`: Clears out all port mappings for an app.
- `ports:clear`: Clears out all port mappings for an app.
- triggers: `post-proxy-ports-update`
- `proxy:ports-remove`: Removes one or more port mappings from an app.
- `ports:remove`: Removes one or more port mappings from an app.
- triggers: `post-proxy-ports-update`
- `proxy:ports-set`: Sets all port mappings for an app.
- `ports:set`: Sets all port mappings for an app.
- triggers: `post-proxy-ports-update`
Proxy implementations may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins.