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

docs: add docs and tests for this feature

Browse Source
This commit is contained in:
Jose Diaz-Gonzalez
2026-07-22 03:45:32 -04:00
parent 3f13949337
commit 9c61031f3e
2 changed files with 89 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -221,8 +221,61 @@ You can pass flags which will output only the value of the specific information
dokku ports:report node-js-app --ports-map
```
Use `--ports-map-json` or `--ports-map-detected-json` to get the same data as a JSON array of objects. Each object has the following fields:
- `scheme`: the port scheme (e.g. `http`, `https`, `udp`)
- `host_port`: the host/listener port
- `container_port`: the container port
```shell
dokku ports:report node-js-app --ports-map-json
```
```json
[
{
"scheme": "http",
"host_port": 80,
"container_port": 5000
},
{
"scheme": "https",
"host_port": 443,
"container_port": 5000
}
]
```
The JSON output can be processed with tools such as `jq`:
```shell
dokku ports:report node-js-app --ports-map-json | jq '.[].host_port'
```
```
80
443
```
```shell
dokku ports:report node-js-app --ports-map-detected-json | jq '.[0].container_port'
```
```
5000
```
## Properties
### Configured flags
The following flags surface configured port mappings managed by `ports:set` / `ports:add` / `ports:remove` / `ports:clear`:
| Flag | Description |
|---|---|
| `--ports-map` | Configured port mappings as space-separated `scheme:host-port:container-port` values |
| `--ports-map-json` | Configured port mappings as a JSON array of `{scheme, host_port, container_port}` objects |
### Read-only flags
The following flags surface in `ports:report` but are not managed by `ports:set` - they are derived from the deploy:
@@ -230,3 +283,4 @@ The following flags surface in `ports:report` but are not managed by `ports:set`
| Flag | Description |
|---|---|
| `--ports-map-detected` | Port mapping inferred from `EXPOSE` directives or the running container |
| `--ports-map-detected-json` | Detected port mappings as a JSON array of `{scheme, host_port, container_port}` objects |

35
tests/unit/ports.bats
View File

@@ -50,6 +50,11 @@ teardown() {
echo "status: $status"
assert_output "http:1234:5001"
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-json | jq -e 'length == 1 and .[0].scheme == \"http\" and .[0].host_port == 1234 and .[0].container_port == 5001'"
echo "output: $output"
echo "status: $status"
assert_success
run /bin/bash -c "dokku ports:add $TEST_APP http:8080:5002 https:8443:5003"
echo "output: $output"
echo "status: $status"
@@ -60,6 +65,11 @@ teardown() {
echo "status: $status"
assert_output "http:1234:5001 http:8080:5002 https:8443:5003"
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-json | jq -e 'length == 3 and any(.scheme == \"http\" and .host_port == 1234 and .container_port == 5001) and any(.scheme == \"http\" and .host_port == 8080 and .container_port == 5002) and any(.scheme == \"https\" and .host_port == 8443 and .container_port == 5003)'"
echo "output: $output"
echo "status: $status"
assert_success
run /bin/bash -c "dokku ports:set $TEST_APP http:8080:5000 https:8443:5000 http:1234:5001"
echo "output: $output"
echo "status: $status"
@@ -90,6 +100,11 @@ teardown() {
echo "status: $status"
assert_output "http:1234:5001 http:8080:5000 https:8443:5000"
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-json | jq -e 'length == 3 and any(.scheme == \"http\" and .host_port == 1234 and .container_port == 5001) and any(.scheme == \"http\" and .host_port == 8080 and .container_port == 5000) and any(.scheme == \"https\" and .host_port == 8443 and .container_port == 5000)'"
echo "output: $output"
echo "status: $status"
assert_success
run /bin/bash -c "dokku ports:remove $TEST_APP 8080"
echo "output: $output"
echo "status: $status"
@@ -100,6 +115,11 @@ teardown() {
echo "status: $status"
assert_output "http:1234:5001 https:8443:5000"
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-json | jq -e 'length == 2 and any(.scheme == \"http\" and .host_port == 1234 and .container_port == 5001) and any(.scheme == \"https\" and .host_port == 8443 and .container_port == 5000)'"
echo "output: $output"
echo "status: $status"
assert_success
run /bin/bash -c "dokku ports:remove $TEST_APP http:1234:5001"
echo "output: $output"
echo "status: $status"
@@ -110,6 +130,11 @@ teardown() {
echo "status: $status"
assert_output "https:8443:5000"
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-json | jq -e 'length == 1 and .[0].scheme == \"https\" and .[0].host_port == 8443 and .[0].container_port == 5000'"
echo "output: $output"
echo "status: $status"
assert_success
run /bin/bash -c "dokku ports:clear $TEST_APP"
echo "output: $output"
echo "status: $status"
@@ -120,10 +145,20 @@ teardown() {
echo "status: $status"
assert_output_not_exists
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-json | jq -e '. == [] or . == null'"
echo "output: $output"
echo "status: $status"
assert_success
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-detected"
echo "output: $output"
echo "status: $status"
assert_output "http:80:5000"
run /bin/bash -c "dokku --quiet ports:report $TEST_APP --ports-map-detected-json | jq -e 'length == 1 and .[0].scheme == \"http\" and .[0].host_port == 80 and .[0].container_port == 5000'"
echo "output: $output"
echo "status: $status"
assert_success
}
@test "(ports:add) post-deploy add" {