Merge pull request #8954 from dokku/dependabot/pip/tests/apps/dockerfile-release/gunicorn-26.1.0

chore(deps): bump gunicorn from 26.0.0 to 26.1.0 in /tests/apps/dockerfile-release

.codacy.yml

@@ -1,10 +0,0 @@
----
-engines:
-  duplication:
-    exclude_paths:
-      - "*"
-exclude_paths:
-  - vendor/**/*
-  - tests/**/*
-  - "**_test.go"
-  - contrib/*

.devcontainer/Dockerfile

@@ -2,14 +2,16 @@ FROM dokku/dokku:latest
 
 RUN apt-get update
 RUN apt-get install --no-install-recommends -y build-essential file nano && \
-  apt-get install --no-install-recommends -y help2man shellcheck uuid-runtime wget xmlstarlet && \
+  apt-get install --no-install-recommends -y software-properties-common help2man shellcheck uuid-runtime wget xmlstarlet && \
   apt-get clean autoclean && \
   apt-get autoremove --yes && \
   rm -rf /var/lib/apt/lists/*
 
 ARG TARGETARCH
-RUN wget https://dl.google.com/go/go1.19.6.linux-${TARGETARCH}.tar.gz && \
-  tar -xvf go1.19.6.linux-${TARGETARCH}.tar.gz && \
+COPY common.mk common.mk
+RUN GOLANG_VERSION=$(grep BUILD_IMAGE common.mk | cut -d' ' -f3 | cut -d':' -f2) && \
+  wget https://dl.google.com/go/go${GOLANG_VERSION}.linux-${TARGETARCH}.tar.gz && \
+  tar -xvf go${GOLANG_VERSION}.linux-${TARGETARCH}.tar.gz && \
   mv go /usr/local
 
 RUN GOROOT=/usr/local/go /usr/local/go/bin/go install golang.org/x/tools/gopls@latest 2>&1

.devcontainer/bin/bump-modules

@@ -0,0 +1,21 @@
+#!/usr/bin/env bash
+
+export GOWORK=off
+pushd /root/go/src/github.com/dokku/dokku/plugins/ >/dev/null || exit 1
+for plugin in *; do
+  if [[ ! -f "/root/go/src/github.com/dokku/dokku/plugins/$plugin/go.mod" ]]; then continue; fi
+  echo "$plugin"
+  pushd /root/go/src/github.com/dokku/dokku/plugins/$plugin || exit 1
+  echo "running go mod tidy for $plugin"
+  if ! go mod tidy; then
+    echo "go mod tidy failed for $plugin"
+    exit 1
+  fi
+  echo "running go mod download for $plugin"
+  if ! go mod download; then
+    echo "go mod download failed for $plugin"
+    exit 1
+  fi
+  popd >/dev/null || exit 1
+done
+popd >/dev/null || exit 1

.devcontainer/bin/deploy-test-app

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+
+main() {
+  declare APP="${1:-test}"
+
+  if ! dokku apps:exists $APP; then
+    dokku apps:create $APP
+  fi
+
+  dokku builder-herokuish:set $APP allowed true
+  dokku git:sync --build $APP https://github.com/dokku/smoke-test-app.git
+}
+
+main "$@"

.devcontainer/bin/setup-dev-env

@@ -3,27 +3,7 @@
 install-go-devtools() {
   go install github.com/go-delve/delve/cmd/dlv@latest
   go install honnef.co/go/tools/cmd/staticcheck@latest
-}
-
-install-go-mods() {
-  local plugin_root="/root/go/src/github.com/dokku/dokku/plugins"
-
-  export GO111MODULE=off
-  echo "-----> Fetching onsi/gomega dependency for tests"
-  go get github.com/onsi/gomega || true
-
-  echo "-----> Fetching spf13/pflag dependency for subcommands"
-  go get github.com/spf13/pflag || true
-  pushd "$plugin_root" >/dev/null || true
-  find "$plugin_root/" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | while read -r plugin; do
-    pushd "$plugin_root/$plugin" >/dev/null || true
-    if [[ -f "go.mod" ]]; then
-      echo "-----> Fetching dependencies for $plugin plugin"
-      go get || true
-    fi
-    popd >/dev/null || true
-  done
-  popd >/dev/null || true
+  go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
 }
 
 setup-ci() {
@@ -34,7 +14,6 @@ setup-ci() {
 }
 
 main() {
-  install-go-mods
   install-go-devtools
   setup-ci
 }

.devcontainer/devcontainer.json

@@ -4,7 +4,9 @@
     "context": ".."
   },
   "containerEnv": {
+    "DOKKU_HOSTNAME": "dokku.me",
     "DOKKU_HOST_ROOT": "${localWorkspaceFolder}/tmp/data/home/dokku",
+    "DOKKU_LIB_HOST_ROOT": "${localWorkspaceFolder}/tmp/data/var/lib/dokku",
     "GO_ROOT_MOUNT": "${localWorkspaceFolder}:/go/src/github.com/dokku/dokku"
   },
   "customizations": {
@@ -13,18 +15,26 @@
         "golang.go",
         "mads-hartmann.bash-ide-vscode",
         "ms-vscode.makefile-tools",
-        "sleistner.vscode-fileutils"
+        "sleistner.vscode-fileutils",
+        "ms-azuretools.vscode-docker"
       ]
     }
   },
-  "initializeCommand": ["mkdir", "-p", "tmp/data"],
+  "initializeCommand": [
+    "mkdir",
+    "-p",
+    "tmp/data"
+  ],
   "mounts": [
     "source=/var/run/docker.sock,target=/var/run/docker.sock,type=bind",
     "source=${localWorkspaceFolder}/tmp/data/,target=/mnt/dokku/,type=bind"
   ],
   "overrideCommand": false,
   "postCreateCommand": "setup-dev-env",
-  "runArgs": ["--init"],
+  "postStartCommand": "printenv > .vscode/devcontainer.env",
+  "runArgs": [
+    "--init"
+  ],
   "workspaceFolder": "/root/go/src/github.com/dokku/dokku",
   "workspaceMount": "type=bind,source=${localWorkspaceFolder},target=/root/go/src/github.com/dokku/dokku,consistency=cached"
-}
+}

.dockerignore

@@ -8,8 +8,11 @@ docs
 tests
 !build/package/*
 !docs/_build/entrypoint
+!docs/_build/hooks.py
 !docs/_build/requirements.txt
 !tests/dhparam.pem
 !contrib/bash-completion
+!contrib/dependencies.json
 !contrib/docker
+!contrib/update-deb-dependencies
 vendor

.editorconfig

@@ -19,3 +19,6 @@ indent_size = 4
 insert_final_newline = true
 indent_style = tab
 indent_size = 4
+
+[*.md]
+tab_width = 4

.github/ISSUE_TEMPLATE/bug_report.yaml

@@ -1,7 +1,8 @@
 ---
 name: Bug Report
 description: File a bug report
-labels: ["needs: investigation", "type: bug"]
+labels: ["needs: investigation"]
+type: Bug
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/documentation.yaml

@@ -0,0 +1,26 @@
+---
+name: Documentation Issue
+description: Let us know that something in the docs needs clarification
+labels: ["needs: investigation", "type: documentation"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Consider [sponsoring Dokku](https://github.com/sponsors/dokku). Sponsorship goes directly to supporting activities such as fixing bugs and general maintenance.
+  - type: input
+    id: docs-link
+    attributes:
+      label: Link to the documentation page
+      description: Which docs page is impacted?
+  - type: textarea
+    id: description
+    attributes:
+      label: Documentation problem
+      description: Describe what you think is incorrect, not well documented, or missing from the documentation
+    validations:
+      required: true
+  - type: textarea
+    id: report-output
+    attributes:
+      label: dokku report
+      description: Please paste the output of the command `dokku report` so we know what systems any issue might apply to

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

@@ -0,0 +1,37 @@
+---
+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@v8
+      with:
+        name: build
+        path: build
+
+    - name: set up docker buildx
+      id: buildx
+      uses: docker/setup-buildx-action@v4
+
+    - name: build docker image
+      shell: bash
+      run: |
+        docker buildx build \
+                --load \
+                --progress plain \
+                --tag "dokku/dokku:latest" \
+                .
+
+    - name: smoke test image
+      shell: bash
+      run: |
+        make test-image-healthcheck IMAGE_TAG=dokku/dokku:latest

.github/commands/bump-azure

@@ -18,7 +18,11 @@ main() {
 
   cd tmp
 
-  $GH_FOLDER/bin/gh auth login --with-token <<<"$BOT_GITHUB_API_TOKEN"
+  if [[ -n "$BOT_GITHUB_API_TOKEN" ]]; then
+    $GH_FOLDER/bin/gh auth login --with-token <<<"$BOT_GITHUB_API_TOKEN"
+  else
+    echo "BOT_GITHUB_API_TOKEN is not set, skipping gh auth login"
+  fi
 
   echo "=====> Cloning quickstart templates"
   rm -rf azure-quickstart-templates >/dev/null
@@ -35,15 +39,29 @@ main() {
   contents="$(jq --arg VERSION "$VERSION" '.parameters.dokkuVersion.defaultValue = $VERSION' application-workloads/dokku/dokku-vm/azuredeploy.json)"
   echo "${contents}" >application-workloads/dokku/dokku-vm/azuredeploy.json
 
+  # update the version in main.bicep
+  # the line being updated looks like this:
+  # param dokkuVersion string = '0.28.4'
+  # we need to update the value of dokkuVersion to the new version
+  sed -i "s/param dokkuVersion string = '[^']*'/param dokkuVersion string = '$VERSION'/" application-workloads/dokku/dokku-vm/main.bicep
+
   echo "=====> Updating remote repository"
   git add application-workloads/dokku/dokku-vm
   git checkout -b dokku-$VERSION
   git commit -m "Update dokku-vm dokku version to $VERSION"
-  git remote set-url origin "https://$BOT_GITHUB_USERNAME:$BOT_GITHUB_API_TOKEN@github.com/dokku/azure-quickstart-templates.git"
-  git push -f origin dokku-$VERSION
+  if [[ -z "$BOT_GITHUB_API_TOKEN" ]] || [[ -z "$BOT_GITHUB_USERNAME" ]]; then
+    echo "BOT_GITHUB_API_TOKEN or BOT_GITHUB_USERNAME is not set, skipping git remote set-url"
+  else
+    git remote set-url origin "https://$BOT_GITHUB_USERNAME:$BOT_GITHUB_API_TOKEN@github.com/dokku/azure-quickstart-templates.git"
+    git push -f origin dokku-$VERSION
+  fi
 
-  echo "=====> Creating upstream pull request"
-  ../$GH_FOLDER/bin/gh pr create --head dokku:dokku-$VERSION --repo Azure/azure-quickstart-templates --title "Update dokku-vm dokku version to $VERSION" --body ''
+  if [[ -z "$BOT_GITHUB_API_TOKEN" ]] || [[ -z "$BOT_GITHUB_USERNAME" ]]; then
+    echo "BOT_GITHUB_API_TOKEN or BOT_GITHUB_USERNAME is not set, skipping gh pr create"
+  else
+    echo "=====> Creating upstream pull request"
+    ../$GH_FOLDER/bin/gh pr create --head dokku:dokku-$VERSION --repo Azure/azure-quickstart-templates --title "Update dokku-vm dokku version to $VERSION" --body ''
+  fi
 
   popd &>/dev/null
 }

.github/commands/ci-setup

@@ -1,20 +1,24 @@
 #!/usr/bin/env bash
 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
+echo "CI_SERVER_IP=${internal_ip}" >>"$GITHUB_ENV"
+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

@@ -85,6 +85,13 @@ updates:
     open-pull-requests-limit: 2
     labels:
       - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/ports"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
   - package-ecosystem: gomod
     directory: "/plugins/proxy"
     schedule:
@@ -120,6 +127,20 @@ updates:
     open-pull-requests-limit: 2
     labels:
       - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/scheduler-docker-local"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: gomod
+    directory: "/plugins/scheduler-k3s"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 2
+    labels:
+      - "type: dependencies"
   - package-ecosystem: gomod
     directory: "/plugins/scheduler"
     schedule:
@@ -127,150 +148,181 @@ updates:
     open-pull-requests-limit: 2
     labels:
       - "type: dependencies"
+  - package-ecosystem: "docker"
+    directory: "/plugins/caddy-vhosts"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: "docker"
+    directory: "/plugins/haproxy-vhosts"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: "docker"
+    directory: "/plugins/logs"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: "docker"
+    directory: "/plugins/openresty-vhosts"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: dependencies"
+  - package-ecosystem: "docker"
+    directory: "/plugins/traefik-vhosts"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: dependencies"
   - package-ecosystem: bundler
     directory: "/tests/apps/ruby"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: bundler
     directory: "/tests/apps/multi"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/checks-root"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/config"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/dockerfile-app-json-formations"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/dockerfile-noexpose"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/dockerfile-procfile-bad"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/dockerfile-procfile"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/dockerfile"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/gitsubmodules"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: gomod
     directory: "/tests/apps/gogrpc"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
-    ignore:
-      - dependency-name: google.golang.org/grpc
-        versions:
-          - "> 1.29.1"
+      - "type: tests"
   - package-ecosystem: pip
     directory: "/tests/apps/multi"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: maven
     directory: "/tests/apps/java"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
+  - package-ecosystem: npm
+    directory: "/tests/apps/multi"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/nodejs-express"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/nodejs-worker"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/nodejs-express-noappjson"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: npm
     directory: "/tests/apps/nodejs-express-noprocfile"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: composer
     directory: "/tests/apps/php"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: pip
     directory: "/tests/apps/python-flask"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
-  - package-ecosystem: npm
-    directory: "/tests/apps/.websocket.disabled"
-    schedule:
-      interval: daily
-    open-pull-requests-limit: 10
-    labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: github-actions
     directory: "/"
     schedule:
@@ -278,6 +330,11 @@ updates:
     open-pull-requests-limit: 10
     labels:
       - "type: dependencies"
+    ignore:
+      - dependency-name: "*"
+        update-types:
+          - "version-update:semver-minor"
+          - "version-update:semver-patch"
   - package-ecosystem: "docker"
     directory: "/"
     schedule:
@@ -291,84 +348,91 @@ updates:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/dockerfile"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/dockerfile-procfile"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/dockerfile-entrypoint"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/dockerfile-procfile-bad"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/go-fail-predeploy"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/zombies-dockerfile-no-tini"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/dockerfile-release"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
+  - package-ecosystem: pip
+    directory: "/tests/apps/dockerfile-release"
+    schedule:
+      interval: daily
+    open-pull-requests-limit: 10
+    labels:
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/dockerfile-app-json-formations"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/gogrpc"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/zombies-dockerfile-tini"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/tests/apps/go-fail-postdeploy"
     schedule:
       interval: daily
     open-pull-requests-limit: 10
     labels:
-      - "type: dependencies"
+      - "type: tests"
   - package-ecosystem: "docker"
     directory: "/docs/_build"
     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/linters/.yamllint.yml

@@ -3,3 +3,6 @@ extends: default
 
 rules:
   line-length: disable
+
+ignore:
+  - plugins/scheduler-k3s/templates/*

.github/workflows/ci.yml

@@ -14,14 +14,17 @@ 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
+    runs-on: ubuntu-24.04
     outputs:
       skip: ${{ steps.check-commit.outputs.skip }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
         with:
           ref: ${{ github.event.pull_request.head.sha }}
 
@@ -40,7 +43,7 @@ jobs:
 
   build:
     name: build
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     needs: check-commit
     if: ${{ needs.check-commit.outputs.skip != 'true' }}
     outputs:
@@ -50,14 +53,14 @@ jobs:
     timeout-minutes: 45
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
 
       - name: set up qemu
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v4
 
       - name: set up docker buildx
         id: buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v4
 
       - name: build package
         run: ./tests/ci/setup.sh build
@@ -67,65 +70,57 @@ jobs:
       - name: set matrix for build
         id: set-matrix
         run: |
-          json=$(python .github/commands/matrix)
+          json=$(python3 .github/commands/matrix)
           echo $json
           echo "matrix=$json" >> $GITHUB_OUTPUT
 
       - name: upload packages
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v7
         with:
           name: build
           path: build
 
-  build-image:
-    name: build-image.${{ matrix.architecture }}
+  build-image-amd64:
+    name: build-image.linux/amd64
     needs: build
-    runs-on: ubuntu-20.04
-    strategy:
-      fail-fast: false
-      matrix:
-        architecture:
-          - linux/amd64
-          - linux/arm
-          - linux/arm64
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
 
-      - name: download packages
-        uses: actions/download-artifact@v3
+      - name: build-image
+        uses: ./.github/actions/build-image
         with:
-          name: build
-          path: build
+          architecture: linux/amd64
 
-      - name: set up qemu
-        uses: docker/setup-qemu-action@v2
+  build-image-arm64:
+    name: build-image.linux/arm64
+    needs: build
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 20
 
-      - name: set up docker buildx
-        id: buildx
-        uses: docker/setup-buildx-action@v2
+    steps:
+      - uses: actions/checkout@v7
 
-      - name: build docker image
-        run: |
-          docker buildx build \
-                --platform ${{ matrix.architecture }} \
-                --progress plain \
-                --tag "dokku/dokku:latest" \
-                .
+      - name: build-image
+        uses: ./.github/actions/build-image
+        with:
+          architecture: linux/arm64
 
   unit-tests:
     name: unit.${{ matrix.index }}
     needs: build
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix: ${{fromJson(needs.build.outputs.matrix)}}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
 
       - name: download packages
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v8
         with:
           name: build
           path: build
@@ -137,7 +132,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
@@ -148,7 +143,7 @@ jobs:
           SYNC_GITHUB_PASSWORD: ${{ secrets.SYNC_GITHUB_PASSWORD }}
           SYNC_GITHUB_USERNAME: ${{ secrets.SYNC_GITHUB_USERNAME }}
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v7
         with:
           name: test-results-${{ matrix.index }}
           path: test-results
@@ -156,15 +151,15 @@ jobs:
   docker-deploy-tests:
     name: docker
     needs: build
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
 
       - name: download packages
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v8
         with:
           name: build
           path: build
@@ -172,17 +167,21 @@ jobs:
       - name: ci-setup
         run: ./.github/commands/ci-setup
 
+      - name: docker-container-setup
+        run: |
+          ./tests/ci/setup.sh docker
+
       - name: test docker deploys
         shell: bash
         timeout-minutes: 20
         run: |
-          ./tests/ci/setup.sh docker
+          docker exec dokku bash -c "cat /etc/sudoers.d/dokku-nginx"
           DOKKU_SSH_PORT=3022 sudo -E make -e test-ci-docker
 
   go-tests:
     name: go.${{ matrix.index }}
     needs: build
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     strategy:
       fail-fast: false
       matrix:
@@ -191,10 +190,10 @@ jobs:
       GITHUB_NODE_INDEX: ${{ matrix.index }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
 
       - name: download packages
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v8
         with:
           name: build
           path: build
@@ -215,7 +214,7 @@ jobs:
             2) sudo -E make -e deploy-test-multi ;;
             3) sudo -E make -e deploy-test-go-fail-predeploy deploy-test-go-fail-postdeploy ;;
           esac
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v7
         with:
           name: coverage.${{ matrix.index }}
           path: test-results/coverage
@@ -223,7 +222,7 @@ jobs:
   publish-test-results:
     name: publish-test-results
     needs: unit-tests
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     permissions:
       checks: write
     # the build-and-test job might be skipped, we don't need to run this job then
@@ -231,7 +230,7 @@ jobs:
 
     steps:
       - name: download test-results
-        uses: actions/download-artifact@v3
+        uses: actions/download-artifact@v8
         with:
           path: test-results
 
@@ -240,5 +239,5 @@ jobs:
         with:
           check_name: Unit Test Results
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          junit_files: test-results/**/*.xml
+          files: test-results/**/*.xml
           comment_mode: "off"

.github/workflows/codeql-analysis.yml

@@ -23,10 +23,14 @@ on:
   schedule:
     - cron: '18 22 * * 2'
 
+concurrency:
+  group: codeql-analysis-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   analyze:
     name: Analyze
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
 
     strategy:
       fail-fast: false
@@ -38,11 +42,15 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
+
+      # workaround for https://github.com/github/codeql/issues/14235
+      - name: Remove go.work file
+        run: rm go.work
 
       # Initializes the CodeQL tools for scanning.
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v2
+        uses: github/codeql-action/init@v4
         with:
           languages: ${{ matrix.language }}
           # If you wish to specify custom queries, you can do so here or in a config file.
@@ -53,7 +61,7 @@ jobs:
       # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
       # If this step fails, then you should remove it and run the build manually (see below)
       - name: Autobuild
-        uses: github/codeql-action/autobuild@v2
+        uses: github/codeql-action/autobuild@v4
 
       # ℹ️ Command-line programs to run using the OS shell.
       # 📚 https://git.io/JvXDl
@@ -62,9 +70,5 @@ jobs:
       #    and modify them (or add more) to build your code if your project
       #    uses a compiled language
 
-      # - run: |
-      #   make bootstrap
-      #   make release
-
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v2
+        uses: github/codeql-action/analyze@v4

.github/workflows/dependency-updates.yml

@@ -0,0 +1,110 @@
+---
+name: 'dependency-updates'
+
+# yamllint disable-line rule:truthy
+on:
+  schedule:
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    name: prepare
+    runs-on: ubuntu-24.04
+    outputs:
+      matrix: ${{ steps.matrix.outputs.matrix }}
+    steps:
+      - name: Clone
+        uses: actions/checkout@v7
+
+      - name: Build dependency matrix
+        id: matrix
+        run: |
+          matrix=$(jq -c '
+            [
+              (.dependencies[]      | {section: "dependencies",      name, version, url: .urls.amd64}),
+              (.predependencies[]   | {section: "predependencies",   name, version, url: .urls.amd64}),
+              (.recommendations[]   | {section: "recommendations",   name, version, url: .urls.amd64})
+            ]
+            | map(. + {repo: (.url | capture("https://github.com/(?<r>[^/]+/[^/]+)/releases").r)})
+            | map(del(.url))
+            | {include: .}
+          ' contrib/dependencies.json)
+          echo "matrix=${matrix}" >> "$GITHUB_OUTPUT"
+
+  update:
+    name: 'update / ${{ matrix.name }}'
+    runs-on: ubuntu-24.04
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix: ${{ fromJson(needs.prepare.outputs.matrix) }}
+    concurrency:
+      group: dependency-updates-${{ matrix.name }}
+      cancel-in-progress: false
+    steps:
+      - name: Clone
+        uses: actions/checkout@v7
+
+      - name: Resolve latest release
+        id: latest
+        env:
+          GH_TOKEN: ${{ secrets.HOMEBREW_GITHUB_API_TOKEN }}
+          REPO: ${{ matrix.repo }}
+          CURRENT: ${{ matrix.version }}
+        run: |
+          tag=$(gh release view --repo "$REPO" --json tagName -q .tagName)
+          latest="${tag#v}"
+          echo "latest=${latest}" >> "$GITHUB_OUTPUT"
+          if dpkg --compare-versions "$latest" gt "$CURRENT"; then
+            echo "outdated=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "outdated=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Bump dependency entry
+        if: steps.latest.outputs.outdated == 'true'
+        env:
+          SECTION: ${{ matrix.section }}
+          NAME: ${{ matrix.name }}
+          OLD: ${{ matrix.version }}
+          NEW: ${{ steps.latest.outputs.latest }}
+        run: |
+          tmp=$(mktemp)
+          jq --arg section "$SECTION" \
+             --arg name "$NAME" \
+             --arg old "$OLD" \
+             --arg new "$NEW" '
+            ($old) as $oldv |
+            ($new) as $newv |
+            (.[$section]) |= map(
+              if .name == $name then
+                .version = $newv
+                | .urls.amd64 |= (gsub("v" + $oldv; "v" + $newv) | gsub($oldv; $newv))
+                | .urls.arm64 |= (gsub("v" + $oldv; "v" + $newv) | gsub($oldv; $newv))
+              else . end
+            )
+          ' contrib/dependencies.json > "$tmp"
+          mv "$tmp" contrib/dependencies.json
+
+      - name: Open pull request
+        if: steps.latest.outputs.outdated == 'true'
+        uses: peter-evans/create-pull-request@v8
+        with:
+          token: ${{ secrets.HOMEBREW_GITHUB_API_TOKEN }}
+          branch: chore/bump-${{ matrix.name }}-${{ steps.latest.outputs.latest }}
+          base: ${{ github.ref_name }}
+          delete-branch: true
+          committer: 'Dokku Bot <no-reply@dokku.com>'
+          author: 'Dokku Bot <no-reply@dokku.com>'
+          commit-message: 'chore: bump ${{ matrix.name }} to ${{ steps.latest.outputs.latest }}'
+          title: 'chore: bump ${{ matrix.name }} to ${{ steps.latest.outputs.latest }}'
+          body: |
+            Bumps `${{ matrix.name }}` from `${{ matrix.version }}` to `${{ steps.latest.outputs.latest }}`.
+
+            Release notes: https://github.com/${{ matrix.repo }}/releases/tag/v${{ steps.latest.outputs.latest }}
+          labels: 'type: dependencies'

.github/workflows/docs.yml

@@ -7,17 +7,21 @@ on:
     branches:
       - master
 
+concurrency:
+  group: docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   deploy:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-24.04
     steps:
       - name: Cloning repo
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
       - name: "Setup python 3.10"
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v7
         with:
           python-version: '3.10'
 

.github/workflows/lint.yml

@@ -10,36 +10,45 @@ on:
     branches:
       - 'master'
 
+concurrency:
+  group: lint-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   hadolint:
     name: hadolint
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Run hadolint
-        uses: hadolint/hadolint-action@54c9adbab1582c2ef04b2016b760714a4bfde3cf
+        uses: hadolint/hadolint-action@2332a7b74a6de0dda2e2221d575162eba76ba5e5
         # v3.0.0 => 4b5806eb9c6bee4954fc0e0cc3ad6175fc9782c1
 
   markdown-lint:
     name: markdown-lint
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v3
-      - name: Run markdown-lint
-        uses: avto-dev/markdown-lint@04d43ee9191307b50935a753da3b775ab695eceb
-        # v1.5.0 => 04d43ee9191307b50935a753da3b775ab695eceb
+        uses: actions/checkout@v7
+      - name: Setup node
+        uses: actions/setup-node@v7
         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
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
+    if: github.event.pull_request.user.login != 'dependabot[bot]'
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Setup packer
         uses: hashicorp/setup-packer@main
         with:
@@ -48,38 +57,29 @@ jobs:
         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@v37.5.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:
     name: shellcheck
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - 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
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Run shfmt
-        uses: luizm/action-sh-checker@76ab0b22e1f194e4a582edc7969df6485c4e9246
+        uses: luizm/action-sh-checker@883217215b11c1fabbf00eb1a9a041f62d74c744
         # v0.5.0 => edd0e45ecff35b05f162052b50df50976c1b74fc
         env:
           SHFMT_OPTS: -l -bn -ci -i 2 -d
@@ -88,10 +88,10 @@ jobs:
 
   yamllint:
     name: yamllint
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     steps:
       - name: Clone
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Run yamllint
         uses: ibiqlik/action-yamllint@2576378a8e339169678f9939646ee3ee325e845c
         # v3.1.1 => 2576378a8e339169678f9939646ee3ee325e845c

.github/workflows/release.yml

@@ -1,44 +1,50 @@
 ---
-name: 'release'
+name: "release"
 
 # yamllint disable-line rule:truthy
 on:
   workflow_dispatch:
     inputs:
       release_type:
-        description: 'Release type [build, betafish, patch, minor, major]'
+        description: "Release type"
+        default: "patch"
         required: true
-        default: 'build'
-
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+          - build
+          - betafish
 jobs:
   release:
     name: release
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     env:
       PACKAGECLOUD_TOKEN: ${{ secrets.PACKAGECLOUD_TOKEN }}
     outputs:
       version: ${{ steps.version.outputs.version }}
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v7
         with:
           fetch-depth: 0
 
       - uses: ruby/setup-ruby@v1
         with:
-          ruby-version: 2.6
+          ruby-version: 2.7
 
       - name: login to docker hub
-        uses: docker/login-action@v2
+        uses: docker/login-action@v4
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: set up qemu
-        uses: docker/setup-qemu-action@v2
+        uses: docker/setup-qemu-action@v4
 
       - name: set up docker buildx
         id: buildx
-        uses: docker/setup-buildx-action@v2
+        uses: docker/setup-buildx-action@v4
 
       - name: inspect builder
         run: |
@@ -67,18 +73,18 @@ jobs:
         run: echo "version=$(cat build/next-version)" >> $GITHUB_OUTPUT
 
       - name: upload packages
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v7
         with:
           name: build
           path: build
 
   build-digitalocean:
     name: build-digitalocean
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     needs: release
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
 
       - name: Setup packer
         uses: hashicorp/setup-packer@main
@@ -103,18 +109,18 @@ jobs:
           PKR_VAR_dokku_version="${VERSION:1}" make image/build/digitalocean
 
       - name: upload packages
-        uses: actions/upload-artifact@v3
+        uses: actions/upload-artifact@v7
         with:
           name: digitalocean-manifest.json
           path: digitalocean-manifest.json
 
   bump-azure:
     name: bump-azure
-    runs-on: ubuntu-20.04
+    runs-on: ubuntu-24.04
     needs: release
     steps:
       - name: Checkout code
-        uses: actions/checkout@v3
+        uses: actions/checkout@v7
       - name: Bump Azure Template
         env:
           BOT_GITHUB_USERNAME: ${{ secrets.HOMEBREW_GITHUB_USERNAME }}
@@ -130,6 +136,31 @@ jobs:
     runs-on: macos-latest
     needs: release
     steps:
+      - name: Brew doctor
+        run: |
+          brew doctor || true
+      - name: Brew cleanup
+        run: |
+          echo "====> Running brew cleanup"
+          brew cleanup || true
+          echo "====> Untapping homebrew/core"
+          brew untap homebrew/core || true
+          echo "====> Untapping homebrew/cask"
+          brew untap homebrew/cask || true
+          echo "====> Untapping aws/tap"
+          brew untap aws/tap || true
+          echo "====> Untapping hashicorp/tap"
+          brew untap hashicorp/tap || true
+          echo "====> Uninstalling openssl@1.1"
+          brew uninstall openssl@1.1 || true
+          echo "====> Uninstalling ruby@3.0"
+          brew uninstall ruby@3.0 || true
+          echo "====> Running brew cleanup"
+          brew cleanup || true
+      - name: Brew doctor
+        run: brew doctor || true
+      - name: Brew config
+        run: brew config
       - name: Bump Homebrew Formula
         env:
           HOMEBREW_GITHUB_USERNAME: ${{ secrets.HOMEBREW_GITHUB_USERNAME }}

.gitignore

@@ -11,3 +11,6 @@ test-results/
 stack.tgz
 tmp
 coverage.out
+site
+go.work.sum
+node_modules

.golangci-lint.yml

@@ -0,0 +1,24 @@
+---
+run:
+  timeout: 5m
+
+linters:
+  disable-all: true
+
+  enable:
+    - errcheck
+    - goconst
+    - gocyclo
+    - gofumpt
+    - gosec
+    - gosimple
+    - govet
+    - ineffassign
+    - misspell
+    - revive
+    - staticcheck
+    - typecheck
+    - unconvert
+    - unparam
+    - unused
+    - whitespace

.prettierignore

@@ -0,0 +1 @@
+*.md

.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/*'

.well-known/funding-manifest-urls

@@ -0,0 +1 @@
+https://dokku.com/funding.json

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,12 +92,12 @@ 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
 
-All changes should be be based on the latest master commit.
+All changes should be based on the latest master commit.
 
 ### Submitting Changes
 

Dockerfile

@@ -1,4 +1,4 @@
-FROM phusion/baseimage:focal-1.2.0
+FROM phusion/baseimage:noble-1.0.3
 
 CMD ["/sbin/my_init"]
 
@@ -15,26 +15,44 @@ RUN addgroup --gid $DOKKU_GID dokku \
 
 COPY ./tests/dhparam.pem /tmp/dhparam.pem
 COPY ./build/package/ /tmp
+COPY ./contrib/dependencies.json /tmp/dependencies.json
+
+ENV DOKKU_INIT_SYSTEM=sv
 
 SHELL ["/bin/bash", "-o", "pipefail", "-c"]
 # hadolint ignore=DL3005,DL3008
 RUN mkdir -p /etc/apt/keyrings \
   && mkdir -p /etc/apt/keyrings \
+  && apt-get remove -y systemd && apt-get autoremove -y && apt-get update && apt-get -y --no-install-recommends install gpg jq lsb-release openssl openssh-server rsync software-properties-common \
   && curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /etc/apt/keyrings/docker.gpg \
   && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null \
   && apt-get update \
-  && apt-get -y --no-install-recommends install docker-ce docker-ce-cli containerd.io docker-compose-plugin \
+  && apt-get -y --no-install-recommends install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin \
+  && PACK_URL="$(jq -r --arg arch "$(dpkg --print-architecture)" '.dependencies[] | select(.name == "pack") | .urls[$arch]' /tmp/dependencies.json)" \
+  && curl -fsSL "$PACK_URL" | tar -C /usr/bin/ --no-same-owner -xzf - pack \
+  && chmod +x /usr/bin/pack \
+  && test -x /usr/bin/pack \
+  && curl -o /tmp/nixpacks.bash -sSL https://nixpacks.com/install.sh \
+  && chmod +x /tmp/nixpacks.bash \
+  && NIXPACKS_BIN_DIR=/usr/bin BIN_DIR=/usr/bin /tmp/nixpacks.bash \
+  && test -x /usr/bin/nixpacks \
+  && rm -rf /tmp/nixpacks.bash \
+  && curl -o /tmp/railpack.bash -sSL https://railpack.com/install.sh \
+  && chmod +x /tmp/railpack.bash \
+  && RAILPACK_BIN_DIR=/usr/bin BIN_DIR=/usr/bin /tmp/railpack.bash \
+  && test -x /usr/bin/railpack \
+  && rm -rf /tmp/railpack.bash \
   && echo "dokku dokku/hostname string $DOKKU_HOSTNAME" | debconf-set-selections \
   && echo "dokku dokku/skip_key_file boolean $DOKKU_SKIP_KEY_FILE" | debconf-set-selections \
   && echo "dokku dokku/vhost_enable boolean $DOKKU_VHOST_ENABLE" | debconf-set-selections \
+  && echo "dokku dokku/install_default_site boolean true" | debconf-set-selections \
   && curl -sSL https://packagecloud.io/dokku/dokku/gpgkey | apt-key add - \
-  && echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ focal main" | tee /etc/apt/sources.list.d/dokku.list \
+  && echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ noble main" | tee /etc/apt/sources.list.d/dokku.list \
   && mkdir -p /etc/nginx/ \
   && cp /tmp/dhparam.pem /etc/nginx/dhparam.pem \
   && apt-get update \
   && apt-get upgrade -y \
-  && apt-get -y --no-install-recommends --only-upgrade install openssl openssh-server \
-  && apt-get -y --no-install-recommends install rsync "/tmp/dokku-$(dpkg --print-architecture).deb" \
+  && apt-get -y --no-install-recommends install lambda-builder "/tmp/dokku-$(dpkg --print-architecture).deb" \
   && apt-get purge -y syslog-ng-core \
   && apt-get autoremove -y \
   && apt-get clean && rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
@@ -45,6 +63,7 @@ COPY ./docker .
 
 RUN \
   rsync -a /tmp/ / \
+  && chmod +x /usr/local/bin/* \
   && rm -rf /tmp/* \
   && rm /etc/runit/runsvdir/default/sshd/down \
   && chown -R dokku:dokku /home/dokku/ \
@@ -63,3 +82,6 @@ RUN \
   && rm -f /usr/local/openresty/nginx/conf/sites-enabled/default /usr/share/openresty/html/index.html \
   && sed -i '/imklog/d' /etc/rsyslog.conf \
   && rm -f /var/log/btmp /var/log/wtmp /var/log/*log /var/log/apt/* /var/log/dokku/*.log /var/log/nginx/* /var/log/openresty/*
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5m --retries=3 \
+  CMD curl -fsS http://127.0.0.1:18080/_dokku/health || exit 1

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,23 +2,16 @@ DOKKU_VERSION ?= master
 
 TARGETARCH ?= amd64
 
-DOCKER_IMAGE_LABELER_VERSION ?= 0.5.0
-HEROKUISH_VERSION ?= 0.6.0
-LAMBDA_BUILDER_VERSION ?= 0.4.0
-NETRC_VERSION ?= 0.6.0
-PLUGN_VERSION ?= 0.12.0
-PROCFILE_VERSION ?= 0.15.0
-SIGIL_VERSION ?= 0.9.0
-SSHCOMMAND_VERSION ?= 0.16.0
-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
-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
-PROCFILE_UTIL_URL ?= https://github.com/josegonzalez/go-procfile-util/releases/download/v${PROCFILE_VERSION}/procfile-util_${PROCFILE_VERSION}_linux_${TARGETARCH}.tgz
-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
+DOCKER_IMAGE_LABELER_URL ?= $(shell jq -r --arg name docker-image-labeler --arg arch $(TARGETARCH) '.dependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+DOCKER_CONTAINER_HEALTHCHECKER_URL ?= $(shell jq -r --arg name docker-container-healthchecker  --arg arch $(TARGETARCH) '.dependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+LAMBDA_BUILDER_URL ?= $(shell jq -r --arg name lambda-builder  --arg arch $(TARGETARCH) '.dependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+NETRC_URL ?= $(shell jq -r --arg name netrc  --arg arch $(TARGETARCH) '.dependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+PLUGN_URL ?= $(shell jq -r --arg name plugn  --arg arch $(TARGETARCH) '.predependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+PROCFILE_UTIL_URL ?= $(shell jq -r --arg name procfile-util  --arg arch $(TARGETARCH) '.dependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+SIGIL_URL ?= $(shell jq -r --arg name gliderlabs-sigil  --arg arch $(TARGETARCH) '.predependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
+SSHCOMMAND_URL ?= $(shell jq -r --arg name sshcommand  --arg arch $(TARGETARCH) '.dependencies[] | select(.name == $$name) | .urls[$$arch]' contrib/dependencies.json)
 STACK_URL ?= https://github.com/gliderlabs/herokuish.git
-PREBUILT_STACK_URL ?= gliderlabs/herokuish:latest-20
+PREBUILT_STACK_URL ?= gliderlabs/herokuish:latest-24
 DOKKU_LIB_ROOT ?= /var/lib/dokku
 PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/plugins
 CORE_PLUGINS_PATH ?= ${DOKKU_LIB_ROOT}/core-plugins
@@ -61,7 +54,7 @@ go-build:
 	basedir=$(PWD); \
 	for dir in plugins/*; do \
 		if [ -e $$dir/Makefile ]; then \
-			$(MAKE) -e -C $$dir $(PLUGIN_MAKE_TARGET) || exit $$? ;\
+			GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) GOWORK=off $(MAKE) -e -C $$dir $(PLUGIN_MAKE_TARGET) || exit $$? ;\
 		fi ;\
 	done
 
@@ -71,7 +64,7 @@ ifndef PLUGIN_NAME
 	$(error PLUGIN_NAME not specified)
 endif
 	if [ -e plugins/$(PLUGIN_NAME)/Makefile ]; then \
-		$(MAKE) -e -C plugins/$(PLUGIN_NAME) $(PLUGIN_MAKE_TARGET) || exit $$? ;\
+		GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) GOWORK=off $(MAKE) -e -C plugins/$(PLUGIN_NAME) $(PLUGIN_MAKE_TARGET) || exit $$? ;\
 	fi
 
 go-clean:
@@ -82,9 +75,12 @@ go-clean:
 		fi ;\
 	done
 
-copyfiles:
-	$(MAKE) go-build || exit 1
+copydokku:
 	cp dokku /usr/local/bin/dokku
+	chmod 0755 /usr/local/bin/dokku
+
+copyfiles: copydokku
+	$(MAKE) go-build || exit 1
 	mkdir -p ${CORE_PLUGINS_PATH} ${PLUGINS_PATH}
 	rm -rf ${CORE_PLUGINS_PATH}/*
 	test -d ${CORE_PLUGINS_PATH}/enabled || PLUGIN_PATH=${CORE_PLUGINS_PATH} plugn init
@@ -135,7 +131,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 jq docker-image-labeler docker-container-healthchecker lambda-builder netrc sshcommand plugn procfile-util docker help2man man-db sigil dos2unix parallel
 	$(MAKE) -e stack
 
 apt-update:
@@ -157,38 +153,36 @@ man-db:
 	apt-get -qq -y --no-install-recommends install man-db
 
 docker-image-labeler:
-	wget -qO /tmp/docker-image-labeler_latest.tgz ${DOCKER_IMAGE_LABELER_URL}
-	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
+	wget -qO /usr/local/bin/docker-image-labeler ${DOCKER_IMAGE_LABELER_URL}
+	chmod +x /usr/local/bin/docker-image-labeler
+
+docker-container-healthchecker:
+	wget -qO /usr/local/bin/docker-container-healthchecker ${DOCKER_CONTAINER_HEALTHCHECKER_URL}
+	chmod +x /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
-	mv /usr/local/bin/lambda-builder-${TARGETARCH} /usr/local/bin/lambda-builder
+	wget -qO /usr/local/bin/lambda-builder ${LAMBDA_BUILDER_URL}
+	chmod +x /usr/local/bin/lambda-builder
 
 netrc:
-	wget -qO /tmp/netrc_latest.tgz ${NETRC_URL}
-	tar xzf /tmp/netrc_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/netrc-${TARGETARCH} /usr/local/bin/netrc
+	wget -qO /usr/local/bin/netrc ${NETRC_URL}
+	chmod +x /usr/local/bin/netrc
 
 procfile-util:
-	wget -qO /tmp/procfile-util_latest.tgz ${PROCFILE_UTIL_URL}
-	tar xzf /tmp/procfile-util_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/procfile-util-${TARGETARCH} /usr/local/bin/procfile-util
+	wget -qO /usr/local/bin/procfile-util ${PROCFILE_UTIL_URL}
+	chmod +x /usr/local/bin/procfile-util
 
 plugn:
-	wget -qO /tmp/plugn_latest.tgz ${PLUGN_URL}
-	tar xzf /tmp/plugn_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/plugn-${TARGETARCH} /usr/local/bin/plugn
+	wget -qO /usr/local/bin/plugn ${PLUGN_URL}
+	chmod +x /usr/local/bin/plugn
 
 sigil:
-	wget -qO /tmp/sigil_latest.tgz ${SIGIL_URL}
-	tar xzf /tmp/sigil_latest.tgz -C /usr/local/bin
-	mv /usr/local/bin/gliderlabs-sigil-${TARGETARCH} /usr/local/bin/sigil
+	wget -qO /usr/local/bin/sigil ${SIGIL_URL}
+	chmod +x /usr/local/bin/sigil
 
 sshcommand:
-	wget -qO /tmp/sshcommand_latest.tgz ${SSHCOMMAND_URL}
-	tar xzf /tmp/sshcommand_latest.tgz -C /usr/local/bin
+	wget -qO /usr/local/bin/sshcommand ${SSHCOMMAND_URL}
+	chmod +x /usr/local/bin/sshcommand
 	sshcommand create dokku /usr/local/bin/dokku
 
 docker:
@@ -232,3 +226,8 @@ vagrant-acl-add:
 
 vagrant-dokku:
 	vagrant ssh -- "sudo -H -u root bash -c 'dokku $(RUN_ARGS)'"
+
+IMAGE_TAG ?= dokku/dokku:latest
+
+test-image-healthcheck:
+	IMAGE_TAG=$(IMAGE_TAG) ./tests/image/healthcheck.sh

README.md

@@ -1,6 +1,6 @@
 # Dokku
 
-[![Build Status](https://github.com/dokku/dokku/workflows/CI/badge.svg)](https://github.com/dokku/dokku/actions?query=workflow%3ACI)
+[![Build Status](https://github.com/dokku/dokku/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/dokku/dokku/actions?query=branch%3Amaster)
 [![Ubuntu Package](https://img.shields.io/badge/package-ubuntu-brightgreen.svg?style=flat-square "Ubuntu Package")](https://packagecloud.io/dokku/dokku)
 [![Arch Package](https://img.shields.io/badge/package-arch-brightgreen.svg?style=flat-square "Arch Package")](https://aur.archlinux.org/packages/dokku/)
 [![Slack Group](https://img.shields.io/badge/irc-slack-blue.svg?style=flat-square "Slack Group")](https://slack.dokku.com/)
@@ -74,9 +74,8 @@ Support us with a monthly donation and help us continue our activities. [[Become
 
 A fresh VM running any of the following operating systems:
 
-- Ubuntu 20.04 / 22.04 x64 - Any currently supported release
-- Debian 10+ x64
-- Arch Linux x64 *(experimental)*
+- Ubuntu 22.04 / 24.04 (amd64/arm64) - Any currently supported release
+- Debian 11+ (amd64/arm64)
 
 An SSH keypair that can be used for application deployment. If this exists before installation, it will be automatically imported into dokku.
 Otherwise, you will need to import the keypair manually after installation using `dokku ssh-keys:add`.
@@ -86,8 +85,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 -NP . https://dokku.com/install/v0.30.10/bootstrap.sh
-sudo DOKKU_TAG=v0.30.10 bash bootstrap.sh
+wget -NP . https://dokku.com/install/v0.38.27/bootstrap.sh
+sudo DOKKU_TAG=v0.38.27 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.

Vagrantfile

@@ -1,7 +1,7 @@
 # -*- mode: ruby -*-
 # vi: set ft=ruby :
 
-BOX_NAME = ENV["BOX_NAME"] || "bento/ubuntu-20.04"
+BOX_NAME = ENV["BOX_NAME"] || "bento/ubuntu-24.04"
 BOX_CPUS = ENV["BOX_CPUS"] || "1"
 BOX_MEMORY = ENV["BOX_MEMORY"] || "1024"
 DOKKU_DOMAIN = ENV["DOKKU_DOMAIN"] || "dokku.me"
@@ -9,7 +9,7 @@ DOKKU_IP = ENV["DOKKU_IP"] || "10.0.0.2"
 PREBUILT_STACK_URL = File.exist?("#{File.dirname(__FILE__)}/stack.tgz") ? 'file:///root/dokku/stack.tgz' : nil
 PUBLIC_KEY_PATH = "#{Dir.home}/.ssh/id_rsa.pub"
 
-make_cmd = "DEBIAN_FRONTEND=noninteractive make -e install"
+make_cmd = "TARGETARCH=$(dpkg --print-architecture) DEBIAN_FRONTEND=noninteractive make -e install"
 if PREBUILT_STACK_URL
   make_cmd = "PREBUILT_STACK_URL='#{PREBUILT_STACK_URL}' #{make_cmd}"
 end
@@ -39,9 +39,11 @@ Vagrant::configure("2") do |config|
   end
 
   config.vm.define "empty", autostart: false
+  config.vm.synced_folder ".", "/vagrant", type: "nfs", nfs_version: 4, nfs_udp: false
+
 
   config.vm.define "dokku", primary: true do |vm|
-    vm.vm.synced_folder File.dirname(__FILE__), "/root/dokku"
+    vm.vm.synced_folder File.dirname(__FILE__), "/root/dokku", type: "nfs", nfs_version: 4, nfs_udp: false
     vm.vm.hostname = "#{DOKKU_DOMAIN}"
     vm.vm.network :private_network, ip: DOKKU_IP
 
@@ -53,7 +55,7 @@ Vagrant::configure("2") do |config|
       vb.customize ["modifyvm", :id, "--cableconnected1", "on"]
     end
 
-    vm.vm.provision :shell, :inline => "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq >/dev/null && apt-get -qq -y --no-install-recommends install git build-essential >/dev/null && cd /root/dokku && #{make_cmd}"
+    vm.vm.provision :shell, :inline => "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq >/dev/null && apt-get -qq -y --no-install-recommends install git build-essential jq nginx >/dev/null && cd /root/dokku && #{make_cmd}"
     vm.vm.provision :shell do |s|
       s.inline = <<-EOT
         echo '"\e[5~": history-search-backward' > /root/.inputrc
@@ -72,19 +74,19 @@ Vagrant::configure("2") do |config|
   config.vm.define "dokku-windows", autostart: false do |vm|
     vm.vm.hostname = "#{DOKKU_DOMAIN}"
     vm.vm.network :private_network, ip: DOKKU_IP
-    vm.vm.provision :shell, :inline => "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq >/dev/null && apt-get -qq -y --no-install-recommends install git dos2unix >/dev/null"
+    vm.vm.provision :shell, :inline => "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq >/dev/null && apt-get -qq -y --no-install-recommends install git dos2unix nginx >/dev/null"
     vm.vm.provision :shell, :inline => "cd /vagrant/ && export DOKKU_BRANCH=`git symbolic-ref -q --short HEAD 2>/dev/null` && export DOKKU_TAG=`git describe --tags --exact-match 2>/dev/null` && cd /root/ && cp /vagrant/bootstrap.sh ./ && dos2unix bootstrap.sh && bash bootstrap.sh"
   end
 
   config.vm.define "dokku-deb", autostart: false do |vm|
-    vm.vm.synced_folder File.dirname(__FILE__), "/root/dokku"
+    vm.vm.synced_folder File.dirname(__FILE__), "/root/dokku", type: "nfs", nfs_version: 4, nfs_udp: false
     vm.vm.hostname = "#{DOKKU_DOMAIN}"
     vm.vm.network :private_network, ip: DOKKU_IP
     vm.vm.provision :shell, :inline => "cd /root/dokku && make install-from-deb"
   end
 
   config.vm.define "build", autostart: false do |vm|
-    vm.vm.synced_folder File.dirname(__FILE__), "/root/dokku"
+    vm.vm.synced_folder File.dirname(__FILE__), "/root/dokku", type: "nfs", nfs_version: 4, nfs_udp: false
     vm.vm.hostname = "#{DOKKU_DOMAIN}"
     vm.vm.network :private_network, ip: DOKKU_IP
     vm.vm.provision :shell, :inline => "export DEBIAN_FRONTEND=noninteractive && apt-get update -qq >/dev/null && apt-get -qq -y --no-install-recommends install git >/dev/null && cd /root/dokku && #{make_cmd}"
@@ -93,9 +95,9 @@ Vagrant::configure("2") do |config|
 
   config.vm.define "build-arch", autostart: false do |vm|
     vm.vm.box = "bugyt/archlinux"
-    vm.vm.synced_folder File.dirname(__FILE__), "/dokku"
+    vm.vm.synced_folder File.dirname(__FILE__), "/dokku", type: "nfs", nfs_version: 4, nfs_udp: false
     if Pathname.new("#{File.dirname(__FILE__)}/../dokku-arch").exist?
-      vm.vm.synced_folder "#{File.dirname(__FILE__)}/../dokku-arch", "/dokku-arch"
+      vm.vm.synced_folder "#{File.dirname(__FILE__)}/../dokku-arch", "/dokku-arch", type: "nfs", nfs_version: 4, nfs_udp: false
     end
     vm.vm.hostname = "#{DOKKU_DOMAIN}"
     vm.vm.network :private_network, ip: DOKKU_IP

bootstrap.sh

@@ -3,7 +3,7 @@ set -eo pipefail
 [[ $TRACE ]] && set -x
 
 # A script to bootstrap dokku.
-# It expects to be run on Ubuntu 20.04/22.04 via 'sudo`
+# It expects to be run on Ubuntu 22.04/24.04 via 'sudo`
 # If installing a tag higher than 0.3.13, it may install dokku via a package (so long as the package is higher than 0.3.13)
 # It checks out the dokku source code from GitHub into ~/dokku and then runs 'make install' from dokku source.
 
@@ -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, 12], Ubuntu [18.04, 20.04, 22.04]"
+SUPPORTED_VERSIONS="Debian [11, 12, 13], Ubuntu [22.04, 24.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"
   }
 
@@ -48,9 +48,15 @@ install-requirements() {
         apt-get update -qq >/dev/null
         apt-get -qq -y --no-install-recommends install gpg-agent
       fi
-      if ! dpkg -l | grep -q software-properties-common; then
+      if ! command -v lsb_release &>/dev/null; then
         apt-get update -qq >/dev/null
-        apt-get -qq -y --no-install-recommends install software-properties-common
+        apt-get -qq -y --no-install-recommends install lsb-release
+      fi
+      if [[ "$DOKKU_DISTRO_VERSION" -lt "13" ]]; then
+        if ! dpkg -l | grep -q software-properties-common; then
+          apt-get update -qq >/dev/null
+          apt-get -qq -y --no-install-recommends install software-properties-common
+        fi
       fi
       ;;
     ubuntu)
@@ -122,7 +128,22 @@ install-dokku-from-source() {
     log-fail "This installation script requires apt-get. For manual installation instructions, consult https://dokku.com/docs/getting-started/advanced-installation/"
   fi
 
-  apt-get -qq -y --no-install-recommends install sudo git make software-properties-common
+  apt-get -qq -y --no-install-recommends install sudo git make
+  case "$DOKKU_DISTRO" in
+    debian)
+      if [[ "$DOKKU_DISTRO_VERSION" -lt "13" ]]; then
+        if ! dpkg -l | grep -q software-properties-common; then
+          apt-get -qq -y --no-install-recommends install software-properties-common
+        fi
+      fi
+      ;;
+    ubuntu)
+      if ! dpkg -l | grep -q software-properties-common; then
+        apt-get -qq -y --no-install-recommends install software-properties-common
+      fi
+      ;;
+  esac
+
   cd /root
   if [[ ! -d /root/dokku ]]; then
     git clone "$DOKKU_REPO" /root/dokku
@@ -160,7 +181,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" "12"; then
+  if ! in-array "$DOKKU_DISTRO_VERSION" "22.04" "24.04" "10" "11" "12" "13"; then
     log-fail "Unsupported Linux distribution. Only the following versions are supported: $SUPPORTED_VERSIONS"
   fi
 
@@ -168,10 +189,6 @@ install-dokku-from-deb-package() {
     NO_INSTALL_RECOMMENDS=" --no-install-recommends "
   fi
 
-  echo "--> Initial apt-get update"
-  apt-get update -qq >/dev/null
-  apt-get -qq -y --no-install-recommends install apt-transport-https
-
   if ! command -v docker &>/dev/null; then
     echo "--> Installing docker"
     if uname -r | grep -q linode; then
@@ -185,26 +202,26 @@ install-dokku-from-deb-package() {
     wget -nv -O - https://get.docker.com/ | sh
   fi
 
-  OS_ID="$(lsb_release -cs 2>/dev/null || echo "bionic")"
+  OS_ID="$(lsb_release -cs 2>/dev/null || echo "noble")"
   if ! in-array "$DOKKU_DISTRO" "debian" "ubuntu" "raspbian"; then
     DOKKU_DISTRO="ubuntu"
-    OS_ID="bionic"
+    OS_ID="noble"
   fi
 
   if [[ "$DOKKU_DISTRO" == "ubuntu" ]]; then
-    OS_IDS=("bionic" "focal" "jammy")
+    OS_IDS=("jammy" "noble")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
-      OS_ID="bionic"
+      OS_ID="noble"
     fi
   elif [[ "$DOKKU_DISTRO" == "debian" ]]; then
-    OS_IDS=("stretch" "buster" "bullseye" "bookworm")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
-      OS_ID="bullseye"
+      OS_ID="bookworm"
     fi
   elif [[ "$DOKKU_DISTRO" == "raspbian" ]]; then
-    OS_IDS=("buster" "bullseye")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     if ! in-array "$OS_ID" "${OS_IDS[@]}"; then
-      OS_ID="bullseye"
+      OS_ID="bookworm"
     fi
   fi
 
@@ -220,19 +237,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

common.mk

@@ -1,7 +1,7 @@
 GO_ARGS ?=
 GO_PLUGIN_MAKE_TARGET ?= build
 GO_REPO_ROOT := /go/src/github.com/dokku/dokku
-BUILD_IMAGE := golang:1.19.6
+BUILD_IMAGE := golang:1.26.2
 GO_BUILD_CACHE ?= /tmp/dokku-go-build-cache
 GO_MOD_CACHE   ?= /tmp/dokku-go-mod-mod
 GO_ROOT_MOUNT  ?= $$PWD/../..:$(GO_REPO_ROOT)
@@ -21,17 +21,17 @@ build-in-docker: clean
 		-e GO111MODULE=on \
 		-w $(GO_REPO_ROOT)/plugins/$(PLUGIN_NAME) \
 		$(BUILD_IMAGE) \
-		bash -c "GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) make -j4 $(GO_PLUGIN_MAKE_TARGET)" || exit $$?
+		bash -c "GO_ARGS='$(GO_ARGS)' CGO_ENABLED=0 GOOS=linux GOARCH=$(GOARCH) GOWORK=off make -j4 $(GO_PLUGIN_MAKE_TARGET)" || exit $$?
 
 clean:
 	rm -rf $(BUILD)
 	find . -xtype l -delete
 
 commands: **/**/commands.go
-	go build -ldflags="-s -w" $(GO_ARGS) -o commands src/commands/commands.go
+	GOARCH=$(GOARCH) go build -mod=readonly -ldflags="-s -w" $(GO_ARGS) -o commands src/commands/commands.go
 
 subcommands:
-	go build -ldflags="-s -w" $(GO_ARGS) -o subcommands/subcommands src/subcommands/subcommands.go
+	GOARCH=$(GOARCH) go build -mod=readonly -ldflags="-s -w" $(GO_ARGS) -o subcommands/subcommands src/subcommands/subcommands.go
 	$(MAKE) $(SUBCOMMANDS)
 
 subcommands/%:
@@ -41,7 +41,7 @@ src-clean:
 	rm -rf .gitignore src vendor Makefile *.go glide.* go.sum go.mod
 
 triggers:
-	go build -ldflags="-s -w" $(GO_ARGS) -o triggers src/triggers/triggers.go
+	GOARCH=$(GOARCH) go build -mod=readonly -ldflags="-s -w" $(GO_ARGS) -o triggers src/triggers/triggers.go
 	$(MAKE) $(TRIGGERS)
 
 triggers/%:

contrib/build-base.Dockerfile

@@ -1,8 +1,24 @@
-FROM ubuntu:20.04
+FROM ubuntu:24.04
 
 ENV DEBIAN_FRONTEND=noninteractive
 
-RUN apt-get update -qq && apt-get -qq -y --no-install-recommends install ca-certificates curl gcc git build-essential wget ruby-dev lintian rpm help2man man-db sudo
-RUN curl -sL -o /usr/local/share/ca-certificates/GlobalSignRootCA_R3.crt https://raw.githubusercontent.com/rubygems/rubygems/master/lib/rubygems/ssl_certs/rubygems.org/GlobalSignRootCA_R3.pem
-RUN update-ca-certificates
+RUN apt-get update -qq && apt-get -qq -y --no-install-recommends install \
+    adduser \
+    build-essential \
+    ca-certificates \
+    coreutils \
+    curl \
+    gcc \
+    git \
+    help2man \
+    jq \
+    libc-bin \
+    lintian \
+    man-db \
+    openssh-client \
+    python3 \
+    rpm \
+    ruby-dev \
+    sudo \
+    wget
 RUN command -v fpm || gem install fpm

contrib/build-docs

@@ -125,7 +125,7 @@ main() {
 
   echo "====> Rebuild versions"
   if [[ -f "tmp/docs-build/versions.json" ]]; then
-    python contrib/sort-mkdocs-versions
+    python3 contrib/sort-mkdocs-versions
   else
     echo "      No version file exists"
   fi
@@ -135,20 +135,33 @@ main() {
   mv docs-main docs
   git checkout -- mkdocs.yml docs
 
-  if [[ "$(git -C tmp/docs-build ls-files -dmo)" == "docs/sitemap.xml.gz" ]]; then
+  echo "====> Checking for file changes"
+  changes=$(git -C tmp/docs-build ls-files -dmo)
+  if [[ -z "$changes" ]]; then
+    echo " !    No doc changes found"
+    exit 0
+  fi
+
+  if [[ "$changes" == "docs/sitemap.xml.gz" ]]; then
     echo " !    No doc changes found"
     git -C tmp/docs-build checkout -- docs/sitemap.xml.gz
-  else
-    echo "====> Pushing docs"
-    git -C tmp/docs-build add .
-    git -C tmp/docs-build commit -m "chore: regenerate docs"
-
-    if [[ -n "$BOT_GITHUB_USERNAME" ]] && [[ -n "$BOT_GITHUB_API_TOKEN" ]]; then
-      git -C tmp/docs-build remote set-url origin "https://$BOT_GITHUB_USERNAME:$BOT_GITHUB_API_TOKEN@github.com/dokku/docs.git"
-    fi
-
-    git -C tmp/docs-build push origin master
+    exit 0
   fi
+
+  echo "====> Changes found"
+  echo "$changes"
+
+  echo "====> Committing changes"
+  git -C tmp/docs-build add .
+  git -C tmp/docs-build commit -m "chore: regenerate docs"
+
+  echo "====> Pushing changes"
+  if [[ -n "$BOT_GITHUB_USERNAME" ]] && [[ -n "$BOT_GITHUB_API_TOKEN" ]]; then
+    git -C tmp/docs-build remote set-url origin "https://$BOT_GITHUB_USERNAME:$BOT_GITHUB_API_TOKEN@github.com/dokku/docs.git"
+  fi
+
+  git -C tmp/docs-build push origin master
+
 }
 
 main "$@"

contrib/build-dokku.Dockerfile

@@ -1,27 +1,29 @@
-FROM dokku/build-base:0.0.1 AS builder
+FROM dokku/build-base:0.1.2 AS builder
 
 ENV DEBIAN_FRONTEND=noninteractive
 
 ARG GOLANG_VERSION
-
-RUN wget -qO /tmp/go${GOLANG_VERSION}.linux.tar.gz "https://storage.googleapis.com/golang/go${GOLANG_VERSION}.linux-$(dpkg --print-architecture).tar.gz" \
-  && tar -C /usr/local -xzf /tmp/go${GOLANG_VERSION}.linux.tar.gz \
-  && cp /usr/local/go/bin/* /usr/local/bin
-
 ARG WORKDIR=/go/src/github.com/dokku/dokku
 
 WORKDIR ${WORKDIR}
 
+RUN wget -qO /tmp/go${GOLANG_VERSION}.linux.tar.gz "https://go.dev/dl/go${GOLANG_VERSION}.linux-$(dpkg --print-architecture).tar.gz" \
+  && tar -C /usr/local -xzf /tmp/go${GOLANG_VERSION}.linux.tar.gz \
+  && cp /usr/local/go/bin/* /usr/local/bin \
+  && mkdir -p ${WORKDIR}/contrib
+
 COPY Makefile ${WORKDIR}/
 COPY *.mk ${WORKDIR}/
+COPY contrib/dependencies.json ${WORKDIR}/contrib/dependencies.json
 
 RUN make deb-setup sshcommand plugn
 
 COPY . ${WORKDIR}
 
 ENV GOPATH=/go
+ENV GOROOT=/usr/local/go
 
-FROM builder as amd64
+FROM builder AS amd64
 
 ARG PLUGIN_MAKE_TARGET
 ARG DOKKU_VERSION=master
@@ -36,7 +38,7 @@ RUN PLUGIN_MAKE_TARGET=${PLUGIN_MAKE_TARGET} \
   make version copyfiles \
   && make deb-dokku
 
-FROM builder as armhf
+FROM builder AS arm64
 
 COPY --from=amd64 /tmp /tmp
 COPY --from=amd64 /usr/local/share/man/man1/dokku.1 /usr/local/share/man/man1/dokku.1-generated
@@ -48,26 +50,6 @@ ARG DOKKU_VERSION=master
 ARG DOKKU_GIT_REV
 ARG IS_RELEASE=false
 
-RUN PLUGIN_MAKE_TARGET=${PLUGIN_MAKE_TARGET} \
-  DOKKU_VERSION=${DOKKU_VERSION} \
-  DOKKU_GIT_REV=${DOKKU_GIT_REV} \
-  IS_RELEASE=${IS_RELEASE} \
-  SKIP_GO_CLEAN=true \
-  GOARCH=arm make version copyfiles \
-  && DOKKU_ARCHITECTURE=armhf GOARCH=arm make deb-dokku
-
-FROM builder as arm64
-
-COPY --from=armhf /tmp /tmp
-COPY --from=amd64 /usr/local/share/man/man1/dokku.1 /usr/local/share/man/man1/dokku.1-generated
-
-RUN rm -rf /tmp/build-dokku
-
-ARG PLUGIN_MAKE_TARGET
-ARG DOKKU_VERSION=master
-ARG DOKKU_GIT_REV
-ARG IS_RELEASE=false
-
 RUN PLUGIN_MAKE_TARGET=${PLUGIN_MAKE_TARGET} \
   DOKKU_VERSION=${DOKKU_VERSION} \
   DOKKU_GIT_REV=${DOKKU_GIT_REV} \

contrib/copy-packages

@@ -15,7 +15,7 @@ def download_file(filename, url):
 
 
 def upload_file(filename):
-    versions = ["jammy"]
+    versions = ["noble"]
     cmd_template = "package_cloud push dokku/dokku/ubuntu/{0} {1}"
     for version in versions:
         cmd = cmd_template.format(version, filename)
@@ -25,7 +25,7 @@ def upload_file(filename):
 def main():
     auth = HTTPBasicAuth(PACKAGECLOUD_TOKEN, "")
     base = requests.get(
-        "https://packagecloud.io/api/v1/repos/dokku/dokku/packages/deb/ubuntu/focal.json",
+        "https://packagecloud.io/api/v1/repos/dokku/dokku/packages/deb/ubuntu/jammy.json",
         auth=auth,
     )
     data = base.json()

contrib/dependencies.json

@@ -0,0 +1,104 @@
+{
+  "dependencies": [
+    {
+      "name": "docker-container-healthchecker",
+      "version": "0.16.0",
+      "urls": {
+        "amd64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.16.0/docker-container-healthchecker-linux-amd64",
+        "arm64": "https://github.com/dokku/docker-container-healthchecker/releases/download/v0.16.0/docker-container-healthchecker-linux-arm64"
+      }
+    },
+    {
+      "name": "docker-image-labeler",
+      "version": "0.10.0",
+      "urls": {
+        "amd64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.10.0/docker-image-labeler-linux-amd64",
+        "arm64": "https://github.com/dokku/docker-image-labeler/releases/download/v0.10.0/docker-image-labeler-linux-arm64"
+      }
+    },
+    {
+      "name": "lambda-builder",
+      "version": "0.9.4",
+      "urls": {
+        "amd64": "https://github.com/dokku/lambda-builder/releases/download/v0.9.4/lambda-builder-linux-amd64",
+        "arm64": "https://github.com/dokku/lambda-builder/releases/download/v0.9.4/lambda-builder-linux-arm64"
+      }
+    },
+    {
+      "name": "netrc",
+      "version": "0.11.1",
+      "urls": {
+        "amd64": "https://github.com/dokku/netrc/releases/download/v0.11.1/netrc-linux-amd64",
+        "arm64": "https://github.com/dokku/netrc/releases/download/v0.11.1/netrc-linux-arm64"
+      }
+    },
+    {
+      "name": "pack",
+      "version": "0.40.9",
+      "urls": {
+        "amd64": "https://github.com/buildpacks/pack/releases/download/v0.40.9/pack-v0.40.9-linux.tgz",
+        "arm64": "https://github.com/buildpacks/pack/releases/download/v0.40.9/pack-v0.40.9-linux-arm64.tgz"
+      }
+    },
+    {
+      "name": "procfile-util",
+      "version": "0.20.8",
+      "urls": {
+        "amd64": "https://github.com/dokku/procfile-util/releases/download/v0.20.8/procfile-util-linux-amd64",
+        "arm64": "https://github.com/dokku/procfile-util/releases/download/v0.20.8/procfile-util-linux-arm64"
+      }
+    },
+    {
+      "name": "sshcommand",
+      "version": "0.20.2",
+      "urls": {
+        "amd64": "https://github.com/dokku/sshcommand/releases/download/v0.20.2/sshcommand",
+        "arm64": "https://github.com/dokku/sshcommand/releases/download/v0.20.2/sshcommand"
+      }
+    }
+  ],
+  "predependencies": [
+    {
+      "name": "gliderlabs-sigil",
+      "version": "0.12.1",
+      "urls": {
+        "amd64": "https://github.com/gliderlabs/sigil/releases/download/v0.12.1/sigil-linux-amd64",
+        "arm64": "https://github.com/gliderlabs/sigil/releases/download/v0.12.1/sigil-linux-arm64"
+      }
+    },
+    {
+      "name": "plugn",
+      "version": "0.17.1",
+      "urls": {
+        "amd64": "https://github.com/dokku/plugn/releases/download/v0.17.1/plugn-linux-amd64",
+        "arm64": "https://github.com/dokku/plugn/releases/download/v0.17.1/plugn-linux-arm64"
+      }
+    }
+  ],
+  "recommendations": [
+    {
+      "name": "dokku-event-listener",
+      "version": "0.20.1",
+      "urls": {
+        "amd64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.20.1/dokku-event-listener-linux-amd64",
+        "arm64": "https://github.com/dokku/dokku-event-listener/releases/download/v0.20.1/dokku-event-listener-linux-arm64"
+      }
+    },
+    {
+      "name": "dokku-update",
+      "version": "0.10.0",
+      "urls": {
+        "amd64": "https://github.com/dokku/dokku-update/releases/download/v0.10.0/dokku-update",
+        "arm64": "https://github.com/dokku/dokku-update/releases/download/v0.10.0/dokku-update"
+      }
+    },
+    {
+      "name": "herokuish",
+      "version": "0.11.16",
+      "urls": {
+        "amd64": "https://github.com/gliderlabs/herokuish/releases/download/v0.11.16/herokuish_0.11.16_linux_x86_64.tgz",
+        "arm64": "https://github.com/gliderlabs/herokuish/releases/download/v0.11.16/herokuish_0.11.16_linux_x86_64.tgz"
+      }
+    }
+  ]
+}

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

@@ -1,8 +1,9 @@
 #!/usr/bin/env bash
 set -eo pipefail
 [[ $DOKKU_TRACE ]] && set -x
-export DOKKU_PORT=${DOKKU_PORT:=22}
+export DOKKU_PORT=${DOKKU_PORT:=}
 export DOKKU_HOST=${DOKKU_HOST:=}
+export DOKKU_APP_PATH=${DOKKU_APP_PATH:=}
 
 fn-random-number() {
   [[ -n "$1" ]] && RANGE="$1"
@@ -49,7 +50,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
@@ -61,12 +62,42 @@ fn-dokku-host() {
   echo "$DOKKU_HOST"
 }
 
+fn-dokku-app() {
+  declare DOKKU_GIT_REMOTE="$1" DOKKU_REMOTE_HOST="$2"
+  remote_output="$(git remote -v 2>/dev/null | grep -Ei "^${DOKKU_GIT_REMOTE}\s" | head -n 1 | awk '{print $2}')"
+
+  # check if there is a scheme
+  if echo "$remote_output" | grep -qEi "ssh://"; then
+    echo "$remote_output" | grep -Ei "ssh://dokku@$DOKKU_REMOTE_HOST" | cut -f2 -d'@' | cut -f2 -d'/' 2>/dev/null
+  else
+    echo "$remote_output" | grep -Ei "dokku@$DOKKU_REMOTE_HOST" | cut -f2 -d'@' | cut -f2 -d':' 2>/dev/null
+  fi
+}
+
+fn-dokku-port() {
+  declare DOKKU_GIT_REMOTE="$1" DOKKU_REMOTE_HOST="$2"
+  remote_output="$(git remote -v 2>/dev/null | grep -Ei "^${DOKKU_GIT_REMOTE}\s" | head -n 1 | awk '{print $2}')"
+
+  if echo "$remote_output" | grep -qEi "ssh://"; then
+    local output="$(echo "$remote_output" | grep -Ei "ssh://dokku@$DOKKU_REMOTE_HOST" | cut -f2 -d'@' | cut -f1 -d'/' 2>/dev/null)"
+    # check if output has a : and if so, get the port
+    if echo "$output" | grep -qEi ":"; then
+      echo "$output" | cut -f2 -d':' 2>/dev/null
+    else
+      echo "22"
+    fi
+  else
+    echo "22"
+  fi
+}
+
 fn-get-remote() {
   git config dokku.remote 2>/dev/null || echo "dokku"
 }
 
 main() {
   declare CMD="$1" APP_ARG="$2"
+
   local APP="" DOKKU_GIT_REMOTE="$(fn-get-remote)" DOKKU_REMOTE_HOST=""
   local cmd_set=false next_index=1 skip=false args=("$@")
 
@@ -84,6 +115,10 @@ main() {
       APP=${args[$next_index]}
       skip=true
       shift 2
+    elif [[ "$arg" == "--app-path" ]]; then
+      DOKKU_APP_PATH=${args[$next_index]}
+      skip=true
+      shift 2
     elif [[ "$arg" == "--remote" ]]; then
       DOKKU_GIT_REMOTE=${args[$next_index]}
       skip=true
@@ -103,22 +138,41 @@ main() {
     next_index=$((next_index + 1))
   done
 
+  if [[ -n "$DOKKU_APP_PATH" ]]; then
+    pushd "$DOKKU_APP_PATH" &>/dev/null || exit 1
+    trap 'popd &>/dev/null || true' RETURN INT TERM
+  fi
+
   DOKKU_REMOTE_HOST="$(fn-dokku-host "$DOKKU_GIT_REMOTE" "$DOKKU_HOST")"
   if [[ -z "$DOKKU_REMOTE_HOST" ]] && [[ "$CMD" != remote ]] && [[ "$CMD" != remote:* ]]; then
     fn-client-help-msg
   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)
+      APP="$(fn-dokku-app "$DOKKU_GIT_REMOTE" "$DOKKU_REMOTE_HOST")"
       set -e
     else
       echo " !     This is not a git repository" 1>&2
     fi
   fi
 
+  if [[ -z "$DOKKU_PORT" ]]; then
+    DOKKU_PORT="$(fn-dokku-port "$DOKKU_GIT_REMOTE" "$DOKKU_REMOTE_HOST")"
+  fi
+
   case "$CMD" in
+    remote:show)
+      echo "dokku-app: $APP"
+      echo "dokku-git-remote: $DOKKU_GIT_REMOTE"
+      echo "dokku-host: $DOKKU_HOST"
+      echo "dokku-port: $DOKKU_PORT"
+      echo "dokku-remote-host: $DOKKU_REMOTE_HOST"
+      echo "dokku-ssh-user: dokku"
+      echo "dokku-constructed-remote: ssh://dokku@$DOKKU_REMOTE_HOST:$DOKKU_PORT/$APP"
+      exit 0
+      ;;
     apps:create)
       if [[ -z "$APP" ]] && [[ -z "$APP_ARG" ]]; then
         APP=$(fn-random-name)
@@ -129,7 +183,7 @@ main() {
             ssh -p "$DOKKU_PORT" "dokku@$DOKKU_REMOTE_HOST" apps
             exit 1
           else
-            APP=$(random_name)
+            APP=$(fn-random-name)
             counter=$((counter + 1))
           fi
         done
@@ -184,14 +238,23 @@ main() {
   esac
 
   [[ " apps certs help ls nginx shell storage trace version " == *" $CMD "* ]] && unset APP
-  [[ " certs:chain domains:add-global domains:remove-global domains:set-global ps:restore " == *" $CMD "* ]] && unset APP
+  [[ " certs:chain domains:add-global domains:clear-global domains:remove-global domains:set-global ps:restore " == *" $CMD "* ]] && unset APP
   [[ " storage:ensure-directory " == *" $CMD "* ]] && unset APP
+  [[ " network:create network:destroy network:exists network:info network:list network:rebuildall " == *" $CMD "* ]] && unset APP
+  [[ " logs:vector-logs logs:vector-start logs:vector-stop " == *" $CMD "* ]] && unset APP
+  [[ " scheduler-k3s:cluster:add scheduler-k3s:cluster:list scheduler-k3s:cluster:remove " == *" $CMD "* ]] && unset APP
+  [[ " scheduler-k3s:ensure-charts scheduler-k3s:initialize scheduler-k3s:show-kubeconfig scheduler-k3s:uninstall " == *" $CMD "* ]] && unset APP
+  [[ " scheduler-k3s:profiles:add scheduler-k3s:profiles:list scheduler-k3s:profiles:remove " == *" $CMD "* ]] && unset APP
   [[ "$CMD" =~ events*|plugin*|ssh-keys* ]] && unset APP
   [[ -n "$APP_ARG" ]] && [[ "$APP_ARG" == "--global" ]] && unset APP
-  [[ -n "$@" ]] && [[ -n "$APP" ]] && app_arg="--app $APP"
+  if [[ -n "$@" ]] && [[ -n "$APP" ]]; then
+    set -- "$APP" "$@"
+    set -- "--app" "$@"
+  fi
   # 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 $@ || {
+  local ssh_args=("-o" "LogLevel=QUIET" "-p" "$DOKKU_PORT" "-t" "dokku@$DOKKU_REMOTE_HOST" "--")
+  ssh_args+=("$@")
+  ssh "${ssh_args[@]}" || {
     ssh_exit_code="$?"
     echo " !     Failed to execute dokku command over ssh: exit code $?" 1>&2
     echo " !     If there was no output from Dokku, ensure your configured SSH Key can connect to the remote server" 1>&2

contrib/images/digitalocean/in_parts/011-docker

@@ -4,12 +4,10 @@ set -o errexit
 
 export DEBIAN_FRONTEND=noninteractive
 
-pkgs=(apt-transport-https
-  ca-certificates
+pkgs=(ca-certificates
   curl
   jq
   linux-image-extra-virtual
-  software-properties-common
 )
 
 echo '--> Updating apt repositories'
@@ -30,7 +28,7 @@ EOM
 
 echo '--> Installing docker-ce'
 apt-get -y update
-apt-get -y install docker-ce docker-compose-plugin
+apt-get -y install docker-ce docker-buildx-plugin docker-compose-plugin
 
 echo '--> Enabling docker-ce'
 systemctl enable docker

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

@@ -12,10 +12,9 @@ pkgs=(apache2-utils
   curl
   man-db
 
-  netcat
+  netcat-traditional
   net-tools
 
-  software-properties-common
   parallel
   python3-software-properties
   rsync
@@ -25,7 +24,7 @@ pkgs=(apache2-utils
   unzip
 
   nginx
-  dnsutils
+  bind9-dnsutils
   cgroupfs-mount
   cgroup-lite
   sudo
@@ -33,7 +32,8 @@ pkgs=(apache2-utils
   debconf
 )
 
-dokku_pkgs=(docker-image-labeler
+dokku_pkgs=(docker-container-healthchecker
+  docker-image-labeler
   gliderlabs-sigil
   lambda-builder
   netrc
@@ -49,7 +49,7 @@ echo '--> Setting up dokku apt repository'
 curl -fsSL https://packagecloud.io/dokku/dokku/gpgkey -o /etc/apt/keyrings/dokku.asc
 
 cat >/etc/apt/sources.list.d/dokku.list <<EOM
-deb [arch=amd64 signed-by=/etc/apt/keyrings/dokku.asc]  https://packagecloud.io/dokku/dokku/ubuntu/ bionic main
+deb [arch=amd64 signed-by=/etc/apt/keyrings/dokku.asc]  https://packagecloud.io/dokku/dokku/ubuntu/ noble main
 EOM
 
 echo '--> Install dependencies for dokku from new repository'

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,17 +347,15 @@ 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
     if [ -f /usr/lib/systemd/system/csf.service ]; then
       fw="csf"
-      if [[ $(systemctl status $fw >/dev/null 2>&1) ]]; then
+      if systemctl status $fw >/dev/null 2>&1; then
 
         FW_VER="\e[32m[PASS]\e[0m Firewall service (${fw}) is active\n"
         ((PASS++))
@@ -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
@@ -505,7 +497,7 @@ osv=0
 
 if [[ $OS == "Ubuntu" ]]; then
   ost=1
-  if [[ $VER == "22.10" ]] || [[ $VER == "22.04" ]] || [[ $VER == "20.04" ]] || [[ $VER == "18.04" ]] || [[ $VER == "16.04" ]]; then
+  if [[ $VER == "24.04" ]] || [[ $VER == "22.10" ]] || [[ $VER == "22.04" ]] || [[ $VER == "20.04" ]] || [[ $VER == "18.04" ]] || [[ $VER == "16.04" ]]; then
     osv=1
   fi
 
@@ -521,6 +513,9 @@ elif [[ "$OS" =~ Debian.* ]]; then
     11)
       osv=1
       ;;
+    12)
+      osv=1
+      ;;
     *)
       osv=2
       ;;
@@ -546,7 +541,7 @@ elif [[ $OS == "CentOS Stream" ]]; then
   fi
 elif [[ $OS == "Rocky Linux" ]]; then
   ost=1
-  if [[ $VER =~ 8\. ]]; then
+  if [[ $VER =~ 8\. ]] || [[ $VER =~ 9\. ]]; then
     osv=1
   else
     osv=2

contrib/images/digitalocean/packer.pkr.hcl

@@ -12,7 +12,7 @@ variable "dokku_version" {
 }
 
 source "digitalocean" "ubuntu" {
-  image         = "ubuntu-22-04-x64"
+  image         = "ubuntu-24-04-x64"
   region        = "nyc1"
   size          = "s-1vcpu-512mb-10gb"
   ssh_username  = "root"
@@ -30,6 +30,7 @@ build {
       "echo '--> Waiting until cloud-init is complete'",
       "/usr/bin/cloud-init status --wait",
     ]
+    valid_exit_codes = [0, 2]
   }
 
   provisioner "file" {

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
@@ -137,7 +134,7 @@ fn-publish-package() {
   [[ "$RELEASE_TYPE" == "raspbian" ]] && DIST=raspbian
 
   if [[ "$RELEASE_TYPE" == "raspbian" ]]; then
-    OS_IDS=("buster" "bullseye")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     for OS_ID in "${OS_IDS[@]}"; do
       log-info "(release-dokku) pushing deb to packagecloud.com/${REPOSITORY}/${DIST}"
       package_cloud push "${REPOSITORY}/${DIST}/${OS_ID}" "$PACKAGE_NAME"
@@ -147,7 +144,7 @@ fn-publish-package() {
       fi
     done
   elif [[ "$DIST" == "ubuntu" ]]; then
-    OS_IDS=("bionic" "focal" "jammy")
+    OS_IDS=("jammy" "noble")
     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"
@@ -158,7 +155,7 @@ fn-publish-package() {
     done
 
     DIST=debian
-    OS_IDS=("buster" "bullseye" "bookworm")
+    OS_IDS=("bullseye" "bookworm" "trixie")
     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 CURRENT_VERSION="$1" NEXT_VERSION="$2" IS_PATCH="$3"
+  if [[ "$IS_PATCH" == "true" ]]; then
+    git log "v${CURRENT_VERSION}..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
@@ -224,14 +225,14 @@ fn-repo-update() {
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/development/release-process.md
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/getting-started/install/docker.md
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/getting-started/installation/index.md
-  fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/home.html
+  fn-replace-version "v$CURRENT_VERSION" "v$NEXT_VERSION" docs/home.html
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/template.html
   fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" README.md
 
   if [[ "$RELEASE" == 'patch' ]]; then
     fn-replace-version "$CURRENT_VERSION" "$NEXT_VERSION" docs/assets/versions.json
   else
-    versions=$(python -c 'import json,sys;d=json.load(sys.stdin);d["max-versions"].append("'"${NEXT_VERSION}"'"); print(json.dumps(d, indent=2, sort_keys=True))' <docs/assets/versions.json)
+    versions=$(python3 -c 'import json,sys;d=json.load(sys.stdin);d["max-versions"].append("'"${NEXT_VERSION}"'"); print(json.dumps(d, indent=2, sort_keys=True))' <docs/assets/versions.json)
     echo "$versions" >docs/assets/versions.json
     git add docs/assets/versions.json
   fi
@@ -241,21 +242,21 @@ 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
+  local COMMIT_MESSAGE HISTORY HISTORY_CONTENTS HISTORY_BUG HISTORY_DEPENDENCY HISTORY_DEPRECATION HISTORY_DOCUMENTATION HISTORY_ENHANCEMENT HISTORY_BC_BREAK HISTORY_REFACTOR HISTORY_REMOVAL HISTORY_SECURITY HISTORY_OTHER HISTORY_TESTS ISSUE_FILE
 
   pushd "$ROOT_DIR" >/dev/null
 
   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" "$NEXT_VERSION" "$IS_PATCH"); do
     ISSUE_FILE="/tmp/github-data/${PULL_REQUEST_ID}.json"
     if [[ ! -f "$ISSUE_FILE" ]]; then
       while true; do
@@ -294,6 +295,8 @@ fn-repo-update-history-and-commit() {
       HISTORY_REFACTOR="${HISTORY_REFACTOR}"$'\n'"$CHANGELOG_TEXT"
     elif [[ "$TYPE" == "removal" ]]; then
       HISTORY_REMOVAL="${HISTORY_REMOVAL}"$'\n'"$CHANGELOG_TEXT"
+    elif [[ "$TYPE" == "security" ]]; then
+      HISTORY_SECURITY="${HISTORY_SECURITY}"$'\n'"$CHANGELOG_TEXT"
     elif [[ "$TYPE" == "tests" ]]; then
       HISTORY_TESTS="${HISTORY_TESTS}"$'\n'"$CHANGELOG_TEXT"
     else
@@ -313,6 +316,11 @@ fn-repo-update-history-and-commit() {
     HISTORY="${HISTORY}"$'\n\n'"See the [${NEXT_VERSION} migration guide](/docs/appendices/${NEXT_VERSION}-migration-guide.md) for more information on migrating to ${NEXT_VERSION}."
   fi
 
+  if [[ "$HISTORY_SECURITY" ]]; then
+    HISTORY="${HISTORY}"$'\n\n'"### Security"
+    HISTORY="${HISTORY}"$'\n'"$HISTORY_SECURITY"
+  fi
+
   if [[ "$HISTORY_BC_BREAK" ]]; then
     HISTORY="${HISTORY}"$'\n\n'"### Backwards Compatibility Breaks"
     HISTORY="${HISTORY}"$'\n'"$HISTORY_BC_BREAK"
@@ -386,15 +394,17 @@ fn-build-docker-image() {
 
   if [[ "$IS_RELEASE" == "true" ]]; then
     docker buildx build \
-      --platform linux/arm,linux/arm64,linux/amd64 \
+      --platform linux/arm64,linux/amd64 \
       --progress plain \
       --push \
+      --label "org.opencontainers.image.version=$VERSION" \
       --tag "dokku/dokku:latest" \
       --tag "dokku/dokku:$VERSION" .
   elif [[ "$SKIP_IMAGE_BUILD" != "true" ]]; then
     docker buildx build \
-      --platform linux/arm,linux/arm64,linux/amd64 \
+      --platform linux/arm64,linux/amd64 \
       --progress plain \
+      --label "org.opencontainers.image.version=$VERSION" \
       --tag "dokku/dokku:latest" \
       --tag "dokku/dokku:$(echo "$VERSION" | tr + -)" .
   fi
@@ -402,7 +412,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,20 +443,22 @@ 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"
   fn-extract-package "$IS_RELEASE" "dokku_${NEXT_VERSION}_amd64.deb" || log-fail "Error extracting deb package"
   mkdir -p build/package
   cp -f "build/dokku_${NEXT_VERSION}_amd64.deb" build/package/dokku-amd64.deb
   cp -f "build/dokku_${NEXT_VERSION}_arm64.deb" build/package/dokku-arm64.deb
-  cp -f "build/dokku_${NEXT_VERSION}_armhf.deb" build/package/dokku-armhf.deb
 
   if [[ "$RELEASE" != "build" ]]; then
-    fn-publish-package "$IS_RELEASE" "raspbian" "build/dokku_${NEXT_VERSION}_armhf.deb" || log-fail "Error publishing deb package"
     fn-publish-package "$IS_RELEASE" "deb" "build/dokku_${NEXT_VERSION}_arm64.deb" || log-fail "Error publishing deb package"
     fn-publish-package "$IS_RELEASE" "deb" "build/dokku_${NEXT_VERSION}_amd64.deb" || log-fail "Error publishing deb package"
     fn-build-docker-image "$NEXT_VERSION" "$IS_RELEASE" || log-fail "Error building docker image"

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/update-deb-dependencies

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+import json
+import re
+
+
+def main():
+    """
+    updates the control file with the tested debian dependencies
+    """
+    deps = {}
+    with open("contrib/dependencies.json", encoding="utf-8") as handle:
+        deps = json.load(handle)
+
+    control_lines = []
+    with open("debian/control", encoding="utf-8") as handle:
+        control_lines = [line for line in handle.readlines()]
+
+    for key in ["dependencies", "predependencies", "recommendations"]:
+        for dependency in deps[key]:
+            name = dependency["name"]
+            version = dependency["version"]
+            pattern = re.compile(rf"(?<![\w-]){re.escape(name)}(?![\w-])")
+            for i, line in enumerate(control_lines):
+                control_lines[i] = pattern.sub(f"{name} (>= {version})", line)
+
+    with open("debian/control", mode="w", encoding="utf-8") as handle:
+        handle.writelines(control_lines)
+
+
+if __name__ == "__main__":
+    main()

contrib/write-mkdocs

@@ -1,13 +1,17 @@
 #!/usr/bin/env python
-from bs4 import BeautifulSoup
 import os
 import pathlib
 import shutil
 import sys
+
 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 +53,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("."))) if "." in x else [-1, -1, -1],
+                        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,238 +111,30 @@ 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)
-
-
-def modify_content_noop(lines, _):
-    modified = False
-    updated_lines = []
-    for line in lines:
-        updated_lines.append(line)
-    return updated_lines, modified
-
-
-def modify_content_links(lines, filename):
-    filename = filename.replace("/usr/src/source/docs/", "")
-    parts = filename.split("/")
-    parts.pop()
-    replacement = "](" + '/'.join([".." for _ in parts]) + "/"
-    modified = False
-    updated_lines = []
-    for line in lines:
-        if "](/docs/" in line:
-            line = line.replace("](/docs/", replacement)
-            modified = True
-
-        updated_lines.append(line)
-    return updated_lines, modified
-
-
-def modify_content_stripspace(lines, _):
-    modified = False
-    updated_lines = []
-    for line in lines:
-        line = line.rstrip()
-        updated_lines.append(line)
-    return updated_lines, modified
-
-
-def modify_content_inject_newlines(lines, _):
-    modified = False
-    updated_lines = []
-    for line in lines:
-        updated_lines.append(line.rstrip() + "\n")
-    return updated_lines, modified
-
-
-def is_info(line):
-    return line.startswith("> ")
-
-
-def is_new(line):
-    return line.startswith("> ") and "new as of" in line.lower()
-
-
-def is_note(line):
-    return line.startswith("> Note:")
-
-
-def is_warning(line):
-    return line.startswith("> Warning:")
-
-
-def modify_content_admonition(lines, _):
-    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("> ")
-
-            is_admonition = True
-            admonition_lines.append(line)
-        elif is_admonition and line in [">", "> "]:
-            line = ""
-            admonition_lines.append(line)
-        elif is_admonition and line.startswith("> "):
-            line = "    " + line.removeprefix("> ")
-            admonition_lines.append(line)
-        elif line == "":
-            is_admonition = False
-            if len(admonition_lines) > 0:
-                updated_lines.extend(admonition_lines)
-                admonition_lines = []
-            updated_lines.append("")
-        else:
-            updated_lines.append(line)
-    return updated_lines, modified
-
-
-def is_shell_codeblock_start(line):
-    return line == "```shell"
-
-
-def modify_content_terminal_example(lines, _):
-    modified = False
-    updated_lines = []
-    command_block = []
-    example_block = []
-    in_command_block = False
-    in_example_block = False
-    previous_block = ""
-    next_line_must_be = None
-    for line in lines:
-        if is_shell_codeblock_start(line):
-            command_block.append(line)
-            modified = True
-            in_command_block = True
-            continue
-        elif in_command_block:
-            command_block.append(line)
-            if line == "```":
-                in_command_block = False
-                previous_block = "command_block"
-                next_line_must_be = ""
-            continue
-        elif line == "```":
-            if previous_block == "":
-                updated_lines.append(line)
-                continue
-            elif 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("")
-                    for command_line in command_block:
-                        updated_lines.append(f"    {command_line}")
-                    command_block = []
-
-                    updated_lines.append("")
-                    updated_lines.append("=== \"Output\"")
-                    updated_lines.append("")
-                    for example_line in example_block:
-                        updated_lines.append(f"    {example_line}")
-                    example_block = []
-                else:
-                    in_example_block = True
-                continue
-        elif previous_block == "command_block":
-            if next_line_must_be is None:
-                if in_example_block:
-                    example_block.append(line)
-                else:
-                    updated_lines.extend(command_block)
-                    updated_lines.append("")
-                    updated_lines.append(line)
-                    command_block = []
-                    previous_block = ""
-                continue
-            elif next_line_must_be == "":
-                if line == "":
-                    next_line_must_be = None
-                    continue
-
-        updated_lines.append(line)
-
-    if len(command_block) > 0:
-        updated_lines.extend(command_block)
-
-    return updated_lines, modified
-
-
-def update_markdown(src):
-    markdown_files = []
-    allowed_extensions = [".md"]
-    for subdir, _, files in os.walk(src):
-        for file in files:
-            ext = os.path.splitext(file)[-1].lower()
-            file_path = os.path.join(subdir, file)
-            if ext in allowed_extensions:
-                markdown_files.append(file_path)
-
-    modifiers = [
-        modify_content_noop,
-        modify_content_links,
-        modify_content_stripspace,
-        modify_content_admonition,
-        modify_content_terminal_example,
-        modify_content_inject_newlines,
-    ]
-
-    for file in markdown_files:
-        modified = False
-        lines = []
-        with open(file, 'r') as f:
-            lines = f.readlines()
-            for modifier in modifiers:
-                lines, m = modifier(lines, file)
-                if m:
-                    modified = True
-
-        if modified:
-            with open(file, 'w') as fp:
-                fp.writelines(lines)
+    with open(dest, mode="wt", encoding="utf-8") as handler:
+        yaml.dump(data, handler)
 
 
 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",)
-
     if os.path.exists("/usr/src/app/docs"):
         print("      Removing old docs folder")
         shutil.rmtree("/usr/src/app/docs")

deb.mk

@@ -11,16 +11,12 @@ endif
 .PHONY: install-from-deb deb-all deb-dokku deb-setup
 
 install-from-deb:
-	@echo "--> Initial apt-get update"
-	sudo apt-get update -qq >/dev/null
-	sudo apt-get -qq -y --no-install-recommends install apt-transport-https
-
 	@echo "--> Installing docker"
 	wget -nv -O - https://get.docker.com/ | sh
 
 	@echo "--> Installing dokku"
 	wget -qO- https://packagecloud.io/dokku/dokku/gpgkey | sudo tee /etc/apt/trusted.gpg.d/dokku.asc
-	@echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ $(shell lsb_release -cs 2>/dev/null || echo "focal") main" | sudo tee /etc/apt/sources.list.d/dokku.list
+	@echo "deb https://packagecloud.io/dokku/dokku/ubuntu/ $(shell lsb_release -cs 2>/dev/null || echo "noble") main" | sudo tee /etc/apt/sources.list.d/dokku.list
 	sudo apt-get update -qq >/dev/null
 	sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get -qq -y --no-install-recommends install dokku
 
@@ -31,7 +27,7 @@ deb-all: deb-setup deb-dokku
 deb-setup:
 	@echo "-> Updating deb repository and installing build requirements"
 	@sudo apt-get update -qq >/dev/null
-	@sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get -qq -y --no-install-recommends install gcc git build-essential wget ruby-dev ruby1.9.1 lintian >/dev/null 2>&1
+	@sudo DEBIAN_FRONTEND=noninteractive DEBCONF_NONINTERACTIVE_SEEN=true apt-get -qq -y --no-install-recommends install gcc git build-essential wget ruby-dev lintian >/dev/null 2>&1
 	@command -v fpm >/dev/null || sudo gem install fpm --no-ri --no-rdoc
 	@ssh -o StrictHostKeyChecking=no git@github.com || true
 
@@ -43,6 +39,7 @@ ifneq (,$(findstring false,$(IS_RELEASE)))
 	sed -i.bak -e "s/^/`date +%s`:/" /tmp/build-dokku/var/lib/dokku/STABLE_VERSION && rm /tmp/build-dokku/var/lib/dokku/STABLE_VERSION.bak
 endif
 
+	contrib/update-deb-dependencies
 	cp -r debian /tmp/build-dokku/DEBIAN
 	sed -i.bak "s/^Architecture: .*/Architecture: $(DOKKU_ARCHITECTURE)/g" /tmp/build-dokku/DEBIAN/control && rm  /tmp/build-dokku/DEBIAN/control.bak
 	rm -f /tmp/build-dokku/DEBIAN/lintian-overrides

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
 
@@ -15,5 +14,6 @@ db_input "high" "dokku/hostname" || true
 db_input "high" "dokku/vhost_enable" || true
 if [ "$ACTION" != "reconfigure" ]; then
   db_input "high" "dokku/key_file" || true
+  db_input "high" "dokku/install_default_site" || true
 fi
 db_go || true

debian/control

@@ -1,11 +1,11 @@
 Package: dokku
-Version: 0.30.10
+Version: 0.38.27
 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, cron | cron-daemon, curl, logrotate, man-db, netcat, sshcommand, docker-engine-cs (>= 19.03.0) | docker-engine (>= 19.03.0) | docker-io (>= 19.03.0) | docker.io (>= 19.03.0) | docker-ce (>= 19.03.0) | docker-ee (>= 19.03.0) | moby-engine, docker-compose-plugin | moby-compose | docker-compose, docker-buildx-plugin | moby-buildx | docker-buildx, docker-container-healthchecker, docker-image-labeler, lambda-builder, net-tools, netrc, parallel, procfile-util, rsync, dos2unix, unzip, util-linux
+Recommends: herokuish, bash-completion, dokku-update, dokku-event-listener
+Pre-Depends: gliderlabs-sigil, jq, nginx (>= 1.8.0) | openresty, bind9-dnsutils, debconf, plugn, sudo, python3, rsyslog
 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
 
@@ -26,6 +24,40 @@ call-sshcommand() {
   fi
 }
 
+setup-docker-live-restore() {
+  # skip if running in docker-based installation
+  if [[ "$DOKKU_INIT_SYSTEM" == "sv" ]]; then
+    return
+  fi
+
+  # allow disabling via /etc/default/dokku
+  if [[ "$DOKKU_LIVE_RESTORE" == "false" ]]; then
+    return
+  fi
+
+  live_restore="$(docker info --format '{{ .LiveRestoreEnabled }}' || true)"
+  if [ "$live_restore" = "true" ]; then
+    echo "Docker live-restore is already enabled"
+    return
+  fi
+
+  echo "Enabling docker live-restore"
+  if [[ ! -f /etc/docker/daemon.json ]]; then
+    mkdir -p /etc/docker
+    echo "{}" >/etc/docker/daemon.json
+  fi
+
+  config="$(jq '. + {"live-restore": true}' /etc/docker/daemon.json)"
+  echo "$config" >/etc/docker/daemon.json
+  if command -v systemctl &>/dev/null; then
+    if ! systemctl reload docker; then
+      echo "Unable to reload docker, please reload manually" 1>&2
+    fi
+  else
+    echo "Unable to reload docker, please reload manually" 1>&2
+  fi
+}
+
 setup-user() {
   echo "Setting up dokku user"
   call-sshcommand create dokku /usr/bin/dokku
@@ -86,7 +118,8 @@ setup-plugins() {
       PLUGIN_PATH="${DOKKU_LIB_ROOT}/plugins" plugn enable "$plugin"
     fi
   done
-  find -L "${DOKKU_LIB_ROOT}" -type l -delete
+  find -L "${DOKKU_LIB_ROOT}/core-plugins" -type l -delete
+  find -L "${DOKKU_LIB_ROOT}/plugins" -type l -delete
   chown dokku:dokku -R "${DOKKU_LIB_ROOT}/plugins" "${DOKKU_LIB_ROOT}/core-plugins"
 
   echo "Install all core plugins"
@@ -102,6 +135,85 @@ setup-sshcommand() {
   fi
 }
 
+disable-default-vhost-path() {
+  local path="$1"
+  local backup_path="${path}.dokku-disabled"
+
+  if [ ! -e "$path" ] && [ ! -L "$path" ]; then
+    return
+  fi
+
+  if [ -e "$backup_path" ] || [ -L "$backup_path" ]; then
+    return
+  fi
+
+  case "$path" in
+    /etc/nginx/sites-enabled/*)
+      rm -f "$path"
+      echo "Removed conflicting nginx default at $path" 1>&2
+      return
+      ;;
+  esac
+
+  if [ -L "$path" ]; then
+    rm -f "$path"
+    echo "Removed conflicting nginx default symlink at $path" 1>&2
+    return
+  fi
+
+  mv -n "$path" "$backup_path"
+  echo "Disabled $path (renamed to $backup_path)" 1>&2
+}
+
+setup-default-site() {
+  db_get "dokku/install_default_site"
+  if [ "$RET" != "true" ]; then
+    return
+  fi
+
+  local nginx_bin nginx_version major minor patch
+  nginx_bin="$(command -v nginx || true)"
+  if [ -z "$nginx_bin" ]; then
+    return
+  fi
+
+  nginx_version="$("$nginx_bin" -v 2>&1 | cut -d'/' -f 2 | awk '{print $1}')"
+  major="$(echo "$nginx_version" | awk -F. '{print $1}')"
+  minor="$(echo "$nginx_version" | awk -F. '{print $2}')"
+  patch="$(echo "$nginx_version" | awk -F. '{print $3}')"
+
+  # ssl_reject_handshake requires nginx >= 1.19.4; older nginx gets the
+  # HTTP-only catch-all so the SSL listen lines do not require a cert.
+  local default_vhost_basename="default-site.conf"
+  if [ "${major:-0}" -lt 2 ]; then
+    if [ "${major:-0}" -lt 1 ] || [ "${minor:-0}" -lt 19 ] || { [ "${minor:-0}" -eq 19 ] && [ "${patch:-0}" -lt 4 ]; }; then
+      default_vhost_basename="default-site-legacy.conf"
+    fi
+  fi
+
+  local default_vhost_target="/etc/nginx/conf.d/00-default-vhost.conf"
+  local default_vhost_source="${DOKKU_LIB_ROOT}/core-plugins/available/nginx-vhosts/templates/${default_vhost_basename}"
+
+  if [ -e "$default_vhost_target" ]; then
+    return
+  fi
+
+  if [ ! -f "$default_vhost_source" ]; then
+    return
+  fi
+
+  for path in /etc/nginx/sites-enabled/default /etc/nginx/sites-available/default /etc/nginx/conf.d/default.conf; do
+    disable-default-vhost-path "$path"
+  done
+
+  echo "Installing nginx default catch-all site at $default_vhost_target"
+  install -m 0644 -o root -g root "$default_vhost_source" "$default_vhost_target"
+
+  if command -v dokku &>/dev/null; then
+    dokku nginx:reload || true
+  fi
+}
+
 dpkg-handling() {
   if [ -f "${DOKKU_ROOT}/VHOST" ]; then
     echo "VHOST file detected, skipping modification"
@@ -129,9 +241,6 @@ case "$1" in
   configure)
     mandb
     [ ! -x /usr/bin/docker.io ] || ln -sf /usr/bin/docker.io /usr/local/bin/docker
-    if [[ -f /sbin/modprobe ]]; then
-      modprobe aufs || echo "WARNING: Restart server to finish installing dokku!"
-    fi
 
     setup-user
     setup-storage
@@ -139,6 +248,10 @@ case "$1" in
     dpkg-handling
     setup-plugins
     setup-sshcommand
+    setup-docker-live-restore
+    if [ -z "$2" ]; then
+      setup-default-site
+    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
 

debian/prerm

@@ -11,39 +11,39 @@ ps_backtrace() {
     exit 1
   fi
 
-  declare -i pid=$1
+  declare -i pid="$1"
   ppid=0
   header_modifier=""
   while :; do
-    if [ $ppid -ne 0 ]; then
+    if [[ "$ppid" -ne 0 ]]; then
       header_modifier=h
     fi
-    ppid=$(ps -o ppid= $pid)
-    ps uww $header_modifier -p $pid
-    if [ $pid -eq 1 ]; then
+    ppid="$(ps -o ppid= "$pid")"
+    ps uww $header_modifier -p "$pid"
+    if [[ "$pid" -eq 1 ]] || [[ "$pid" -eq 0 ]]; then
       break
     fi
-    pid=$ppid
+    pid="$ppid"
   done
 }
 
 main() {
   # HACK: Ensure that we only delete data when purging dokku from the system
-  if ps_backtrace $BASHPID 2>/dev/null | grep dpkg | grep -- "--purge" >/dev/null; then
+  if ps_backtrace "$BASHPID" 2>/dev/null | grep dpkg | grep -- "--purge" >/dev/null; then
     echo "Processing purge"
 
     echo "Destroying deployed applications"
     for app in $(DOKKU_QUIET_OUTPUT=1 dokku apps:list); do
-      dokku --force apps:destroy $app
+      dokku --force apps:destroy "$app"
     done
 
     # HACK: Only disable core plugins, as we don't know what data users store in non-core plugin directories
     echo "Disabling all core plugins"
-    find ${DOKKU_LIB_ROOT}/core-plugins/available -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | while read -r plugin; do
-      if [ ! -d ${DOKKU_LIB_ROOT}/plugins/available/$plugin ]; then
-        rm ${DOKKU_LIB_ROOT}/plugins/available/$plugin
-        PLUGIN_PATH=${DOKKU_LIB_ROOT}/core-plugins plugn disable $plugin
-        PLUGIN_PATH=${DOKKU_LIB_ROOT}/plugins plugn disable $plugin
+    find "${DOKKU_LIB_ROOT}/core-plugins/available" -mindepth 1 -maxdepth 1 -type d -printf '%f\n' | while read -r plugin; do
+      if [[ ! -d "${DOKKU_LIB_ROOT}/plugins/available/$plugin" ]]; then
+        rm "${DOKKU_LIB_ROOT}/plugins/available/$plugin"
+        PLUGIN_PATH="${DOKKU_LIB_ROOT}/core-plugins" plugn disable "$plugin"
+        PLUGIN_PATH="${DOKKU_LIB_ROOT}/plugins" plugn disable "$plugin"
       fi
     done
   else

debian/templates

@@ -22,3 +22,8 @@ Template: dokku/nginx_enable
 Description: Enable nginx-vhosts plugin?
 Type: boolean
 Default: true
+
+Template: dokku/install_default_site
+Description: Install a catch-all nginx default site on fresh install?
+Type: boolean
+Default: true

docker/etc/cron.d/docker-builder-prune

@@ -0,0 +1,4 @@
+PATH=/usr/local/bin:/usr/bin:/bin
+SHELL=/bin/bash
+
+5 4 * * * root /usr/local/bin/docker builder prune -f >>/var/log/dokku/builder-prune.log 2>&1

docker/etc/my_init.d/10_dokku_init

@@ -20,7 +20,11 @@ log-warn() {
 support-userns() {
   chown 0:0 /usr/bin/sudo
   chmod 4755 /usr/bin/sudo
-  chown 0:0 /usr/lib/sudo/sudoers.so
+  if [[ -f /usr/lib/sudo/sudoers.so ]]; then
+    chown 0:0 /usr/lib/sudo/sudoers.so
+  elif [[ -f /usr/libexec/sudo/sudoers.so ]]; then
+    chown 0:0 /usr/libexec/sudo/sudoers.so
+  fi
   chown -R 0:0 /etc/sudoers
   chown -R 0:0 /etc/sudoers.d
   chown -R 0:0 /run/sshd
@@ -31,6 +35,9 @@ main() {
 
   support-userns
 
+  rm -f /var/run/dokku/ready
+  mkdir -p /var/run/dokku
+
   if [[ ! -d /mnt/dokku ]]; then
     log-info "Creating missing /mnt/dokku"
     mkdir -p /mnt/dokku
@@ -54,6 +61,22 @@ main() {
     fi
   done
 
+  touch /etc/default/dokku
+  echo "export DOKKU_INIT_SYSTEM=sv" >>/etc/default/dokku
+  if [[ -x /usr/local/bin/docker ]]; then
+    echo "export DOCKER_BIN=/usr/local/bin/docker" >>/etc/default/dokku
+  fi
+
+  if [[ -n "$DOKKU_HOST_ROOT" ]]; then
+    echo "export DOKKU_HOST_ROOT=$DOKKU_HOST_ROOT" >>/etc/default/dokku
+    chown dokku:dokku /etc/default/dokku
+  fi
+
+  if [[ -n "$DOKKU_LIB_HOST_ROOT" ]]; then
+    echo "export DOKKU_LIB_HOST_ROOT=$DOKKU_LIB_HOST_ROOT" >>/etc/default/dokku
+    chown dokku:dokku /etc/default/dokku
+  fi
+
   if [[ -f /mnt/dokku/plugin-list ]]; then
     while read line; do
       local plugin_name="$(echo "$line" | awk -F: '{print $1}')"
@@ -65,22 +88,17 @@ main() {
     done </mnt/dokku/plugin-list
   fi
 
+  # run core install triggers to force create any folders that may be missing
+  dokku plugin:install
+
   if [[ -n "$DOKKU_HOSTNAME" ]]; then
     echo "dokku dokku/hostname string $DOKKU_HOSTNAME" | debconf-set-selections
     echo "dokku dokku/vhost_enable boolean true" | debconf-set-selections
     dokku --quiet domains:set-global "$DOKKU_HOSTNAME"
   fi
 
-  if [[ -x /usr/local/bin/docker ]]; then
-    mkdir -p /home/dokku/.dokkurc
-    echo "export DOCKER_BIN=/usr/local/bin/docker" >"/home/dokku/.dokkurc/DOCKER_BIN"
-  fi
-
-  if [[ -n "$DOKKU_HOST_ROOT" ]]; then
-    touch /etc/default/dokku
-    echo "export DOKKU_HOST_ROOT=$DOKKU_HOST_ROOT" >>/etc/default/dokku
-    chown dokku:dokku /etc/default/dokku
-  fi
+  echo "dokku dokku/skip_key_file boolean true" | debconf-set-selections
+  echo "dokku dokku/key_file string /root/.ssh/id_rsa.pub" | debconf-set-selections
 
   NGINX_ROOT="/etc/nginx"
   if [[ -x /usr/bin/openresty ]]; then

docker/etc/nginx/conf.d/zz-dokku-health.conf

@@ -0,0 +1,16 @@
+# Internal health endpoint for the official dokku/dokku Docker image.
+# Bound to loopback so it is reachable only from inside the container
+# and never conflicts with user app vhosts on 80/443.
+server {
+    listen      127.0.0.1:18080;
+    server_name _;
+    access_log  off;
+    default_type text/plain;
+
+    location = /_dokku/health {
+        if (-f /var/run/dokku/ready) {
+            return 200 "ok\n";
+        }
+        return 503 "not ready\n";
+    }
+}

docker/etc/runit/runsvdir/default/dokku-restore/finish

@@ -10,6 +10,10 @@ if [[ "$1" -ne 0 ]]; then
 fi
 
 echo "Done restoring dokku apps."
-exec sleep infinity
 
-exit 0
+while ! (echo >/dev/tcp/127.0.0.1/22) >/dev/null 2>&1; do sleep 1; done
+while ! (echo >/dev/tcp/127.0.0.1/80) >/dev/null 2>&1; do sleep 1; done
+touch /var/run/dokku/ready
+echo "Dokku is ready."
+
+exec sleep infinity

docker/etc/ssh/sshd_config

@@ -0,0 +1,133 @@
+#       $OpenBSD: sshd_config,v 1.80 2008/07/02 02:24:18 djm Exp $
+
+# This is the sshd server system-wide configuration file.  See
+# sshd_config(5) for more information.
+
+# This sshd was compiled with PATH=/usr/bin:/bin:/usr/sbin:/sbin
+
+# The strategy used for options in the default sshd_config shipped with
+# OpenSSH is to specify options with their default value where
+# possible, but leave them commented.  Uncommented options change a
+# default value.
+
+UseDNS no
+
+Port 22 
+Port 22333
+#AddressFamily any
+#ListenAddress 0.0.0.0
+#ListenAddress ::
+
+# Disable legacy (protocol version 1) support in the server for new
+# installations. In future the default will change to require explicit
+# activation of protocol 1
+Protocol 2
+
+# HostKey for protocol version 1
+#HostKey /etc/ssh_host_key
+# HostKeys for protocol version 2
+#HostKey /etc/ssh_host_rsa_key
+#HostKey /etc/ssh_host_dsa_key
+
+# Lifetime and size of ephemeral version 1 server key
+#KeyRegenerationInterval 1h
+#ServerKeyBits 1024
+
+# Logging
+# obsoletes QuietMode and FascistLogging
+SyslogFacility AUTHPRIV
+#LogLevel INFO
+
+# Authentication:
+
+#LoginGraceTime 2m
+#PermitRootLogin yes
+#StrictModes yes
+#MaxAuthTries 6
+#MaxSessions 10
+
+#RSAAuthentication yes
+#PubkeyAuthentication yes
+#AuthorizedKeysFile     .ssh/authorized_keys
+
+# For this to work you will also need host keys in /etc/ssh_known_hosts
+#RhostsRSAAuthentication no
+# similar for protocol version 2
+#HostbasedAuthentication no
+# Change to yes if you don't trust ~/.ssh/known_hosts for
+# RhostsRSAAuthentication and HostbasedAuthentication
+#IgnoreUserKnownHosts no
+# Don't read the user's ~/.rhosts and ~/.shosts files
+#IgnoreRhosts yes
+
+# To disable tunneled clear text passwords, change to no here! Also,
+# remember to set the UsePAM setting to 'no'.
+PasswordAuthentication no
+#PermitEmptyPasswords no
+
+# SACL options
+# The default for the SACLSupport option is now "no", as this option has been
+# depreciated in favor of SACL enforcement in the PAM configuration (/etc/pam.d/sshd).
+#SACLSupport no
+
+# Change to no to disable s/key passwords
+# Disabled for passenger-docker. We only allow key authentication.
+ChallengeResponseAuthentication no
+
+# Kerberos options
+#KerberosAuthentication no
+#KerberosOrLocalPasswd yes
+#KerberosTicketCleanup yes
+
+# GSSAPI options
+#GSSAPIAuthentication no
+#GSSAPICleanupCredentials yes
+#GSSAPIStrictAcceptorCheck yes
+#GSSAPIKeyExchange no
+
+# Set this to 'yes' to enable PAM authentication, account processing,
+# and session processing. If this is enabled, PAM authentication will
+# be allowed through the ChallengeResponseAuthentication and
+# PasswordAuthentication.  Depending on your PAM configuration,
+# PAM authentication via ChallengeResponseAuthentication may bypass
+# the setting of "PermitRootLogin without-password".
+# If you just want the PAM account and session checks to run without
+# PAM authentication, then enable this but set PasswordAuthentication
+# and ChallengeResponseAuthentication to 'no'.
+# Also, PAM will deny null passwords by default.  If you need to allow
+# null passwords, add the "     nullok" option to the end of the
+# securityserver.so line in /etc/pam.d/sshd.
+UsePAM yes
+
+#AllowAgentForwarding yes
+#AllowTcpForwarding yes
+#GatewayPorts no
+X11Forwarding yes
+#X11DisplayOffset 10
+#X11UseLocalhost yes
+#PrintMotd yes
+#PrintLastLog yes
+#TCPKeepAlive yes
+#UseLogin no
+#UsePrivilegeSeparation yes
+#PermitUserEnvironment no
+#Compression delayed
+#ClientAliveInterval 0
+#ClientAliveCountMax 3
+#UseDNS yes
+#PidFile /var/run/sshd.pid
+#MaxStartups 10
+#PermitTunnel no
+#ChrootDirectory none
+
+# no default banner path
+#Banner none
+
+# override default of no subsystems
+Subsystem       sftp    /usr/lib/openssh/sftp-server
+
+# Example of overriding settings on a per-user basis
+#Match User anoncvs
+#       X11Forwarding no
+#       AllowTcpForwarding no
+#       ForceCommand cvs server

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/lambda-builder,/usr/bin/nixpacks,/usr/bin/railpack,/usr/bin/pack

docker/usr/local/bin/lambda-builder

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

docker/usr/local/bin/nixpacks

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

docker/usr/local/bin/railpack

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -eo pipefail
+[[ $TRACE ]] && set -x
+
+main() {
+  declare desc="re-runs railpack commands as sudo"
+  local RAILPACK_BIN=""
+  if [[ -x "/usr/bin/railpack" ]]; then
+    RAILPACK_BIN="/usr/bin/railpack"
+  fi
+
+  if [[ -z "$RAILPACK_BIN" ]]; then
+    echo "!   No railpack binary found" 1>&2
+    exit 1
+  fi
+
+  sudo -E "$RAILPACK_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/README.md

@@ -0,0 +1,161 @@
+# Dokku Documentation
+
+This documentation covers the installation, configuration, and usage of Dokku - a Docker-powered PaaS that provides a Heroku-like experience.
+
+## Getting Started
+
+- [Installation](getting-started/installation/index.md) - Install Dokku on your server
+    - [Debian](getting-started/install/debian.md)
+    - [Docker](getting-started/install/docker.md)
+    - [DigitalOcean](getting-started/install/digitalocean.md)
+    - [Azure](getting-started/install/azure.md)
+    - [DreamHost](getting-started/install/dreamhost.md)
+    - [Vagrant](getting-started/install/vagrant.md)
+- [Advanced Installation](getting-started/advanced-installation.md) - Custom installation options
+- [Upgrading](getting-started/upgrading/index.md) - Upgrade to newer Dokku versions
+- [Uninstalling](getting-started/uninstalling.md) - Remove Dokku from your server
+- [Troubleshooting](getting-started/troubleshooting.md) - Common issues and solutions
+- [Where to Get Help](getting-started/where-to-get-help.md) - Support resources
+
+## Deployment
+
+- [Application Deployment](deployment/application-deployment.md) - Deploy your first app
+- [Application Management](deployment/application-management.md) - Manage deployed applications
+- [Logs](deployment/logs.md) - View application logs
+- [Remote Commands](deployment/remote-commands.md) - Run commands remotely
+- [User Management](deployment/user-management.md) - Manage SSH access
+- [Zero Downtime Deploys](deployment/zero-downtime-deploys.md) - Deploy without interruption
+
+### Deployment Methods
+
+- [Git](deployment/methods/git.md) - Deploy via git push
+- [Archive](deployment/methods/archive.md) - Deploy from tar/zip archives
+- [Image](deployment/methods/image.md) - Deploy from Docker images
+
+### Builders
+
+- [Builder Management](deployment/builders/builder-management.md) - Configure build systems
+- [Buildpack Management](deployment/builders/buildpack-management.md) - Manage buildpack settings
+- [Herokuish Buildpacks](deployment/builders/herokuish-buildpacks.md) - Heroku-compatible buildpacks
+- [Cloud Native Buildpacks](deployment/builders/cloud-native-buildpacks.md) - CNB support
+- [Dockerfiles](deployment/builders/dockerfiles.md) - Build from Dockerfile
+- [Nixpacks](deployment/builders/nixpacks.md) - Nixpacks builder
+- [Railpack](deployment/builders/railpack.md) - Railpack builder
+- [Lambda](deployment/builders/lambda.md) - Lambda-style functions
+- [Null Builder](deployment/builders/null.md) - Skip the build phase
+
+### Schedulers
+
+- [Scheduler Management](deployment/schedulers/scheduler-management.md) - Configure schedulers
+- [Docker Local](deployment/schedulers/docker-local.md) - Default Docker scheduler
+- [K3s](deployment/schedulers/k3s.md) - Lightweight Kubernetes
+- [Kubernetes](deployment/schedulers/kubernetes.md) - External Kubernetes clusters
+- [Nomad](deployment/schedulers/nomad.md) - HashiCorp Nomad
+- [Null Scheduler](deployment/schedulers/null.md) - Skip scheduling
+
+### Continuous Integration
+
+- [Generic CI](deployment/continuous-integration/generic.md) - General CI/CD setup
+- [GitHub Actions](deployment/continuous-integration/github-actions.md)
+- [GitLab CI](deployment/continuous-integration/gitlab-ci.md)
+- [Woodpecker CI](deployment/continuous-integration/woodpecker-ci.md)
+
+## Configuration
+
+- [Environment Variables](configuration/environment-variables.md) - Configure app environment
+- [Domains](configuration/domains.md) - Custom domain management
+- [SSL/TLS](configuration/ssl.md) - HTTPS and certificates
+
+## Networking
+
+- [Proxy Management](networking/proxy-management.md) - Reverse proxy configuration
+- [Port Management](networking/port-management.md) - Port mapping and exposure
+- [DNS](networking/dns.md) - DNS configuration
+- [Network](networking/network.md) - Docker network management
+
+### Proxies
+
+- [Nginx](networking/proxies/nginx.md) - Default proxy
+- [Caddy](networking/proxies/caddy.md)
+- [HAProxy](networking/proxies/haproxy.md)
+- [Traefik](networking/proxies/traefik.md)
+- [OpenResty](networking/proxies/openresty.md)
+
+## Processes
+
+- [Process Management](processes/process-management.md) - Scale and manage processes
+- [Scheduled Cron Tasks](processes/scheduled-cron-tasks.md) - Scheduled jobs
+- [One-off Tasks](processes/one-off-tasks.md) - Run one-time commands
+- [Entering Containers](processes/entering-containers.md) - Access running containers
+
+## Advanced Usage
+
+- [Persistent Storage](advanced-usage/persistent-storage.md) - Mount volumes
+- [Docker Options](advanced-usage/docker-options.md) - Custom Docker run arguments
+- [Resource Management](advanced-usage/resource-management.md) - CPU and memory limits
+- [Plugin Management](advanced-usage/plugin-management.md) - Install and manage plugins
+- [Registry Management](advanced-usage/registry-management.md) - Docker registry integration
+- [Repository Management](advanced-usage/repository-management.md) - Git repository settings
+- [Build Tracking](advanced-usage/builds.md) - Inspect, cancel, and manage builds
+- [Deployment Tasks](advanced-usage/deployment-tasks.md) - Pre/post deploy hooks
+- [Event Logs](advanced-usage/event-logs.md) - Dokku event history
+- [Backup and Recovery](advanced-usage/backup-recovery.md) - Data backup strategies
+
+## Development
+
+- [Architecture](development/architecture.md) - Internal architecture overview for contributors
+- [Plugin Creation](development/plugin-creation.md) - Build custom plugins
+- [Plugin Triggers](development/plugin-triggers.md) - Available plugin hooks
+- [Testing](development/testing.md) - Test Dokku and plugins
+- [Release Process](development/release-process.md) - How Dokku releases work
+
+## Community
+
+- [Plugins](community/plugins.md) - Community-maintained plugins
+- [Clients](community/clients.md) - API clients and tools
+
+## Enterprise
+
+- [Dokku Pro](enterprise/pro.md) - Commercial features and support
+
+## Appendices
+
+### Migration Guides
+
+- [0.38.0](appendices/0.38.0-migration-guide.md)
+- [0.37.0](appendices/0.37.0-migration-guide.md)
+- [0.36.0](appendices/0.36.0-migration-guide.md)
+- [0.35.0](appendices/0.35.0-migration-guide.md)
+- [0.34.0](appendices/0.34.0-migration-guide.md)
+- [0.33.0](appendices/0.33.0-migration-guide.md)
+- [0.32.0](appendices/0.32.0-migration-guide.md)
+- [0.31.0](appendices/0.31.0-migration-guide.md)
+- [0.30.0](appendices/0.30.0-migration-guide.md)
+- [0.29.0](appendices/0.29.0-migration-guide.md)
+- [0.28.0](appendices/0.28.0-migration-guide.md)
+- [0.27.0](appendices/0.27.0-migration-guide.md)
+- [0.26.0](appendices/0.26.0-migration-guide.md)
+- [0.25.0](appendices/0.25.0-migration-guide.md)
+- [0.24.0](appendices/0.24.0-migration-guide.md)
+- [0.23.0](appendices/0.23.0-migration-guide.md)
+- [0.22.0](appendices/0.22.0-migration-guide.md)
+- [0.21.0](appendices/0.21.0-migration-guide.md)
+- [0.20.0](appendices/0.20.0-migration-guide.md)
+- [0.10.0](appendices/0.10.0-migration-guide.md)
+- [0.9.0](appendices/0.9.0-migration-guide.md)
+- [0.8.0](appendices/0.8.0-migration-guide.md)
+- [0.7.0](appendices/0.7.0-migration-guide.md)
+- [0.6.0](appendices/0.6.0-migration-guide.md)
+- [0.5.0](appendices/0.5.0-migration-guide.md)
+
+### File Formats
+
+- [app.json](appendices/file-formats/app-json.md) - Application configuration
+- [Procfile](appendices/file-formats/procfile.md) - Process definitions
+- [Dockerfile](appendices/file-formats/dockerfile.md) - Docker build instructions
+- [.buildpacks](appendices/file-formats/buildpacks-file.md) - Buildpack configuration
+- [project.toml](appendices/file-formats/project-toml.md) - CNB configuration
+- [nixpacks.toml](appendices/file-formats/nixpacks-toml.md) - Nixpacks configuration
+- [railpack.json](appendices/file-formats/railpack-json.md) - Railpack configuration
+- [lambda.yml](appendices/file-formats/lambda-yml.md) - Lambda configuration
+- [nginx.conf.sigil](appendices/file-formats/nginx-conf-sigil.md) - Nginx template customization

docs/_build/Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.11.4-alpine
+FROM python:3.15.0rc1-alpine
 
 WORKDIR /usr/src/app
 

docs/_build/entrypoint

@@ -3,7 +3,7 @@ set -eo pipefail
 
 write-mkdocs() {
   if [[ -f /usr/src/source/contrib/write-mkdocs ]]; then
-    if ! python /usr/src/source/contrib/write-mkdocs; then
+    if ! python3 /usr/src/source/contrib/write-mkdocs; then
       exit 0
     fi
   fi
@@ -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/hooks.py

@@ -0,0 +1,407 @@
+#!/usr/bin/env python
+
+import posixpath
+import re
+
+from collections.abc import Callable
+from re import Match
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.structure.files import File, Files
+from mkdocs.structure.pages import Page
+
+
+def on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files) -> str | None:
+    resp = re_on_page_markdown(markdown, page=page, config=config, files=files)
+    if not resp:
+        return resp
+    
+
+    modifiers: list[Callable[[list[str], str], tuple[list[str], bool]]] = [
+        modify_content_noop,
+        modify_content_links,
+        modify_content_stripspace,
+        modify_content_admonition,
+        modify_content_terminal_example,
+    ]
+
+    is_modified = False
+    lines = resp.split("\n")
+    for modifier in modifiers:
+        lines, modified = modifier(lines, page.file.src_path)
+        if modified:
+            is_modified = True
+
+    if is_modified:
+        resp = "\n".join(lines)
+    
+    return resp
+
+
+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:
+        updated_lines.append(line)
+    return updated_lines, modified
+
+
+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]) + "/"
+    modified = False
+    updated_lines = []
+    for line in lines:
+        if "](/docs/" in line:
+            line = line.replace("](/docs/", replacement)
+            modified = True
+
+        updated_lines.append(line)
+    return updated_lines, modified
+
+
+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:
+        line = line.rstrip()
+        updated_lines.append(line)
+    return updated_lines, modified
+
+
+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: 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: str) -> bool:
+    """
+    Checks if a given line is a "note" admonition
+    """
+    return line.startswith("> Note:")
+
+
+def is_warning(line: str) -> bool:
+    """
+    Checks if a given line is a "warning" admonition
+    """
+    return line.startswith("> Warning:")
+
+
+def modify_content_admonition(lines: list[str], filename: str) -> tuple[list[str], bool]:
+    """
+    Applies adminition info to each line in the output
+    """
+    modified = False
+    updated_lines = []
+    admonition_lines = []
+    is_admonition = False
+    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 [">", "> "]:
+            line = ""
+            admonition_lines.append(line)
+        elif is_admonition and line.startswith("> "):
+            line = "    " + line.removeprefix("> ")
+            admonition_lines.append(line)
+        elif line == "":
+            is_admonition = False
+            if len(admonition_lines) > 0:
+                modified = True
+                updated_lines.extend(admonition_lines)
+                admonition_lines = []
+            updated_lines.append("")
+        else:
+            updated_lines.append(line)
+    return updated_lines, modified
+
+
+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: list[str], _) -> tuple[list[str], bool]:
+    """
+    Modifies content so that terminal output is shown appropriately
+    """
+    modified = False
+    updated_lines = []
+    command_block = []
+    example_block = []
+    in_command_block = False
+    in_example_block = False
+    previous_block = ""
+    next_line_must_be = None
+    for line in lines:
+        if is_shell_codeblock_start(line):
+            command_block.append(line)
+            modified = True
+            in_command_block = True
+            continue
+        elif in_command_block:
+            command_block.append(line)
+            if line == "```":
+                in_command_block = False
+                previous_block = "command_block"
+                next_line_must_be = ""
+            continue
+        elif line == "```":
+            if previous_block == "":
+                updated_lines.append(line)
+                continue
+            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("")
+                    for command_line in command_block:
+                        updated_lines.append(f"    {command_line}")
+                    command_block = []
+
+                    updated_lines.append("")
+                    updated_lines.append('=== "Output"')
+                    updated_lines.append("")
+                    for example_line in example_block:
+                        updated_lines.append(f"    {example_line}")
+                    example_block = []
+                else:
+                    in_example_block = True
+                continue
+        elif previous_block == "command_block":
+            if next_line_must_be is None:
+                if in_example_block:
+                    example_block.append(line)
+                else:
+                    updated_lines.extend(command_block)
+                    updated_lines.append("")
+                    updated_lines.append(line)
+                    command_block = []
+                    previous_block = ""
+                continue
+            if next_line_must_be == "":
+                if line == "":
+                    next_line_must_be = None
+                    continue
+
+        updated_lines.append(line)
+
+    if len(command_block) > 0:
+        updated_lines.extend(command_block)
+
+    return updated_lines, modified
+
+
+def re_on_page_markdown(markdown: str, *, page: Page, config: MkDocsConfig, files: Files) -> str | None:
+    """
+    This hook is called after the page's markdown is loaded from file and can be
+    """
+
+    def replace(match: Match):
+        badge_type, args = match.groups()
+        args = args.strip()
+        if badge_type == "version":
+            return _badge_for_version(args, page, files)
+        if badge_type == "scheduler":
+            return _badge_for_scheduler(args, page, files)
+        if type == "flag":
+            return flag(args, page, files)
+
+        # Otherwise, raise an error
+        raise RuntimeError(f"Unknown shortcode: {badge_type}")
+
+    return re.sub(r"<!-- md:(\w+)(.*?) -->", replace, markdown, flags=re.I | re.M)
+
+
+def _badge(icon: str, text: str = "", badge_type: str = ""):
+    """
+    Create badge
+    """
+    classes = f"mdx-badge mdx-badge--{badge_type}" if badge_type else "mdx-badge"
+    text = f"{text}{{ data-preview='' }}" if text.endswith(")") else text
+    return "".join(
+        [
+            f'<span class="{classes}">',
+            *([f'<span class="mdx-badge__icon">{icon}</span>'] if icon else []),
+            *([f'<span class="mdx-badge__text">{text}</span>'] if text else []),
+            "</span>",
+        ]
+    )
+
+
+def _badge_for_scheduler(text: str, page: Page, files: Files):
+    """
+    Create badge for scheduler
+    """
+
+    # Return badge
+    icon = "simple-docker"
+    if text in ["kubernetes", "k3s"]:
+        icon = "simple-kubernetes"
+        text = "k3s"
+    elif text == "nomad":
+        icon = "simple-nomad"
+    elif text in ["docker", "docker-local"]:
+        icon = "simple-docker"
+        text = "docker-local"
+
+    href = f"https://dokku.com/docs/deployment/schedulers/{text}/"
+    return _badge(
+        icon=f"[:{icon}:]({href} '{text}')",
+        text=f"[{text}]({href})",
+    )
+
+
+def _badge_for_version(text: str, page: Page, files: Files):
+    """
+    Create badge for version
+    """
+
+    # Return badge
+    icon = "material-tag-outline"
+    href = f"https://github.com/dokku/dokku/releases/tag/v{text}"
+    return _badge(
+        icon=f"[:{icon}:]({href} 'Since {text}')",
+        text=f"[{text}]({href})",
+    )
+
+
+def flag(args: str, page: Page, files: Files):
+    """
+    Create flag
+    """
+
+    flag_type, *_ = args.split(" ", 1)
+    if flag_type == "experimental":
+        return _badge_for_experimental(page, files)
+    raise RuntimeError(f"Unknown flag type: {flag_type}")
+
+
+def _badge_for_experimental(page: Page, files: Files):
+    """
+    Create badge for experimental
+    """
+
+    icon = "material-flask-outline"
+    href = _resolve_path("conventions.md#experimental", page, files)
+    return _badge(icon=f"[:{icon}:]({href} 'Experimental')")
+
+
+def _resolve_path(path: str, page: Page, files: Files):
+    """
+    Resolve path of file relative to given page - the posixpath always includes
+    one additional level of `..` which we need to remove
+    """
+
+    path, anchor, *_ = f"{path}#".split("#")
+    path = _resolve(files.get_file_from_path(path), page)
+    return "#".join([path, anchor]) if anchor else path
+
+
+def _resolve(file: File, page: Page):
+    """
+    Resolve path of file relative to given page - the posixpath always includes
+    one additional level of `..` which we need to remove
+    """
+
+    path = posixpath.relpath(file.src_uri, page.file.src_uri)
+    return posixpath.sep.join(path.split(posixpath.sep)[1:])

docs/_build/requirements.txt

@@ -1,23 +1,23 @@
-beautifulsoup4==4.12.2
-click==8.1.6
+beautifulsoup4==4.15.0
+click==8.4.2
 ghp-import==2.1.0
-importlib-metadata==6.8.0
-Jinja2==3.1.2
-Markdown>=3.2.1,<3.5
-MarkupSafe==2.1.3
+importlib-metadata==9.0.0
+Jinja2==3.1.6
+Markdown>=3.10.3,<3.11
+MarkupSafe==3.0.3
 mergedeep==1.3.4
-mkdocs==1.5.1
+mkdocs==1.6.1
 mkdocs-exclude==1.0.2
-mkdocs-material==9.1.21
-mkdocs-material-extensions==1.1.1
-packaging==23.1
-Pygments==2.15.1
-pymdown-extensions==10.1
-pyparsing==3.1.0
-python-dateutil==2.8.2
-PyYAML==6.0.1
-pyyaml_env_tag==0.1
-six==1.16.0
-soupsieve==2.4.1
-watchdog==3.0.0
-zipp==3.16.2
+mkdocs-material==9.7.7
+mkdocs-material-extensions==1.3.1
+packaging==26.3
+Pygments==2.21.0
+pymdown-extensions==11.0.1
+pyparsing==3.3.2
+python-dateutil==2.9.0.post0
+PyYAML==6.0.3
+pyyaml_env_tag==1.1
+six==1.17.0
+soupsieve==2.9.2
+watchdog==6.0.0
+zipp==4.1.0

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
 
@@ -95,6 +96,14 @@ System administrators are highly encouraged to store persistent data in app-spec
 
 See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more information on how to attach persistent storage to your app.
 
+### Restoring on a machine with a different CPU Architecture
+
+When restoring a backup on a machine that has a different CPU architecture, you will need to clear out the `~/.basher`  as it's not portable across different CPU architectures. Do so with the following command immediately after restoring your dokku configs:
+
+```shell
+rm -rf /home/dokku/.basher
+```
+
 ## Recovering app code
 
 In case of an emergency when your git repo and backups are completely lost, you can recover the last pushed copy from your remote Dokku server (assuming you still have the ssh key).

docs/advanced-usage/builds.md

@@ -0,0 +1,197 @@
+# Build Tracking
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+Every deploy that flows through Dokku - whether triggered by `git push`, `ps:rebuild`, `ps:restart`, `config:set`, or `git:from-archive` / `git:from-image` / `git:sync` / `git:load-image` - is recorded as a structured build record on disk. The `builds` plugin lets operators inspect what is currently deploying, look up the result of an old deploy, and stream the captured build log without depending on `journalctl`.
+
+```
+builds:cancel <app>                               # Cancel a running build for an app
+builds:info <app> <build-id> [--format json]      # Show details for a single build
+builds:list [<app>] [--format json] [--kind ...] [--status ...]
+                                                  # List builds (running across all apps, or running + history for one)
+builds:output <app> [<build-id>|current]          # Show build output (tail for live, cat for finished)
+builds:prune <app> [--all-apps]                   # Reap abandoned records and apply retention
+builds:report [<app>] [<flag>]                    # Display a build report
+builds:set [--global|<app>] <key> [<value>]       # Set or clear a builds property
+```
+
+## Build records
+
+Every build is identified by a sortable base36 ULID-style id (`DOKKU_BUILD_ID`) generated at deploy start. For each build, Dokku writes:
+
+- `$DOKKU_LIB_ROOT/data/builds/<app>/<build-id>.json` - the structured record
+- `$DOKKU_LIB_ROOT/data/builds/<app>/<build-id>.log` - the captured stdout/stderr of the deploy
+
+Output is also tagged into syslog as `dokku-<build-id>` so `journalctl -t dokku-<build-id>` continues to work. The on-disk log file is the durable source of truth and is read for `builds:output` even when journald has rotated old entries away.
+
+### Record schema
+
+```json
+{
+  "id": "01j8c4xv7bk5w3",
+  "app": "myapp",
+  "kind": "build",
+  "pid": 12345,
+  "started_at": "2026-04-30T13:50:00Z",
+  "finished_at": "2026-04-30T13:51:14Z",
+  "status": "succeeded",
+  "source": "git-hook",
+  "exit_code": 0
+}
+```
+
+- **kind** - `build` for paths that produce a new image (`git push`, `git:*`, `ps:rebuild`); `deploy` for paths that re-deploy an existing image (`ps:restart`, `ps:start`, `dokku deploy`, `config:set`).
+- **status** - on-disk values are `running | succeeded | failed | canceled`. `abandoned` is a fifth display-only value computed at read time for `running` records whose PID is no longer alive; it is never persisted to the record.
+- **source** - the user-typed command that originated the deploy (e.g. `git-hook`, `ps:restart`, `config-redeploy`, `git:sync`).
+
+## Listing builds
+
+Without an app argument, `builds:list` shows currently-running builds across every app on the host:
+
+```shell
+dokku builds:list
+```
+
+```
+=====> Currently running builds
+App        Build ID        Kind   PID    Source     Started
+myapp      01j8c4xv7bk5w3  build  12345  git-hook   2026-04-30T13:50:00Z
+```
+
+With an app, `builds:list` returns running builds plus the most recent finalized records up to the configured retention:
+
+```shell
+dokku builds:list myapp
+```
+
+Filter by kind or status:
+
+```shell
+dokku builds:list myapp --kind build
+dokku builds:list myapp --status running
+dokku builds:list --format json
+```
+
+## Inspecting a single build
+
+```shell
+dokku builds:info myapp 01j8c4xv7bk5w3
+```
+
+```
+=====> Build 01j8c4xv7bk5w3
+       Build ID:   01j8c4xv7bk5w3
+       App:        myapp
+       Kind:       build
+       Status:     succeeded
+       PID:        12345
+       Source:     git-hook
+       Started:    2026-04-30T13:50:00Z
+       Finished:   2026-04-30T13:51:14Z
+       Duration:   1m14s
+       Exit Code:  0
+       Log:        /var/lib/dokku/data/builds/myapp/01j8c4xv7bk5w3.log
+```
+
+JSON output includes the same fields plus a computed `log_path`:
+
+```shell
+dokku builds:info myapp 01j8c4xv7bk5w3 --format json | jq .
+```
+
+## Streaming build output
+
+```shell
+# tail -f the live build, or cat the log for a finished one
+dokku builds:output myapp 01j8c4xv7bk5w3
+
+# resolve "current" from the in-flight deploy
+dokku builds:output myapp current
+```
+
+If the on-disk log file is missing (for example, a build from before this plugin was installed), `builds:output` falls back to `journalctl -t dokku-<build-id>`.
+
+## Cancelling a build
+
+`builds:cancel` reads the active `.deploy.lock` for an app, looks up the matching build record, and sends `SIGQUIT` to the deploy's process group. The record is finalized as `canceled` (or `failed` if the process had already exited without finalizing - in that case Dokku marks the record so it doesn't sit in `running` forever).
+
+```shell
+dokku builds:cancel myapp
+```
+
+If the record is already finalized when cancel runs, no signal is sent and the record is left untouched.
+
+## Retention
+
+Build records are pruned by count, not by age. The default retention is **20** records per app. Live in-flight deploys are never pruned regardless of count.
+
+Set a per-app retention:
+
+```shell
+dokku builds:set myapp retention 50
+```
+
+Set the global default:
+
+```shell
+dokku builds:set --global retention 10
+```
+
+Clear an override (falls back to the global value, then the default):
+
+```shell
+dokku builds:set myapp retention
+```
+
+## Manual pruning
+
+`builds:prune` invokes the same logic that runs at the end of every deploy - it reaps abandoned records (status=running with a dead PID, finalized as `failed`) and trims the directory to the configured retention. Useful after lowering retention via `builds:set` or to clean up after a host reboot:
+
+```shell
+dokku builds:prune myapp
+dokku builds:prune --all-apps
+```
+
+## Reports
+
+```shell
+dokku builds:report
+dokku builds:report myapp
+dokku builds:report myapp --build-status
+```
+
+Available flags:
+
+- `--build-id`, `--build-kind`, `--build-status`, `--build-pid`, `--build-source`, `--build-started-at`, `--build-finished-at`, `--build-exit-code`: details of the most recent build for the app
+- `--builds-retention`: per-app retention override (empty if none)
+- `--builds-global-retention`: global retention override (empty if none)
+- `--builds-computed-retention`: the resolved retention applied to this app
+
+`--build-status` returns the **display** status, so an abandoned in-flight build shows `abandoned` rather than `running`. The raw on-disk status is only visible by reading the JSON record directly.
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `builds:report`. The JSON keys emitted by `builds:report --format json` are the same names with the leading `--builds-` stripped (e.g. `retention`, `global-retention`, `computed-retention`). Legacy keys with the `builds-` prefix (e.g. `builds-retention`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release. Status keys (`build-id`, `build-status`, etc.) have no plugin prefix and are unaffected.
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `retention` | app + global | `20` | `--builds-retention`, `--builds-global-retention`, `--builds-computed-retention` | Number of recent build records kept per app; older finalized records are pruned at the end of each deploy |
+
+### Read-only flags
+
+The following flags surface in `builds:report` but are not managed by `builds:set` - they are derived metadata recorded during the build:
+
+| Flag | Description |
+|---|---|
+| `--build-id` | Unique identifier of the most recent build for the app |
+| `--build-kind` | Whether the record was a `build` or a `deploy` |
+| `--build-status` | Display status (`running`, `succeeded`, `failed`, `canceled`, `abandoned`); computed at read time |
+| `--build-source` | Trigger that started the build (e.g. `git-hook`, `ps:rebuild`, `ps:restart`) |
+| `--build-pid` | PID of the build process |
+| `--build-started-at` | UNIX timestamp the build started |
+| `--build-finished-at` | UNIX timestamp the build finished |
+| `--build-exit-code` | Exit code of the build process |

docs/advanced-usage/deployment-tasks.md

@@ -1,5 +1,6 @@
 # Deployment Tasks
 
+> [!IMPORTANT]
 > New as of 0.5.0
 
 ## Usage
@@ -55,15 +56,19 @@ Please keep the above in mind when utilizing deployment tasks.
 
 ### Changing the `app.json` location
 
-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.
+The `app.json` is expected to be found in a specific directory, depending on the deploy approach:
 
-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.
+- The `WORKDIR` of the Docker image for deploys resulting from `git:from-image` and `git:load-image` commands.
+- The root of the source code tree for all other deploys (git push, `git:from-archive`, `git:sync`).
 
+Sometimes it may be desirable to set a different path for a given app, e.g. when deploying from a monorepo. This can be done via the `appjson-path` property:
 
 ```shell
 dokku app-json:set node-js-app appjson-path .dokku/app.json
 ```
 
+The value is the path to the desired file *relative* to the base search directory, and will never be treated as absolute paths in any context. If that file does not exist within the repository, Dokku will continue the build process as if the repository has no `app.json`.
+
 The default value may be set by passing an empty value for the option:
 
 ```shell
@@ -84,6 +89,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:
@@ -95,18 +101,20 @@ dokku app-json:report
 ```
 =====> node-js-app app-json information
        App-json computed appjson path: app2.json
-       App-json global appjson path:   app.json
+       App-json global appjson path:
        App-json appjson path:          app2.json
 =====> python-sample app-json information
        App-json computed appjson path: app.json
-       App-json global appjson path:   app.json
+       App-json global appjson path:
        App-json appjson path:
 =====> ruby-sample app-json information
        App-json computed appjson path: app.json
-       App-json global appjson path:   app.json
+       App-json global appjson path:
        App-json appjson path:
 ```
 
+The `appjson-path` and `global-appjson-path` keys hold the raw per-app and global value respectively, and are empty when nothing has been set. The `computed-appjson-path` key holds the effective value used at deploy time, falling back to the global value (where one has been set) and then to the built-in default of `app.json`.
+
 You can run the command for a specific app also.
 
 ```shell
@@ -116,7 +124,7 @@ dokku app-json:report node-js-app
 ```
 =====> node-js-app app-json information
        App-json computed appjson path: app2.json
-       App-json global appjson path:   app.json
+       App-json global appjson path:
        App-json appjson path:          app2.json
 ```
 
@@ -140,7 +148,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.
 
-> 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.
 
@@ -158,6 +167,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`.
@@ -170,4 +180,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,57 +1,128 @@
 # 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
-
 ```
-docker-options:add <app> <phase(s)> OPTION    # Add Docker option to app for phase (comma-separated phase list)
-docker-options:clear <app> [<phase(s)>...]    # Clear a docker options from application
-docker-options:remove <app> <phase(s)> OPTION # Remove Docker option from app for phase (comma-separated phase list)
-docker-options:report [<app>] [<flag>]        # Displays a docker options report for one or more apps
+docker-options:add [--process PROC...] <app> <phase(s)> OPTION    # Add Docker option to app for phase
+docker-options:clear [--process PROC...] <app> [<phase(s)>...]    # Clear docker options from app
+docker-options:list <app> [--process PROC] --phase PHASE          # List docker options for one process+phase pair
+docker-options:remove [--process PROC...] <app> <phase(s)> OPTION # Remove Docker option from app for phase
+docker-options:report [<app>] [<flag>] [--format json|stdout]     # Displays a docker options report for one or more apps
 ```
 
-> When specifying multiple phases, they **must** be comma-separated _without_ spaces in between each phase, like so:
->
-> ```shell
-> dokku docker-options:add node-js-app deploy,run "-v /var/log/node-js-app:/app/logs"
-> ```
+The `docker-options` plugin allows users to specify custom [container options](https://docs.docker.com/engine/reference/run/) for containers created by Dokku at various phases.
 
-## About Dokku phases
+## Usage
 
-Dokku deploys your application in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
+### Background
 
-- `build`: the container that executes the appropriate buildpack
-- `deploy`: the container that executes your running/deployed application
-- `run`: the container that executes any arbitrary command via `dokku run`
+#### Phases
 
-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.
+Dokku deploys your app in multiple "phases" and the `docker-options` plugin allows you to pass arguments to their underlying docker container:
 
-More information on supported Docker options can be found here: https://docs.docker.com/engine/reference/commandline/run/.
+- `build`: The `build` phase is used to provide container options that are available during the build process for use by the various builders.
+    - A given builder may strip out or ignore options that are unsupported by the builder in question - as an example, the `dockerfile` builder does not support mounted volumes.
+- `deploy`: The `deploy` phase is used to provide container options that are set on _deployed_ process types. This covers every process type specified in an app `Procfile` as well as any default processes your app may deploy.
+    - The `deploy` phase is usually the correct phase to add options for running containers.
+- `run`: The `run` phase is used to provide container options to one-off containers created by `dokku run`, `dokku run:detached`, and any cron tasks specified in your `app.json`.
+
+> [!IMPORTANT]
+> The `run` phase does _not_ correspond 1-to-1 to `docker run` or `docker container run` commands. Specifying a container option at the `run` phase will only be invoked on containers created by the `run` plugin and cron tasks. Please be sure to specify options at the correct phase for your use-case.
+
+Adding or removing docker-options will not apply to any running containers, and only applies to containers created _after_ the options have been modified. As such, changing an app's docker options must be followed by a `dokku ps:rebuild` or a deploy in order to take effect.
+
+#### Supported Docker Options
+
+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.
 
-## Examples
+#### Scheduler support
 
-### Add Docker options
+Docker options are written in Docker's own vocabulary and are passed verbatim to `docker run` by the `docker-local` scheduler. Other schedulers translate only the subset that has an equivalent in their own runtime, and ignore the rest.
 
-Add some options for the deployed/running app and when executing [`dokku run`](/docs/processes/one-off-tasks.md):
+The `k3s` scheduler translates `--cap-add`, `--cap-drop`, `--privileged`, and `--sysctl` into their Kubernetes equivalents. See the [k3s scheduler documentation](/docs/deployment/schedulers/k3s.md) for details, including the restriction that only namespaced sysctls can be set on a pod.
 
 ```shell
-# Mount a host volume in a Docker container: "-v /host/path:/container/path"
-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"
+dokku docker-options:add node-js-app deploy "--sysctl net.ipv4.ip_unprivileged_port_start=1024"
 ```
 
-> 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.
+#### Mounting volumes and host directories
 
-### Remove a Docker option
+Docker supports volume and host directory mounting via the `-v` or `--volume` flags. In order to simplify usage, Dokku provides a `storage` plugin as an abstraction to interact with persistent storage. In most cases, the Dokku project recommends using the persistent storage plugin over directly manipulating docker options at different phases. See the [persistent storage documentation](/docs/advanced-usage/persistent-storage.md) for more information on how to attach persistent storage to your app.
+
+### Commands
+
+#### Add Docker options
+
+To add a docker option to an app, use the `docker-options:add` command. This takes an app name, a comma-separated list of phases, and the docker-option to add.
 
 ```shell
-dokku docker-options:remove node-js-app run "-v /var/log/node-js-app:/app/logs"
+dokku docker-options:add node-js-app deploy "--ulimit nofile=12"
 ```
 
-### Clear all Docker options for an app
+Multiple phases can be specified by using a comma when specifying phases:
+
+```shell
+dokku docker-options:add node-js-app deploy,run "--ulimit nofile=12"
+```
+
+Multiple docker options can also be specified in a single call. Each `--flag [value]` group is detected on flag boundaries, shell-tokenized for quoting safety, and stored as its own entry so it round-trips through `docker-options:report` and `docker-options:list`:
+
+```shell
+dokku docker-options:add node-js-app deploy "--ulimit nofile=12" "--shm-size 256m"
+```
+
+Option values are stored and passed to the container verbatim. Quoting only controls how a value is split into words - no shell expansion is performed, so `$(...)`, backticks, `$VAR`, and globs are treated literally rather than being interpreted by the shell. This is what lets values such as a Traefik router rule be applied as-is:
+
+```shell
+dokku docker-options:add node-js-app deploy '--label "traefik.http.routers.web.rule=Host(`node-js-app.example.com`) && PathPrefix(`/api`)"'
+```
+
+> [!WARNING]
+> Options added before 0.38.25 were expanded by the shell when a container was created. Any such option that relied on shell expansion - `$(...)`, backticks, or `$VAR` - is treated as a literal string after upgrading and must be re-added with the value already resolved:
+>
+> ```shell
+> dokku docker-options:remove node-js-app deploy "--group-add \$(getent group docker | cut -d: -f3)"
+> dokku docker-options:add node-js-app deploy "--group-add $(getent group docker | cut -d: -f3)"
+> ```
+
+A misplaced `--process PROC` (i.e. one specified after the app name instead of before it) is honored as a subcommand flag rather than stored as a docker option, so the two invocations below behave identically:
+
+```shell
+dokku docker-options:add --process web node-js-app deploy "--ulimit nofile=12" "--shm-size 256m"
+dokku docker-options:add node-js-app deploy "--ulimit nofile=12" "--shm-size 256m" --process web
+```
+
+#### Remove a Docker option
+
+To remove docker options from an app, use the `docker-options:remove` command. This takes an app name, a comma-separated list of phases, and the docker-option to remove.
+
+```shell
+dokku docker-options:remove node-js-app run "--ulimit nofile=12"
+```
+
+Multiple phases can be specified by using a comma when specifying phases:
+
+```shell
+dokku docker-options:remove node-js-app deploy,run "--ulimit nofile=12"
+```
+
+Multiple docker options can also be removed in a single call, mirroring the splitting that `docker-options:add` performs:
+
+```shell
+dokku docker-options:remove node-js-app deploy "--ulimit nofile=12" "--shm-size 256m"
+```
+
+A stored option is matched by shell word rather than by exact string, so the value only has to be equivalent to the stored one, not byte-identical. Quoting an option one way removes an option that was stored quoted another way:
+
+```shell
+dokku docker-options:add node-js-app deploy "--label 'com.example.owner=platform team'"
+dokku docker-options:remove node-js-app deploy '--label "com.example.owner=platform team"'
+```
+
+#### Clear all Docker options for an app
 
 Docker options can be removed for a specific app using the `docker-options:clear` command.
 
@@ -82,8 +153,9 @@ dokku docker-options:clear node-js-app build,run
 -----> Clearing docker-options for node-js-app on phase run
 ```
 
-### Displaying docker-options reports for an app
+#### 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:
@@ -95,8 +167,8 @@ dokku docker-options:report
 ```
 =====> node-js-app docker options information
        Docker options build:
-       Docker options deploy: -v /var/log/node-js-app:/app/logs
-       Docker options run:  -v /var/log/node-js-app:/app/logs
+       Docker options deploy: --ulimit nofile=12 --shm-size 256m
+       Docker options run:  --ulimit nofile=12 --shm-size 256m
 =====> python-sample docker options information
        Docker options build:
        Docker options deploy:
@@ -125,3 +197,101 @@ You can pass flags which will output only the value of the specific information
 ```shell
 dokku docker-options:report node-js-app --docker-options-build
 ```
+
+When process-specific options are configured (see below), the report exposes one additional dynamic flag per configured `process.deploy` pair, named `--docker-options-deploy.<process>`:
+
+```shell
+dokku docker-options:report node-js-app --docker-options-deploy.web
+```
+
+A machine-readable JSON view is available via `--format json`:
+
+```shell
+dokku docker-options:report node-js-app --format json
+```
+
+The JSON report includes the existing string keys (`build`, `deploy`, `run`, and `deploy.<process>` when configured) plus parallel `-list` keys for the same shorthand keys. Each `-list` value is a JSON array with one element per option as originally stored via `docker-options:add`, which allows export tooling to round-trip options that contain spaces without splitting the legacy space-joined strings. Empty phases emit an empty array (`[]`). The deprecated `docker-options-*` prefixed keys are unchanged and do not gain `-list` companions.
+
+```json
+{
+  "build": "",
+  "build-list": [],
+  "deploy": "-v /logs:/logs --memory=512m",
+  "deploy-list": ["-v /logs:/logs", "--memory=512m"],
+  "run": "",
+  "run-list": [],
+  "deploy.web": "-p 8080:5000",
+  "deploy.web-list": ["-p 8080:5000"],
+  "docker-options-build": "",
+  "docker-options-deploy": "-v /logs:/logs --memory=512m",
+  "docker-options-run": "",
+  "docker-options-deploy.web": "-p 8080:5000"
+}
+```
+
+### Process-Specific Options
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+Docker options can be scoped to specific process types declared in the app's `Procfile` by passing one or more `--process` flags. This is useful when a deploy-phase option (for example a port mapping) makes sense for one process type but would conflict with another - the canonical case being a `web` process that needs `-p 6789:5000` published while the `worker` process must not bind that port.
+
+Process scoping is supported only for the `deploy` phase. The `build` phase runs once per app and the `run` phase covers ad-hoc commands and cron tasks where no Procfile process type is in play; both reject `--process`.
+
+There is no `--global` flag. Omitting `--process` keeps the historical behavior of applying the option to every container in the app. Avoiding a `--global` flag here is intentional: elsewhere in Dokku `--global` means "across all apps" (e.g. `dokku config:set --global`), which would be misleading in this plugin where the scope is always one app.
+
+#### Setting process-specific options
+
+```shell
+# Add a port mapping only to the web process
+dokku docker-options:add --process web node-js-app deploy "-p 6789:5000"
+
+# Add a GPU mount only to the worker process
+dokku docker-options:add --process worker node-js-app deploy "--gpus all"
+```
+
+Multiple `--process` flags can be combined to apply the same option to several process types in one call:
+
+```shell
+dokku docker-options:add --process web --process api node-js-app deploy "-v /shared:/shared"
+```
+
+If `--process` names a process type that is not currently declared in the app's `Procfile`, the command succeeds but emits a warning. This allows configuring options ahead of a deploy that adds the new process type.
+
+The `_default_` value is reserved internally and cannot be passed to `--process`.
+
+#### Removing and clearing process-specific options
+
+```shell
+# Remove a single option from one process
+dokku docker-options:remove --process web node-js-app deploy "-p 6789:5000"
+
+# Clear every option for a process+phase
+dokku docker-options:clear --process worker node-js-app deploy
+```
+
+Without `--process`, `:remove` and `:clear` operate on the default scope only - per-process lists are left untouched.
+
+#### Listing options for a process and phase
+
+The `docker-options:list` command prints the options stored for a single process+phase pair, one option per line. Omitting `--process` lists the default scope.
+
+```shell
+dokku docker-options:list node-js-app --process web --phase deploy
+dokku docker-options:list node-js-app --phase deploy
+```
+
+## Properties
+
+### Internal properties
+
+The following properties are recorded internally by the docker-options plugin and are not exposed via `docker-options:report`:
+
+| Property | Scope | Description | Source |
+|---|---|---|---|
+| `migrated-from-files` | global | Global migration sentinel that records that the legacy `DOCKER_OPTIONS_<PHASE>` flat-file store has been drained into plugin properties | `plugins/docker-options/functions.go` writes `"true"` once the install-time migration runs |
+| `migrated-build` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_BUILD` file was drained into the `_default_.build` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
+| `migrated-deploy` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_DEPLOY` file was drained into the `_default_.deploy` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
+| `migrated-run` | per-app | Per-app marker recording that the app's legacy `DOCKER_OPTIONS_RUN` file was drained into the `_default_.run` property list. Only set when the legacy file contained non-empty content | `plugins/docker-options/functions.go` writes `"true"` after the per-phase drain |
+| `migrated-traefik-backticks` | global | Global sentinel recording that stored Traefik labels whose backticks carried a stray backslash have been repaired | `plugins/docker-options/functions.go` writes `"true"` once the install-time repair runs |
+| `migrated-canonical-options` | global | Global sentinel recording that stored options have been rewritten into the canonical form, quoting values whose shell metacharacters were left bare by an older legacy-file drain and splitting entries that carried several flags | `plugins/docker-options/functions.go` writes `"true"` once the install-time rewrite runs |

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,23 +1,41 @@
 # Persistent Storage
 
-> New as of 0.5.0
+> [!IMPORTANT]
+> New as of 0.5.0. Named storage entries new as of 0.38.0.
 
-The preferred method to mount external containers to a Dokku managed container, is to use the Dokku storage plugin.
+The preferred method to attach persistent storage to a Dokku-managed container is the Dokku storage plugin.
 
 ```
-storage:ensure-directory [--chown option] <directory>  # Creates a persistent storage directory in the recommended storage path
-storage:list <app> [--format text|json]                # List bind mounts for app's container(s) (host:container)
-storage:mount <app> <host-dir:container-dir>           # Create a new bind mount
-storage:report [<app>] [<flag>]                        # Displays a checks report for one or more apps
-storage:unmount <app> <host-dir:container-dir>         # Remove an existing bind mount
+storage:annotations:report [<name>] [<flag>]           # Display annotations for one or more storage entries
+storage:annotations:set <name> <key> [<value>]         # Set or clear a single annotation on a storage entry
+storage:create <name> [<path>] [flags]                 # Register a named storage entry
+storage:destroy <name> [--force] [--destroy-host-dir]  # Remove a named storage entry (must be unmounted from every app first)
+storage:ensure-directory [--chown option] <directory>  # [DEPRECATED] use storage:create instead
+storage:exec <name> [-- <cmd>...]                      # Run a command (or shell) in a temporary container that mounts the entry
+storage:info <name> [--format text|json]               # Show details for one storage entry
+storage:labels:report [<name>] [<flag>]                # Display labels for one or more storage entries
+storage:labels:set <name> <key> [<value>]              # Set or clear a single label on a storage entry
+storage:list <app> [--format text|json]                # List bind mounts for an app's container(s) (legacy host:container view)
+storage:list-entries [--scheduler s] [--format text|json]  # List registered storage entries
+storage:mount <app> <name> --container-dir <path> [flags]  # Mount a named entry into an app
+storage:mount <app> <host-dir:container-dir>           # [LEGACY] colon-form mount, docker-local only
+storage:report [<app>] [<flag>]                        # Display a storage report for one or more apps
+storage:report --global                                # Display a cluster-wide entry inventory
+storage:set <name> <property> [<value>]                # Update a storage entry in place
+storage:unmount <app> <name> [--container-dir <path>]  # Remove an attachment
+storage:wait <name>                                    # Block until a k3s entry's PVC is bound
 ```
 
-> The storage plugin is compatible with storage mounts created with the docker-options. The storage plugin will only list mounts from the deploy/run phase.
+A storage entry is the source of truth for the underlying volume - a host directory on docker-local, or a PersistentVolumeClaim on k3s. Multiple apps can mount the same entry, and an attachment carries the per-app details (container path, phases, subpath, readonly, process type). Names are globally unique across the install and must be DNS-1123 labels (lowercase letters, digits, dashes) of 45 characters or less so they can be used verbatim as Helm release and PVC names.
+
+The legacy `storage:mount <app> <host>:<container>` form continues to work on docker-local. On a k3s app it is rejected; create a named entry with `storage:create --scheduler k3s` and mount it instead. Existing colon-form mounts are migrated automatically the first time the new code runs - they show up as `legacy-<hash>` entries in `storage:list-entries`.
 
 The storage plugin supports the following mount points:
 
-- explicit paths that exist on the host
-- docker volumes
+- explicit paths that exist on the host (docker-local)
+- docker volumes (docker-local)
+- PersistentVolumeClaims provisioned via a StorageClass (k3s)
+- hostPath-backed PVs (k3s)
 
 ## Usage
 
@@ -36,7 +54,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
 ```
@@ -44,15 +61,30 @@ dokku storage:list node-js-app --format json
 ```
 [
   {
+    "entry_name": "node-js-app",
     "host_path": "/var/lib/dokku/data/storage/node-js-app",
+    "container_path": "/app/storage"
+  }
+]
+```
+
+Each entry mirrors the underlying attachment. `readonly` (boolean) and `volume_options` (string) reflect `Attachment.Readonly` and `Attachment.VolumeOptions` directly and are only present when set, so external tooling can drift-detect attachments against the raw attachment fields. For example, a mount created with `--volume-options noexec,nosuid --volume-readonly` renders as:
+
+```
+[
+  {
+    "entry_name": "node-js-data",
+    "host_path": "/var/lib/dokku/data/storage/node-js-data",
     "container_path": "/app/storage",
-    "volume_options": ""
+    "readonly": true,
+    "volume_options": "noexec,nosuid"
   }
 ]
 ```
 
 ### 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 +102,137 @@ 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.
-- `--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 `heroku/builder` builder.
+- `--chown paketo`: Use `2000:2000` as the folder permissions.
+    - This is used for apps deployed with Cloud Native Buildpacks using the `cloudfoundry/cnb` or `paketo` builders.
+- `--chown root`: Use `0:0` as the folder permissions.
+    - This is used for containers that run their processes as root, as is typical for most Dockerfile or Docker image deploys.
 - `--chown false`: Skips the `chown` call.
+- `--chown <uid>`: Use `<uid>:<uid>` as the folder permissions, where `<uid>` is a custom numeric user/group id.
+    - This is used for containers that run their processes as a uid/gid that doesn't correspond to any of the above named options.
 
 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.
+The `--chown` flag - whether on `storage:create` or `storage:ensure-directory` - only manages the default `/var/lib/dokku/data/storage/<name>` location. If a custom `<path>` is passed to `storage:create`, the chown call is refused and the operator must chown the path themselves.
+
+> [!WARNING]
+> Failing to set the correct directory ownership may result in issues in persisting files written to the mounted storage directory.
+
+### Setting directory permissions
+
+> [!IMPORTANT]
+> New as of 0.38.27
+
+Where `--chown` states who owns the host directory, `--mode` states its permission bits. It takes a 3 or 4 digit octal mode, and is a `--mode` flag on `storage:create` and a `mode` property on `storage:set`:
+
+```shell
+dokku storage:create node-js-data --mode 0777
+```
+
+```shell
+dokku storage:set node-js-data mode 0770
+```
+
+Omitting the value clears the mode, leaving the directory's permissions alone on subsequent runs:
+
+```shell
+dokku storage:set node-js-data mode
+```
+
+Without a mode, a newly created directory keeps the `0755` default and a pre-existing directory keeps whatever permissions it already had. The value is stored on the entry and re-applied every time `storage:create` or `storage:set` runs against it, so a declarative caller converges the directory by re-running the same command rather than reaching for `chmod` over SSH. The mode is shown by `storage:info`:
+
+```shell
+dokku storage:info node-js-data
+```
+
+```
+-----> Storage entry node-js-data
+       Scheduler:        docker-local
+       Host path:        /var/lib/dokku/data/storage/node-js-data
+       Mode:             0777
+```
+
+The mode is applied to the directory itself and does not recurse into its contents. Like `--chown`, it is docker-local only and only manages the default `/var/lib/dokku/data/storage/<name>` location - it is refused for k3s entries and for entries created with a custom `<path>`. That refusal also covers migrated `legacy-*` entries, whose host paths come from the original colon-form mount rather than the default location.
+
+### Updating a storage entry
+
+> [!IMPORTANT]
+> The property form is new as of 0.38.27. Prior versions used flags, which still work but emit a deprecation warning.
+
+An existing entry is edited with `storage:set`, which takes a property and a value. Omitting the value unsets the property, restoring whatever the entry defaults to:
+
+```shell
+dokku storage:set node-js-data chown herokuish
+dokku storage:set node-js-data chown
+```
+
+The following properties can be set:
+
+| Property | Description | Unsetting it means |
+|---|---|---|
+| `chown` | Ownership preset or numeric uid for the host directory | no chown is performed |
+| `mode` | Octal permissions for the host directory | permissions are left alone |
+| `namespace` | Namespace holding the PVC (k3s) | the `default` namespace |
+| `reclaim-policy` | Whether the underlying volume survives `storage:destroy` | `Retain` |
+| `size` | PVC size (k3s) | rejected, since k3s entries require a size |
+| `access-mode` | PVC access mode (k3s) | rejected, see below |
+| `storage-class-name` | PVC storage class (k3s) | rejected, see below |
+
+`access-mode` and `storage-class-name` cannot be changed on an entry that already exists, because Kubernetes cannot apply either to a bound PVC. Both a different value and an empty one are refused, since clearing is equally a change:
+
+```shell
+dokku storage:set node-js-data access-mode ReadWriteMany
+```
+
+```
+ !     storage:set cannot change access-mode in place; recreate the entry
+```
+
+Setting `chown` or `mode` on a docker-local entry applies the change to the host directory immediately. Every other property is a metadata write, and k3s entries re-apply their helm release so the cluster picks the change up.
+
+The older flag form - `dokku storage:set node-js-data --mode 0770` - continues to work and warns. It gained unset semantics too, so `--mode ""` clears the mode the same way omitting the positional value does.
+
+### Annotations and labels
+
+> [!IMPORTANT]
+> New as of 0.38.27
+
+Annotations and labels are attached to a storage entry one key at a time, matching the [scheduler-k3s equivalents](/docs/deployment/schedulers/k3s.md#setting-annotations). On k3s they propagate to both the PersistentVolumeClaim and the PersistentVolume, so backup tools like Velero and Longhorn can find the volume.
+
+```shell
+dokku storage:annotations:set node-js-data backup.velero.io/backup-volumes node-js-data
+dokku storage:labels:set node-js-data app.kubernetes.io/part-of billing
+```
+
+Keys may contain `/`, as the Kubernetes-style keys above do, and are stored verbatim. To clear a single key, omit the value. Other keys are left untouched, so a declarative caller does not need to re-send the whole set on every call:
+
+```shell
+dokku storage:annotations:set node-js-data backup.velero.io/backup-volumes
+```
+
+Configured annotations and labels can be inspected with the matching report commands. Without an entry name they cover every registered entry:
+
+```shell
+dokku storage:annotations:report
+dokku storage:annotations:report node-js-data
+dokku storage:labels:report node-js-data
+```
+
+```
+=====> node-js-data annotations information
+       Annotation backup.velero.io/backup-volumes: node-js-data
+```
+
+JSON output emits the keys flat, and a single value can be read directly with a flag of the form `--storage-annotations.<key>` (or `--storage-labels.<key>`), which requires an entry name:
+
+```shell
+dokku storage:annotations:report node-js-data --format json
+dokku storage:annotations:report node-js-data --storage-annotations.backup.velero.io/backup-volumes
+```
+
+`storage:create` still accepts repeatable `--annotation key=value` and `--label key=value` flags for setting the initial set at creation time. The same flags on `storage:set` are deprecated in favor of these commands, because they replace the entire map rather than a single key.
 
 ### Mounting storage into apps
 
@@ -99,6 +252,17 @@ In the first example, Dokku will then mount the shared contents of `/var/lib/dok
 
 > If the `/storage` path within the container had pre-existing content, the container files will be over-written. This may be an issue for users that create assets at build time but then mount a directory at the same place during runtime. Files are not merged.
 
+For named storage entries, additional Docker mount options can be passed via `--volume-options`. The value is a comma-separated mount-options string stored verbatim on the attachment and rendered into the `-v` flag at deploy time. This is useful for SELinux labels (`Z`, `z`) or hardening flags (`noexec,nosuid`):
+
+```shell
+dokku storage:create node-js-data
+dokku storage:mount node-js-app node-js-data --container-dir /app/storage --volume-options Z
+```
+
+When combined with `--volume-readonly`, the rendered options become `ro,<volume-options>` - for example, `--volume-options noexec,nosuid --volume-readonly` renders as `:ro,noexec,nosuid`.
+
+Re-running `storage:mount` against a named entry with the same `--container-dir` and `--process-type` updates the existing attachment's mount-time attributes (`--phase`, `--volume-subpath`, `--volume-readonly`, `--volume-chown`, `--volume-options`) in place rather than appending a duplicate. This is the idempotent equivalent of `storage:set` for entries, and lets declarative tooling change a mount-time attribute without an unmount-then-remount dance that would briefly drop the volume from `storage:report`. Mount-time fields are rewritten wholesale, not merged - omitting a flag on a re-mount clears any previously-set value. The legacy `host:container[:opts]` form still rejects duplicates with `Mount path already exists.`.
+
 Once persistent storage is mounted, the app requires a restart. See the [process scaling documentation](/docs/processes/process-management.md) for more information.
 
 ```shell
@@ -123,8 +287,68 @@ Once persistent storage is unmounted, the app requires a restart. See the [proce
 dokku ps:restart app-name
 ```
 
+### Destroying storage entries
+
+A named storage entry can be removed with the `storage:destroy` command. The entry must first be unmounted from every app that mounts it.
+
+```shell
+dokku storage:destroy rdmtest-entry
+```
+
+As the command is destructive - removing the registry entry and, depending on the scheduler and reclaim policy, the underlying volume - it will default to asking for confirmation before executing the removal.
+
+```
+ !     WARNING: Potentially Destructive Action
+ !     This command will destroy storage entry rdmtest-entry.
+ !     To proceed, type "rdmtest-entry"
+> rdmtest-entry
+-----> Storage entry rdmtest-entry destroyed
+```
+
+The confirmation may be avoided by providing the `--force` flag, which is useful for non-interactive or automated callers:
+
+```shell
+dokku storage:destroy rdmtest-entry --force
+```
+
+The global `--force` flag is also supported:
+
+```shell
+dokku --force storage:destroy rdmtest-entry
+```
+
+#### Removing the host directory
+
+> [!IMPORTANT]
+> New as of 0.38.27
+
+By default a docker-local entry's host directory survives `storage:destroy` - the entry is deregistered but the data stays on disk. The `--destroy-host-dir` flag removes the directory and everything in it:
+
+```shell
+dokku storage:destroy node-js-data --destroy-host-dir
+```
+
+```
+ !     Storage entry node-js-data is backed by /var/lib/dokku/data/storage/node-js-data, which will be removed along with its contents.
+ !     WARNING: Potentially Destructive Action
+ !     This command will destroy storage entry node-js-data.
+ !     To proceed, type "node-js-data"
+```
+
+The removal is recursive, so it succeeds whether or not the directory is empty. It is only permitted for entries at the default `/var/lib/dokku/data/storage/<name>` location; an entry created with a custom `<path>` is refused, and the operator removes the path themselves.
+
+The same removal can be declared ahead of time with `--reclaim-policy`, which behaves for a docker-local host directory the way it behaves for a k3s PersistentVolume. An entry created with `Delete` has its host directory removed on `storage:destroy` without any extra flag, while `Retain` - the default when unset - keeps it:
+
+```shell
+dokku storage:create node-js-data --reclaim-policy Delete
+dokku storage:destroy node-js-data --force
+```
+
+`--destroy-host-dir` is docker-local only. On a k3s entry the underlying volume is already governed by the reclaim policy recorded on the entry, so passing the flag is an error.
+
 ### 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:
@@ -167,6 +391,60 @@ You can pass flags which will output only the value of the specific information
 dokku storage:report node-js-app --storage-deploy-mounts
 ```
 
+In addition to the aggregated `Storage build/deploy/run mounts:` lines, the report emits one flat dotted key per attachment field, indexed from `1`. The key shape is `--storage-attachment.<index>.<field>` for each of `entry-name`, `host-path`, `container-path`, `phases`, `process-type`, `subpath`, `readonly`, `volume-options`, and `volume-chown`. Fields render as empty strings when unset, and attachments are ordered by lex-sort of the index (so `10` sorts before `2`):
+
+```shell
+dokku storage:create node-js-data
+dokku storage:mount node-js-app node-js-data --container-dir /app/storage --volume-options Z --volume-chown herokuish --volume-subpath uploads
+dokku storage:report node-js-app
+```
+
+```
+=====> node-js-app storage information
+       Storage attachment 1 container path:  /app/storage
+       Storage attachment 1 entry name:      node-js-data
+       Storage attachment 1 host path:       /var/lib/dokku/data/storage/node-js-data
+       Storage attachment 1 phases:          deploy,run
+       Storage attachment 1 process type:    _default_
+       Storage attachment 1 readonly:        false
+       Storage attachment 1 subpath:         uploads
+       Storage attachment 1 volume chown:    herokuish
+       Storage attachment 1 volume options:  Z
+       Storage build mounts:
+       Storage deploy mounts: -v /var/lib/dokku/data/storage/node-js-data:/app/storage:Z
+       Storage run mounts:  -v /var/lib/dokku/data/storage/node-js-data:/app/storage:Z
+```
+
+The same keys are exposed in JSON output, both in the stripped (`attachment.1.volume-options`) and legacy (`storage-attachment.1.volume-options`) forms:
+
+```shell
+dokku storage:report node-js-app --format json | jq '. | with_entries(select(.key | startswith("attachment.")))'
+```
+
+```json
+{
+  "attachment.1.container-path": "/app/storage",
+  "attachment.1.entry-name": "node-js-data",
+  "attachment.1.host-path": "/var/lib/dokku/data/storage/node-js-data",
+  "attachment.1.phases": "deploy,run",
+  "attachment.1.process-type": "_default_",
+  "attachment.1.readonly": "false",
+  "attachment.1.subpath": "uploads",
+  "attachment.1.volume-chown": "herokuish",
+  "attachment.1.volume-options": "Z"
+}
+```
+
+A single attachment field can be fetched directly via the info-flag form:
+
+```shell
+dokku storage:report node-js-app --storage-attachment.1.volume-options
+```
+
+```
+Z
+```
+
 ## Use Cases
 
 ### Sharing storage across deploys
@@ -195,14 +473,27 @@ 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.
+
+## Properties
+
+### Internal properties
+
+The following property is recorded internally by the storage plugin and is not exposed via `storage:report`:
+
+| Property | Scope | Description | Source |
+|---|---|---|---|
+| `legacy-mounts-migrated` | per-app | Per-app marker recording that the app's legacy `-v` docker-options entries were drained into named storage entries plus attachments. Only set when at least one `-v` line was actually migrated; apps that have never had legacy mounts never receive this marker | `plugins/storage/migrate.go` writes `"true"` after a successful drain |

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] [--skip-install-trigger] # 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:list [--format stdout|json]       # 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,72 @@ dokku plugin:list
 
 ```
 plugn: dev
-  00_dokku-standard    0.30.10 enabled    dokku core standard plugin
-  20_events            0.30.10 enabled    dokku core events logging plugin
-  app-json             0.30.10 enabled    dokku core app-json plugin
-  apps                 0.30.10 enabled    dokku core apps plugin
-  build-env            0.30.10 enabled    dokku core build-env plugin
-  buildpacks           0.30.10 enabled    dokku core buildpacks plugin
-  certs                0.30.10 enabled    dokku core certificate management plugin
-  checks               0.30.10 enabled    dokku core checks plugin
-  common               0.30.10 enabled    dokku core common plugin
-  config               0.30.10 enabled    dokku core config plugin
-  docker-options       0.30.10 enabled    dokku core docker-options plugin
-  domains              0.30.10 enabled    dokku core domains plugin
-  enter                0.30.10 enabled    dokku core enter plugin
-  git                  0.30.10 enabled    dokku core git plugin
-  logs                 0.30.10 enabled    dokku core logs plugin
-  network              0.30.10 enabled    dokku core network plugin
-  nginx-vhosts         0.30.10 enabled    dokku core nginx-vhosts plugin
-  plugin               0.30.10 enabled    dokku core plugin plugin
-  proxy                0.30.10 enabled    dokku core proxy plugin
-  ps                   0.30.10 enabled    dokku core ps plugin
-  repo                 0.30.10 enabled    dokku core repo plugin
-  resource             0.30.10 enabled    dokku core resource plugin
-  scheduler-docker-local 0.30.10 enabled    dokku core scheduler-docker-local plugin
-  shell                0.30.10 enabled    dokku core shell plugin
-  ssh-keys             0.30.10 enabled    dokku core ssh-keys plugin
-  storage              0.30.10 enabled    dokku core storage plugin
-  tags                 0.30.10 enabled    dokku core tags plugin
-  tar                  0.30.10 enabled    dokku core tar plugin
-  trace                0.30.10 enabled    dokku core trace plugin
+  00_dokku-standard    0.38.27 enabled    dokku core standard plugin
+  20_events            0.38.27 enabled    dokku core events logging plugin
+  app-json             0.38.27 enabled    dokku core app-json plugin
+  apps                 0.38.27 enabled    dokku core apps plugin
+  build-env            0.38.27 enabled    dokku core build-env plugin
+  buildpacks           0.38.27 enabled    dokku core buildpacks plugin
+  certs                0.38.27 enabled    dokku core certificate management plugin
+  checks               0.38.27 enabled    dokku core checks plugin
+  common               0.38.27 enabled    dokku core common plugin
+  config               0.38.27 enabled    dokku core config plugin
+  docker-options       0.38.27 enabled    dokku core docker-options plugin
+  domains              0.38.27 enabled    dokku core domains plugin
+  enter                0.38.27 enabled    dokku core enter plugin
+  git                  0.38.27 enabled    dokku core git plugin
+  logs                 0.38.27 enabled    dokku core logs plugin
+  network              0.38.27 enabled    dokku core network plugin
+  nginx-vhosts         0.38.27 enabled    dokku core nginx-vhosts plugin
+  plugin               0.38.27 enabled    dokku core plugin plugin
+  proxy                0.38.27 enabled    dokku core proxy plugin
+  ps                   0.38.27 enabled    dokku core ps plugin
+  repo                 0.38.27 enabled    dokku core repo plugin
+  resource             0.38.27 enabled    dokku core resource plugin
+  scheduler-docker-local 0.38.27 enabled    dokku core scheduler-docker-local plugin
+  shell                0.38.27 enabled    dokku core shell plugin
+  ssh-keys             0.38.27 enabled    dokku core ssh-keys plugin
+  storage              0.38.27 enabled    dokku core storage plugin
+  tags                 0.38.27 enabled    dokku core tags plugin
+  tar                  0.38.27 enabled    dokku core tar plugin
+  trace                0.38.27 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.
+The list can also be emitted as JSON via the `--format json` flag. In addition to the name, version, enabled state, and description shown in the default output, the JSON output includes whether a plugin is a core plugin and - for git-based third-party plugins - the install source (the git remote URL, the currently checked-out commit, and the followed branch). This is useful for tooling that reconstructs a server's set of installed plugins:
+
+```shell
+dokku plugin:list --format json
+```
+
+```json
+[
+  {
+    "name": "apps",
+    "version": "0.38.27",
+    "enabled": true,
+    "core": true,
+    "description": "dokku core apps plugin",
+    "source_url": "",
+    "committish": "",
+    "branch": ""
+  },
+  {
+    "name": "postgres",
+    "version": "1.42.0",
+    "enabled": true,
+    "core": false,
+    "description": "dokku postgres service plugin",
+    "source_url": "https://github.com/dokku/dokku-postgres.git",
+    "committish": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
+    "branch": "master"
+  }
+]
+```
+
+The `source_url`, `committish`, and `branch` fields are only populated for plugins installed from a git repository. They are empty for core plugins as well as for plugins installed from a tarball or a local `file://` path. When a plugin is pinned to a specific commit or tag (a detached checkout), the `branch` field is empty while `committish` still reports the exact commit.
+
+> [!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 +113,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.
 
@@ -125,6 +161,12 @@ The `--core` flag may also be indicated as the sole argument, though it is only
 dokku plugin:install --core
 ```
 
+If installing plugins in a Dockerfile, you will want to skip the `install` trigger. This will be run on container boot.
+
+```shell
+dokku plugin:install https://github.com/dokku/smoke-test-plugin.git --name smoke-test-plugin --skip-install-trigger
+```
+
 Finally, all flags may be omitted to trigger the `install` procedures for both core and third-party plugins:
 
 ```shell
@@ -165,6 +207,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,11 +1,13 @@
 # Registry Management
 
+> [!IMPORTANT]
 > New as of 0.25.0
 
 ```
-registry:login [--password-stdin] <server> <username> [<password>] # Login to a docker registry
-registry:report [<app>] [<flag>]                                   # Displays a registry report for one or more apps
-registry:set <app> <key> (<value>)                                 # Set or clear a registry property for an app
+registry:login [--global|--password-stdin] [<app>] <server> <username> [<password>] # Login to a docker registry
+registry:logout [--global] [<app>] <server>                                         # Logout from a docker registry
+registry:report [<app>] [<flag>]                                                    # Displays a registry report for one or more apps
+registry:set <app>|--global <key> (<value>)                                         # Set or clear a registry property for an app
 ```
 
 The registry plugin enables interacting with remote registries, which is useful when either deploying images via `git:from-image` or when interacting with custom schedulers to deploy built image artifacts.
@@ -14,34 +16,75 @@ The registry plugin enables interacting with remote registries, which is useful
 
 ### Logging into a registry
 
-The `registry:login` command can be used to log into a docker registry. The following are examples for logging into various common registries:
+The `registry:login` command can be used to log into a docker registry. Credentials can be stored globally (for all apps) or on a per-app basis.
+
+#### Global login
+
+To log in globally (credentials shared by all apps), use the `--global` flag:
 
 ```shell
 # hub.docker.com
-dokku registry:login docker.io $USERNAME $PASSWORD
+dokku registry:login --global docker.io $USERNAME $PASSWORD
 
 # digitalocean
 # the username and password are both defined as the same api token
-dokku registry:login registry.digitalocean.com $DIGITALOCEAN_API_TOKEN $DIGITALOCEAN_API_TOKEN
+dokku registry:login --global registry.digitalocean.com $DIGITALOCEAN_API_TOKEN $DIGITALOCEAN_API_TOKEN
 
 # github container registry
 # see the following link for information on retrieving a personal access token
 #   https://docs.github.com/en/packages/guides/pushing-and-pulling-docker-images#authenticating-to-github-container-registry
-dokku registry:login ghcr.io $USERNAME $REGISTRY_PAT_TOKEN
+dokku registry:login --global ghcr.io $USERNAME $REGISTRY_PAT_TOKEN
 
 # quay
 # a robot user may be used to login
-dokku registry:login quay.io $USERNAME $PASSWORD
+dokku registry:login --global quay.io $USERNAME $PASSWORD
 ```
 
-For security reasons, the password may also be specified as stdin by specifying the `--password-stdin` flag. This is supported regardless of the registry being logged into.
+> [!NOTE]
+> For backwards compatibility, if the `--global` flag is omitted and only three arguments are provided (server, username, password), the command will behave as a global login but will show a deprecation warning.
+
+#### Per-app login
+
+To log in for a specific app, specify the app name as the first argument:
 
 ```shell
-echo "$PASSWORD" | dokku registry:login --password-stdin docker.io $USERNAME
+# log into docker.io for a specific app
+dokku registry:login node-js-app docker.io $USERNAME $PASSWORD
+
+# log into ghcr.io for a specific app
+dokku registry:login node-js-app ghcr.io $USERNAME $REGISTRY_PAT_TOKEN
+```
+
+Per-app credentials are stored in `/var/lib/dokku/config/registry/$APP/config.json` and are automatically used for docker operations (build, push, pull) for that specific app.
+
+#### Password via stdin
+
+For security reasons, the password may also be specified as stdin by specifying the `--password-stdin` flag. This is supported for both global and per-app logins:
+
+```shell
+# global login via stdin
+echo "$PASSWORD" | dokku registry:login --global --password-stdin docker.io $USERNAME
+
+# per-app login via stdin
+echo "$PASSWORD" | dokku registry:login node-js-app --password-stdin docker.io $USERNAME
 ```
 
 For certain Docker registries - such as Amazon ECR or Google's GCR registries - users may instead wish to use a docker credential helper to automatically authenticate against a server; please see the documentation regarding the credential helper in question for further setup instructions.
 
+### Logging out from a registry
+
+The `registry:logout` command can be used to log out from a docker registry:
+
+```shell
+# global logout
+dokku registry:logout --global docker.io
+
+# per-app logout
+dokku registry:logout node-js-app docker.io
+```
+
+When an app is destroyed, any per-app registry credentials are automatically removed.
+
 ### Setting a remote server
 
 To specify a remote server registry for pushes, set the `server` property via the `registry:set` command. The default value for this property is empty string. Setting the value to `docker.io` or `hub.docker.com` will result in the computed value being empty string (as that is the default, implicit registry), while any non-zero length value will have a `/` appended to it if there is not one already.
@@ -98,7 +141,31 @@ Setting the property value to an empty string will reset the value to the system
 
 ```shell
 # per-app
-dokku registry:set node-js-app push-on-release
+dokku registry:set node-js-app image-repo
+```
+
+### Templating the image repository name
+
+Instead of setting the image repository name on a per-app basis, it can be set via a template with the `image-repo-template` property. The property can be set globally or for a specific app, with the per-app value overriding the global value when both are present:
+
+```shell
+# globally
+dokku registry:set --global image-repo-template "my-awesome-prefix/{{ .AppName }}"
+
+# per-app
+dokku registry:set node-js-app image-repo-template "my-awesome-prefix/{{ .AppName }}-prod"
+```
+
+Dokku uses a Golang template and has access to the `AppName` variable as shown above. The per-app `image-repo` property always takes precedence over the rendered template when both are set.
+
+Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.
+
+```shell
+# per-app
+dokku registry:set node-js-app image-repo-template
+
+# globally
+dokku registry:set --global image-repo-template
 ```
 
 ### Pushing images on build
@@ -124,3 +191,53 @@ dokku registry:set node-js-app push-on-release
 # globally
 dokku registry:set --global push-on-release
 ```
+
+#### Recovering from local image GC
+
+When `push-on-release` is enabled, Dokku treats the remote registry as the canonical store for app images. If a local image disappears - for example because a `docker image prune` cron ran, the host rebooted, or an operator removed it manually - subsequent commands that need the image (`ps:restart`, `ps:scale`, `dokku run`, `domains:add`, `certs:add`, etc.) will pull the missing tag back from the registry automatically. Per-app registry credentials configured via `registry:login` are honored during the pull. This recovery covers the deployed numeric tag pushed by the registry plugin - a missing `latest` tag will be ignored.
+
+### Push extra tags 
+
+To push the image on release with extra tags, set the `push-extra-tags` to a comma-separated list of tags via the `registry:set` command. The default value for this property is empty. Setting the property will result in the image being tagged with extra tags every release.
+
+```shell
+# multiple-tags
+dokku registry:set node-js-app push-extra-tags foo,bar
+```
+The `push-extra-tags` can be set to a single tag too.
+
+```shell
+# single tag
+dokku registry:set node-js-app push-extra-tags foo
+```
+
+This property can be set for a single app or globally via the `--global` flag. When set globally, the app-specific value will always overide the global value. The default global value for this property is `false`.
+
+```shell
+dokku registry:set --global push-extra-tags foo,bar
+```
+
+Setting the property value to an empty string will reset the value to the system default. Resetting the value can be done per app or globally.
+
+```shell
+# per-app
+dokku registry:set node-js-app push-extra-tags
+
+# globally
+dokku registry:set --global push-extra-tags
+```
+
+## Properties
+
+### Settable properties
+
+> [!NOTE]
+> The `Report flags` column lists the CLI argument names accepted by `registry:report`. The JSON keys emitted by `registry:report --format json` are the same names with the leading `--registry-` stripped (e.g. `image-repo`, `global-server`, `computed-push-on-release`). Legacy keys with the `registry-` prefix (e.g. `registry-image-repo`) are also emitted during the 0.38.x deprecation window and will be removed in a future major release.
+
+| Property | Scope | Default | Report flags | Description |
+|---|---|---|---|---|
+| `image-repo` | app only | `dokku/<app>` | `--registry-image-repo`, `--registry-computed-image-repo` | Repository name used when pushing the app's image (overrides the global template) |
+| `image-repo-template` | app + global | none | `--registry-image-repo-template`, `--registry-global-image-repo-template`, `--registry-computed-image-repo-template` | Go template used to compute the per-app image repository when `image-repo` is unset |
+| `push-extra-tags` | app + global | none | `--registry-push-extra-tags`, `--registry-global-push-extra-tags`, `--registry-computed-push-extra-tags` | Comma-separated list of additional tags pushed alongside the deploy tag |
+| `push-on-release` | app + global | `false` | `--registry-push-on-release`, `--registry-global-push-on-release`, `--registry-computed-push-on-release` | When `true`, pushes the image to the registry on every successful build |
+| `server` | app + global | none | `--registry-server`, `--registry-global-server`, `--registry-computed-server` | Registry server host (e.g. `ghcr.io`) used when pushing images |

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:
 
@@ -30,7 +32,7 @@ Valid resource options include:
 
 See the [Supported Resource Management Properties](/docs/deployment/schedulers/docker-local.md#supported-resource-management-properties) section of the docker local scheduler documentation for more information on how each resource limit maps to Docker.
 
-Resource limits and reservations are applied only during the `run` and `deploy` phases of an application, and will not impact the `build` phase of an application.
+Resource reservations are applied only during the `run` and `deploy` phases of an application. Resource limits also apply during the `build` phase when explicitly configured against the `build` process type - see [Build-time Resource Limits](#build-time-resource-limits) below.
 
 ### Resource Limits
 
@@ -118,6 +120,40 @@ dokku resource:limit --process-type web node-js-app
        nvidia-gpu:
 ```
 
+#### Build-time Resource Limits
+
+> [!IMPORTANT]
+> New as of 0.38.0
+
+Resource limits may be applied to the build container by using the special `build` process type. This allows constraining memory and CPU usage during the `build` phase, which is otherwise unconstrained.
+
+```shell
+dokku resource:limit --memory 4g --process-type build node-js-app
+```
+
+```
+=====> Setting resource limits for node-js-app (build)
+       memory: 4g
+```
+
+Build-time limits are applied via the `docker-args-process-build` plugin trigger. They do not inherit from default (`_default_`) limits - only limits explicitly set against the `build` process type are applied at build time. This is intentional: build phases often require more memory than the runtime process, and silently inheriting a small runtime limit would cause confusing OOM failures.
+
+> [!WARNING]
+> Do not use `build` as a runtime process type in your `Procfile`. The `build` name is reserved by the resource plugin to scope limits to the build container, and using it as a Procfile entry will cause those limits to be applied to that runtime container as well.
+
+Supported limits per builder:
+
+| Builder    | `--cpu` | `--memory` | `--memory-swap` | `--nvidia-gpu` |
+|------------|---------|------------|-----------------|----------------|
+| herokuish  | yes     | yes        | yes             | yes            |
+| dockerfile | no      | yes        | yes             | no             |
+| pack       | no      | no         | no              | no             |
+| nixpacks   | no      | no         | no              | no             |
+| railpack   | no      | no         | no              | no             |
+| lambda     | no      | no         | no              | no             |
+
+Resource keys outside the supported set for a builder are silently ignored. Reservations (`resource:reserve`) are never applied at build time - only limits.
+
 #### Clearing Resource Limits
 
 In cases where the values are incorrect - or there is no desire to limit resources - resource limits may be cleared using the `resource:limit-clear` command.

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.23.0-migration-guide.md

@@ -4,5 +4,5 @@
 
 - The `plugin:list` command no longer outputs the version for the `plugn` binary.
 - Users building docker images that run Dokku will need to use a new sudoer wrapper for the `docker-image-labeler` 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 `dokku` user's cron is now in use by Dokku itself. Customizations will be overwritten. Users are encouraged to use a cron entry in `/etc/cron.d/dokku` to avoid this issue.
+- The `dokku` user's cron is now in use by Dokku itself. Customizations will be overwritten. Users are encouraged to use a cron file at `/etc/cron.d/dokku` to avoid this issue.
 - As of 0.23.0, Dokku will now inject the `max-size` log driver option for applications. This is restricted to app-configured log driver values empty, `local` or `json-file` in 0.23.1 to increase setup compatibility. Users who configure alternative log drivers at the system level will need to either set the global `max-size` property to `unlimited` or switch to the built-in `vector` logging support.

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.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.32.0-migration-guide.md

@@ -0,0 +1,30 @@
+# 0.32.0 Migration Guide
+
+## Deprecations
+
+- The following `pre-build-*` plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the `pre-build` plugin trigger.
+    - pre-build-buildpack
+    - pre-build-dockerfile
+    - pre-build-lambda
+    - pre-build-pack
+- The following `pre-release-*` plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the `pre-release-builder` plugin trigger.
+    - pre-release-buildpack
+    - pre-release-dockerfile
+    - pre-release-lambda
+    - pre-release-pack
+- The following `post-build-*` plugin triggers have been deprecated and will be removed in the next release. Users should instead trigger the `post-build` plugin trigger.
+    - post-build-buildpack
+    - post-build-dockerfile
+    - post-build-lambda
+    - post-build-pack
+- The `CHECKS` file was deprecated in the previous release in favor of defining healthchecks in the `app.json` file. It's support and auto-migration to healthchecks in the `app.json` file will be removed in the next release. See the [zero-downtime deploy documentation](/docs/deployment/zero-downtime-deploys.md) for more information on how the new zero downtime check format works.
+
+## Removals
+
+- ARM support has been removed. 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.
+- The following proxy-port related code has been removed. It is replaced by the `ports` plugin and it's related plugin triggers.
+    - `proxy:ports-*` commands
+    - `proxy-configure-ports` plugin trigger
+    - `common#get_available_port()`
+    - `common#get_dockerfile_exposed_ports()`
+    - `common#get_exposed_ports_from_image()`

docs/appendices/0.33.0-migration-guide.md

@@ -0,0 +1,3 @@
+# 0.33.0 Migration Guide
+
+Dokku 0.33.0 did not introduce any refactors, removals, or deprecations, and focused solely on system improvements.

docs/appendices/0.34.0-migration-guide.md

@@ -0,0 +1,23 @@
+# 0.34.0 Migration Guide
+
+## Removals
+
+- The `disable-chown` property of the `scheduler-docker-local` plugin has been removed. Mounted paths will no longer have file permissions changed during the pre-deploy phase. Files baked into the container image for herokuish builds will always be owned by the correct user.
+- The `git:unlock` command has been removed. It was previously used to "unlock" a temporary directory that already existed. The directory the `git:unlock` command used to cleanup is now properly removed on exit of the `git:from-image` command.
+- The k3s plugin no longer supports port mappings other than `https:443` and `http:80`. If no matching port map is specified, Dokku will use expose the app on the first port mapping, with priority given to `https` mappings over `http`.
+- Golang functions to invoke plugin triggers named `PlugnTrigger*` have been removed in favor of `CallPlugnTrigger`.
+
+## Changes
+
+- The k3s scheduler now creates an Ingress object per domain instead of one per port mapping. This will cause a short amount of downtime during the next app deploy after upgrading to 0.34.0
+- App lock files have been removed from the `/home/dokku` directory and moved into the `data/apps` directory.
+- Logs are now rotated via `copytruncate` instead of `create` in logrotate.
+- The k3s scheduler now defaults to nginx as it's default proxy implementation. The traefik proxy implementation is still available, though users will need to set the global `ingress-class` k3s property to `traefik` via the following command:
+
+    ```shell
+    dokku scheduler-k3s:set --global ingress-class traefik
+    ```
+
+## Deprecations
+
+The `pre-deploy` plugin trigger is deprecated as of `0.34.4`. It is currently invoked during the `post-release-builder` plugin trigger, where image mutation is heavily discouraged. Users should instead move any trigger usage to the `pre-release-builder` plugin trigger. The `pre-deploy` plugin trigger will be removed in a future release.

docs/appendices/0.35.0-migration-guide.md

@@ -0,0 +1,17 @@
+# 0.35.0 Migration Guide
+
+## Changes
+
+- The provided `dokku/dokku:latest` Docker image now runs Ubuntu 24.04 Noble. Users that install custom packages within their docker-based installations should be sure to check package compatibility with Ubuntu 24.04.
+- The default image used for Cloud Native Buildpack builds is now `heroku/builder:24`, and is based on both the `heroku-24` stack as well as Ubuntu 24.04. Users that wish to stick with the old, `heroku-22`/Ubuntu 22.04 builder may specify `heroku/buildpacks:22` as their builder image. Please see the [cloud native buildpack deployment documentation](/docs/deployment/builders/cloud-native-buildpacks.md#customizing-the-buildpack-stack-builder) for more information on how to specify a custom buildpack stack builder.
+- The default image used for Herokuish Buildpack builds is now `gliderlabs/herokuish:latest-24`, and is based on both the `heroku-24` stack as well as Ubuntu 24.04. Users that wish to stick with the old, `heroku-22`/Ubuntu 22.04 builder may specify `gliderlabs/herokuish:latest-22` 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 `vector` image used by Dokku for enhanced logging support has been upgraded from 0.39.x to 0.41.x. To take advantage of the new image, execute the following commands:
+    ```
+    dokku logs:vector-stop
+    dokku logs:vector-start
+    ```
+- The `openresty` image used by Dokku for proxying via openresty has been upgraded from 0.8.0 to 0.9.0. To take advantage of the new image, execute the following commands:
+    ```
+    dokku openresty:stop
+    dokku openresty:start
+    ```

docs/appendices/0.36.0-migration-guide.md

@@ -0,0 +1,12 @@
+# 0.36.0 Migration Guide
+
+## Changes
+
+- Process stop timeouts are now configured via the `ps` property `stop-timeout-seconds`. Existing `DOKKU_DOCKER_STOP_TIMEOUT` environment variables will be automatically migrated to the new value.
+- Processes now default to a `30` second stop timeout.
+- The `domains:clear` command no longer runs domain setup after clearing the domains. Use `domains:reset` or run `domains:setup` manually to have the same effect.
+- The deprecated `DOKKU_DISABLE_ANSI_PREFIX_REMOVAL` setting has been removed. Dokku deploys no longer use shell escape codes to modify output, and thus deploy output may now contain `remote:` as a prefix in each lines output.
+
+## Deprecations
+
+Ubuntu 20.04 is now a deprecated installation target. The operating system will be considered EOL by Canonical in April 2025. Users are encouraged to upgrade to Ubuntu 24.04 or consider switching their instllation method to the [Docker-based installation method](/docs/getting-started/install/docker.md) to avoid any disruption in usage.

docs/appendices/0.37.0-migration-guide.md

@@ -0,0 +1,15 @@
+# 0.37.0 Migration Guide
+
+## Changes
+
+- The `app.json` file format is now parsed as JSONC and supports inline comments.
+- The `scheduler-k3s:cluster-add` command is now `scheduler-k3s:cluster:add`.
+- The `scheduler-k3s:cluster-list` command is now `scheduler-k3s:cluster:list`.
+- The `scheduler-k3s:cluster-remove` command is now `scheduler-k3s:cluster:remove`.
+
+## Removals
+
+- Support for the `DOKKU_DOCKERFILE_CACHE_BUILD` environment variable has been removed. Use the `docker-options` plugin to set build arguments for your app instead.
+- Support for the `DOKKU_DOCKER_BUILD_OPTS` environment variable has been removed. Use the `docker-options` plugin to set build arguments for your app instead.
+- Support for the `no-cache` nixpacks property has been removed. Use the `docker-options` plugin to set build arguments for your app instead.
+- Support for customizing the label-key for the caddy proxy has been removed. Always use `caddy.` as a prefix for your caddy directives.

docs/appendices/0.38.0-migration-guide.md

@@ -0,0 +1,72 @@
+# 0.38.0 Migration Guide
+
+## Changes
+
+- Dokku now generates a minimal nginx configuration for apps without running `web` processes (undeployed apps, apps with no `web` process type, or apps with stopped web processes). This configuration returns `502 Bad Gateway` responses, ensuring the app's domain resolves and monitoring tools can detect non-200 status codes. The configuration is automatically replaced with the full proxy configuration once the app is deployed with running `web` processes. See the [nginx documentation](/docs/networking/proxies/nginx.md#nginx-configuration-for-undeployed-apps) for more details.
+- Users with custom `nginx.conf.sigil` templates that reference `DOKKU_APP_WEB_LISTENERS` should be aware that this variable may now be empty when the template is rendered for apps without running web processes. Custom templates should handle this case gracefully, for example by using a conditional to serve an error page instead of proxying:
+
+    ```
+    location / {
+    {{ if $.DOKKU_APP_WEB_LISTENERS }}
+      proxy_pass  http://{{ $.APP }}-{{ $upstream_port }};
+    {{ else }}
+      return 502;
+    {{ end }}
+    }
+    ```
+
+- The path on disk to both the global `ENV` file and app `ENV` files have been moved. Users should reference environment variables via the provided plugin triggers rather than directly sourcing the ENV files. Existing ENV files are merged into the new location and removed once they have been drained. **Changed in 0.38.26:** removal previously happened on the subsequent Dokku install for app ENV files, and never happened at all for the global ENV file. **Changed in 0.38.27:** an ENV file found at the old path after its migration has been recorded is never merged into the new location, because the new location holds every change made since. Such a file is removed when its values agree with the current config, and otherwise moved aside to `ENV.migrated` with the keys it disagrees on named in a warning, so its values can still be applied by hand with `dokku config:set`. That copy is left for review and should be deleted afterwards: Dokku no longer reads it, and it holds everything it was not allowed to import - including keys that were unset on purpose, which for a revoked secret means a copy lingering on disk.
+- During a fresh apt install, the upstream nginx default vhost files (`/etc/nginx/sites-enabled/default`, `/etc/nginx/sites-available/default`, and `/etc/nginx/conf.d/default.conf`) are renamed to `${path}.dokku-disabled` (not deleted) to avoid a `duplicate default server for 0.0.0.0:80` error. Operators with local customizations can recover them by inspecting the `.dokku-disabled` siblings. Upgrade-in-place installs do not touch any existing nginx files.
+- Fresh apt installs now ship a catch-all default site at `/etc/nginx/conf.d/00-default-vhost.conf` that rejects requests with unknown Host headers using `ssl_reject_handshake on` (HTTPS) and `return 444` (HTTP). This replaces the manual workaround previously documented in the nginx docs. The behavior can be opted out at install time via the `dokku/install_default_site` debconf prompt. On nginx older than 1.19.4 (e.g., Debian Bullseye's nginx 1.18.0), the postinst installs an HTTP-only variant of the catch-all that omits the SSL listener and `ssl_reject_handshake`, since that directive is unsupported on those versions. See the [Default site documentation](/docs/networking/proxies/nginx.md#default-site).
+- The `docker-local` scheduler now sends `SIGTERM` to old containers immediately after a successful deploy, rather than waiting `wait-to-retire` seconds before signaling. This matches Heroku's graceful-shutdown contract and lets applications begin draining in-flight work as soon as proxy traffic switches. The `wait-to-retire` grace period and `stop-timeout-seconds` hard-stop continue to apply as before. See the [zero downtime deploys documentation](/docs/deployment/zero-downtime-deploys.md#wait-to-retire) for more details.
+- The `docker-local` scheduler no longer queues an image for retirement when another running container of the same app still uses it. This fixes the case where a `ps:rebuild` against an image-based deploy (`git:from-image`) produced an identical-SHA image and the `dokku-retire` cron timer would log `Image ... has running containers, skipping rm` on every run. Stuck entries from prior versions are pruned automatically on the next `ps:retire` run.
+- All `:report` subcommands now accept the `--global` flag, which scopes the report to globally-configured properties. The flag composes with `--format json`, so a JSON report of global properties can be obtained via, for example, `dokku scheduler:report --global --format json`. Previously, combining `--global` with `--format json` was rejected with an "info flag" error, and `--global` on its own was treated as an unknown flag.
+- Every `:report` key of the form `<plugin>-global-<property>` now returns the raw stored global value (empty when the property has never been set) instead of the resolved value with the built-in default substituted in. A new `<plugin>-computed-<property>` key has been added wherever a default existed and returns the effective value (per-app value, falling back to the global value, then to the built-in default). This affects `app-json`, `builder-dockerfile`, `builder-herokuish`, `builder-lambda`, `builder-nixpacks`, `builder-pack`, `builder-railpack`, `caddy`, `checks`, `git`, `haproxy`, `logs`, `network`, `nginx`, `openresty`, `proxy`, `registry`, `scheduler`, `scheduler-k3s` and `traefik`. External tooling that read `<plugin>-global-<property>` and depended on the default value should switch to `<plugin>-computed-<property>`. The bare `<plugin>-<property>` keys for caddy/haproxy/traefik/openresty global-only properties (`caddy-image`, `haproxy-log-level`, `traefik-api-enabled`, `openresty-image`, `openresty-letsencrypt-email`, `openresty-letsencrypt-server`, `openresty-allowed-letsencrypt-domains-func-base64`, etc.) have also been replaced by the `global-` and `computed-` pair.
+- The `ps` and `cron` plugins now follow the same `<plugin>-global-<property>` / `<plugin>-computed-<property>` convention. The `ps:report` keys `stop-timeout-seconds`, `global-stop-timeout-seconds`, and `computed-stop-timeout-seconds` have been renamed to `ps-stop-timeout-seconds`, `ps-global-stop-timeout-seconds`, and `ps-computed-stop-timeout-seconds`. The `cron:report` keys `cron-mailfrom` and `cron-mailto` have been renamed to `cron-global-mailfrom` and `cron-global-mailto`, and new `cron-computed-mailfrom` and `cron-computed-mailto` keys have been added. The corresponding user-facing `--<flag>` arguments to `ps:report` and `cron:report` were renamed alongside the JSON keys; no aliases are kept. Additionally, both `ps:report --global` and `cron:report --global` now emit the `<plugin>-computed-<property>` keys for every settable global property with a default (`ps-computed-procfile-path`, `ps-computed-stop-timeout-seconds`, `cron-computed-maintenance`, `cron-computed-mailfrom`, `cron-computed-mailto`), matching the shape used by the other plugins.
+- A second round of `:report` additions surfaces every remaining settable-but-unreported property under the same raw/global/computed convention so external tooling can verify drift via `:report --format json` without falling back to a generic bash task. The `ps` plugin gains `--ps-dockerfile-start-cmd` and `--ps-computed-dockerfile-start-cmd`, `--ps-start-cmd` and `--ps-computed-start-cmd`, and the `--ps-skip-deploy` / `--ps-global-skip-deploy` / `--ps-computed-skip-deploy` triple (default `false`). The `builder` plugin gains the `--builder-skip-cleanup` triple (default `false`). The `scheduler` plugin gains the `--scheduler-shell` triple. The `proxy` plugin gains the `--proxy-proxy-port` and `--proxy-proxy-ssl-port` triples and exposes the raw `disabled` property as `--proxy-disabled` / `--proxy-computed-disabled`, alongside the existing inverted `--proxy-enabled`. The `openresty` plugin gains `--openresty-global-log-level` and `--openresty-computed-log-level` (default `ERROR`). The `nginx` plugin gains the `--nginx-nginx-service-command` triple. The `scheduler-k3s` plugin gains `--scheduler-k3s-global-token`, but the value is masked as `*******` in default stdout output; the raw value is returned only when the report is requested via `--format json` or when this flag is queried explicitly by name. The traefik `dns-provider-<env_var>` keys are reported as `--traefik-global-dns-provider-<env_var>` and follow the same masking and explicit-query rules, as does the traefik `basic-auth-password` property, whose `--traefik-global-basic-auth-password` and `--traefik-computed-basic-auth-password` keys are masked in default stdout output.
+- All Go-implemented plugins (`app-json`, `apps`, `builder`, `buildpacks`, `builds`, `cron`, `docker-options`, `logs`, `network`, `ports`, `proxy`, `ps`, `registry`, `resource`, `scheduler`, `scheduler-k3s`, `storage`) now emit JSON keys from `:report --format json` without the `<plugin>-` head segment, matching the shape bash plugins have always emitted. For example, `dokku ps:report myapp --format json` now contains `stop-timeout-seconds`, `global-stop-timeout-seconds`, and `computed-stop-timeout-seconds` keys. The CLI flag names (`--ps-stop-timeout-seconds`, etc.) are unchanged, and `:set` semantics are unchanged. For backwards compatibility during the 0.38.x patch series, the old `<plugin>-<property>` JSON keys are emitted side-by-side with the new keys, so external scripts reading either shape continue to work. The legacy keys will be dropped in a future major release. External JSON consumers should migrate to the new key shape.
+- The `scheduler-k3s` plugin now manages env config and the dokku-generated image pull Secret as their own helm releases with stable names (`config-{app}` and `pull-secret-{app}`) rather than bundling them into the app helm chart with a per-deploy timestamp suffix (`env-{app}.{ts}` / `ims-{app}.{ts}`). This fixes two bugs: a helm rollback of the app chart no longer deletes Secrets that older ReplicaSets still reference, and the Deployment's `imagePullSecrets` list no longer accumulates references to nonexistent Secrets across deploys. The next deploy of an app switches the Deployment's `envFrom` and `imagePullSecrets` references to the stable names and prunes any leaked entries; existing live Deployments do not need to be patched manually. App rename now also uninstalls the old `tls-{app}`, `config-{app}`, and `pull-secret-{app}` releases under the previous app name; the new name's releases are recreated on the next deploy or certs sync.
+- **New in 0.38.25:** Values supplied through docker options, `dokku run`'s `-e`/`--env` flag, and `--ttl-seconds` are no longer evaluated by the shell when assembling a container's arguments; they are now tokenized and passed through verbatim. This closes a command-injection vector where a `$(...)` or backtick expression in one of these values executed on the host as the `dokku` user during build, deploy, or run. As a result, shell metacharacters such as `$(...)`, backticks, `$VAR`, and globs in these values are treated literally instead of being expanded, and `--ttl-seconds` must now be a plain integer. Existing Traefik docker-options labels (those whose label key begins with `traefik.`) whose backticks were stored with a stray backslash are repaired automatically the first time `dokku` runs after the upgrade, so they become valid on the next deploy.
+- **New in 0.38.26:** Docker options drained out of the pre-0.38.0 `DOCKER_OPTIONS_<PHASE>` files were copied verbatim rather than being re-serialized the way `docker-options:add` stores them, so `docker-options:remove` compared the canonical string it builds against a value that could never match it and exited successfully without removing anything. Removal now matches stored options by shell word instead of by exact string, so those entries can be removed with the value as originally written. Stored options are also rewritten into the canonical form the first time `dokku` runs after the upgrade: values whose shell metacharacters were left unquoted are quoted, and an entry that carried several flags on one line becomes one entry per flag, which additionally fixes `ps:report` reading a restart policy off such a line and the `k3s` scheduler translating only the first of several `--cap-add`/`--sysctl` flags. Options added through `docker-options:add` are already canonical and are left untouched.
+- **New in 0.38.26:** Deprecated `DOKKU_*` config variables belonging to plugins whose install step runs before the `config` plugin's were not migrated to their plugin property on the upgrade run. Install steps fire in alphabetical order, so `apps`, `builder`, and `checks` read an app's environment before the `config` plugin had relocated the `ENV` file, found nothing, and moved nothing - without reporting anything. `dokku config:show` kept listing the variable while the plugin behaved as though it were unset, which for `DOKKU_CHECKS_SKIPPED` meant a process type silently regained a health check it was meant to skip. The relocation is now performed before any deprecated variable is read, regardless of install order. Affected installs recover on their next `dokku plugin:install --core`, which the upgrade already runs; the variables listed below can also be re-applied by hand using their replacement command.
+- **New in 0.38.27:** The 0.38.26 upgrade merged the leftover pre-0.38.0 `ENV` file back over the current config. Releases 0.38.0 through 0.38.25 recorded the migration and left that file on disk on purpose, and 0.38.26 read it as a hand-edit, so the environment as it stood at the 0.38.x upgrade won over every `dokku config:set` and `dokku config:unset` made since - including reinstating variables and secrets that had been deliberately unset. Nothing appeared broken, because running containers keep the environment they were created with; the rewound values would have reached containers on the next deploy. The 0.38.26 run consumed the leftover file, so this cannot happen a second time, but it also cannot be undone automatically. To check an app that was upgraded to 0.38.26 and has a container still running from before that upgrade, compare each key in `dokku config:show <app>` against `docker exec <container> printenv <key>` - `GIT_REV` is expected to differ after a deploy, anything else that differs was rewound. Repair with `dokku config:set --no-restart <app> KEY=VALUE` for values that regressed and `dokku config:unset --no-restart <app> KEY` for variables that came back.
+- The storage plugin now treats persistent volumes as named, scheduler-aware first-class resources via `storage:create`, `storage:mount`, `storage:set`, and `storage:destroy`. The legacy `storage:mount <app> <host>:<container>` colon form continues to work on docker-local apps but is deprecated; on k3s apps it is rejected. Existing colon-form mounts are migrated automatically the first time the new storage plugin runs (during the install trigger) - they appear as `legacy-<hash>` entries in `storage:list-entries`. The migration is idempotent and tied to a per-app flag file at `$DOKKU_LIB_ROOT/config/storage/.migrated/<app>`; deleting that file forces a re-scan on the next install. The `storage:ensure-directory` command keeps working but now emits a deprecation warning - prefer `storage:create <name> [<path>]` (the path defaults to the same `$DOKKU_LIB_ROOT/data/storage/<name>` location). Storage entry names must now be DNS-1123 labels of 45 characters or less so they can be used verbatim as Helm release and Kubernetes resource names; underscores and uppercase characters that the older `ensure-directory` validator accepted are rejected for new names. The migration synthesizer always uses lowercase hex hashes so existing data is never locked out.
+
+### TLS handshake behavior change
+
+With the new catch-all installed on nginx 1.19.4+, an HTTPS request to a hostname that matches a configured dokku app but where the app has no TLS certificate configured will have its TLS handshake rejected by the catch-all (via `ssl_reject_handshake on`). Previously, nginx fell through to the lexicographically first port-443 server block and presented that block's certificate, producing a cert-mismatch error on the client. The new behavior is a correctness improvement, but operators who deliberately relied on the old fall-through certificate (for monitoring probes, for example) need to either configure a certificate for the target app or remove the catch-all on that host. Existing apps that already have certificates configured are unaffected: nginx selects the right server block via SNI before TLS completion, so the catch-all is never consulted for legitimate requests.
+
+This change does not apply to nginx older than 1.19.4 (e.g., Debian Bullseye's nginx 1.18.0), where the catch-all is installed as an HTTP-only variant. On those systems, HTTPS handshakes to unknown hosts continue to fall through to the first port-443 server block as before.
+
+### Environment variables migrated to plugin properties
+
+A number of `DOKKU_*` config environment variables have been replaced with properly-namespaced plugin properties. Existing values are migrated automatically the first time `dokku` runs after the upgrade, and the original config variable is unset. No manual action is required.
+
+Going forward, configure these settings using the property commands listed below. Setting the deprecated env vars via `dokku config:set` will no longer have any effect.
+
+| Deprecated Env Var | Replacement Command |
+|---|---|
+| `DOKKU_APP_PROXY_TYPE` | `dokku proxy:set <app> type <value>` |
+| `DOKKU_APP_RESTORE` | `dokku ps:set <app> restore <true\|false>` |
+| `DOKKU_APP_SHELL` | `dokku scheduler:set <app> shell <value>` |
+| `DOKKU_CHECKS_DISABLED` | `dokku checks:disable <app> [proctypes]` |
+| `DOKKU_CHECKS_ENABLED` | `dokku checks:enable <app> [proctypes]` |
+| `DOKKU_CHECKS_SKIPPED` | `dokku checks:skip <app> [proctypes]` |
+| `DOKKU_CHECKS_WAIT` | `dokku checks:set <app> wait <value>` |
+| `DOKKU_CHECKS_TIMEOUT` | `dokku checks:set <app> timeout <value>` |
+| `DOKKU_CHECKS_ATTEMPTS` | `dokku checks:set <app> attempts <value>` |
+| `DOKKU_DEFAULT_CHECKS_WAIT` | `dokku checks:set --global default-wait <value>` |
+| `DOKKU_DISABLE_APP_AUTOCREATION` | `dokku apps:set --global disable-autocreation <true\|false>` |
+| `DOKKU_DISABLE_PROXY` | `dokku proxy:disable <app>` / `dokku proxy:enable <app>` |
+| `DOKKU_DOCKERFILE_START_CMD` | `dokku ps:set <app> dockerfile-start-cmd <value>` |
+| `DOKKU_PROXY_PORT` | `dokku proxy:set <app> proxy-port <value>` |
+| `DOKKU_PROXY_SSL_PORT` | `dokku proxy:set <app> proxy-ssl-port <value>` |
+| `DOKKU_SKIP_ALL_CHECKS` | `dokku checks:disable <app>` |
+| `DOKKU_SKIP_CLEANUP` | `dokku builder:set <app> skip-cleanup <true\|false>` |
+| `DOKKU_SKIP_DEFAULT_CHECKS` | `dokku checks:skip <app>` |
+| `DOKKU_SKIP_DEPLOY` | `dokku ps:set <app> skip-deploy <true\|false>` |
+| `DOKKU_START_CMD` | `dokku ps:set <app> start-cmd <value>` |
+
+`DOKKU_PARALLEL_ARGUMENTS` is removed entirely; it has no replacement.
+
+`DOKKU_SKIP_CLEANUP` continues to be honored when set in `/etc/environment` or `~dokku/.dokkurc/*` so that bootstrap-time configuration keeps working, but the `builder skip-cleanup` property is the canonical interface and takes precedence when set.

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`