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

3
docs/appendices/0.31.0-migration-guide.md
View File

@@ -1,5 +1,6 @@
# 0.30.0 Migration Guide
# 0.31.0 Migration Guide
## Changes
- Herokuish build cache is now mounted from a docker volume - eg. `cache-node-js-app` - instead of the local filesystem. All existing app cache will be cleared upon upgrading past 0.29.0.
- The `proxy:ports*` commands have been replaced with the new `ports` plugin. Users will be able to use the old `proxy:ports*` commands for a single minor release, and they will be removed in the next minor release.

2
docs/configuration/environment-variables.md
View File

@@ -116,7 +116,7 @@ The following config variables have special meanings and can be set in a variety
| `DOKKU_PARALLEL_ARGUMENTS`. | none | `dokku config:set` | Allows passing custom arguments to parallel for `ps:*all` commands |
| `DOKKU_PROXY_PORT` | automatically assigned | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set` | |
| `DOKKU_PROXY_SSL_PORT` | automatically assigned | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` <br /> `dokku config:set` | |
| `DOKKU_PROXY_PORT_MAP` | automatically assigned | `dokku proxy:ports-add` <br /> `dokku proxy:ports-remove`, `dokku proxy:ports-clear` | |
| `DOKKU_PROXY_PORT_MAP` | automatically assigned | `dokku ports:add` <br /> `dokku ports:remove`, `dokku ports:clear` | |
| `DOKKU_SKIP_ALL_CHECKS` | none | `dokku config:set` | |
| `DOKKU_SKIP_CLEANUP` | | `/etc/environment` <br /> `~dokku/.dokkurc` <br /> `~dokku/.dokkurc/*` | When a deploy is triggered, if this is set to a non-empty value, then old docker containers and images will not be removed. |
| `DOKKU_SKIP_DEFAULT_CHECKS` | | `dokku config:set` | |

2
docs/configuration/ssl.md
View File

@@ -134,7 +134,7 @@ Certain versions of nginx have bugs that prevent [HTTP/2](https://nginx.org/en/d
### SSL Port Exposure
When your app is served from port `80` then the `/home/dokku/APP/nginx.conf` file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port `99999`) you may need to manually expose an ssl port via `dokku proxy:ports-add <APP> https:443:99999`.
When your app is served from port `80` then the `/home/dokku/APP/nginx.conf` file will automatically be updated to instruct nginx to respond to ssl on port 443 as a new cert is added. If your app uses a non-standard port (perhaps you have a dockerfile deploy exposing port `99999`) you may need to manually expose an ssl port via `dokku ports:add <APP> https:443:99999`.
## Other

6
docs/development/plugin-triggers.md
View File

@@ -1498,8 +1498,8 @@ popd &>/dev/null
### `post-proxy-ports-update`
- Description: Allows you to run commands once the proxy port mappings for an app have been updated. It also sends the invoking command. This can be "add", "clear" or "remove".
- Invoked by: `dokku proxy:ports-add`, `dokku proxy:ports-clear`, `dokku proxy:ports-remove`
- Description: Allows you to run commands once the port mappings for an app have been updated. It also sends the invoking command. This can be "add", "clear" or "remove".
- Invoked by: `dokku ports:add`, `dokku ports:clear`, `dokku ports:remove`
- Arguments: `$APP` `action name`
- Example:
@@ -1842,7 +1842,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
### `proxy-configure-ports`
- Description: Configures the proxy port mapping
- Description: Configures the port mapping
- Invoked by: `internally triggered by proxy plugins`
- Arguments: `$APP`
- Example:

16
docs/getting-started/troubleshooting.md
View File

@@ -72,12 +72,12 @@ For example, if you have an `EXPOSE` directive like so:
EXPOSE 8000
```
The proxy port mapping will be `http:8000:8000`.
The port mapping will be `http:8000:8000`.
To avoid this issue, either of the following can be done:
- Remove `EXPOSE` directive: This will require respecting the `$PORT` environment variable (automatically set by Dokku). Once that change is deployed, the port mapping should be cleared via the `dokku proxy:ports-clear $APP` command (where `$APP` is your app name).
- Update the port mapping: Updating the port mapping to redirect port `80` to your app's exposed port via `dokku proxy:ports-set $APP http:80:$EXPOSED_PORT` can also fix the issue. This will also allow certificate management and the letsencrypt plugin to work correctly.
- Remove `EXPOSE` directive: This will require respecting the `$PORT` environment variable (automatically set by Dokku). Once that change is deployed, the port mapping should be cleared via the `dokku ports:clear $APP` command (where `$APP` is your app name).
- Update the port mapping: Updating the port mapping to redirect port `80` to your app's exposed port via `dokku ports:set $APP http:80:$EXPOSED_PORT` can also fix the issue. This will also allow certificate management and the letsencrypt plugin to work correctly.
See the [port management documentation](/docs/networking/port-management.md) for more information on how Dokku exposes ports for applications and how you can configure these for your app.
@@ -233,16 +233,14 @@ If this solves the issue temporarily, longer term you should consider [configuri
### My application deploys properly, but won't load in browser "connection refused"
This could be a result of a bad proxy configuration (`http:5000:5000` may be incorrect). Run `dokku proxy:report myapp` to check if your app has the correct proxy configuration. It should show something like the following.
This could be a result of a bad proxy configuration (`http:5000:5000` may be incorrect). Run `dokku ports:report node-js-app` to check if your app has the correct proxy configuration. It should show something like the following.
```
=====> myapp proxy information
Proxy enabled: true
Proxy port map: http:80:5000 https:443:5000
Proxy type: nginx
=====> node-js-app ports information
Port map: http:80:5000 https:443:5000
```
Set `dokku proxy:ports-set front http:80:5000` to get proxy correctly configured for http endpoint.
Set `dokku ports:set node-js-app http:80:5000` to get proxy correctly configured for http endpoint.
### I deployed a new app but now subdomains are miss-routed

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.