dokku · josegonzalez · Jul 2, 2023 · Jul 2, 2023 · Jul 2, 2023
diff --git a/docs/appendices/0.31.0-migration-guide.md b/docs/appendices/0.31.0-migration-guide.md
@@ -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.
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
@@ -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`                                                                                                                               | |

diff --git a/docs/configuration/ssl.md b/docs/configuration/ssl.md
@@ -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
 

diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md
@@ -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:

diff --git a/docs/getting-started/troubleshooting.md b/docs/getting-started/troubleshooting.md
@@ -74,12 +74,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.
 
@@ -235,16 +235,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
 

diff --git a/docs/networking/port-management.md b/docs/networking/port-management.md
@@ -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
+```
diff --git a/docs/networking/proxies/nginx.md b/docs/networking/proxies/nginx.md
@@ -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
 

diff --git a/docs/networking/proxy-management.md b/docs/networking/proxy-management.md
@@ -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.

diff --git a/plugins/ports/.gitignore b/plugins/ports/.gitignore
@@ -0,0 +1,7 @@
+/commands
+/subcommands/*
+/triggers/*
+/triggers
+/install
+/post-*
+/report
diff --git a/plugins/ports/Makefile b/plugins/ports/Makefile
@@ -0,0 +1,6 @@
+SUBCOMMANDS = subcommands/list subcommands/add subcommands/clear subcommands/remove subcommands/set subcommands/report
+TRIGGERS = triggers/post-certs-remove triggers/post-certs-update triggers/report
+BUILD = commands subcommands triggers
+PLUGIN_NAME = ports
+
+include ../../common.mk