Release 0.31.2

# History

## 0.31.2

Install/update via the bootstrap script:

```shell
wget -NP . https://dokku.com/install/v0.31.2/bootstrap.sh
sudo DOKKU_TAG=v0.31.2 bash bootstrap.sh
```

### Bug Fixes

- #6154: @josegonzalez Ensure app clones have domains setup
- #6164: @josegonzalez Use correct path for openresty letsencrypt data
- #6165: @josegonzalez Ensure we cleanup extracted files prior to next deployment
- #6166: @josegonzalez Remove unused source from openresty trigger
- #6163: @josegonzalez Add missing triggers for openresty-vhosts plugin
- #6151: @josegonzalez Do not pass an empty argument to scheduler-run when triggering cron tasks manually
- #6150: @josegonzalez Correct issue where temp file cleanup fails deploy

### Documentation

- #6167: @josegonzalez Correct svg path on homepage
- #6153: @imankulov Fix superscript typos in plugin documentation

### Tests

- #6152: @josegonzalez Use buildjet for building arm images
- #6149: @josegonzalez Fix issue where CI cannot install docker-compose-plugin

### Dependencies

- #6161: @josegonzalez Upgrade sigil to 0.10.1
- #6162: @josegonzalez Upgrade herokuish to 0.7.1
- #6160: @josegonzalez Upgrade sshcommand to 0.17.1
- #6159: @josegonzalez Upgrade procfile-util to 0.16.0
- #6158: @josegonzalez Upgrade netrc to 0.7.1
- #6157: @josegonzalez Upgrade lambda-builder to 0.5.0
- #6147: @dependabot[bot] chore(deps): bump tj-actions/changed-files from 37.6.1 to 38.1.0
- #6145: @dependabot[bot] chore(deps): bump mkdocs-material from 9.2.2 to 9.2.3 in /docs/_build
- #6139: @dependabot[bot] chore(deps): bump flask from 2.3.2 to 2.3.3 in /tests/apps/multi
- #6140: @dependabot[bot] chore(deps): bump flask from 2.3.2 to 2.3.3 in /tests/apps/python-flask
- #6141: @dependabot[bot] chore(deps): bump mkdocs-material from 9.1.21 to 9.2.2 in /docs/_build

### Other

- #6148: @josegonzalez Add missing relabel command to docker-image-labeler for CNB builder

.devcontainer/devcontainer.json

@@ -7,12 +7,16 @@
     "DOKKU_HOST_ROOT": "${localWorkspaceFolder}/tmp/data/home/dokku",
     "GO_ROOT_MOUNT": "${localWorkspaceFolder}:/go/src/github.com/dokku/dokku"
   },
-  "extensions": [
-    "golang.go",
-    "mads-hartmann.bash-ide-vscode",
-    "ms-vscode.makefile-tools",
-    "sleistner.vscode-fileutils"
-  ],
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "golang.go",
+        "mads-hartmann.bash-ide-vscode",
+        "ms-vscode.makefile-tools",
+        "sleistner.vscode-fileutils"
+      ]
+    }
+  },
   "initializeCommand": ["mkdir", "-p", "tmp/data"],
   "mounts": [
     "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind",

.github/actions/build-image/action.yml

@@ -0,0 +1,39 @@
+---
+name: 'build-image'
+
+description: 'builds a dokku docker image'
+
+inputs:
+  architecture:
+    description: 'platform to build'
+    required: true
+    default: 'linux/amd64'
+
+runs:
+  using: "composite"
+  steps:
+    - name: download packages
+      uses: actions/download-artifact@v3
+      with:
+        name: build
+        path: build
+
+    - name: set up docker buildx
+      id: buildx
+      uses: docker/setup-buildx-action@v2
+
+    - name: build docker image
+      shell: bash
+      run: |
+        if [[ "${{ inputs.architecture }}" == "linux/arm" ]]; then
+          docker buildx build \
+                --platform linux/arm \
+                --progress plain \
+                --tag "dokku/dokku:latest" \
+                .
+        else
+          docker buildx build \
+                  --progress plain \
+                  --tag "dokku/dokku:latest" \
+                  .
+        fi

.github/commands/ci-setup

@@ -2,19 +2,23 @@
 set -eo pipefail
 set -x
 
+DOKKU_DOMAIN=${DOKKU_DOMAIN:="dokku.me"}
+
 echo "=====> set hostname"
 hostname
 internal_ip="$(ifconfig eth0 | grep 'inet ' | awk '{print $2}')"
-sudo hostname "dokku.me"
-echo "dokku.me" | sudo tee /etc/hostname
+sudo hostname "$DOKKU_DOMAIN"
+echo "$DOKKU_DOMAIN" | sudo tee /etc/hostname
 hostname
 sudo cat /etc/hostname
 
-echo "=====> resolve dokku.me"
+echo "=====> resolve $DOKKU_DOMAIN"
 sudo apt -qq -y --no-install-recommends install net-tools
-# dokku.me now resolves to 10.0.0.2. add 10.0.0.2/24 to eth0
-ifconfig
-sudo ip addr add 10.0.0.2/24 broadcast 10.0.0.255 dev eth0
+if [[ "$DOKKU_DOMAIN" == "dokku.me" ]]; then
+  # dokku.me now resolves to 10.0.0.2. add 10.0.0.2/24 to eth0
+  ifconfig
+  sudo ip addr add 10.0.0.2/24 broadcast 10.0.0.255 dev eth0
+fi
 
 echo "=====> install ci-dependencies"
 make ci-dependencies

.github/dependabot.yml

@@ -8,6 +8,125 @@ updates:
     open-pull-requests-limit: 10
     labels:
       - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/app-json"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/apps"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/builder"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/buildpacks"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/common"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/config"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/cron"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/docker-options"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/logs"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/network"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/nginx-vhosts"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/proxy"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/ps"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/registry"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/repo"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/resource"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/scheduler"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
   - package-ecosystem: bundler
     directory: "/tests/apps/ruby"
     schedule:

.github/linters/.markdown-lint.yml

@@ -8,3 +8,30 @@ MD013: false
 # Inline HTML
 # https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md033
 MD033: false
+
+# List indentation
+# 2 spaces breaks list formatting in mkdocs
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md007
+MD007:
+  indent: 4
+
+# Fenced code blocks should have a language specified
+# We use a second, un-languaged code block to denote the output
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md040
+MD040: false
+
+# Blank line inside blockquote
+# This is typically done when a section has a "New as of" or "Warning" in addition to a note
+# May wish to take advantage of github-style admonitions
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md028
+MD028: false
+
+# No duplicate headers
+# HISTORY.md has a ton of these
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md024
+MD024: false
+
+# First line h1
+# The issue template doesn't have one
+# https://github.com/DavidAnson/markdownlint/blob/main/doc/Rules.md#md041
+MD041: false

.github/workflows/ci.yml

@@ -14,10 +14,38 @@ concurrency:
   group: build-${{ github.event.pull_request.number || github.ref }}
   cancel-in-progress: true
 
+env:
+  INSTALL_DOCKER_REPO: 1
+
 jobs:
+  check-commit:
+    runs-on: ubuntu-20.04
+    outputs:
+      skip: ${{ steps.check-commit.outputs.skip }}
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: check if message contain keywords ace scopeid
+        id: check-commit
+        run: |
+          # checking for "docs" or "[ci skip]" messages
+          message=$(git log -1 --pretty=format:'%s')
+          if [[ "$message" =~ "\[(ci skip)\]" ]]; then
+            echo "Skipping tests due to [ci skip] message"
+            echo "skip=true" >> $GITHUB_OUTPUT
+          elif [[ "$message" =~ "^docs:" ]]; then
+            echo "Skipping tests due to "docs:" prefix on message"
+            echo "skip=true" >> $GITHUB_OUTPUT
+          fi
+
   build:
     name: build
     runs-on: ubuntu-20.04
+    needs: check-commit
+    if: ${{ needs.check-commit.outputs.skip != 'true' }}
     outputs:
       matrix: ${{ steps.set-matrix.outputs.matrix }}
     strategy:
@@ -36,6 +64,8 @@ jobs:
 
       - name: build package
         run: ./tests/ci/setup.sh build
+        env:
+          SKIP_IMAGE_BUILD: true
 
       - name: set matrix for build
         id: set-matrix
@@ -50,6 +80,51 @@ jobs:
           name: build
           path: build
 
+  build-image-amd64:
+    name: build-image.linux/amd64
+    needs: build
+    runs-on: ubuntu-20.04
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: build-image
+        uses: ./.github/actions/build-image
+        with:
+          architecture: linux/amd64
+
+  build-image-arm:
+    name: build-image.linux/arm
+    needs: build
+    runs-on: buildjet-4vcpu-ubuntu-2204-arm
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: set up qemu
+        uses: docker/setup-qemu-action@v2
+
+      - name: build-image
+        uses: ./.github/actions/build-image
+        with:
+          architecture: linux/arm
+
+  build-image-arm64:
+    name: build-image.linux/arm64
+    needs: build
+    runs-on: buildjet-4vcpu-ubuntu-2204-arm
+    timeout-minutes: 20
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: build-image
+        uses: ./.github/actions/build-image
+        with:
+          architecture: linux/arm64
+
   unit-tests:
     name: unit.${{ matrix.index }}
     needs: build
@@ -74,7 +149,7 @@ jobs:
       #   uses: luchihoratiu/debug-via-ssh@main
       #   with:
       #     NGROK_AUTH_TOKEN: ${{ secrets.NGROK_AUTH_TOKEN }}
-      #     SSH_PASS: ${{ secrets.SSH_PASS }}
+      #     SSH_PASS: ${{ secrets.NGROK_SSH_PASS }}
 
       - name: run ci
         timeout-minutes: 30
@@ -161,6 +236,8 @@ jobs:
     name: publish-test-results
     needs: unit-tests
     runs-on: ubuntu-20.04
+    permissions:
+      checks: write
     # the build-and-test job might be skipped, we don't need to run this job then
     if: success() || failure()
 

.github/workflows/lint.yml

@@ -27,12 +27,16 @@ jobs:
     steps:
       - name: Clone
         uses: actions/checkout@v3
-      - name: Run markdown-lint
-        uses: avto-dev/markdown-lint@04d43ee9191307b50935a753da3b775ab695eceb
-        # v1.5.0 => 04d43ee9191307b50935a753da3b775ab695eceb
+      - name: Setup node
+        uses: actions/setup-node@v3
         with:
-          config: '.github/linters/.markdown-lint.yml'
-          args: './README.md'
+          node-version: '20'
+          cache: 'npm'
+          cache-dependency-path: '.github/workflows/lint.yml'
+      - name: Install markdownlint-cli
+        run: npm install -g markdownlint-cli@0.35.0
+      - name: Run markdown-lint
+        run: markdownlint -c .github/linters/.markdown-lint.yml *.md **/*.md
 
   packer:
     name: packer
@@ -46,9 +50,17 @@ jobs:
           version: latest
       - name: Run packer init
         run: "make image/init/digitalocean"
+        env:
+          PACKER_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Get changed files in the docs folder
+        id: changed-files-specific
+        uses: tj-actions/changed-files@v38.1.0
+        with:
+          files: contrib/images/digitalocean/**
       - name: Run `packer validate`
         env:
           DIGITALOCEAN_TOKEN: ${{ secrets.DIGITALOCEAN_TOKEN }}
+        if: steps.changed-files-specific.outputs.any_changed == 'true'
         run: "make image/validate/digitalocean"
 
   shellcheck:
@@ -60,9 +72,6 @@ jobs:
       - name: Run shellcheck
         uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38
         # 1.1.0 => 94e0aab03ca135d11a35e5bfc14e6746dc56e7e9
-        env:
-          # keep in sync with tests/shellcheck-exclude
-          SHELLCHECK_OPTS: -e SC1001 -e SC1003 -e SC1090 -e SC1091 -e SC1117 -e SC2029 -e SC2030 -e SC2031 -e SC2034 -e SC2046 -e SC2064 -e SC2068 -e SC2086 -e SC2119 -e SC2120 -e SC2128 -e SC2148 -e SC2153 -e SC2154 -e SC2155 -e SC2162 -e SC2174 -e SC2179 -e SC2191 -e SC2199 -e SC2207 -e SC2219 -e SC2220 -e SC2230 -e SC2231 -e SC2235 -e SC2267 -e SC2295
 
   shfmt:
     name: shfmt

.github/workflows/release.yml

@@ -91,14 +91,16 @@ jobs:
       - name: Run `packer validate`
         env:
           DIGITALOCEAN_TOKEN: ${{ secrets.DIGITALOCEAN_TOKEN }}
-          PKR_VAR_dokku_version: ${{ needs.release.outputs.version }}
-        run: "make image/validate/digitalocean"
+        run: |
+          VERSION=${{ needs.release.outputs.version }}
+          PKR_VAR_dokku_version="${VERSION:1}" make image/validate/digitalocean
 
       - name: Bump Digitalocean Image
         env:
           DIGITALOCEAN_TOKEN: ${{ secrets.DIGITALOCEAN_TOKEN }}
-          PKR_VAR_dokku_version: ${{ needs.release.outputs.version }}
-        run: "make image/build/digitalocean"
+        run: |
+          VERSION=${{ needs.release.outputs.version }}
+          PKR_VAR_dokku_version="${VERSION:1}" make image/build/digitalocean
 
       - name: upload packages
         uses: actions/upload-artifact@v3

.gitignore

@@ -11,3 +11,4 @@ test-results/
 stack.tgz
 tmp
 coverage.out
+site

.shellcheckrc

@@ -1,9 +1,33 @@
+# SC1001 - This \/ will be a regular '/' in this context - https://github.com/koalaman/shellcheck/wiki/SC1001
+# SC1003 - Want to escape a single quote? echo 'This is how it'\''s done' - https://github.com/koalaman/shellcheck/wiki/SC1003
+# SC1090 - Can't follow non-constant source. Use a directive to specify location - https://github.com/koalaman/shellcheck/wiki/SC1090
 # SC1091 - Not following: FILE: does not exist (No such file or directory) - https://github.com/koalaman/shellcheck/wiki/SC1091
-#        - used for sourcing function files throughout the codebase
+# SC1117 - Backslash is literal in "\n". Prefer explicit escaping: "\\n" - https://github.com/koalaman/shellcheck/wiki/SC1117
+# SC2029 - Note that, unescaped, this expands on the client side - https://github.com/koalaman/shellcheck/wiki/SC2029
+# SC2030 - Modification of var is local (to subshell caused by pipeline). - https://github.com/koalaman/shellcheck/wiki/SC2030
+# SC2031 - var was modified in a subshell. That change might be lost. - https://github.com/koalaman/shellcheck/wiki/SC2031
 # SC2034 - VAR appears unused - https://github.com/koalaman/shellcheck/wiki/SC2034
-#        - used for declaring desc and deprecated function variables
+# SC2046 - Quote this to prevent word splitting - https://github.com/koalaman/shellcheck/wiki/SC2046
 # SC2064 - Use single quotes, otherwise this expands now rather than when signalled. - https://github.com/koalaman/shellcheck/wiki/SC2064
-#        - used for traps
+# SC2068 - Double quote array expansions to avoid re-splitting elements - https://github.com/koalaman/shellcheck/wiki/SC2068
+# SC2086 - Double quote to prevent globbing and word splitting - https://github.com/koalaman/shellcheck/wiki/SC2086
+# SC2119 - Use 'function "$@"' if function's $1 should mean script's $1 - https://github.com/koalaman/shellcheck/wiki/SC2119
+# SC2120 - Function references arguments, but none are ever passed - https://github.com/koalaman/shellcheck/wiki/SC2120
+# SC2128 - Expanding an array without an index only gives the first element - https://github.com/koalaman/shellcheck/wiki/SC2128
+# SC2148 - Tips depend on target shell and yours is unknown. Add a shebang - https://github.com/koalaman/shellcheck/wiki/SC2148
+# SC2153 - Possible misspelling: DOKKU_ROOT may not be assigned, but DOKKU_PORT is - https://github.com/koalaman/shellcheck/wiki/SC2153
+# SC2154 - Var is referenced but not assigned - https://github.com/koalaman/shellcheck/wiki/SC2154
 # SC2155 - Declare and assign separately to avoid masking return values - https://github.com/koalaman/shellcheck/wiki/SC2155
-#        - used throughout the codebase
-disable=SC1091,SC2034,SC2064,SC2155
+# SC2162 - read without -r will mangle backslashes - https://github.com/koalaman/shellcheck/wiki/SC2162
+# SC2174 - When used with -p, -m only applies to the deepest directory - https://github.com/koalaman/shellcheck/wiki/SC2174
+# SC2179 - Use array+=("item") to append items to an array - https://github.com/koalaman/shellcheck/wiki/SC2179
+# SC2191 - The = here is literal. To assign by index, use ( [index]=value ) with no spaces. To keep as literal, quote it - https://github.com/koalaman/shellcheck/wiki/SC2191
+# SC2199 - Arrays implicitly concatenate in [[ ]]. Use a loop (or explicit * instead of @) - https://github.com/koalaman/shellcheck/wiki/SC2199
+# SC2207 - Prefer mapfile or read -a to split command output (or quote to avoid splitting) - https://github.com/koalaman/shellcheck/wiki/SC2207
+# SC2219 - Instead of 'let expr', prefer (( expr ))  - https://github.com/koalaman/shellcheck/wiki/SC2219
+# SC2220 - Invalid flags are not handled. Add a *) case - https://github.com/koalaman/shellcheck/wiki/SC2220
+# SC2231 - Quote expansions in this for loop glob to prevent wordsplitting, e.g. "$dir"/*.txt  - https://github.com/koalaman/shellcheck/wiki/SC2231
+# SC2235 - Use { ..; } instead of (..) to avoid subshell overhead - https://github.com/koalaman/shellcheck/wiki/SC2235
+# SC2267 - GNU xargs -i is deprecated in favor of -I{} - https://github.com/koalaman/shellcheck/wiki/SC2267
+# SC2295 - Expansions inside ${..} need to be quoted separately, otherwise they match as patterns - https://github.com/koalaman/shellcheck/wiki/SC2295
+disable=SC1001,SC1003,SC1090,SC1091,SC1117,SC2029,SC2030,SC2031,SC2034,SC2046,SC2064,SC2068,SC2086,SC2119,SC2120,SC2128,SC2148,SC2153,SC2154,SC2155,SC2162,SC2174,SC2179,SC2191,SC2199,SC2207,SC2219,SC2220,SC2231,SC2235,SC2267,SC2295

.stickler.yml

@@ -1,13 +0,0 @@
----
-linters:
-  shellcheck:
-    shell: bash
-    exclude: SC2034,SC1090,SC2191
-  golint:
-
-files:
-  ignore:
-    - 'debian/*'
-    - 'docs/*'
-    - 'tests/*'
-    - '*/vendor/*'

CONTRIBUTING.md

@@ -19,11 +19,11 @@ a chance of keeping on top of things.
 - [Reporting Security Issues](#reporting-security-issues)
 - [Reporting Issues](#reporting-other-issues)
 - [Contributing](#contributing)
-  - [Making Changes](#making-changes)
-  - [Which branch to base the work](#which-branch-to-base-the-work)
-  - [Submitting Changes](#submitting-changes)
-  - [When will my change be merged?](#when-will-my-change-be-merged)
-  - [Running tests locally](#running-tests-locally)
+    - [Making Changes](#making-changes)
+    - [Which branch to base the work](#which-branch-to-base-the-work)
+    - [Submitting Changes](#submitting-changes)
+    - [When will my change be merged?](#when-will-my-change-be-merged)
+    - [Running tests locally](#running-tests-locally)
 - [Additional Resources](#additional-resources)
 
 ## Reporting security issues
@@ -65,24 +65,24 @@ need to do
 
 - Make sure you have a [GitHub account](https://github.com/signup/free).
 - Submit an [issue](https://github.com/dokku/dokku/issues), assuming one does not already exist.
-  - Clearly describe the issue including steps to reproduce when it is a bug.
-  - Make sure you fill in the earliest version that you know has the issue.
+    - Clearly describe the issue including steps to reproduce when it is a bug.
+    - Make sure you fill in the earliest version that you know has the issue.
 - Fork the repository on GitHub.
 
 ### Making Changes
 
 - Create a topic branch from where you want to base your work.
-  - This is usually the master branch.
-  - Only target an existing branch if you are certain your fix must be on that
-    branch.
-  - To quickly create a topic branch based on master; `git checkout -b my_contribution origin/master`.
-    It is best to avoid working directly on the `master` branch. Doing so will
+    - This is usually the master branch.
+    - Only target an existing branch if you are certain your fix must be on that
+      branch.
+    - To quickly create a topic branch based on master; `git checkout -b my_contribution origin/master`.
+      It is best to avoid working directly on the `master` branch. Doing so will
     help avoid conflicts if you pull in updates from origin.
 - Make commits of logical units. Implementing a new function and calling it in
   another file constitute a single logical unit of work.
-  - Before you make a pull request, squash your commits into logical units of work
-    using `git rebase -i` and `git push -f`.
-  - A majority of submissions should have a single commit, so if in doubt,
+    - Before you make a pull request, squash your commits into logical units of work
+      using `git rebase -i` and `git push -f`.
+    - A majority of submissions should have a single commit, so if in doubt,
     squash your commits down to one commit.
 - Check for unnecessary whitespace with `git diff --check` before committing.
 - Use descriptive commit messages and reference the #issue number.
@@ -92,7 +92,7 @@ need to do
 - Your work should apply the [Dokku coding standards](https://github.com/progrium/bashstyle)
 - Pull requests must be cleanly rebased on top of master without multiple branches
   mixed into the PR.
-  - **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your
+    - **Git tip**: If your PR no longer merges cleanly, use `rebase master` in your
     feature branch to update your pull request rather than `merge master`.
 
 ### Which branch to base the work

ISSUE_TEMPLATE.md

@@ -39,10 +39,10 @@
 - The nginx configuration (if applicable) via `dokku nginx:show-config APP_NAME`
 - Link to the exact repository being deployed (if possible/applicable):
 - If a deploy is failing or behaving unexpectedly:
-  - Application name
-  - The type of application being deployed (node, php, python, ruby, etc.)
-  - If using buildpacks, which custom buildpacks are in use
-  - If using a `Dockerfile`, the contents of that file
-  - If it exists, the contents of your `Procfile`.
+    - Application name
+    - The type of application being deployed (node, php, python, ruby, etc.)
+    - If using buildpacks, which custom buildpacks are in use
+    - If using a `Dockerfile`, the contents of that file
+    - If it exists, the contents of your `Procfile`.
 - Output of failing Dokku commands after running `dokku trace:on`
   (BEWARE: `trace:on` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXX):

Makefile

@@ -2,15 +2,17 @@ DOKKU_VERSION ?= master
 
 TARGETARCH ?= amd64
 
-DOCKER_IMAGE_LABELER_VERSION ?= 0.5.0
-HEROKUISH_VERSION ?= 0.5.38
-LAMBDA_BUILDER_VERSION ?= 0.4.0
-NETRC_VERSION ?= 0.6.0
+DOCKER_IMAGE_LABELER_VERSION ?= 0.6.1
+DOCKER_CONTAINER_HEALTHCHECKER_VERSION ?= 0.6.4
+HEROKUISH_VERSION ?= 0.7.1
+LAMBDA_BUILDER_VERSION ?= 0.5.0
+NETRC_VERSION ?= 0.7.1
 PLUGN_VERSION ?= 0.12.0
-PROCFILE_VERSION ?= 0.15.0
-SIGIL_VERSION ?= 0.9.0
-SSHCOMMAND_VERSION ?= 0.16.0
+PROCFILE_VERSION ?= 0.16.0
+SIGIL_VERSION ?= 0.10.1
+SSHCOMMAND_VERSION ?= 0.17.1
 DOCKER_IMAGE_LABELER_URL ?= https://github.com/dokku/docker-image-labeler/releases/download/v${DOCKER_IMAGE_LABELER_VERSION}/docker-image-labeler_${DOCKER_IMAGE_LABELER_VERSION}_linux_${TARGETARCH}.tgz
+DOCKER_CONTAINER_HEALTHCHECKER_URL ?= https://github.com/dokku/docker-container-healthchecker/releases/download/v${DOCKER_CONTAINER_HEALTHCHECKER_VERSION}/docker-container-healthchecker_${DOCKER_CONTAINER_HEALTHCHECKER_VERSION}_linux_${TARGETARCH}.tgz
 LAMBDA_BUILDER_URL ?= https://github.com/dokku/lambda-builder/releases/download/v${LAMBDA_BUILDER_VERSION}/lambda-builder_${LAMBDA_BUILDER_VERSION}_linux_${TARGETARCH}.tgz
 NETRC_URL ?= https://github.com/dokku/netrc/releases/download/v${NETRC_VERSION}/netrc_${NETRC_VERSION}_linux_${TARGETARCH}.tgz
 PLUGN_URL ?= https://github.com/dokku/plugn/releases/download/v${PLUGN_VERSION}/plugn_${PLUGN_VERSION}_linux_${TARGETARCH}.tgz
@@ -18,7 +20,7 @@ PROCFILE_UTIL_URL ?= https://github.com/josegonzalez/go-procfile-util/releases/d
 SIGIL_URL ?= https://github.com/gliderlabs/sigil/releases/download/v${SIGIL_VERSION}/gliderlabs-sigil_${SIGIL_VERSION}_linux_${TARGETARCH}.tgz
 SSHCOMMAND_URL ?= https://github.com/dokku/sshcommand/releases/download/v${SSHCOMMAND_VERSION}/sshcommand_${SSHCOMMAND_VERSION}_linux_x86_64.tgz
 STACK_URL ?= https://github.com/gliderlabs/herokuish.git
-PREBUILT_STACK_URL ?= gliderlabs/herokuish:latest-20
+PREBUILT_STACK_URL ?= gliderlabs/herokuish:latest-22
 DOKKU_LIB_ROOT ?= /var/lib/dokku
 PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/plugins
 CORE_PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/core-plugins
@@ -135,7 +137,7 @@ plugin-dependencies: plugn procfile-util
 plugins: plugn procfile-util docker
 	sudo -E dokku plugin:install --core
 
-dependencies: apt-update docker-image-labeler lambda-builder netrc sshcommand plugn procfile-util docker help2man man-db sigil dos2unix jq parallel
+dependencies: apt-update docker-image-labeler docker-container-healthchecker lambda-builder netrc sshcommand plugn procfile-util docker help2man man-db sigil dos2unix jq parallel
 	$(MAKE) -e stack
 
 apt-update:
@@ -161,6 +163,11 @@ docker-image-labeler:
 	tar xzf /tmp/docker-image-labeler_latest.tgz -C /usr/local/bin
 	mv /usr/local/bin/docker-image-labeler-${TARGETARCH} /usr/local/bin/docker-image-labeler
 
+docker-container-healthchecker:
+	wget -qO /tmp/docker-container-healthchecker_latest.tgz ${DOCKER_CONTAINER_HEALTHCHECKER_URL}
+	tar xzf /tmp/docker-container-healthchecker_latest.tgz -C /usr/local/bin
+	mv /usr/local/bin/docker-container-healthchecker-${TARGETARCH} /usr/local/bin/docker-container-healthchecker
+
 lambda-builder:
 	wget -qO /tmp/lambda-builder_latest.tgz ${LAMBDA_BUILDER_URL}
 	tar xzf /tmp/lambda-builder_latest.tgz -C /usr/local/bin

README.md

@@ -86,8 +86,8 @@ Otherwise, you will need to import the keypair manually after installation using
 To install the latest stable release, run the following commands as a user who has access to `sudo`:
 
 ```shell
-wget https://dokku.com/install/v0.30.2/bootstrap.sh
-sudo DOKKU_TAG=v0.30.2 bash bootstrap.sh
+wget -NP . https://dokku.com/install/v0.31.2/bootstrap.sh
+sudo DOKKU_TAG=v0.31.2 bash bootstrap.sh
 ```
 
 You can then proceed to configure your server domain (via `dokku domains:set-global`) and user access (via `dokku ssh-keys:add`) to complete the installation.

bootstrap.sh

@@ -12,7 +12,7 @@ set -eo pipefail
 # That's good because it prevents our output overlapping with wget's.
 # It also means that we can't run a partially downloaded script.
 
-SUPPORTED_VERSIONS="Debian [10, 11], Ubuntu [18.04, 20.04, 22.04]"
+SUPPORTED_VERSIONS="Debian [10, 11, 12], Ubuntu [18.04, 20.04, 22.04]"
 
 log-fail() {
   declare desc="log fail formatter"
@@ -28,7 +28,7 @@ ensure-environment() {
     echo "Preparing to install $DOKKU_TAG from $DOKKU_REPO..."
   fi
 
-  hostname -f >/dev/null 2>&1 || {
+  hostname -f &>/dev/null || {
     log-fail "This installation script requires that you have a hostname set for the instance. Please set a hostname for 127.0.0.1 in your /etc/hosts"
   }
 
@@ -160,7 +160,7 @@ install-dokku-from-deb-package() {
   local NO_INSTALL_RECOMMENDS=${DOKKU_NO_INSTALL_RECOMMENDS:=""}
   local OS_ID
 
-  if ! in-array "$DOKKU_DISTRO_VERSION" "18.04" "20.04" "22.04" "10" "11"; then
+  if ! in-array "$DOKKU_DISTRO_VERSION" "18.04" "20.04" "22.04" "10" "11" "12"; then
     log-fail "Unsupported Linux distribution. Only the following versions are supported: $SUPPORTED_VERSIONS"
   fi
 
@@ -197,7 +197,7 @@ install-dokku-from-deb-package() {
       OS_ID="bionic"
     fi
   elif [[ "$DOKKU_DISTRO" == "debian" ]]; then
-    OS_IDS=("stretch" "buster" "bullseye")
+    OS_IDS=("stretch" "buster" "bullseye" "bookworm")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
       OS_ID="bullseye"
     fi
@@ -220,19 +220,15 @@ install-dokku-from-deb-package() {
   [[ -n $DOKKU_NGINX_ENABLE ]] && echo "dokku dokku/nginx_enable string $DOKKU_NGINX_ENABLE" | sudo debconf-set-selections
 
   if [[ -n $DOKKU_CHECKOUT ]]; then
-    # shellcheck disable=SC2086
     apt-get -qq -y $NO_INSTALL_RECOMMENDS install "dokku=$DOKKU_CHECKOUT"
   else
-    # shellcheck disable=SC2086
     apt-get -qq -y $NO_INSTALL_RECOMMENDS install dokku
   fi
 }
 
 main() {
   export DOKKU_DISTRO DOKKU_DISTRO_VERSION
-  # shellcheck disable=SC1091
   DOKKU_DISTRO=$(. /etc/os-release && echo "$ID")
-  # shellcheck disable=SC1091
   DOKKU_DISTRO_VERSION=$(. /etc/os-release && echo "$VERSION_ID")
 
   export DEBIAN_FRONTEND=noninteractive

contrib/dokku-docker-bin.sh

@@ -4,5 +4,4 @@ set -eo pipefail
 DOKKU_DOCKER_CONTAINER_NAME=${DOKKU_DOCKER_CONTAINER_NAME:=dokku}
 
 # TODO: handle cases where we need a tty
-# shellcheck disable=SC2086
 docker exec $DOKKU_DOCKER_ENV -i "$DOKKU_DOCKER_CONTAINER_NAME" dokku "$@"

contrib/dokku_client.sh

@@ -49,7 +49,7 @@ fn-dokku-host() {
   declare DOKKU_GIT_REMOTE="$1" DOKKU_HOST="$2"
 
   if [[ -z "$DOKKU_HOST" ]]; then
-    if [[ -d .git ]] || git rev-parse --git-dir >/dev/null 2>&1; then
+    if [[ -d .git ]] || git rev-parse --git-dir &>/dev/null; then
       DOKKU_HOST=$(git remote -v 2>/dev/null | grep -Ei "^${DOKKU_GIT_REMOTE}\s" | head -n 1 | cut -f1 -d' ' | cut -f2 -d '@' | cut -f1 -d':' 2>/dev/null || true)
     fi
   fi
@@ -109,7 +109,7 @@ main() {
   fi
 
   if [[ -z "$APP" ]]; then
-    if [[ -d .git ]] || git rev-parse --git-dir >/dev/null 2>&1; then
+    if [[ -d .git ]] || git rev-parse --git-dir &>/dev/null; then
       set +e
       APP=$(git remote -v 2>/dev/null | grep -Ei "^${DOKKU_GIT_REMOTE}\s" | grep -Ei "dokku@$DOKKU_REMOTE_HOST" | head -n 1 | cut -f2 -d'@' | cut -f1 -d' ' | cut -f2 -d':' 2>/dev/null)
       set -e
@@ -190,7 +190,6 @@ main() {
   [[ -n "$APP_ARG" ]] && [[ "$APP_ARG" == "--global" ]] && unset APP
   [[ -n "$@" ]] && [[ -n "$APP" ]] && app_arg="--app $APP"
   # echo "ssh -o LogLevel=QUIET -p $DOKKU_PORT -t dokku@$DOKKU_REMOTE_HOST -- $app_arg $@"
-  # shellcheck disable=SC2068,SC2086
   ssh -o LogLevel=QUIET -p $DOKKU_PORT -t dokku@$DOKKU_REMOTE_HOST -- $app_arg $@ || {
     ssh_exit_code="$?"
     echo " !     Failed to execute dokku command over ssh: exit code $?" 1>&2

contrib/images/digitalocean/in_parts/012-dokku-packages

@@ -33,7 +33,8 @@ pkgs=(apache2-utils
   debconf
 )
 
-dokku_pkgs=(docker-image-labeler
+dokku_pkgs=(docker-container-healthchecker
+  docker-image-labeler
   gliderlabs-sigil
   lambda-builder
   netrc

contrib/images/digitalocean/in_parts/100-image-check

@@ -31,7 +31,6 @@ cmdExists() {
 function getDistro {
   if [ -f /etc/os-release ]; then
     # freedesktop.org and systemd
-    # shellcheck disable=SC1091
     . /etc/os-release
     OS=$NAME
     VER=$VERSION_ID
@@ -41,7 +40,6 @@ function getDistro {
     VER=$(lsb_release -sr)
   elif [ -f /etc/lsb-release ]; then
     # For some versions of Debian/Ubuntu without lsb_release command
-    # shellcheck disable=SC1091
     . /etc/lsb-release
     OS=$DISTRIB_ID
     VER=$DISTRIB_RELEASE
@@ -255,11 +253,9 @@ function checkUsers {
         if [[ "${u[0]}" == "${user}" ]]; then
           if [[ ${u[1]} == "!" ]] || [[ ${u[1]} == "!!" ]] || [[ ${u[1]} == "*" ]]; then
             echo -en "\e[32m[PASS]\e[0m User ${user} has no password set.\n"
-            # shellcheck disable=SC2030
             ((PASS++))
           else
             echo -en "\e[41m[FAIL]\e[0m User ${user} has a password set on their account. Only system users are allowed on the image.\n"
-            # shellcheck disable=SC2030
             ((FAIL++))
             STATUS=2
           fi
@@ -292,7 +288,6 @@ function checkUsers {
                   STATUS=2
                 else
                   echo -en "\e[93m[WARN]\e[0m User \e[1m${user}\e[0m has empty private key file in \e[93m${key}\e[0m\n"
-                  # shellcheck disable=SC2030
                   ((WARN++))
                   if [[ $STATUS != 2 ]]; then
                     STATUS=1
@@ -352,11 +347,9 @@ function checkFirewall {
     ufwa=$(ufw status | head -1 | sed -e "s/^Status:\ //")
     if [[ $ufwa == "active" ]]; then
       FW_VER="\e[32m[PASS]\e[0m Firewall service (${fw}) is active\n"
-      # shellcheck disable=SC2031
       ((PASS++))
     else
       FW_VER="\e[93m[WARN]\e[0m No firewall is configured. Ensure ${fw} is installed and configured\n"
-      # shellcheck disable=SC2031
       ((WARN++))
     fi
   elif [[ $OS == "CentOS Linux" ]] || [[ $OS == "CentOS Stream" ]] || [[ $OS == "Rocky Linux" ]] || [[ $OS == "AlmaLinux" ]]; then
@@ -451,7 +444,6 @@ function checkUpdates {
       sleep 2
       apt-get --just-print upgrade | grep -i security | awk '{print $2}' | awk '!seen[$0]++'
       echo -en
-      # shellcheck disable=SC2031
       ((FAIL++))
       STATUS=2
     else

contrib/release-dokku

@@ -9,19 +9,16 @@ readonly DOKKU_GIT_REV="$(git rev-parse HEAD)"
 trap "rm -rf '$TMP_WORK_DIR' >/dev/null" RETURN INT TERM EXIT
 
 log-info() {
-  # shellcheck disable=SC2034
   declare desc="Log info formatter"
   echo "$*"
 }
 
 log-error() {
-  # shellcheck disable=SC2034
   declare desc="Log error formatter"
   echo "!   $*" 1>&2
 }
 
 log-fail() {
-  # shellcheck disable=SC2034
   declare desc="Log fail formatter"
   log-error "$*"
   exit 1
@@ -158,7 +155,7 @@ fn-publish-package() {
     done
 
     DIST=debian
-    OS_IDS=("buster" "bullseye")
+    OS_IDS=("buster" "bullseye" "bookworm")
     for OS_ID in "${OS_IDS[@]}"; do
       log-info "(release-dokku) pushing ${RELEASE_TYPE} to packagecloud.com/${REPOSITORY}/${DIST}"
       package_cloud push "${REPOSITORY}/${DIST}/${OS_ID}" "$PACKAGE_NAME"
@@ -186,8 +183,12 @@ fn-replace-version() {
 
 fn-repo-merged-requests() {
   declare desc="Retrieves all pull request ids since a given release of dokku"
-  declare TAG="$1"
-  git log "v${TAG}..HEAD" --oneline | grep "Merge pull request" | cut -d' ' -f 5 | cut -d '#' -f2
+  declare TAG="$1" IS_PATCH="$2"
+  if [[ "$IS_PATCH" == "true" ]]; then
+    git log "v${TAG}..HEAD" --oneline | grep "Merge pull request" | cut -d' ' -f 5 | cut -d '#' -f2
+  else
+    curl -u "$RELEASE_GITHUB_USERNAME:$RELEASE_GITHUB_API_TOKEN" --fail -sS "https://api.github.com/search/issues?q=repo:dokku/dokku+milestone:v${NEXT_VERSION}+is:pr&per_page=100" | jq '.items[].number'
+  fi
 }
 
 fn-repo-push-tags() {
@@ -204,7 +205,7 @@ fn-repo-push-tags() {
 
 fn-repo-update() {
   declare desc="Updates files within the repository for a given release"
-  declare IS_RELEASE="$1" CURRENT_VERSION="$2" NEXT_VERSION="$3"
+  declare IS_RELEASE="$1" CURRENT_VERSION="$2" NEXT_VERSION="$3" IS_PATCH="$4"
 
   log-info "(release-dokku) Replacing ${CURRENT_VERSION} with ${NEXT_VERSION}"
   for f in plugins/*/plugin.toml; do
@@ -241,13 +242,13 @@ fn-repo-update() {
   fi
 
   log-info "(release-dokku) Adding HISTORY.md, committing and tagging"
-  fn-repo-update-history-and-commit "$CURRENT_VERSION" "$NEXT_VERSION"
+  fn-repo-update-history-and-commit "$CURRENT_VERSION" "$NEXT_VERSION" "$IS_PATCH"
   git tag "v${NEXT_VERSION}"
 }
 
 fn-repo-update-history-and-commit() {
   declare desc="Updates the history file and commits the changes"
-  declare CURRENT_VERSION="$1" NEXT_VERSION="$2"
+  declare CURRENT_VERSION="$1" NEXT_VERSION="$2" IS_PATCH="$3"
   local PULL_REQUEST_ID TITLE AUTHOR TYPE CHANGELOG_TEXT
   local COMMIT_MESSAGE HISTORY HISTORY_CONTENTS HISTORY_BUG HISTORY_DEPENDENCY HISTORY_DEPRECATION HISTORY_DOCUMENTATION HISTORY_ENHANCEMENT HISTORY_BC_BREAK HISTORY_REFACTOR HISTORY_REMOVAL HISTORY_OTHER HISTORY_TESTS ISSUE_FILE
 
@@ -255,7 +256,7 @@ fn-repo-update-history-and-commit() {
 
   mkdir -p /tmp/github-data
 
-  for PULL_REQUEST_ID in $(fn-repo-merged-requests "$CURRENT_VERSION"); do
+  for PULL_REQUEST_ID in $(fn-repo-merged-requests "$CURRENT_VERSION" "$IS_PATCH"); do
     ISSUE_FILE="/tmp/github-data/${PULL_REQUEST_ID}.json"
     if [[ ! -f "$ISSUE_FILE" ]]; then
       while true; do
@@ -305,7 +306,7 @@ fn-repo-update-history-and-commit() {
   HISTORY="${HISTORY}"$'\n\n'"## ${NEXT_VERSION}"
   HISTORY="${HISTORY}"$'\n\n'"Install/update via the bootstrap script:"
   HISTORY="${HISTORY}"$'\n\n'"\`\`\`shell"
-  HISTORY="${HISTORY}"$'\n'"wget https://dokku.com/install/v${NEXT_VERSION}/bootstrap.sh"
+  HISTORY="${HISTORY}"$'\n'"wget -NP . https://dokku.com/install/v${NEXT_VERSION}/bootstrap.sh"
   HISTORY="${HISTORY}"$'\n'"sudo DOKKU_TAG=v${NEXT_VERSION} bash bootstrap.sh"
   HISTORY="${HISTORY}"$'\n'"\`\`\`"
 
@@ -391,7 +392,7 @@ fn-build-docker-image() {
       --push \
       --tag "dokku/dokku:latest" \
       --tag "dokku/dokku:$VERSION" .
-  else
+  elif [[ "$SKIP_IMAGE_BUILD" != "true" ]]; then
     docker buildx build \
       --platform linux/arm,linux/arm64,linux/amd64 \
       --progress plain \
@@ -402,7 +403,7 @@ fn-build-docker-image() {
 
 main() {
   declare RELEASE="$1"
-  local CURRENT_VERSION NEXT_VERSION IS_RELEASE
+  local CURRENT_VERSION NEXT_VERSION IS_PATCH IS_RELEASE
   local VALID_RELEASE_LEVELS=("major" "minor" "patch" "betafish" "build")
 
   if [[ "$RELEASE" == '--trace' ]]; then
@@ -433,9 +434,14 @@ main() {
   NEXT_VERSION="$(fn-version-next "$CURRENT_VERSION" "$RELEASE")"
   IS_RELEASE="$(fn-is-release "$RELEASE")"
 
+  IS_PATCH="false"
+  if [[ "$RELEASE" == "patch" ]]; then
+    IS_PATCH="true"
+  fi
+
   echo "v${NEXT_VERSION}" >build/next-version
 
-  fn-repo-update "$IS_RELEASE" "$CURRENT_VERSION" "$NEXT_VERSION"
+  fn-repo-update "$IS_RELEASE" "$CURRENT_VERSION" "$NEXT_VERSION" "$IS_PATCH"
   fn-build-dokku "$IS_RELEASE" "$NEXT_VERSION" || log-fail "Error building package"
   fn-extract-package "$IS_RELEASE" "dokku_${NEXT_VERSION}_armhf.deb" || log-fail "Error extracting deb package"
   fn-extract-package "$IS_RELEASE" "dokku_${NEXT_VERSION}_arm64.deb" || log-fail "Error extracting deb package"

contrib/release-plugin

@@ -7,19 +7,16 @@ readonly TMP_WORK_DIR="$(mktemp -d "/tmp/dokku-plugin-release.XXXXXX")"
 trap "rm -rf '$TMP_WORK_DIR' >/dev/null" RETURN INT TERM EXIT
 
 log-info() {
-  # shellcheck disable=SC2034
   declare desc="Log info formatter"
   echo "$*"
 }
 
 log-error() {
-  # shellcheck disable=SC2034
   declare desc="Log error formatter"
   echo "!   $*" 1>&2
 }
 
 log-fail() {
-  # shellcheck disable=SC2034
   declare desc="Log fail formatter"
   log-error "$*"
   exit 1

contrib/write-mkdocs

@@ -1,13 +1,19 @@
 #!/usr/bin/env python
-from bs4 import BeautifulSoup
 import os
 import pathlib
 import shutil
 import sys
+from collections.abc import Callable
+
 import yaml
 
+from bs4 import BeautifulSoup
 
-def get_nav_from_selector(soup, selector, docs_dir):
+
+def get_nav_from_selector(soup: BeautifulSoup, selector: str, docs_dir: str):
+    """
+    Generates navigation from template file
+    """
     navigation = []
     header_name = ""
     for anchor in soup.select(selector):
@@ -49,44 +55,50 @@ def get_nav_from_selector(soup, selector, docs_dir):
                     children = os.listdir(docs_dir + "/" + child_dir)
                     children = [child_dir + c for c in children]
                     children.sort()
-                    children.insert(
-                        0, "getting-started/advanced-installation.md")
+                    children.insert(0, "getting-started/advanced-installation.md")
                     if os.path.exists(docs_dir + "/" + filename):
                         children.insert(0, filename)
                     else:
-                        children.insert(
-                            0, "getting-started/installation/index.md")
-                    nav[header_name].append({
-                        "Getting Started with Dokku": children,
-                    })
+                        children.insert(0, "getting-started/installation/index.md")
+                    nav[header_name].append(
+                        {
+                            "Getting Started with Dokku": children,
+                        }
+                    )
                     continue
-                elif filename == "getting-started/upgrading.md":
+
+                if filename == "getting-started/upgrading.md":
                     child_dir = "appendices/"
                     children = os.listdir(docs_dir + "/" + child_dir)
 
-                    children.sort(key=lambda x: list(
-                        map(int, x.split("-")[0].split('.'))),
-                        reverse=True)
+                    children.sort(
+                        key=lambda x: list(map(int, x.split("-")[0].split("."))),
+                        reverse=True,
+                    )
                     children = [child_dir + c for c in children]
                     if os.path.exists(docs_dir + "/" + filename):
                         children.insert(0, filename)
                     else:
-                        children.insert(
-                            0, "getting-started/upgrading/index.md")
-                    nav[header_name].append({
-                        "Upgrading": children,
-                    })
+                        children.insert(0, "getting-started/upgrading/index.md")
+                    nav[header_name].append(
+                        {
+                            "Upgrading": children,
+                        }
+                    )
                     continue
-                else:
-                    nav[header_name].append(filename)
+
+                nav[header_name].append(filename)
     return navigation
 
 
-def generate_nav(src, dest):
+def generate_nav(src: str, dest: str) -> None:
+    """
+    Writes out navigation information to the mkdocs yaml file
+    """
     navigation = []
     repo_dir = pathlib.Path(__file__).parent.parent.resolve()
     docs_dir = str(repo_dir) + "/docs"
-    with open(docs_dir + "/template.html") as response:
+    with open(docs_dir + "/template.html", encoding="utf-8") as response:
         soup = BeautifulSoup(response, "html.parser")
         selectors = [
             ".container .row .list-group a",
@@ -101,21 +113,26 @@ def generate_nav(src, dest):
             print("No navigation found")
             sys.exit(1)
 
-    with open(src) as f:
-        data = yaml.unsafe_load(f)
+    with open(src, encoding="utf-8") as handler:
+        data = yaml.unsafe_load(handler)
         data["nav"] = [
             {"Docs": navigation},
             {"Pro": "https://pro.dokku.com/docs/getting-started/"},
             {"Blog": "https://dokku.com/blog/"},
             {"Tutorials": "https://dokku.com/tutorials/"},
-            {"Purchase Dokku Pro": "https://dokku.dpdcart.com/cart/add?product_id=217344&method_id=236878"},
+            {
+                "Purchase Dokku Pro": "https://dokku.dpdcart.com/cart/add?product_id=217344&method_id=236878"
+            },
         ]
 
-    with open(dest, mode="wt", encoding="utf-8") as f:
-        yaml.dump(data, f)
+    with open(dest, mode="wt", encoding="utf-8") as handler:
+        yaml.dump(data, handler)
 
 
-def modify_content_noop(lines, _):
+def modify_content_noop(lines: list[str], _) -> tuple[list[str], bool]:
+    """
+    Simply returns the lines as is
+    """
     modified = False
     updated_lines = []
     for line in lines:
@@ -123,11 +140,14 @@ def modify_content_noop(lines, _):
     return updated_lines, modified
 
 
-def modify_content_links(lines, filename):
+def modify_content_links(lines: list[str], filename: str) -> tuple[list[str], bool]:
+    """
+    Modifies links to be relative instead of absolute
+    """
     filename = filename.replace("/usr/src/source/docs/", "")
     parts = filename.split("/")
     parts.pop()
-    replacement = "](" + '/'.join([".." for _ in parts]) + "/"
+    replacement = "](" + "/".join([".." for _ in parts]) + "/"
     modified = False
     updated_lines = []
     for line in lines:
@@ -139,7 +159,10 @@ def modify_content_links(lines, filename):
     return updated_lines, modified
 
 
-def modify_content_stripspace(lines, _):
+def modify_content_stripspace(lines: list[str], _) -> tuple[list[str], bool]:
+    """
+    Removes trailing whitespace from each line
+    """
     modified = False
     updated_lines = []
     for line in lines:
@@ -148,7 +171,10 @@ def modify_content_stripspace(lines, _):
     return updated_lines, modified
 
 
-def modify_content_inject_newlines(lines, _):
+def modify_content_inject_newlines(lines: list[str], _) -> tuple[list[str], bool]:
+    """
+    Ensures every line has a trailing newline character
+    """
     modified = False
     updated_lines = []
     for line in lines:
@@ -156,47 +182,117 @@ def modify_content_inject_newlines(lines, _):
     return updated_lines, modified
 
 
-def is_info(line):
+def is_github_new(line: str, next_line: str | None) -> bool:
+    """
+    Checks if a given line is a github "new as of" admonition
+    """
+    if not next_line:
+        return False
+
+    return line.startswith("> [!IMPORTANT]") and "new as of" in next_line.lower()
+
+
+def is_github_note(line: str) -> bool:
+    """
+    Checks if a given line is a github "note" admonition
+    """
+    return line.startswith("> [!NOTE]")
+
+
+def is_github_warning(line: str) -> bool:
+    """
+    Checks if a given line is a github "warning" admonition
+    """
+    return line.startswith("> [!WARNING]")
+
+
+def is_info(line: str) -> bool:
+    """
+    Checks if a given line is an "info" admonition
+    """
     return line.startswith("> ")
 
 
-def is_new(line):
+def is_new(line: str) -> bool:
+    """
+    Checks if a given line is a "new as of" admonition
+    """
     return line.startswith("> ") and "new as of" in line.lower()
 
 
-def is_note(line):
+def is_note(line: str) -> bool:
+    """
+    Checks if a given line is a "note" admonition
+    """
     return line.startswith("> Note:")
 
 
-def is_warning(line):
+def is_warning(line: str) -> bool:
+    """
+    Checks if a given line is a "warning" admonition
+    """
     return line.startswith("> Warning:")
 
 
-def modify_content_admonition(lines, _):
+def modify_content_admonition(lines: list[str], _) -> tuple[list[str], bool]:
+    """
+    Applies adminition info to each line in the output
+    """
     modified = False
     updated_lines = []
     admonition_lines = []
     is_admonition = False
-    for line in lines:
-        if is_info(line) or is_new(line) or is_note(line) or is_warning(line):
-            if is_new(line):
-                line = line.replace("> ", "!!! tip \"New\"\n\n    ")
-                line = line.replace("New as of", "Introduced in")
-                line = line.replace("new as of", "introduced in")
-            if is_note(line):
-                line = line.replace(
-                    "> Note: ", "!!! note \"Note\"\n\n    ")
-            elif is_warning(line):
-                line = line.replace(
-                    "> Warning: ", "!!! warning \"Warning\"\n\n    ")
-            elif is_info(line):
-                if not is_admonition:
-                    line = line.replace("> ", "!!! info \"Info\"\n\n    ")
-                elif line in [">", "> "]:
-                    line = ""
-                else:
-                    line = "    " + line.removeprefix("> ")
+    replace_new_in_next_line = False
+    for index, line in enumerate(lines):
+        next_line: str | None = None
+        if index + 1 < len(lines):
+            next_line = lines[index + 1]
 
+        if replace_new_in_next_line:
+            line = line.replace("New as of", "Introduced in")
+            line = line.replace("new as of", "introduced in")
+            replace_new_in_next_line = False
+
+        if is_github_new(line, next_line):
+            line = line.replace("> [!IMPORTANT]", '!!! tip "New"')
+            is_admonition = True
+            admonition_lines.append(line)
+            admonition_lines.append("")
+            replace_new_in_next_line = True
+        elif is_github_note(line):
+            line = line.replace("> [!NOTE]", '!!! note "Note"')
+            is_admonition = True
+            admonition_lines.append(line)
+            admonition_lines.append("")
+        elif is_github_warning(line):
+            line = line.replace("> [!WARNING]", '!!! warning "Warning"')
+            is_admonition = True
+            admonition_lines.append(line)
+            admonition_lines.append("")
+        elif is_new(line):
+            print("is_new")
+            line = line.replace("> ", '!!! tip "New"\n\n    ')
+            line = line.replace("New as of", "Introduced in")
+            line = line.replace("new as of", "introduced in")
+            is_admonition = True
+            admonition_lines.append(line)
+        elif is_note(line):
+            print("is_note")
+            line = line.replace("> Note: ", '!!! note "Note"\n\n    ')
+            is_admonition = True
+            admonition_lines.append(line)
+        elif is_warning(line):
+            print("is_warning")
+            line = line.replace("> Warning: ", '!!! warning "Warning"\n\n    ')
+            is_admonition = True
+            admonition_lines.append(line)
+        elif is_info(line):
+            if not is_admonition:
+                line = line.replace("> ", '!!! info "Info"\n\n    ')
+            elif line in [">", "> "]:
+                line = ""
+            else:
+                line = "    " + line.removeprefix("> ")
             is_admonition = True
             admonition_lines.append(line)
         elif is_admonition and line in [">", "> "]:
@@ -208,6 +304,7 @@ def modify_content_admonition(lines, _):
         elif line == "":
             is_admonition = False
             if len(admonition_lines) > 0:
+                modified = True
                 updated_lines.extend(admonition_lines)
                 admonition_lines = []
             updated_lines.append("")
@@ -216,11 +313,17 @@ def modify_content_admonition(lines, _):
     return updated_lines, modified
 
 
-def is_shell_codeblock_start(line):
+def is_shell_codeblock_start(line: str) -> bool:
+    """
+    Checks to see if a line starts a codeblock
+    """
     return line == "```shell"
 
 
-def modify_content_terminal_example(lines, _):
+def modify_content_terminal_example(lines: list[str], _) -> tuple[list[str], bool]:
+    """
+    Modifies content so that terminal output is shown appropriately
+    """
     modified = False
     updated_lines = []
     command_block = []
@@ -246,20 +349,20 @@ def modify_content_terminal_example(lines, _):
             if previous_block == "":
                 updated_lines.append(line)
                 continue
-            elif previous_block == "command_block":
+            if previous_block == "command_block":
                 example_block.append(line)
 
                 if in_example_block:
                     previous_block = ""
                     in_example_block = False
-                    updated_lines.append("=== \"Shell\"")
+                    updated_lines.append('=== "Shell"')
                     updated_lines.append("")
                     for command_line in command_block:
                         updated_lines.append(f"    {command_line}")
                     command_block = []
 
                     updated_lines.append("")
-                    updated_lines.append("=== \"Output\"")
+                    updated_lines.append('=== "Output"')
                     updated_lines.append("")
                     for example_line in example_block:
                         updated_lines.append(f"    {example_line}")
@@ -278,7 +381,7 @@ def modify_content_terminal_example(lines, _):
                     command_block = []
                     previous_block = ""
                 continue
-            elif next_line_must_be == "":
+            if next_line_must_be == "":
                 if line == "":
                     next_line_must_be = None
                     continue
@@ -292,6 +395,9 @@ def modify_content_terminal_example(lines, _):
 
 
 def update_markdown(src):
+    """
+    Updates all markdown files to be mkdocs compatible
+    """
     markdown_files = []
     allowed_extensions = [".md"]
     for subdir, _, files in os.walk(src):
@@ -301,7 +407,7 @@ def update_markdown(src):
             if ext in allowed_extensions:
                 markdown_files.append(file_path)
 
-    modifiers = [
+    modifiers: list[Callable[[list[str], str], tuple[list[str], bool]]] = [
         modify_content_noop,
         modify_content_links,
         modify_content_stripspace,
@@ -311,27 +417,32 @@ def update_markdown(src):
     ]
 
     for file in markdown_files:
-        modified = False
+        is_modified = False
         lines = []
-        with open(file, 'r') as f:
-            lines = f.readlines()
+        with open(file, "r", encoding="utf-8") as handler:
+            lines = handler.readlines()
             for modifier in modifiers:
-                lines, m = modifier(lines, file)
-                if m:
-                    modified = True
+                lines, modified = modifier(lines, file)
+                if modified:
+                    is_modified = True
 
-        if modified:
-            with open(file, 'w') as fp:
-                fp.writelines(lines)
+        if is_modified:
+            with open(file, "w", encoding="utf-8") as handler:
+                handler.writelines(lines)
 
 
 def main():
+    """
+    Main command that performs doc manipulation
+    """
     print("----> Copying mkdocs.yml")
     print("      Generating navigation")
     generate_nav("/usr/src/source/mkdocs.yml", "/usr/src/app/mkdocs.yml")
 
     print("----> Copying docs folder")
-    update_markdown("/usr/src/source/docs",)
+    update_markdown(
+        "/usr/src/source/docs",
+    )
 
     if os.path.exists("/usr/src/app/docs"):
         print("      Removing old docs folder")

debian/config

@@ -3,7 +3,6 @@ set -eo pipefail
 [[ $TRACE ]] && set -x
 
 if [[ -e /usr/share/debconf/confmodule ]]; then
-  # shellcheck disable=SC1091
   . /usr/share/debconf/confmodule
 fi
 

debian/control

@@ -1,11 +1,11 @@
 Package: dokku
-Version: 0.30.2
+Version: 0.31.2
 Section: web
 Priority: optional
 Architecture: amd64
-Depends: apache2-utils, locales, git, cpio, curl, man-db, netcat, sshcommand (>= 0.12.0), docker-engine-cs (>= 17.05.0) | docker-engine (>= 17.05.0) | docker-io (>= 17.05.0) | docker.io (>= 17.05.0) | docker-ce (>= 17.05.0) | docker-ee (>= 17.05.0) | moby-engine, docker-compose-plugin | moby-compose, docker-image-labeler (>= 0.2.2), lambda-builder, net-tools, netrc, software-properties-common, parallel, procfile-util (>= 0.11.0), python-software-properties | python3-software-properties, rsync, rsyslog, dos2unix, jq, unzip
-Recommends: herokuish (>= 0.3.4), bash-completion, dokku-update, dokku-event-listener
-Pre-Depends: gliderlabs-sigil, nginx (>= 1.8.0) | openresty, dnsutils, cgroupfs-mount | cgroup-lite, plugn (>= 0.3.0), sudo, python3, debconf
+Depends: apache2-utils, locales, git, cpio, curl, man-db, netcat, sshcommand (>= 0.17.1), docker-engine-cs (>= 17.05.0) | docker-engine (>= 17.05.0) | docker-io (>= 17.05.0) | docker.io (>= 17.05.0) | docker-ce (>= 17.05.0) | docker-ee (>= 17.05.0) | moby-engine, docker-compose-plugin | moby-compose, docker-container-healthchecker (>= 0.6.4), docker-image-labeler (>= 0.6.1), lambda-builder (>= 0.5.0), net-tools, netrc (>= 0.7.1), software-properties-common, parallel, procfile-util (>= 0.16.0), python-software-properties | python3-software-properties, rsync, rsyslog, dos2unix, jq, unzip
+Recommends: herokuish (>= 0.7.1), bash-completion, dokku-update, dokku-event-listener
+Pre-Depends: gliderlabs-sigil (>= 0.10.1), nginx (>= 1.8.0) | openresty, dnsutils, cgroupfs-mount | cgroup-lite, plugn (>= 0.3.0), sudo, python3, debconf
 Maintainer: Jose Diaz-Gonzalez <dokku@josediazgonzalez.com>
 Description: Docker-powered PaaS that helps build and manage the lifecycle of applications
  Dokku is an extensible, open source Platform as a Service

debian/postinst

@@ -3,12 +3,10 @@ set -eo pipefail
 [[ $TRACE ]] && set -x
 
 if [[ -e /usr/share/debconf/confmodule ]]; then
-  # shellcheck disable=SC1091
   . /usr/share/debconf/confmodule
 fi
 
 if [[ -r /etc/default/dokku ]]; then
-  # shellcheck disable=SC1091
   source /etc/default/dokku
 fi
 

debian/postrm

@@ -3,7 +3,6 @@ set -eo pipefail
 [[ $TRACE ]] && set -x
 
 if [[ -e /usr/share/debconf/confmodule ]]; then
-  # shellcheck disable=SC1091
   . /usr/share/debconf/confmodule
 fi
 

debian/preinst

@@ -3,7 +3,6 @@ set -eo pipefail
 [[ $TRACE ]] && set -x
 
 if [[ -e /usr/share/debconf/confmodule ]]; then
-  # shellcheck disable=SC1091
   . /usr/share/debconf/confmodule
 fi
 

docker/etc/my_init.d/10_dokku_init

@@ -56,11 +56,11 @@ main() {
 
   if [[ -f /mnt/dokku/plugin-list ]]; then
     while read line; do
-      local plugin_name="$(echo "$line" | awk '{print $2}')"
+      local plugin_name="$(echo "$line" | awk -F: '{print $1}')"
       if dokku plugin:installed "$plugin_name"; then
         log-warn "Skipping already installed plugin: $plugin_name"
       else
-        dokku plugin:install "$plugin_name" "$(echo "$line" | cut -d':' -f1)"
+        dokku plugin:install "$(echo "$line" | awk -F': ' '{print $2}')" --name "$plugin_name"
       fi
     done </mnt/dokku/plugin-list
   fi

docker/etc/sudoers.d/dokku-docker

@@ -1 +1 @@
-dokku    ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-image-labeler,/usr/bin/pack,/usr/bin/crontab
+dokku    ALL=NOPASSWD:SETENV:/usr/bin/docker,/usr/bin/docker-container-healthchecker,/usr/bin/docker-image-labeler,/usr/bin/pack,/usr/bin/crontab

docker/usr/local/bin/docker-container-healthchecker

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $TRACE ]] && set -x
+
+main() {
+  declare desc="re-runs docker-container-healthchecker commands as sudo"
+  local DOCKER_CONTAINER_HEALTHCHECKER_BIN=""
+  if [[ -x "/usr/bin/docker-container-healthchecker" ]]; then
+    DOCKER_CONTAINER_HEALTHCHECKER_BIN="/usr/bin/docker-container-healthchecker"
+  fi
+
+  if [[ -z "$DOCKER_CONTAINER_HEALTHCHECKER_BIN" ]]; then
+    echo "!   No docker-container-healthchecker binary found" 1>&2
+    exit 1
+  fi
+
+  sudo -E "$DOCKER_CONTAINER_HEALTHCHECKER_BIN" "$@"
+}
+
+main "$@"

docs.mk

@@ -1,6 +1,6 @@
 .PHONY: docs-build-image
 docs-build-image:
-	 docker build -f docs/_build/Dockerfile --progress plain -t app/mkdocs .
+	docker build -f docs/_build/Dockerfile --progress plain -t app/mkdocs .
 
 .PHONY: docs-build
 docs-build:

docs/_build/Dockerfile

@@ -1,10 +1,10 @@
-FROM python:3.11.2-alpine
+FROM python:3.11.4-alpine
 
 WORKDIR /usr/src/app
 
 COPY docs/_build/requirements.txt .
 
-RUN apk add --no-cache bash yaml && \
+RUN apk add --no-cache bash build-base yaml && \
   pip install --no-cache-dir -r requirements.txt
 
 COPY docs/_build/entrypoint /bin/entrypoint

docs/_build/entrypoint

@@ -23,17 +23,15 @@ main() {
   fi
 
   if [[ "$CMD" == "deps" ]]; then
-    pip freeze
-    return $?
+    exec pip freeze
   fi
 
   if [[ "$CMD" == "serve" ]]; then
     write-mkdocs
-    mkdocs serve -a 0.0.0.0:3487
-    return $?
+    exec mkdocs serve -a 0.0.0.0:3487
   fi
 
-  "$CMD" "${ARGS[@]}"
+  exec "$CMD" "${ARGS[@]}"
 }
 
 main "$@"

docs/_build/requirements.txt

@@ -1,23 +1,23 @@
-beautifulsoup4==4.12.0
-click==8.1.3
+beautifulsoup4==4.12.2
+click==8.1.7
 ghp-import==2.1.0
-importlib-metadata==6.1.0
+importlib-metadata==6.8.0
 Jinja2==3.1.2
 Markdown>=3.2.1,<3.5
-MarkupSafe==2.1.2
+MarkupSafe==2.1.3
 mergedeep==1.3.4
-mkdocs==1.4.2
+mkdocs==1.5.2
 mkdocs-exclude==1.0.2
-mkdocs-material==9.1.3
+mkdocs-material==9.2.3
 mkdocs-material-extensions==1.1.1
-packaging==23.0
-Pygments==2.14.0
-pymdown-extensions==9.10
-pyparsing==3.0.9
+packaging==23.1
+Pygments==2.16.1
+pymdown-extensions==10.1
+pyparsing==3.1.1
 python-dateutil==2.8.2
-PyYAML==6.0
+PyYAML==6.0.1
 pyyaml_env_tag==0.1
 six==1.16.0
-soupsieve==2.4
+soupsieve==2.4.1
 watchdog==3.0.0
-zipp==3.15.0
+zipp==3.16.2

docs/advanced-usage/backup-recovery.md

@@ -6,7 +6,8 @@ The best plan for disaster recovery is to always keep multiple (remote) copies o
 
 ## TLDR
 
-> Warning: This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis.
+> [!WARNING]
+> This method has many caveats. Please read this entire document before assuming these backups work as expected, and test your backups on a regular basis.
 
 ### Creating a backup
 

docs/advanced-usage/deployment-tasks.md

@@ -1,5 +1,6 @@
 # Deployment Tasks
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
 ## Usage
@@ -57,8 +58,10 @@ Please keep the above in mind when utilizing deployment tasks.
 
 When deploying a monorepo, it may be desirable to specify the specific path of the `app.json` file to use for a given app. This can be done via the `app-json:set` command. If a value is specified and that file does not exist within the repository, Dokku will continue the build process as if the repository has no `app.json` file.
 
+For deploys via the `git:from-image` and `git:load-image` commands, the `app.json` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `app.json` extracted directly from the source code. Both cases will respect the configured `appjson-path` property value.
+
 ```shell
-dokku app-json:set node-js-app appjson-path second-app.json
+dokku app-json:set node-js-app appjson-path .dokku/app.json
 ```
 
 The default value may be set by passing an empty value for the option:
@@ -81,6 +84,7 @@ dokku app-json:set --global appjson-path
 
 ### Displaying app-json reports for an app
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 You can get a report about the app's storage status using the `app-json:report` command:
@@ -137,9 +141,8 @@ Dokku provides limited support for the `app.json` manifest from Heroku (document
 - `scripts.dokku.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase.
 - `scripts.postdeploy`: This is run _after_ an app's containers are scheduled. Changes made to your image are _not_ committed at this phase.
 
-For buildpack-based deployments, the location of the `app.json` file should be at the root of your repository. Dockerfile-based app deploys should have the `app.json` in the configured `WORKDIR` directory; otherwise Dokku defaults to the buildpack app behavior of looking in `/app`.
-
-> Warning: Any failed `app.json` deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers.
+> [!WARNING]
+> Any failed `app.json` deployment task will fail the deploy. In the case of either phase, a failure will not affect any running containers.
 
 The following is an example `app.json` file. Please note that only the `scripts.dokku.predeploy` and `scripts.dokku.postdeploy` tasks are supported by Dokku at this time. All other fields will be ignored and can be omitted.
 
@@ -157,6 +160,7 @@ The following is an example `app.json` file. Please note that only the `scripts.
 
 #### Procfile Release command
 
+> [!IMPORTANT]
 > New as of 0.14.0
 
 The `Procfile` also supports a special `release` command which acts in a similar way to the [Heroku Release Phase](https://devcenter.heroku.com/articles/release-phase). This command is executed _after_ an app's docker image is built, but _before_ any containers are scheduled. This is also run _after_ any command executed by `scripts.dokku.predeploy`.
@@ -169,4 +173,5 @@ release: curl https://some.external.api.service.com/deployment?state=built
 
 Unlike the `scripts.dokku.predeploy` command, changes made during by the `release` command are _not_ persisted to disk.
 
-> Warning: scaling the release command up will likely result in unspecified issues within your deployment, and is highly discouraged.
+> [!WARNING]
+> scaling the release command up will likely result in unspecified issues within your deployment, and is highly discouraged.

docs/advanced-usage/docker-options.md

@@ -1,5 +1,6 @@
 # Docker Container Options
 
+> [!IMPORTANT]
 > New as of 0.3.17
 
 Pass [container options](https://docs.docker.com/engine/reference/run/) to the `docker run` command  during Dokku's `build`, `deploy` and `run` phases
@@ -27,7 +28,7 @@ Dokku deploys your application in multiple "phases" and the `docker-options` plu
 
 Manipulation of docker options will not restart running containers. This enables multiple options to be set/unset before final application. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` in order to take effect.
 
-More information on supported Docker options can be found here: https://docs.docker.com/engine/reference/commandline/run/.
+More information on supported Docker options can be found [here](https://docs.docker.com/engine/reference/commandline/run/).
 
 Container options configured via the `docker-options` plugin are not used to modify the process a container runs. Container options are the `[OPTIONS]` portion of the following, where `[CONTAINER_COMMAND]` and `[ARG]` are the process and the arguments passed to it that are launched in the created container: `docker run [OPTIONS] [CONTAINER_COMMAND] [ARG...]`. Please see the documentation for [customizing the run command](/docs/deployment/builders/dockerfiles.md#customizing-the-run-command) or use a [Procfile](/docs/deployment/builders/dockerfiles.md#procfiles-and-multiple-processes) to modify the command used by a Dockerfile-based container.
 
@@ -43,7 +44,8 @@ dokku docker-options:add node-js-app deploy "-v /var/log/node-js-app:/app/logs"
 dokku docker-options:add node-js-app run "-v /var/log/node-js-app:/app/logs"
 ```
 
-> Note: When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory.
+> [!NOTE]
+> When [mounting a host directory](https://docs.docker.com/engine/reference/run/#volume-shared-filesystems) in a Dokku app you should first create that directory as user `dokku` and then mount the directory under `/app` in the container using `docker-options` as above. Otherwise the app will lack write permission in the directory.
 
 ### Remove a Docker option
 
@@ -84,6 +86,7 @@ dokku docker-options:clear node-js-app build,run
 
 ### Displaying docker-options reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the app's docker-options status using the `docker-options:report` command:

docs/advanced-usage/event-logs.md

@@ -1,5 +1,6 @@
 # Dokku Event Logs
 
+> [!IMPORTANT]
 > New as of 0.3.21
 
 Docker provides an _events_ command to show system's real time events. Likewise, Dokku can record events as syslog entries and also provides a plugin to display the last ones.
@@ -75,4 +76,4 @@ pre-release-buildpack
 pre-release-dockerfile
 receive-app
 update
-```
+```

docs/advanced-usage/persistent-storage.md

@@ -1,5 +1,6 @@
 # Persistent Storage
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
 The preferred method to mount external containers to a Dokku managed container, is to use the Dokku storage plugin.
@@ -36,7 +37,6 @@ dokku storage:list node-js-app
 
 The output format can also be set to `json` for programmatic access:
 
-
 ```shell
 dokku storage:list node-js-app --format json
 ```
@@ -53,6 +53,7 @@ dokku storage:list node-js-app --format json
 
 ### Creating storage directories
 
+> [!IMPORTANT]
 > New as of 0.25.5
 
 A storage directory can be created with the `storage:ensure-directory` command. This command will create a subdirectory in the recommended `/var/lib/dokku/data/storage` path - created during Dokku installation - and prepare it for use with an app.
@@ -70,16 +71,17 @@ dokku storage:ensure-directory node-js-app
 By default, permissions are set for usage with Herokuish buildpacks. These permissions can be changed via the `--chown` option according to the following table:
 
 - `--chown herokuish` (default): Use `32767:32767` as the folder permissions.
-  - This is used for apps deployed with Buildpacks via Herokuish.
+    - This is used for apps deployed with Buildpacks via Herokuish.
 - `--chown heroku`: Use `1000:1000` as the folder permissions.
-  - This is used for apps deployed with Cloud Native Buildpacks using the `heroku/buildpacks` builder.
+    - This is used for apps deployed with Cloud Native Buildpacks using the `heroku/buildpacks` builder.
 - `--chown packeto`: Use `2000:2000` as the folder permissions.
-  - This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `packeto` builders.
+    - This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `packeto` builders.
 - `--chown false`: Skips the `chown` call.
 
 Users deploying via Dockerfile will want to specify `--chown false` and manually `chown` the created directory if the user and/or group id  of the runnning process in the deployed container do not correspond to any of the above options.
 
-> Warning: Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory.
+> [!WARNING]
+> Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory.
 
 ### Mounting storage into apps
 
@@ -125,6 +127,7 @@ dokku ps:restart app-name
 
 ### Displaying storage reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the app's storage status using the `storage:report` command:
@@ -195,14 +198,17 @@ dokku docker-options:add node-js-app build "-v /tmp/python-test:/opt/test"
 
 You cannot use mounted volumes during the build phase of a Dockerfile deploy. This is because Docker does not support volumes when executing `docker build`.
 
-> Warning: **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase.
+> [!WARNING]
+> **This can cause data loss** if you bind a mount under `/app` in buildpack apps as herokuish will attempt to remove the original app path during the build phase.
 
 ## App User and Persistent Storage file ownership (buildpack apps only)
 
+> [!IMPORTANT]
 > New as of 0.7.1
 
 By default, Dokku will execute your buildpack app processes as the `herokuishuser` user. You may override this by setting the `DOKKU_APP_USER` config variable.
 
-> NOTE: this user must exist in your herokuish image.
+> [!NOTE]
+> this user must exist in your herokuish image.
 
 Additionally, the default `docker-local` scheduler that comes with Dokku will ensure your storage mounts are owned by either `herokuishuser` or the overridden value you have set in `DOKKU_APP_USER`. See the [docker-local scheduler documentation](/docs/deployment/schedulers/docker-local.md#disabling-chown-of-persistent-storage) docs for more information.

docs/advanced-usage/plugin-management.md

@@ -1,17 +1,18 @@
 # Plugin Management
 
+> [!IMPORTANT]
 > New as of 0.4.0
 
 ```
 plugin:disable <name>                    # Disable an installed plugin (third-party only)
 plugin:enable <name>                     # Enable a previously disabled plugin
-plugin:install [--core|git-url [--committish tag|branch|commit|--name custom-plugin-name]]           # Optionally download git-url (with custom tag/committish) & run install trigger for active plugins (or only core ones)
+plugin:install [--core|--git-url] [--committish branch|commit|tag] [--name custom-plugin-name]           # Optionally download git-url (and pin to the specified branch/commit/tag) & run install trigger for active plugins (or only core ones)
 plugin:installed <name>                  # Checks if a plugin is installed
 plugin:install-dependencies [--core]     # Run install-dependencies trigger for active plugins (or only core ones)
 plugin:list                              # Print active plugins
 plugin:trigger <args...>.                # Trigger an arbitrary plugin hook
 plugin:uninstall <name>                  # Uninstall a plugin (third-party only)
-plugin:update [name [committish]]        # Optionally update named plugin from git (with custom tag/committish) & run update trigger for active plugins
+plugin:update [name [branch|commit|tag]] # Optionally update named plugin from git (and pin to the specified branch/commit/tag) & run update trigger for active plugins
 ```
 
 ```shell
@@ -35,38 +36,39 @@ dokku plugin:list
 
 ```
 plugn: dev
-  00_dokku-standard    0.30.2 enabled    dokku core standard plugin
-  20_events            0.30.2 enabled    dokku core events logging plugin
-  app-json             0.30.2 enabled    dokku core app-json plugin
-  apps                 0.30.2 enabled    dokku core apps plugin
-  build-env            0.30.2 enabled    dokku core build-env plugin
-  buildpacks           0.30.2 enabled    dokku core buildpacks plugin
-  certs                0.30.2 enabled    dokku core certificate management plugin
-  checks               0.30.2 enabled    dokku core checks plugin
-  common               0.30.2 enabled    dokku core common plugin
-  config               0.30.2 enabled    dokku core config plugin
-  docker-options       0.30.2 enabled    dokku core docker-options plugin
-  domains              0.30.2 enabled    dokku core domains plugin
-  enter                0.30.2 enabled    dokku core enter plugin
-  git                  0.30.2 enabled    dokku core git plugin
-  logs                 0.30.2 enabled    dokku core logs plugin
-  network              0.30.2 enabled    dokku core network plugin
-  nginx-vhosts         0.30.2 enabled    dokku core nginx-vhosts plugin
-  plugin               0.30.2 enabled    dokku core plugin plugin
-  proxy                0.30.2 enabled    dokku core proxy plugin
-  ps                   0.30.2 enabled    dokku core ps plugin
-  repo                 0.30.2 enabled    dokku core repo plugin
-  resource             0.30.2 enabled    dokku core resource plugin
-  scheduler-docker-local 0.30.2 enabled    dokku core scheduler-docker-local plugin
-  shell                0.30.2 enabled    dokku core shell plugin
-  ssh-keys             0.30.2 enabled    dokku core ssh-keys plugin
-  storage              0.30.2 enabled    dokku core storage plugin
-  tags                 0.30.2 enabled    dokku core tags plugin
-  tar                  0.30.2 enabled    dokku core tar plugin
-  trace                0.30.2 enabled    dokku core trace plugin
+  00_dokku-standard    0.31.2 enabled    dokku core standard plugin
+  20_events            0.31.2 enabled    dokku core events logging plugin
+  app-json             0.31.2 enabled    dokku core app-json plugin
+  apps                 0.31.2 enabled    dokku core apps plugin
+  build-env            0.31.2 enabled    dokku core build-env plugin
+  buildpacks           0.31.2 enabled    dokku core buildpacks plugin
+  certs                0.31.2 enabled    dokku core certificate management plugin
+  checks               0.31.2 enabled    dokku core checks plugin
+  common               0.31.2 enabled    dokku core common plugin
+  config               0.31.2 enabled    dokku core config plugin
+  docker-options       0.31.2 enabled    dokku core docker-options plugin
+  domains              0.31.2 enabled    dokku core domains plugin
+  enter                0.31.2 enabled    dokku core enter plugin
+  git                  0.31.2 enabled    dokku core git plugin
+  logs                 0.31.2 enabled    dokku core logs plugin
+  network              0.31.2 enabled    dokku core network plugin
+  nginx-vhosts         0.31.2 enabled    dokku core nginx-vhosts plugin
+  plugin               0.31.2 enabled    dokku core plugin plugin
+  proxy                0.31.2 enabled    dokku core proxy plugin
+  ps                   0.31.2 enabled    dokku core ps plugin
+  repo                 0.31.2 enabled    dokku core repo plugin
+  resource             0.31.2 enabled    dokku core resource plugin
+  scheduler-docker-local 0.31.2 enabled    dokku core scheduler-docker-local plugin
+  shell                0.31.2 enabled    dokku core shell plugin
+  ssh-keys             0.31.2 enabled    dokku core ssh-keys plugin
+  storage              0.31.2 enabled    dokku core storage plugin
+  tags                 0.31.2 enabled    dokku core tags plugin
+  tar                  0.31.2 enabled    dokku core tar plugin
+  trace                0.31.2 enabled    dokku core trace plugin
 ```
 
-> Warning: All plugin commands other than `plugin:list` and `plugin:help` require sudo access and must be run directly from the Dokku server.
+> [!WARNING]
+> All plugin commands other than `plugin:list` and `plugin:help` require sudo access and must be run directly from the Dokku server.
 
 ### Checking if a plugin is installed
 
@@ -78,7 +80,8 @@ dokku plugin:installed postgres
 
 ### Installing a plugin
 
-> Note: Plugins installed in this method within a [docker-based installation](/docs/getting-started/install/docker.md) of Dokku do not persist across installs. Please see the [plugin installation section](/docs/getting-started/install/docker.md#plugin-installation) of the docker-based installation docs for further details.
+> [!NOTE]
+> Plugins installed in this method within a [docker-based installation](/docs/getting-started/install/docker.md) of Dokku do not persist across installs. Please see the [plugin installation section](/docs/getting-started/install/docker.md#plugin-installation) of the docker-based installation docs for further details.
 
 Installing a plugin is easy as well using the `plugin:install` command. This command will also trigger the `install` pluginhook on all existing plugins.
 
@@ -165,6 +168,12 @@ An optional commit SHA-like object may be specified.
 dokku plugin:update postgres 2.0.0
 ```
 
+Any future invocation of `plugin:update` will respect the previously specified SHA-like object. To follow a particular branch again, specify that branch:
+
+```shell
+dokku plugin:update postgres main
+```
+
 ### Uninstalling a plugin
 
 Third party plugins can be uninstalled using the `plugin:uninstall` command:

docs/advanced-usage/registry-management.md

@@ -1,5 +1,6 @@
 # Registry Management
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 ```
@@ -69,22 +70,22 @@ dokku registry:set --global server
 The following are the values that should be used for common remote servers:
 
 - Amazon Elastic Container Registry:
-  - value: `$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/`
-  - notes: The `$AWS_ACCOUNT_ID` and `$AWS_REGION` should match the values for your account and region, respectively. Additionally, an IAM profile that allows `push` access to the repository specified by `image-repo` should be attached to your Dokku server.
+    - value: `$AWS_ACCOUNT_ID.dkr.ecr.$AWS_REGION.amazonaws.com/`
+    - notes: The `$AWS_ACCOUNT_ID` and `$AWS_REGION` should match the values for your account and region, respectively. Additionally, an IAM profile that allows `push` access to the repository specified by `image-repo` should be attached to your Dokku server.
 - Azure Container Registry:
-  - value `$REGISTRY_NAME.azurecr.io/`
-  - notes: The `$AKS_REGISTRY_NAME` should match the name of the registry created on your account.
+    - value `$REGISTRY_NAME.azurecr.io/`
+    - notes: The `$AKS_REGISTRY_NAME` should match the name of the registry created on your account.
 - Docker Hub:
-  - value: `docker.io/`
-  - notes: Requires owning the namespace used in the `image-repo` value.
+    - value: `docker.io/`
+    - notes: Requires owning the namespace used in the `image-repo` value.
 - Digitalocean:
-  - value: `registry.digitalocean.com/`
-  - notes: Requires setting the correct `image-repo` value for your registry.
+    - value: `registry.digitalocean.com/`
+    - notes: Requires setting the correct `image-repo` value for your registry.
 - Github Container Registry:
-  - value: `ghcr.io/`
-  - notes: Requires that the authenticated user has access to the namespace used in the `image-repo` value.
+    - value: `ghcr.io/`
+    - notes: Requires that the authenticated user has access to the namespace used in the `image-repo` value.
 - Quay.io:
-  - value: `quay.io/`
+    - value: `quay.io/`
 
 ### Specifying an image repository name
 

docs/advanced-usage/repository-management.md

@@ -1,5 +1,6 @@
 # Repository Management
 
+> [!IMPORTANT]
 > New as of 0.6.0
 
 ```

docs/advanced-usage/resource-management.md

@@ -1,5 +1,6 @@
 # Resource Management
 
+> [!IMPORTANT]
 > New as of 0.15.0
 
 ```
@@ -16,7 +17,8 @@ The resource plugin is meant to allow users to limit or reserve resources for a
 
 By default, Dokku allows unlimited resource access to apps deployed on a server. In some cases, it may be desirable to limit this on a per-app or per-process-type basis. The `resource` plugin allows management of both resource "limits" and resource "reservations", where each resource request type has specific meaning to the scheduler in use for a given app.
 
-> Warning: The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect.
+> [!WARNING]
+> The meaning of a values and it's units are specific to the scheduler in use for a given app. If a value is incorrect for a scheduler, this may result in containers failing to start correctly. If a scheduler does not support a given resource type combination, it will be ignored. All resource commands require an app rebuild or deploy in order to take effect.
 
 Valid resource options include:
 

docs/appendices/0.10.0-migration-guide.md

@@ -4,10 +4,10 @@
 
 By default, Dokku will ship a PCI Compliant nginx configuration. For developers whose users are on older browsers or mobile devices, you may need to ship a custom `nginx.conf.sigil` to enable ciphers for older browsers.
 
-See the [nginx customization](/docs/networking/proxies/nginx/#customizing-the-nginx-configuration) docs for more details.
+See the [nginx customization](/docs/networking/proxies/nginx.md#customizing-the-nginx-configuration) docs for more details.
 
 ## Nginx Error Pages
 
 We now ship with nicer error pages by default. You are free to customize your Dokku installation via a custom `nginx.conf.sigil` to change what error pages are displayed in different circumstances.
 
-See the [nginx customization](/docs/networking/proxies/nginx/#customizing-the-nginx-configuration) docs for more details.
+See the [nginx customization](/docs/networking/proxies/nginx.md#customizing-the-nginx-configuration) docs for more details.

docs/appendices/0.21.0-migration-guide.md

@@ -8,7 +8,7 @@ The `tls` name is no longer a reserved app name, and can be used by applications
 
 - `git#git_deploy_branch()` is deprecated in favor of `plugn trigger git-deploy-branch`.
 - The `config` command is deprecated in favor of `config:show`.
-  - Usage of this command in conjunction with either the `--export` or `--shell` flag is deprecated in favor of `config:export --format` with the correct format value (`exports` or `shell`, respectively).
+    - Usage of this command in conjunction with either the `--export` or `--shell` flag is deprecated in favor of `config:export --format` with the correct format value (`exports` or `shell`, respectively).
 - The `nginx:build-config` command is deprecated in favor of `proxy:build-config`.
 
 ## Removals

docs/appendices/0.25.0-migration-guide.md

@@ -19,7 +19,7 @@ Before upgrading, uninstall the registry plugin via `dokku plugin:uninstall regi
 - The `dokku run` command now always removes the ephemeral container on exit. Users that need a persistent container should instead specify a `console` process type in their `Procfile` specifying an available shell (usually either `bash` or `sh`) and scale that container appropriately.
 - The `pre-deploy` plugin trigger is now called internally by Dokku. Scheduler plugins should avoid calling this trigger, as any image changes introduced by subsequent trigger calls will be ignored.
 - The default image used for Herokuish Buildpack builds is now `gliderlabs/herokuish:latest-20`, and is based on both the `heroku-20` stack as well as Ubuntu 20.04. Users that wish to stick with the old, `heroku-18`/Ubuntu 18.04 builder may specify `gliderlabs/herokuish:latest-18` as their builder image. Please see the [herokuish buildpack deployment documentation](/docs/deployment/builders/herokuish-buildpacks.md#customizing-the-buildpack-stack-builder) for more information on how to specify a custom buildpack stack builder.
-  - This change does not impact any users of Cloud Native Buildpacks.
+    - This change does not impact any users of Cloud Native Buildpacks.
 - We fixed an issue that required extracting Procfiles at the beginning of a deploy. Due to this change, a `Dockerfile` app contains a `Procfile` that does not specify a `web` process will fail to start. Usage of a `Procfile` with _only_ a `release` command should be replaced with a `scripts.dokku.postdeploy` deployment task in the `app.json` file. The alternative is to define the `web` process in the `Procfile`. See the [deployment task documentation](/docs/advanced-usage/deployment-tasks.md) for more information.
 
 ### Deprecations

docs/appendices/0.26.0-migration-guide.md

@@ -9,4 +9,4 @@
 
 - The `scheduler` plugin now controls the scheduler in use for deploys. Apps will have their `DOKKU_SCHEDULER` environment variables migrated to the scheduler plugin, after which that value will be removed from said app. Please see the [scheduler documentation](/docs/deployment/schedulers/scheduler-management.md) for more information.
 - The `deploy-source` metadata from `apps:report` is now no longer computed on the fly, but hydrated at deploy time via the `deploy-source-set` trigger. This value may be empty until your next deploy.
-  - Additionally, the `deploy-source` trigger has now been removed.
+    - Additionally, the `deploy-source` trigger has now been removed.

docs/appendices/0.27.0-migration-guide.md

@@ -3,6 +3,7 @@
 ## Changes
 
 - Renaming an application will now only rename domains that are associated with global domains. As an example:
+
     ```shell
     dokku domains:set-global dokku.me
     dokku apps:create node-js-app

docs/appendices/0.30.0-migration-guide.md

@@ -13,7 +13,7 @@
 ## Removals
 
 - Support for [SPDY](https://en.wikipedia.org/wiki/SPDY) has been removed. No major browser supports it as of 2021. Custom `nginx.conf.sigil` templates referencing spdy-related variables will continue to build until the 1.0.0 release.
-- Support for the `DOKKU_SCALE` file - deprecated in 0.25.0 - has been removed in favor of the `formations` key in the `app.json` file. Please see the [process management documentation](/docs/processes/process-management.md#manually-managing-process-scaling) for more information on how to use the `formation` key of the `app.json` file.
+- Support for the `DOKKU_SCALE` file - deprecated in 0.25.0 - has been removed in favor of the `formation` key in the `app.json` file. Please see the [process management documentation](/docs/processes/process-management.md#manually-managing-process-scaling) for more information on how to use the `formation` key of the `app.json` file.
 - The deprecated `--detach` global flag for `dokku run` was removed. Please see the [one-off tasks documentation](/docs/processes/one-off-tasks.md#running-a-detached-container) for more information on running detached containers.
 - The following deprecated trigger have been removed in favor of the `post-release-builder` trigger. See the [plugin triggers documentation](https://dokku.com/docs/development/plugin-triggers/#post-release-builder) for more details.
     - `post-release-buildpack`

docs/appendices/0.31.0-migration-guide.md

@@ -0,0 +1,36 @@
+# 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 `vector` container integration now mounts config to `/etc/vector` instead of the path `/etc/vector/vector.json`, allowing users the ability to provide extra configuration for Vector Sinks. To take advantage of the new functionality, the vector container should be stopped (via `dokku logs:vector-stop`) and then started (via `dokku logs:vector-start`).
+- The `traefik` integration now mounts config to `/data` instead of the path `/acme.json`, fixing permissions issues under certain architectures. To take advantage of the new functionality, the traefik container should be stopped (via `dokku traefik:stop`) and then started (via `dokku traefik:start`).
+- Users no longer need to clear the `source-image` git property when transitioning from image-based deploys (`git:from-image` and `git:load-image`) to other deployment methods (git push, `git:from-archive`, `git:sync`).
+- For deploys via the `git:from-image` and `git:load-image` commands, the `CHECKS` file is now extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `CHECKS` extracted directly from the source code. The filename in both cases is `CHECKS` and cannot be modified.
+- Port mappings are now auto-detected during the build process. Users may override detected port mappings via the `ports` plugin. A default port mapping of `http:80:5000` will be used if none is otherwise specified.
+- Users building docker images that run Dokku will need to use a new sudoer wrapper for the `docker-container-healthchecker` binary to work correctly. A reference version has been placed in the `docker` skeleton directory. This should only impact platform developers, and users of our Docker image will already have the file available.
+- The default image used for Herokuish Buildpack builds is now `gliderlabs/herokuish:latest-22`, and is based on both the `heroku-22` stack as well as Ubuntu 22.04. Users that wish to stick with the old, `heroku-20`/Ubuntu 20.04 builder may specify `gliderlabs/herokuish:latest-20` as their builder image. Please see the [herokuish buildpack deployment documentation](/docs/deployment/builders/herokuish-buildpacks.md#customizing-the-buildpack-stack-builder) for more information on how to specify a custom buildpack stack builder.
+- The default image used for Cloud Native Buildpack builds is now `heroku/builder:22`, and is based on both the `heroku-22` stack as well as Ubuntu 22.04. Users that wish to stick with the old, `heroku-20`/Ubuntu 20.04 builder may specify `heroku/buildpacks:20` as their builder image. Please see the [herokuish buildpack deployment documentation](/docs/deployment/builders/herokuish-buildpacks.md#customizing-the-buildpack-stack-builder) for more information on how to specify a custom buildpack stack builder.
+
+## Deprecations
+
+- 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.
+- The `common#get_available_port()` function has been deprecated and will be removed in the next release. Users should avoid interacting with this function and instead use the `ports-get-available` plugin trigger for fetching an available port.
+- The `proxy-configure-ports` plugin trigger has been deprecated and will be removed in the next release. Users should instead trigger the `ports-configure` plugin trigger.
+- The `common#get_dockerfile_exposed_ports()` function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was in the `builder-dockerfile` plugin.
+- The `common#get_exposed_ports_from_image()` function is deprecated and will be removed in the next release. There is no replacement for this as it's only use in Dokku core was during the build process.
+- The environment variable `DOKKU_PROXY_PORT_MAP` has been migrated to the properties system. Direct changes to the value will be ignored, and users should interact with port maps via the `ports` plugin.
+- The `CHECKS` file is deprecated in favor of defining healthchecks in the `app.json` file. The [docker-container-healthchecker](https://github.com/dokku/docker-container-healthchecker) tool can be used to generate healthcheck entries in `app.json` format from existing `CHECKS` files. See the [zero-downtime deploy documentation](/docs/deployment/zero-downtime-deploys.md) for more information on how the new zero downtime check format works.
+- ARM support is now deprecated, and will be removed in the next minor release. ARM releases are not tested in CI and do not get testing locally. Users of ARM installations on platforms such as the Raspberry PI should consider migrating to ARM64. ARM64 will continue to be supported by Dokku, and there are no plans to remove support for ARM64.
+
+## Un-Deprecations
+
+- The bare `apps` and `config` cli aliases are no longer deprecated. This better follows Heroku's output and is more useful to users. The subcommands will be treated as the primary, documented versions, while the aliases are there for convenience.
+
+## Removals
+
+- The variable `RAW_TCP_PORTS` is no longer exposed for `nginx.conf.sigil` templating.
+- The environment variable `DOKKU_DOCKERFILE_PORTS` is no longer in use. Users wishing to change port mappings should instead use the `ports` plugin.
+- The `common#get_app_raw_tcp_ports()` function has been removed in the next release. Users should instead use the `ports-get` plugin trigger for fetching ports for an app.
+- The plugin trigger `network-compute-ports` has been removed. It's only use was in the `scheduler-docker-local` plugin, for exposing ports. It's functionality is now implemented via the `ports` plugin.
+- The plugin trigger `network-get-port` has been removed. It's only use was in the `scheduler-docker-local` plugin, for recording ports. It's functionality is now implemented via the `ports` plugin.

docs/appendices/0.5.0-migration-guide.md

@@ -3,23 +3,23 @@
 ## `nginx-vhosts` plugin
 
 - The nginx-vhosts template language is now [sigil](https://github.com/gliderlabs/sigil)
-  - No need to escape literal `$` characters (or other "bash-isms")
-  - Template variables are represented as {{ .VARIABLE_NAME }}
-  - A detailed list of template variables can be found [here](/docs/networking/proxies/nginx.md#available-template-variables)
+    - No need to escape literal `$` characters (or other "bash-isms")
+    - Template variables are represented as {{ .VARIABLE_NAME }}
+    - A detailed list of template variables can be found [here](/docs/networking/proxies/nginx.md#available-template-variables)
 - A custom nginx-vhosts template must be named `nginx.conf.sigil`
-  - The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app)
-  - Dokku no longer looks for this file in `/home/dokku/node-js-app` on the Dokku server
-  - Check out an example template [here](/docs/networking/proxies/nginx.md)
+    - The default path for this custom template is the root of your repo (i.e. `/app` in the container or `WORKDIR` if defined in a dockerfile app)
+    - Dokku no longer looks for this file in `/home/dokku/node-js-app` on the Dokku server
+    - Check out an example template [here](/docs/networking/proxies/nginx.md)
 - Support for server-wide SSL certs have been dropped in favor of using the `certs` plugin
-  - `dokku certs:add node-js-app < certs.tar`
+    - `dokku certs:add node-js-app < certs.tar`
 - All domains for an SSL-enabled app will be redirected to https by default
-  - This can be overridden with a custom template
+    - This can be overridden with a custom template
 - Replaced "magic" `NO_VHOST` variable with `domains:enable/disable`
 - Simplified zero downtime control
-  - `checks:enable/disable`
+    - `checks:enable/disable`
 
 ## Dockerfile apps with exposed ports
 
 - Dockerfiles with `EXPOSE` clauses will get [all **tcp** ports proxied by default](/docs/deployment/builders/dockerfiles.md#exposed-ports)
-  - Note that nginx will proxy the same port numbers to listen publicly
-  - UDP ports can be exposed by disabling the [nginx proxy](/docs/networking/proxy-management.md) with `dokku proxy:disable node-js-app`
+    - Note that nginx will proxy the same port numbers to listen publicly
+    - UDP ports can be exposed by disabling the [nginx proxy](/docs/networking/proxy-management.md) with `dokku proxy:disable node-js-app`

docs/appendices/0.6.0-migration-guide.md

@@ -3,30 +3,30 @@
 ## Zero-downtime deployment
 
 - You can now **actually** disable zero-downtime deployments per-app and per-process-type
-  - Some config variables have been moved around
-    - `DOKKU_CHECKS_ENABLED` has been migrated to `DOKKU_CHECKS_SKIPPED`
-    - `DOKKU_CHECKS_DISABLED` is now a thing
-    - The values for the above can be a comma-separated list of process-types or the literal string `_all_`
-  - See the [updated `checks`](/docs/deployment/zero-downtime-deploys.md) docs for more info
+    - Some config variables have been moved around
+        - `DOKKU_CHECKS_ENABLED` has been migrated to `DOKKU_CHECKS_SKIPPED`
+        - `DOKKU_CHECKS_DISABLED` is now a thing
+        - The values for the above can be a comma-separated list of process-types or the literal string `_all_`
+    - See the [updated `checks`](/docs/deployment/zero-downtime-deploys.md) docs for more info
 
 ## Proxy port mapping
 
 - You can now configure host -> container proxy port mappings
-  - The UI is handled by the [proxy](/docs/networking/proxy-management.md) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes.
+    - The UI is handled by the [proxy](/docs/networking/proxy-management.md) interface plugin by setting the `DOKKU_PROXY_PORT_MAP` config variable in the format of `scheme:host-port:container-port`. The default `nginx-vhosts` proxy plugin supports both the `http` and `https` schemes.
 - Default port mappings
-  - buildpack apps will be set to `http:80:5000` and will also include `https:443:5000` if SSL is enabled.
-  - dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container.
-    - You may override this behavior with the [`proxy:ports-*` commands](/docs/networking/proxy-management.md) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command
-    - dockerfile apps without explicitly exposed ports will behave the same as a buildpack app
-  - NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands
+    - buildpack apps will be set to `http:80:5000` and will also include `https:443:5000` if SSL is enabled.
+    - dockerfile apps with explicitly exposed ports (i.e. using the `EXPOSE` directive) will be configured with a listener on each exposed port that proxies to the same port of the deployed application container.
+        - You may override this behavior with the [`proxy:ports-*` commands](/docs/networking/proxy-management.md) or by directly setting `DOKKU_PROXY_PORT_MAP` with the `config:set` command
+        - dockerfile apps without explicitly exposed ports will behave the same as a buildpack app
+    - NOTE: These defaults **are not** automatically changed on subsequent pushes and must be manipulated with the aforementioned commands
 
 ## Calling the `dokku` binary
 
 - Plugins should *not* call the `dokku` binary directly. Clients using the `--app` argument are potentially broken, amongst others, when doing so. Instead, please source the `functions` file for a given plugin when attempting to call Dokku internal functions. As a result, the following Dokku commands are no longer publicly exposed:
-  - `dokku build`
-  - `dokku receive`
-  - `dokku release`
-  - `dokku tar:build`
-  - `dokku tar:build-locked`
-  - `dokku git:build`
-  - `dokku git:build-locked`
+    - `dokku build`
+    - `dokku receive`
+    - `dokku release`
+    - `dokku tar:build`
+    - `dokku tar:build-locked`
+    - `dokku git:build`
+    - `dokku git:build-locked`

docs/appendices/0.8.0-migration-guide.md

@@ -2,13 +2,13 @@
 
 ## Domain Management
 
-You can now set global and app domains via `domains:set` and `domains:set-global`. See the [domains documentation](/docs/configuration/domains/) for more details.
+You can now set global and app domains via `domains:set` and `domains:set-global`. See the [domains documentation](/docs/configuration/domains.md) for more details.
 
 ## Plugin Uninstallation
 
 A new `uninstall` plugin trigger was introduced. This functionality may be in use for newer plugins, so be aware that older Dokku versions may require manual cleanup.
 
-See the [uninstall trigger documentation](/docs/development/plugin-triggers/#uninstall) for implementation instructions.
+See the [uninstall trigger documentation](/docs/development/plugin-triggers.md#uninstall) for implementation instructions.
 
 ## Deployment Tasks
 

docs/assets/favicons/browserconfig.xml

@@ -2,10 +2,10 @@
 <browserconfig>
   <msapplication>
     <tile>
-      <square70x70logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/mstile-70x70.png"/>
-      <square150x150logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/mstile-150x150.png"/>
-      <square310x310logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/mstile-310x310.png"/>
-      <wide310x150logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/mstile-310x150.png"/>
+      <square70x70logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/mstile-70x70.png"/>
+      <square150x150logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/mstile-150x150.png"/>
+      <square310x310logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/mstile-310x310.png"/>
+      <wide310x150logo src="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/mstile-310x150.png"/>
       <TileColor>#da532c</TileColor>
     </tile>
   </msapplication>

docs/assets/favicons/manifest.json

@@ -2,37 +2,37 @@
     "name": "Dokku",
     "icons": [
         {
-            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.30.2\/docs\/assets\/favicons\/android-chrome-36x36.png",
+            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.31.2\/docs\/assets\/favicons\/android-chrome-36x36.png",
             "sizes": "36x36",
             "type": "image\/png",
             "density": "0.75"
         },
         {
-            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.30.2\/docs\/assets\/favicons\/android-chrome-48x48.png",
+            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.31.2\/docs\/assets\/favicons\/android-chrome-48x48.png",
             "sizes": "48x48",
             "type": "image\/png",
             "density": "1.0"
         },
         {
-            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.30.2\/docs\/assets\/favicons\/android-chrome-72x72.png",
+            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.31.2\/docs\/assets\/favicons\/android-chrome-72x72.png",
             "sizes": "72x72",
             "type": "image\/png",
             "density": "1.5"
         },
         {
-            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.30.2\/docs\/assets\/favicons\/android-chrome-96x96.png",
+            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.31.2\/docs\/assets\/favicons\/android-chrome-96x96.png",
             "sizes": "96x96",
             "type": "image\/png",
             "density": "2.0"
         },
         {
-            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.30.2\/docs\/assets\/favicons\/android-chrome-144x144.png",
+            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.31.2\/docs\/assets\/favicons\/android-chrome-144x144.png",
             "sizes": "144x144",
             "type": "image\/png",
             "density": "3.0"
         },
         {
-            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.30.2\/docs\/assets\/favicons\/android-chrome-192x192.png",
+            "src": "https:\/\/cdn.jsdelivr.net\/dokku\/dokku@v0.31.2\/docs\/assets\/favicons\/android-chrome-192x192.png",
             "sizes": "192x192",
             "type": "image\/png",
             "density": "4.0"

docs/assets/versions.json

@@ -27,6 +27,7 @@
     "0.27.10",
     "0.28.4",
     "0.29.4",
-    "0.30.2"
+    "0.30.11",
+    "0.31.2"
   ]
 }

docs/community/plugins.md

@@ -24,6 +24,7 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 
 | Plugin                                                                                            | Author                | Compatibility         |
 | ------------------------------------------------------------------------------------------------- | --------------------- | --------------------- |
+| [Cron Restart](https://github.com/dokku/dokku-cron-restart)                                       | [dokku][]             | 0.30.0+               |
 | [CouchDB](https://github.com/dokku/dokku-couchdb)                                                 | [dokku][]             | 0.4.0+                |
 | [Elasticsearch](https://github.com/dokku/dokku-elasticsearch-plugin)                              | [dokku][]             | 0.4.0+                |
 | [Grafana/Graphite/Statsd](https://github.com/dokku/dokku-graphite-grafana)                        | [dokku][]             | 0.4.0+                |
@@ -45,7 +46,8 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 
 ## Community plugins
 
-> Warning: The following plugins have been supplied by our community and may not have been tested by Dokku maintainers.
+> [!WARNING]
+> The following plugins have been supplied by our community and may not have been tested by Dokku maintainers.
 
 ### Datastores
 
@@ -115,12 +117,12 @@ The following plugins are available and provided by Dokku maintainers.  Please f
 | [Open App Ports](https://github.com/josegonzalez/dokku-ports)                                     | [josegonzalez][]      | 0.3.x                 |
 | [Proctype Filter](https://github.com/michaelshobbs/dokku-proctype-filter)                         | [michaelshobbs][]     | 0.4.0+                |
 | [robots.txt](https://notabug.org/candlewaster/dokku-robots.txt)                                   | [candlewaster][]      | 0.4.x                 |
-| [SSH Deployment Keys](https://github.com/cedricziel/dokku-deployment-keys)<sup>2</sup>            | [cedricziel][]        | 0.4.0+                |
-| [SSH Hostkeys](https://github.com/cedricziel/dokku-hostkeys-plugin)<sup>3</sup>                   | [cedricziel][]        | 0.3.x                 |
+| [SSH Deployment Keys](https://github.com/cedricziel/dokku-deployment-keys)<sup>3</sup>            | [cedricziel][]        | 0.4.0+                |
+| [SSH Hostkeys](https://github.com/cedricziel/dokku-hostkeys-plugin)<sup>4</sup>                   | [cedricziel][]        | 0.3.x                 |
 | [Application build hook](https://github.com/fteychene/dokku-build-hook)                           | [fteychene][]         | 0.4.0+                |
 | [Post Deploy Script](https://github.com/baikunz/dokku-post-deploy-script)                         | [baikunz][]           | 0.4.0+                |
-| [Auto Sync](https://github.com/IdeaSynthesis/dokku-autosync)<sup>4</sup>                          | [fomojola][]          | 0.8.1+                |
-| [Deploy Webhook](https://github.com/IdeaSynthesis/dokku-deploy-webhook)<sup>5</sup>               | [fomojola][]          | 0.8.1+                |
+| [Auto Sync](https://github.com/IdeaSynthesis/dokku-autosync)<sup>5</sup>                          | [fomojola][]          | 0.8.1+                |
+| [Deploy Webhook](https://github.com/IdeaSynthesis/dokku-deploy-webhook)<sup>6</sup>               | [fomojola][]          | 0.8.1+                |
 
 <sup>1</sup> Extends app.json support to include creating volumes and creating / linking databases on push
 
@@ -207,7 +209,7 @@ The following plugins have been removed as their functionality is now in Dokku C
 | [Volume (persistent storage)](https://github.com/ohardy/dokku-volume)                             | [ohardy][]            | v0.5.0 (storage plugin)                   |
 
 <sup>1</sup> Conflicts with [VHOSTS Custom Configuration](https://github.com/neam/dokku-nginx-vhosts-custom-configuration)
-<sup>2</sup> Similar to the heroku-labs feature (see https://devcenter.heroku.com/articles/labs-user-env-compile)
+<sup>2</sup> Similar to the [heroku-labs feature](https://devcenter.heroku.com/articles/labs-user-env-compile)
 
 ### Unmaintained Plugins
 

docs/configuration/domains.md

@@ -1,5 +1,6 @@
 # Domain Configuration
 
+> [!IMPORTANT]
 > New as of 0.3.10
 
 ```
@@ -65,6 +66,7 @@ dokku domains:set node-js-app dokku.me dokku.org
 
 ## Displaying domains reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the app's domains status using the `domains:report` command:

docs/configuration/environment-variables.md

@@ -14,13 +14,15 @@ config:keys (<app>|--global) [--merged]
 config:set [--encoded] [--no-restart] (<app>|--global) KEY1=VALUE1 [KEY2=VALUE2 ...]  Set one or more config vars
 config:unset [--no-restart] (<app>|--global) KEY1 [KEY2 ...]                          Unset one or more config vars
 ```
+
 > For security reasons - and as per [docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available _only_ during runtime, as noted in [this issue](https://github.com/dokku/dokku/issues/1860). Consider using [build arguments](/docs/deployment/builders/dockerfiles.md#build-time-configuration-variables) to expose variables during build-time for Dockerfile apps.
 
 Environment variables are available both at run time and during the application build/compilation step for buildpack-based deploys.
 
 For buildpack deploys, Dokku will create a  `/app/.env` file that can be used for legacy buildpacks. Note that this is _not_ updated when `config:set` or `config:unset` is called, and is only written during a `deploy` or `ps:rebuild`. Developers are encouraged to instead read from the application environment directly, as the proper values will be available then.
 
-> Note: Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications.
+> [!NOTE]
+> Global `ENV` files are sourced before app-specific `ENV` files. This means that app-specific variables will take precedence over global variables. Configuring your global `ENV` file is manual, and should be considered potentially dangerous as configuration applies to all applications.
 
 You can set multiple environment variables at once:
 
@@ -28,7 +30,8 @@ You can set multiple environment variables at once:
 dokku config:set node-js-app ENV=prod COMPILE_ASSETS=1
 ```
 
-> Note: Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:
+Whitespace and special characters get tricky. If you are using dokku locally you don't need to do any special escaping. If you are using dokku over ssh you will need to backslash-escape spaces:
+
 ```shell
 dokku config:set node-js-app KEY="VAL\ WITH\ SPACES"
 ```
@@ -58,8 +61,7 @@ dokku config:export node-js-app
 eval $(dokku config:export node-js-app)
 ```
 
-You can control the format of the exported variables with the `--format` flag. 
-`--format=shell` will output the variables in a single-line for usage in command-line utilities:
+You can control the format of the exported variables with the `--format` flag. `--format=shell` will output the variables in a single-line for usage in command-line utilities:
 
 ```shell
 dokku config:export --format shell node-js-app
@@ -73,7 +75,8 @@ dokku config:export --format shell node-js-app
 
 The following config variables have special meanings and can be set in a variety of ways. Unless specified via global app config, the values may not be passed into applications. Usage of these values within applications should be considered unsafe, as they are an internal configuration values that may be moved to the internal properties system in the future.
 
-> Warning: This list is not exhaustive, and may vary from version to version.
+> [!WARNING]
+> This list is not exhaustive, and may vary from version to version.
 
 | Name                           | Default                         | How to modify                                                                                                                                    | Description                                                                                                |
 | ------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
@@ -111,12 +114,10 @@ The following config variables have special meanings and can be set in a variety
 | `DOKKU_DISABLE_APP_AUTOCREATION` | none                            | `dokku config:set`                                                                                                                               | Disables automatic creation of a non-existent app on deploy. |
 | `DOKKU_DOCKER_STOP_TIMEOUT`    | `10`                            | `dokku config:set`                                                                                                                               | Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands _also_ respect this value. If not specified, the docker defaults for the [docker stop command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.|
 | `DOKKU_DOCKERFILE_CACHE_BUILD` | none                            | `dokku config:set`                                                                                                                               | |
-| `DOKKU_DOCKERFILE_PORTS`       | dockerfile ports                | `dokku config:set`                                                                                                                               | |
 | `DOKKU_DOCKERFILE_START_CMD`   | none                            | `dokku config:set`                                                                                                                               | |
 | `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_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`                                                                                                                               | |

docs/configuration/ssl.md

@@ -1,5 +1,6 @@
 # SSL Configuration
 
+> [!IMPORTANT]
 > New as of 0.4.0
 
 Dokku supports SSL/TLS certificate inspection and CSR/Self-signed certificate generation via the `certs` plugin. Note that whenever SSL/TLS support is enabled SPDY is also enabled.
@@ -33,7 +34,8 @@ tar cvf cert-key.tar server.crt server.key
 dokku certs:add node-js-app < cert-key.tar
 ```
 
-> Note: If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`.
+> [!NOTE]
+> If your `.crt` file came alongside a `.ca-bundle`, you'll want to concatenate those into a single `.crt` file before adding it to the `.tar`.
 
 ```shell
 cat yourdomain_com.crt yourdomain_com.ca-bundle > server.crt
@@ -47,7 +49,8 @@ Note that with the default nginx template, requests will be redirected to the `h
 
 ### Certificate generation
 
-> Note: Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.
+> [!NOTE]
+> Using this method will create a self-signed certificate, which is only recommended for development or staging use, not production environments.
 
 The `certs:generate` command will walk you through the correct `openssl` commands to create a key, csr and a self-signed cert for a given app/domain. We automatically put the self-signed cert in place as well as add the specified domain to the application configuration.
 
@@ -69,6 +72,7 @@ dokku certs:show node-js-app key > server.key
 
 ### Displaying certificate reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the apps ssl status using the `certs:report` command:
@@ -132,37 +136,12 @@ See the [NGINX HSTS documentation](/docs/networking/proxies/nginx.md#hsts-header
 
 Certain versions of nginx have bugs that prevent [HTTP/2](https://nginx.org/en/docs/http/ngx_http_v2_module.html) from properly responding to all clients, thus causing applications to be unavailable. For HTTP/2 to be enabled in your applications' nginx configs, you need to have installed nginx 1.11.5 or higher. See [issue 2435](https://github.com/dokku/dokku/issues/2435) for more details.
 
-## Running behind a load balancer
-
-Your application has access to the HTTP headers `X-Forwarded-Proto`, `X-Forwarded-Port` and `X-Forwarded-For`. These headers indicate the protocol of the original request (HTTP or HTTPS), the port number, and the IP address of the client making the request, respectively. The default configuration is for Nginx to set these headers.
-
-If your server runs behind an HTTP(S) load balancer, then Nginx will see all requests as coming from the load balancer. If your load balancer sets the `X-Forwarded-` headers, you can tell Nginx to pass these headers from load balancer to your application via `nginx:set`:
-
-```shell
-dokku nginx:set node-js-app x-forwarded-for-value "\$http_x_forwarded_for"
-dokku nginx:set node-js-app x-forwarded-port-value "\$http_x_forwarded_port"
-dokku nginx:set node-js-app x-forwarded-proto-value "\$http_x_forwarded_proto"
-```
-
-Only use this option if:
-1. All requests are terminated at the load balancer, and forwarded to Nginx
-2. The load balancer is configured to send the `X-Forwarded-` headers (this may be off by default)
-
-If it's possible to make HTTP(S) requests directly to Nginx, bypassing the load balancer, or if the load balancer is not configured to set these headers, then it becomes possible for a client to set these headers to arbitrary values.
-
-The `x-forwarded-ssl` property may also be set for application frameworks that require this value. Note that this is a non-standard version of setting `x-forwarded-proto` to `https`, and should only be done as a last resort.
-
-```shell
-# force-setting value to `on`
-dokku nginx:set node-js-app x-forwarded-ssl on
-
-# force-setting value to `off`
-dokku nginx:set node-js-app x-forwarded-ssl on
-
-# removing the value from nginx.conf (default)
-dokku nginx:set node-js-app x-forwarded-ssl
-```
-
 ### 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
+
+### Running behind a proxy (`X-Forwarded-Ssl`, etc.)
+
+See the [running behind another proxy documentation](/docs/networking/proxies/nginx.md#running-behind-another-proxy--configuring-x-forwarded--headers) for more information on how to configure your Nginx config when your server is running behind a proxy (e.g. load balancer, etc.).

docs/deployment/application-deployment.md

@@ -1,6 +1,7 @@
 # Deploying an Application
 
-> Note: This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should substitute the domain `dokku.me` for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use `dokku.me` which points to the IP of the VM.
+> [!NOTE]
+> This walkthrough uses the hostname `dokku.me` in commands. When deploying to your own server, you should substitute the domain `dokku.me` for the domain name or IP address associated with your server. Users of the Vagrant VM included with Dokku can use `dokku.me` which points to the IP of the VM.
 
 ## Deploy tutorial
 
@@ -8,7 +9,6 @@ Once you have configured Dokku with at least one user, you can deploy applicatio
 
 ```shell
 # from your local machine
-# SSH access to github must be enabled on this host
 git clone https://github.com/heroku/ruby-getting-started
 ```
 
@@ -53,7 +53,8 @@ Dokku supports linking a single service to multiple applications as well as link
 
 ### Deploy the app
 
-> Warning: Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).**
+> [!WARNING]
+> Your app should respect the `PORT` environment variable, otherwise it may not respond to web requests. You can find more information in the [port management documentation](/docs/networking/port-management.md).**
 
 Now you can deploy the `ruby-getting-started` app to your Dokku server. All you have to do is add a remote to name the app. Applications are created on-the-fly on the Dokku server.
 
@@ -62,16 +63,18 @@ Now you can deploy the `ruby-getting-started` app to your Dokku server. All you
 # the remote username *must* be dokku or pushes will fail
 cd ruby-getting-started
 git remote add dokku dokku@dokku.me:ruby-getting-started
-git push dokku main:master
+git push dokku main
 ```
 
-> Note: Some tools may not support the short-upstream syntax referenced above, and you may need to prefix
+> [!NOTE]
+> Some tools may not support the short-upstream syntax referenced above, and you may need to prefix
 > the upstream with the scheme `ssh://` like so: `ssh://dokku@dokku.me:ruby-getting-started`
 > Please see the [Git](https://git-scm.com/docs/git-clone#_git_urls_a_id_urls_a) documentation for more details.
 
-> Note: Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/<your private key>`.
+> [!NOTE]
+> Your private key should be registered with `ssh-agent` in your local development environment. If you get a `permission denied` error when pushing, you can register your private key as follows: `ssh-add -k ~/<your private key>`.
 
-After running `git push dokku main:master`, you should have output similar to this in your terminal:
+After running `git push dokku main`, you should have output similar to this in your terminal:
 
 ```
 Counting objects: 231, done.
@@ -103,7 +106,7 @@ Once the deploy is complete, the application's web URL will be generated as abov
 Dokku supports deploying applications in a few ways:
 
 - [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) via [Herokuish](https://github.com/gliderlabs/herokuish#buildpacks): See the [herokuish buildpacks documentation](/docs/deployment/builders/herokuish-buildpacks.md) to learn about the different ways to specify a buildpack.
-  - This is the default method used by Dokku.
+    - This is the default method used by Dokku.
 - [Dockerfile](https://docs.docker.com/reference/builder/): See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to learn about the different ways to configure Dockerfile-based deploys.
 - [Docker Image](https://docs.docker.com/get-started/overview/#docker-objects): See the [docker image documentation](/docs/deployment/methods/git.md#initializing-an-app-repository-from-a-docker-image) to learn about how to deploy a Docker Image.
 
@@ -149,7 +152,7 @@ dokku config:set ruby-getting-started DOKKU_SKIP_DEPLOY=true
 
 ### Redeploying or restarting
 
-If you need to redeploy or restart your app: 
+If you need to redeploy or restart your app:
 
 ```shell
 # on the Dokku host
@@ -169,7 +172,8 @@ ssh-keyscan -t rsa github.com >> ~/.ssh/known_hosts
 ssh -T git@github.com
 ```
 
-> Warning: if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply.
+> [!WARNING]
+> if the buildpack or Dockerfile build process require SSH key access for other reasons, the above may not always apply.
 
 ## Deploying to subdomains
 
@@ -180,7 +184,7 @@ If you do not enter a fully qualified domain name when pushing your app, Dokku d
 # the remote username *must* be dokku or pushes will fail
 # the below example assumes your app server domain or IP is dokku.me. Push in the form of: dokku@{serveripordomain}:{dokkuappname} 
 git remote add dokku dokku@dokku.me:ruby-getting-started
-git push dokku main:master
+git push dokku main
 ```
 
 ```
@@ -194,7 +198,7 @@ You can also specify the fully qualified name as follows:
 # from your local machine
 # the remote username *must* be dokku or pushes will fail
 git remote add dokku dokku@dokku.me:app.dokku.me
-git push dokku main:master
+git push dokku main
 ```
 
 ```
@@ -208,7 +212,7 @@ This is useful when you want to deploy to the root domain:
 # from your local machine
 # the remote username *must* be dokku or pushes will fail
 git remote add dokku dokku@dokku.me:dokku.me
-git push dokku main:master
+git push dokku main
 ```
 
 ```

docs/deployment/application-management.md

@@ -1,5 +1,6 @@
 # Application Management
 
+> [!IMPORTANT]
 > New as of 0.3.1
 
 ```
@@ -19,6 +20,7 @@ apps:unlock <app>                              # Unlocks an app for deployment
 
 ### Listing applications
 
+> [!IMPORTANT]
 > New as of 0.8.1. Use the `apps` command for older versions.
 
 You can easily list all available applications using the `apps:list` command:
@@ -117,6 +119,7 @@ Destroying an application will unlink all linked services and destroy any config
 
 ### Renaming a deployed app
 
+> [!IMPORTANT]
 > New as of 0.4.7
 
 You can rename a deployed app using the `apps:rename` command. Note that the application *must* have been deployed at least once, or the rename will not complete successfully:
@@ -150,7 +153,7 @@ By default, Dokku will deploy the renamed app, though you can skip the deploy by
 dokku apps:rename --skip-deploy node-js-app io-js-app
 ```
 
-Remember to also change your git remote on your local machine in order to make `git push dokku main:master` work again. For this you can use `git remote set-url`.
+Remember to also change your git remote on your local machine in order to make `git push dokku main` work again. For this you can use `git remote set-url`.
 
 ```shell
 git remote set-url dokku dokku@dokku.me:io-js-app
@@ -158,6 +161,7 @@ git remote set-url dokku dokku@dokku.me:io-js-app
 
 ### Cloning an existing app
 
+> [!IMPORTANT]
 > New as of 0.11.5
 
 You can clone an existing app using the `apps:clone` command.  Note that the application *must* have been deployed at least once, or cloning will not complete successfully:
@@ -177,7 +181,8 @@ This will copy all of your app's contents into a new app directory with the name
 - SSL certificates will not be copied to the new app.
 - Port mappings with the scheme `https` and host-port `443` will be skipped.
 
-> Warning: If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors.
+> [!WARNING]
+> If you have exposed specific ports via `docker-options` plugin, or performed anything that cannot be done against multiple applications, `apps:clone` may result in errors.
 
 By default, Dokku will deploy this new app, though you can skip the deploy by using the `--skip-deploy` flag:
 
@@ -193,6 +198,7 @@ dokku apps:clone --ignore-existing node-js-app io-js-app
 
 ### Locking app deploys
 
+> [!IMPORTANT]
 > New as of 0.11.6
 
 If you wish to disable deploying for a period of time, this can be done via deploy locks. Normally, deploy locks exist only for the duration of a deploy so as to avoid deploys from colliding, but a deploy lock can be created by running the `apps:lock` command.
@@ -207,11 +213,13 @@ dokku apps:lock node-js-app
 
 ### Unlocking app deploys
 
+> [!IMPORTANT]
 > New as of 0.11.6
 
 In some cases, it may be necessary to remove an existing deploy lock. This can be performed via the `apps:unlock` command.
 
-> Warning: Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.
+> [!WARNING]
+> Removing the deploy lock *will not* stop in progress deploys. At this time, in progress deploys will need to be manually terminated by someone with server access.
 
 ```shell
 dokku apps:unlock node-js-app
@@ -225,6 +233,7 @@ dokku apps:unlock node-js-app
 
 ### Checking lock status
 
+> [!IMPORTANT]
 > New as of 0.13.0
 
 In some cases, you may wish to inspect the state of an app lock. To do so, you can issue an `apps:lock` command. This will exit non-zero if there is no app lock in place.
@@ -239,6 +248,7 @@ Deploy lock does not exist
 
 ### Displaying reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the deployed apps using the `apps:report` command:

docs/deployment/builders/builder-management.md

@@ -1,5 +1,6 @@
 # Builder Management
 
+> [!IMPORTANT]
 > New as of 0.24.0
 
 ```
@@ -51,7 +52,8 @@ dokku builder:set --global selected
 
 #### Changing the build directory
 
-> Warning: Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the `git.keep-git-dir` property.
+> [!WARNING]
+> Please keep in mind that setting a custom build directory will result in loss of any changes to the top-level directory, such as the `git.keep-git-dir` property.
 
 When deploying a monorepo, it may be desirable to specify the specific build directory to use for a given app. This can be done via the `builder:set` command. If a value is specified and that directory does not exist within the repository, the build will fail.
 
@@ -131,14 +133,14 @@ dokku builder:report node-js-app --builder-selected
 To create a custom builder, the following triggers must be implemented:
 
 - `builder-build`:
-  - arguments: `BUILDER_TYPE` `APP` `SOURCECODE_WORK_DIR`
-  - description: Creates a docker image named with the output of `common#get_app_image_name $APP`.
+    - arguments: `BUILDER_TYPE` `APP` `SOURCECODE_WORK_DIR`
+    - description: Creates a docker image named with the output of `common#get_app_image_name $APP`.
 - `builder-detect`:
-  - arguments: `APP` `SOURCECODE_WORK_DIR`
-  - description: Outputs the name of the builder (without the `builder-` prefix) to use to build the app.
+    - arguments: `APP` `SOURCECODE_WORK_DIR`
+    - description: Outputs the name of the builder (without the `builder-` prefix) to use to build the app.
 - `builder-release`:
-  - arguments: `BUILDER_TYPE` `APP` `IMAGE_AG`
-  - description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately.
+    - arguments: `BUILDER_TYPE` `APP` `IMAGE_AG`
+    - description: A post-build, pre-release trigger that can be used to post-process the image. Usually simply tags and labels the image appropriately.
 
 Custom plugins names _must_ have the prefix `builder-` or builder overriding via `builder:set` may not function as expected.
 

docs/deployment/builders/cloud-native-buildpacks.md

@@ -1,5 +1,6 @@
 # Cloud Native Buildpacks
 
+> [!IMPORTANT]
 > New as of 0.22.0
 
 ```
@@ -13,7 +14,8 @@ buildpacks:set-property [--global|<app>] <key> <value>  # Set or clear a buildpa
 
 Cloud Native Buildpacks are an evolution over the Buildpacks technology provided by the Herokuish builder. See the [herokuish buildpacks documentation](/docs/deployment/builders/herokuish-buildpacks.md) for more information on how to clear buildpack build cache for an application.
 
-> Warning: This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time.
+> [!WARNING]
+> This functionality uses the `pack` cli from the [Cloud Native Buildpacks](https://buildpacks.io) project to build apps. As the integration is experimental in Dokku, it is likely to change over time.
 
 ## Usage
 
@@ -28,25 +30,27 @@ Builds will proceed with the `pack` cli for the app from then on.
 As this functionality is highly experimental, there are a number of caveats. Please note that not all issuesare listed below.
 
 - Specifying specific buildpacks is not currently possible.
-  - A future release will add support for specifying buildpacks via the `buildpacks` plugin.
+    - A future release will add support for specifying buildpacks via the `buildpacks` plugin.
 - There is currently no way to specify extra arguments for `pack` cli invocations.
-  - A future release will add support for injecting extra arguments during the build process.
+    - A future release will add support for injecting extra arguments during the build process.
 - The default process type is `web`.
 - Build cache is stored in Docker volumes instead of on disk. As such, `repo:purge-cache` currently has no effect.
-  - A future version will add integration with the `repo` plugin.
+    - A future version will add integration with the `repo` plugin.
 - `pack` is not currently included with Dokku, nor is it added as a package dependency.
-  - A future version will include it as a package dependency.
+    - A future version will include it as a package dependency.
 
 ### Detection
 
 This builder will be auto-detected in either the following cases:
 
 - The `DOKKU_CNB_EXPERIMENTAL` app environment variable is set to `1`.
-  ```shell
-  dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1
-  ```
+
+    ```shell
+    dokku config:set --no-restart node-js-app DOKKU_CNB_EXPERIMENTAL=1
+    ```
+
 - A `project.toml` file exists in the root of the app repository.
-  - This file is consumed by `pack-cli` and used to describe how the app is built.
+    - This file is consumed by `pack-cli` and used to describe how the app is built.
 
 The builder can also be specified via the `builder:set` command:
 
@@ -60,8 +64,10 @@ dokku builder:set node-js-app selected pack
 
 When deploying a monorepo, it may be desirable to specify the specific path of the `project.toml` file to use for a given app. This can be done via the `builder-pack:set` command. If a value other than `project.toml` is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no `project.toml`.
 
+For deploys via the `git:from-image` and `git:load-image` commands, the `project.toml` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `project.toml` extracted directly from the source code. Both cases will respect the configured `projecttoml-path` property value.
+
 ```shell
-dokku builder-pack:set node-js-app projecttoml-path project2.toml
+dokku builder-pack:set node-js-app projecttoml-path .dokku/project.toml
 ```
 
 The default value may be set by passing an empty value for the option:
@@ -84,6 +90,7 @@ dokku builder-pack:set --global projecttoml-path
 
 ### Displaying builder-pack reports for an app
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 You can get a report about the app's storage status using the `builder-pack:report` command:
@@ -132,9 +139,10 @@ project2.toml
 
 ### Customizing the Buildpack stack builder
 
+> [!IMPORTANT]
 > New as of 0.23.0
 
-The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/buildpacks`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
+The default stack builder in use by CNB buildpacks in Dokku is based on `heroku/builder:22`. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
 
 ```shell
 dokku buildpacks:set-property node-js-app stack paketobuildpacks/build:base-cnb
@@ -148,7 +156,7 @@ dokku buildpacks:set-property node-js-app stack
 
 A change in the stack builder value will execute the `post-stack-set` trigger.
 
-Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_CNB_BUILDER` environment variable (`heroku/buildpacks` by default).
+Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_CNB_BUILDER` environment variable (`heroku/builder:22` by default).
 
 ```shell
 # set globally
@@ -157,3 +165,7 @@ dokku buildpacks:set-property --global stack paketobuildpacks/build:base-cnb
 # unset globally
 dokku buildpacks:set-property --global stack
 ```
+
+### Specifying commands via Procfile
+
+See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app.

docs/deployment/builders/dockerfiles.md

@@ -1,5 +1,6 @@
 # Dockerfile Deployment
 
+> [!IMPORTANT]
 > New as of 0.3.15
 
 ```
@@ -29,7 +30,7 @@ Dokku will only select the `dockerfile` builder if both the `herokuish` and `pac
 If an application was previously deployed via buildpacks, the following commands should be run before a Dockerfile deploy will succeed:
 
 ```shell
-dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP 
+dokku proxy:clear node-js-app
 ```
 
 ### Changing the `Dockerfile` location
@@ -38,6 +39,8 @@ dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP
 
 When deploying a monorepo, it may be desirable to specify the specific path of the `Dockerfile` file to use for a given app. This can be done via the `builder-dockerfile:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
 
+For git push, `git:from-archive`, and `git:sync` workflows, the `Dockerfile` is extracted directly from the source code, respecting the configured `dockerfile-path` property value.
+
 ```shell
 dokku builder-dockerfile:set node-js-app dockerfile-path Dockerfile2
 ```
@@ -62,6 +65,7 @@ dokku builder-dockerfile:set --global dockerfile-path
 
 ### Displaying builder-dockerfile reports for an app
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 You can get a report about the app's storage status using the `builder-dockerfile:report` command:
@@ -112,10 +116,10 @@ Dockerfile2
 
 For security reasons - and as per [Docker recommendations](https://github.com/docker/docker/issues/13490) - Dockerfile-based deploys have variables available only during runtime.
 
-For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](/docs/advanced-usage/docker-options.md):
+For users that require customization in the `build` phase, you may use build arguments via the [docker-options plugin](/docs/advanced-usage/docker-options.md). All environment variables set by the `config` plugin are automatically exported during a docker build, and thus `--build-arg` only requires setting a key without a value.
 
 ```shell
-dokku docker-options:add node-js-app build '--build-arg NODE_ENV=production'
+dokku docker-options:add node-js-app build '--build-arg NODE_ENV'
 ```
 
 Once set, the Dockerfile usage would be as follows:
@@ -148,18 +152,18 @@ ENV NODE_ENV ${NODE_ENV}
 RUN echo $NODE_ENV
 ```
 
-### Building images with Docker Buildkit
+### Building images with Docker BuildKit
 
-If your Dockerfile is using Docker engine's [buildkit](https://docs.docker.com/develop/develop-images/build_enhancements/) (not to be confused with buildpacks), then the `DOCKER_BUILDKIT=1` environment variable needs to be set. Additionally, complete build log output can be forced via `BUILDKIT_PROGRESS=plain`. Both of these environment variables can be set as follows:
+If your Dockerfile is using Docker Engine's [BuildKit](https://docs.docker.com/develop/develop-images/build_enhancements/) (not to be confused with buildpacks), then the `DOCKER_BUILDKIT=1` environment variable needs to be set (unless you're using Docker Engine v24 or higher, which [uses BuildKit by default](https://docs.docker.com/build/buildkit/#getting-started)). Additionally, complete build log output can be forced via `BUILDKIT_PROGRESS=plain`. Both of these environment variables can be set as follows:
 
 ```shell
 echo "export DOCKER_BUILDKIT=1" | sudo tee -a /etc/default/dokku
 echo "export BUILDKIT_PROGRESS=plain" | sudo tee -a /etc/default/dokku
 ```
 
-#### Buildkit directory caching
+#### BuildKit directory caching
 
-Buildkit implements the `RUN --mount` option, enabling mount directory caches for `RUN` directives. The following is an example that mounts debian packaging related directories, which can speed up fetching of remote package data.
+BuildKit implements the `RUN --mount` option, enabling mount directory caches for `RUN` directives. The following is an example that mounts debian packaging related directories, which can speed up fetching of remote package data.
 
 ```Dockerfile
 FROM debian:latest
@@ -194,34 +198,10 @@ Setting `$DOKKU_DOCKERFILE_CACHE_BUILD` to `true` or `false` will enable or disa
 
 ### Procfiles and multiple processes
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
-You can also customize the run command using a `Procfile`, much like you would on Heroku or
-with a buildpack deployed app. The `Procfile` should contain one or more lines defining [process types and associated commands](https://devcenter.heroku.com/articles/procfile#declaring-process-types).
-When you deploy your app, a Docker image will be built. The `Procfile` will be extracted from the image
-(it must be in the folder defined in your `Dockerfile` as `WORKDIR` or `/app`) and the commands
-in it will be passed to `docker run` to start your process(es). Here's an example `Procfile`:
-
-```Procfile
-web: bin/run-prod.sh
-worker: bin/run-worker.sh
-```
-
-And `Dockerfile`:
-
-```Dockerfile
-FROM ubuntu:20.04
-WORKDIR /app
-COPY . ./
-CMD ["bin/run-dev.sh"]
-```
-
-When you deploy this app the `web` process will automatically be scaled to 1 and your Docker container
-will be started basically using the command `docker run bin/run-prod.sh`. If you want to also run
-a worker container for this app, you can run `dokku ps:scale worker=1` and a new container will be
-started by running `docker run bin/run-worker.sh` (the actual `docker run` commands are a bit more
-complex, but this is the basic idea). If you use an `ENTRYPOINT` in your `Dockerfile`, the lines
-in your `Procfile` will be passed as arguments to the `ENTRYPOINT` script instead of being executed.
+See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app.
 
 ### Exposed ports
 

docs/deployment/builders/herokuish-buildpacks.md

@@ -1,5 +1,6 @@
 # Herokuish Buildpacks
 
+> [!IMPORTANT]
 > Subcommands new as of 0.15.0
 
 ```
@@ -17,14 +18,15 @@ builder-herokuish:report [<app>] [<flag>]   # Displays a builder-herokuish repor
 builder-herokuish:set <app> <key> (<value>) # Set or clear a builder-herokuish property for an app
 ```
 
-> Warning: If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin.
+> [!WARNING]
+> If using the `buildpacks` plugin, be sure to unset any `BUILDPACK_URL` and remove any such entries from a committed `.env` file. A specified `BUILDPACK_URL` will always override a `.buildpacks` file or the buildpacks plugin.
 
 Dokku normally defaults to using [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) for deployment, though this may be overridden by committing a valid `Dockerfile` to the root of your repository and pushing the repository to your Dokku installation. To avoid this automatic `Dockerfile` deployment detection, you may do one of the following:
 
 - Set a `BUILDPACK_URL` environment variable
-  - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
+    - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
 - Create a `.buildpacks` file in the root of your repository.
-  - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands.
+    - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands.
 
 This page will cover usage of the `buildpacks` plugin.
 
@@ -35,9 +37,9 @@ This page will cover usage of the `buildpacks` plugin.
 This builder will be auto-detected in either the following cases:
 
 - The `BUILDPACK_URL` app environment variable is set.
-  - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
+    - This can be done via `dokku config:set` or via a committed `.env` file in the root of the repository. See the [environment variable documentation](/docs/configuration/environment-variables.md) for more details.
 - A `.buildpacks` file exists in the root of the app repository.
-  - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands.
+    - This can be via a committed `.buildpacks` file or managed via the `buildpacks` plugin commands.
 
 The builder can also be specified via the `builder:set` command:
 
@@ -147,6 +149,7 @@ dokku buildpacks:clear node-js-app
 
 ### Customizing the Buildpack stack builder
 
+> [!IMPORTANT]
 > New as of 0.23.0
 
 The default stack builder in use by Herokuish buildpacks in Dokku is based on `gliderlabs/herokuish:latest`. Typically, this is installed via an OS package which pulls the requisite Docker image. Users may desire to switch the stack builder to a custom version, either to update the operating system or to customize packages included with the stack builder. This can be performed via the `buildpacks:set-property` command.
@@ -163,7 +166,7 @@ dokku buildpacks:set-property node-js-app stack
 
 A change in the stack builder value will execute the `post-stack-set` trigger.
 
-Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_IMAGE` environment variable (`gliderlabs/herokuish:latest-20` by default).
+Finally, stack builders can be set or unset globally as a fallback. This will take precedence over a globally set `DOKKU_IMAGE` environment variable (`gliderlabs/herokuish:latest-22` by default).
 
 ```shell
 # set globally
@@ -175,6 +178,7 @@ dokku buildpacks:set-property --global stack
 
 ### Allowing herokuish for non-amd64 platforms
 
+> [!IMPORTANT]
 > New as of 0.29.0
 
 By default, the builder-herokuish plugin is not enabled for non-amd64 platforms, and attempting to use it is blocked. This is because the majority of buildpacks are not cross-platform compatible, and thus building apps will either be considerably slower - due to emulating the amd64 platform - or won't work - due to building amd64 packages on arm/arm64 platforms.
@@ -213,18 +217,18 @@ dokku buildpacks:report
 
 ```
 =====> node-js-app buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:v0.5.23-20
-       Buildpacks global stack:    gliderlabs/herokuish:latest-20
+       Buildpacks computed stack:  gliderlabs/herokuish:v0.7.0-22
+       Buildpacks global stack:    gliderlabs/herokuish:latest-22
        Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git
-       Buildpacks stack:           gliderlabs/herokuish:v0.5.23-20
+       Buildpacks stack:           gliderlabs/herokuish:v0.7.0-20
 =====> python-sample buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:latest-20
-       Buildpacks global stack:    gliderlabs/herokuish:latest-20
+       Buildpacks computed stack:  gliderlabs/herokuish:latest-22
+       Buildpacks global stack:    gliderlabs/herokuish:latest-22
        Buildpacks list:            https://github.com/heroku/heroku-buildpack-nodejs.git,https://github.com/heroku/heroku-buildpack-python.git
        Buildpacks stack:
 =====> ruby-sample buildpacks information
-       Buildpacks computed stack:  gliderlabs/herokuish:latest-20
-       Buildpacks global stack:    gliderlabs/herokuish:latest-20
+       Buildpacks computed stack:  gliderlabs/herokuish:latest-22
+       Buildpacks global stack:    gliderlabs/herokuish:latest-22
        Buildpacks list:
        Buildpacks stack:
 ```
@@ -248,6 +252,7 @@ dokku buildpacks:report node-js-app --buildpacks-list
 
 ### Displaying builder-herokuish reports for an app
 
+> [!IMPORTANT]
 > New as of 0.29.0
 
 You can get a report about the app's storage status using the `builder-herokuish:report` command:
@@ -301,7 +306,7 @@ false
 If an application was previously deployed via Dockerfile, the following commands should be run before a buildpack deploy will succeed:
 
 ```shell
-dokku config:unset --no-restart node-js-app DOKKU_PROXY_PORT_MAP
+dokku ports:clear node-js-app
 ```
 
 ### Using a specific buildpack version
@@ -322,31 +327,6 @@ This will use the latest commit on the `master` branch of the specified buildpac
 dokku buildpacks:set node-js-app https://github.com/heroku/heroku-buildpack-nodejs#v87
 ```
 
-### Specifying commands via Procfile
-
-While many buildpacks have a default command that is run when a detected repository is pushed, it is possible to override this command via a Procfile. A Procfile can also be used to specify multiple commands, each of which is subject to process scaling. See the [process scaling documentation](/docs/processes/process-management.md) for more details around scaling individual processes.
-
-A Procfile is a file named `Procfile`. It should be named `Procfile` exactly, and not anything else. For example, `Procfile.txt` is not valid. The file should be a simple text file.
-
-The file must be placed in the root directory of your application. It will not function if placed in a subdirectory.
-
-If the file exists, it should not be empty, as doing so may result in a failed deploy.
-
-The syntax for declaring a `Procfile` is as follows. Note that the format is one process type per line, with no duplicate process types.
-
-```
-<process type>: <command>
-```
-
-If, for example, you have multiple queue workers and wish to scale them separately, the following would be a valid way to work around the requirement of not duplicating process types:
-
-```Procfile
-worker:           env QUEUE=* bundle exec rake resque:work
-importantworker:  env QUEUE=important bundle exec rake resque:work
-```
-
-The `web` process type holds some significance in that it is the only process type that is automatically scaled to `1` on the initial application deploy. See the [process scaling documentation](/docs/processes/process-management.md) for more details around scaling individual processes.
-
 ### `curl` build timeouts
 
 Certain buildpacks may time out in retrieving dependencies via `curl`. This can happen when your network connection is poor or if there is significant network congestion. You may see a message similar to `gzip: stdin: unexpected end of file` after a `curl` command.
@@ -361,3 +341,7 @@ dokku config:set --global CURL_CONNECT_TIMEOUT=180
 ### Clearing buildpack cache
 
 See the [repository management documentation](/docs/advanced-usage/repository-management.md#clearing-app-cache) for more information on how to clear buildpack build cache for an application.
+
+### Specifying commands via Procfile
+
+See the [Procfile documentation](/docs/processes/process-management.md#procfile) for more information on how to specify different processes for your app.

docs/deployment/builders/lambda.md

@@ -1,5 +1,6 @@
 # Lambda Builder
 
+> [!IMPORTANT]
 > New as of 0.28.0
 
 ```
@@ -43,8 +44,10 @@ The `lambda` builder plugin delegates all build logic to [lambda-builder](https:
 
 When deploying a monorepo, it may be desirable to specify the specific path of the `lambda.yml` file to use for a given app. This can be done via the `builder-lambda:set` command. If a value is specified and that file does not exist in the app's build directory, then the build will fail.
 
+For deploys via the `git:from-image` and `git:load-image` commands, the `lambda.yml` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `lambda.yml` extracted directly from the source code. Both cases will respect the configured `lambdayml-path` property value.
+
 ```shell
-dokku builder-lambda:set node-js-app lambdayml-path lambda2.yml
+dokku builder-lambda:set node-js-app lambdayml-path .dokku/lambda.yml
 ```
 
 The default value may be set by passing an empty value for the option:

docs/deployment/builders/null.md

@@ -1,5 +1,6 @@
 # Null Builder
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 The `null` builder does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the [network documentation](/docs/networking/network.md#routing-an-app-to-a-known-ip:port-combination) for more information on the aforementioned use case.

docs/deployment/logs.md

@@ -43,7 +43,8 @@ The above command will show logs continually from the web process.
 
 ### Failed deploy logs
 
-> Warning: The default [docker-local scheduler](/docs/deployment/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.
+> [!WARNING]
+> The default [docker-local scheduler](/docs/deployment/schedulers/docker-local.md) will "store" these until the next deploy or until the old containers are garbage collected - whichever runs first. If you require the logs beyond this point in time, please ship the logs to a centralized log server.
 
 In some cases, it may be useful to retrieve the logs from a previously failed deploy.
 
@@ -89,13 +90,15 @@ dokku logs:set --global max-size
 
 ### Vector Logging Shipping
 
+> [!IMPORTANT]
 > New as of 0.22.6
 
 Vector is an open-source, lightweight and ultra-fast tool for building observability pipelines. Dokku integrates with it for shipping container logs for the `docker-local` scheduler. Users may configure log-shipping on a per-app or global basis, neither of which interfere with the `dokku logs` commands.
 
 #### Starting the Vector container
 
-> Warning: While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected.
+> [!WARNING]
+> While the default vector image may be updated over time, this will not impact running vector containers. Users are encouraged to view any Dokku and Vector changelogs to ensure their system will continue running as expected.
 
 Vector may be started via the `logs:vector-start` command.
 

docs/deployment/methods/git.md

@@ -1,5 +1,6 @@
 # Git Deployment
 
+> [!IMPORTANT]
 > Subcommands new as of 0.12.0
 
 ```
@@ -25,7 +26,8 @@ Git-based deployment has been the traditional method of deploying applications i
 
 ## Usage
 
-> Warning: Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process.
+> [!WARNING]
+> Pushing from a shallow clone is not currently supported and may have undefined behavior. Please unshallow your local repository before pushing to a Dokku app to avoid potential errors in the deployment process.
 
 ### Initializing an application
 
@@ -38,9 +40,10 @@ When an application is created via `git push`, Dokku will create the proper `pre
 dokku git:initialize node-js-app
 ```
 
-In order for the above command to succeed, the application _must_ already exist. 
+In order for the above command to succeed, the application _must_ already exist.
 
-> Warning: If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.
+> [!WARNING]
+> If the `pre-receive` hook was customized in any way, this will overwrite that hook with the current defaults for Dokku.
 
 ### Changing the deploy branch
 
@@ -72,6 +75,7 @@ Pushing multiple branches can also be supported by creating a [receive-branch](/
 
 ### Configuring the `GIT_REV` environment variable
 
+> [!IMPORTANT]
 > New as of 0.12.0
 
 Application deployments will include a special `GIT_REV` environment variable containing the current deployment sha being deployed. For rebuilds, this SHA will remain the same.
@@ -123,6 +127,7 @@ Please keep in mind that setting `keep-git-dir` to `true` may result in unstaged
 
 ### Initializing an app repository from a docker image
 
+> [!IMPORTANT]
 > New as of 0.24.0
 
 A Dokku app repository can be initialized or updated from a Docker image via the `git:from-image` command. This command will either initialize the app repository or update it to include the specified Docker image via a `FROM` stanza. This is an excellent way of tracking changes when deploying only a given docker image, especially if deploying an image from a remote CI/CD pipeline.
@@ -160,19 +165,6 @@ dokku git:from-image node-js-app dokku/node-js-getting-started:latest "Camila" "
 
 If the image is a private image that requires a docker login to access, the `registry:login` command should be used to log into the registry. See the [registry documentation](/docs/advanced-usage/registry-management.md#logging-into-a-registry) for more details on this process.
 
-Building an app from an image will result in the following files being extracted from the source image (with all custom paths specified for each file being respected):
-
-- `app.json`
-- `nginx.conf.sigil`
-- `Procfile`
-
-In the case where the repository is later modified to manually add any of the above files and deployed via `git push`, the files will still be extracted from the initial source image. To avoid this, please clear the `source-image` git property. It will be set back to the original source image on any subsequent `git:from-image` calls.
-
-```shell
-# sets an empty value
-dokku git:set node-js-app source-image
-```
-
 Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds.
 
 ```shell
@@ -183,6 +175,7 @@ See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to
 
 ### Initializing an app repository from an archive file
 
+> [!IMPORTANT]
 > New as of 0.24.0
 
 A Dokku app repository can be initialized or updated from the contents of an archive file via the `git:from-archive` command. This is an excellent way of tracking changes when deploying pre-built binary archives, such as java jars or go binaries. This can also be useful when deploying directly from a GitHub repository at a specific commit.
@@ -215,6 +208,7 @@ curl -sSL https://github.com/dokku/smoke-test-app/releases/download/2.0.0/smoke-
 
 ### Initializing an app repository from a remote image without a registry
 
+> [!IMPORTANT]
 > New as of 0.30.0
 
 A Dokku app repository can be initialized or updated from the contents of an image archive tar file  via the `git:load-image` command. This method can be used when a Docker Registry is unavailable to act as an intermediary for storing an image, such as when building an image in CI and deploying directly from that image.
@@ -248,19 +242,6 @@ The `git:load-image` command can optionally take a git `user.name` and `user.ema
 docker image save dokku/node-js-getting-started:latest | ssh dokku@dokku.me git:load-image node-js-app dokku/node-js-getting-started:latest "Camila" "camila@example.com"
 ```
 
-Building an app from an image will result in the following files being extracted from the source image (with all custom paths specified for each file being respected):
-
-- `app.json`
-- `nginx.conf.sigil`
-- `Procfile`
-
-In the case where the repository is later modified to manually add any of the above files and deployed via `git push`, the files will still be extracted from the initial source image. To avoid this, please clear the `source-image` git property. It will be set back to the original source image on any subsequent `git:load-image` calls.
-
-```shell
-# sets an empty value
-dokku git:set node-js-app source-image
-```
-
 Finally, certain images may require a custom build context in order for `ONBUILD ADD` and `ONBUILD COPY` statements to succeed. A custom build context can be specified via the `--build-dir` flag. All files in the specified `build-dir` will be copied into the repository for use within the `docker build` process. The build context _must_ be specified on each deploy, and is not otherwise persisted between builds.
 
 ```shell
@@ -271,6 +252,7 @@ See the [dockerfile documentation](/docs/deployment/builders/dockerfiles.md) to
 
 ### Initializing an app repository from a remote repository
 
+> [!IMPORTANT]
 > New as of 0.23.0
 
 A Dokku app repository can be initialized or updated from a remote git repository via the `git:sync` command. This command will either clone or fetch updates from a remote repository and has undefined behavior if the history cannot be fast-fowarded to the referenced repository reference. Any repository that can be cloned by the `dokku` user can be specified.
@@ -302,6 +284,7 @@ dokku git:sync --build node-js-app https://github.com/heroku/node-js-getting-sta
 
 ### Initializing from private repositories
 
+> [!IMPORTANT]
 > New as of 0.24.0
 
 Initializing from a private repository requires one of the following:

docs/deployment/remote-commands.md

@@ -91,7 +91,7 @@ In addition, the following commands have special local side-effects:
 
 #### Specifying a remote
 
-While many users will only ever push to a single dokku remote from a given repository, it may be useful to point the same repository at multiple remotes, especially in the case of pre-production environments. This can be done via the `remote` commands. These commands are _only_ available within the official remote client, and are not server-side commands.
+While many users will only ever push to a single dokku remote from a given repository, it may be useful to point the same repository at multiple remotes, especially in the case of pre-production environments. This can be done via the `remote` commands. These commands are *only* available within the official remote client, and are not server-side commands.
 
 To see your currently configured remote, run `dokku remote`. This will respect the `--remote` flag.
 
@@ -101,7 +101,7 @@ To add a remote, run `dokku remote:add $REMOTE_NAME dokku@dokku.me:$APP_NAME`, r
 
 To remove a remote, run `dokku remote:remove $REMOTE_NAME`. This is equivalent to running `git remote remove $REMOTE_NAME`.
 
-By default, the remote in use is `dokku`. To change the remote the client uses by default, run `dokku remote:set $REMOTE_NAME`, where `$REMOTE_NAME` is the name of your desired remote. This will not check the value specified, so that remote _must_ be available or errors will occur when running normal client commands. Note that specifying `--remote` when running dokku commands will override this configuration value.
+By default, the remote in use is `dokku`. To change the remote the client uses by default, run `dokku remote:set $REMOTE_NAME`, where `$REMOTE_NAME` is the name of your desired remote. This will not check the value specified, so that remote *must* be available or errors will occur when running normal client commands. Note that specifying `--remote` when running dokku commands will override this configuration value.
 
 To clear the configured remote, run `dokku remote:unset`. The client will unset the configured remote, and will default back to `dokku`, or the value of `--remote` if specified.
 

docs/deployment/schedulers/docker-local.md

@@ -1,5 +1,6 @@
 # Docker Local Scheduler
 
+> [!IMPORTANT]
 > Subcommands new as of 0.12.12
 
 ```
@@ -7,6 +8,7 @@ scheduler-docker-local:report [<app>] [<flag>]              # Displays a schedul
 scheduler-docker-local:set <app> <key> (<value>)            # Set or clear a scheduler-docker-local property for an app
 ```
 
+> [!IMPORTANT]
 > New as of 0.12.0
 
 Dokku natively includes functionality to manage application lifecycles for a single server using the `scheduler-docker-local` plugin. It is the default scheduler, but as with all schedulers, it is set on a per-application basis. The scheduler can currently be overridden by running the following command:
@@ -55,6 +57,7 @@ All image containers with the label `org.opencontainers.image.vendor=linuxserver
 
 ### Deploying Process Types in Parallel
 
+> [!IMPORTANT]
 > New as of 0.25.5
 
 By default, Dokku deploys an app's processes one-by-one in order, with the `web` process being deployed first. Deployment parallelism may be achieved by setting the `parallel-schedule-count` property, which defaults to `1`. Increasing this number increases the number of process types that may be deployed in parallel (with the web process being the exception).
@@ -78,19 +81,14 @@ Note that increasing the value of `parallel-schedule-count` may significantly im
 
 #### Increasing parallelism within a process deploy
 
+> [!IMPORTANT]
 > New as of 0.26.0
 
 By default, Dokku will deploy one instance of a given process type at a time. This can be increased by customizing the `app.json` `formation` key to include a `max_parallel` key for the given process type.
 
-An `app.json` file can be committed to the root of the pushed app repository, and must be within the built image artifact in the image's working directory as shown below.
-
-- Buildpacks: `/app/app.json`
-- Dockerfile: `WORKDIR/app.json` or `/app.json` (if no working directory specified)
-- Docker Image: `WORKDIR/app.json` or `/app.json` (if no working directory specified)
-
 The `formation` key should be specified as follows in the `app.json` file:
 
-```Procfile
+```json
 {
   "formation": {
     "web": {
@@ -107,6 +105,8 @@ Omitting or removing the entry will result in parallelism for that process type
 
 Note that increasing the value of `max_parallel` may significantly impact CPU utilization on your host as your app containers - and their respective processes - start up. Setting a value higher than the number of available CPUs is discouraged. It is recommended that users carefully set this value so as not to overburden their server.
 
+See the [app.json location documentation](/docs/advanced-usage/deployment-tasks.md#changing-the-appjson-location) for more information on where to place your `app.json` file.
+
 ## Scheduler Interface
 
 The following sections describe implemented scheduler functionality for the `docker-local` scheduler.
@@ -125,7 +125,6 @@ This plugin implements various functionality through `plugn` triggers to integra
 - `ps:stop`
 - `run`
 
-
 ### Logging support
 
 App logs for the `logs` command are fetched from running containers via the `docker` cli. To persist logs across deployments, consider using Dokku's [vector integration](/docs/deployment/logs.md#vector-logging-shipping) to ship logs to another service or a third-party platform.
@@ -137,15 +136,15 @@ The `docker-local` scheduler supports a minimal list of resource _limits_ and _r
 #### Resource Limits
 
 - cpu: (docker option: `--cpus`), is specified in number of CPUs a process can access.
-  - See the ["CPU" section](https://docs.docker.com/config/containers/resource_constraints/#cpu) of the Docker Runtime Options documentation for more information.
+    - See the ["CPU" section](https://docs.docker.com/config/containers/resource_constraints/#cpu) of the Docker Runtime Options documentation for more information.
 - memory: (docker option: `--memory`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes). Default unit is `m` (megabytes).
-  - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
+    - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
 - memory-swap: (docker option: `--memory-swap`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes)
-  - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
+    - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
 - nvidia-gpus: (docker option: `--gpus`), is specified in number of Nvidia GPUs a process can access.
-  - See the ["GPU" section](https://docs.docker.com/config/containers/resource_constraints/#gpu) of the Docker Runtime Options documentation for more information.
+    - See the ["GPU" section](https://docs.docker.com/config/containers/resource_constraints/#gpu) of the Docker Runtime Options documentation for more information.
 
 #### Resource Reservations
 
 - memory: (docker option: `--memory-reservation`) should be specified with a suffix of `b` (bytes), `k` (kilobytes), `m` (megabytes), `g` (gigabytes). Default unit is `m` (megabytes).
-  - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.
+    - See the ["Memory" section](https://docs.docker.com/config/containers/resource_constraints/#memory) of the Docker Runtime Options documentation for more information.

docs/deployment/schedulers/kubernetes.md

@@ -1,6 +1,7 @@
 # Kubernetes Scheduler
 
-> Warning: This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.
+> [!WARNING]
+> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.
 
 The [Kubernetes Scheduler Plugin](https://github.com/dokku/dokku-scheduler-kubernetes) is available free as an external plugin. Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-kubernetes/issues) for more information on the status of the plugin.
 

docs/deployment/schedulers/nomad.md

@@ -1,6 +1,7 @@
 # Nomad Scheduler
 
-> Warning: This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.
+> [!WARNING]
+> This scheduler is not in Dokku core and thus functionality may change over time as the API stabilizes.
 
 The [Nomad Scheduler Plugin](https://github.com/dokku/dokku-scheduler-nomad) is available free as an external plugin. Please see the plugin's [issue tracker](https://github.com/dokku/dokku-scheduler-nomad/issues) for more information on the status of the plugin.
 
@@ -20,4 +21,5 @@ This plugin implements various functionality through `plugn` triggers to integra
 
 ### Logging support
 
-> Warning: Fetching app logs for the `logs` command is currently not implemented. Please consider using [Vector](https://vector.dev/docs/setup/installation/platforms/kubernetes/) or a similar tool to ship logs to another service or a third-party platform.
+> [!WARNING]
+> Fetching app logs for the `logs` command is currently not implemented. Please consider using [Vector](https://vector.dev/docs/setup/installation/platforms/kubernetes/) or a similar tool to ship logs to another service or a third-party platform.

docs/deployment/schedulers/null.md

@@ -1,5 +1,6 @@
 # Null Scheduler
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 The `null` scheduler does nothing, and is useful for routing to services not managed by Dokku. It should not be used in normal operation. Please see the [network documentation](/docs/networking/network.md#routing-an-app-to-a-known-ip:port-combination) for more information on the aforementioned use case.

docs/deployment/schedulers/scheduler-management.md

@@ -1,5 +1,6 @@
 # Scheduler Management
 
+> [!IMPORTANT]
 > New as of 0.26.0
 
 ```
@@ -91,23 +92,23 @@ Custom plugins names _must_ have the prefix `scheduler-` or scheduler overriding
 At this time, the following dokku commands are used to implement a complete scheduler.
 
 - `apps:destroy`: stops the app processes on the scheduler
-  - triggers: post-delete, scheduler-register-retired, scheduler-retire
+    - triggers: post-delete, scheduler-register-retired, scheduler-retire
 - `apps:rename`: handles app renaming
-  - triggers: post-app-rename-setup
+    - triggers: post-app-rename-setup
 - `apps:clone`: handles app cloning
-  - triggers: post-app-clone-setup
+    - triggers: post-app-clone-setup
 - `deploy`: deploys app proceses and checks the status of a deploy
-  - triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed
+    - triggers: scheduler-app-status, scheduler-deploy, scheduler-is-deployed, scheduler-logs-failed
 - `enter`: enters a running container
-  - triggers: scheduler-enter
+    - triggers: scheduler-enter
 - `logs`: fetches app logs
-  - triggers: scheduler-logs
+    - triggers: scheduler-logs
 - `run`: starts one-off run containers (detached and non-detached) as well as listing run processes
-  - triggers: scheduler-run, scheduler-run-list
+    - triggers: scheduler-run, scheduler-run-list
 - `ps:stop`: stops app processes
-  - triggers: scheduler-stop
+    - triggers: scheduler-stop
 - `ps:inspect`: outputs inspect output for processes in an app
-  - triggers: scheduler-inspect
+    - triggers: scheduler-inspect
 
 Schedulers may decide to omit some functionality here, or use plugin triggers to supplement config with information from other plugins. Additionally, a scheduler may implement other triggers in order handle any extra processes needed during a deploy.
 

docs/deployment/user-management.md

@@ -1,5 +1,6 @@
 # User Management
 
+> [!IMPORTANT]
 > New as of 0.7.0
 
 ```
@@ -34,6 +35,7 @@ The output contains the following information:
 - The `KEY_NAME`.
 - A comma separated list of SSH options under the `SSHCOMMAND_ALLOWED_KEYS` name.
 
+> [!IMPORTANT]
 > New as of 0.20.2
 
 The keys for a specific user may be listed by specifying a second argument to the `ssh-keys:list` command:
@@ -42,6 +44,7 @@ The keys for a specific user may be listed by specifying a second argument to th
 dokku ssh-keys:list admin
 ```
 
+> [!IMPORTANT]
 > New as of 0.22.3
 
 The output format may be specified via the `--format` flag. Supported values include `json` and `text`.
@@ -58,7 +61,7 @@ dokku ssh-keys:list --format json admin
 
 ### Adding SSH keys
 
-You can add your public key to Dokku with the `ssh-keys:add` command. The output will be the fingerprint of the SSH key:
+You can add your public key to Dokku with the `ssh-keys:add` command. The path specified must contain your desired public ssh key contents and must exist on the server. Any special characters - such as `~` - are interpreted under the `dokku` user context. The output will be the fingerprint of the SSH key:
 
 ```shell
 dokku ssh-keys:add KEY_NAME path/to/id_rsa.pub
@@ -72,6 +75,24 @@ SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc
 
 > `KEY_NAME` is a unique name which is used to identify public keys. Attempting to re-use a key name will result in an error. The SSH (Git) user is *always* `dokku`, as this is the system user that the `dokku` binary uses to perform all its actions.
 
+Alternatively, you may pipe the contents of your ssh key via `cat` or `echo` into the `ssh-keys:add` command instead of specifying a path to the ssh key:
+
+```shell
+echo "$CONTENTS_OF_YOUR_PUBLIC_SSH_KEY_HERE" | dokku ssh-keys:add KEY_NAME
+```
+
+```
+SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc
+```
+
+```shell
+cat path/to/id_rsa.pub | dokku ssh-keys:add KEY_NAME
+```
+
+```
+SHA256:ABC123ABC123+abc123abc123Zabc123abcZ123abc
+```
+
 Admin users and root can add keys remotely by specifying the `dokku` bin on their `ssh` command:
 
 ```shell

docs/deployment/zero-downtime-deploys.md

@@ -1,5 +1,6 @@
 # Zero Downtime Deploy Checks
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
 ```
@@ -13,7 +14,7 @@ checks:skip <app> [process-type(s)]       Skip zero-downtime checks for all proc
 
 By default, Dokku will wait `10` seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by an application, traffic will be switched to point to your new containers. Dokku will also wait a further `60` seconds *after* the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application.
 
-You may both create user-defined checks for web processes using a `CHECKS` file, as well as customize any and all parts of this experience using the checks plugin.
+You may both create user-defined checks for web processes using the `healthchecks` key in the `app.json` file, as well as customize any and all parts of this experience using the checks plugin.
 
 > Web checks are performed via `curl` on Dokku host. Some application code - such
 > as the Django framework - checks for specific hostnames or header values, these
@@ -42,7 +43,7 @@ There are certain settings that can be configured via environment variables:
 - `DOKKU_DEFAULT_CHECKS_WAIT`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running.
 - `DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands *also* respect this value. If not specified, the Docker defaults for the [`docker stop` command](https://docs.docker.com/engine/reference/commandline/stop/) will be used.
 
-The following settings may also be specified in the `CHECKS` file, though are available as environment variables in order to ease application reuse.
+The following settings may also be specified in the `app.json` file, though are available as environment variables in order to ease application reuse.
 
 - `DOKKU_CHECKS_WAIT`: (default: `5`) Wait this many seconds for the container to start before running checks.
 - `DOKKU_CHECKS_TIMEOUT`: (default: `30`) Wait this many seconds for each response before marking it as a failure.
@@ -83,6 +84,7 @@ dokku checks:disable node-js-app worker
 
 ### Displaying checks reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the app's checks status using the `checks:report` command:
@@ -135,97 +137,47 @@ dokku checks:report node-js-app --checks-disabled-list
 
 ## Customizing checks
 
+> [!IMPORTANT]
+> New as of 0.31.0
+
 If your application needs a longer period to boot up - perhaps to load data into memory, or because of slow boot time - you may also use Dokku's `checks` functionality to more precisely check whether an application can serve traffic or not.
 
-Checks are run against the detected `web` process from your application's `Procfile`. For non-web processes, Dokku will fallback to the aforementioned process uptime check.
+Healthchecks are run against all process from your application's `Procfile`. When no healthcheck is defined, Dokku will fallback to a process uptime check.
 
-To specify checks, add a `CHECKS` file to the root of your project directory. The `CHECKS` file should be plain text and may contain:
+One or more healthchecks can be defined in the `app.json` file - see the [deployment task documentation](/docs/advanced-usage/deployment-tasks.md) for more information on how this is extracted - under the `healthchecks.web` path:
 
-- check instructions
-- settings (NAME=VALUE)
-- comments (lines starting with #)
-- empty lines
-
-> For Dockerfile and Docker Image based deploys, the file *must* be in the `WORKDIR` directory of the built image. `/app` is used by default as the root container directory for buildpack-based deploys.
-
-### Check instructions
-
-The format of a check instruction is a path or relative URL, optionally followed by the expected content:
-
-```
-/about  Our Amazing Team
+```json
+{
+  "healthchecks": {
+    "web": [
+        {
+            "type":        "startup",
+            "name":        "web check",
+            "description": "Checking if the app responds to the /health/ready endpoint",
+            "path":        "/health/ready",
+            "attempts": 3
+        }
+    ]
+}
 ```
 
-The `CHECKS` file can contain multiple checks:
+A healthcheck entry takes the following properties:
 
-```
-/                       My Amazing App
-/stylesheets/index.css  .body
-/scripts/index.js       $(function()
-/images/logo.png
-```
+- `attempts`: (default: `3` seconds) Number of retry attempts to perform on failure.
+- `command`: (default `''` - empty string) Command to execute within container.
+- `content`: (default: `''` - empty string) Content to search in http path check output.
+- `initialDelay`: (default: 0, unit: seconds) Number of seconds to wait after a container has started before triggering the healthcheck.
+- `name`: (default: autogenerated) The name of the healthcheck. If unspecified, it will be autogenerated from the rest of the healthcheck information.
+- `path`: (default: `/` - for http checks): An http path to check.
+- `timeout`: (default: `5` seconds): Number of seconds to wait before timing out a healthcheck.
+- `type`: (default: `""` - none): Type of the healthcheck. Options: liveness, readiness, startup.
+- `uptime`: (default: `""` - none): Amount of time the container must be alive before the container is considered healthy. Any restarts will cause this to check to fail, and this check does not respect retries.
+- `wait`: (default: `5` seconds): Number of seconds to wait between healthcheck attempts.
 
-To check an application that supports multiple hostnames, use relative URLs that include the hostname:
+> [!WARNING]
+> Healthchecks are implemented by specific scheduler plugins, and not all plugins support all options. Please consult the scheduler documentation for further details on what is supported.
 
-```
-//admin.dokku.me  Admin Dashboard
-//static.dokku.me/logo.png
-```
-
-You can also specify the protocol to explicitly check HTTPS requests:
-
-```
-https://admin.dokku.me  Admin Dashboard
-https://static.dokku.me/logo.png
-```
-
-While a full URL may be used in order to invoke checks, if you are using relative URLs, the port *must* be omitted.
-
-> Changed as of 0.22.5
-
-Please note that dollar sign bracket characters (`{` and `}`) must be escaped when used within a `CHECKS` file. Escaping follows golang template rules. The proper way to do this is via one of the following methods:
-
-```
-# escaping the `{` character
-# using double-quotes
-{{"{"}}
-
-# using raw string constants
-{{`{`}}
-
-# escaping the `}` character
-# using double-quotes
-{{"}"}}
-
-# using raw string constants
-{{`}`}}
-```
-
-### Templating Checks Files
-
-> New as of 0.22.5
-
-An app's `CHECKS` file is sent through a single pass of the [`sigil`](https://github.com/gliderlabs/sigil/) templating tool. This enables usage of Golang templating within application `CHECKS` files. In addition to general templating access, access to app environment variables is also allowed via the `var` function:
-
-```
-{{ var "SOME_ENV_VAR" }}
-```
-
-This may be useful if certain zero-downtime checks require access to an app-specific value, such as a domain name.
-
-### Check settings
-
-The default behavior is to wait for `5` seconds before running the checks, to timeout the checks after `30` seconds, and to attempt the checks `5` times. If the checks fail `5` times, the deployment is considered failed and the old container will continue serving traffic.
-
-You can change the default behavior by setting `WAIT`, `TIMEOUT`, and `ATTEMPTS` to different values in the `CHECKS` file:
-
-```
-WAIT=30     # Wait 1/2 minute
-TIMEOUT=60  # Timeout after a minute
-ATTEMPTS=10 # Attempt checks 10 times
-
-/  My Amazing App
-```
+See the [docker-container-healthchecker](https://github.com/dokku/docker-container-healthchecker) documentation for more details on how healthchecks are interpreted.
 
 ## Manually invoking checks
 
@@ -312,182 +264,3 @@ dokku checks:run node-js-app web.3
 -----> Running pre-flight checks
 Invalid container id specified (APP.web.3)
 ```
-
-## Example: Successful Rails deployment
-
-In this example, a Rails application is successfully deployed to Dokku. The initial round of checks fails while the server is starting, but once it starts they succeed and the deployment is successful. `WAIT` is set to `10` because our application takes a while to boot up. `ATTEMPTS` is set to `6`, but the third attempt succeeds.
-
-### Successful `CHECKS` file
-
-```
-WAIT=10
-ATTEMPTS=6
-/check.txt  simple_check
-```
-
-For this check to work, we've added a line to `config/routes.rb` that simply returns a string:
-
-```
-get '/check.txt', to: proc {[200, {}, ['simple_check']]}
-```
-
-### Successful deploy output
-
-> Note: The output has been trimmed for brevity.
-
-```shell
-git push dokku master
-```
-
-```
------> Cleaning up...
------> Building node-js-app from herokuish...
------> Adding BUILD_ENV to build environment...
------> Ruby app detected
------> Compiling Ruby/Rails
------> Using Ruby version: ruby-2.0.0
-
-.....
-
------> Discovering process types
-       Procfile declares types -> web
------> Releasing node-js-app...
------> Deploying node-js-app...
------> Running pre-flight checks
------> Attempt 1/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/check.txt => "simple_check"
- !
-curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
- !    Check attempt 1/6 failed.
------> Attempt 2/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/check.txt => "simple_check"
- !
-curl: (7) Failed to connect to 172.17.0.155 port 5000: Connection refused
- !    Check attempt 2/6 failed.
------> Attempt 3/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/check.txt => "simple_check"
------> All checks successful!
-=====> node-js-app container output:
-       => Booting Thin
-       => Rails 4.2.0 application starting in production on http://0.0.0.0:5000
-       => Run `rails server -h` for more startup options
-       => Ctrl-C to shutdown server
-       Thin web server (v1.6.3 codename Protein Powder)
-       Maximum connections set to 1024
-       Listening on 0.0.0.0:5000, CTRL+C to stop
-=====> end node-js-app container output
------> Running post-deploy
------> Configuring myapp.dokku.me...
------> Creating http nginx.conf
-       Reloading nginx
------> Shutting down old container in 60 seconds
-=====> Application deployed:
-       http://myapp.dokku.me
-```
-
-## Example: Failing Rails deployment
-
-In this example, a Rails application fails to deploy. The reason for the failure is that the PostgreSQL database connection fails. The initial checks will fail while we wait for the server to start up, just like in the above example. However, once the server does start accepting connections, we will see an error 500 due to the PostgreSQL database connection failure.
-
-Once the attempts have been exceeded, the deployment fails and we see the container output, which shows the PostgreSQL connection errors.
-
-### Failing `CHECKS` file
-
-```
-WAIT=10
-ATTEMPTS=6
-/
-```
-
-> The check to the root url `/` would normally access the database.
-
-### Failing deploy output
-
-> Note: The output has been trimmed for brevity.
-
-```shell
-git push dokku master
-```
-
-```
------> Cleaning up...
------> Building node-js-app from herokuish...
------> Adding BUILD_ENV to build environment...
------> Ruby app detected
------> Compiling Ruby/Rails
------> Using Ruby version: ruby-2.0.0
-
-.....
-
-Discovering process types
-Procfile declares types -> web
-Releasing node-js-app...
-Deploying node-js-app...
-Running pre-flight checks
------> Attempt 1/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/ => ""
- !
-curl: (7) Failed to connect to 172.17.0.188 port 5000: Connection refused
- !    Check attempt 1/6 failed.
------> Attempt 2/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/ => ""
- !
-curl: (7) Failed to connect to 172.17.0.188 port 5000: Connection refused
- !    Check attempt 2/6 failed.
------> Attempt 3/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/ => ""
- !
-curl: (22) The requested URL returned error: 500 Internal Server Error
- !    Check attempt 3/6 failed.
------> Attempt 4/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/ => ""
- !
-curl: (22) The requested URL returned error: 500 Internal Server Error
- !    Check attempt 4/6 failed.
------> Attempt 5/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/ => ""
- !
-curl: (22) The requested URL returned error: 500 Internal Server Error
- !    Check attempt 5/6 failed.
------> Attempt 6/6 Waiting for 10 seconds ...
-       CHECKS expected result:
-       http://localhost/ => ""
- !
-curl: (22) The requested URL returned error: 500 Internal Server Error
-Could not start due to 1 failed checks.
- !    Check attempt 6/6 failed.
-=====> node-js-app container output:
-       => Booting Thin
-       => Rails 4.2.0 application starting in production on http://0.0.0.0:5000
-       => Run `rails server -h` for more startup options
-       => Ctrl-C to shutdown server
-       Thin web server (v1.6.3 codename Protein Powder)
-       Maximum connections set to 1024
-       Listening on 0.0.0.0:5000, CTRL+C to stop
-       Started GET "/" for 172.17.42.1 at 2015-03-26 21:36:47 +0000
-         Is the server running on host "172.17.42.1" and accepting
-         TCP/IP connections on port 5431?
-       PG::ConnectionBad (could not connect to server: Connection refused
-         Is the server running on host "172.17.42.1" and accepting
-         TCP/IP connections on port 5431?
-       ):
-         vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `initialize'
-         vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `new'
-         vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:651:in `connect'
-         vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:242:in `initialize'
-         vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:44:in `new'
-         vendor/bundle/ruby/2.0.0/gems/activerecord-4.2.0/lib/active_record/connection_adapters/postgresql_adapter.rb:44:in `postgresql_connection
-=====> end node-js-app container output
-/usr/bin/dokku: line 49: 23409 Killed                  dokku deploy "$APP"
-To dokku@dokku.me:myapp
- ! [remote rejected] dokku -> master (pre-receive hook declined)
-error: failed to push some refs to 'dokku@dokku.me:myapp'
-```

docs/development/plugin-creation.md

@@ -103,7 +103,7 @@ if ! command -v "nginx" &>/dev/null; then
 fi
 
 # `which` example
-if ! which nginx >/dev/null 2>&1; then
+if ! which nginx &>/dev/null; then
   dokku_log_fail "Missing nginx, install it"
 fi
 ```
@@ -145,6 +145,7 @@ Any functions that must be kept private should reside in the plugin's `trigger/`
 
 ### Use helper functions to fetch app images
 
+> [!IMPORTANT]
 > New as of 0.4.0
 
 Dokku allows image tagging and deployment of tagged images. This means hard-coding the `$IMAGE` as `dokku/$APP` is no longer sufficient.
@@ -155,6 +156,7 @@ Plugins should use `get_running_image_tag()` and `get_app_image_name()` as sourc
 
 ### Use `$DOCKER_BIN` instead of `docker` directly
 
+> [!IMPORTANT]
 > New as of 0.17.5
 
 Certain systems may require a wrapper function around the `docker` binary for proper execution. Utilizing the `$DOCKER_BIN` environment variable when calling docker for those functions is preferred.
@@ -169,6 +171,7 @@ docker run -d $IMAGE /bin/bash -e -c "$COMMAND"
 
 ### Include labels for all temporary containers and images
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
 As of 0.5.0, labels are used to help cleanup intermediate containers with `dokku cleanup`. Plugins that create containers and images should add the correct labels to the `build`, `commit`, and `run` docker commands.
@@ -197,7 +200,7 @@ Avoid copying files from running containers as these files may change over time.
 source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
 
 local TMP_FILE=$(mktemp "/tmp/dokku-${DOKKU_PID}-${FUNCNAME[0]}.XXXXXX")
-trap "rm -rf '$TMP_FILE' >/dev/null" RETURN INT TERM
+trap "rm -rf '$TMP_FILE' >/dev/null" RETURN INT TERM EXIT
 
 local IMAGE_TAG="$(get_running_image_tag "$APP")"
 local IMAGE=$(get_deploying_app_image_name "$APP" "$IMAGE_TAG")
@@ -208,6 +211,7 @@ Files are copied from the `/app` directory - for images built via buildpacks - o
 
 ### Avoid calling the `dokku` binary directly
 
+> [!IMPORTANT]
 > New as of 0.6.0
 
 Plugins should **not** call the `dokku` binary directly from within plugins because clients using the `--app` argument are potentially broken when doing so.

docs/development/plugin-triggers.md

@@ -104,6 +104,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `app-json-get-content`
+
+- Description: Outputs the contents of the app-json file, if any
+- Invoked by: Deployment checks
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `app-maybe-create`
 
 - Description: Creates an app (gated by whether this is globally enabled or not)
@@ -237,6 +252,21 @@ APP="$1"; PROPERTY="$2"
 # TODO
 ```
 
+### `builder-herokuish-allowed`
+
+- Description: Checks if herokuish is allowed to run on non-amd64 hosts
+- Invoked by: unit tests
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `builder-image-is-cnb`
 
 - Description: Checks if an image is cnb-based
@@ -282,6 +312,36 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `buildpack-stack-name`
+
+- Description: Retrieves the configured buildpack stack for the pack and herokuish builders
+- Invoked by: builder-herokuish and builder-pack
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `caddy-template-source`
+
+- Description: Retrieves an alternative template for the caddy compose config
+- Invoked by: caddy-vhosts
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `certs-exists`
 
 - Description: Echos `true` if certs exists for the app, `false` otherwise
@@ -297,6 +357,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `certs-force`
+
+- Description: Echos `true` if a cert should be simulated for the app, no output otherwise
+- Invoked by:
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `check-deploy`
 
 - Description: Allows you to run checks on a deploy before Dokku allows the container to handle requests.
@@ -599,9 +674,25 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 echo 'derp.dkr.ecr.us-east-1.amazonaws.com'
 ```
 
+### `deploy-source-set`
+
+- Description: Used to set metadata about how the app is being deployed
+- Invoked by: `git:from-archive`, `git:from-image`, `git:load-image`, `git:sync`, and all git push commands
+- Arguments: `$APP $SOURCE_TYPE $METADATA`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `docker-args-build`
 
-> Warning: Deprecated, please use `docker-args-process-build` instead
+> [!WARNING]
+> Deprecated, please use `docker-args-process-build` instead
 
 - Description:
 - Invoked by: `internal function dokku_build() (build phase)`
@@ -626,7 +717,8 @@ echo -n "$STDIN$output"
 
 ### `docker-args-deploy`
 
-> Warning: Deprecated, please use `docker-args-process-deploy` instead
+> [!WARNING]
+> Deprecated, please use `docker-args-process-deploy` instead
 
 - Description:
 - Invoked by: `dokku deploy`
@@ -697,7 +789,8 @@ APP="$1"; IMAGE_SOURCE_TYPE="$3"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $AP
 
 ### `docker-args-run`
 
-> Warning: Deprecated, please use `docker-args-process-run` instead
+> [!WARNING]
+> Deprecated, please use `docker-args-process-run` instead
 
 - Description:
 - Invoked by: `dokku run`
@@ -924,7 +1017,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
-> Warning: The `git-pre-pull` trigger should _not_ be used for authentication since it does not get called for commands that use `git-upload-archive` such as `git archive`. Instead, use the [`user-auth`](#user-auth) trigger.
+> [!WARNING]
+> The `git-pre-pull` trigger should _not_ be used for authentication since it does not get called for commands that use `git-upload-archive` such as `git archive`. Instead, use the [`user-auth`](#user-auth) trigger.
 
 ### `git-revision`
 
@@ -960,6 +1054,21 @@ if [[ ! -f  "$DOKKU_ROOT/VHOST" ]]; then
 fi
 ```
 
+### `haproxy-template-source`
+
+- Description: Retrieves an alternative template for the haproxy compose config
+- Invoked by: haproxy-vhosts
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `logs-get-property`
 
 - Description: Return the value for an app's log property
@@ -1006,21 +1115,6 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
-### `network-compute-ports`
-
-- Description: Computes the ports for a given app container
-- Invoked by: `internally triggered by proxy-build-config within proxy implementations`
-- Arguments: `$APP $PROC_TYPE $IS_HEROKUISH_CONTAINER $CONTAINER_INDEX`
-- Example:
-
-```shell
-#!/usr/bin/env bash
-
-set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
-
-# TODO
-```
-
 ### `network-config-exists`
 
 - Description: Returns whether the network configuration for a given app exists
@@ -1066,21 +1160,6 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
-### `network-get-port`
-
-- Description: Return the port for a given app container
-- Invoked by: `internally triggered by a deploy`
-- Arguments: `$APP $PROCESS_TYPE $CONTAINER_ID $IS_HEROKUISH_CONTAINER`
-- Example:
-
-```shell
-#!/usr/bin/env bash
-
-set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
-
-# TODO
-```
-
 ### `network-get-property`
 
 - Description: Return the value for an app's network property
@@ -1146,7 +1225,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 - Description: Return the path to a `sigil` template that should be used to generate a given nginx configuration file.
 - Invoked by: `nginx-vhosts#build-config`
 - Arguments: `$APP $TEMPLATE_TYPE`
-  - The `TEMPLATE_TYPE` argument can be one of: `[app-config, hsts-config, validate-config]`
+    - The `TEMPLATE_TYPE` argument can be one of: `[app-config, hsts-config, validate-config]`
 - Example:
 
 ```shell
@@ -1209,7 +1288,8 @@ echo "$NEW_SUBDOMAIN.$VHOST"
 
 ### `nginx-pre-reload`
 
-> Warning: The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run `plugn trigger network-get-listeners APP` within any implementation of `nginx-pre-reload` in order to retrieve all application listeners.
+> [!WARNING]
+> The arguments INTERNAL_PORT and INTERNAL_IP_ADDRESS are no longer sufficient to retrieve all app listeners. Please run `plugn trigger network-get-listeners APP` within any implementation of `nginx-pre-reload` in order to retrieve all application listeners.
 
 - Description: Run before nginx reloads hosts
 - Invoked by: `dokku proxy:build-config`
@@ -1226,6 +1306,112 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 nginx -t
 ```
 
+### `openresty-template-source`
+
+- Description: Retrieves an alternative template for the openresty compose config
+- Invoked by: openresty-vhosts
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `ports-clear`
+
+- Description: Clears the ports for a given app without triggering further restarts or rebuilds
+- Invoked by: internally
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `ports-configure`
+
+- Description: Configures the initial proxy ports
+- Invoked by: `internally triggered by proxy plugins`
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `ports-get`
+
+- Description: Returns a list of port mappings, newline delimited
+- Invoked by: Various networking plugins
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `ports-get-available`
+
+- Description: Prints out an available port greater than 1024
+- Invoked by: Various networking plugins
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
+### `ports-get-property`
+
+- Description: Return the value for an app's ports property
+- Invoked by:
+- Arguments: `$APP $KEY`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+APP="$1"; PROPERTY="$2"
+
+# TODO
+```
+
+### `ports-set-detected`
+
+- Description: Allows builders to specify detected port mappings for a given app
+- Invoked by: Builder plugins
+- Arguments: `$APP [$PORT_MAPPING...]`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `post-app-clone`
 
 - Description: Allows you to run commands after an app was cloned.
@@ -1304,7 +1490,8 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 ### `post-build-pack`
 
-> Warning: The pack plugin trigger apis are under development and may change
+> [!WARNING]
+> The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using pack.
@@ -1335,6 +1522,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `post-build-lambda`
+
+- Description: Allows you to run commands after the build image is create for a given app. Only applies to apps using lambda.
+- Invoked by: `internal function dokku_build() (build phase)`
+- Arguments: `$APP` `$SOURCECODE_WORK_DIR`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `post-certs-remove`
 
 - Description: Allows you to run commands after a cert is removed
@@ -1371,7 +1573,7 @@ APP="$1"
 
 ### `post-config-update`
 
-- Description: Allows you to get notified when one or more configs is added or removed. Action can be `set` or `unset`. 
+- Description: Allows you to get notified when one or more configs is added or removed. Action can be `set` or `unset`.
 - Invoked by: `dokku config:set`, `dokku config:unset`
 - Arguments: `$APP` `set|unset` `key1=VALUE1 key2=VALUE2`
 - Example:
@@ -1388,7 +1590,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 - Description: This trigger should be used to do stuff to containers after they are created but before they are started. They are explicitely for commands that may involve network traffic, and _not_ for commands that are self-contained, such as chown or tar.
 - Invoked by: `dokku run`, `dokku ps:rebuild`, `dokku deploy`
-- Arguments "app|service" "$CONTAINER_ID" "$APP|$SERVICE" "$PHASE"
+- Arguments: "app|service" "$CONTAINER_ID" "$APP|$SERVICE" "$PHASE"
 
 ```shell
 #!/usr/bin/env bash
@@ -1498,8 +1700,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:
 
@@ -1518,7 +1720,8 @@ haproxy-build-config "$APP"
 
 ### `post-release-builder`
 
-> Warning: Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.
+> [!WARNING]
+> Image mutation in this trigger may result in an invalid run state, and is heavily discouraged.
 
 - Description: Invokes a command after the build process is complete.
 - Invoked by: builder plugins
@@ -1535,6 +1738,21 @@ BUILDER_TYPE="$1"; APP="$2"; IMAGE=$3
 # TODO
 ```
 
+### `post-stack-set` TODO
+
+- Description: Allows you to run commands after changing the stack
+- Invoked by: buildpacks plugin
+- Arguments: `$APP` `$VALUE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `post-stop`
 
 - Description: Can be used to run commands after an app is manually stopped
@@ -1568,9 +1786,25 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `pre-build-lambda`
+
+- Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using lambda.
+- Invoked by: `internal function dokku_build() (build phase)`
+- Arguments: `$APP` `$SOURCECODE_WORK_DIR`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `pre-build-pack`
 
-> Warning: The pack plugin trigger apis are under development and may change
+> [!WARNING]
+> The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run commands before the build image is created for a given app. For instance, this can be useful to add env vars to your container. Only applies to apps using pack.
@@ -1715,7 +1949,7 @@ APP="$1"; IMAGE_TAG="$2"; IMAGE=$(get_app_image_name $APP $IMAGE_TAG)
 dokku_log_info1 "Installing GraphicsMagick..."
 
 CMD="cat > gm && \
-  dpkg -s graphicsmagick >/dev/null 2>&1 || \
+  dpkg -s graphicsmagick &>/dev/null || \
   (apt-get update -qq && apt-get -qq -y --no-install-recommends install graphicsmagick && apt-get clean)"
 
 CID=$(docker run $DOKKU_GLOBAL_RUN_ARGS -i -a stdin $IMAGE /bin/bash -c "$CMD")
@@ -1724,9 +1958,27 @@ DOCKER_COMMIT_LABEL_ARGS=("--change" "LABEL org.label-schema.schema-version=1.0"
 docker commit "${DOCKER_COMMIT_LABEL_ARGS[@]}" $CID $IMAGE >/dev/null
 ```
 
+### `pre-release-lambda`
+
+- Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using lambda.
+- Invoked by: `internal function dokku_release() (release phase)`
+- Arguments: `$APP $IMAGE_TAG`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions"
+APP="$1"; IMAGE_TAG="$2";
+
+# TODO
+```
+
 ### `pre-release-pack`
 
-> Warning: The pack plugin trigger apis are under development and may change
+> [!WARNING]
+> The pack plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run commands before environment variables are set for the release step of the deploy. Only applies to apps using pack.
@@ -1810,6 +2062,21 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 # TODO
 ```
 
+### `procfile-exists`
+
+- Description: Checks if a procfile exists for the specified app
+- Invoked by: `internally`
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `proxy-build-config`
 
 - Description: Builds the proxy implementation configuration for a given app
@@ -1842,7 +2109,10 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 ### `proxy-configure-ports`
 
-- Description: Configures the proxy port mapping
+> [!WARNING]
+> Deprecated, please use `ports-configure` instead
+
+- Description: Configures the port mapping
 - Invoked by: `internally triggered by proxy plugins`
 - Arguments: `$APP`
 - Example:
@@ -1929,6 +2199,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
 
 # TODO
 ```
+
 ### `ps-current-scale`
 
 - Description: Prints out the current scale contents (process-type=quantity) delimited by newlines.
@@ -2068,7 +2339,8 @@ mail -s "$APP containers on $HOSTNAME failed to retire" ops@dokku.me
 
 ### `scheduler-app-status`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Fetch the status of an app
@@ -2087,7 +2359,8 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 
 ### `scheduler-deploy`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run scheduler commands when an app is deployed
@@ -2106,7 +2379,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3";
 
 ### `scheduler-detect`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to check which scheduler is in use for an app
@@ -2125,7 +2399,8 @@ APP="$1"
 
 ### `scheduler-enter`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to enter a running container for a given app
@@ -2144,7 +2419,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="$@"
 
 ### `scheduler-inspect`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run inspect commands for all containers for a given app
@@ -2161,11 +2437,31 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 # TODO
 ```
 
-### `scheduler-logs`
+### `scheduler-is-deployed`
 
 > Warning: The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
+- Description: Allows you to check if the scheduler has deployed the app
+- Invoked by: Various plugins
+- Arguments: `$DOKKU_SCHEDULER $APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+DOKKU_SCHEDULER="$1"; APP="$2";
+
+# TODO
+```
+
+### `scheduler-logs`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
 - Description: Allows you to run scheduler commands when retrieving container logs
 - Invoked by: `dokku logs:failed`
 - Arguments: `$DOKKU_SCHEDULER $APP $PROCESS_TYPE $TAIL $PRETTY_PRINT $NUM`
@@ -2182,7 +2478,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; PROCESS_TYPE="$3"; TAIL="$4"; PRETTY_PRINT="$5";
 
 ### `scheduler-logs-failed`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run scheduler commands when retrieving failed container logs
@@ -2201,7 +2498,8 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 
 ### `scheduler-pre-restore`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run commands before an app is restored
@@ -2220,7 +2518,8 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 
 ### `scheduler-post-delete`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run scheduler commands when an app is deleted
@@ -2237,11 +2536,31 @@ DOKKU_SCHEDULER="$1"; APP="$2"; IMAGE_TAG="$3";
 # TODO
 ```
 
-### `scheduler-post-run`
+### `scheduler-post-deploy-process`
 
 > Warning: The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
+- Description: Allows you to run a command after a process has been started
+- Invoked by: scheduler-docker-local
+- Arguments: `$APP $PROCESS_TYPE`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+APP="$1"; PROCESS_TYPE="$2";
+
+# TODO
+```
+
+### `scheduler-post-run`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
 - Description: Allows you to run scheduler commands after a `dokku run` invocation is called
 - Invoked by: `dokku run`
 - Arguments: `$DOKKU_SCHEDULER $APP $CONTAINER_ID`
@@ -2258,7 +2577,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER_ID="$3";
 
 ### `scheduler-register-retired`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows scheduling retiring a local container and any related images
@@ -2278,7 +2598,8 @@ CONTAINER_ID="$2";
 
 ### `scheduler-retire`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run scheduler commands when containers should be force retired from the system
@@ -2297,7 +2618,8 @@ DOKKU_SCHEDULER="$1"; APP="$2";
 
 ### `scheduler-run`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run scheduler commands when a command is executed for your app
@@ -2316,7 +2638,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; ARGS="${@:3}";
 
 ### `scheduler-run-list`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Lists all run containers for a given app
@@ -2335,7 +2658,8 @@ DOKKU_SCHEDULER="$1"; APP="$2"; FORMAT="$3";
 
 ### `scheduler-run-logs`
 
-> Warning: The scheduler plugin trigger apis are under development and may change
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
 - Description: Allows you to run scheduler commands when retrieving one-off container logs
@@ -2352,11 +2676,31 @@ DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER="$3"; TAIL="$4"; PRETTY_PRINT="$5"; NU
 # TODO
 ```
 
-### `scheduler-stop`
+### `scheduler-run-stop`
 
 > Warning: The scheduler plugin trigger apis are under development and may change
 > between minor releases until the 1.0 release.
 
+- Description: Allows a scheduler to stop all "run" containers or a specified container
+- Invoked by: `dokku run:stop`
+- Arguments: `$DOKKU_SCHEDULER $APP $CONTAINER_NAME`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+DOKKU_SCHEDULER="$1"; APP="$2"; CONTAINER_NAME="$3";
+
+# TODO
+```
+
+### `scheduler-stop`
+
+> [!WARNING]
+> The scheduler plugin trigger apis are under development and may change
+> between minor releases until the 1.0 release.
+
 - Description: Allows you to run scheduler commands when a tag is destroyed
 - Invoked by: `dokku apps:destroy, dokku ps:stop`
 - Arguments: `$DOKKU_SCHEDULER $APP $REMOVE_CONTAINERS`
@@ -2387,6 +2731,21 @@ APP="$1"
 # TODO
 ```
 
+### `traefik-template-source`
+
+- Description: Retrieves an alternative template for the traefik compose config
+- Invoked by: traefik-vhosts
+- Arguments: `$APP`
+- Example:
+
+```shell
+#!/usr/bin/env bash
+
+set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x
+
+# TODO
+```
+
 ### `uninstall`
 
 - Description: Used to cleanup after itself.

docs/development/release-process.md

@@ -29,7 +29,7 @@ The workflow looks like this:
 ```shell
 # having dokku-arch in ../dokku-arch
 vagrant up build-arch
-# wait for "==> build-arch: ==> Finished making: dokku 0.30.2-2 (Mon Feb 22 23:20:37 CET 2016)"
+# wait for "==> build-arch: ==> Finished making: dokku 0.31.2-2 (Mon Feb 22 23:20:37 CET 2016)"
 cd ../dokku-arch
 git add PKGBUILD .SRCINFO
 git commit -m 'Update to dokku 0.9.9'

docs/enterprise/pro.md

@@ -29,4 +29,4 @@ Dokku Pro has the following functionality:
 - Authenticated HTTP(S) endpoints for git push functionality
 - Single Page App (SPA) Web UI exposing app, datastore, and ssh key management
 
-While each release is fairly feature complete, individual features and documentation will expand over time. Feature development follows a monthly release cadence, with individual bug fixes released on an as needed basis. 
+While each release is fairly feature complete, individual features and documentation will expand over time. Feature development follows a monthly release cadence, with individual bug fixes released on an as needed basis.

docs/getting-started/advanced-installation.md

@@ -22,7 +22,7 @@ You can always install Dokku straight from the latest - potentially unstable - `
 
 ```shell
 # using a branch results in installing from source
-wget https://dokku.com/install/master/bootstrap.sh;
+wget -NP . https://dokku.com/install/master/bootstrap.sh;
 sudo DOKKU_BRANCH=master bash bootstrap.sh
 ```
 
@@ -47,7 +47,7 @@ sudo SSHCOMMAND_URL=https://raw.githubusercontent.com/yourusername/sshcommand/ma
 The bootstrap script allows the Dokku repository URL to be overridden to bootstrap a host from your own clone of Dokku using the `DOKKU_REPO` environment variable. Example:
 
 ```shell
-wget https://dokku.com/install/master/bootstrap.sh;
+wget -NP . https://dokku.com/install/master/bootstrap.sh;
 chmod +x bootstrap.sh
 sudo DOKKU_REPO=https://github.com/yourusername/dokku.git DOKKU_BRANCH=master ./bootstrap.sh
 ```
@@ -78,7 +78,7 @@ Follow the [user management documentation](/docs/deployment/user-management.md)
 
 ## VMs with less than 1 GB of memory
 
-Having less than 1 GB of system memory available for Dokku and its containers may result in unexpected errors, such as `! [remote rejected] master -> master (pre-receive hook declined)` during installation of NPM dependencies (https://github.com/npm/npm/issues/3867).
+Having less than 1 GB of system memory available for Dokku and its containers may result in unexpected errors, such as `! [remote rejected] master -> master (pre-receive hook declined)` [during installation of NPM dependencies](https://github.com/npm/npm/issues/3867).
 
 To work around this issue, it might suffice to augment the Linux swap file size to a maximum of twice the physical memory size.
 

docs/getting-started/install/docker.md

@@ -3,7 +3,7 @@
 Pull the dokku/dokku image:
 
 ```shell
-docker pull dokku/dokku:0.30.2
+docker pull dokku/dokku:0.31.2
 ```
 
 Next, run the image.
@@ -19,7 +19,7 @@ docker container run \
   --publish 8443:443 \
   --volume /var/lib/dokku:/mnt/dokku \
   --volume /var/run/docker.sock:/var/run/docker.sock \
-  dokku/dokku:0.30.2
+  dokku/dokku:0.31.2
 ```
 
 The above command will start a new docker container that is ready when a message similar to `Runit started as PID 12345` appears.
@@ -61,7 +61,7 @@ redis: https://github.com/dokku/dokku-redis.git
 The alternative is to build a custom docker image via a custom Dockerfile. This Dockerfile can run any `plugin:install` command. Note that the version installed at that time will be the one that persists. Below is an example Dockerfile showing this method.
 
 ```Dockerfile
-FROM dokku/dokku:0.30.2
+FROM dokku/dokku:0.31.2
 RUN dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
 RUN dokku plugin:install https://github.com/dokku/dokku-redis.git redis
 ```

docs/getting-started/install/vagrant.md

@@ -36,7 +36,7 @@
         Port 22
     ```
 
-    > For users that have customized the IP address of their VM - either in a custom `Vagrantfile` or via the `DOKKU_IP` environment variable - and are not using `10.0.0.2` for the Vagrant IP, you'll need to instead use the output of `vagrant ssh-config dokku` for your `~/.ssh/config` entry. 
+    > For users that have customized the IP address of their VM - either in a custom `Vagrantfile` or via the `DOKKU_IP` environment variable - and are not using `10.0.0.2` for the Vagrant IP, you'll need to instead use the output of `vagrant ssh-config dokku` for your `~/.ssh/config` entry.
 
 6. Connect to the server via `vagrant ssh` and add your ssh key to the install. Additionally, set the global domain name to `dokku.me`.
 

docs/getting-started/installation/index.md

@@ -1,10 +1,10 @@
 # Getting Started with Dokku
 
-### What is Dokku?
+## What is Dokku?
 
 Dokku is an extensible, open source Platform as a Service that runs on a single server of your choice. Dokku supports building apps on the fly from a `git push` via either Dockerfile or by auto-detecting the language with Buildpacks, and then starts containers based on your built image. Using technologies such as nginx and cron, Web processes are automatically routed to, while background processes and automated cron tasks are also managed by Dokku.
 
-### System Requirements
+## System Requirements
 
 To start using Dokku, you'll need a system that meets the following minimum requirements:
 
@@ -12,7 +12,7 @@ To start using Dokku, you'll need a system that meets the following minimum requ
     - [Ubuntu 20.04/22.04](https://www.ubuntu.com/download)
     - [Debian 10+ x64](https://www.debian.org/distrib/)
 - A server with one of the following architectures
-    - AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers 
+    - AMD64 (alternatively known as `x86_64`), commonly used for Intel cloud servers
     - ARMV7 (alternatively known as `armhf`), commonly used for Raspberry PI
     - ARMV8 (alternatively known as `arm64`), commonly used for Raspberry PI and AWS Graviton
 
@@ -28,23 +28,23 @@ Finally, we recommend attaching at least one domain name to your server. This is
 
 Please see the [dns documentation](/docs/networking/dns.md) and [domains documentation](/docs/configuration/domains.md) for more details.
 
-### Installing the latest stable version
+## Installing the latest stable version
 
-This is the simple method of installing Dokku. For alternative methods of installation, see the [advanced install guide](/docs/getting-started/advanced-installation.md#configuring). 
+This is the simple method of installing Dokku. For alternative methods of installation, see the [advanced install guide](/docs/getting-started/advanced-installation.md#configuring).
 
-#### 1. Install Dokku
+### 1. Install Dokku
 
 To install the latest stable version of Dokku, you can run the following shell commands:
 
 ```shell
 # for debian systems, installs Dokku via apt-get
-wget https://dokku.com/install/v0.30.2/bootstrap.sh
-sudo DOKKU_TAG=v0.30.2 bash bootstrap.sh
+wget -NP . https://dokku.com/install/v0.31.2/bootstrap.sh
+sudo DOKKU_TAG=v0.31.2 bash bootstrap.sh
 ```
 
 The installation process takes about 5-10 minutes, depending upon internet connection speed.
 
-#### 2. Setup SSH key and Virtualhost Settings
+### 2. Setup SSH key and Virtualhost Settings
 
 Once the installation is complete, you should configure an ssh key and set your global domain.
 
@@ -67,6 +67,6 @@ dokku domains:set-global 10.0.0.2.sslip.io
 
 See the [user management](/docs/deployment/user-management.md#adding-ssh-keys) and [domains documentation](/docs/configuration/domains.md#customizing-hostnames) for more information.
 
-#### 3. Deploy your first application
+### 3. Deploy your first application
 
 At this point, you should be able to [deploy to the Dokku installation](/docs/deployment/application-deployment.md).

docs/getting-started/troubleshooting.md

@@ -1,5 +1,6 @@
 # Troubleshooting
 
+> [!IMPORTANT]
 > New as of 0.17.0
 
 ```
@@ -33,7 +34,7 @@ dokku trace:off
 
 ## Common Problems
 
-### I deployed my app but I am getting the default nginx page.
+### I deployed my app but I am getting the default nginx page
 
 Most of the time it's caused by some defaults newer versions of nginx set. To make sure that's the issue you're having run the following:
 
@@ -58,10 +59,8 @@ A value of 64 would allow domains with up to 64 characters. Set it to 128 if you
 Save the file and try stopping nginx and starting it again:
 
 ```shell
-/etc/init.d/nginx stop
-## * Stopping nginx nginx                                        [ OK ]
-/etc/init.d/nginx start
-## * Starting nginx nginx                                        [ OK ]
+dokku nginx:stop
+dokku nginx:start
 ```
 
 ---
@@ -74,12 +73,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.
 
@@ -93,7 +92,7 @@ The following error may be emitted from a deploy:
 
 The `remote rejected` error does not give enough information. Anything could have failed. Enable trace mode and begin debugging. If this does not help you, create a [gist](https://gist.github.com) containing the full log, and create an issue.
 
-One the reasons why you may get this error is because the command that is run in the container exited (without errors). For example, (in Procfile) when you define a new worker container to run Delayed Job and use the bin/delayed_job start command. This command deamonizes the process and exists. The container thinks it's done so it closes itself. The error you get is the one above. To fix the above problem for Delayed Job, you must define the worker to user rake jobs:work, which doesn't deamonize the process. 
+One the reasons why you may get this error is because the command that is run in the container exited (without errors). For example, (in Procfile) when you define a new worker container to run Delayed Job and use the bin/delayed_job start command. This command deamonizes the process and exists. The container thinks it's done so it closes itself. The error you get is the one above. To fix the above problem for Delayed Job, you must define the worker to user rake jobs:work, which doesn't deamonize the process.
 
 ### I get the aforementioned error in the build phase (after turning on Dokku tracing)
 
@@ -123,7 +122,7 @@ Sometimes (especially on DigitalOcean) deploying again seems to get past these s
 resolvconf -u
 ```
 
-Please see https://github.com/dokku/dokku/issues/841 and https://github.com/dokku/dokku/issues/649.
+Please see [#841](https://github.com/dokku/dokku/issues/841) and [#649](https://github.com/dokku/dokku/issues/649).
 
 ### After adding an SSH key, I am told I cannot read from the remote repository on push
 
@@ -157,7 +156,7 @@ Host DOKKU_HOSTNAME
 
 Also see [issue #116](https://github.com/dokku/dokku/issues/116).
 
-### I successfully deployed my application with no deployment errors and receiving **Bad Gateway** when attempting to access the application.
+### I successfully deployed my application with no deployment errors and receiving **Bad Gateway** when attempting to access the application
 
 In many cases the application will require the a `process.env.PORT` port opposed to a specified port.
 
@@ -167,9 +166,13 @@ When specifying your port you may want to use something similar to:
 var port = process.env.PORT || 3000
 ```
 
-Please see https://github.com/dokku/dokku/issues/282.
+Please see [#282](https://github.com/dokku/dokku/issues/282).
 
-### Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file`.
+Additionally, your application should listen/bind to all interfaces (`0.0.0.0`). Many frameworks default to listening on `127.0.0.1`.
+
+Please see [#5798](https://github.com/dokku/dokku/issues/5798).
+
+### Deployment fails because of slow internet connection, messages shows `gzip: stdin: unexpected end of file`
 
 If you see output similar this when deploying:
 
@@ -189,11 +192,11 @@ dokku config:set --global CURL_TIMEOUT=1200
 dokku config:set --global CURL_CONNECT_TIMEOUT=180
 ```
 
-Please see https://github.com/dokku/dokku/issues/509.
+Please see [#509](https://github.com/dokku/dokku/issues/509).
 
 Another reason for this error (although it may respond immediately ruling out a timeout issue) may be because you've set the config setting `SSL_CERT_FILE`. Using a config setting with this key interferes with the buildpack's ability to download its dependencies, so you must rename the config setting to something else, e.g. `MY_APP_SSL_CERT_FILE`.
 
-### Build fails with `Killed` message.
+### Build fails with `Killed` message
 
 This generally occurs when the server runs out of memory. You can either add more RAM to your server or setup swap space. The follow script will create 2 GB of swap space.
 
@@ -207,7 +210,7 @@ sudo sysctl -w vm.swappiness=10
 echo vm.swappiness = 10 | sudo tee -a /etc/sysctl.conf
 ```
 
-### I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application.
+### I successfully deployed my application with no deployment errors but I'm receiving Connection Timeout when attempting to access the application
 
 This can occur if Dokku is running on a system with a firewall like UFW enabled (some OS versions like Ubuntu have this enabled by default). You can check if this is your case by running the following script:
 
@@ -221,7 +224,7 @@ If the previous script returned `Status: active` and a list of ports, UFW is ena
 sudo ufw disable
 ```
 
-### I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection.
+### I can't connect to my application because the server is sending an invalid response, or can't provide a secure connection
 
 This isn't usually an issue with Dokku, but rather an app config problem. This can happen when your application is configured to enforce secure connections/HSTS, but you don't have SSL set up for the app.
 
@@ -231,16 +234,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
 

docs/getting-started/upgrading/index.md

@@ -18,6 +18,7 @@ Docker releases updates periodically to their engine. We recommend reading their
 
 Before upgrading, check the migration guides to get comfortable with new features and prepare your deployment to be upgraded.
 
+- [Upgrading to 0.31](/docs/appendices/0.31.0-migration-guide.md)
 - [Upgrading to 0.30](/docs/appendices/0.30.0-migration-guide.md)
 - [Upgrading to 0.29](/docs/appendices/0.29.0-migration-guide.md)
 - [Upgrading to 0.28](/docs/appendices/0.28.0-migration-guide.md)
@@ -61,7 +62,7 @@ dokku ps:stopall
 # for versions between 0.8.1 and 0.11.3, use
 dokku --quiet apps:list | xargs -L1 dokku ps:stop
 
-# for versions versions older than 0.8.1, use
+# for versions older than 0.8.1, use
 dokku --quiet apps | xargs -L1 dokku ps:stop
 ```
 

docs/home.html

@@ -10,26 +10,26 @@
     <meta name="author" content="">
     <title>Dokku - The smallest PaaS implementation you've ever seen</title>
 
-    <link rel="apple-touch-icon" sizes="57x57" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-57x57.png">
-    <link rel="apple-touch-icon" sizes="60x60" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-60x60.png">
-    <link rel="apple-touch-icon" sizes="72x72" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-72x72.png">
-    <link rel="apple-touch-icon" sizes="76x76" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-76x76.png">
-    <link rel="apple-touch-icon" sizes="114x114" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-114x114.png">
-    <link rel="apple-touch-icon" sizes="120x120" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-120x120.png">
-    <link rel="apple-touch-icon" sizes="144x144" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-144x144.png">
-    <link rel="apple-touch-icon" sizes="152x152" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-152x152.png">
-    <link rel="apple-touch-icon" sizes="180x180" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/apple-touch-icon-180x180.png">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/favicon-32x32.png" sizes="32x32">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/android-chrome-192x192.png" sizes="192x192">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/favicon-96x96.png" sizes="96x96">
-    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/favicon-16x16.png" sizes="16x16">
-    <link rel="manifest" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/manifest.json">
-    <link rel="shortcut icon" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/favicon.ico">
+    <link rel="apple-touch-icon" sizes="57x57" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-57x57.png">
+    <link rel="apple-touch-icon" sizes="60x60" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-60x60.png">
+    <link rel="apple-touch-icon" sizes="72x72" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-72x72.png">
+    <link rel="apple-touch-icon" sizes="76x76" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-76x76.png">
+    <link rel="apple-touch-icon" sizes="114x114" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-114x114.png">
+    <link rel="apple-touch-icon" sizes="120x120" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-120x120.png">
+    <link rel="apple-touch-icon" sizes="144x144" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-144x144.png">
+    <link rel="apple-touch-icon" sizes="152x152" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-152x152.png">
+    <link rel="apple-touch-icon" sizes="180x180" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/apple-touch-icon-180x180.png">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/favicon-32x32.png" sizes="32x32">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/android-chrome-192x192.png" sizes="192x192">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/favicon-96x96.png" sizes="96x96">
+    <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/favicon-16x16.png" sizes="16x16">
+    <link rel="manifest" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/manifest.json">
+    <link rel="shortcut icon" href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/favicon.ico">
     <meta name="apple-mobile-web-app-title" content="Dokku">
     <meta name="application-name" content="Dokku">
     <meta name="msapplication-TileColor" content="#da532c">
-    <meta name="msapplication-TileImage" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/mstile-144x144.png">
-    <meta name="msapplication-config" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/favicons/browserconfig.xml">
+    <meta name="msapplication-TileImage" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/mstile-144x144.png">
+    <meta name="msapplication-config" content="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/favicons/browserconfig.xml">
     <meta name="theme-color" content="#ffffff">
 
     <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.2.0-beta1/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-0evHe/X+R7YkIZDRvuzKMRqM+OrBnVFBL6DOitfPri4tjfHxaWutUpFmBp4vmVor" crossorigin="anonymous">
@@ -38,7 +38,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com">
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
     <link href="https://fonts.googleapis.com/css2?family=Lato:wght@400;700;900&display=swap" rel="stylesheet">
-    <link href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.30.2/docs/assets/style.css" rel="stylesheet">
+    <link href="https://cdn.jsdelivr.net/gh/dokku/dokku@v0.31.2/docs/assets/style.css" rel="stylesheet">
     <!-- <link href="./assets/style.css" rel="stylesheet"> -->
 </head>
 
@@ -98,7 +98,7 @@
         <main class="container px-4 px-lg-5">
             <div class="row">
                 <div class="col-lg-7">
-                    <a class="badge-link" href="https://github.com/dokku/dokku/releases"><span class="badge py-2 d-flex fit-content"><div class="circle align-self-center me-2"></div>Latest release <span id="releaseVersion" class="ms-1">v0.30.2</span></span></a>
+                    <a class="badge-link" href="https://github.com/dokku/dokku/releases"><span class="badge py-2 d-flex fit-content"><div class="circle align-self-center me-2"></div>Latest release <span id="releaseVersion" class="ms-1">v0.31.2</span></span></a>
                     <h1 class="text-white hero-heading mt-5">An open source PAAS alternative to Heroku.</h1>
                     <h4 class="text-white mt-5">Dokku helps you build and manage the lifecycle of applications from building to scaling.</h4>
                     <div class="d-flex mt-5">
@@ -116,7 +116,7 @@
                             </p>
                             <p class="line">
                                 <span class="prompt">$</span>
-                                <span class="command">wget https://dokku.com/bootstrap.sh</span>
+                                <span class="command">wget -NP . https://dokku.com/bootstrap.sh</span>
                             </p>
                             <br>
 
@@ -125,7 +125,7 @@
                             </p>
                             <p class="line">
                                 <span class="prompt">$</span>
-                                <span class="command">sudo DOKKU_TAG=v0.30.2 bash bootstrap.sh</span>
+                                <span class="command">sudo DOKKU_TAG=v0.31.2 bash bootstrap.sh</span>
                             </p>
                             <br>
 
@@ -227,7 +227,7 @@
                             Create</a>
                           <a class="nav-link" id="nav-deploy-tab" data-bs-toggle="tab" href="#nav-deploy" role="tab" aria-controls="nav-deploy" aria-selected="false">
                             <svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
-                                <path d="M29.8709 1.40551C29.8591 1.34642 29.8311 1.29205 29.7903 1.24881C29.7495 1.20556 29.6976 1.17524 29.6407 1.16141C25.8466 0.20375 17.082 3.61605 12.3285 8.51812C11.4813 9.38524 10.7088 10.3268 10.0198 11.3321C8.55457 11.1953 7.08939 11.3105 5.84189 11.8721C2.31916 13.4706 1.29423 17.6454 1.00817 19.4376C0.992669 19.5358 0.999288 19.6364 1.02751 19.7315C1.05574 19.8267 1.10481 19.9138 1.17093 19.9862C1.23705 20.0586 1.31844 20.1144 1.40878 20.1491C1.49913 20.1838 1.59601 20.1966 1.69192 20.1865L7.34824 19.5456C7.35215 19.9859 7.37777 20.4257 7.42498 20.8633C7.4545 21.1658 7.58527 21.4482 7.79477 21.6618L9.98487 23.9221C10.1921 24.1384 10.466 24.2734 10.7593 24.3037C11.1808 24.3522 11.6044 24.3786 12.0285 24.3829L11.4082 30.2153C11.3985 30.3141 11.411 30.414 11.4446 30.507C11.4783 30.6001 11.5323 30.684 11.6023 30.7521C11.6724 30.8202 11.7567 30.8708 11.8487 30.9C11.9408 30.9291 12.0381 30.936 12.1331 30.9202C13.8704 30.6322 17.9241 29.5744 19.4639 25.9396C20.0081 24.6508 20.1198 23.1466 19.9942 21.6417C20.9712 20.9312 21.8861 20.134 22.7285 19.2591C27.4994 14.3627 30.7849 5.51625 29.8709 1.40551ZM18.4878 12.9162C18.0711 12.4862 17.7873 11.9384 17.6723 11.3419C17.5573 10.7455 17.6162 10.1273 17.8417 9.56541C18.0672 9.00356 18.449 8.52333 18.939 8.18546C19.4289 7.84759 20.005 7.66725 20.5942 7.66725C21.1835 7.66725 21.7595 7.84759 22.2494 8.18546C22.7394 8.52333 23.1212 9.00356 23.3467 9.56541C23.5722 10.1273 23.6311 10.7455 23.5161 11.3419C23.4011 11.9384 23.1173 12.4862 22.7006 12.9162C22.4242 13.202 22.0959 13.4288 21.7344 13.5835C21.373 13.7383 20.9855 13.8179 20.5942 13.8179C20.2029 13.8179 19.8154 13.7383 19.454 13.5835C19.0926 13.4288 18.7642 13.202 18.4878 12.9162Z" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
+                                <path d="M29.8709 1.40551C29.8591 1.34642 29.8311 1.29205 29.7903 1.24881C29.7495 1.20556 29.6976 1.17524 29.6407 1.16141C25.8466 0.20375 17.082 3.61605 12.3285 8.51812C11.4813 9.38524 10.7088 10.3268 10.0198 11.3321C8.55457 11.1953 7.08939 11.3105 5.84189 11.8721C2.31916 13.4706 1.29423 17.6454 1.00817 19.4376C0.992669 19.5358 0.999288 19.6364 1.02751 19.7315C1.05574 19.8267 1.10481 19.9138 1.17093 19.9862C1.23705 20.0586 1.31844 20.1144 1.40878 20.1491C1.49913 20.1838 1.59601 20.1966 1.69192 20.1865L7.34824 19.5456C7.35215 19.9859 7.37777 20.4257 7.42498 20.8633C7.4545 21.1658 7.58527 21.4482 7.79477 21.6618L9.98487 23.9221C10.1921 24.1384 10.466 24.2734 10.7593 24.3037C11.1808 24.3522 11.6044 24.3786 12.0285 24.3829L11.4082 30.2153C11.3985 30.31.2 11.411 30.414 11.4446 30.507C11.4783 30.6001 11.5323 30.684 11.6023 30.7521C11.6724 30.8202 11.7567 30.8708 11.8487 30.9C11.9408 30.9291 12.0381 30.936 12.1331 30.9202C13.8704 30.6322 17.9241 29.5744 19.4639 25.9396C20.0081 24.6508 20.1198 23.1466 19.9942 21.6417C20.9712 20.9312 21.8861 20.134 22.7285 19.2591C27.4994 14.3627 30.7849 5.51625 29.8709 1.40551ZM18.4878 12.9162C18.0711 12.4862 17.7873 11.9384 17.6723 11.3419C17.5573 10.7455 17.6162 10.1273 17.8417 9.56541C18.0672 9.00356 18.449 8.52333 18.939 8.18546C19.4289 7.84759 20.005 7.66725 20.5942 7.66725C21.1835 7.66725 21.7595 7.84759 22.2494 8.18546C22.7394 8.52333 23.1212 9.00356 23.3467 9.56541C23.5722 10.1273 23.6311 10.7455 23.5161 11.3419C23.4011 11.9384 23.1173 12.4862 22.7006 12.9162C22.4242 13.202 22.0959 13.4288 21.7344 13.5835C21.373 13.7383 20.9855 13.8179 20.5942 13.8179C20.2029 13.8179 19.8154 13.7383 19.454 13.5835C19.0926 13.4288 18.7642 13.202 18.4878 12.9162Z" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
                                 <path d="M5.29982 22.8765C4.60428 22.9646 3.95721 23.29 3.46136 23.801C2.232 25.074 2.11548 29.7889 2.11548 29.7889C2.11548 29.7889 6.68686 29.6687 7.91692 28.3985C8.41409 27.8876 8.72993 27.2187 8.81347 26.4997" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
                             </svg>
                             Deploy</a>
@@ -418,7 +418,7 @@
                                 <g id="mysql" data-bs-toggle="svg-tooltip" data-bs-placement="bottom" title="MySQL" filter="url(#filter9_d_55_77)" transform="translate(79.2566,394.257) translate(-79.2566,-394.257)" style="animation: 30s linear infinite both mysql_t;">
                                 <ellipse fill="white" rx="51.2566" ry="51.2566" transform="translate(79.2566,394.257)"/>
                                 <path d="M39,411.45L41.6356,411.45L41.6356,401.092L45.7157,410.121C46.1971,411.214,46.8562,411.601,48.1485,411.601C49.4411,411.601,50.0746,411.214,50.5563,410.121L54.6364,401.092L54.6364,411.449L57.272,411.449L57.272,401.109C57.272,400.1,56.8664,399.612,56.0303,399.36C54.0283,398.738,52.685,399.276,52.0767,400.621L48.0726,409.533L44.1953,400.621C43.6124,399.276,42.2439,398.738,40.2419,399.36C39.4055,399.612,39,400.1,39,401.109L39,411.45L39,411.45ZM59.4635,403.019L62.0983,403.019L62.0983,408.725C62.0736,409.035,62.1982,409.763,63.642,409.785C64.3786,409.797,69.327,409.785,69.3732,409.785L69.3732,402.991L72.0141,402.991C72.0263,402.991,72.0115,412.257,72.0117,412.296C72.026,414.581,69.1626,415.078,67.8428,415.116L59.5205,415.116L59.5205,413.351C59.5353,413.351,67.8366,413.353,67.8575,413.351C69.5538,413.173,69.3535,412.334,69.3533,412.051L69.3533,411.363L63.7512,411.363C61.1447,411.339,59.4852,410.207,59.4647,408.905C59.4626,408.785,59.5209,403.076,59.4633,403.019L59.4635,403.019Z" fill="#00618A" transform="translate(55.5095,407.109) translate(-55.5095,-407.109)"/>
-                                <path d="M74.0451,411.45L81.6224,411.45C82.5094,411.45,83.371,411.265,84.0554,410.945C85.1957,410.424,85.7533,409.718,85.7533,408.793L85.7533,406.876C85.7533,406.12,85.1198,405.413,83.8779,404.943C83.2189,404.69,82.408,404.556,81.6224,404.556L78.4289,404.556C77.365,404.556,76.8581,404.236,76.7314,403.53C76.706,403.446,76.706,403.379,76.706,403.295L76.706,402.101C76.706,402.034,76.706,401.966,76.7314,401.882C76.8581,401.344,77.137,401.193,78.0745,401.109C78.1504,401.109,78.2518,401.092,78.328,401.092L85.8547,401.092L85.8547,399.344L78.4546,399.344C77.3902,399.344,76.8326,399.411,76.3259,399.562C74.7546,400.05,74.0704,400.823,74.0704,402.168L74.0704,403.698C74.0704,404.875,75.4136,405.884,77.6689,406.12C77.9226,406.136,78.1759,406.153,78.4291,406.153L81.1661,406.153C81.2677,406.153,81.3691,406.153,81.445,406.17C82.2814,406.237,82.636,406.389,82.8897,406.691C83.0416,406.842,83.0922,406.994,83.0922,407.162L83.0922,408.692C83.0922,408.877,82.9656,409.113,82.7124,409.314C82.4841,409.516,82.104,409.651,81.5971,409.684C81.4957,409.684,81.4198,409.701,81.3184,409.701L74.0449,409.701L74.0449,411.449L74.0451,411.45ZM102.195,408.406C102.195,410.205,103.538,411.214,106.25,411.416C106.503,411.433,106.757,411.45,107.01,411.45L113.878,411.45L113.878,409.701L106.959,409.701C105.413,409.701,104.831,409.314,104.831,408.39L104.831,399.343L102.195,399.343L102.195,408.406ZM87.4354,408.498L87.4354,402.264C87.4354,400.68,88.5529,399.719,90.762,399.416C90.9976,399.383,91.2352,399.366,91.4732,399.366L96.476,399.366C96.7298,399.366,96.9587,399.383,97.2126,399.416C99.4219,399.719,100.539,400.68,100.539,402.264L100.539,408.498C100.539,409.783,100.065,410.47,98.971,410.919L101.567,413.251L98.507,413.251L96.4066,411.364L94.2921,411.497L91.4732,411.497C90.9907,411.497,90.4829,411.43,89.9241,411.278C88.2481,410.823,87.4354,409.947,87.4354,408.498L87.4354,408.498ZM90.28,408.346C90.28,408.431,90.3054,408.515,90.3309,408.616C90.4831,409.341,91.1688,409.745,92.21,409.745L94.6044,409.745L92.4049,407.769L95.465,407.769L97.3835,409.492C97.7369,409.305,97.9697,409.018,98.0509,408.65C98.0762,408.566,98.0762,408.481,98.0762,408.397L98.0762,402.416C98.0762,402.348,98.0762,402.264,98.0509,402.18C97.8984,401.506,97.2128,401.118,96.1971,401.118L92.21,401.118C91.042,401.118,90.2802,401.624,90.2802,402.416L90.2802,408.346L90.28,408.346Z" fill="#E48E00" transform="translate(93.9614,406.297) translate(-93.9614,-406.297)"/>
+                                <path d="M74.0451,411.45L81.6224,411.45C82.5094,411.45,83.371,411.265,84.0554,410.945C85.1957,410.424,85.7533,409.718,85.7533,408.793L85.7533,406.876C85.7533,406.12,85.1198,405.413,83.8779,404.943C83.2189,404.69,82.408,404.556,81.6224,404.556L78.4289,404.556C77.365,404.556,76.8581,404.236,76.7314,403.53C76.706,403.446,76.706,403.379,76.706,403.295L76.706,402.101C76.706,402.034,76.706,401.966,76.7314,401.882C76.8581,401.344,77.137,401.193,78.0745,401.109C78.1504,401.109,78.2518,401.092,78.328,401.092L85.8547,401.092L85.8547,399.344L78.4546,399.344C77.3902,399.344,76.8326,399.411,76.3259,399.562C74.7546,400.05,74.0704,400.823,74.0704,402.168L74.0704,403.698C74.0704,404.875,75.4136,405.884,77.6689,406.12C77.9226,406.136,78.1759,406.153,78.4291,406.153L81.1661,406.153C81.2677,406.153,81.3691,406.153,81.445,406.17C82.2814,406.237,82.636,406.389,82.8897,406.691C83.0416,406.842,83.0922,406.994,83.0922,407.162L83.0922,408.692C83.0922,408.877,82.9656,409.113,82.7124,409.314C82.4841,409.516,82.104,409.651,81.5971,409.684C81.4957,409.684,81.4198,409.701,81.3184,409.701L74.0449,409.701L74.0449,411.449L74.0451,411.45ZM102.195,408.406C102.195,410.205,103.538,411.214,106.25,411.416C106.503,411.433,106.757,411.45,107.01,411.45L113.878,411.45L113.878,409.701L106.959,409.701C105.413,409.701,104.831,409.314,104.831,408.39L104.831,399.343L102.195,399.343L102.195,408.406ZM87.4354,408.498L87.4354,402.264C87.4354,400.68,88.5529,399.719,90.762,399.416C90.9976,399.383,91.2352,399.366,91.4732,399.366L96.476,399.366C96.7298,399.366,96.9587,399.383,97.2126,399.416C99.4219,399.719,100.539,400.68,100.539,402.264L100.539,408.498C100.539,409.783,100.065,410.47,98.971,410.919L101.567,413.251L98.507,413.251L96.4066,411.364L94.2921,411.497L91.4732,411.497C90.9907,411.497,90.4829,411.43,89.9241,411.278C88.2481,410.823,87.4354,409.947,87.4354,408.498L87.4354,408.498ZM90.28,408.346C90.28,408.431,90.31.0,408.515,90.3309,408.616C90.4831,409.341,91.1688,409.745,92.21,409.745L94.6044,409.745L92.4049,407.769L95.465,407.769L97.3835,409.492C97.7369,409.305,97.9697,409.018,98.0509,408.65C98.0762,408.566,98.0762,408.481,98.0762,408.397L98.0762,402.416C98.0762,402.348,98.0762,402.264,98.0509,402.18C97.8984,401.506,97.2128,401.118,96.1971,401.118L92.21,401.118C91.042,401.118,90.2802,401.624,90.2802,402.416L90.2802,408.346L90.28,408.346Z" fill="#E48E00" transform="translate(93.9614,406.297) translate(-93.9614,-406.297)"/>
                                 <path d="M116.197,396.443C114.577,396.399,113.339,396.549,112.281,396.993C111.981,397.119,111.501,397.122,111.452,397.497C111.617,397.67,111.643,397.927,111.774,398.139C112.027,398.546,112.453,399.091,112.834,399.377C113.25,399.69,113.678,400.024,114.124,400.294C114.917,400.775,115.802,401.05,116.565,401.532C117.015,401.816,117.462,402.174,117.901,402.495C118.118,402.653,118.264,402.9,118.546,402.999L118.546,402.953C118.398,402.765,118.36,402.507,118.224,402.311L117.625,401.715C117.039,400.942,116.296,400.262,115.506,399.698C114.876,399.248,113.465,398.64,113.203,397.91L113.156,397.864C113.603,397.814,114.126,397.653,114.539,397.543C115.231,397.358,115.85,397.406,116.565,397.222C116.888,397.131,117.21,397.039,117.533,396.947L117.533,396.764C117.171,396.395,116.914,395.906,116.519,395.572C115.488,394.698,114.362,393.824,113.203,393.096C112.56,392.692,111.765,392.43,111.083,392.087C110.854,391.972,110.451,391.913,110.3,391.721C109.942,391.266,109.747,390.691,109.471,390.162C108.893,389.054,108.325,387.843,107.813,386.677C107.463,385.882,107.235,385.098,106.799,384.385C104.707,380.962,102.456,378.897,98.9679,376.866C98.2258,376.434,97.3322,376.264,96.3879,376.041L94.8677,375.949C94.5584,375.82,94.2366,375.444,93.9462,375.261C92.7908,374.535,89.8272,372.955,88.9714,375.032C88.431,376.344,89.779,377.623,90.2611,378.288C90.5995,378.754,91.0327,379.276,91.2745,379.8C91.4336,380.145,91.4611,380.49,91.5971,380.855C91.9321,381.753,92.2231,382.73,92.6565,383.56C92.8755,383.98,93.1169,384.422,93.3937,384.798C93.5635,385.028,93.8543,385.13,93.9003,385.485C93.6158,385.882,93.5996,386.496,93.4397,386.998C92.7198,389.258,92.9913,392.066,94.0386,393.738C94.36,394.251,95.1169,395.352,96.1576,394.93C97.0681,394.561,96.8647,393.417,97.1251,392.408C97.184,392.18,97.1477,392.011,97.2632,391.858L97.2632,391.904L98.0924,393.554C98.706,394.538,99.7954,395.566,100.718,396.26C101.197,396.619,101.574,397.241,102.193,397.451L102.193,397.406L102.146,397.406C102.027,397.22,101.839,397.142,101.686,396.993C101.325,396.641,100.924,396.204,100.626,395.801C99.7868,394.667,99.0449,393.426,98.369,392.133C98.0462,391.516,97.7656,390.836,97.4935,390.208C97.3886,389.966,97.3899,389.6,97.1713,389.474C96.8733,389.934,96.4343,390.306,96.2038,390.85C95.8352,391.718,95.7876,392.777,95.6511,393.875C95.5703,393.904,95.606,393.884,95.5588,393.921C94.9172,393.767,94.6916,393.11,94.4534,392.546C93.85,391.12,93.7381,388.823,94.2687,387.182C94.4062,386.757,95.0268,385.419,94.7756,385.027C94.6557,384.636,94.26,384.409,94.0386,384.11C93.7646,383.74,93.491,383.253,93.3014,382.826C92.8078,381.714,92.5773,380.466,92.0577,379.342C91.8093,378.805,91.3892,378.261,91.0442,377.783C90.6623,377.254,90.2346,376.864,89.9386,376.224C89.8333,375.997,89.6903,375.633,89.8463,375.399C89.8961,375.241,89.9661,375.175,90.1229,375.124C90.3901,374.919,91.1343,375.192,91.4126,375.307C92.1515,375.613,92.768,375.904,93.3937,376.316C93.6942,376.514,93.998,376.898,94.361,377.004L94.7756,377.004C95.4241,377.152,96.1507,377.05,96.7565,377.233C97.8274,377.557,98.7871,378.061,99.6585,378.608C102.314,380.277,104.485,382.652,105.97,385.485C106.209,385.942,106.312,386.377,106.523,386.861C106.947,387.837,107.482,388.841,107.905,389.795C108.326,390.747,108.737,391.708,109.333,392.5C109.646,392.917,110.856,393.14,111.406,393.371C111.791,393.533,112.423,393.702,112.788,393.921C113.485,394.34,114.161,394.838,114.815,395.297C115.142,395.526,116.147,396.029,116.197,396.443L116.197,396.443Z" fill="#00618A" transform="translate(103.696,388.499) translate(-103.696,-388.499)"/>
                                 <path fill-rule="evenodd" clip-rule="evenodd" d="M95.6047,378.975C95.2669,378.969,95.028,379.012,94.7754,379.067L94.7754,379.113L94.8216,379.113C94.9827,379.442,95.2669,379.654,95.4664,379.938C95.6199,380.259,95.7735,380.58,95.9272,380.901L95.9731,380.855C96.2584,380.655,96.3891,380.335,96.3877,379.846C96.2734,379.727,96.2564,379.576,96.1574,379.434C96.0257,379.243,95.7708,379.135,95.6047,378.975L95.6047,378.975Z" fill="#00618A" transform="translate(95.5816,379.938) translate(-95.5816,-379.938)"/>
                                 <path fill-rule="evenodd" clip-rule="evenodd" d="M115.115,409.651C115.115,410.806,116.032,411.584,117.058,411.584C118.083,411.584,119,410.806,119,409.651C119,408.497,118.083,407.718,117.058,407.718C116.032,407.718,115.115,408.497,115.115,409.651L115.115,409.651ZM118.565,409.651C118.565,410.527,117.892,411.182,117.058,411.182C116.214,411.182,115.551,410.527,115.551,409.651C115.551,408.775,116.213,408.12,117.058,408.12C117.892,408.12,118.565,408.775,118.565,409.651ZM117.581,410.754L118.016,410.754L117.379,409.785C117.721,409.749,117.98,409.584,117.98,409.182C117.98,408.734,117.695,408.548,117.146,408.548L116.281,408.548L116.281,410.754L116.654,410.754L116.654,409.801L117.001,409.801L117.581,410.754L117.581,410.754ZM116.654,409.491L116.654,408.857L117.084,408.857C117.307,408.857,117.576,408.899,117.576,409.156C117.576,409.466,117.332,409.491,117.052,409.491L116.654,409.491L116.654,409.491Z" fill="#E48E00" transform="translate(117.058,409.651) translate(-117.058,-409.651)"/>

docs/networking/dns.md

@@ -1,6 +1,7 @@
 # DNS Configuration
 
-> Note: This is a work in progress.
+> [!NOTE]
+> This is a work in progress.
 
 ## DNS Versions
 

docs/networking/network.md

@@ -1,5 +1,6 @@
 # Network Management
 
+> [!IMPORTANT]
 > New as of 0.11.0, Enhanced in 0.20.0
 
 ```
@@ -20,6 +21,7 @@ The Network plugin allows developers to abstract the concept of container networ
 
 ### Listing networks
 
+> [!IMPORTANT]
 > New as of 0.20.0, Requires Docker 1.21+
 
 You can easily list all available networks using the `network:list` command:
@@ -51,6 +53,7 @@ test-network
 
 ### Creating a network
 
+> [!IMPORTANT]
 > New as of 0.20.0, Requires Docker 1.21+
 
 Docker networks can be created via the `network:create` command. Executing this command will create an attachable `bridge` network. This can be used to route requests between containers without going through any public network.
@@ -67,6 +70,7 @@ Specifying other additional flags or other types of networks can be created dire
 
 ### Destroying a network
 
+> [!IMPORTANT]
 > New as of 0.20.0, Requires Docker 1.21+
 
 A Docker network without any associated containers may be destroyed via the `network:destroy` command. Docker will refuse to destroy networks that have containers attached.
@@ -75,7 +79,7 @@ A Docker network without any associated containers may be destroyed via the `net
 dokku network:destroy test-network
 ```
 
-```shell
+```
  !     WARNING: Potentially Destructive Action
  !     This command will destroy network test.
  !     To proceed, type "test"
@@ -89,12 +93,13 @@ As the command is destructive, it will default to asking for confirmation before
 dokku --force network:destroy test-network
 ```
 
-```shell
+```
 -----> Destroying network test
 ```
 
 ### Checking if a network exists
 
+> [!IMPORTANT]
 > New as of 0.20.0, Requires Docker 1.21+
 
 For CI/CD pipelines, it may be useful to see if an network exists before creating a new network. You can do so via the `network:exists` command:
@@ -111,6 +116,7 @@ The `network:exists` command will return non-zero if the network does not exist,
 
 ### Checking network info
 
+> [!IMPORTANT]
 > New as of 0.20.0, Requires Docker 1.21+
 
 Network information can be retrieved via the `network:info` command. This is a slightly different version of the `docker network` command.
@@ -155,21 +161,32 @@ Only a single `$IP:$PORT` combination can be routed to for a given app, and that
 
 ### Attaching an app to a network
 
+> [!IMPORTANT]
 > New as of 0.20.0, Requires Docker 1.21+
 
 Apps will default to being associated with the default `bridge` network or a network specified by the `initial-network` network property. Additionally, an app can be attached to `attachable` networks by changing the `attach-post-create` or `attach-post-deploy` network properties when using the [docker-local scheduler](/docs/deployment/schedulers/docker-local.md). A change in these values will require an app deploy or rebuild.
 
 ```shell
 # associates the network after a container is created but before it is started
+# commonly used for cross-app networking
 dokku network:set node-js-app attach-post-create test-network
 
 # associates the network after the deploy is successful but before the proxy is updated
+# used for cross-app networking when healthchecks must be invoked first
 dokku network:set node-js-app attach-post-deploy other-test-network
 
 # associates the network at container creation
+# typically blocks access to services and external routing
 dokku network:set node-js-app initial-network global-network
 ```
 
+Multiple networks can also be specified for the `attach-post-create` and `attach-post-deploy` phases.
+
+```shell
+# one or more networks can be specified
+dokku network:set node-js-app attach-post-create test-network test-network-2
+```
+
 Setting the `attach` network property to an empty value will de-associate the container with the network.
 
 ```shell
@@ -196,7 +213,8 @@ dokku network:set --global initial-network
 
 #### Network Aliases
 
-> Note: This feature is only available when an app has been attached to a network other than the default `bridge` network.
+> [!NOTE]
+> This feature is only available when an app has been attached to a network other than the default `bridge` network.
 
 When a container created for a deployment is being attached to a network - regardless of which network property was used - a network alias of the pattern `APP.PROC_TYPE` will be added to all containers. This can be used to load-balance requests between containers. For an application named `node-js-app` with a process type of web, the network alias - or resolvable DNS record within the network - will be:
 
@@ -282,7 +300,8 @@ Whatever the reason, the semantics of the two network hooks are important and ar
     - Use case: When another container on the network is already running and needed by this container.
     - Example: A key-value store exposing itself to all your apps may be on the `initial-network`.
 
-> Warning: If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed.
+> [!WARNING]
+> If the attachment fails during the `running` container state, this may result in your application failing to respond to proxied requests once older containers are removed.
 
 ### Rebuilding network settings
 
@@ -334,7 +353,7 @@ CONTAINER ID        IMAGE                      COMMAND                CREATED
 
 As such, the container's IP address will be an internal IP, and thus it is only accessible on the host itself:
 
-```
+```shell
 docker inspect --format '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' node-js-app.web.1
 ```
 

docs/networking/port-management.md

@@ -1,37 +1,54 @@
 # Port Management
 
-> New as of 0.5.0, Enhanced in 0.6.0
+> [!IMPORTANT]
+> 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.
+> [!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,15 +79,13 @@ 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
 ```
 
 ```
------> 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
        Reloading nginx
@@ -98,15 +113,13 @@ 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
 ```
 
 ```
------> 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
        Reloading nginx
@@ -114,21 +127,22 @@ 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
 
@@ -138,7 +152,7 @@ For buildpack deployments, your application _must_ respect the `PORT` environmen
 
 > Changed as of 0.5.0
 
-Dokku's default proxy implementation - nginx - supports HTTP and GRPC 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` and manually exposing the ports via the `docker-options` plugin. For example, `dokku docker-options:add myapp deploy "-p 2456:2456/udp'`. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/docs/networking/proxy-management.md).
+Dokku's default proxy implementation - nginx - supports HTTP and GRPC 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` and manually exposing the ports via the `docker-options` plugin. For example, `dokku docker-options:add myapp deploy "-p 2456:2456/udp"`. If you would like to investigate alternative proxy methods, please refer to our [proxy management documentation](/docs/networking/proxy-management.md).
 
 #### Applications using EXPOSE
 
@@ -156,10 +170,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
@@ -169,24 +183,40 @@ Any application that does not use an `EXPOSE` directive will result in Dokku def
 - modify your application to support the `PORT` environment variable.
 - switch to using an `EXPOSE` directive in your Dockerfile.
 
-#### Switching between `EXPOSE` usage modes
+### Displaying ports reports for an app
 
-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.
+You can get a report about the app's ports status using the `ports:report` command:
 
 ```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:report
 ```
 
-### Docker Image
+```
+=====> node-js-app ports information
+       Port map detected: http:80:5000
+       Port map:          http:80:5000 https:443:5000
+=====> python-sample ports information
+       Port map detected: http:80:5000
+       Port map:          http:80:5000
+=====> ruby-sample ports information
+       Port map detected: http:80:5000
+       Port map:          http:80:5000
+```
 
-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.
+You can run the command for a specific app also.
 
 ```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:report node-js-app
 ```
 
-All other port-related behavior is the same as when deploying via Dockerfile.
+```
+=====> node-js-app ports information
+       Port map detected: http:80:5000
+       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
+```

docs/networking/proxies/caddy.md

@@ -1,5 +1,6 @@
 # Caddy Proxy
 
+> [!IMPORTANT]
 > New as of 0.28.0
 
 Dokku provides integration with the [Caddy](https://caddyserver.com/) proxy service by utilizing the Docker label-based integration implemented by Caddy.
@@ -19,7 +20,8 @@ Using the `caddy` plugin integration requires the `docker-compose-plugin` for Do
 
 ## Usage
 
-> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy.
+> [!WARNING]
+> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Caddy.
 
 The Caddy plugin has specific rules for routing requests:
 
@@ -103,7 +105,7 @@ You can use these modifiers as follows:
 dokku caddy:logs --tail --num 10
 ```
 
-The above command will show logs continually from the vector container, with an initial history of 10 log lines
+The above command will show logs continually from the caddy container, with an initial history of 10 log lines
 
 ### Changing the Caddy log level
 

docs/networking/proxies/haproxy.md

@@ -1,5 +1,6 @@
 # Haproxy Proxy
 
+> [!IMPORTANT]
 > New as of 0.28.0
 
 Dokku provides integration with the [Haproxy](http://www.haproxy.org) proxy service by utilizing the Docker label-based integration implemented by [EasyHaproxy](https://github.com/byjg/docker-easy-haproxy).
@@ -15,11 +16,12 @@ haproxy:stop                               # Stops the haproxy server
 
 ## Requirements
 
-Using the `caddy` plugin integration requires the `docker-compose-plugin` for Docker. See [this document](https://docs.docker.com/compose/install/) from the Docker documentation for more information on the installation process for the `docker-compose-plugin`.
+Using the `haproxy` plugin integration requires the `docker-compose-plugin` for Docker. See [this document](https://docs.docker.com/compose/install/) from the Docker documentation for more information on the installation process for the `docker-compose-plugin`.
 
 ## Usage
 
-> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy.
+> [!WARNING]
+> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Haproxy.
 
 The Haproxy plugin has specific rules for routing requests:
 

docs/networking/proxies/nginx.md

@@ -15,7 +15,8 @@ nginx:validate-config [<app>] [--clean]  # Validates and optionally cleans up in
 
 ## Usage
 
-> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided.
+> [!WARNING]
+> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided.
 
 ### Request Proxying
 
@@ -23,10 +24,12 @@ By default, the `web` process is the only process proxied by the nginx proxy imp
 
 Nginx will proxy the requests in a [round-robin balancing fashion](http://nginx.org/en/docs/http/ngx_http_upstream_module.html#upstream) to the different deployed (scaled) containers running the `web` proctype. This way, the host's resources can be fully leveraged for single-threaded applications (e.g. `dokku ps:scale node-js-app web=4` on a 4-core machine).
 
-> Note: Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers.
+> [!NOTE]
+> Due to how the plugin is implemented, if an app successfully starts up `web` containers but fails to deploy some other containers, nginx may eventually stop routing requests. Users should revert their code in these cases, or manually trigger `dokku proxy:build-config $APP` in order to ensure requests route to the new web containers.
 
 ### Starting nginx
 
+> [!IMPORTANT]
 > New as of 0.28.0
 
 The nginx server can be started via `nginx:start`.
@@ -37,6 +40,7 @@ dokku nginx:start
 
 ### Stopping nginx
 
+> [!IMPORTANT]
 > New as of 0.28.0
 
 The nginx server can be stopped via `nginx:stop`.
@@ -47,9 +51,11 @@ dokku nginx:stop
 
 ### Binding to specific addresses
 
+> [!IMPORTANT]
 > New as of 0.19.2
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 By default, nginx will listen to all interfaces (`[::]` for IPv6, `0.0.0.0` for IPv4) when proxying requests to applications. This may be changed using the `bind-address-ipv4` and `bind-address-ipv6` properties. This is useful in cases where the proxying should be internal to a network or if there are multiple network interfaces that should respond with different content.
 
@@ -65,15 +71,18 @@ dokku nginx:set node-js-app bind-address-ipv4
 dokku nginx:set node-js-app bind-address-ipv6
 ```
 
-> Warning: Validation is not performed on either value.
+> [!WARNING]
+> Validation is not performed on either value.
 
 Users with apps that contain a custom `nginx.conf.sigil` file will need to modify the files to respect the new `NGINX_BIND_ADDRESS_IPV4` and `NGINX_BIND_ADDRESS_IPV6` variables.
 
 ### HSTS Header
 
+> [!IMPORTANT]
 > New as of 0.20.0
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 If SSL certificates are present, HSTS will be automatically enabled. It can be toggled via `nginx:set`:
 
@@ -93,7 +102,8 @@ Beware that if you enable the header and a subsequent deploy of your application
 
 #### Globally disabling the HSTS Header
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 HSTS Header can be disabled for all apps by setting the `hsts` property to false after passing the `--global` flag to `nginx:set`.
 
@@ -107,9 +117,46 @@ Once the HSTS setting is disabled globally, it can be re-enabled on a per-app ba
 dokku nginx:set node-js-app hsts true
 ```
 
+### Running behind another proxy — configuring `X-Forwarded-*` headers
+
+Dokku's default Nginx configuration passes the de-facto standard HTTP headers [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto), and `X-Forwarded-Port` to your application.
+These headers indicate the IP address of the original client making the request, the protocol of the original request (HTTP or HTTPS), and the port number of the original request, respectively.
+
+If you have another HTTP proxy sitting in between the end user and your server (for example, a load balancer, or a CDN), then the values of these headers will contain information about (e.g. the IP address of) the the closest proxy, and not the end user.
+
+To fix this, assuming that the other proxy also passes `X-Forwarded-*` headers, which in turn contain information about the end user, you can tell Nginx include those values in the `X-Forwarded-*` headers that it sends to your application. You can do this via `nginx:set`, like so:
+
+```shell
+dokku nginx:set node-js-app x-forwarded-for-value '$http_x_forwarded_for'
+dokku nginx:set node-js-app x-forwarded-port-value '$http_x_forwarded_port'
+dokku nginx:set node-js-app x-forwarded-proto-value '$http_x_forwarded_proto'
+```
+
+However, note that you should only do this if:
+
+1. Requests to your website always go through a trusted proxy.
+2. That proxy is configured to send the aforementioned `X-Forwarded-*` headers.
+
+Otherwise, if it's possible for clients to make HTTP requests directly against your server, bypassing the other proxy, or if the other proxy is not configured to set these headers, then a client can basically pass any arbitrary values for these headers (which your app then presumably reads) and thereby fake an IP address, for example.
+
+There's also the `X-Forwarded-Ssl` header which a less common alternative to `X-Forwarded-Proto` — and because of that, isn't included in Dokku's default Nginx configuration.
+But you can tell Nginx to send this header as well, if necessary.
+
+```shell
+# force-setting value to `on`
+dokku nginx:set node-js-app x-forwarded-ssl on
+
+# force-setting value to `off`
+dokku nginx:set node-js-app x-forwarded-ssl off
+
+# removing the value from nginx.conf (default)
+dokku nginx:set node-js-app x-forwarded-ssl
+```
+
 ### Checking access logs
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 You may check nginx access logs via the `nginx:access-logs` command. This assumes that app access logs are being stored in `/var/log/nginx/$APP-access.log`, as is the default in the generated `nginx.conf`.
 
@@ -139,9 +186,11 @@ dokku nginx:error-logs node-js-app -t
 
 ### Changing log path
 
+> [!IMPORTANT]
 > New as of 0.20.1
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 The path to where log files are stored can be changed by calling the `nginx:set` command with the following options:
 
@@ -166,9 +215,11 @@ In all cases, the nginx config must be regenerated after setting the above value
 
 ### Changing log format
 
+> [!IMPORTANT]
 > New as of 0.22.0
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 The format of the access log can be changed by calling the `nginx:set` command as follows:
 
@@ -209,9 +260,11 @@ dokku proxy:build-config node-js-app
 
 ### Specifying a read timeout
 
+> [!IMPORTANT]
 > New as of 0.21.0
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 When proxying requests to your applications, it may be useful to specify a proxy read timeout. This can be done via the `nginx:set` command as follows:
 
@@ -231,9 +284,11 @@ In all cases, the nginx config must be regenerated after setting the above value
 
 ### Specifying a custom client_max_body_size
 
+> [!IMPORTANT]
 > New as of 0.23.0
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 Users can override the default `client_max_body_size` value - which limits file uploads - via `nginx:set`. Changing this value will only apply to every `server` stanza of the default `nginx.conf.sigil`; users of custom `nginx.conf.sigil` files must update their templates to support the new value.
 
@@ -273,7 +328,8 @@ As app nginx configs are actually executed within a shared context, it is possib
 
 The `nginx:validate-config` command also takes an optional `--clean` flag. If specified, invalid nginx configs will be removed.
 
-> Warning: Invalid app nginx config's will be removed _even if_ the config is valid in the global server context.
+> [!WARNING]
+> Invalid app nginx config's will be removed _even if_ the config is valid in the global server context.
 
 ```shell
 dokku nginx:validate-config --clean
@@ -287,20 +343,23 @@ dokku nginx:validate-config node-js-app --clean
 
 ### Customizing the nginx configuration
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
 Dokku uses a templating library by the name of [sigil](https://github.com/gliderlabs/sigil) to generate nginx configuration for each app. This may be overriden by committing the [default configuration template](https://github.com/dokku/dokku/blob/master/plugins/nginx-vhosts/templates/nginx.conf.sigil) to a file named `nginx.conf.sigil` in the root of the app repository.
 
 When deploying a monorepo, it may be desirable to specify the specific path of the `nginx.conf.sigil` file to use for a given app. This can be done via the `nginx:set` command. If a value is specified and that file does not exist in the app's build directory, Dokku will continue the build process as if the repository has no `nginx.conf.sigil`.
 
+For deploys via the `git:from-image` and `git:load-image` commands, the `nginx.conf.sigil` is extracted from the configured `WORKDIR` property of the image. For all other deploys - git push, `git:from-archive`, `git:sync` - will have the `nginx.conf.sigil` extracted directly from the source code. Both cases will respect the configured `nginx-conf-sigil-path` property value.
+
 ```shell
-dokku nginx:set node-js-app nginx-conf-sigil-path dokku/nginx.conf.sigil
+dokku nginx:set node-js-app nginx-conf-sigil-path .dokku/nginx.conf.sigil
 ```
 
 This property can also be changed globally, which will take into effect if there is no value at the app level.
 
 ```shell
-dokku nginx:set --global nginx-conf-sigil-path dokku/nginx.conf.sigil
+dokku nginx:set --global nginx-conf-sigil-path .dokku/nginx.conf.sigil
 ```
 
 In either case, the value can be reset by specifying an empty value.
@@ -314,7 +373,8 @@ dokku nginx:set --global nginx-conf-sigil-path
 
 #### Disabling custom nginx config
 
-> Note: Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
+> [!NOTE]
+> Changing this value globally or on a per-app basis will require rebuilding the nginx config via the `proxy:build-config` command.
 
 While enabled by default, using a custom nginx config can be disabled via `nginx:set`. This may be useful in cases where you do not want to allow users to override any higher-level customization of app nginx config.
 
@@ -337,16 +397,16 @@ Unsetting this value is the same as enabling custom nginx config usage.
 {{ .PROXY_PORT }}                   Non-SSL nginx listener port (same as `DOKKU_PROXY_PORT` config var)
 {{ .PROXY_SSL_PORT }}               SSL nginx listener port (same as `DOKKU_PROXY_SSL_PORT` config var)
 {{ .NOSSL_SERVER_NAME }}            List of non-SSL VHOSTS
-{{ .PROXY_PORT_MAP }}               List of port mappings (same as `DOKKU_PROXY_PORT_MAP` config var)
-{{ .PROXY_UPSTREAM_PORTS }}         List of configured upstream ports (derived from `DOKKU_PROXY_PORT_MAP` config var)
-{{ .RAW_TCP_PORTS }}                List of exposed tcp ports as defined by Dockerfile `EXPOSE` directive (**Dockerfile apps only**)
+{{ .PROXY_PORT_MAP }}               List of port mappings (same as the `map` ports property)
+{{ .PROXY_UPSTREAM_PORTS }}         List of configured upstream ports (derived from the `map` ports property)
 {{ .SSL_INUSE }}                    Boolean set when an app is SSL-enabled
 {{ .SSL_SERVER_NAME }}              List of SSL VHOSTS
 ```
 
 Finally, each process type has it's network listeners - a list of IP:PORT pairs for the respective app containers - exposed via an `.DOKKU_APP_${PROCESS_TYPE}_LISTENERS` variable - the `PROCESS_TYPE` will be upper-cased with hyphens transformed into underscores. Users can use the new variables to expose non-web processes via the nginx proxy.
 
-> Note: Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`.
+> [!NOTE]
+> Application environment variables are available for use in custom templates. To do so, use the form of `{{ var "FOO" }}` to access a variable named `FOO`.
 
 #### Customizing via configuration files included by the default templates
 
@@ -399,7 +459,8 @@ These are provided as an alternative to the generic Nginx error page, are shared
 
 By default, Dokku will route any received request with an unknown HOST header value to the lexicographically first site in the nginx config stack. This means that accessing the dokku server via its IP address or a bogus domain name may return a seemingly random website.
 
-> Warning: some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:
+> [!WARNING]
+> some versions of Nginx may create a default site when installed. This site is simply a static page which says "Welcome to Nginx", and if this default site is enabled, Nginx will not route any requests with an unknown HOST header to Dokku. If you want Dokku to receive all requests, run the following commands:
 >
 > ```
 > rm /etc/nginx/sites-enabled/default
@@ -457,10 +518,6 @@ See the [customizing hostnames documentation](/docs/configuration/domains.md#cus
 
 See the [disabling vhosts documentation](/docs/configuration/domains.md#disabling-vhosts) for more information on how to disable domain usage for your app.
 
-### Running behind a load balancer
-
-See the [load balancer documentation](/docs/configuration/ssl.md#running-behind-a-load-balancer) for more information on how to configure your nginx config for running behind a network load balancer.
-
 ### SSL Configuration
 
 See the [ssl documentation](/docs/configuration/ssl.md) for more information on how to configure SSL certificates for your application.
@@ -471,7 +528,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
 

docs/networking/proxies/openresty.md

@@ -0,0 +1,166 @@
+# OpenResty Proxy
+
+> [!IMPORTANT]
+> New as of 0.31.0
+
+Dokku can provide integration with the [OpenResty](https://openresty.org/) proxy service by utilizing the Docker label-based integration implemented by [openresty-docker-proxy](https://github.com/dokku/openresty-docker-proxy).
+
+```
+openresty:report [<app>] [<flag>]            # Displays a openresty report for one or more apps
+openresty:logs [--num num] [--tail]          # Display openresty log output
+openresty:set <app> <property> (<value>)     # Set or clear an openresty property for an app
+openresty:show-config <app>                  # Display openresty compose config
+openresty:start                              # Starts the openresty server
+openresty:stop                               # Stops the openresty server
+```
+
+## Requirements
+
+Using the `openresty` plugin integration requires the `docker-compose-plugin` for Docker. See [this document](https://docs.docker.com/compose/install/) from the Docker documentation for more information on the installation process for the `docker-compose-plugin`.
+
+## Usage
+
+> [!WARNING]
+> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to OpenResty.
+
+The OpenResty plugin has specific rules for routing requests:
+
+- OpenResty integration is exposed via docker labels attached to containers. Changes in labels require either app deploys or rebuilds.
+- While OpenResty will respect labels associated with other containers, only `web` containers have OpenResty labels injected by the plugin.
+- Only `http:80` and `https:443` port mappings are supported at this time.
+- Requests are routed as soon as the container is running and passing healthchecks.
+
+### Switching to OpenResty
+
+To use the OpenResty plugin, use the `proxy:set` command for the app in question:
+
+```shell
+dokku proxy:set node-js-app openresty
+```
+
+This will enable the docker label-based OpenResty integration. All future deploys will inject the correct labels for OpenResty to read and route requests to containers. Due to the docker label-based integration used by OpenResty, a single deploy or rebuild will be required before requests will route successfully.
+
+```shell
+dokku ps:rebuild node-js-app
+```
+
+Any changes to domains or port mappings will also require either a deploy or rebuild.
+
+### Starting OpenResty container
+
+OpenResty can be started via the `openresty:start` command. This will start a OpenResty container via the `docker compose up` command.
+
+```shell
+dokku openresty:start
+```
+
+### Stopping the OpenResty container
+
+OpenResty may be stopped via the `openresty:stop` command.
+
+```shell
+dokku openresty:stop
+```
+
+The OpenResty container will be stopped and removed from the system. If the container is not running, this command will do nothing.
+
+### Showing the OpenResty compose config
+
+For debugging purposes, it may be useful to show the OpenResty compose config. This can be achieved via the `openresty:show-config` command.
+
+```shell
+dokku openresty:show-config
+```
+
+### Customizing the OpenResty container image
+
+While the default OpenResty image is hardcoded, users may specify an alternative by setting the `image` property with the `--global` flag:
+
+```shell
+dokku openresty:set --global image dokku/openresty-docker-proxy:0.5.6
+```
+
+#### Checking the OpenResty container's logs
+
+It may be necessary to check the OpenResty container's logs to ensure that OpenResty is operating as expected. This can be performed with the `openresty:logs` command.
+
+```shell
+dokku openresty:logs
+```
+
+This command also supports the following modifiers:
+
+```shell
+--num NUM        # the number of lines to display
+--tail           # continually stream logs
+```
+
+You can use these modifiers as follows:
+
+```shell
+dokku openresty:logs --tail --num 10
+```
+
+The above command will show logs continually from the openresty container, with an initial history of 10 log lines
+
+### SSL Configuration
+
+The OpenResty plugin only supports automatic ssl certificates from it's letsencrypt integration. Managed certificates provided by the `certs` plugin are ignored.
+
+#### Enabling letsencrypt integration
+
+By default, letsencrypt is disabled and https port mappings are ignored. To enable, set the `letsencrypt-email` property with the `--global` flag:
+
+```shell
+dokku openresty:set --global letsencrypt-email automated@dokku.sh
+```
+
+After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt. All http requests will then be redirected to https.
+
+#### Customizing the letsencrypt server
+
+The letsencrypt integration is set to the production letsencrypt server by default. To change this, set the `letsencrypt-server` property with the `--global` flag:
+
+```shell
+dokku openresty:set --global letsencrypt-server https://acme-staging-v02.api.letsencrypt.org/directory
+```
+
+After enabling, the OpenResty container will need to be restarted and apps will need to be rebuilt to retrieve certificates from the new server.
+
+## Displaying OpenResty reports for an app
+
+You can get a report about the app's OpenResty config using the `openresty:report` command:
+
+```shell
+dokku openresty:report
+```
+
+```
+=====> node-js-app openresty information
+       Openresty image:                   dokku/openresty-docker-proxy:0.5.6
+       Openresty letsencrypt email:       automated@dokku.sh
+=====> python-app openresty information
+       Openresty image:                   dokku/openresty-docker-proxy:0.5.6
+       Openresty letsencrypt email:       automated@dokku.sh
+=====> ruby-app openresty information
+       Openresty image:                   dokku/openresty-docker-proxy:0.5.6
+       Openresty letsencrypt email:       automated@dokku.sh
+```
+
+You can run the command for a specific app also.
+
+```shell
+dokku openresty:report node-js-app
+```
+
+```
+=====> node-js-app openresty information
+       Openresty image:                   dokku/openresty-docker-proxy:0.5.6
+       Openresty letsencrypt email:       automated@dokku.sh
+```
+
+You can pass flags which will output only the value of the specific information you want. For example:
+
+```shell
+dokku openresty:report node-js-app --openresty-letsencrypt-email
+```

docs/networking/proxies/traefik.md

@@ -1,5 +1,6 @@
 # Traefik Proxy
 
+> [!IMPORTANT]
 > New as of 0.28.0
 
 Dokku provides integration with the [Traefik](https://traefik.io/) proxy service by utilizing the Docker label-based integration implemented by Traefik.
@@ -19,7 +20,8 @@ Using the `traefik` plugin integration requires the `docker-compose-plugin` for
 
 ## Usage
 
-> Warning: As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik.
+> [!WARNING]
+> As using multiple proxy plugins on a single Dokku installation can lead to issues routing requests to apps, doing so should be avoided. As the default proxy implementation is nginx, users are encouraged to stop the nginx service before switching to Traefik.
 
 The Traefik plugin has specific rules for routing requests:
 
@@ -102,7 +104,7 @@ You can use these modifiers as follows:
 dokku traefik:logs --tail --num 10
 ```
 
-The above command will show logs continually from the vector container, with an initial history of 10 log lines
+The above command will show logs continually from the traefik container, with an initial history of 10 log lines
 
 ### Changing the Traefik log level
 
@@ -154,7 +156,8 @@ Traefik exposes an API and Dashboard, which Dokku disables by default for securi
 
 #### Enabling the api
 
-> Warning: Users enabling the dashboard should also enable api basic auth.
+> [!WARNING]
+> Users enabling the dashboard should also enable api basic auth.
 
 By default, the api is disabled. To enable, set the `api` property with the `--global` flag:
 
@@ -166,7 +169,8 @@ After enabling, the Traefik container will need to be restarted.
 
 #### Enabling the dashboard
 
-> Warning: Users enabling the dashboard should also enable api basic auth.
+> [!WARNING]
+> Users enabling the dashboard should also enable api basic auth.
 
 By default, the dashboard is disabled. To enable, set the `dashboard` property with the `--global` flag:
 

docs/networking/proxy-management.md

@@ -1,5 +1,6 @@
 # Proxy Management
 
+> [!IMPORTANT]
 > New as of 0.5.0, Enhanced in 0.6.0
 
 ```
@@ -43,6 +44,7 @@ dokku proxy:build-config --all --parallel -1
 
 ### Clearing the generated proxy config
 
+> [!IMPORTANT]
 > New as of 0.27.0
 
 Generated proxy configurations can also be cleared using the `proxy:clear-config` command.
@@ -61,6 +63,7 @@ Clearing a proxy configuration has different effects depending on the proxy plug
 
 ### Displaying proxy reports for an app
 
+> [!IMPORTANT]
 > New as of 0.8.1
 
 You can get a report about the app's proxy status using the `proxy:report` command:
@@ -73,15 +76,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 +94,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 +104,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,36 +120,36 @@ 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`
+    - triggers: `post-domains-update`
 - `domains:clear`: Clears out an app's associated domains.
-  - triggers: `post-domains-update`
+    - triggers: `post-domains-update`
 - `domains:disable`: Disables domains for an app.
-  - triggers: `pre-disable-vhost`
+    - triggers: `pre-disable-vhost`
 - `domains:enable`: Enables domains for an app.
-  - triggers: `pre-enable-vhost`
+    - triggers: `pre-enable-vhost`
 - `domains:remove`: Removes a domain from an app.
-  - triggers: `post-domains-update`
+    - triggers: `post-domains-update`
 - `domains:set`: Sets all domains for a given app.
-  - triggers: `post-domains-update`
+    - triggers: `post-domains-update`
 - `proxy:build-config`: Builds - or rebuilds - external proxy configuration.
-  - triggers: `proxy-build-config`
+    - triggers: `proxy-build-config`
 - `proxy:clear-config`: Clears out external proxy configuration.
-  - triggers: `proxy-clear-config`
+    - triggers: `proxy-clear-config`
 - `proxy:disable`: Disables the proxy configuration for an app.
-  - triggers: `proxy-disable`
+    - 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
-  - triggers: `post-proxy-ports-update`
-- `proxy: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.
-  - triggers: `post-proxy-ports-update`
-- `proxy:ports-set`: Sets all port mappings for an app.
-  - triggers: `post-proxy-ports-update`
+    - triggers: `proxy-enable`
+- `ports:add`: Adds one or more port mappings to an app
+    - triggers: `post-proxy-ports-update`
+- `ports:clear`: Clears out all port mappings for an app.
+    - triggers: `post-proxy-ports-update`
+- `ports:remove`: Removes one or more port mappings from an app.
+    - triggers: `post-proxy-ports-update`
+- `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.